Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pmret/papermario/llms.txt

Use this file to discover all available pages before exploring further.

include/common_structs.h is the single most-included header in the project. It defines the vector and color types used everywhere from collision math to rendering, along with foundational runtime structs such as SaveData, HeapNode, and CameraRig. All struct sizes given here are verified from the inline comments in the source.

​
Vector types

The codebase provides a complete family of two- and three-component vectors in several element widths. Use the smallest type that covers your range to match original memory layout.

​
8-bit integer vectors

StructFieldsSizeNotes
Vec2bs8 x, y0x02Signed byte XY
Vec2buu8 x, y0x02Unsigned byte XY
Vec3bs8 x, y, z0x03Signed byte XYZ
typedef struct Vec2b  { s8 x; s8 y; }       Vec2b;  // size = 0x02
typedef struct Vec2bu { u8 x; u8 y; }       Vec2bu; // size = 0x02
typedef struct Vec3b  { s8 x; s8 y; s8 z; } Vec3b;  // size = 0x03

​
16-bit integer vectors

StructFieldsSizeNotes
Vec2ss16 x, y0x04Signed halfword XY
Vec2suu16 x, y0x04Unsigned halfword XY
Vec3ss16 x, y, z0x06Signed halfword XYZ
typedef struct Vec2s  { s16 x; s16 y; }           Vec2s;  // size = 0x04
typedef struct Vec2su { u16 x; u16 y; }           Vec2su; // size = 0x04
typedef struct Vec3s  { s16 x; s16 y; s16 z; }    Vec3s;  // size = 0x06

​
32-bit integer vectors

StructFieldsSizeNotes
Vec2is32 x, y0x08Signed word XY
VecXZis32 x, z0x08Signed word XZ (no Y component)
Vec3is32 x, y, z0x0CSigned word XYZ
typedef struct Vec2i  { s32 x; s32 y; }           Vec2i;  // size = 0x08
typedef struct VecXZi { s32 x; s32 z; }           VecXZi; // size = 0x08
typedef struct Vec3i  { s32 x; s32 y; s32 z; }    Vec3i;  // size = 0x0C
VecXZi is used in contexts where the horizontal plane is relevant but vertical position is not.

​
Float vectors

StructFieldsSizeNotes
Vec2ff32 x, y0x08Single-precision XY
VecXZff32 x, z0x08Single-precision XZ
Vec3ff32 x, y, z0x0CSingle-precision XYZ
Vec4ff32 x, y, z, yaw0x10Three-component position plus yaw angle
typedef struct Vec2f  { f32 x; f32 y; }                Vec2f;  // size = 0x08
typedef struct VecXZf { f32 x; f32 z; }                VecXZf; // size = 0x08
typedef struct Vec3f  { f32 x; f32 y; f32 z; }         Vec3f;  // size = 0x0C
typedef struct Vec4f  { f32 x; f32 y; f32 z; f32 yaw; } Vec4f; // size = 0x10

​
Color types

StructFieldsSizeNotes
Color_RGBA8u8 r, g, b, a0x0432-bit RGBA, 8 bits per channel
Color_RGB8u8 r, g, b0x0324-bit RGB, no alpha
Color4ff32 r, g, b, a0x10Float RGBA, used in lighting and blend state
Color3is32 r, g, b0x0CInteger RGB, used in colour arithmetic
Color4is32 r, g, b, a0x10Integer RGBA, used in colour arithmetic
typedef struct { u8 r, g, b, a; } Color_RGBA8;
typedef struct { u8 r, g, b; }    Color_RGB8;

typedef struct Color4f { f32 r; f32 g; f32 b; f32 a; } Color4f; // size = 0x10
typedef struct Color3i { s32 r; s32 g; s32 b; }        Color3i; // size = 0x0C
typedef struct Color4i { s32 r; s32 g; s32 b; s32 a; } Color4i; // size = 0x10

​
Matrix types

TypeDefinitionSizeNotes
Matrix4ftypedef f32 Matrix4f[4][4]0x40Row-major 4×4 float matrix
Matrix4sstruct with whole[4][4] and frac[4][4] of s160x40Fixed-point N64 RSP matrix format
Matrix4s stores the integer and fractional parts of a fixed-point 4×4 matrix separately, matching the format consumed by the RSP microcode.

​
Other core structs

Describes the boom-arm camera parameterisation used by the in-game camera system.
typedef struct CameraRig {
    /* 0x00 */ f32 boomYaw;
    /* 0x04 */ f32 boomLength;
    /* 0x08 */ f32 boomPitch;
    /* 0x0C */ f32 viewPitch;
    /* 0x10 */ Vec3f targetPos;
} CameraRig; // size = 0x1C
A node in the game’s custom heap allocator free list.
typedef struct HeapNode {
    /* 0x00 */ struct HeapNode* next;
    /* 0x04 */ u32 length;
    /* 0x08 */ u16 allocated;
    /* 0x0A */ u16 entryID;
    /* 0x0C */ u32 capacity;
} HeapNode; // size = 0x10
Describes a DMA transfer: source start, source end, and destination address.
typedef struct DmaTable {
    /* 0x00 */ u8* start;
    /* 0x04 */ u8* end;
    /* 0x08 */ u8* dest;
} DmaTable;
Per-partner save record stored in PlayerData.
typedef struct PartnerData {
    /* 0x00 */ u8  enabled;
    /* 0x01 */ s8  level;
    /* 0x02 */ s16 unk_02[3];
} PartnerData; // size = 0x08
Ring buffer storing an NPC’s world-space position over the last 20 frames, used to render motion-blur trails.
typedef struct NpcMotionBlur {
    /* 0x00 */ s8  unused;
    /* 0x01 */ s8  index;      // current ring-buffer write index
    /* 0x02 */ char unk_02[2];
    /* 0x04 */ f32 posX[20];
    /* 0x54 */ f32 posY[20];
    /* 0xA4 */ f32 posZ[20];
} NpcMotionBlur; // size = 0xF4
The full on-cartridge save record for one save slot. Total size is 0x1380 bytes.
typedef struct SaveData {
    /* 0x0000 */ char  magicString[16]; // "Mario Story 006"
    /* 0x0010 */ s8    pad[32];         // always zero
    /* 0x0030 */ s32   crc1;
    /* 0x0034 */ s32   crc2;
    /* 0x0038 */ s32   saveSlot;
    /* 0x003C */ s32   saveCount;
    /* 0x0040 */ PlayerData player;
    /* 0x0468 */ s16   areaID;
    /* 0x046A */ s16   mapID;
    /* 0x046C */ s16   entryID;
    /* 0x0470 */ s32   enemyDefeatFlags[60][12];
    /* 0x0FB0 */ s32   globalFlags[64];     // GF_ flags
    /* 0x10B0 */ s8    globalBytes[512];    // GB_ bytes
    /* 0x12B0 */ s32   areaFlags[8];
    /* 0x12D0 */ s8    areaBytes[16];
    /* 0x12E6 */ Vec3s savePos;
    /* 0x12EC */ SaveMetadata metadata;
} SaveData; // size = 0x1380
SaveGlobals holds settings shared across all save slots (sound mode, last file selected, language). SaveMetadata holds the per-slot summary shown on the file-select screen.
typedef struct SaveGlobals {
    /* 0x00 */ char magicString[16]; // "Mario Story 006"
    /* 0x10 */ s8   pad[32];
    /* 0x30 */ s32  crc1;
    /* 0x34 */ s32  crc2;
    /* 0x38 */ s32  useMonoSound;
    /* 0x3C */ u32  lastFileSelected;
    /* 0x40 */ u32  language;        // PAL only
    /* 0x44 */ s8   reserved[60];
} SaveGlobals; // size = 0x80

typedef struct SaveMetadata {
    /* 0x00 */ s32          timePlayed;
    /* 0x04 */ u8           spiritsRescued;
    /* 0x06 */ s8           level;
    /* 0x07 */ unsigned char filename[8];
} SaveMetadata; // size = 0x18

​
Using struct sizes

Comments in the source follow the format // size = 0xNN. When you add a new field or modify an existing struct, verify that the total matches. The build will not catch size mismatches automatically — you need to cross-reference against the original binary layout documented in the decomp.

Build docs developers (and LLMs) love

Get started for freeTalk to us