From Embassy Wiki
Jump to: navigation, search

ActualMusic is a mod that replaces vanilla Minecraft's bland music with any music you want, for almost any in-game setting and situation. There's very little config-tampering required to set the mod up - just throw some music in the folder it provides and it'll play it when the time is right!

Additionally, it creates little "title cards" that pop up when you enter a new area, telling you where you are (like how some RPGs used to).


Name the mp3 files you put in the folder a specific (set of) keywords that the mod recognizes and you're good to go. You don't need to add each song to the config file!

Change Log

Main Article: ActualMusic Changelog.


Main Article: ActualMusic API.

Setting Up


You can find Embassy (required) on Curseforge here.

You can find ActualMusic on Curseforge here.


Download Embassy for the version of Minecraft you're playing, and ensure that your Forge version is up to date. Download ActualMusic ( there are no different versions for different minecraft versions - one version fits all!) Place them in the mods folder, and you're good to go.

The mod SHOULD be installed on both the server and the client in the case of multiplayer, but it's not strictly required. The server sends packets telling the client things the client isn't normally allowed to know, including the target of mobs ( for Horde ), the location of structures, the location of the Stronghold, the location of your bed, and the name of the world (for your zones.cfg). Without it, these features (and possibly more) won't work.

Generating the Config

Run Minecraft once after installing the mod. This will create a folder called ActualMusic at the top of your config folder. Inside is a config file and a music folder.

Most settings can be managed inside the game from commands. All config options are fully explained in the config file, so check it out and see what you can tweak!


While ActualMusic strives to be as friendly to other mods as it can, it should go without saying that you're going to run into issues if you try to combine it with other mods that replace vanilla Minecraft music. You're free to submit a bug report on my issue tracker if you run into any problems, but compatibility with other music mods isn't guaranteed.

Reporting Bugs

You can report bugs and make suggestions right over here. It's recommended that you use this issue tracker rather than CurseForge or Discord; your report is far more likely to be seen and dealt with if you do. Keeping all the suggestions and reports in one place will make it much easier to respond to them.

Please do not report a bug you found unless you can replicate the problem, give steps to replicate the problem, and you are using the latest version of Embassy and ActualMusic.

Using the Mod

Adding Music

Note that songpacks need only to be on the client. The server will make zero use of any music whatsoever. Clients don't need to have the same songpacks, they can have their own unique setups.

Your base Minecraft folder should look something like this:


In the config folder, near the top, should be a folder called `ActualMusic. Inside should look like this after your first run of Minecraft:


Depending on your computer, Settings.cfg may just be called Settings. That's fine.

Opening your music folder, you'll find that it's empty. Time to fix that! Choose a song pack that's to your liking ( found farther down this page ) and extract it to this empty folder. That's all there is to it! If you want to create your own song pack, keep reading.

Alternate Day Folders

Eventually you may start to get tired of the same songs playing all the time, because it's not like you visit every biome and find yourself in every situation all the time. In this situation you can make subfolders called AltDay[#] (replacing # with a number, or a word in 3.0 and later), put another song pack inside, and ActualMusic will alternate between those folders with each passing day in your Minecraft world. What's better, you don't have to worry if the song pack in the AltDay folder is missing some songs, because if no suitable song is found it will "fall through" to the main music folder, and find a suitable song there.

It should look something like this:



Your first AltDay folder should be called "AltDay[2]", and your next one (should you make it) "AltDay[3]". "AltDay[1]" can be used, but it will override the main music folder if it exists, and the music in the main music folder will only play in the event of a fall-through.

With only AltDay[2], music will play from that folder every second day, and the main folder (or AltDay[1]) every other day. With an AltDay[3] folder, it will cycle through each folder every three days.

Needless to say, this means you can download multiple song packs and put each one in an AltDay folder! This is exactly what I do, and why I added the function!

Similarly, you can create a folder called Dimension(#), where # is the number of the dimension, and it will choose from that folder when in that dimension. This works with the Nether, End, and any other modded dimensions.

In-game Commands

Main Article: ActualMusic Commands.

Redirect Files

Instead of .MP3 files, you can make a txt file named in the same way that performs some extra tasks before playing the song, or even redirects the song loader to another song entirely.

Main article: Redirect Files

Creating a Song Pack

The Basics

Find any song you like (as long as it's an mp3) and copy it into the music folder. Rename the song "Title" (without quotes). This song will now play at the title screen of Minecraft. Find another song that you want to play during the game, copy it in with the last one in the Music folder, and name it "General". This song will now play when in your minecraft world. You should have something like this now:


Now if you open Minecraft, you'll hear the music playing when it loads to the title screen. If you load or create a world, you'll hear the second song you added. This is a good start, but I'll bet you that you're going to get bored of that song playing on an infinite loop after a short while. Besides, you could easily have accomplished the same thing by just playing the song in your media player, right? Time to make things a bit more interesting.

Pick out a few more songs and name them "Night", "BiomeType(Forest)", "Underground", and "DeepUnder". You should have something like this:


Now, the music will change to different songs depending on where you are and (in some cases) what time it is. Following is a detailed explanation of how this works.

If you are deep underground (near lava and diamond level), you'll hear DeepUnder. If you're underground, but not that deep under, you'll hear Underground. If you're above ground and in any biome that is classified by Forge as a forest, BiomeType(Forest) will play regardless of if it's day or night. If none of the above is true, but it's night time, Night will play. Finally, if none of the above are true, General will play.

General is the fallback song when no other conditional song exists to be played, so if you don't include a song called General, the mod won't play music when no other song is available.


The words used in the song names are called "Triggers". They are keywords that indicate when the song should play. As of version 2.0, you can specify more than one trigger in a song name, as many as you think is reasonable. Where Day and Night were just little 'addons' to some songs before 2.0, they are now their own triggers, so instead of GeneralNight, you would just write Night. If you want a song to play when you're low on health and it's night you put both triggers in the name separated by a hyphen, so "LowHP-Night", or "Night-LowHP. The order doesn't matter. You could even have "LowHP-Night-Underground-Battle"!


Some triggers allow for "Conditions", which makes the trigger more specific. You add a condition by putting it next to the trigger in parenthesis, like this: "Riding(Horse)", "BiomeType(Forest)", etc. Capitalization is important when writing your filenames - if it's not capitalized properly, it won't be recognised by the mod.

Random Variants / Using multiple songs for one trigger

By adding a number in square brackets to the end of a song name, you can allow it to have random variants. For example, if you have LowHP[1] and LowHP[2], the mod will choose between those two songs randomly each time the song for Low HP would play. You must not have a version of the song without the variant number, in this case just LowHP, because it only tries for the variant versions if it doesn't find the basic version. Additionally, your numbering must be contiguous ( include every number from beginning to end ) because once the song loader fails to find a file the first time, it stops looking for new songs.

What Songs will Play When?

ActualMusic has a built-in order for deciding what song to play at what time, which can be viewed in the "Reference" section of this documentation. No one song will cause another to stop playing, they will simple fade out and pause until it's time for them to play again. Songs will, however, 'die of old age' (left paused for too long) or 'die of crowding' ( more than the maximum allowed songs playing at once ).

Main Article: ActualMusic Reference Guide.

Debug Screen

Pressing F3 will open the debug screen in Minecraft. After using /music debug, ActualMusic replaces this screen with information to help you create/debug your songpack.

Screenshot is from ActualMusic 2.0.0 and may not be identical to what you see in later versions.

Left-Hand Side

AltDay Tells you what AltDay folder the mod is currently looking into, and what day it is in the world.
Active Songs This indicates how many songs currently have a thread running, and how many are allowed to run at once.
Songs in (parenthesis) have not yet started but are loaded and ready. The song in *Asterisks* is the currently playing song.
Location Card Indicates the last location card that appeared on screen, and the one that applies to the are you're currently in now.
Riding The name of the mob you're currently riding.
Fighting The name of the boss you're currently fighting.
Mobs Aggro / Near The first number is how many mobs are currently aggressive, either to you, a nearby player or a tamed wolf.
The second number is how many mobs are nearby you in total. To the right of that indicates the most common enemy of the enemies nearby.
Screen Indicates what Gui you currently have up, such as GuiChat or GuiMerchant.
Potions Indicates the names potion effects you're currently affected by.
Biome Indicates the biome you're currently in, as seen by ActualMusic. This will sometimes differ from the biome Minecraft says you're in.
ActualMusic considers the most common biome in a radius around you to prevent the song from bouncing back and forth on a 'biome divide'.
BiomeTypes A list of forge biome types that your current biome is a part of.

All of the names used in these information bits are the names you'll use for your songs when making a songpack.

Right-Hand Side

The information on the right is less useful to anyone but myself, as it just helps me debug certain aspects of the code.

In Home Area If you've defined a home area, this shows when you're within its boundaries.
In Zone # Similarly, this shows when within a user-defined zone.
Standing on The name of the block under your feet.
Air The number of air blocks surrounding you within the area the mod scans for nearby blocks.
Water As above, with water.
Structure As above, with any block considered to be part of a structure, like a Stronghold.
Moon The current moon phase. 0 is a full moon.
Language The currently set language.
Valid Candidates All existing files in the currently chosen folder that match a currently set trigger.
These are listed in the priority order of which they'll play, so the song at the top should be the playing.

Songpack Configuration Files

Main Article: Songpack Config.

Song Packs

Main Article: Song Packs.