Scenes and Rooms

Header Commands

The header commands are designed to define the bulk of the structure for Scene and Room files. All commands follow the following 8 byte structure:

struct {
    u8  code;
    u8  data1;
    s32 data2;
}

Command	Description	Variables	Usage	Found in	Optional
0x00	Defines the start positions list	00xx0000 yyyyyyyy	x is the number of start positons y is the segment offset of that list. Follows the actors list format.	scenes	No
0x01	Defines the actor list	01xx0000 yyyyyyyy	x is the number of actors y is the segment offset of that list. Follows the actors list format.	rooms	Yes
0x02	Cameras used by 0x1B command (MM only)	02xx0000 yyyyyyyy	x is the number of entries, y is the segment offset of the entries. Follows the camera entries format	scenes	Yes
0x03	Defines the collision header	03000000 yyyyyyyy	y is the segment offset of the collision header. Follows the collision format.	scenes	No
0x04	Defines the rooms	04xx0000 yyyyyyyy	x is the number of rooms y is the segment offset of the room list. Follows the room list format.	scenes	No
0x05	Sets the wind (red cloth posts, rain)	05000000 wwzzssff	ww will push the wind westward zz affects the wind vertically ss pushes the wind south ff alters the strength of the cloth flapping Documented by Strati and mzxrules	rooms	Yes
0x06	Defines the entrance list	06000000 yyyyyyyy	The number of entrances is undefined, though it is usually equal to the number of start positions (see below) (that the entrance table accesses) y is the segment offset of that list. Follows the entrance list format.	scenes	No
0x07	Special objects	07xx0000 0000yyyy	x loads an elf_message file, which determines how the C-Up Navi icon hints work. 00 for no data, 01 for elf_message_field, 02 for elf_message_ydan. y loads a global object file, assigning it to segment offset 05. 0x0000 for no object, 0x0002 for gameplay_field_keep, or 0x0003 for gameplay_dangeon_keep Posted on z64 by xdaniel	scenes	No
0x08	Room behavior	08xx0000 0000yyzz	x affects Sun's Song, backflipping with A y &>> 4 = Disable Warp Songs y & 1 = Show/Hide invisible actors z affects Link's idle animation OR makes the room "Too Hot". See here. Invisible Actors documented by ChriisTiian	rooms	No
0x09	Unused command	09000000 00000000	Has two instructions saving values to the stack, which aren't read before being overwritten. Documented by Strati	rooms (Depth Test)	Yes
0x0A	Defines the mesh	0A000000 yyyyyyyy	y is the segment offset of the mesh header. Follows the mesh header format.	rooms	No
0x0B	Defines the object list	0Bxx0000 yyyyyyyy	x is the number of objects (maximum 15) y is the segment offset of the object list. Follows the object list format.	rooms	Yes
0x0C	Unused Lighting settings	0Cxx0000 yyyyyyyy	x is the number of unused Lighting settings y is the segment offset of the list. Follows the unused lighting list format. Discovered by ChriisTiian	rooms (Unused)	Yes
0x0D	Pathways	0D000000 yyyyyyyy	y is the segment offset of the path list. Follows the path list format. Documented by xdaniel	scenes	Yes
0x0E	Defines the transition actor list	0Exx0000 yyyyyyyy	x is the number of transition actors y is the segment offset of that list. Follows the transition actors list format.	scenes	Yes
0x0F	Defines the lighting settings	0Fxx0000 yyyyyyyy	x is the number of lighting settings y is the segment offset of that list. Follows the lighting list format.	scenes	No
0x10	Time settings	10000000 xxxxyy00	x = Sets time to a specific value. 0xFFFF = No change y = Time speed (signed), default 0xA.	rooms	No
0x11	Skybox settings	11000000 xx0y0z00	x = Skybox number (see the skybox list) y = Cast. 0 = Sunny, 1 = Cloudy. Affects the sun's lens flare, and skybox 1 will load sky/clouds z = Lighting Settings Control. 0 = Controlled by Day Time, 1 = "Indoor" lighting	scenes	No
0x12	Skybox modifier	12000000 xxyy0000	Allows skyboxes to be enabled in some rooms of a scene but disabled in others. x = disable sky if not 0 (some backgrounds still appear) y = disable sun/moon if not 0 Sun/Moon disabler documented by ChriisTiian	rooms	No
0x13	Defines the exit list	13000000 yyyyyyyy	y is the segment offset of the exit list. Follows the exit list format.	scenes	Yes
0x14	End marker	14000000 00000000	Signals the end of the header	scenes, rooms	No
0x15	Sound settings	15xx0000 0000yyzz	x = Settings config, max value 0x11. See Sound Settings y = Nighttime SFX to play, 0x13 = always playing day sequence z = Music sequence to play, 0x7F = always playing Nighttime SFX Nighttime SFX documented by Strati	scenes	No
0x16	Sound settings	16000000 000000xx	x = echo	rooms	No
0x17	Cutscenes	17000000 xxxxxxxx	x = segment offset of cutscene data. Follows the cutscene data format.	scenes	Yes
0x18	Alternate headers	18000000 xxxxxxxx	x = segment offset of alternate header list. Follows the alternate header list format.	scenes, rooms	Yes
0x19	Camera Settings and World Map	19xx0000 000000yy	x = Affects camera movement y = Sets what location of the world map to highlight. See camera settings	scenes	Yes
Commands beyond 0x19 are used in Majora's Mask only.

Command Ordering

Scenes

Id	Required	Purpose
0x18		Alternate Headers
0x15	✔	Sound Settings
0x04	✔	Rooms
0x0E		Transition Actors
0x19		Camera Settings and World Map
0x03	✔	Collision Header
0x06	✔	Entrance List
0x07	✔	"Special Objects"
0x0D		Pathways
0x00	✔	Link Spawns
0x11	✔	Skybox Settings
0x13		Exit List
0x0F	✔	Lighting Settings
0x17		Cutscenes

Rooms

Id	Required	Purpose
0x18		Alternate Headers
0x16	✔	Sound Settings
0x08	✔	Room Behavior
0x12	✔	Skybox Settings
0x10	✔	Time Settings
0x05		Wind Settings
0x0A	✔	Room Mesh
0x0B		Object List
0x01		Actor List

Unreferenced Assets

Some assets stored within scene and room files are only referenced by external files, or not at all.

• Textures that are used by multiple rooms are typically stored in the scene file to save space.
• Cutscenes:
  • Entrance cutscenes, triggered when spawning using a specific entrance (referenced by code, possibly Ocarina of Time only).
  • Some actors (Sheik in the Ice Cavern, Saria in Sacred Forest Meadow) trigger cutscenes stored within the scene setup, rather than internally.
• Extra scene/room headers not referenced by the 0x18 command:
  • The Spirit Temple in Ocarina of Time has two unreferenced headers in every scene and room.
  • Hyrule Castle has an unreferenced scene header, but no matching room header
  • Death Mountain Trail
  • Cutscene Map

Actors List

aaaaxxxx yyyyzzzz ppppwwww rrrrvvvv (repeats for each actor)
Where:
a = Actor number
x = Position on x-axis
y = Position on y-axis
z = Position on z-axis
p = Rotation around x-axis
w = Rotation around y-axis
r = Rotation around z-axis
v = initialization variable sent to actor

For more info on initializing OoT actors, see Actor List (Variables)

Rooms List

Each room is two pointers, start and end, which game searches for in the file system. A maximum of 32 rooms can exist per scene without encountering potential issues.

Format:
ssssssss eeeeeeee (repeats for each room)
Where:
s = Room virtual address start.
e = Room virtual address end.

Room Behavior

08xx0000 0000yyzz

x

00 - No effect/restrictions
01 - Prevents the Sun's Song time effect.
02 - Disables jumping through the action button.
05 - ??? (Used only in boss rooms)

y - Show / Hides invisible actors (like Floormasters, Fake Walls, etc).

00 - Hide
01 - Show

z - Sets extra idle animation OR makes the room too hot without the Goron Tunic

00 - Link tends to stand in place and glance back at the player
01 - Link's cold sneeze
02 - Link wipes his head
03 - Triggers the Heat timer! Camera seems to move in and out rapidly, and ever so slightly for the "heat" effect
04 - Link stretches and yawns?
06 - ?
07 - Bends over and gasps for breath
09 - Brandishes sword even if not equipped
0A - Re-adjusts his tunic?
 
FF - Link hops on Epona (even as a child)

Entrance List

Contains a list of start position and room pairs. Indexed based off of the entrance called by the entrance table.

Format:
pprr (repeats for each entry)
Where:
p = Which start position to use, defined by the start positions list (command 0x00) for the scene
r = Which room to load for this entrance

Mesh Header

The first byte in the mesh header determines the "type" of mesh information is stored. There are 3 different types of meshes.

Type 0

Simple mesh format; renders all display lists specified.

Header Format

00cc0000 ssssssss eeeeeeee
Where:
c = number of entries
s = start of display list entries
e = end of display list entries

Entry Format

xxxxxxxx yyyyyyyy (repeats for each entry)
Where:
x = display list with opaque geometry. Set to 0 if unused.
y = display list with translucent geometry. Set to 0 if unused.

Type 1

This format is used with certain pre-rendered areas, specifically to render a static background image rather than the panoramas. Notably, the JFIF image is rendered via the S2DEX microcode, rather than the primary rendering microcode (F3DZEX2). The JFIF is drawn using S2DEX's gsSPBgRectCopy (0x0A) macro.

Header Format

See JFIF for more information on the background image format.

Common Format

/* 0x00 */ s8 header_type = 0x01; 
/* 0x01 */ s8 format; // 01 = Single static background, 02 = Multi-static background
/* 0x04 */ u32 *entryRecord; //pointer to entry record that references display lists to draw

Beyond this, the format differs a bit between single and multi backgrounds.

(01) Single Format

// Below is start of data used to initialize a uObjBg (uObjBg_t)
/* 0x08 */ u32 *imagePtr; //pointer/segment address to JFIF background image displayed when viewing from a top-down vantage 
/* 0x0C */ u32 unknown; //value never read?

/* 0x10 */ s32 unknown2; //value never read?
/* 0x14 */ u16 background_width; //typically 320px
/* 0x16 */ u16 background_height; //typically 240px
/* 0x18 */ u8 imageFmt; 
/* 0x19 */ u8 imageSiz;
/* 0x1A */ u16 imagePal;
/* 0x1C */ u16 imageFlip;

(02) Multi Format

/* 0x08 */ u8 background_count; //number of pre-rendered backgrounds stored
/* 0x0C */ BackgroundRecord *background_record; //segment address pointing to the start of the BackgroundRecord array (defined below)

struct
{
/* 0x00 */ u16 unknown_0x0082; //unknown, contains value of 0x0082
/* 0x02 */ s8 backgroundId; //used to give a BackgroundRecord an identifier

// Below is start of data used to initialize a uObjBg (uObjBg_t)
/* 0x04 */ u64 *imagePtr; //pointer/segment address to JFIF background image displayed when viewing from a top-down vantage 
/* 0x08 */ u32 unknown; //value never read?
/* 0x0C */ s32 unknown2; //value never read?
/* 0x10 */ u16 background_width; //typically 320px
/* 0x12 */ u16 background_height; //typically 240px
/* 0x14 */ u8 imageFmt; 
/* 0x15 */ u8 imageSiz;
/* 0x16 */ u16 imagePal;
/* 0x18 */ u16 imageFlip;
} BackgroundRecord; //size 0x1C

Entry Format

xxxxxxxx yyyyyyyy (repeats for each entry)
Where:
x = display list with opaque geometry. Set to 0 if unused.
y = display list with translucent geometry. Set to 0 if unused.

Type 2

Mesh that culls if the camera behind a set point by a certain distance.

Header Format

02cc0000 ssssssss eeeeeeee
Where:
c = number of entries
s = start of display list entries
e = end of display list entries

Entry Format

aaaabbbb ccccdddd xxxxxxxx yyyyyyyy (repeats for each entry)
Where:
a = X coordinate
b = Y coordinate
c = Z coordinate
d = distance from camera to start culling
x = display list with opaque geometry. Set to 0 if unused.
y = display list with translucent geometry. Set to 0 if unused.

Object List

Each entry is a two-byte value representing an index value into the object file table. Objects are graphical dependencies required to load any actors. You should not load the following object files with this command:

Object Id	Filename	Reason
0000	N/A	Not actually a reference to any object file
0001	gameplay_keep	Always loaded by the game engine
0002	gameplay_field_keep	Load using the 0x07 command. Used in "overworld" scenes
0003	gameplay_dangeon_keep	Load using the 0x07 command. Used in "dungeon" scenes
0014	object_link_boy	Loaded when Link is an Adult
0015	object_link_child	Loaded when Link is a Child

A maximum of 15 objects can be defined on the object list. The combined file size of all object files loaded at one time (including the ones listed above) typically cannot exceed 0xFA000 bytes without writing a hack to expand the reserved space. See Objects for more information on this.

If a scene has connected rooms, care must be taken when choosing what order to list object files. When travelling from one room to the next, the game will compare the objects that were loaded by the first room to the objects requested from the second, starting with the first object number in each list. When the game encounters a number that does not match, then all object files after the last match will be unloaded, causing any actors dependent on those object files to unload as well, even if the second room contains the correct object number later on in the list.

Unused Lighting list

tt00 xxxx xxxx xxxx xxxx xxxx xxxx
Where tt = Light type:
00 - Nothing
01 - Light coming from outside of the room
02 - Punctual light source

Type 01

Format:
0100 uu00 vvcc cccc 0000 0000 0000
Where:
u = North/South direction the light is coming from (00 = no light from noth or south, 01-7E = light from north, 7F-FF light from south)
v = East/West direction the light is coming from (00 = no light from east or west, 01-7E = light from east, 7F-FF light from west)
c = RGB color of the light

Type 02

Format:
0200 xxxx yyyy zzzz cccc cc00 rr00
Where:
x = Position on x-axis of the light source
y = Position on y-axis of the light source
z = Position on z-axis of the light source
c = RGB color of the light
r = radius of the emitted light

Path List

Actors which have a "route" to follow, such as the carpenters or the graveyard boy, do not have the route hard-coded within them. Instead, the points which they make straight lines to are mapped out in a list. That is, a point is marked at every turning point, and they follow straight lines between the turning points.

The data pointed to by the scene header is an array of the following struct:

/* 0x00 */ s8 numPoints; //number of points for the given path
/* 0x04 */ SegmentAddress pathStart; //location of first point of the path
//size 0x08 bytes

Each point is a signed 16 bit x, y, z component, as seen below:

/* 0x00 */ s16 x;
/* 0x02 */ s16 y;
/* 0x04 */ s16 z;
//size 0x06 bytes

xdaniel figured this out while working on SayakaGL, and the information was verified by spinout by reversal of a function which reads the data. (Graveyard boy @ func_809E1E90) (SayakaGL Implementation)

Transition Actors

Transition actors are scene level actors that swap the room that is loaded. A maximum of 64 transition actors can exist per scene. Transition actors don't have their own collision, it must be part of the collision specified by the collision command in the scene header.

Format:
ffmmbbnn aaaaxxxx yyyyzzzz wwwwvvvv (repeats for each transition actor)

f = Room to switch to when triggered from the front of the object (for doors, the front has the knob on the right)
m = How the camera reacts during the front transition (effects depend on actor, best to experiment; recommended are 0, 0F, and FF)
b = Room to switch to when triggered from the back of the object
n = How the camera reacts during the back transition
a = Actor Number
x = Position along x-axis
y = Position along y-axis
z = Position along z-axis
w = Y rotation
v = Initialization variable

Check out the transition actor page for a list of all transition actors.

Lighting List

aaaaaabb bbbbcccc ccdddddd eeeeeeff
ffffgggg hhhh

Where:

• a = Ambient light color, RRGGBB format. Usually 0x462D39
• b = First light direction XXYYZZ format. Usually 0xB49A8A
• c = First light color, RRGGBB format. Usually 0x494949
• d = Second light direction, XXYYZZ format. Usually 0x14143C
• e = Second light color, RRGGBB format. Usually 0xB7B7B7
• f = Fog color, RRGGBB format
• g & 0xFC00 = Blend rate between light settings
• g & 0x03FF = Fog near, how close fog starts
• h = Fog far, how far until fog saturates

Exit List

Each entry is a two-byte exit number, from the game's entrance table (for index values, click here). The length of the list is undefined, the engine assumes all indexes within the list which it asks for exist.

Check out the collision format for more information about exits.

Sound Settings

The data1 byte of the sound settings command eventually sets Audio Ctx + 0x3519 (NTSC 1.0). This is used to index a 0x38 byte struct located at 80104778 (NTSC 1.0)

struct struct_104778
{
    s32     unk_0x00; //range u16
    u8      unk_0x05;
    u8      unk_0x06;
    u16     unk_0x10;
    u16     unk_0x12;
    s32     unk_0x18; //size of ?
    s32     unk_0x1C; //size of ?
    s32     unk_0x20; //size of ?
    s32     unk_0x24; //size of ?
    s32     unk_0x28; //size of ?
    s32     unk_0x2C; //size of ?
} //size 0x38

Alternate Header List

The alternate header list defines scene or room to have multiple loadouts, called scene setups.

Each entry in the alternate header list contains a segment offset reference to an alternate header for the current scene/room, or a null offset. Alternate headers have the same format as a normal scene header. The number of alternate headers is undefined, but there must be a minimum of three alternate header records, one for all four combination of day/night child/adult when you add in the main header.

The scene setup number set when spawning into the scene determines which loadout will be used.

• If the alternate header list command is absent, or the scene setup number is 0, the "main" header defined after the alternate header list is used.
• If the scene setup number is 1+, the setup number is subtracted by 1, and the entry at that index is loaded. In other words, scene setup 1 loads alternate header 0
• If the scene setup number is between 1-3 but the alternate header entry is null, the game will scan toward the lower setup number to find a valid scene setup.
• If the scene setup number is 4+, but the alternate header entry is null, the game will crash.

For example:

Index	Alternate Headers
0	00000000
1	02001458
2	00000000

Scene setup numbers 0 and 1 will use the "main" header. Scene setup numbers 2 and 3 will use alternate header 1.

Camera Settings

19xx0000 000000yy

x sets restrictions on both camera movement and c-up camera usage. For more details on skybox camera attributes, see collision camera data.

Value	Where It's Used
00	Scenes without pre-rendered environments that have free C-Up camera control.
10	Shop scenes which have a fixed camera that switches between two views, and lack a C-Up option.
20	Scenes which have pre-rendered backgrounds that can rotate, in which pressing C-Up gives you a bird's eye view.
30	Scenes which have pre-rendered backgrounds that are fixed, and lack a C-Up option.
40	Scenes which have pre-rendered backgrounds that rotate, and lack a C-Up option.
50	The Shooting Gallery.

y sets the scene's location on the world map. The Grotto/Great Fairy Fountain setting might be ignored.

Value	Location
00	Spot 00 - Hyrule Field / Not Applicable
01	Spot 01 - Kakariko Village
02	Spot 02 - Graveyard
03	Spot 03 - Zora's River
04	Spot 04 - Kokiri Forest
05	Spot 05 - Sacred Forest Meadow
06	Spot 06 - Lake Hylia
07	Spot 07 - Zora's Domain
08	Spot 08 - Zora's Fountain
09	Spot 09 - Gerudo Valley
0A	Spot 10 - Lost Woods
0B	Spot 11 - Desert Colossus
0C	Spot 12 - Gerudo's Fortress
0D	Spot 13 - Haunted Wasteland
0E	Market
0F	Spot 15 - Hyrule Castle
10	Spot 16 - Death Mountain Trail
11	Spot 17 - Death Mountain Crater
12	Spot 18 - Goron City
13	Spot 20 - Lon Lon Ranch
14	Dampe's Grave & Windmill
15	Ganon's Castle
16	Grottos & Fairy Fountains

Credits

spinout, jsa, cendamos, MNGoldenEagle, xdaniel, fkualol probably others