Every triangle in SM64’s collision mesh carries a surface type — a 16-bit constant that tells the engine how Mario should interact with it. Surface types control friction, whether a floor is lethal, whether it warps Mario to another area, which camera behaviour to activate, and much more. This page documents all constants defined inDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/n64decomp/sm64/llms.txt
Use this file to discover all available pages before exploring further.
include/surface_terrains.h, the struct Surface layout, the terrain-sound system, and the macros used to build raw collision data in level geometry files.
struct Surface
Defined ininclude/types.h, this struct describes a single collision triangle at runtime.
The primary surface type. One of the
SURFACE_* constants listed below. Determines floor/wall/ceiling behavior, friction class, special effects, and camera mode.An auxiliary data word whose meaning depends on
type. Used by flowing water, horizontal wind, instant-warp surfaces, and certain camera surfaces to carry directional or warp-target data.| Constant | Value | Meaning |
|---|---|---|
SURFACE_FLAG_DYNAMIC | 0x01 | Triangle belongs to a moving object |
SURFACE_FLAG_NO_CAM_COLLISION | 0x02 | Camera passes through this surface |
SURFACE_FLAG_X_PROJECTION | 0x08 | Use X-axis projection for wall normals |
The area room index. Objects and Mario are culled from rooms they are not in, enabling BBH and similar interiors to have separate object sets.
The precomputed unit normal and the plane equation constant. These are filled in by
load_area_terrain at level-load time and used by the collision queries (find_floor, find_ceil, find_wall_collisions).Surface type constants
Standard floors and friction classes
The default floor. Uses the level’s ambient terrain sound type set by the
terrain_type script command. Standard friction.Lava (and frostbite in SSL/SL). Landing on this surface deals continuous damage and triggers the burning animation. The surface type is reused for both lava and freezing surfaces depending on level context.
Ceiling that Mario can grab onto and traverse using the hanging locomotion (used in HMC, CotMC, and similar cave ceilings).
Slows Mario’s movement. Defined but effectively unused in the final game.
Instant kill floor. Mario dies immediately on contact. Used at the bottom of out-of-bounds pits.
Equivalent to
SURFACE_CLASS_VERY_SLIPPERY. Very high slide friction — Mario slides freely and cannot walk. Used for icy slides and some PSS sections.Equivalent to
SURFACE_CLASS_SLIPPERY. Moderate sliding; Mario moves with reduced traction. Used on ice patches.Equivalent to
SURFACE_CLASS_NOT_SLIPPERY. Maximum grip. Mario cannot slide at all — used on rough surfaces and climbable walls.Mario always takes fall damage when landing on this surface, regardless of fall distance. Used on metal/stone platforms.
Hard + slippery. Always deals fall damage and provides reduced traction.
Hard + very slippery. Always deals fall damage and provides minimal traction.
Hard + maximum grip. Always deals fall damage but Mario cannot slide.
Very slippery ice floor. Used in snow levels (CCM, SL) and THI’s underwater floor. Similar to
SURFACE_VERY_SLIPPERY in effect.Water and quicksand
Marks a water volume surface. Used on some waterboxes but has no associated movement action; the waterbox system handles swimming separately.
Water with a directional current. The
force field encodes the flow direction and speed.Quicksand with a depth of 10 units. Mario slowly sinks but can escape.
Lethal quicksand 160 units deep. Mario sinks slowly but dies if fully submerged.
Instantly lethal quicksand. Mario dies on first contact.
Flowing quicksand, 160 units deep. The
force field provides the current direction.Flowing quicksand, 25 units deep.
Moving quicksand, 60 units deep.
Flowing quicksand, 60 units deep (primary SSL desert variant).
Instantly lethal flowing quicksand. Not included in the
SURFACE_IS_QUICKSAND range check.SURFACE_IS_QUICKSAND(cmd) returns true for types 0x21–0x27 (excludes SURFACE_INSTANT_MOVING_QUICKSAND).
Wind
Applies a horizontal push force to Mario. The
force field encodes the wind direction (yaw angle). Used on SL’s snow plains and the wind corridors in SSL.Upward wind combined with a death plane at the bottom. Used in the spiral staircase area to push Mario up. Mario dies if he falls below the associated death boundary.
Warp surfaces
Stepping on one of these triggers an immediate area warp. The
force field identifies the warp destination. Used in WDW (between the two water level areas), DDD, SSL, TTM, and the endless stairs (to warp back when Mario lacks enough stars).Generic warp surface.
Warps Mario when he looks up while standing on it. Used for the Wing Cap entrance (the castle’s central room).
Pool warp used in HMC and DDD.
Timer surfaces
Starts the in-game slide timer. Used at the beginning of Peach’s Secret Slide.
Stops the timer and awards the star if the time is good enough.
Camera-control surfaces
Camera surfaces are intangible to Mario but change the camera behaviour when he enters their volume.| Constant | Value | Effect |
|---|---|---|
SURFACE_CLOSE_CAMERA | 0x000B | Pulls the camera close to Mario |
SURFACE_BOSS_FIGHT_CAMERA | 0x0065 | Wide fixed camera for BoB and WF boss fights |
SURFACE_CAMERA_FREE_ROAM | 0x0066 | Free-roam camera (THI, TTC) |
SURFACE_CAMERA_8_DIR | 0x0069 | Far camera for platforms (THI) |
SURFACE_CAMERA_MIDDLE | 0x006E | Returns camera to the middle (SSL pillars) |
SURFACE_CAMERA_ROTATE_RIGHT | 0x006F | Camera rotates right (Bowser 1, THI) |
SURFACE_CAMERA_ROTATE_LEFT | 0x0070 | Camera rotates left (BoB, TTM) |
SURFACE_CAMERA_BOUNDARY | 0x0072 | Invisible camera movement limiter |
SURFACE_NO_CAM_COLLISION | 0x0076 | No camera collision |
Misc special surfaces
An invisible separation barrier. Used in BBH to isolate the mansion interior from the merry-go-round exterior for room purposes. Mario passes through it.
Triggers the Merry-Go-Round music to play when Mario is standing on it. Handled by
handle_merry_go_round_music in bbh_merry_go_round.inc.c.Generic wall used for some interactive walls (Warp Pipe, Cannon barrel). Also adjusts camera framing.
Non-slippery surface with no camera collision, used by floor switches and Dorrie.
Walls that can be passed through while wearing the Vanish Cap.
TTM vine surface — currently has no action defined.
Bowser arena left trapdoor. Has no action defined.
Painting surfaces
Surfaces in the range0x00A6–0x00D2 cause the corresponding painting in the castle lobby to wobble when Mario touches them. Surfaces in 0x00D3–0x00FC warp Mario into the corresponding level painting.
| Constant | Value | Level |
|---|---|---|
SURFACE_PAINTING_WOBBLE_A6 | 0x00A6 | BoB painting (left zone) |
SURFACE_PAINTING_WARP_D3 | 0x00D3 | BoB painting warp (left) |
SURFACE_PAINTING_WARP_D9 | 0x00D9 | WF painting warp (left) |
SURFACE_PAINTING_WARP_DF | 0x00DF | LLL painting warp (left) |
SURFACE_TTC_PAINTING_1 | 0x00F4 | TTC painting warp (left) |
Surface class constants
The engine reduces any surface type to one of four friction classes for movement calculations:| Constant | Value | Meaning |
|---|---|---|
SURFACE_CLASS_DEFAULT | 0x0000 | Standard traction |
SURFACE_CLASS_VERY_SLIPPERY | 0x0013 | Near-zero traction (slides) |
SURFACE_CLASS_SLIPPERY | 0x0014 | Reduced traction |
SURFACE_CLASS_NOT_SLIPPERY | 0x0015 | Maximum traction |
SURFACE_IS_NOT_HARD(cmd) returns true for all surfaces that do not always cause fall damage (i.e., excludes SURFACE_HARD and 0x35–0x37).
Terrain sound types
The level script commandterrain_type sets the ambient terrain for an area. This controls the footstep sound effects Mario produces. The constant is stored in the level’s area data and accessed via MarioState.terrainSoundAddend.
| Constant | Value | Sound effect theme |
|---|---|---|
TERRAIN_GRASS | 0x0000 | Grass / dirt |
TERRAIN_STONE | 0x0001 | Stone / concrete |
TERRAIN_SNOW | 0x0002 | Snow |
TERRAIN_SAND | 0x0003 | Sand |
TERRAIN_SPOOKY | 0x0004 | Haunted house (quieter, creaky) |
TERRAIN_WATER | 0x0005 | Splashing |
TERRAIN_SLIDE | 0x0006 | Slide surface |
TERRAIN_MASK = 0x0007 masks out the 3-bit terrain index from the combined sound addend.
Collision data format and macros
Raw collision data for level geometry is stored asCollision (s16) arrays. include/surface_terrains.h defines convenience macros that make these arrays readable:
All vertex coordinates are
s16 — they are limited to −32768 … 32767 world units. If your geometry requires larger coordinates, scale the model down or consider splitting collision into multiple pieces.Water box macros
Water bodies are declared at the end of a collision block using the environment loader:TERRAIN_LOAD_* commands
These commands are embedded in the collision data stream itself and are processed by the collision loader, not the physics engine:| Constant | Value | Role |
|---|---|---|
TERRAIN_LOAD_VERTICES | 0x0040 | Begin vertex list |
TERRAIN_LOAD_CONTINUE | 0x0041 | End triangle group, continue stream |
TERRAIN_LOAD_END | 0x0042 | End the entire collision block |
TERRAIN_LOAD_OBJECTS | 0x0043 | Load macro objects placed in this area |
TERRAIN_LOAD_ENVIRONMENT | 0x0044 | Load water/gas environment boxes |
TERRAIN_LOAD_IS_SURFACE_TYPE_LOW(cmd) is true for commands < 0x40 (real surface types), and TERRAIN_LOAD_IS_SURFACE_TYPE_HIGH(cmd) is true for >= 0x65 (camera surfaces and painting types).
How surface type affects Mario’s movement
Floor friction / sliding
Floor friction / sliding
The engine maps every
type to a surface class (SURFACE_CLASS_*). If the class is VERY_SLIPPERY or SLIPPERY, Mario’s action is set to a sliding action rather than walking. The magnitude of slide deceleration is controlled by the class: very slippery surfaces decelerate very slowly, allowing long slides.Fall damage
Fall damage
SURFACE_HARD and 0x35–0x37 always trigger the fall-damage animation and sound regardless of fall height. On all other surfaces, fall damage only occurs when Mario’s fall speed exceeds the threshold.Lava damage
Lava damage
SURFACE_BURNING is detected by mario_floor_is_lava(). Mario takes periodic damage and is launched upward. The burning-feet animation plays and a timer gates how frequently damage is applied.Quicksand sinking
Quicksand sinking
Any type for which
SURFACE_IS_QUICKSAND(type) is true initiates a sinking sub-action. The depth variant determines how far Mario sinks and whether it is instantly lethal.Wind and water current
Wind and water current
SURFACE_HORIZONTAL_WIND, SURFACE_FLOWING_WATER, and the moving quicksand types all use the force field of struct Surface to supply a direction. The physics engine reads this after resolving the floor triangle.Terrain footstep sounds
Terrain footstep sounds
The area-wide
TERRAIN_* constant is blended with certain surface-specific overrides. For example, SURFACE_NOISE_DEFAULT and SURFACE_NOISE_SLIPPERY add noise to the default footstep sample.