{
 "schema": 1,
 "platform": "c64",
 "game": "zak-mckracken-and-the-alien-mindbenders",
 "part": "music",
 "build": "Commodore 64 original, three disks from the C64 Preservation Project's G64 collection: zak_mckracken_boot, _s1 and _s2 [activision_1988](manual)(!)",
 "source": "regenerator2000 live",
 "regions": {
  "exclude": [
   [
    256,
    511,
    "stack"
   ],
   [
    53248,
    57343,
    "I/O and colour RAM"
   ],
   [
    0,
    49919,
    "The game"
   ],
   [
    50998,
    65535,
    "The game"
   ]
  ],
  "extra": [],
  "edges": [
   0,
   256,
   512,
   1024,
   2048,
   4096,
   16384,
   32768,
   40960,
   49152,
   53248,
   57344
  ],
  "elsewhere": [
   [
    0,
    49919,
    "The game"
   ],
   [
    50998,
    65535,
    "The game"
   ]
  ]
 },
 "blocks": [
  {
   "start": 49920,
   "end": 49923,
   "type": "Byte"
  },
  {
   "start": 49924,
   "end": 50802,
   "type": "Code"
  },
  {
   "start": 50803,
   "end": 50997,
   "type": "Byte"
  }
 ],
 "symbols": [
  {
   "address": 49920,
   "name": "music_header",
   "type": "UserDefined",
   "kind": "user"
  },
  {
   "address": 49924,
   "name": "music_start",
   "type": "Subroutine",
   "kind": "user"
  },
  {
   "address": 49980,
   "name": "b_C33C",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 49991,
   "name": "b_C347",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50019,
   "name": "music_voice_start",
   "type": "Subroutine",
   "kind": "user"
  },
  {
   "address": 50069,
   "name": "music_frame",
   "type": "Subroutine",
   "kind": "user"
  },
  {
   "address": 50071,
   "name": "j_C397",
   "type": "Jump",
   "kind": "auto"
  },
  {
   "address": 50085,
   "name": "b_C3A5",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50096,
   "name": "b_C3B0",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50130,
   "name": "music_part_over",
   "type": "UserDefined",
   "kind": "user"
  },
  {
   "address": 50139,
   "name": "b_C3DB",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50153,
   "name": "b_C3E9",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50156,
   "name": "music_read_note",
   "type": "Branch",
   "kind": "user"
  },
  {
   "address": 50166,
   "name": "b_C3F6",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50185,
   "name": "music_read_length",
   "type": "Jump",
   "kind": "user"
  },
  {
   "address": 50195,
   "name": "b_C413",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50217,
   "name": "b_C429",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50222,
   "name": "music_read_extra",
   "type": "Jump",
   "kind": "user"
  },
  {
   "address": 50231,
   "name": "b_C437",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50244,
   "name": "b_C444",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50250,
   "name": "j_C44A",
   "type": "Jump",
   "kind": "auto"
  },
  {
   "address": 50258,
   "name": "b_C452",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50269,
   "name": "music_advance_voice",
   "type": "Jump",
   "kind": "user"
  },
  {
   "address": 50285,
   "name": "b_C46D",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50298,
   "name": "music_copy_instrument",
   "type": "Branch",
   "kind": "user"
  },
  {
   "address": 50352,
   "name": "b_C4B0",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50356,
   "name": "b_C4B4",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50381,
   "name": "b_C4CD",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50392,
   "name": "b_C4D8",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50394,
   "name": "b_C4DA",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50401,
   "name": "music_write_event",
   "type": "Branch",
   "kind": "user"
  },
  {
   "address": 50424,
   "name": "music_write_rest",
   "type": "UserDefined",
   "kind": "user"
  },
  {
   "address": 50443,
   "name": "b_C50B",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50444,
   "name": "j_C50C",
   "type": "Jump",
   "kind": "auto"
  },
  {
   "address": 50454,
   "name": "music_write_note",
   "type": "Branch",
   "kind": "user"
  },
  {
   "address": 50482,
   "name": "b_C532",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50484,
   "name": "j_C534",
   "type": "Jump",
   "kind": "auto"
  },
  {
   "address": 50502,
   "name": "music_start_channels",
   "type": "Jump",
   "kind": "user"
  },
  {
   "address": 50605,
   "name": "music_next_voice",
   "type": "Jump",
   "kind": "user"
  },
  {
   "address": 50614,
   "name": "r_C5B6",
   "type": "Return",
   "kind": "auto"
  },
  {
   "address": 50615,
   "name": "music_take_voice",
   "type": "Subroutine",
   "kind": "user"
  },
  {
   "address": 50644,
   "name": "music_voice_end",
   "type": "Subroutine",
   "kind": "user"
  },
  {
   "address": 50676,
   "name": "b_C5F4",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50690,
   "name": "b_C602",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50710,
   "name": "music_find_tune",
   "type": "Subroutine",
   "kind": "user"
  },
  {
   "address": 50732,
   "name": "b_C62C",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50760,
   "name": "music_build_lengths",
   "type": "Subroutine",
   "kind": "user"
  },
  {
   "address": 50781,
   "name": "b_C65D",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50792,
   "name": "b_C668",
   "type": "Branch",
   "kind": "auto"
  },
  {
   "address": 50803,
   "name": "note_pitch_lo",
   "type": "Field",
   "kind": "user"
  },
  {
   "address": 50867,
   "name": "note_pitch_lo_64",
   "type": "UserDefined",
   "kind": "user"
  },
  {
   "address": 50900,
   "name": "note_pitch_hi",
   "type": "Field",
   "kind": "user"
  },
  {
   "address": 50964,
   "name": "note_pitch_hi_64",
   "type": "UserDefined",
   "kind": "user"
  },
  {
   "address": 50997,
   "name": "music_saved_y",
   "type": "AbsoluteAddress",
   "kind": "user"
  }
 ],
 "comments": [
  {
   "address": 49920,
   "type": "line",
   "text": "The heap block's header, which load_resource writes over the resource's own (write_block_header, $D595): the size, $FF00, which is what op_music_memory last asked alloc_hard for ($FC14/$FC15) and not the block's; the type, 6, a sound; and the number, 1. On the disk the same four bytes are the resource's header: its size, $0436 (1,078 bytes), a 0 and the check byte"
  },
  {
   "address": 49924,
   "type": "line",
   "text": "Starts tune A, called by startMusic ($57B1) with the chips banked in. Keeps the tune's number ($44A6) and address ($A9/$AA and $44AD/$44AE, from the sound tables at $74C0 and $7441), keeps the frame interrupt out of the sound engine while it works ($FC31), turns the music off and stops every sound (reset_sound), counts the tune once more as in use ($753F), builds the note lengths from the tune's tempo, its byte 5 (music_build_lengths), and sets up each voice its byte 4 names (music_voice_start). Then turns the music on ($43E8), takes every voice off the filter and keeps its resonance ($43DF), reads each voice's first note at once (music_frame), lets the interrupt back in and sets $FC32, which sound_frame waits for before it begins the sounds on its list"
  },
  {
   "address": 50019,
   "type": "line",
   "text": "Sets voice X up to play its part of the tune: the part's offset in the tune is the word at the byte of the tune's header that $448E,X gives (6, 8 or 10), kept in $44AF/$44B2,X, and its address, the tune's plus the offset, goes to $44A7/$44AA,X. Marks the voice the music's (music_take_voice) and clears its control register, gate and waveform ($438A,X). A, X and Y are kept"
  },
  {
   "address": 50069,
   "type": "line",
   "text": "The music's work for a frame, called by sound_frame ($3FE0) while the music is on ($43E8) and once by music_start. For each voice from 2 down to 0 ($449F) that the music holds ($43E9) and whose channel is free ($43E0), which is when its last note has ended: finds the tune again, which the heap may have moved (music_find_tune), and reads the voice's next event. Its first byte is the note, a pitch from the table at $C673 and $C6D4, or $FF for a rest, or 0 for the end of the voice's part (music_voice_end). The second is the length, an index into the table music_build_lengths made. Up to two more may follow, each an instrument for the voice (bit 6 clear) or a value for variable 17 (bit 6 set, in its low six bits); bit 7 marks an event's last byte. A new instrument is copied into the voice's sound; the pitch and the length go into the sound's first command, its gate set for a note and cleared for a rest; then the engine starts the sound's voice part and its pulse width part on the voice's two channels (start_channel)"
  },
  {
   "address": 50130,
   "type": "line",
   "text": "The voice's part has ended: when it was the last voice playing, the music is over and nothing more is done this frame. Otherwise the test at $C3DE finds the voice no longer the music's, since music_voice_end has just cleared its bit, and goes on to the next voice"
  },
  {
   "address": 50156,
   "type": "line",
   "text": "A note: its pitch from the two tables by its number, with Y kept at $C735 meanwhile. A rest ($FF) sets $449B and leaves the pitch the voice's sound had"
  },
  {
   "address": 50185,
   "type": "line",
   "text": "The length byte: bit 7 set means the event ends with it ($449C). Its low seven bits pick the length, low byte to $4498 and high to $4499"
  },
  {
   "address": 50222,
   "type": "line",
   "text": "One of the bytes that may follow the length, two at most ($4497 counts them): with bit 6 clear it is an instrument number ($449A); with bit 6 set, its low six bits go to variable 17 ($FE7F), a cue for the scripts (ScummVM calls the variable VAR_MUSIC_TIMER). The opening, global script 1, waits for it to pass 1 six times and sets it back each time: before it shows room 55, and then for each of the five objects it shows there in turn (756 to 760). Tune 95's second voice carries six such cues, all 2"
  },
  {
   "address": 50269,
   "type": "line",
   "text": "Moves the voice's address ($44A7/$44AA) and its offset in the tune ($44AF/$44B2) on by the event's bytes"
  },
  {
   "address": 50298,
   "type": "line",
   "text": "A new instrument, number i: its bytes are where the word at byte 12 + 2i of the tune's header points. Five go into the voice's sound at bytes 15 to 19, the end of its first command: the slide, the envelope and the waveform, which $44A0,X keeps. Seventeen more go to bytes 25 to 41, the voice's pulse width part. Most of the tunes' instruments are 15 bytes long and a few 22, and some header entries name the same one: after a 15-byte instrument the last seven bytes copied are the next one's, or, after a tune's last, what follows the tune"
  },
  {
   "address": 50401,
   "type": "line",
   "text": "The event into the voice's sound (3, 4 or 5, from $4492,X): byte 10 is its first command's flags, whose bit 0 is the gate"
  },
  {
   "address": 50424,
   "type": "line",
   "text": "A rest: clears the gate, unless the voice is resting already ($44A3,X), and marks it resting. The LDY #$13 at $C506 is replaced at $C511 before Y is used, so nothing is stored at byte 19 for a rest"
  },
  {
   "address": 50454,
   "type": "line",
   "text": "A note: after a rest, puts the waveform at byte 19 back from $44A0,X and sets the gate again. Then its pitch to bytes 11 and 12 and the voice no longer resting"
  },
  {
   "address": 50502,
   "type": "line",
   "text": "The length to the command's time, bytes 13 and 14. Then the voice's channel takes the sound ($4375, $4379 for its pulse width channel), with priority $7F, no filter and its voice part at byte 8, one voice fewer free ($43F3), and starts; its pulse width channel, X plus 4, starts on the part at byte 25"
  },
  {
   "address": 50605,
   "type": "line",
   "text": "The next voice, down to voice 0"
  },
  {
   "address": 50615,
   "type": "line",
   "text": "Marks voice X the music's: its bit ($435A,X) in $43EA, the voices whose part is still playing, and in $43E9, the voices the music holds. begin_sound refuses a sound effect while the music is on and holds all three voices; while it holds fewer, an effect may take one of its voices that is idle. A, X and Y are kept"
  },
  {
   "address": 50644,
   "type": "line",
   "text": "Voice X's part has ended. Takes it out of $43EA, and when no voice is left playing, turns the music off ($43E8) and counts the tune ($44A6) and the three voices' sounds ($4492-$4494, sounds 3, 4 and 5) once less in use ($753F). Then gives the voice back ($43E9) and clears the waveform it kept ($44A0,X). A, X and Y are kept. Nothing counts sounds 3, 4 and 5 up for the music, so the end of a tune takes one off theirs: 128, the lock bit alone, while the opening's tune plays, and 127 in the bedroom after it"
  },
  {
   "address": 50710,
   "type": "line",
   "text": "Finds the tune again, which the heap may have moved since the last frame: its address from the sound tables ($74C0/$7441) by its number ($44A6) to $44AD/$44AE, and each voice's address ($44A7/$44AA) set to that plus the voice's offset in the tune ($44AF/$44B2). A, X and Y are kept"
  },
  {
   "address": 50760,
   "type": "line",
   "text": "Builds the note lengths from the tune's tempo T in A: the time each note's first command starts with, which step_channel counts down once a frame, going on to the next command when it falls below zero, so a time of N lasts N + 1 frames. Length 1 is T less 2 and each one after it T more, up to length 32, 32T less 2; low bytes at $44B9 and high at $44DA (music_lengths), and length 0 is left at 0. All four tunes on the disks have a tempo of 8, so their lengths start 6, 14 and 22, which last 7, 15 and 23 frames"
  },
  {
   "address": 50803,
   "type": "line",
   "text": "The low bytes of the pitches of notes 0 to 63, as the sound chip takes them (high bytes at $C6D4). Entry 0 is 0 and never read, since a note of 0 ends the voice's part; from note 1 on, each note is a semitone above the one before, as near as whole numbers allow. The table is tuned to an American machine's clock: note 58, $1C31, is 439.9 Hz on an NTSC machine, the A above middle C, and 423.8 Hz on a European (PAL) one, about two thirds of a semitone flat"
  },
  {
   "address": 50867,
   "type": "line",
   "text": "The low bytes of the pitches of notes 64 to 96 (high bytes at $C714); note 96, $FD2E, is 3,951 Hz on an NTSC machine"
  },
  {
   "address": 50900,
   "type": "line",
   "text": "The high bytes of the pitches of notes 0 to 63 (low bytes at $C673); note 1, $010C, is 16.3 Hz on an NTSC machine"
  },
  {
   "address": 50964,
   "type": "line",
   "text": "The high bytes of the pitches of notes 64 to 96 (low bytes at $C6B3)"
  },
  {
   "address": 50997,
   "type": "line",
   "text": "Where music_frame keeps Y while it reads a note's pitch ($C3F6, $C406). It is the resource's last byte, 0 on the disk"
  }
 ]
}