From CloudModding OoT Wiki
(Redirected from 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