Repository navigation
Sounds
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.
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.
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 { ... }.
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.
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.
Bunny Loader wiki ·
Discord ·
Repository ·
BL Editor
Written for Bunny Loader 0.5.5-beta and Terraria Mobile 1.4.5.8.6.
Bunny Loader is not affiliated with Re-Logic or 505 Games.
