Skip to content
JonataOliveiraa edited this page Nov 14, 2026 · 1 revision
Basics

A mod can give its items, NPCs and tiles sounds of their own, and play them whenever it wants. Sounds are written as in tModLoader: a SoundStyle names the file and says how it plays. Music is different and has its own system, explained in Biomes.

A sound of your own

Put the file in your mod, usually under Assets/Sounds/, as .ogg, .wav or .mp3. A SoundStyle points at it by the mod's name and the path, without the extension. This is the Example Mod's gun:

Item.UseSound = new SoundStyle($"{nameof(ExampleMod)}/Assets/Sounds/Items/Guns/ExampleGun")
{
    Volume = 0.9f,
    PitchVariance = 0.2f,
    MaxInstances = 3,
};

Item.UseSound, NPC.HitSound, NPC.DeathSound and a tile's HitSound all take a SoundStyle, and the game plays it at the right moment: here, every time the gun shoots. If the file is missing, nothing plays and the log says so; nothing throws, so a typo in the path shows up as silence.

The game's own sounds stay as they are, Item.UseSound = SoundID.Item1; or NPC.HitSound = SoundID.NPCHit1;. On the phone Item.UseSound is the game's LegacySoundStyle, not a SoundStyle? as in tModLoader, but it has HasValue and Value, so tModLoader's if (Item.UseSound.HasValue) SoundEngine.PlaySound(Item.UseSound.Value, ...) works unchanged.

How it plays

The options of a SoundStyle shape every play. Volume goes from 0 to 1 (1 by default). Pitch raises or lowers the sound, in octaves from -1 to 1, and PitchVariance adds a random spread around it, so a sound heard many times in a row does not tire the ear; PitchRange = (min, max) sets both at once.

MaxInstances is how many copies of the sound may play at the same time: 1 by default, 0 for no limit. When the limit is reached, SoundLimitBehavior decides what happens: ReplaceOldest, the default, stops the oldest copy, and IgnoreNew skips the new one. The gun above allows three, so fast shots overlap instead of cutting each other off.

Type picks the volume slider the sound follows in the game's settings: SoundType.Sound for the sound volume, SoundType.Ambient for the ambient volume and SoundType.Music for the music volume.

A sound can have variants, chosen at random each time: new SoundStyle("ExampleMod/Assets/Sounds/Hit_", 3) plays Hit_1, Hit_2 or Hit_3. (path, start, count) and (path, ReadOnlySpan<int> variants) choose other numbers. WithVolumeScale(scale) and WithPitchOffset(offset) give a changed copy of a style, and so does C#'s with { ... }.

Playing a sound yourself

SoundEngine.PlaySound(style, player.Center);
SoundEngine.PlaySound(style);

With a position, the sound behaves like the game's own: it gets quieter the farther it is from the middle of the screen, comes from the left or the right, and is not played at all beyond the game's hearing distance. Without a position, it plays at full volume, which suits sounds of the interface. PlaySound returns a SlotId, whose Value is 0 when the sound was not played.

How it works on the phone

The phone's version of Unity cannot create new audio clips, so Bunny Loader plays mod sounds through Android's sound pool, next to the game. A mod SoundStyle given to the game, in Item.UseSound and the others, is a marker that the game passes back when it would play the sound, and Bunny Loader plays the file at that moment.

That has one consequence. Following a sound while it plays (SoundEngine.PlaySound(style, position, callback) and TryGetActiveSound) and looping it (IsLooped) work with the game's sounds that can be tracked, but Android's sound pool gives nothing to follow, so asking for either with a mod's sound file throws NotSupportedException.


← Dust and gore  ·  Localization →

Clone this wiki locally