Scenes and Rooms

Header Commands

The header commands are designed to define the bulk of the structure for Scene and Room files.

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 to 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 to that list. Follows the actors list format.	rooms	?
`0x02`	Cameras used by 0x1B command	`02xx0000 yyyyyyyy`	x is the number of entries y is the segment offset to that list. Follows camera entries format.	scenes	?
`0x03`	Defines the collision header	`03000000 yyyyyyyy`	y is the segment offset to 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 to the room list. Follows the rooms 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	?
`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 to that list. Follows the entrance list format.	scenes	No
`0x07`	Special objects	`07??0000 0000xxxx`	x is the object to use for the room, either gameplay_field_keep (object 0x0002) or gameplay_dangeon_keep (object 0x0003) _{Posted on z64 by xdaniel}	scenes	No?
`0x08`	Room behavior	`08xx0000 0000yyzz`	x affects Sun's Song, backflipping with A y environment related; y = 0x10 for snow flakes; y = 0x00 for nothing z affects Link's idle animation OR makes the room "Too Hot". See here.	rooms	?
`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 y is the segment offset to the object list. Follows the object list format.	rooms	?
`0x0C`	Lighting?	`0Cxx0000 yyyyyyyy`	x is the number of light? settings y is the segment offset to the list. Follows the lighting list format. _{Discovered by ChriisTiian}	scenes	Yes
`0x0D`	Pathways	`0D000000 yyyyyyyy`	y is the segment offset to 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 to that list. Follows the transition actors list format.	scenes	Yes
`0x0F`	Environment Settings	`0Fxx0000 yyyyyyyy`	x is the number of environment settings y is the segment offset to that list. Follows the environments list format.	scenes	?
`0x10`	Time settings	`10000000 xxyyzz00`	x = Time modifier 1 (0xFF = current game time). See time settings for calculation. y = Time modifier 2 (0xFF = current game time). z = time speed (signed), default 0x3.	rooms	?
`0x11`	Skybox settings	`11tt0000 xx0y0z00`	t = External Texture file. 0x00 = no external textures. 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 = Fog. 0 = minimal fog, 1+ = significant fog	scenes	?
`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 = Unknown, set to 01 in Z2_WITCH_SHOP_room_14.	rooms	?
`0x13`	Defines the exit list	`13000000 yyyyyyyy`	y is the segment offset to the exit list. Follows the exit list format.	scenes	?
`0x14`	End marker	`14000000 00000000`	Signals the end of the header	scenes, rooms	No
`0x15`	Sound settings	`15xx0000 0000yyzz`	x = reverb y = Nighttime SFX to play, 0x13 = always playing day background music z = Background sequence to play _{Nighttime SFX documented by Strati}	scenes	No
`0x16`	Sound settings	`16000000 000000xx`	x = echo	rooms	No
`0x17`	Cutscene List	`17xx0000 yyyyyyyy`	x = Number of cutscenes. y = segment offset to the cutscene data. Follows the Cutscene List format.	scenes	Yes
`0x18`	Alternate headers	`18000000 xxxxxxxx`	x = segment offset to alternate header list. Follows the alternate header list format.	scenes, rooms	Yes
`0x19`	World Map Location	`19000000 00000000`	Marks that a location has been visited on the world map and thus can be highlighted, based on the scene number. See world map for more information.	scenes	Yes
`0x1A`	Defines texture animations	`1A000000 xxxxxxxx`	x = segment offset to the entries. Follows the texture animation list format.	scenes	?
`0x1B`	Defines cameras and cutscenes used by actors	`1Bxx0000 yyyyyyyy`	x = Number of entries y = segment offset to the entries. Follows the 0x1B entries list format.	scenes	?
`0x1C`	Defines the mini maps	`1C000000 xxxxxxxx`	x = segment offset to mini map data. Follows the mini map format.	scenes	?
`0x1D`	Unused command	`1D000000 00000000`	Has two instructions saving values to the stack, which aren't read before being overwritten.	Unknown	Yes
`0x1E`	Defines the chest positions on the map	`1Exx0000 yyyyyyyy`	x = Number of entries y = segment offset to the entries. Follows map chests format.	scenes	?

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"
0x00	✔	Link Spawns
0x11	✔	Skybox Settings
0x13		Exit List
0x0F	✔	Lighting Settings
0x17		Cutscene List
0x1B	✔
0x02
0x1C	✔
0x1A	✔
0x1E

Rooms

Id	Required	Purpose
0x18		Alternate Headers
0x16	✔	Sound Settings
0x08	✔	Room Behavior
0x12	✔	Skybox Settings
0x10	✔	Time 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 that trigger when spawning on a specific entrance are referenced by code (possibly Ocarina of Time only). See Entrance Cutscenes
The Spirit Temple in Ocarina of Time has two unreferenced headers in every scene and room, due to the alternate scene header command being absent.
Hyrule Castle has an unreferenced scene header, but no matching room header

Actors List

The actor spawn record format is significantly more complex compared to the Ocarina of Time format:
aaaaxxxx yyyyzzzz ppppwwww rrrrvvvv (repeats for each actor)

Id	Bits	Purpose
a	`1xxx xxxx xxxx xxxx`	No Y Rotation
	`x1xx xxxx xxxx xxxx`	No X Rotation
	`xx1x xxxx xxxx xxxx`	No Z Rotation
	`xxxx 1111 1111 1111`	Actor Id
x		Position on x-axis
y		Position on y-axis
z		Position on z-axis
p	`1111 1111 1xxx xxxx`	Rotation around x-axis (1 = 1°)
p	`xxxx xxxx xxxx x111`	Spawn Time flags (high bits)
w	`1111 1111 1xxx xxxx`	Rotation around y-axis (1 = 1°)
w	`xxxx xxxx x111 1111`	0x1B scene command index (see below)
r	`1111 1111 1xxx xxxx`	Rotation around z-axis (1 = 1°)
r	`xxxx xxxx x111 1111`	Spawn Time flags (low bits)
v		Initialization variable sent to actor

Rotation

You can get the rotation value by shifting the p, w, and r values right by 7.

Rotation Flags

The rotation flags are stored in the actor ID.

a & 8000 - don't convert y rotation
a & 4000 - don't convert x rotation
a & 2000 - don't convert z rotation

If any of these bits are set:

check if rotation value is less than 0xB5
if greater than, add 0xFE98 to value.

If they aren't set:

multiply rotation value by 182.0444 (0x43360B61 float, or approximately 1 degree of rotation) and truncate

Several actors such as En_Box (0006) and En_Time_Tag (01AB) use these flags.

Spawn Time Flags

Spawn time flags work as such:

The entire set of spawn time flags is stored in the x and z rotations.

p & 0x0007 is stored into the "spawn time" var, then left shifted by 7. Bit mask is & 0380
r & 0x007F, then added to the "spawn time" var, giving us a complete mask of  & 03FF possible values.

& 03FF is broken down into 5 groups (for days 0-4) of 2 bits (for day/night).

To combine everything, if p = 0x07, and r = 0x5A...

0x07 << 7    = 0x0380
0x5A & 0x7F  =   0x5A
0x380 + 0x5A = 0x03DA

03DA -> 11 1101 1010

Thus this actor will always spawn on days 0 and 1, the night of day 2, the morning of day 3, and the morning of day 4.

0x1B Index

This tells the actor what 0x1B entry it should use, and is stored in the y rotation.

w & 007F
007F = null (?)
*Link needs to point to the entry that contains the camera for the ocarina (?)

Cameras

Entries
xxxxyyyy zzzzzzzz
x = Camera Type
y = Unknown
z = Offset of camera data

Camera Data
xxxxyyyy zzzzpppp qqqqrrrr vvvvssss FFFF
x = Position on x-axis
y = Position on y-axis
z = Position on z-axis
p = Rotation around x-axis
q = Rotation around y-axis
r = Rotation around z-axis
v = Field of View (in degrees)
s = Pan Speed (how fast the camera should translate/rotate)

Camera types:

00 NONE
01 NORMAL0
02 NORMAL3
03 CIRCLE5
04 HORSE0
05 ZORA0
06 PREREND0
07 PREREND1
08 DOORC
09 DEMO0
0A FREE0
0B FUKAN0
0C NORMAL1
0D NANAME
0E CIRCLE0
0F FIXED0
10 SPIRAL
11 DUNGEON0
12 ITEM0
13 ITEM1
14 ITEM2
15 ITEM3
16 NAVI
17 WARP0
18 DEATH
19 REBIRTH
1A TREASURE
1B TRANSFORM
1C ATTENTION
1D WARP1
1E DUNGEON1
1F FIXED1
20 FIXED2
21 MAZE
22 REMOTEBOMB
23 CIRCLE1
24 CIRCLE2
25 CIRCLE3
26 CIRCLE4
27 FIXED3
28 TOWER0
29 PARALLEL0
2A NORMALD
2B SUBJECTD
2C START0
2D START2
2E STOP0
2F JCRUISING
30 CLIMEMAZE
31 SIDED
32 DUNGEON2
33 BOSS_SHIGE
34 KEEPBACK
35 CIRCLE6
36 CIRCLE7
37 CHUBOSS
38 RFIXED1
39 TRESURE1
3A BOMBBASKET
3B CIRCLE8
3C FUKAN1
3D DUNGEON3
3E TELESCOPE
3F ROOM0
40 RCIRC0
41 CIRCLE9
42 ONTHEPOLE
43 INBUSH
44 BOSS_LAST
45 BOSS_INI
46 BOSS_HAK
47 BOSS_KON
48 CONNECT0
49 MORAY
4A NORMAL2
4B BOMBBOWL
4C CIRCLEa
4D WHIRLPOOL
4E KOKKOGAME
4F GIANT
50 SCENE0
51 ROOM1
52 WATER2
53 SOKONASI
54 FORCEKEEP
55 PARALLEL1
56 START1
57 ROOM2
58 NORMAL4
59 SHELL
5A DUNGEON4

Rooms List

Each room is two pointers, start and end, which game searches for in the file system.

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

Room Behavior

08xx0000 0000yyzz

x - Room Type

00 - ROOM_TYPE_FIELD - No effect/restrictions
01 - ROOM_TYPE_DANGEON - Spawns actor 015A (En_Test4)
02 - ROOM_TYPE_ROOM - Disables jumping through the action button.
03 - ROOM_TYPE_ROOM2 - [?]
04 - ROOM_TYPE_TOWN - Unknown (Used in some overworld areas)
05 - ROOM_TYPE_BOSS - Spawns actor 015A (En_Test4) (Used only in boss rooms)

y

10 - Enables raining on Day 2

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

00 - ROOM_WEATHER_NORMAL - Link tends to stand in place and glance back at the player
01 - ROOM_WEATHER_COLD - Link's cold sneeze
02 - ROOM_WEATHER_HOT - Link wipes his head
03 - ROOM_WEATHER_HEAVY_HOT - Triggers the Heat timer! Camera seems to move in and out rapidly, and ever so slightly for the "heat" effect
04 - ROOM_WEATHER_WARM - Link stretches and yawns?
05 - ROOM_WEATHER_MILD - [?]
06 - ROOM_WEATHER_COOL - [?]
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

Format:
ttcc0000 ssssssss eeeeeeee
Where:
t = type (see below)
c = number of entries
s = start of the entries
e = end of the entries

Mesh type 0

Simple mesh format; render all display lists specified. 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.

Mesh type 1

This format uses the header slightly differently. e is not the end of the entries, but the ROM address of the JFIF image within the room. Following e are 0x14 unknown bytes, perhaps bounds of some sort. At the offset given by s are the display lists, in the same format as mesh type 0.

Mesh type 2

Mesh that clips if the player is not within certain bounds. Format:
aaaabbbb ccccdddd xxxxxxxx yyyyyyyy (repeats for each entry)
Where:
a and b = X and Z maximum player coordinates to render first display list from,
c and d = X and Z minimum player coordinates to render first display list from,
x = first (close) display list. Set to 0 if unused.
y = second (far) display list. Set to 0 if unused.

Object List

Each entry is a two-byte entry of the object number, of the game's object list. Objects are required to load any actors that are not object 1 or object 2 (if the area is not a dungeon) or object 3 (if the area is a dungeon).

Lighting List

tt00 xxxx xxxx xxxx xxxx xxxx xxxx
Where tt = lighting 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 = noth-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 xx00 yy00 zz00 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 a list of:
aa000000 llllllll (repeats for each path)
Where:
a is the number of points for the given path, and
l is the location of the first point of the path
The path pointer list at offset l has a entries, each consisting of:
xxxx yyyy zzzz (repeats for each point of path)
x, y, and z are the (signed) coordinates of the specific point on the path.

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.

Environments list

aaaaaa bbbbbb cccccc dddddd eeeeee ffffff gggg hhhh (repeats for each environment type)
Where:
a = Ambient light color, RRGGBB format. Usually 0x462D39
b = First diffuse light color [illumination of Link from upside], RRGGBB format. Usually 0x494949
c = First diffuse light direction XXYYZZ format. Usually 0xB49A8A
d = Second diffuse light color [illumination of Link from downside], RRGGBB format. Usually 0xB7B7B7.
e = Second diffuse light direction, XXYYZZ format. Usually 0x14143C
f = Fog color, RRGGBB format
g & 0x3FF = Fog start
h = Draw distance

Time Settings

If either modifier is set to 0xFF then the calculation will not be used and the current time will be used instead. Both time modifiers are converted to floating point then are used to calculate a result which is then truncated and cast back to a 16 bit integer. The calculation is as follows.

 // 10000000 xxyyzz00
 (((yy.0 / 60.0) + xx.0) * 60) / 0.0219727 = time

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.

Cutscene List

Cutscene Entries

xxxxxxxx yyyyuutt
x = Segment Address pointing to cutscene data
y = Exit
u = Entrance cutscene activates at
t = Event flag

There needs to be an actor cutscene set to play the cutscene for it to trigger on an entrance.

y &>> 0xFE00 = external scene index
y &>> 0x01F0 = external scene pointer array index
y & 0x000F = external scene record array index and scene setup

Alternate Header List

Each entry is a segment offset pointing to a scene header for the current scene/room. The number of alternate headers is undefined.

Texture Animations

Entries
xx00yyyy zzzzzzzz
x = Segment ID? (Add 7?)
y = Type

 00 = One layer
 01 = Two layers

z = Offset of layer data

Layers
aabbccdd
a = X velocity factor
b = Y velocity factor
c = X size - use 0x20 for 32x
d = Y size - use 0x20 for 32x

Actor Cutscenes

Actor cutscenes are the little mini cutscenes that are triggered by actors, such as pressing or hitting a switch causing the camera to pan and look at a chest that is spawning for example.

Format:
uuuullll ccccdddd aaaassuu hhhhrrbb (repeats for each actor cutscene)

u = u16 Unknown
l = s16 Length of the cutscene (in frames) (FFFF = constantly playing)
c = s16 Camera index

FFE9 = Swamp Boat ride?

FFF0 = Entering warp after defeating boss

FFF5 = Mask Transformation

FFF6 = Opening a large chest

FFF7 = Spin up out of Ground (Only used in Goht Trial for the rainbow reset pads)

FFF8 = Death

FFF9 = Spin down into Ground (Only used in Goht Trial for the rainbow reset pads)

FFFA = Song of Soaring

FFFB = Hold item up (one hand) (Can't use item, caught bottle item, etc)

FFFC = Use bottle item

FFFD = Playing ocarina

FFFE = Hold item up (both hands) (Open small chest, get new item, etc)

FFFF = Null

0000+= Additional cameras (see 0x02 command)

d = s16 Cutscene index (see 0x17 command)

FFFF = Null

a = s16 Additional actor cutscene index. This tells it to use another actor cutscene by index.
s = u8 Sound

00 = No sound

01 = Puzzle complete sound

u = u8 Chest Cutscene

Used in the chest (En_Box) actor.

FF = Set actor cutscene as csId1. This should be the actor cutscene used for when the chest appears.

01 = Set actor cutscene as csId2. This should be on the Open large chest (FFF6) actor cutscene entry.

h = s16 HUD Fade

0000 = Fade out

0001 = Nothing?

0002 = Keep A button on screen

r = u8 Return Camera Type

00 = Keep current position

01 = Place behind link

02 = Rotate until behind link

b = u8 Letterbox. Sets the size of the blackbars on the top and bottom of the screen.

Mini Maps

Data
xxxxxxxx yyyyzzzz
x = Offset of mini map entries
y = Zoom
z = Unknown

Mini Map Entries
aaaaxxxx yyyyzzzz bbbb
a = Mini Map
x = Position on x-axis
y = Position on y-axis
z = Position on z-axis
b = Unknown

Map Chests

aaaabbbb xxxxyyyy zzzz

a = Minimap Index
b = Scene Flag
x = Position on x-axis
y = Position on y-axis
z = Position on z-axis

World Map

The following notes are for J 1.0

At 801BD040 ram/00C749A0 rom is a table of 0xB records representing 11 different world map locations. Each record contains an 0x36 byte array of two-byte "internal" scene indexes (for a total of 26 scenes + terminator). To determine if Link is visiting a world location, each array is scanned for the current internal scene index. If -1 is encountered in an array, the next location array is checked.

If a world map location is found, a flag is written to Save Context + 0x0F5C, otherwise nothing happens.

Credits

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

Contents