Maps data format

This page documents the data format used by Zelda: Link’s Awakening maps.

Note: this is pretty much a work-in-progress. The given binary offsets are valid for the Legend of Zelda, The - Link's Awakening DX (U) (V1.0) [C][!].gbc ROM.

Maps

A map is just an array of pointers to rooms.

In the overworld map, the rooms are laid out as when playing as they are in-game. However on the indoor maps, rooms are packed together irrespectively of the in-game layout.

Maps are stored as a partial addresses to rooms, in a two-bytes little-indian format. (However they don't store the bank to look the room for; this is hardcoded in the game).

Maps are located at:

0x24000 (09:4000): Overworld map (512 bytes)
0x28000 (0A:4000): Indoors A map (dungeons 1-6, caves and houses) (512 bytes)
0x2BB77 (0A:7B77): Color Dungeon map (64 bytes)
0x2C000 (0B:4000): Indoors B map (dungeons 7-8, caves and houses) (512 bytes)

Some rooms may be unused; and some pointers may not point to a valid room.

Rooms

Rooms describe the objects data for a single screen.

They are located at:

0x24200 (09:4200): Overworld rooms, first half (0x248E bytes)
0x28200 (0A:4200): Indoors A rooms (0x3977 bytes)
0x2BBB7 (0A:7BB7): Color Dungeon rooms (0x38C bytes)
0x2C200 (0B:4200): Indoors B rooms (0x3C01 bytes)

Rooms are composed of:

a two-bytes header,
a list of objects.

Room header

1st = Animation index: "set it to different values to control things like water animation and torch and lamp animations." This would make certain tiles animate.
2nd = (Nybble encoded) First 4 bits (0 in 0D) = Wall template (Defining floor and walls). For example, $93 = 9 = walls, 3 = floor type Regular tiles = $00 - $EB Door tiles = $EC - $FD $EC - EF = Key Door $F0 - $F3 = Closed door $F4 - $F7 = Open door

Room objects

An object type is defined by its first nybble:

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)

See the Neo parser for how they work.

Alternate version

Rooms can have an "alternate" version. There are loaded by special exception code in the loader function, 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.

For instance DungeonsAUnreferenced02 is the alternate Goriya room you see when you have the Magnifying Glass.

Layouts

A layout describes how indoor rooms are laid out, for instance in a dungeon.

They are located at:

0x50220 (14:4220): layouts for all maps (13 layouts, 64 bytes each)

The layout are just room indices in an array. To know which room to load when transitioning upwards, for instance, the game lookups in the layout the location right above the current one, reads the room index, then loads this room.

Entities

A separate data segment indicates which entities are in a given room (and their position).

Pointers table

Pointers tables for the entities data are stored in a two-bytes little-indian format. (They don't store the bank to look the data in; this is hardcoded in the game). The tables are located at:

0x58000 (16:4000): Overworld rooms (512 bytes)
0x58200 (16:4200): Indoors A rooms (dungeons 1-6, caves and houses) (512 bytes)
0x58400 (16:4400): Indoors B rooms (dungeons 1-6, caves and houses)(512 bytes)
0x58600 (16:4600): Color Dungeon rooms (64 bytes)

Entities lists

The format is similar to the room objects: each room has an entities list, made of an entity ID and a position. Lists are terminated by the $FF character.

Although this is relatively infrequent, a list can be used several times for different rooms.

Entities lists are located at:

0x58640 (16:4640): entities lists for all rooms.

An entity in the list defined by two bytes:

First byte: vertical and horizontal initial position of the entity;
Second byte: entity type.

Overlay data

The overworld map has overlay data for the gameboy color. The normal layout for overworld maps is loaded, and this defines how each tile on the screen behaves. But the visual data is loaded from the overlay. This is just a straight forward array of 10x8 tile numbers, no special encoding.

Palette data

# TODO

Chests data