Initial remarks
To understand this topic well, it is best to know about hexadecimal, bitwise operations, endianness, and pointers. These won't be covered in detail, so if you need better understanding of these, use the following links:
- Hexadecimal: https://en.wikipedia.org/wiki/Hexadecimal
- Bitwise operations: https://en.wikipedia.org/wiki/Bitwise_operation
- Endianness: https://en.wikipedia.org/wiki/Endianness
- Pointers: http://datacrystal.romhacking.net/wiki/Pointer
Demo data structure
The demo data structure is quite simple. Each button press consists of two bytes, the first containing the buttons to be pressed, and the second containing the length in frames. Specifically:
- The first byte is a bit field of the buttons that should be pressed. The bits correspond to the buttons as follows:
- 0x80: Down
- 0x40: Up
- 0x20: Left
- 0x10: Right
- 0x08: Start
- 0x04: Select
- 0x02: B
- 0x01: A
- The second byte is an 8-bit length, in frames. Note that 1 frame = 1/60 seconds. Possible values range from 1-256 (note that if 0 is specified, it becomes 256). For a button press that lasts more than 256 frames, a second button entry is required.
Examples:
- Example 1: If Up, Left, and A are pressed for 30 frames (.5 seconds), the byte representation would be (in hexadecimal):
61 1E - Example 2: If Right is pressed for 400 frames (6.67 seconds), the byte representation would be:
10 00 10 90
(Note that because this lasts for more than 256 frames, there are two consecutive button entries for Right. The first is 256 (0x100) frames, and the second is 144 (0x90). This makes sense, since 256 + 144 = 400.
Demo button sequence offsets
Now that the button press structure has been explained, you're probably wondering where the data is. Below is a table of offsets for each version and level. Note that these are in hexadecimal:
Donkey Kong Land 2
| Level | Offset (English) | Offset (Japanese) |
|---|---|---|
| Rickety Race | 13F54 | 13F55 |
Donkey Kong Land III
| Level | Offset (English) | Offset (Japanese) |
|---|---|---|
| Jetty Jitters | 53359 | 53014 |
| Rickety Rapids | 53479 | 53134 |
| Whiplash Dash | 536A6 | 53361 |
| Deep Reef Grief | 5374A | 53405 |
Demo button sequence pointer table
Since the demos are of arbitrary length, they have to contain pointers so that the game knows where the aforementioned offsets are in the first place. This is helpful if you ever want to edit or replace these demos.
Donkey Kong Land 2
In both of these versions, these pointers are little-endian, which is typical of Game Boy games.
- English: 0x161AF-161B0
This contains the byte sequence 54 7F, which ends up pointing to 0x13F54 (notice that this is the offset shown above in the Demo button sequence offsets section). - Japanese: 0x161AC-161AD
This contains the byte sequence 55 7F, which ends up pointing to 0x13F55 (notice that this is the offset shown above in the Demo button sequence offsets section).
Note that the pointer can only point from 0x10000-13FFF, due to the Game Boy's 16 KB bank limitation. If you want to point this to another 16 KB bank, the byte for this is found at ROM offset 0x38B4 in the English version, and 0x38E5 in the Japanese version. It is 0x04 in both versions, which corresponds to 0x10000-13FFF (note that 0x4 × 0x4000 = 0x10000). This can be changed to another value, to make the game look elsewhere. Keep in mind, though, that due to the GB's limitations, you are always limited to 16 KB of space. Additionally, you will likely have to expand the ROM to 1 MB, and convert the mapper to MBC5, since Rare's GB games tend to be extremely tight on space. Finally, the subroutine where this pointer is located needs to be in the same bank as the demo data in this game, so if the demo is moved to another bank, this subroutine will have to be moved as well.
Donkey Kong Land III
Unlike in DKL2, these pointers are big-endian. This is unusual for Game Boy games. Rare sure loves big-endian pointers!
- English: 0x14161-14168
This contains the byte sequence 73 59 74 79 76 A6 77 4A, which ends up pointing to: 0x53359, 0x53479, 0x536A6, and 0x5374A (notice that these are the offsets shown above in the Demo button sequence offsets section). - Japanese: 0x8EE2A-8EE31
This contains the byte sequence 70 14 71 34 73 61 74 05, which ends up pointing to: 0x53014, 0x53134, 0x53361, and 0x53405 (notice that these are the offsets shown above in the Demo button sequence offsets section).
Note that you can only point anywhere between 0x50000-53FFF, due to the Game Boy's 16 KB bank limitation. However, it is possible to point elsewhere, to another bank that has more empty space. In the English version, this byte for the ROM bank can be found at ROM offset 0x38E6, and in the Japanese version, it can be found at ROM offset 0x3761. It is 0x14 in both versions (note that 0x14 × 0x4000 = 0x50000). This can be changed to another value, to make the game look elsewhere. For example, changing this to 0x04 will cause the game to look at 0x10000-13FFF instead (this is helpful in the Japanese version, because this space is completely empty!) Keep in mind, though, that due to the GB's limitations, you are always limited to 16 KB of space. However, unlike in DKL2, the pointers do not have to be relocated to another bank even if the demos are, because the game is coded differently in that the pointers are in a different bank from the demos.
Demo button sequence master pointer
In Donkey Kong Land III, the table of pointers for the demo button sequence itself has its own pointer! This is particularly useful if you want to add more demos (and therefore, more pointers for the demos), since you have to relocate the pointer table to expand it. This pointer contains the address of the first pointer for the button sequence. Note that this master pointer is little-endian this time. This is found at the following offsets:
- Donkey Kong Land III (English): 0x14138-14139
This contains the byte sequence 61 41, which ends up pointing to 0x14161. Note that this pointer can point to anywhere in 0x14000-17FFF. - Donkey Kong Land III (Japanese): 0x8EDFF-8EE00
This contains the byte sequence 2A 6E, which ends up pointing to 0x8EE2A. Note that this pointer can point to anywhere in 0x8C000-8FFFF.
Note that this whole thing is coded differently in Donkey Kong Land 2. Instead of reading the pointer from a table, it is determined on the fly, as part of the same subroutine that loads the level index. Therefore, the button sequence pointer is more difficult to relocate, and it requires reworking some ASM code.
Demo level list
Donkey Kong Land 2
In Donkey Kong Land 2, the level for the sole demo can be found at the following offset (note that only one demo exists in this game):
- English: 0x161AB
- Japanese: 0x161A8
These are the level indices:
- 0x00: Mainbrace Mayhem
- 0x01: Topsail Trouble
- 0x02: Slime Climb
- 0x03: Pirate Panic
- 0x04: Gangplank Galley
- 0x05: Rattle Battle
- 0x06: Arctic Abyss
- 0x07: Clapper's Cavern
- 0x08: Black Ice Battle
- 0x09: Kannon's Klaim
- 0x0A: Squawks's Shaft
- 0x0B: Windy Well
- 0x0C: Ghostly Grove
- 0x0D: Gusty Glade
- 0x0E: Web Woods
- 0x0F: Bramble Blast
- 0x10: Bramble Scramble
- 0x11: Screech's Sprint
- 0x12: Jungle Jinx
- 0x13: Klobber Karnage
- 0x14: Animal Antics
- 0x15: Target Terror
- 0x16: Rickety Race
- 0x17: Krazy Koaster
- 0x18: Hothead Hop
- 0x19: Redhot Ride
- 0x1A: Fiery Furnace
- 0x1B: Barrel Bayou
- 0x1C: Krockhead Klamber
- 0x1D: Mudhole Marsh
- 0x1E: Dungeon Danger
- 0x1F: Chain Link Chamber
- 0x20: Toxic Tower
- 0x21: Hornet Hole
- 0x22: Rambi Rumble
- 0x23: Parrot Chute Panic
- 0x24: Lockjaw's Locker
- 0x25: Lava Lagoon
- 0x26: Glimmer's Galleon
- 0x27: Krow's Nest
- 0x28: Kleaver's Kiln
- 0x29: King Zing Sting
- 0x2A: Kreepy Krow
- 0x2B: Stronghold Showdown
- 0x2C: Krocodile Kore
- 0x2D: K. Rool Duel
In a retail game, this byte is 0x16, which corresponds to Rickety Race.
Donkey Kong Land III
In Donkey Kong Land III, the list of levels are found at the following offsets (in this game, four demos exist):
- English: 0x1415D-14160
- Japanese: 0x8EE26-8EE29
These are the level indices:
- 0x00: Seabed Shanty
- 0x01: Coral Quarrel
- 0x02: Deep Reef Grief
- 0x03: Total Rekoil
- 0x04: Liftshaft Lottery
- 0x05: Miller Instinct
- 0x06: Koco Channel
- 0x07: Riverbank Riot
- 0x08: Surface Tension
- 0x09: Black Ice Blitz
- 0x0A: Polar Pitfalls
- 0x0B: Tundra Blunda
- 0x0C: Red Wharf
- 0x0D: Ford Knocks
- 0x0E: Jetty Jitters
- 0x0F: Minky Mischief
- 0x10: Redwood Rampage
- 0x11: Simian Shimmy
- 0x12: Vertigo Verge
- 0x13: Rockface Chase
- 0x14: Clifftop Critters
- 0x15: Rocketeer Rally
- 0x16: Footloose Falls
- 0x17: Rickety Rapids
- 0x18: Stalagmite Frights
- 0x19: Haunted Hollows
- 0x1A: Ghoulish Grotto
- 0x1B: Jungle Jeopardy
- 0x1C: Tropical Tightropes
- 0x1D: Rainforest Rumble
- 0x1E: Karbine Kaos
- 0x1F: Bazuka Bombard
- 0x20: Kuchuka Karnage
- 0x21: Barrel Boulevard
- 0x22: Ugly Ducting
- 0x23: Whiplash Dash
- 0x24: Barbos Bastion
- 0x25: Bleak Magic
- 0x26: Arich Attack
- 0x27: Krazy KAOS
- 0x28: K. Rool Duel
- 0x29: K. Rool's Last Stand
In a retail game, the byte sequence at the above offsets is: 0E 17 23 02, corresponding to Jetty Jitters, Rickety Rapids, Whiplash Dash, and Deep Reef Grief.
Level pointers
For Donkey Kong Land III, the level offsets (listed above) have their own pointer, which can be particularly useful if you want to add more demos (and therefore, more level entries). This pointer is little-endian, and contains the address of the first level in the list. Since you can't expand the list of levels without having to relocate this data, knowing the pointer is helpful for this purpose. This is found at the following offsets:
- Donkey Kong Land III (English): 0x14129-1412A
This contains the byte sequence 5D 41, which ends up pointing to 0x1415D. Note that this pointer can point to anywhere in 0x14000-17FFF. - Donkey Kong Land III (Japanese): 0x8EDEF-8EDF0
This contains the byte sequence 26 6E, which ends up pointing to 0x8EE26. Note that this pointer can point to anywhere in 0x8C000-8FFFF.
Note that this whole thing is coded differently in Donkey Kong Land 2. Instead of reading the level index from a table, it is determined on the fly, as part of a subroutine. Therefore, the level index is more difficult to relocate, and it requires reworking some ASM code.
Example demo
All of this is likely confusing by this point, so let's demonstrate of an example of how a demo is stored. For simplicity, we'll use the Jetty Jitters in the Japanese DKL3 as an example.
- In the Japanese version of DKL3, the master pointer for the demo button press pointers is located at 0x8EDFF-8EE00. The byte sequence here is 2A 6E, this pointer is little-endian, and it points to the same bank as this master pointer (which would be from 0x8C000-8FFFF). This comes out to 0x8EE2A.
- Now we go to ROM offset 0x8EE2A. The Jetty Jitters demo is the first one stored in the game, so we use the first pointer at 0x8EE2A. This has the byte sequence of 70 14. We got part of the big-endian pointer.
- Next, we need the ROM bank as well. In the Japanese version, this is located at 0x3761. This value is 0x14, which means the pointer can be between 0x50000-53FFF because 0x14 × 0x4000 = 0x50000. Combining this with the step above, this pointer ends up being 0x53014. Therefore, the sequence of button presses starts at this ROM offset.
- Next, we need to know which level should be played. The pointer for the level list is located at 0x8EDEF. This byte sequence is 26 6E. This is a little-endian pointer, and the bank is the same as this pointer (therefore, 0x8C000-8FFFF). This comes out to 0x8EE26.
- As this is the first demo stored internally, we read from the byte stored at 0x8EE26, which comes out to 0x0E. Looking at the list of level indices, this comes out to Jetty Jitters.
Important HRAM addresses
There are important addresses in HRAM for demos.
| Offset (DKL2) | Offset (DKL3 - English) | Offset (DKL3 - Japanese) | Purpose |
|---|---|---|---|
| 0xFFE2-FFE3 | 0xFFE2-FFE3 | 0xFFE1-FFE2 | Pointer (big-endian) for next button press in demo (corresponds to ROM offsets 0x10000-13FFF in DKL2; 0x50000-53FFF in DKL3) |
| 0xFFE4 | 0xFFE4 | 0xFFE3 | Frames remaining for current button press in demo |
| 0xFFE5 | 0xFFE5 | 0xFFE4 | Current button press in demo |
| — | 0xFFFC | 0xFFFB | Current demo slot (only last three bits are used) |
Choosing the demo in DKL3
As some people may know, Donkey Kong Land III actually has four demos, though the Jetty Jitters demo is more well-known. By pressing Select, Up, Left, or Down, the demo can be changed. Each press increments a counter at FFFC (in the English version) or FFFB (in the Japanese version). Only the last three bits are looked at, because when the demo is about to load, this counter is read, than a bitwise AND with 0x03 is performed, effectively forcing the counter from 00 to 03. Therefore, the counter resets after every four presses: Pressing a button four times is the same as not pressing anything at all. The counter resets to 0 every time the title screen loads.
Adding more demo slots
This is easier to do in DKL3 than in DKL2 for reasons mentioned earlier, therefore, this section will only cover DKL3. In order to add more demos, the following must be done:
- The pointer table for the button presses needs to be expanded. To do this, it must be relocated to a region of sufficient empty space. Modify the pointer in the "Demo button sequence master pointer" section above, then relocate the pointer table based on the new pointer. After doing this, you can add more pointers.
- The list of levels needs to be expanded. To do this, it most be relocated to a region of sufficient empty space. Modify the pointer in the "Level pointers" section above, then relocate the list of levels based on the new pointer. After doing this, you can add more levels.
- Allow the possible range of values for the demo slot counter to be broader than 00-03. The easiest way to do this is to go to the following ROM offsets, depending on your version:
- English: 0x14125
- Japanese: 0x8EDEB
Fixing the Jetty Jitters demo in the Japanese version of DKL3
If you've seen the Jetty Jitters demo in the Japanese DKL3, it desyncs in a certain spot, and causes the Kongs to die before finishing the level. This does not occur in the English version of DKL3. This is apparently due to sensitive timing differences between the two versions, since the Japanese version takes advantage of the GBC's double speed mode. So, how to fix it? The easiest way is to go to offset 0x530CF and change this byte from 09 to 0B. This causes the corresponding Right+B button press to last two frames longer, which causes the subsequent Right+B+A press to occur two frames later (where Dixie is now actually on the rope when she tries to jump). This small difference is just enough to allow the Kongs to make it to the goal properly.
Alternately, you can disable double-speed mode by going to ROM offset 0x016D and changing three bytes to 00 00 00 -- this will also make the demo work like it does in the GB version, but the lack of double-speed mode in the Japanese version makes the game virtually unplayable, so it's not recommended for a serious fix!
Fixing all of the other demos
The Jetty Jitters demo in the English version of DKL3 is the only demo in either DKL2 or DKL3 where the Kongs actually make it to the end. The others seem unfinished, and Kongs die after certain points in levels. Unfortunately, it seems that these demos are unfinished. They were probably recorded early in development, and then the layouts of these levels likely changed in the middle of development, though the demos were seemingly never adjusted. At least that's my assumption... the evidence of this can be seen if you look at the Important HRAM addresses section above. If you use an emulator with a memory viewer such as BGB, and look at these HRAM addresses, you can see that the game still tries to press buttons and control the Kongs even after they lose a life. So, there's no real easy fix for these seemingly unfinished demos, and it's probably easier to record them from scratch. Which brings me to...
Recording custom demos
All of this would naturally require an extensive ASM hack to do. There's no ASM hack for this released yet, but I have worked on one for the Japanese version of DKL3, with possible plans to implement similar hacks for DKL2 and the English DKL3. So, with patience, I will publicly release this one day!
Conclusion
These notes on demos are rather extensive, and I imagine that anybody interested in this will have lots of questions about this. If you are confused about something, or you spot an error, please let me know! I also plan on expanding and updating this page as needed.
If you would like to see an example hack that takes advantage of a lot of the information in this topic, here's a hack that adds custom demos to the Japanese DKL3!
