Rooms File Format

Rooms File Format

The rooms file is a JSON array of objects, where each object describes a single room used by the Randomizer. These rooms are used as a pool of rooms from which palaces are constructed.

Community Room Properties

Property	Description
name	Name of the room. Must be unique. Used for identification, debugging, and linking segmented rooms.
author	Name of the room's author.
group	Determines which room group this room belongs to. Supported values: VANILLA, V4_0, V5_0.
enabled	true if the room should be used. If false it is ignored (except when used as the second half of a segmented room).
palaceNumber	Must be 7 for Great Palace rooms. Any other value (typically null) for regular palace rooms.
connections	Four-byte hexadecimal string describing the room's exits. See Connections.
enemies	Hexadecimal-encoded enemy room data. Format to be documented elsewhere.
sideviewData	Hexadecimal-encoded sideview room data. Format to be documented elsewhere.
elevatorScreen	The page (0–3) containing the room's elevator, or -1 if the room has no elevator.
hasDrop	true if the room has a drop.
isDropZone	true if this room can be entered via a drop.
isEntrance	true if this room is a palace entrance.
hasItem	true if the room is an item room.
hasBoss	true if the room has a boss. This includes both the palace end bosses and passthrough bosses.
isBossRoom	true if this is the palace's end boss room, with the palace crystal (or Dark Link).
isThunderBirdRoom	true if this room contains Thunderbird.
requirements	Defines which abilities or items are required to traverse the room. See Requirements.
linkedRoomName	Only used for segmented rooms. See Segmented Rooms.
tags	A list of tags for the room to help with room pool selection. Examples: Expert, LongDeadEnd, WalkthroughWall

Vanilla / Legacy Properties

The following fields are used in vanilla or legacy room definitions and should generally not be changed when creating new rooms.

Property	Notes
bitmask	Represents which room bits are flagged at start. Leave this as 0F for new rooms unless you have a good reason.
map	Only used for vanilla rooms.
memoryAddress	Only used for vanilla rooms.
isUpDownReversed	Only used by a handful of vanilla rooms where the Up and Down connection bytes are reversed. Keep this false unless you have a specific compatibility reason to change it.

Connections

The connections field is a hexadecimal string representing four bytes indicating which room each of the 4 potential room exits goes to.

Example: A room with only a left exit. 00FCFCFC

As far as the Randomizer is concerned, each exit can only be ON (00) or OFF (FC). (You may encounter other values, but it's not important, read below for details)

Connections byte order

Each byte is multipurpose and may represent different things depending on the room layout. In general, a byte should only be used for one purpose within a room.

Byte	Possible Uses
Byte 0 ("Left")	The room to the left, or a drop on the first page.
Byte 1 ("Down")	If the room has an elevator going down: the room below. If the room is two pages long: the room to the right. A drop on the second page.
Byte 2 ("Up")	If the room has an elevator going up: the room above. If the room is three pages long: the room to the right. A drop on the third page.
Byte 3 ("Right")	If the room is four pages long: the room to the right. A drop on the fourth page.

Connections byte in detail

Any byte less than FC is considered ON - a room connection that must be possible to take (otherwise a generated palace might be uncompletable). The bytes FC-FF all mean an exit that is not possible to take.

If you're interested in the inner workings: Each room exit uses the high 6 bits xxxx xx.. to indicate an exit to that map number (0-62). The special case 1111 11.. (FC) exits outside the palace. The low 2 bits .... ..xx (0-3) respresent which page of the map you will enter using that exit.

Requirements

The requirements field defines what the player must have in order to logically traverse a room.

Requirement types are:

• JUMP
• FAIRY
• UPSTAB
• DOWNSTAB
• KEY
• DASH
• GLOVE
• REFLECT

Requirements use nested arrays to express logical OR and AND conditions.

No Requirements

"requirements": []

The room is always traversable.

OR Conditions

"requirements": [
  "GLOVE",
  "FAIRY"
]

Requires Glove OR Fairy.

AND Conditions

"requirements": [
  [
    "JUMP",
    "DASH"
  ]
]

Requires Jump AND Dash.

Combined Conditions

"requirements": [
  "FAIRY",
  [
    "DASH",
    "JUMP"
  ]
]

Requires Fairy OR Jump+Dash.

Segmented Rooms

Segmented rooms are composed of two separate rooms. In palace construction logic, the rooms are treated as two separate logical entities. The rooms are then merged together into a single room when it's written to the ROM.

To create a segmented room, define the room twice in the JSON file. The first room should be the logically more important room. If the room has an item, this must be in the first of the two rooms.

The two room definitions should otherwise be identical except for the following fields:

Property	First Room	Second Room
connections	Connection bytes for the first logical segment. While these will eventually be merged in the output ROM, it is very important to define the correct exits for palace generation.	Connection bytes for the second logical segment.
enabled	Must be true.	Must be false.
hasItem	Set to true if the room contains an item.	Must be false.
name	Name of the first room.	Name of the second room.
linkedRoomName	Exact name of the second room.	Exact name of the first room.
requirements	Logical requirements for traversing the first segment.	Logical requirements for traversing the second segment.

Example:

First room

For readability, it is recommended that name appear before linkedRoomName.

{
  "connections": "00FFFFFF",
  "enabled": true,
  "hasItem": false,
  "name": "Room A",
  "linkedRoomName": "Room B",
  "requirements": []
}

Second room

{
  "connections": "FFFF0000",
  "enabled": false,
  "hasItem": false,
  "name": "Room B",
  "linkedRoomName": "Room A",
  "requirements": []
}