Immersive Music

Let the soundtrack follow your journey.

Immersive Music brings 120 tracks inspired by fantasy, medieval, and Celtic music to your adventures. From open grasslands and quiet forests to deep caves and otherworldly dimensions, each setting has its own musical atmosphere. All included music was created by the author using Suno AI and is free to use.

The mod senses your biome type, dimension, temperature, time of day, light level, sky visibility, underwater status, and altitude. It combines these observations with each track's conditions and weight to choose music that fits your surroundings. Biomes are identified through vanilla biome tags, so modded biomes with the appropriate tags can also be matched.

Enjoy a soundtrack throughout your session, from the main menu to world exploration, with smooth fades between tracks. Menu music is chosen randomly and plays to completion before the next selection. Once you enter a world, music is selected to suit the environment. You can also disable early switching to let each track finish before the mod chooses the next one.

Features

• Music that responds to your surroundings: Distinct moods for mornings, nights, the surface, caves, and underwater exploration.
• 120 fantasy and Celtic tracks: Peaceful, mysterious, and somber music for exploring, building, and wandering.
• Smooth transitions: Configurable fades, with a default duration of two seconds.
• Compatibility with other music: Replaces vanilla background music and fades out when another mod plays music through the music channel.
• A customizable music pool: Edit the music pool JSON to add your own tracks, define where they can play, and adjust their preferences and selection weights.

Custom Music and JSON Configuration

The music pool currently loads from JSON files inside the mod's JAR. The following steps modify those bundled resources. Back up the JAR before editing, restart the game after saving, and reapply your changes when updating the mod.

1. Add Your Audio Files

Convert your music to Ogg Vorbis (.ogg). Use lowercase English letters, numbers, and underscores in filenames.

Open the mod's JAR with an archive editor and place your audio files at the following paths. This example uses the track group moonlit_forest:

assets/immersive_music/
├── music_pool.json
├── sounds.json
└── sounds/music/
    ├── moonlit_forest_a.ogg
    └── moonlit_forest_b.ogg

Each rule currently defines two variants, A and B. You can provide two tracks or point both sound events to the same audio file.

2. Register the Sound Events

Add the following members inside the top-level object in assets/immersive_music/sounds.json. Keep the existing entries and separate members with commas:

"music.moonlit_forest_a": {
  "sounds": [
    {
      "name": "immersive_music:music/moonlit_forest_a",
      "stream": true
    }
  ]
},
"music.moonlit_forest_b": {
  "sounds": [
    {
      "name": "immersive_music:music/moonlit_forest_b",
      "stream": true
    }
  ]
}

name is the audio resource location, without the .ogg extension. stream: true enables streaming playback for longer music files. If you only have one audio file, use its resource location as the name for both events.

3. Add a Music Pool Rule

Append an object to the top-level array in assets/immersive_music/music_pool.json. This example adds a track group that favors forests at night:

{
  "number": 61,
  "id": "moonlit_forest",
  "realm": "overworld",
  "layer": "surface",
  "weight": 3,
  "tagsAny": [
    "minecraft:is_forest",
    "minecraft:is_taiga"
  ],
  "tagsNone": [],
  "preferredTags": [
    "minecraft:is_taiga"
  ],
  "preferences": {
    "temperature": {
      "gte": 0.0,
      "lt": 0.9
    },
    "height": {
      "gte": 48
    },
    "brightness": {
      "lt": 8
    },
    "skyVisible": true,
    "dayTimeAny": [
      [13000, 23000]
    ]
  }
}

This group is eligible on the surface in Overworld-type realms, in forest or taiga biomes. It favors cool, dark nighttime conditions with visible sky. Unmet preferences reduce its weight rather than preventing playback.

4. Top-Level Parameters

Only vanilla minecraft: biome tags are accepted. Enter them without a leading #, for example minecraft:is_forest, minecraft:is_ocean, or minecraft:is_mountain. These tags can also match modded biomes that carry them.

5. Environment Preferences

All preference fields are optional. When several preferences are unmet, their multipliers are applied together. Hard conditions determine eligibility, while preferences influence selection chances. For example, use heightLimit to restrict a track to certain altitudes, or preferences.height to make those altitudes more favorable.

In a range object, gte means "greater than or equal to" and lt means "less than." You can specify either bound or both:

"heightLimit": { "gte": 48, "lt": 128 }

This requires an altitude of 48 <= Y < 128.

dayTimeAny uses time-of-day ticks from 0 to 23999. Each interval includes its start and excludes its end. 0 is morning, 6000 is noon, 12000 is around sunset, and 18000 is midnight. Split an interval that crosses the day boundary into two parts:

"dayTimeAny": [[23000, 24000], [0, 1000]]

Environment rules and weights apply to music selection inside a world. The main menu selects randomly from the pool. World selection also includes randomness and repeat suppression, so a higher weight does not guarantee that a track will always play.

Free Use and Credits

All 120 included tracks were created by the author using Suno AI and are free for players to use. The mod's source code is released under the MIT License. Music assets are not covered by the code's MIT license.