Sound Effects & Sound Driver - pk-hack/CoilSnake GitHub Wiki

[!WARNING] In CoilSnake 4.2, new additions to the sound driver must be added at the bottom of the code. CoilSnake 4.2 expects the song table's location to never change, but since it's the last thing in the driver, it will move if any additions are made before it, and therefore break.

For creating new SFX in this version, unless you can guarantee that they overwrite one that is larger, add them at the bottom of main.asm and place their pointers in the SFX_Table.

EarthBound's sound effects are baked into its sound driver, so if you want to edit them, you'll need to go through that driver. Ever since CoilSnake 4.2, the sound driver is included in projects.

Also you can hack the main code of the driver itself too if you like, but nobody's done much with it yet.

The sound driver is included in a project at Music/Packs/01/engine.bin. But unless you like staring at meaningless numbers, you'll want to use a disassembly of it. The disassembly offers meaningless letters alongside meaningless numbers, but importantly it can then be compiled to create a new engine.bin.

Compiling the driver

The compiler used is asar, and you can get it here.

Next, get the disassembly files from here. There are four files so it's best to just press the "Download ZIP" button so you don't miss any.

When you're ready to compile, open a terminal and type asar main.asm engine.bin, and then move the resulting file to Music/Packs/01/engine.bin. You might want to automate this process with some kind of script. Please note that asar will write over an existing file, not replace it, so if your modified sound driver ends up shorter than the original, then data from the original will remain past the end of the new one's code. This isn't a huge deal though. The workaround is to delete the old driver before compiling, or to make sure that the compiler output location is always unique.

Editing sound effects

Onto sound effect editing. You're probably here just for that. It's best to draft sound effects in EBMusEd. Remember: you're limited to up to two channels, and only the instruments loaded at the time. Sound effects play in channels 6 and 7 (only 7 if it's a one-channel sound), so when writing music, make sure to keep that in mind too.

All the sound effects are helpfully stored in sfx_sequences.asm.
The sound effect format is actually quite different from regular music, but shares a few key similarities. There are also several different formats of sound effects. Here is an example of a single note, single channel sound effect:

; $183A - Cursor move
                db $02
SFX_03:         db $04, $02           ; Note length, hold length
                db $13, $BE, $CA, $AB ; Instrument, volume, pan, note
                db $00                ; Detune

(In assembly, you start raw byte sequences with db, and then write the bytes beginning with $ and separated with commas. Don't forget that it's in hex. If you need to write a pointer to a label, do dw [label].)

The notes themselves are the same as music editing.
Note lengths are weird. We will discuss them later.
Unsure about volume, but it seems to be louder than music for the same values.
Panning seems to be increased by $C0 compared to what you might be used to in music editing, but it seems that the outcome is the same both ways.
Unsure about detune, but I assume it's the inverse of the finetune command (decreasing pitch instead of increasing it).

The first byte is the header byte, and it defines the rest of the format. The pointer of the sound effect (in the SFX_Table in main.asm) should reference directly after the header byte.

This table documents header bytes and their following formats:

Header byte	Description	Format	Format description
`$00`	Unused, same as `$02`	`$00` AA BB CC DD EE FF GG	[Same as `$02`]
`$02`	Single note, single channel	`$02` AA BB CC DD EE FF GG	(Header byte), note length, hold length, instrument, volume, pan, note, detune
`$04`	Sequenced, single channel	`$04` AA BB CC DD [sequence]	(Header byte), instrument, volume, pan, detune, (sequence)
`$06`	Sequenced no staccato, single channel	`$06` AA BB CC DD [sequence]	(Header byte), instrument, volume, pan, detune, (sequence)
`$08`	Execute assembly code	`$08` [assembly]	[Ends when it hits a `ret`]
`$0A`	Sequenced, two channels	AA AA `$0A` BB CC DD EE [sequence] `$04` FF GG HH II [sequence]	Pointer to where FF is, (header byte), instrument, volume, pan, detune, (sequence), `$04`, instrument, volume, pan, detune, (sequence)
`$0C`	Sequenced, no staccato, two channels	AA AA `$0C` BB CC DD EE [sequence] `$06` FF GG HH II [sequence]	Pointer to where FF is, (header byte), instrument, volume, pan, detune, (sequence), `$06`, instrument, volume, pan, detune, (sequence)
`$0E`	Unused, same as `$10`	AA AA BB BB `$0E` CC DD EE FF GG HH II	[Same as `$10`]
`$10`	Noise, single channel	AA AA BB BB `$10` CC DD EE FF GG HH II	Pointer to sequence of GAIN values (`$7F` for key-off and `$00` for end), pointer to sequence of noise clocks (can be `$0000` for nothing), (header byte), length, hold length, instrument, volume, pan, noise clock, speed

Sequenced sound effects

Sequenced sound effects (headers $04, $06, $0A, and $0C) store the actual sequencing in more or less the same format as music does. With this in mind, it's quite easy to draft something in EBMusEd and then paste most of it directly in. Notable differences:

Only a subset of commands are supported. This includes setting panning and volume.
Note lengths do not take the optional second byte for release time and volume. Uses the SFX-specific note length system.
C8 Ties are not supported. Unknown if percussion notes (CA-DF) are supported.

Very important: sequence data must be terminated with $00.

You might notice that the two-channel sequenced SFX format is actually just two single channel SFX in disguise, with a pointer to the second channel. This means you can reuse other SFX for the second channel if you like, but you probably won't. That's why I wrote the format in the table above to include the second sound effect.

TODO: check if you can play SFX of other types as the second channel.

Note lengths

Note lengths use a unique format. Instead of directly writing the amount of ticks a note lasts for, it references a table which lists the note length and how long the key should be held during that note. This data is in the SFX_Note_Table in main.asm.

This table helps you convert from music note lengths to SFX note lengths (indexed by note length).

[!TIP] It should be possible to customise these or even add new entries up to index $FF.

Note length	Hold length	SFX note length byte
`01`	`02`	`25`
`02`	`01`	`4D`
`02`	`02`	`27`
`03`	`01`	`01`
`03`	`02`	`03` or `29`
`03`	`03`	`31`
`04`	`02`	`2B` or `21` or `31`
`04`	`03`	`45`
`05`	`02`	`2D` or `49`
`05`	`03`	`47`
`05`	`04`	`4B`
`06`	`02`	`05` or `2F`
`06`	`03`	`33`
`06`	`05`	`07`
`09`	`02`	`21`
`09`	`07`	`23`
`0C`	`02`	`09`
`0C`	`06`	`35`
`0C`	`0A`	`0B`
`12`	`02`	`19`
`12`	`09`	`3D`
`12`	`10`	`1B`
`18`	`02`	`0D`
`18`	`0C`	`37`
`18`	`16`	`0F`
`24`	`02`	`1D`
`24`	`12`	`3F`
`24`	`22`	`1F`
`30`	`02`	`11`
`30`	`18`	`39`
`30`	`2E`	`13`
`60`	`02`	`15`
`60`	`30`	`3B`
`60`	`5E`	`17`

Custom example breakdown

I drafted this sequence in EBMusEd, then I ported it over and used the note lengths table above.

; Custom sound effect
                ; header byte - sequenced, single channel
                db $04
                ; Instrument, volume, pan, note
; pointer label goes here, after the header byte
SFX_CSTM:       db $0E, $B4, $CA, $00
                ; set note length (06 length, 05 hold)
                db $07
                ; some notes...
                db $A4, $A4, $B0, $C9, $AB, $C9, $C9, $AA, $C9, $A9, $C9
                ; a longer note (0C length, 0A hold)
                db $0B, $A7
                ; back to the same lengths as before
                db $07, $A4, $A7, $A9
                ; end
                db $00

It starts with the header byte of $04. Note that the label (which is used in the main SFX table) comes after the header byte, not at the header byte.

Then we set the note length, play some notes, including changing the note length for one note. Ties are not supported.

Finally, we end with $00 to mark the termination of the sequence. If you forget this, bad things will happen. Tanaka will find you.

That's all there is to it! Seems simple, right? With this knowledge, you can go and make something really cool. In fact, you might want to try this example sound effect to practice compiling and all that jazz.