Donkey Kong Country graphics and sound (Yoshifanatic's disassembly)

In the first US release, each sprite pose is one block in ROM: an 8-byte header, then 2 bytes per piece (its X, then its Y), then the pose's tiles, which the game sends to video memory as they stand, 32 bytes a tile (dkc-av/sprite-pose-upload). Header byte 0 counts the large pieces; bytes 1 and 3 count two groups of small pieces, and bytes 2 and 4 give each group's first tile number, counted from the sprite's own tile base. Each large piece's tile number is 2 past the last, plus 16 more on reaching a multiple of 16, so from a base that is a multiple of 16 eight large pieces fill each pair of tile rows (computed); each small piece's is 1 past the last. Large pieces get both of a sprite's two extra bits in the sprite table, the second as the size bit; small pieces get the second bit never. A piece whose Y comes out at $F0 or more after the sprite's offset is added is left out of the frame, and the first extra bit, the ninth X bit, is kept only when X passes 255. dkc-av/sprite-pose-format

About: Donkey Kong Country Metasprites

Value: header bytes 8 · bytes per piece 2 · bytes per tile 32

With object size setting 0 the two sizes are 8×8 and 16×16 (snesdev-ppu-registers), which the tile steps fit: a large piece takes a 2×2 square of tiles. Which size setting holds during levels, and the sprite table's bit layout, aren't read here. The disassembly's own extraction script (AsarScripts/ExtractOAMData.asm) sizes a pose the same way: 8 + 2 × (byte 0 + byte 1 + byte 3) header bytes and byte 0 × 128 + (byte 1 + byte 3) × 32 tile bytes. Its asset table lists 2,882 pose files (counted).

In the first US release, a sprite's tiles go to video memory only when its pose changes: the game queues one transfer of header byte 5 × 32 bytes, read straight from the pose's block in ROM after its piece list, to video memory at the sprite's own tile base, and a second of byte 7's low four bits × 32 bytes, landing byte 6 × 16 words further on, when that count isn't 0. A later routine runs the queue as DMA transfers to video memory. The queue has a limit on uploads; at or past it, nothing is queued, and poses from number 141 up are drawn as the pose last uploaded. dkc-av/sprite-pose-upload

About: Donkey Kong Country Metasprites

The limit is the value at $3C, compared with the queue's fill at $170D; pose 141 is $8D.

In the first US release, sprites draw from eight palette slots of 15 colors each: the game copies 30 bytes per palette to color memory at entry 129 + 16 × the slot (computed), leaving the 16-color block's first entry alone. A sprite asks for a palette by its address. A slot that holds that palette and whose use count isn't negative is shared, and its count goes up; a holder whose count is negative is passed over. Without a match, the first empty slot takes the palette and its upload joins a queue of 16, from which each call of the upload routine sends one. With neither, the sprite gets slot 0 and the request is kept with a retry value of 120 (computed), whose unit isn't read. In one mode, set by a flag the code tests, the colors come from a copy in RAM laid out like the ROM's palette area instead of from ROM. dkc-av/sprite-palettes

About: Donkey Kong Country Palette swap

Value: slots 8 · colors 15 · bytes 30 · queue 16

Entry 129 is $81. The mode flag is bit $10 of the word at $1E15; in it the colors are read from $7F2779 + (the palette's address − $81CC), $FC:81CC being the asset table's first sprite palette. The request is kept at $1E35 and the value 120 ($78) at $1E3D.

In the first US release, the two Kongs' palettes are swapped by which Kong the game has as current. When the word the disassembly names the current Kong is 1, the palette the disassembly files as Donkey Kong's active one goes to the sprite a first Kong slot names, and Diddy's inactive one to sprite 4; otherwise Diddy's active one goes to the sprite a second slot names and Donkey Kong's inactive one to sprite 2. A slot holding 0 falls back to sprite 2 or 4. Under one condition, read but not identified, all four move two palettes on, to the ones the disassembly files as the Kongs' P2 palettes. dkc-av/kong-palettes

About: Donkey Kong Country Palette swap

The slots are $0512 (first) and $0514 (second); the palettes are $FC:849A (Donkey Kong active), $FC:8440 (Diddy inactive), $FC:8422 (Diddy active) and $FC:84B8 (Donkey Kong inactive). The condition is the word at $42 being 2 and the one at $44 not 0, and it adds 60 bytes. A new game sets the current Kong word to 1 (DKC1/Routine_Macros_DKC1.asm#L64320-L64321).

In the first US release, each animation is a script of entries, each a length byte below 128 followed by a 2-byte pose number. Each frame the game takes the sprite's animation speed from its timer; when the timer reaches 0 or less it adds the next entry's length × 256 and shows that entry's pose, so at the speed an animation starts with a length counts frames (computed). An entry that leaves the timer still negative is passed over, so a higher speed can skip poses. A byte from 128 up is a command: the first restarts the animation from its first entry, and the second calls a routine named by a 3-byte address. dkc-av/animation-scripts

About: Donkey Kong Country Metasprites

An animation starts at speed $0100, one length unit taken off each frame. The two commands are $80 (restart) and $81 (call); the command table holds more, unread here.

In the first US release, eight looping animations of the two Kongs list these pose entries before their restart command (counted, computed). At the speed an animation starts with, the lengths add up to the frames one pass takes (computed), as long as the routines the scripts call (commands $81, $83 and $84, unread) leave the speed and the script alone. The animations the disassembly names Donkey Kong's walk and run each step through 20 poses, one length unit apiece; the ones it names Diddy's walk and run have 16 and 13 poses, two units apiece. dkc-av/kong-animation-frames

About: Donkey Kong Country Metasprites

The counts are the scripts' entries, not a measured cycle; the fall script holds commands $83 and $81, and the roll and Diddy's idle scripts start with $84. Donkey Kong's idle script (animation 1) and both Kongs' jump scripts run into routines before any restart, so they aren't counted. Which of animations 2 and 3 plays when is the disassembly's naming, unchecked.

In the first US release, the game sends the sound driver to the audio processor once, at reset: first a small loader, then 3,454 bytes of driver to audio RAM from address 1,248 (both computed), the first 256 of them zeros, then the sound effects. To start a song it sends the song's data, each block headed by its length and its address in audio RAM, restarts the driver at its entry point, and waits for the driver to answer 255. Each byte goes over the ports with a toggling handshake that the loader echoes back. dkc-av/sound-driver-load

About: Donkey Kong Country Music driver

Value: driver bytes 3454 · driver address $04E0 · restart $05E0

The driver goes to $04E0 (1,248), its length is $0D7E, its entry point is $05E0, and the answer is $FF. Rev 2's driver is not the same bytes; a byte diff against the build shows it moved and its command table changed, so these lines describe 1.0 only.

In the first US release, the game loads samples into audio RAM a list at a time and keeps a 255-byte map from each sample's number to its slot. It points the sound chip's sample directory at $3200, 4 bytes a slot (the sample's start and its loop point), and puts sample data from $3300. A list of 29 samples loads once, the first time either of the two routines that ask for it runs; after it, each song's own list loads in its place, starting where the 29 end, unless the same list is already loaded. For each sample the game sends its data, then its directory entry, and writes its slot into the map, which it then copies to audio RAM at $04E0. The driver's instrument command reads that map. dkc-av/sample-loading

About: Donkey Kong Country Sampled sound

Value: directory $3200 · data $3300 · map $04E0 · map bytes 255 · shared samples 29

Sample data has the space from $3300 to the echo buffer at $DF00, 44,032 bytes (computed); the code sets no limit of its own. The 70 samples total 73,787 bytes in Rev 2 (computed from dkc-av/sample-table), more than that space, which is why the songs carry lists. The map covers sample numbers 0 to 254.

The sample table holds 70 entries, each a 3-byte pointer into banks C7 and C8; each sample there starts with two 16-bit words, its loop offset and its length in bytes, and its data follows. The table and the rest of bank C9 are byte-identical in the first US release and Rev 2; banks C7 and C8 may differ, so the rows' lengths and loop offsets are Rev 2's. In Rev 2, 8 of the 70 samples have a loop offset other than 0, and 32 have the loop flag set in their last block, so they repeat (counted, computed). dkc-av/sample-table

About: Donkey Kong Country Sampled sound

Within each bank, each sample's 4 header bytes and its length end where the next sample starts; the last sample in bank C7 ends before the bank does, and the next starts at $C8:0000. In Rev 2 the first block with the end flag ends one byte before the length in 68 samples and at it in samples 16 and 26 (computed). The asset table names the data files BRRFile00 to BRRFile45, numbered in hex.

In the first US release, the song table has 27 entries, each a 3-byte pointer to a song's data, and a second table holds 28 sample lists. Starting a song through the game's music routine first loads the sample list with the song's own number, so the Samples column is each song's set beside the 29 shared ones. Lists 18 and 26 are one list; list 27 has no song of its own: when the boot screen's fanfare (song 10) starts before the shared 29 have loaded, list 27 loads in their place, and otherwise list 10 does. dkc-av/song-table

About: Donkey Kong Country Music driver

The disassembly names the songs, by number: 0 DKIslandSwing, 1 CaveDwellerConcert, 2 MistyMenance, 3 AquaticAmbience, 4 MineCartMadness, 5 NorthernHemispheres, 6 VoicesOfTheTemple, 7 FearFactory, 8 LifeInTheMines, 9 TitleTheme, 10 SplashScreenFanfare, 11 IceCaveChant, 12 SimianSegue, 13 ForestFrenzy, 14 CreditsConcerto, 15 GameOver, 16 BonusRoomBlitz, 17 DeathMusic, 18 Victory, 19 TreetopRock, 20 FunkysFugue, 21 BadBossBoogie, 22 CandysLoveSong, 23 CrankysTheme, 24 GangplankGalleon, 25 Failure, 26 BeatLevel. Its asset table also lists three songs no entry points to (EarlyTitleTheme, EarlyCreditsConcerto, EarlyBadBossBoogie); the first's end address, $93FFB5, is written with the wrong bank.

In the first US release, the sound driver reads each track as bytes: from $81 up a note, followed by its length, where the note byte plus the track's transpose picks the entry in a table of 61 pitches; $80 a rest; and below $80 one of 49 commands, $00 to $30, through a jump table. A note writes the voice's volume, pitch, sample, and envelope to the sound chip and keys the voice on. The rows give each command's length in bytes, as its handler moves the track on, and what it sets; four of the commands set parameters for effects the driver runs each tick, whose use isn't read here. dkc-av/driver-commands

About: Donkey Kong Country Music driver

The three tick effects are the bits $01, $02 and $04 of the voice's flags at $0150; the routine at $0917 that runs them isn't read here, so their parameters aren't named. Message $FC sets the value at $25 that switches $02 and $11 to the average. The table is 1.0's: Rev 2's driver has a different command table.

In the first US release, every song gets the same echo buffer and delay: when it restarts, the driver sets the sound chip's echo delay to 4, which makes an 8,192-byte buffer (computed), and its buffer to start at $DF00, and clears the 8,192 bytes from there (computed). It also sets echo volume, feedback, and every voice's echo bit to 0, and starts the song with echo writing off. A song turns echo on with its own commands: $15 gives the feedback and the echo volume and turns writing on, $16 and $17 set echo per voice, and $18 the filter. dkc-av/echo-setup

About: Donkey Kong Country Echo

Value: delay 4 · buffer $DF00 · buffer bytes 8192

Echo delay 4 is 4 × 16 ms = 64 ms at 32 kHz (computed from the S-DSP page). The flags go to $E0 at the start of setup and $20 at its end; bit $20 is the echo-write disable. The cleared range is $DF00 to $FEFF. The driver writes the delay and buffer registers nowhere else, so no song can change them.

In the first US release, sound effects play on the same eight voices as the music: the driver runs 16 tracks, the music's eight and eight for effects, and effect track 8 + n uses voice n. An effect that starts takes its voice over, turning its noise and echo bits off; while it plays, the music track for that voice keeps its place, and a music note on that voice writes nothing to it. When the effect ends the voice goes back to the music, with its echo bit set again if the music had turned echo on. dkc-av/sound-effect-voices

About: Donkey Kong Country Music driver

In the first US release, each entrance (a stage's start, its checkpoint barrel, a way into or out of a bonus room) picks the routines that run each frame while that entrance is in play from a table of 230 rows, one per entrance number. Each row is a pair of routines; each of the first routines named here writes the background layers' scroll registers (dkc-av/parallax-layers), and one caller runs the first alone while another runs the first and then the second. The frame interrupt runs the current task of a list, and the list the game sets up for play holds a loading task and then that second caller, so once the loading task moves the list on, both routines of the entrance's pair run on each frame interrupt; the interrupt that comes while a frame's work is still running only rewrites the brightness and returns. The 230 rows hold 21 different pairs (counted). By the disassembly's names for the entrance numbers, Torchlight Trouble's rows hold the pair that Reptile Rumble, Bouncy Bonanza, Manic Mincers and Elevator Antics also use, and Orang-utan Gang's start and its five returns from bonus rooms hold a pair no other entrance uses. dkc-av/level-display-routines

About: Donkey Kong Country Scrolling

Value: rows 230 · pairs 21

The pairs are named here by their first routine: CODE_808C6C for the jungle stages, CODE_808E38 for the caves, CODE_808D43 for Orang-utan Gang. Rows go past the bonus rooms to the bosses ($E0-$E5); the entrance defines continue to $FF with no table rows.

In the first US release, the stages' display routines move the second background layer at half the first layer's horizontal speed in the jungle, Orang-utan Gang, snow and cave pairs (dkc-av/level-display-routines). Vertically the jungle pair moves it at a quarter of the first layer's speed, and Orang-utan Gang's and the snow pair at an eighth, the snow pair holding it at 31 px at most; the cave pair moves it at an eighth of the first layer's position held at 287 px or less (both converted from hex). The underwater pair holds the second layer's vertical scroll at -1 (converted from hex) and moves the third layer vertically with the first. The cave and underwater pairs move the third layer horizontally at one and a half times the first layer's speed (computed), except in Poison Pond, where HDMA rewrites the third layer's scroll down the screen (dkc-av/poison-pond-blend). dkc-av/parallax-layers

About: Donkey Kong Country Scrolling

Value: bg 2 horizontal 0.5 · bg 2 vertical jungle 0.25 · bg 2 vertical snow 0.125 · snow cap 31 · cave hold 287 · bg 3 horizontal cave water 1.5

Each routine also writes the first layer's scroll from the camera words as they stand. The holds compare with BMI, a signed test. The underwater pair writes the second layer's horizontal scroll at half speed too, but an HDMA channel rewrites that register on every line in those stages (dkc-av/poison-pond-blend); the cave pair writes the third layer's vertical scroll from the held position's low byte and the first layer's high byte. Which hardware layer holds which picture (the foreground, the far background) isn't read.

In the first US release, Torchlight Trouble's beam is window 1 reshaped on every line by HDMA. The second start step of 45 entrances (counted), Torchlight Trouble's among them, points HDMA channel 2 at a table in RAM of 224 one-line entries (computed), each writing window 1's left and right edges, all set to 255 and 254, and turns that channel on. Only the 6 entrances whose flag word has bit 2 set (converted from hex), which by the disassembly's names are Torchlight Trouble's start, checkpoint and bonus-room ways in and out, rewrite the table each frame, and only while the game keeps a sprite number for it. The beam starts at a point set by that sprite's position and offsets carried in its current pose, which also carries two slopes, one for the beam's upper edge and one for its lower edge, in 1/256 px a line; when bit 14 of the sprite's attribute word is set (converted from hex), both slopes and the horizontal offset are taken negated. The point's line is held between 0 and 223 (converted from hex). From it, each line up moves the edge by the upper slope and each line down by the lower: with a positive slope the window runs from the edge to 255, with a negative one from 0 to the edge, and once the edge passes the screen's side every line beyond is set back to 255 and 254. Every frame the cave display routine makes the table's first entry 1 line or 3 by the low bit of a counter, so on alternate counts the whole shape sits 2 lines lower (computed). dkc-av/torchlight-beam-window

About: Donkey Kong Country HDMA

Value: lines 224 · entrances 6 · flag bit $0004 · mirror bit $4000 · jitter lines 2

The table is at $7F1C28, three bytes a line (a line count of 1, then the left and right edges); the writer stores each line's edges as one word at $7F1C29. The kept sprite number is at $DD and the counter at $2A. The slopes and offsets are the six bytes before the address the pose table gives (dkc-av/sprite-pose-format), as words at offsets 0 and 2 and bytes at 4 and 5. Pattern 1 writes two registers in turn, so each entry reaches the left edge and then the right. The flag word is $1E15 and the bit $0004; the attribute bit is $4000, and that it is the horizontal flip rests on the disassembly's name for the attribute word, YXPPCCCT.

In the first US release, Torchlight Trouble dims the stage with color math outside its beam (dkc-av/torchlight-beam-window). The start code of its 6 entrances loads 128 background colors into color memory with every bit inverted, sets color 0, the backdrop, to a gray of 16 of 31 in each channel (converted from hex), writes 255 to both bytes of color 17 (white, converted from hex), and fills the third background layer's map with one tile word (in the value). It puts the third layer alone on the main screen with window 1, inverted, applied to it, and the first and second layers and the sprites on the subscreen, with no color window in use. Color math subtracts the subscreen from the third layer and from the backdrop, and the cave display routine writes the same layers and color math again every frame. Where the third layer shows color 17, 31 less an inverted channel gives the channel back (computed), so the stage shows its own background colors; where the backdrop shows, 16 less the inverted channel leaves the channel 15 lower (computed). While a countdown the game keeps is above 0, each frame takes 1 off it, writes to the backdrop the color the new count picks from four (in the value, for counts 0 to 3), and turns off the main screen's layers and color math, so that frame shows the backdrop alone. dkc-av/torchlight-color-math

About: Donkey Kong Country Color math

Value: backdrop $4210 · tile word $1001 · entrances 6 · flash colors $4E73, $7FFF, $5318, $3210

$A422 writes $22 to $2130 (subscreen addend; the subscreen's transparent region set to inside the color window, which is empty with no color window enabled) and $A4 to $2131 (subtract, backdrop and BG3, no half). $0300 writes $00 to $2123 and $03 to $2124 (window 1 enabled and inverted for BG3). $4210 is 16 in each 5-bit channel; inverted, a channel c is 31 − c, so 16 − (31 − c) = c − 15, and a channel below 15 can't go under 0. The countdown is at $1E1D; the colors are picked at index count − 1 after the decrement.

In the first US release, the snow stages can wave their third background layer up and down, line by line, with HDMA. The second start step of 15 entrances (by the disassembly's names, Snow Barrel Blast's, Ice Age Alley's and Rambi's bonus room's) builds a table in RAM of 288 one-line entries for that layer's vertical scroll, from a table of 64 values rising from 0 to 127: down the screen the values run 0, 0, 0, 1, 1, 1, 2, 2, 2, 2, 2, 1, 1, 1, 0, 0, then the same below 0, a 32-line wave of up to 2 px either way (computed). The step points HDMA channel 2 at the table and leaves HDMA off. The snow display routine starts the channel one entry further back every 2 counts of a counter it reads, so the wave moves down a line every 2 counts and repeats every 64 (computed), and turns the channel on, with the third layer's map moved to another address in video memory, only while a weather stage the game keeps is 5. dkc-av/snow-wave

About: Donkey Kong Country HDMA

{
 "entries": 288,
 "period": 32,
 "amplitude": 2,
 "wave": [
  0,
  0,
  0,
  1,
  1,
  1,
  2,
  2,
  2,
  2,
  2,
  1,
  1,
  1,
  0,
  0,
  0,
  0,
  0,
  -1,
  -1,
  -1,
  -2,
  -2,
  -2,
  -2,
  -2,
  -1,
  -1,
  -1,
  0,
  0
 ],
 "weatherStage": 5
}

The table is at $7F1C28, the RAM the caves use for their window table (dkc-av/torchlight-beam-window). Pattern 2 writes one register twice, the low and high bytes of the scroll. The map setting moves from $78 to $7C. The weather stage is the word at $1DF1; the counter is $28. The routine reached at weather stages 2 and up also sends new tiles to video memory at $5E00 and $5F00 every frame or every other frame, not read here as graphics. The second start step also runs CODE_80A992, and the builder ends with a call to CODE_80AA42 (line 71565); neither is read.

In the first US release, Poison Pond lays its third background layer over the rest of the stage at half strength. The second start step of its 2 entrances (by the disassembly's names, its start and its checkpoint) puts the third layer alone on the main screen and the first and second layers and the sprites on the subscreen, and sets color math to add the subscreen at half to the third layer and the backdrop. It turns on HDMA channels 2, 5 and 6; the underwater stages' channel setup points them at tables in RAM that set the second layer's horizontal scroll, the first layer's scroll and the third's down the screen. The other 7 underwater entrances (Croctopus Chase's, Coral Capers', Clam City's and Enguarde's bonus room's) take a second step that turns on channels 2 and 5 and sets the color math's layers and operation and the fixed color from a per-entrance table: adding on the second layer and the backdrop for Croctopus Chase, Coral Capers and Enguarde's bonus room, and subtracting at half on the second layer for Clam City. dkc-av/poison-pond-blend

About: Donkey Kong Country Color math

{
 "entrances": 2,
 "otherUnderwater": 7,
 "hdmaPoisonPond": [
  2,
  5,
  6
 ],
 "hdmaOther": [
  2,
  5
 ],
 "designation": {
  "croctopusChase": "$22",
  "coralCapers": "$22",
  "enguardeBonus": "$22",
  "clamCity": "$C2"
 }
}

$6402 writes $02 to $2130 (subscreen addend) and $64 to $2131 (add, half, backdrop and BG3). The enable word's high byte is the HDMA enable: $64 is channels 2, 5 and 6, $24 channels 2 and 5. Pattern 3 writes two registers twice each, so channel 5 reaches the first layer's horizontal and vertical scroll and channel 6 the third's. The setup fills the channel 5 and 6 tables with four copies of a 100-byte table of entries of 22, 11, 10 and 21 lines and the channel 2 table with 224 one-line entries. In the per-entrance table, $22 is add on BG2 and the backdrop and $C2 subtract at half on BG2; whether the addend is the subscreen or the fixed color is set by $2130, which the other step doesn't write and which isn't read here. Poison Pond's step also runs CODE_B9AD17, then writes its own $2131.

In the first US release, the game's fades step the screen's brightness by one of its 16 levels at a fixed pace. A control byte beside the brightness copy holds the pace: a value n from 1 to 127 brightens one level every n frames up to full, and 128 plus n darkens one level every n frames down to black, then the byte clears itself. Each frame the copy is written to the brightness register. Every fade-out start in the code uses a pace of 2, so a fade from full brightness to black takes 15 steps and 30 frames (computed); fade-ins start at black with a pace of 2 or, in three places, 3. dkc-av/screen-fade

About: Donkey Kong Country Screen fade

Value: levels 16 · fade out pace 2 · fade out frames 30 · fade in paces 2, 3

A fade-in from black runs 15 steps; the 16th step finds the level past 15, holds it at 15 and ends the fade, so the byte clears two frames after full brightness is reached. Which transition (level entry, bonus room, death, the map) starts which fade isn't read here: the fade-out stores sit in sprite and level code in banks B6 and BE, the fade-in stores in the screen setups of bank 80. One screen setup (line 9895) also points HDMA channel 3 at the brightness register, from a table in ROM, which can change brightness line by line; what it draws isn't read.