---===[ SM64DS LEVEL FORMAT DOC ]===---

By Mega-Mario

Last updated: 2017/06/10

---===[ WHERE TO FIND THE DATA ]===---

In a clean ROM, the level data is found in overlays 8 to 59 (one overlay per
level).
However, that level data has no unified structure, and is all surrounded with code
and
data relating to certain objects, so it is a pain to modify without breaking the
game.

SM64DSe, since version 1.1, creates new overlays (typically overlays 103 to 154),
and moves
each level's data in its new overlay, restructuring it in a more unified structure.
The new
overlays are also programmed to load the old overlays they are replacing, so that
objects
relying on the old overlays still work.

---===[ LEVEL HEADERS ]===---

Level header as generated by SM64DSe v2.3.2 (patch version 4).

Offset Size Desc

00 84 Overlay initializer/deinitializer code
54 1 Object bank 0 setting
55 1 Object bank 1 setting
56 1 Object bank 2 setting
57 1 Object bank 3 setting
58 1 Object bank 4 setting
59 1 Object bank 5 setting
5A 1 Object bank 6 setting
5B 1 Zero (Padding)
5C 4 Object bank 7 setting
60 4 Address of the CLPS chunk
64 4 Address of the 'misc' objects table
68 2 Internal file ID of the level model (.bmd)
6A 2 Internal file ID of the level collision map (.kcl)
6C 2 Internal file ID of the minimap tileset (.icg)
6E 2 Internal file ID of the minimap palette (.icl)
70 4 Address of the level area data
74 1 Number of level areas
75 1 Zero - start with normal camera, 1 start the level with 'far' camera
76 2 Scale factor for minimap coordinates
78 1 bit0-3: ??? (always 0xF),
bit4-7: sky/background (0=none, or 1-11)
79 3 Zero (?)
7C 3 Music data (byte 1: (SWAR entry address - 4) / 4, byte 2: SBNK ID, byte 3:
SSEQ ID (0- index)
7F 1 bit0-3: level format version, 0: original, 1: fix missing texture animation
translations
bit4-7: overlay de/initialiser version, 0: original, 1: support for "dynamic
overlays" (EUR only)
80 20 Reserved for future use
94 ... Level data

This header is generated by SM64DSe's patching, and isn't found under this form in
the original game data.
However, the block from 0x60 to 0x7C (28 bytes) can be found in a similar format in
the original level overlays,
but at varying offsets. The block from 0x54 to 0x5B (7 bytes) is originally
hardcoded in the game binary.
The dword at 0x5C isn't an original feature of the game engine-- it is made
possible by the new level format only.
The level music data was previously stored in a 156 byte table consisting of 52 3-
byte entries. Since version 2.1x,
music data has been moved to within the individual overlays.
All the data past 0x94 is copied from the original level overlays.

---===[ CLPS DATA ]===---

This stores a list of the collision types available in the current level. These
entries are referenced by the
level's collision map - each face has a collision type which acts as an index into
the CLPS table.

Header: 8 bytes

Offset Size Desc

00 4 String "CLPS"
04 2 Unknown, 0x08
06 2 Number of entries

Data:

Each entry is 8 bytes long. Number determined by CLPS header[0x06].

Offset Size Desc

00 1 Sound effect (?)
01 1 Camera behaviour (?)
02 1 Collision behaviour
03 1 Unknown
04 1 Path ID (always?)
05 1 Unknown
06 1 Unknown
07 1 Unknown

---===[ LEVEL AREA DATA ]===---

Each entry is 12 bytes. Number determined by header[0x74].

Offset Size Desc

00 4 Address of the objects table (NULL = no table)
04 4 Address of the texture animation data (NULL = no data)
08 1 Minimap tilemap index
09 3 ???

The objects table uses the same format as the one header[0x64] points to.
Except it typically only contains objects of type 0 and 5. The other object
types are contained by the header[0x64] table.

---===[ OBJECT TABLES ]===---

First part: 8 bytes

Offset Size Desc

00 4 Number of entries in table
04 4 Address of the object table

Object table: 8 bytes per entry

Offset Size Desc
00 1 Bit0-4: object type; Bit5-7: layer (0=all stars, 1-7=star 1..7)
01 1 Number of objects
02 2 Zero (?)
04 4 Address of the object list

Valid object types:

* 0: level objects, standard format (16 bytes per object)
* 1: level entrances (16 bytes per object)
* 2: path nodes (6 bytes per object)
* 3: paths (6 bytes per object)
* 4: views/camera anchors (14 bytes per object)
* 5: level objects, simple format (8 bytes per object)
* 6: teleport source points (8 bytes per object)
* 7: teleport dest. points (8 bytes per object)
* 8: fog (8 bytes per object)
* 9: doors/inter-area warps (12 bytes per object)
* 10: level exits (14 bytes per object)
* 11: minimap tilemap file IDs (2 bytes per object)
* 12: minimap scale (2 bytes per object)
* 14: unknown (4 bytes per object)

---===[ OBJECT TYPE 0: LEVEL OBJECTS (STANDARD) ]===---

16 bytes per object.

Offset Size Desc

00 2 Object ID
02 2 X position (divide by 1000 to obtain 3D coordinate)
04 2 Y position
06 2 Z position
08 2 Object-specific parameter (2)
0A 2 Y rotation (0x0400 = 90�)
0C 2 Object-specific parameter (3)
0E 2 Object-specific parameter (1)

The first two object-specific parameters (2 and 3 in SM64DSe) should be X and Z

rotation, respectively.
However, most objects ignore them. A few objects use them as X/Z rotation, and some
other objects use it for other purposes.

---===[ OBJECT TYPE 1: ENTRANCES ]===---

16 bytes per object.

Offset Size Desc

00 2 Must be zero (?)
02 2 X position
04 2 Y position
06 2 Z position
08 2 Parameter (?)
0A 2 Y rotation
0C 2 Parameter (?)
0E 2 Parameter (meaning=idk; weird)

---===[ OBJECT TYPE 2: PATH NODES ]===---

6 bytes per object.

Offset Size Desc

00 2 X position
02 2 Y position
04 2 Z position

---===[ OBJECT TYPE 3: PATHS ]===---

6 bytes per object. Path ID set in 0xF in supported objects.

Offset Size Desc

00 2 Start Node Index
02 1 Number of Nodes
03 1 Parameter (? always 255)
04 1 Parameter (? inheritance?)
05 1 Parameter (? always either 255 or 127)

---===[ OBJECT TYPE 4: VIEWS/CAMERA ANCHORS ]===---

14 bytes per object.

Offset Size Desc

00 2 Parameter (?)
02 2 X position
04 2 Y position
06 2 Z position
08 2 Parameter (?)
0A 2 Y Rotation
0C 2 Parameter (?)

---===[ OBJECT TYPE 5: LEVEL OBJECTS (SIMPLE) ]===---

8 bytes per object. This format is commonly used for objects like trees and coins,
that don't require extensive parameters.

Offset Size Desc

00 2 bit0-8: object ID; bit 9-15: object-specific parameter (1)
02 2 X position
04 2 Y position
06 2 Z position

---===[ OBJECT TYPE 6: TELEPORT SOURCE ]===---

8 bytes per object.

Offset Size Desc

00 2 X position
02 2 Y position
04 2 Z position
06 1 Parameter (?)
07 1 Destination index (0-) * 10

---===[ OBJECT TYPE 7: TELEPORT DESTINATION ]===---

8 bytes per object.

Offset Size Desc

00 2 X position
02 2 Y position
04 2 Z position
06 2 Parameter (?)

---===[ OBJECT TYPE 8: FOG ]===---

8 bytes per object. Adds fog to a level.

Offset Size Desc

00 1 Density (0 = None, 1 = Show fog)
01 1 Red Colour Component (0 - 255)
02 1 Green Colour Component (0 - 255)
03 1 Blue Colour Component (0 - 255)
04 2 Start distance
06 2 End distance

---===[ OBJECT TYPE 9: DOOR OBJECTS ]===---

12 bytes per object.

Offset Size Desc

00 2 X position
02 2 Y position
04 2 Z position
06 2 Y Rotation
08 1 For virtual doors, the width and height of the door plane (bits 0 - 3 Plane X,
4 - 7 Plane Y)
09 1 IDs of 'inside' and 'outside' areas (bits 0 - 3 inside ID, 4 - 7 outside ID)
0A 1 Door type

---===[ OBJECT TYPE 10: EXITS ]===---

14 bytes per object.

Offset Size Desc

00 2 X position
02 2 Y position
04 2 Z position
06 2 Paramater (?)
08 2 Y Rotation
0A 1 Destination level ID
0B 1 Destination level entrance ID
0C 2 Parameter (?)

---===[ OBJECT TYPE 11: MINIMAP TILE ID ]===---

2 bytes per object.

Offset Size Desc

00 2 minimap tilemap file ID

---===[ OBJECT TYPE 12: MINIMAP SCALE ]===---

2 bytes per object.

Offset Size Desc

00 2 Minimap scale (Divide by 1000?)

---===[ OBJECT TYPE 14: UNKNOWN ]===---

4 bytes per object. Seems to do absolutely nothing.

Offset Size Desc

00 2 Parameter (?)
02 2 Parameter (?)
04 2 Parameter (?)
08 2 Parameter (?)

---===[ TEXTURE ANIMATION DATA ]===---

24 bytes per entry.

Offset Size Desc

00 4 Total number of frames
04 4 Address of the scale values table (4 bytes each, 20:12 fixedpoint)
08 4 Address of the rotation values table (2 bytes each, 0x0400 = 90�)
0C 4 Address of the translation values table (4 bytes each, 20:12 fixedpoint.
Translation orientation defined by rotation)
10 4 Number of animations
14 4 Address of the animation data

Animation data: 28 bytes per entry.

Offset Size Desc

00 4 ???, 0x0000FFFF
04 4 Address of the name of the material with the texture to animate (null-
terminated ascii string)
08 4 Default scale value? Set to 1
0C 2 Number of scale values
0E 2 Start offset in dwords in the scale values table
10 2 Number of rotation values
12 2 Start offset in words in the rotation values table
14 2 Number of X translation values
16 2 Start offset in dwords of the X translations in the translation values table
18 2 Number of Y translation values
1A 2 Start offset in dwords of the Y translations in the translation values table