zladx / ladx-disassembly

Disassembly of Legend of Zelda: Links Awakening DX

Links Awakening DX Disassembly

Disassembly of one of my favorite games. Taking it easy for now.

It builds the following ROMs:

• azlj.gbc (Japanese, v1.0) md5: f75874e3654360094fc2b09bd1fed7e8
• azlj-r1.gbc (Japanese, v1.1) md5: 6d8f9cd72201caabdfd0455a819af9ce
• azlj-r2.gbc (Japanese, v1.2) md5: 2e2596c008d47df901394d28f5bd66ec
• azle.gbc (English, v1.0) md5: 07c211479386825042efb4ad31bb525f
• azle-r1.gbc (English, v1.1) md5: ccbb56212e3dbaa9007d389a17e9d075
• azle-r2.gbc (English, v1.2) md5: 7351daa3c0a91d8f6fe2fbcca6182478
• azlg.gbc (German, v1.0) md5: e91fd46e7092d32ca264f21853f09539
• azlg-r1.gbc (German, v1.1) md5: b0080c2f1919a4bb0ea73b788f4a6786
• azlf.gbc (French, v1.0) md5: 1043fd167d0ed9c4094e3c9d8e757f1e
• azlf-r1.gbc (French, v1.1) md5: 68242187b65166b5f8225b20e2021659

Additionally, a wiki includes a high-level overview of the game engine, and technical informations on the data formats used throughout the game.

Usage

1. Install Python 3 and rgbds (version >= 0.6.0 required);
2. make all.

This will build both the games and their debug symbols. Once built, use BGB to load the debug symbols into the debugger.

How to contribute

1. Fork this repository;
2. Find a little piece of code to improve:

• Maybe a typo, a missing constant, an obvious label that could be renamed;
• Or start following a thread (Link's animations? The island fade-out special effect? Trading items constants?) and document some details along your read;
• You can also look at the known improvements – especially good first issues;

3. Submit a pull request.

Having questions, or do you need help? Join the discussion on Discord. You can also read disassembling How-Tos in the Wiki, for some infos about the tools and disassembling processes.

Resources

• Artemis251's Link's Awakening Cache: ROM map, maps data format
• Xkeeper's Link's Awakening depot: maps tilesets and save format infos
• LALE: level editor, notes on maps data format
• The Legend of Zelda Link's Awakening /DX Speedrunning Wiki : infos on wrong warps and map data format
• Zelda III Disassembly (archive): good source on Zelda SNES source code, which has many similarities to LADX
• Disassembling Link's Awakening: a series of blog posts and progress reports
• Discord: LADX

Contributors

Thanks to these people for contributing:

• mojobojo - https://github.com/mojobojo
• kemenaran - https://github.com/kemenaran
• Drenn1 - https://github.com/Drenn1
• Sanqui - https://github.com/Sanqui
• Kyle McGuffin - https://github.com/kcmcg
• Marijn van der Werf - https://github.com/marijnvdwerf
• samuel-flynn - https://github.com/samuel-flynn
• Xkeeper - https://github.com/Xkeeper0
• Vextrove - https://github.com/Vextrove
• daid - https://github.com/daid
• stephaneseng - https://github.com/stephaneseng
• zelosos - https://gitlab.com/zelosos
• tobiasvl - https://github.com/tobiasvl

(See contribution details here)

ladx-disassembly's Issues

Doubts about the reverse engineering process

Hi! First, great job on this!

I have some questions about the process:

1. How did you manage to rip all text dialogues?

2. I know some Game Boy ROMs that have compressed graphics. How do you guarantee that only converting ROM banks will give you all graphics data from the game?

3. Is there any plan on music and SFX? Maybe a tool or technique to rip that?

Cheers!

Parse maps Warp data

For now maps have their header and blocks data disassembled, but not their warp data.

From the LALE hacking notes:

Warps
Each screen can have one warp

5-Byte Warps

• First byte = Area Type (E tells it to be a warp, 2 = area type)
  • 00 = overworld
  • 01 = dungeons A
  • 02 = dungeons B
• Second byte = Dungeon map (00 = Level 1, 01 = Level 2, etc)
• Third byte = Dest Room (Must be in map of the dest dungeon)
• Fourth byte = X (Tile x, extra X)
• Fifth byte = Y (Add 10, starts at header)

These Warp data can probably be parsed and disassembled to a readable ASM format (by a script similar to tools/generate_map_data.py).

Fix shiftability of palettes in bank20

When inserting bytes at the beginning of bank 20, Link's palette becomes corrupted.

This is probably because some pointers to palette data in bank 20 are not labeled properly.

Integrate `mgbdis` as a submodule

For now disassemblies are generated using a fork of the mgbdis disassembler (https://github.com/kemenaran/mgbdis), with a few cosmetic changes.

This fork should be referenced in the project, so that we know which version of the fork is used for disassembling.

Label palettes pointer tables

palettes.asm has some wrong comments, and data not marked as pointers while they are (and thus labels are missing).

We should turn these data blocks into proper pointers.

Quick overview

For rooms on maps > $0A, background palette data is found by:

• Getting a pointer from table Data_021_4413 which is indexed by MapID - $0A
• then this pointer just points to $100 bytes which is indexed by roomnr.
• The result is a single byte, which is an index into table Data_021_443F which are pointers to the actual palette data.

Add Continuous Integration checks

It would be nice to have each PR tested, to ensure the compiled output is still the identical to the original file.

Maybe with a Gitlab-CI integration, or CircleCI.

Makefile: ignore missing files during tests

When we test the target, md5sum currently prints a warning for each missing file.

azle.gbc: OK
md5sum: stat 'azle-r1.gbc': No such file or directory
md5sum: stat 'azle-r2.gbc': No such file or directory
md5sum: stat 'azlg.gbc': No such file or directory
md5sum: stat 'azlg-r1.gbc': No such file or directory
md5sum: stat 'azlj.gbc': No such file or directory
md5sum: stat 'azlj-r1.gbc': No such file or directory
md5sum: stat 'azlj-r2.gbc': No such file or directory
md5sum: stat 'azlf.gbc': No such file or directory
md5sum: stat 'azlf-r1.gbc': No such file or directory

Instead the make test target should ignore the missing files.

Implementation

md5sum seems to have an --ignore-missing option, but it doesn't seem to work on macOS. Maybe we'll have to re-implement a small md5sum from scratch.

Improve the disassembly of map headers

For now map headers data is not separated from the map blocks.

It looks like this:

Overworld00::
  db   $0B, $E5, $8A, $00, $00, $8A, $10, $00, $8A, $20, $EF, $10, $7C, $11, $7D, $19, $7C, $13, $80, $84, $14, $4D, $17, $81, $23, $37, $83, $24, $0A, $27, $38, $32, $1D, $33, $2E, $34, $48, $36, $49, $37, $4E, $38, $5D, $41, $1D, $42, $37, $43, $39, $44, $E1, $E1, $07, $3A, $58, $10, $82, $45, $3A, $C2, $35, $E0, $47, $3B, $48, $38, $50, $1D, $C3, $51, $37, $C2, $52, $37, $85, $53, $09, $82, $58, $7A, $C2, $60, $37, $85, $63, $09, $68, $38, $72, $2E, $85, $73, $2F, $78, $4E, $69, $50, $79, $09, $FE

This should be improved, by:

• Documenting the header structure (in tools/generate_map_data.py) ;
• Maybe moving the blocks to separate files (like data/blocks/overworld_00.blk).

It could look like this:

Overworld00::
  db ANIMATION_TARAMANCH ; animated tiles set
  db WALLS_NONE | FLOOR_MOUNTAINS ; walls and floor type
  incbin 'data/blocks/overworld_00.blk'

All this data is already parsed by tools/generate_map_data.py. It should just be a matter of augmenting the script to output the right informations.

Number of disassembled banks

Forgive me but why are there 61 banks of disassembled data? I thought there should be only 16 banks?

Document the sound effects generation

Sounds effects (i.e. jingles, waveform-based sfx and noise-based sfx) are generated in https://github.com/zladx/LADX-Disassembly/blob/master/src/code/audio/sfx.asm.

The format seems pretty straightforward; probably no op-codes are involved. Still, the code needs documentation, and at least labeling of the different sound effects.

Remove pre-defined labels

labels.asm contains a medium-sized list of pre-generated labels.

This is rather kludgy: labels should resolve to either:

• an actual reference (for those pointing to a disassembled bank)
• a raw 2-bytes address (for those pointing to non-disassembled-yet code)

Use rgbgfx for compiling images rather than our custom python script

Understand how tilemaps handlers work

Each room has a tilemap ID. And a tilemap ID is not an exact resource: a custom handler will load the tilemap, by compositing several tileset fragments into memory.

There handlers are defined at TilemapLoadingHandlersTable (

LADX-Disassembly/src/code/bank20.asm

Line 1091 in 8f50f17

TilemapLoadingHandlersTable::

).

We should re-label and document the tilemap loaders.

Split misc_cgb.png

misc_cgb.png is apparently at least two different graphics: one spritesheet for the photographer, and credits gfx. It should be split it two PNG files.

ROM map is misformatted

The file src/ROM map.md is formatted such that all banks appear on the same line when viewed in a web browser, rather than each bank on its own line as was likely intended. Consider adding backslashes to the end of each line to insert line breaks, or structure the map as a table.

Extract the entity initialization handlers

Each entity has an initialization handler, a function executed once when the entity is initialized.

Extract and label the table and functions of these handlers.

Resolve the labels in the entities jump table

There a huge jump table, jumping to the code for handling every type of entity. It should be easy to track the code it jumps to.

https://github.com/zladx/LADX-Disassembly/blob/master/src/code/entities/_handlers_table.asm#L13

TODO

• Commit the disassembly of all banks containing entities code
• Move the code to its own code/entities directory
• Make a list of all entities types (in https://github.com/zladx/LADX-Disassembly/blob/master/src/constants/entities.asm)
• Convert raw addresses into labels

Gigaleak source files for disassembly?

Has anyone actually managed to use the Nintendo Gigaleak actual source files for Links Awakening DX as a reference for this project?

Parse and format the entities room data

For now a few pieces of the room-loading code are well-documented:

However the code indicating which entities are in a given room, and what is their initial position is still undocumented.

TODO

• Find the entities room data
• Document the code loading this data

References

• https://github.com/Xkeeper0/links-awakening-junk/ has code for parsing the enemies data, it should be possible to see how it does (see this page, "Enemies data")

Map disassembly inforation

Some notes while I'm here, since I got pinged and figured I'd drop by.

• The 'unreferenced' rooms in the overworld are all the "alternate" layouts for the given rooms. I'm not sure where or how these are swapped in, but they all come directly after the room they're an alternate of. For example, after the Egg, the unreferenced room is the Egg opened; for Eagle's Tower, the next one is the spun-around version, etc.
• The parser, as written, doesn't seem to have any understanding of object sizes. These are fairly simple to implement, at least. See the Neo parser for how they work. Short version:
  • Read high nybble of first byte of object data
  • E: Advance 5 bytes (warp data)
  • C: Advance 3 bytes (vertical object)
  • 8: Advance 3 bytes (horizontal object)
  • D, B, A, 9: ¯\_(ツ)_/¯ These don't seem to ever be used by the game.
  • F, 0-7: Advance 2 bytes (standard object)
• The lack of the above means that map_parser.py currently treats any FE as an end-of-room marker, but this appears in warp data for a few rooms (namely Overworld13 and OverworldE3, maybe others)
• DungeonsAUnreferenced00 and DungeonsAUnreferenced01 seem to be leftover end-of-room bytes! Kinda weird that they come right after two of the Instrument rooms...
• DungeonsAUnreferenced02 is the alternate Goriya room you see when you have the Magnifying Glass.
• DungeonsAUnreferenced03 and beyond are the Color Dungeon pointers (and rooms). You might need to add a manual exception for this in your parser.

Beyond that, nice work! I see it also handled the bizarre ordering of Overworld63 well.

Find what the unused entities were supposed to do

Several unknown entities are unused throughout the code.

These are mostly visible in the entities handlers table: all the entities labeled EntityXXXHandler are not used in the final game–but point to actual code.

For instance these two ones (but there are others)

LADX-Disassembly/src/code/entities/_handlers_table.asm

Lines 120 to 121 in 7f2c25b

	._67 entity_pointer Entity67Handler
	._68 entity_pointer Entity68Handler ; $68

It could be interesting to understand what where these entities, and why they were eventually left out of the final game.

Resources

Maybe some leftover elements mentioned on The Cutting Room Floor could provide some hints.

Disassemble the maps data

Maps data location has been documented in other projects. It consists of:

• Three base maps (overworld, underworld, side-scrolling views) ;
• Room pointers tables (mapping rooms indices to actual room data) ;
• Room data, defining the base map template, the room objects, and several room metadatas.

The code for parsing and loading the map data has been partially reverse-engineered and documented to a good extend (see for instance CopyMapToTileMapLoop in src/bank0.asm).

However the map data is still in binary form. It could be mangled into a format similar to what pokered uses : a mix of self-described assembly for data-structures, and bin files for data.

How

This probably involves writing a Python script to parse the overworld and dungeon map data, and write:

• a readable output for data-structures ;
• bin files for actual data (like map objects).

Documentation

The best documentation available about the map data format probably lies in the source of the LALE Zelda Level Editor. Other fragments are available on various web pages:

• LALE : level editor, notes on maps data format
• Xkeeper's Link's Awakening depot: maps tilesets and save format infos
• Artemis251's Link's Awakening Cache: ROM map, maps data format

Make the PNG graphics easier to edit

Tiles data are stored as PNG files. However sometimes the 4-tiles objects are not aligned: instead they are split between multiple rows or columns.

Exemple

These files should be converted to a PNG layout easier to edit. The original layout of the binary file could be restored at compile time.

Result

How

Different projects have different methods to deal with this issue. One is to add special commands to the PNG filename (like .w16.interleave.png), and then to use pret's gfx.py tool to convert the PNG back to 2bpp.

However this requires users building the code to have a working Python2 installation on their computer.

Another solution would be to add support for interleaved formats to rgbgfx (which is in C, bundled with rgbasm, and generally quite fast). But that's more code to write.

(Also pokecrystal has an intermediary solution with a Python script wrapping the original gfx.py; this may be a thing to look at).

Find what `LINK_MOTION_UNKNOWN_0A` is used for

LINK_MOTION_UNKNOWN_0A is used in a couple of places (mostly related to the Blaino mini boss), but it is not clear yet what it does.

Find out, and then rename the LINK_MOTION_UNKNOWN_0A constant accordingly.

Repo fork status

This repo is marked as being a fork of iimarckus/gb-bootstrap, but it isn't really one any more. It might be worth considering asking support to change this into a normal repo for that reason

Not sure if they'll need more information, but the first commit that started this repo seems to be cd58d92 (with 645df59 being the last one from iimarckus/gb-bootstrap)

Fix palette of Link and NPCs tiles

Link sprite sheet (and NPCs sprite sheets in general) are PNG files, but those are not easy to understand. For a start, the palette seems wrong.

Example of Link's PNG sprite sheet with an incorrect palette

We should edit these PNG sprite sheets to make them easier to edit–beginning with fixing the palette of the PNG files (while still compiling to the same .2bpp in the end).

How

rgbgfx seems to have support for alternate grayscale palettes. Probably the PNG files can be re-extracted using a better palette, and then rgbgfx invoked with the correct options would be able to compile the file back to the original .2bpp.

Understand the purpose of base_maps

For now there's a few blobs of binary data sorted out as base_map.

I don't actually really know what these binary data are used for. Are they pointer tables? A list of tilesets?

Resources

• https://github.com/Xkeeper0/links-awakening-junk can render the rooms (see test.php), so maybe it uses these base_map somehow.
• The LALE level editor can also render rooms, so maybe it reads those base_maps too.

Parse Color Dungeon map

From @Xkeeper0

DungeonsAUnreferenced03 and beyond are the Color Dungeon pointers (and rooms). You might need to add a manual exception for this in your parser.

This means the Color Dungeon map starts at 0x2BB77.

The map parser should be edited to:

• Shorten the Dungeons A Rooms (as unreferenced rooms are actually the other map)
• Add a Map descriptor for the Color Dungeon map

Document the save file format

At 01:5DE6 sees to be the code for saving the game data to the battery-powered save area.

The format of the saved data has been reverse-engineered, but it is not documented in the disassembly yet.

Resources

• @Xkeeper0 reverse-engineered save format: https://xkeeper.net/hacking/linksawakening/savedata.php

Find and document the Chest data

For now a few pieces of the room-loading code are well-documented:

• Initiating a room transition
• Finding and loading the tileset for the current room
• Finding the actual room data
• Looping over the objects to build the room objects map
• Updating the actual Background map during the scroll transition

However the code indicating which chests are in a room, and what they contains is undocumented.

TODO

• Find the chests data section
• Document the code loading and iterating over the chest data

References

• https://github.com/Xkeeper0/links-awakening-junk has some code about displaying the chest data
• The LALE level editor has notes about the chest id locations

Clarify the relation between hMusicTrack, hNextMusicTrack and wActiveMusicTrack

There are several variables controlling the music track playback:

• hMusicTrack,
• hNextMusicTrack,
• wActiveMusicTrack

These variables are often used together, but seem to have subtle differences (like one of these seems to have immediate effect, and another to store the track to be played after a transition).

We should understand better what these variables do (and maybe rename some of them accordingly).

Make doesn't compile

I'm new to this disassembly project but when I run make it gives me an error:

Error: file not found (../../Zelda.gbc)Makefile:25: recipe for target 'bin/banks/bank_00_0.bin' failed

Is there more to this than simply running make?

Make the source code shiftable

ROM hacks are much easier if code can be added and removed without breaking the game.

For this, all ROM raw addresses need to be labeled. That means turning all direct ROM references (e.g. call $1234) into a label (e.g. call Func_000_1234).

(Documenting the label, e.g. call AnimateEntities is a nice-to-have, but is not strictly required.)

TODO

• Make bank 0 shiftable
• Make other code banks shiftable
  • Make many code banks shiftable
  • bank0.asm:88
  • music_1.asm:4
  • audio/sfx.asm:454
  • bank20.asm:80
  • credits.asm:76
  • photos.asm:42
  • bank14.asm:44
  • entities/bank36.asm:84
  • entities/bank18.asm:144
  • entities/bank19.asm:200
• Make graphics shiftable

Progress

Progress can be tracked by running tools/stats.sh, which counts the number of remaining raw addresses that need to be labeled.

How to

• To see which banks need to be made shiftable: tools/stats.sh --verbose.
• To convert blobs of data-interpreted-as-code into an ASM data block with label: tools/data_to_asm.py <start address> <end address>
• How To: make a bank shiftable

Make Octorock / Octorok spelling consistent

Currently there’s an entity named Octorok, and one named WingedOctorock. We should pick a spelling, and rename the entities to have a consistent naming.

`make` should only build the default ROM

Since the revisions PR, make builds all revisions and languages by default.

But make without arguments is often use to check that the ROM builds correctly. It should be fast by default.

make all could be used to build all the languages and revisions.

Make the disassembly stand-alone

Now that mgbdis can disassemble banks almost perfectly, we could add the remaining banks so that the disassembly is stand-alone, and doesn't require the original ROM to fill in the blanks.

Of course much of the disassembled code would actually be data, but this can be fixed later.

Total banks

64 banks in the original ROM.

Missing banks

• $08: Indoor map data
• $16: Entities pointer table and data, text
• $17: Credits code and text
• $1B: Audio code and Music
• $1C: Dialogs code and text (partially done)
• $1D: Text
• $1E: Audio code and Music
• $1F: Audio code and Music
• $21: Background and Objects palettes code and data
• $22: Data
• $23: Indoor paletes
• $24: Indoor palettes; code for some overworld objects
• $25: Overworld tilemaps (00 -> CB)
• $26: Overworld tilemaps (CC -> FF)
• $27: Data
• $28: Photo album and Game Boy Printer code
• $37: Code
• $3C: Super GameBoy graphics and code
• $3D: Code

See the ROM map for details.

Identify and label the BG maps handlers

The game engine supports loading a BG tilemap asynchronously: the game code requests a BG map to be loaded by writing to wBGMapToLoad, and later, during the next V-Blank interrupt, the V-Blank interrupt handler copies the requested tilemap to VRAM.

For now the BG maps are stored sequentially in src/data/backgrounds/background_tile_commands.asm – a file generated automatically by tools/generate_background_data.py, which dumps these data from the original game. They are named BackgroundTileCommands01, BackgroundTileCommands02, and so on.

We should identify and name these BG maps.

The relevant steps could be (with one PR for each step):

1. Create new BGMAP_***** constants to src/constants/gfx.asm, and name them accordingly.
   For instance, if it turns out that BackgroundTileCommands01 is the title screen BG map, we should create a BGMAP_TITLE_SCREEN equ $01 constant.
2. Then edit the Python script, to generate named labels (BGMapTitleScreen::) instead of automatic labels (BackgroundTileCommands01).
3. Then split the BG maps into individual files, one for each BG map.
   _This would allow to reduce the size of the localized BG maps file in revisions/, by storing only the relevant BG maps that diverge from revision to revision, instead of storing the whole BG maps.

NB : additionnaly, once all of this is done, we could write a Python script that can decompress and re-compress BG maps. This would allow to store the BG maps uncompressed, (so they can be easily changed using a tile editor). The BG maps would be re-compressed to the original commands-based format at compile-time.

Convert palettes to RGB format

For now color palettes are stored as sequences of bytes.

They would be easier to read with an RBG() macro, that would emit the correct bytes at compile-time.

Regarding tilemap and attrmap encoding

• peach.tilemap and peach.attrmap are committed, but none of the other decoded files are; should they be?
• Running convert_background.py decode on menu_file_selection.tilemap.encoded and menu_file_selection.attrmap.encoded fails with an IndexError. I think this is because they fallthrough into the subsequent tilemap03 data. It might be more useful to combine those files, and instead of the Tilemap03 and Attrmap03 pointers, store either a raw address (like the ._07 dw $D651) or an offset from the base pointer (e.g. dw MenuFileSelectionAttrmap + $0123).
• Tilemap06 and Tilemap09 might also belong combined with another file. This would explain why some decoded files fail to open in Tilemap Studio, e.g. inventory.tilemap complains "Attrmap is longer than tilemap."

Figure out the unknown audio opcodes

The purpose of some audio opcodes is still unknown. We should figure them out.

• List of the audio opcodes: https://github.com/zladx/LADX-Disassembly/blob/master/src/code/audio_macros.asm

Makefile does not compile on Windows

Hello, I'm a beginner to disassembling as well as using GitHub so I'm sorry if this issue is not very well written.

Typing make all into the command prompt results in the following errors:

File not found - *.asm
File not found - *.png
rgbasm -E -i src/ -o src/main.o src/main.asm
error: Unable to open incbin file 'gfx/characters/link_1.dmg.2bpp'
make: *** [src/main.o] Error 1

Here is a list of things I've tried to resolve the issue, sorted from most prevalent to least prevalent:

• replacing the shell command (used for the asm_files and gfx_files variables) with the bash command in the makefile resulted in resolving the "file not found" errors however it still would not compile due to the RGBDS error.
• I found out the gfx.py script was not working due to missing modules, however that has now been resolved and, even when combined with the bash fix mentioned previously, the makefile still does not work.
• I've used three different versions of make - nmake (gave a different error due to syntax differences), GnuWin32, and Cygwin (both gave the same errors).
• I've tried removing make from my system's Path, and then copying make directly to the folder - same error.

OS: Windows 10
Programs used:

• Python 3.6.4
• Python 2.7.14 (the system Path directs to this version of Python, not 3.6.4)
• Git 2.10.2.windows.1
• Make 3.81 (GnuWin32)
• RGBDS 0.3.6

Document the Super GameBoy frame data format

Link's Awakening supports Super GameBoy features – that is, displaying this nice colored frame.

---

The Super GameBoy communication works by sending commands on the Joypad control bits.

The first command is used to detect the SGB presence. Then the subsequent commands tell the Super GameBoy to upload some frame data (tiles, tilemap and palettes).

Between each command, the code busy-loops to wait for the command completion.

The global structure of the code is pretty much figured out (see src/code/super_gameboy.asm). What needs to be done is:

• Documenting the actual code for sending commands to the SGB
• Documenting the data format: how are tiles, tilemap and palettes splitted out

Resources

• Reading a documentation about the SGB workings should greatly help

Identify the remaining sound effects constants

Many places in the code still have sound effects (sfx, or music tracks) referenced by a numeric value. For instance:

  ld a, $35
  ld [hNextMusicTrack], a

We should ensure that everywhere in the code, these numeric values are replaced by proper constants (found in constants/sfx.asm). For instance:

  ld a, MUSIC_MAMUS_SONG
  ld [hNextMusicTrack], a

Label the steps of the photo picture cutscenes

A little cutscene plays when taking each photo picture. These cutscenes are defined in https://github.com/zladx/LADX-Disassembly/blob/master/src/code/photos.asm.

Each cutscene is splitted into several small fragments:

• loading resources,
• starting the cutscene until the first step is reached,
• starting to play the next sequence in the cutscene, etc.

These steps are not labeled for now. It should be relatively easy to understand what each step does.

The wGameplaySubtype variable (at $DB96) controls the steps of a cutscene: by watching its value change during gameplay in a debugger, it should help understand which step is what.

To access each cutscene individually, you can either:

• During gameplay, manually set the value of $DB95 in a debugger to a value between $0E and 1A, and $DB96 to 0. This will bring you directly to the cutscene.
• Or, at compile-time, enable the ROM_DebugTool3 value. Then use the built-in debug commands to access a fully-filled photo album.

Find and understand the tile placement data

For now a few pieces of the room-loading code are well-documented:

• Initiating a room transition
• Finding and loading the tileset for the current room
• Finding the actual room data
• Looping over the objects to build the room objects map
• Updating the actual Background map during the scroll transition

However converting room objects into actual background tiles requires more than the tileset. It needs to convert the objects into the indices of actual tiles.

TODO

• Find the tilemaps (if the game uses tilemaps)
• Or placement positions: some data indicating "this object is formed by taking 4 tiles starting from $4567 in the order specified by data at $5678"

References

• https://github.com/Xkeeper0/links-awakening-junk can render the rooms from the actual tilesets (see test.php): in the code there must be a place where the matching between objects and tiles is done, for reference.
• The LALE level editor can render graphics, so it must also known how to match objects and tiles. The code is complex though.

Name the few unamed tilemaps

In src/data/backgrounds/ are some tilemaps that have no name (like tilemap_03, tilemap_06, tilemap_09, etc).

They seem to be related to the inventory, but they are not named yet.

We should understand what they do, and name them accordingly.

Fix the name of music tracks

There's a list that matches music tracks ids to names – but it seems to be invalid: many names are not the correct ones. (See src/constants/sfx.asm)

By listening to each music track, the constants could be renamed to have the correct names.

How

Listening to a specific music track id in-game is easy:

1. Run the game in an emulator with a debugger (like BGB);
2. Go to the overworld;
3. Edit the memory at $FFB0 (hMusicTrack), and write a track ID;
4. The music track should start playing.

Rename `Velocity` to `Speed`

Most speed-related variables are named Speed-Something – but some still use the outdated Velocity name.

We should rename variables and comments so that “speed” is used everywhere.

Figure out the audio code and data format

Some music-generating code has been reverse-engineered (see src/code/audio/music.asm), but the actual soundtrack has not been disassembled yet.

Document the entities code

The code for entities AI (i.e. actors, NPCs, enemies, etc) has been entirely decompiled. But much of the code is still undocumented.

A useful task is to pick one of the entities (the files in the src/code/entities/ directory), analyze how it works, and label the functions to document its behavior.