Add music track registry and biome mood by yel0h · Pull Request #3679 · PixelGuys/Cubyz

yel0h · 2026-10-04T22:04:11Z

Progress toward tag-based music selection as outlined in #732. This PR is just the data model and changes no behavior.

Each zig.zon file in the music folder declares tags, a mood target, a tolerance and a chance for the song of the same id. Adds Mood, a point in anxiety/energy/sanity space. Biomes and tracks are positioned in this space. Biomes can now declare a baseMood. Cave biomes default to a higher baseline anxiety.

Example music track file:

.{
    .tags = .{ .peaceful, .day, .surface },
    .moodTarget = .{.anxiety = 0.2, .energy = 0.3, .sanity = 0.8},
    .moodTolerance = 0.6,
    .chance = 1.0,
}

Wunka · 2026-10-05T13:57:49Z

I think an artist opinion would be nice here @ikabod-kee @careeoki

ikabod-kee · 2026-10-05T16:20:20Z

Oh holy shit. Let me check this out

ikabod-kee · 2026-10-05T16:23:25Z

This looks very good to me! I'm not sure if Quantum actually wanted the mood system like that so he'll have to give you some feedback on this- but this is a very good start and I'm excited to see some implementation.

IntegratedQuantum

Instead of just adding these values, please also outline how you intend the system to work, also check out some criteria I added in #732 (comment)

IntegratedQuantum · 2026-10-05T16:54:54Z

 			addon.readAllZon(allocator, "items", true, &self.items, &self.itemMigrations);
 			addon.readAllZon(allocator, "tools", true, &self.proceduralItems, null);
 			addon.readAllZon(allocator, "structure_tables", false, &self.structureTables, null);
+			addon.readAllZon(allocator, "music_tracks", true, &self.musicTracks, null);


I think the metadata should be put in the same folder, like we did for models.

IntegratedQuantum · 2026-10-05T16:55:44Z

 pub const migrations = @import("migrations.zig");
 pub const models = @import("models.zig");
+pub const mood = @import("mood.zig");
+pub const musicTracks = @import("musicTracks.zig");


Please don't make a new root-level files for this. This clearly is only used for music, thus belongs in the audio file and folder.

IntegratedQuantum · 2026-10-05T16:56:27Z

@@ -0,0 +1,12 @@
+pub const Mood = struct {


This could also be declared locally in the MusicTrack struct

IntegratedQuantum · 2026-10-05T16:58:02Z

+}
+
+pub fn registerTracks(tracksZon: *Assets.ZonHashMap) void {
+	anyTag = Tag.find("any");


For any comptime-known tags, just declare them in the Tag enum

IntegratedQuantum · 2026-10-05T17:03:16Z

 	subBiomeTotalChance: f32 = 0,
 	preferredMusic: []const u8, // TODO: Support multiple possibilities that are chosen based on time and danger.
+	baseMood: main.mood.Mood,
+	musicTags: []const Tag.WeightedTag,


My idea was to have tags be hard restrictions. If we add weights to them I think the resulting vector space may get too big to be able to produce good matches on the mood and the tags (e.g. a few tags on a track that doesn't match the mood at all may outcompete any tracks that do match the mood and vice versa).

Also tags should not be specialized, to allow one system (e.g. music) to make use of the tags of another system (e.g. .oak).

yel0h · 2026-10-06T14:06:03Z

The way I wanted this to work was:
The player has the 3-value mood, which is affected, for example, by actions described here. The mood values always decay toward the current biome's baseMood.
A music track is a candidate to be played if there's at least one match between its tags and the biome's musicTags.
Each candidate then has a weight calculated based on:

the sum of the matching tags' weights,
how well the mood fits, considering its distance to the player's mood, and the moodTolerance value,
the track's weight specified in the zon.

When the current song finishes playing, the system does a weighted random pick of the next track, excluding the last few played unless that would leave no candidates. If the player travels to another biome whose tags don't match the current song, it immediately fades to a new one.
And if there are no candidates to choose from, it just picks among tracks tagged .any.
So basically I just put the ideas from #732 together.

yel0h · 2026-10-06T14:16:27Z

Now I guess if we want hard filtering tags, that would mean that for a track to be considered a candidate, all of its tags have to be among the current biome's tags. In that case, the .any tag is also not needed, it's enough to leave a music track untagged. The candidate weight calculation would then depend on the track's weight and mood fit only.

IntegratedQuantum

Please also add at least one example to a biome, and make a PR with an example music track to Cubyz-Assets (note that you'll also need to touch the release CI script to copy the file over)

Thanks for working on this by the way, this is quite important, and something I've been neglecting for quite a few release cycles.

IntegratedQuantum

one more thing

IntegratedQuantum · 2026-10-07T15:39:19Z

+		energy: f32,
+		sanity: f32,
+
+		pub fn loadFromZon(zon: ZonElement, isCave: ?bool) Mood {


Bools in functions signatures are hard to read.

Suggested change

pub fn loadFromZon(zon: ZonElement, isCave: ?bool) Mood {

pub fn loadFromZon(zon: ZonElement, options: struct{isCave: bool = false}) Mood {

Example music track file for PixelGuys/Cubyz#3679

yel0h · 2026-10-07T16:26:33Z

Replaced

IntegratedQuantum

I can't wait to see how this turns out.

Add music track registry and biome mood/music tags

1709d9d

IntegratedQuantum requested changes Oct 5, 2026

View reviewed changes

Move music metadata next to audio and make music tags hard restrictions

77faefe

IntegratedQuantum requested changes Oct 6, 2026

View reviewed changes

Cleanup

4ebc357

yel0h mentioned this pull request Oct 7, 2026

Ship music metadata and add example for leaves PixelGuys/Cubyz-Assets#40

Merged

yel0h changed the title ~~Add music track registry and biome mood/music tags~~ Add music track registry and biome mood Oct 7, 2026

IntegratedQuantum requested changes Oct 7, 2026

View reviewed changes

IntegratedQuantum mentioned this pull request Oct 7, 2026

Print an error when a music file does not have an associated metadata file #3683

Open

IntegratedQuantum pushed a commit to PixelGuys/Cubyz-Assets that referenced this pull request Oct 7, 2026

Ship music metadata and add example for leaves (#40)

bd8743a

Example music track file for PixelGuys/Cubyz#3679

Pass Mood.loadFromZon options as struct instead of optional bool

5523bc3

careeoki mentioned this pull request Oct 7, 2026

Add zon files for each song PixelGuys/Cubyz-Assets#30

Open

IntegratedQuantum approved these changes Oct 7, 2026

View reviewed changes

IntegratedQuantum merged commit f1e494a into PixelGuys:master Oct 7, 2026
3 checks passed

yel0h deleted the music-data-model branch October 7, 2026 19:25

	pub fn loadFromZon(zon: ZonElement, isCave: ?bool) Mood {
	pub fn loadFromZon(zon: ZonElement, options: struct{isCave: bool = false}) Mood {

Conversation

yel0h commented Oct 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Wunka commented Oct 5, 2026

Uh oh!

ikabod-kee commented Oct 5, 2026

Uh oh!

ikabod-kee commented Oct 5, 2026

Uh oh!

IntegratedQuantum left a comment

Choose a reason for hiding this comment

Uh oh!

IntegratedQuantum Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

IntegratedQuantum Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

IntegratedQuantum Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

IntegratedQuantum Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

IntegratedQuantum Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

yel0h commented Oct 6, 2026

Uh oh!

yel0h commented Oct 6, 2026

Uh oh!

IntegratedQuantum left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

IntegratedQuantum left a comment

Choose a reason for hiding this comment

Uh oh!

IntegratedQuantum Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

yel0h commented Oct 7, 2026

Uh oh!

IntegratedQuantum left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

yel0h commented Oct 4, 2026 •

edited

Loading