Metroid: Metroid (USA) Music Table Patch

Music timbre information (e.g. duty cycle) for tracks in Metroid is hard-coded in an extremely limiting and romhacker-hostile manner that makes it difficult to configure the timbre as desired when modifying the game's music. This small patch replaces the original system for specifying timbre with a simple table of values that can be easily modified in new hacks.

This hack is for romhackers who are developing their own Metroid hacks only. It does nothing visible to players.

METROID MUSIC TABLE PATCH
v1.0

By Justin Olbrantz (Quantam)

The permanent home of this document and others, with the latest updates, is https://github.com/TheRealQuantam/RetroDocs.

The Metroid music engine hard-codes track square channel timbres (especially duty cycle) in an extremely obtuse and romhacking-hostile way. This simple patch replaces that method with a simple table lookup that makes music modification much easier. But first, a few preliminaries.

The Metroid cartridge is organized such that each zone is assigned a ROM bank which is loaded at $8000-$bfff, and all its data and code (including music) are placed in that bank. As music code and some data structures are present in all zones, they are duplicated in all banks, and any changes will also need to be made potentially across all banks.

The $8000-$bfff banks used for different parts of the game:
0: Title screen and ending
1: Brinstar
2: Norfair
3: Tourian
4: Kraid's lair
5: Ridley's lair

The file offset = bank * $4000 + address - $7ff0

The tracks are as follows:

# Name Bks Sq1T Sq2T
0 (0) Ridley's Lair @4/5: b3:1 b3:1
1 (1) Tourian @all: 92:0 96:0
2 (2) Item Room @all: 92:0 96:0
3 (3) Kraid's Lair @4/5: 92:0 96:0
4 (4) Norfair @ 2: 34:4 34:4
5 (5) Escape @ 3: f4:2 f4:2
6 (6) Mother Brain @ 3: 92:0 96:0
7 (7) Brinstar @ 1: 34:2 34:3
8 (8) Samus Appears @all: 34:2 34:0
9 (9) Item Fanfare @all: b6:1 f6:0
10 (a) Ending @ 0: f5:2 f6:1
11 (b) Title Theme @ 0: b6:2 f6:5

Table legend:
Bks: Bank(s) the track exists in
Sq1T: Square 1 channel timbre settings. The left side is the ctrl 1 value, the right side is the envelope number if any.
Sq2T: Square 2 channel timbre settings.

The ctrl 1 values have the format ddLV vvvv:
d: Duty cycle. 0: 12.5%, 1: 25%, 2: 50%, 3: 75%
L: Disable length counter and play note forever. This is mostly irrelevant since notes in Metroid are set to play for 127 frames, which is longer than the longest length in the length table.
V: Specifies that v is the volume and not decay rate. Always set.
v: The volume

Finally, the table implemented by this patch (across banks):

bc96 struct[$c]: Square wave channel ctrl 1 values
+0: Square wave 1 channel ctrl 1 value
+1: Square wave 2 channel ctrl 1 value

E.g. the table from the patch, which does not change any track timbres:
B3 B3 92 96 92 96 92 96 34 34 F4 F4 92 96 34 34 34 34 B6 F6 F5 F6 B6 F6
B3 B3: Track 0 both channel ctrl 1 values are $b3
92 96 x3: Track 1-3 have square 1 value $92, square 2 value $96
etc.

Database match: Metroid (USA)
Database: No-Intro: Nintendo Entertainment System (v. 20210216-231042)
File SHA-1: ECF39EC5A33E6A6F832F03E8FFC61C5D53F4F90B
File CRC32: A2C89CB9
ROM SHA-1: FDBFC7871962F72A1EF57E5A7E456164FB93430B
ROM CRC32: 70080810