Skip to content

Audio

A track is a tracker module: XM, IT, S3M or MOD, made in a free editor such as OpenMPT or MilkyTracker. Streamed audio (OGG, MP3) is not supported for music.

Why modules:

  • The DS plays them well. The DS has 16 sound channels and no decoder for compressed audio. Its own games sequence their music from samples, as a module does. On DS the engine plays modules with Maxmod, a mature player made for exactly this.
  • They are small. A module holds short samples and the notes that play them, so a whole soundtrack fits a budget measured in kilobytes.
  • One file, two platforms. The desktop plays the same files with a module player in Rust, mixed at the DS’s output rate, so both sound alike.

ploom import-midi <song.mid> <instruments.txt> <out.xm> turns a MIDI file and a list of instruments into a module for audio/music/, with the converter the importer uses for a game’s music. It reports the notes it had to drop and the memory the module takes on DS.

audio/audio.txt lists every sound by kind, name and file. The sample’s begins:

music town_night music/town_night.xm
music found_it music/found_it.xm once
sfx bump sfx/bump.wav keep
sfx door_open sfx/door_open.wav priority=2 keep
sfx menu_move sfx/menu_move.wav keep
sfx creak sfx/creak.wav priority=2
Kind What Options
music A module once: a jingle, played once instead of looping
sfx A sound effect, a WAV file keep: always loaded on DS; priority=N (0 to 255): who gets a channel when all are busy
cry A species’ cry, a WAV file; the name is the species’ number

game.toml and map.toml name sounds by their names here. A script names them through a symbol file, where a sound is its position among its kind’s lines:

sound CREAK = 13
music NIGHT_TOWN = 0
music FOUND_IT = 1

Effects and cries are WAV files, played as 8-bit mono on both platforms. On DS sound has 512 KB of the 4 MB, and music has 320 KB of that: one module with its samples may take no more, and the build says which module is over and by how much (decision 167).

Only effects marked keep stay loaded. Every other effect, and every cry, is read from the cartridge the first time it plays and stays while there is room, the oldest-played going first. So a game can have thousands of effects. Mark keep the few the player hears all the time (the cursor, doors, the bump), so not even their first play waits. An effect longer than two seconds at 16 kHz is stored as ADPCM on DS, half the room. The build prints how much memory sound takes at most and stops if it is over the budget.

A cry plays as a creature comes out in battle, as its health turns red (lower) and as it faints (much lower), and when a script says cry SPECIES, pitch. For a game you do not share, ploom fetch-sprites --cries fetches cries and writes their cry lines; they are Nintendo’s sounds and are never committed or shipped (see Creatures, moves and data).

A map names its track in map.toml:

music = "town_night"

Scripts change it: playmusic TRACK (fading over half a second), playmusic none, playmusic map (back to the map’s own), fademusic ticks. The sample’s home goes quiet indoors:

on load {
playmusic none
}

A track marked once plays through once and stops. fanfare TRACK plays it over the music, waits for it, and gives the music back where it was. The build works out each jingle’s length from its rows and tempos, so fanfare waits the same time on every platform. The sample’s shared found_item script plays one when an item is found:

fanfare FOUND_IT
say "You found the {0}."

Which track plays can follow rules beyond the map’s music: night and season tracks, a track while surfing or cycling, a flag, a variable a script sets, and each trainer class’s eye music. [audio.music] lists the rules tried first; the first that gives a track plays, else the map’s own (decision 269). The sample has one field track, so out on the water the music stops:

[audio.music]
order = ["surf"]
surf = "none"

A map’s own tracks for the rules are music_night, music_seasons, music_flag, music_region and travel_music in its map.toml. In scripts, eyemusic CLASS plays a trainer class’s track as the trainer sees the player, and musicoverride TRACK puts a track over the map’s until musicoverride map; the override is saved. Every key is in the game.toml reference and the map.toml reference.

[battle.music] names the battle’s tracks by who the foe is, and [battle.sounds] the effects of hits, stat changes, capsules and the experience bar. What is not named is not heard. The sample has no battle music of its own, so its town theme stands in:

[battle]
low_hp = "alarm"
[battle.music]
wild = "town_night"
trainer = "town_night"
victory = "found_it"
[battle.sounds]
hit = "bump"
shake = "rattle"
catch = "click"
alarm = "whistle"

A battle’s track is pushed over the map’s and the map’s comes back after. A once victory track is a fanfare. low_hp is what plays while the player’s creature is in danger: "alarm" repeats the alarm effect, "music" plays the danger track. trainerbattle ... called: rival plays the rival track, music: final the final one, and [battle.music] last plays as a leader’s last creature comes out.

[audio.sounds] says which effect plays at each moment of the interface: the cursor, a choice, a menu opening, a page of text turning, a bump, doors, steps in snow or mud, the save. With this table every moment it does not name is silent; without it the engine plays its own sounds by their places in audio.txt. From the sample:

[audio]
sound_option = true # the options screen offers stereo or mono
cry_level = 128 # the music at half under a cry
cry_down = 4
cry_up = 8
fanfare_in = 6
save_sound = "message" # the save's click once its message is typed out
[audio.sounds]
cursor = "menu_move"
select = "confirm"
text_next = "menu_move"
bump = "bump"
door_open = "door_open"
save = "click"
[audio.screens.bag]
page = "hop"

cry_level and its ticks lower the music under a cry; fanfare_out, fanfare_in and fanfare_gap shape how it makes way for a jingle. [audio.screens] gives a screen (the bag, the party, the shop, the battle’s menus) sounds of its own, and [audio.doors] names door sounds a door piece chooses with door_sound. Each reference game’s tables were measured from its code, and ploom import writes them for the games it imports (decisions 239, 243). With sound_option = true the DS bank also holds a mono copy of each module for players who choose mono.

A desktop build copies audio/ beside the game. The DS sound bank is made by the DS build with the SDK’s mmutil, then rewritten by PokeLoom’s own build (long effects to ADPCM, shared samples stored once), so it needs the DS toolchain today. Planned (plan 13): ploom build nds with no Rust and no DS toolchain on the creator’s machine.

  • Planned (plan 13): the DS build without the toolchain, above.
  • Listed in plan 25, not scheduled: effects that loop until a script stops them, music layers and sound emitters placed on the map, and cry modes beyond pitch (reversed, recorded).