Scenes and Rooms

From CloudModding MM Wiki
Jump to: navigation, search

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 is unknown
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 xxxxyy00 x = start time (0xFFFF = current game time)
y = time speed (signed), default 0x3.
rooms  ?
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 = 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 track
z = track to play
Nighttime SFX documented by Strati
scenes No
0x16 Sound settings 16000000 000000xx x = echo rooms No
0x17 Cutscenes 17xx0000 yyyyyyyy x = Number of cutscenes. y = segment offset to the cutscene data. Follows the MM cutscene 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  ?

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°)
xxxx xxxx xxxx x111 Spawn Time flags (high bits)
w 1111 1111 1xxx xxxx Rotation around y-axis (1 = 1°)
xxxx xxxx x111 1111 0x1B scene command index (see below)
r 1111 1111 1xxx xxxx Rotation around z-axis (1 = 1°)
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 aaaaFFFF 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
a = Unknown

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

00 - No effect/restrictions
01 - Spawns actor 015A (En_Test4)
02 - Disables jumping through the action button.
05 - Spawns actor 015A (En_Test4) (Used only in boss rooms)

y - Unknown. 01 in Shadow Temple rooms 0, 2, 00 in room 1

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

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

Scene actors change the room that is loaded.  They usually 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)
Where:
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 = actor variable

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

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.

Cutscenes

For more information, see Cutscenes.

Cutscene Entries

xxxxxxxx yyyyuutt
xx = Offset of cutscene data
yy = Exit
uu = Entrance cutscene activates at
tt = Event flag

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 = unknown - use 0x20 if unsure
d = unknown - use 0x20 if unsure

0x1B

uuuutttt bbbbcccc nnnnssuu uuuuddee
t = Length (FFFF = constantly playing)
b = Camera to use

FFF0 = Entering warp after defeating boss
FFF5 = Mask Transformation
FFF6 = Opening a large chest
FFF7 = ???
FFF8 = ???
FFF9 = ???
FFFA = Song of Soaring
FFFB = Using event item
FFFC = Drinking bottle
FFFD = Playing ocarina
FFFE = Opening a small chest
FFFF = Null
0000+= Additional cameras (see 0x02 command)

c = Cutscene to play (FFFF = No cutscene)
n = Next entry?
s = Puzzle sound to play
d = Camera postion after

00 = Keep current position
01 = Place behind link
02 = Rotate until behind link

e = Size of black bars (80 = Max)
u = Unknown

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