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.txt
Section titled “audio.txt”audio/audio.txt lists every sound by kind, name and file. The sample’s begins:
music town_night music/town_night.xmmusic found_it music/found_it.xm oncesfx bump sfx/bump.wav keepsfx door_open sfx/door_open.wav priority=2 keepsfx menu_move sfx/menu_move.wav keepsfx 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 = 13music NIGHT_TOWN = 0music FOUND_IT = 1Effects and cries
Section titled “Effects and cries”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).
Map music
Section titled “Map music”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}Jingles
Section titled “Jingles”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_ITsay "You found the {0}."Music rules
Section titled “Music rules”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 and sounds
Section titled “Battle music and sounds”[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.
Interface sounds
Section titled “Interface sounds”[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 monocry_level = 128 # the music at half under a crycry_down = 4cry_up = 8fanfare_in = 6save_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.
Building
Section titled “Building”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
Section titled “Planned”- 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).