Skip to content

SNES data

The SNES export writes the project into chunks of at most 32 KB, one LoROM bank each, with the C that finds them. This page documents data version 4 (resident exports) and 5 (streamed exports), for an engine that reads the data itself. The generated inc/modsprite_data.h declares every record and table named here.

The files

File
res/ms_chunk_NN.bin the data, in chunks of at most 32 KB
modsprite_chunks.asm one superfree section per chunk, labelled ms_chunk_NN, so the linker places each in a bank
inc/modsprite_data.h the counts and constants (as numbers), the record types, the tables' declarations
src/modsprite_data.c ms_chunks[] and the tables' addresses in the chunks; ms_data_init() sets them up
modsprite_rom.mk ROMBANKS and ROMSIZE: the ROM size the chunks need

Layout

  • Little-endian, like the 65816. Every 16-bit field sits on an even offset, so the records read the same packed or aligned.
  • The records the runtime indexes are padded to 8 or 16 bytes (816-tcc multiplies by other sizes with a library call); a render frame's 22 bytes are multiplied in shifts.
  • A table the runtime indexes sits whole in one chunk. Render frames come in pages of 1024 (MS_RF_PAGE_SHIFT, ms_rf_pages[]); ms_render_frame(index) finds one.
  • Lists a render frame points to are far references: an offset into a chunk and the chunk's number, MS_FAR(chunk, offset).

Constants

MS_DATA_VERSION, the counts (MS_MODULE_COUNT, MS_FRAME_COUNT, MS_ANIMATION_COUNT, MS_SCENE_COUNT, MS_MAPPING_COUNT, MS_RENDER_FRAME_COUNT, MS_ANIM_STEP_COUNT, MS_TILE_COUNT, MS_PALETTE_ENTRY_COUNT, MS_BASE_PALETTE_COUNT, MS_PALETTE_SWAP_COUNT, ...), the sprite sizes (MS_SMALL_SIZE, MS_LARGE_SIZE, and MS_OBJ_SIZE, OBSEL's size select in bits 5 to 7), MS_TILE_TABLES, MS_FIXED_ENTRY (0x80), MS_NO_ANIMATION and MS_NO_ROLE (0xFFFF), MS_UNKNOWN_TYPE (0xFF), and the project's MS_EVENT_*, MS_HITBOX_*, MS_POINT_* and MS_ROLE_*. A streamed export adds MS_STREAMED, MS_SLOT_TILES, MS_SCENE_SLOT_TILES, MS_SLOT_ALIGN and MS_UPLOAD_BUDGET.

The records

typedef struct {                 /* 22 bytes */
    u16 sprites_offset; u8 sprites_chunk; u8 run_count;   /* its sprites: run_count runs */
    u16 boxes_offset;   u8 boxes_chunk;   u8 box_count;
    u16 points_offset;  u8 points_chunk;  u8 point_count;
    u8  sprite_count;   u8 part_count;
    s16 min_x, min_y, max_x, max_y;      /* the box around its sprites, from the draw position */
} MS_RenderFrame;

typedef struct { u8 palette; u8 count; } MS_Run;   /* 2 bytes, then count MS_Sprite */
/* palette: the run's palette entry; MS_FIXED_ENTRY set: a scene object's own colours, not recoloured */

typedef struct {                 /* 8 bytes: one hardware sprite, ready for the OAM */
    s16 x, y;                    /* from the draw position */
    u8  tile;                    /* the tile's low 8 bits */
    u8  attribute;               /* V flip 0x80, H flip 0x40, the tile's bit 8 0x01 */
    u8  size;                    /* 2: large (its bit in the high table), 0: small */
    u8  reserved;
} MS_Sprite;

typedef struct { u8 type; u8 reserved; u16 role; s16 x, y, w, h; u16 reserved2[2]; } MS_Hitbox;   /* 16 bytes */
typedef struct { u8 type; u8 reserved; u16 role; s16 x, y; } MS_Point;                           /* 8 bytes */

typedef struct {                 /* 8 bytes */
    u16 frame_index;             /* the step's render frame */
    u16 duration_ticks;          /* in video frames at 60 a second */
    u16 first_event; u8 event_count; u8 reserved;
} MS_AnimStep;

typedef struct {                 /* 16 bytes */
    u16 first_step; u16 step_count; u16 fps;
    u8  playback;                /* 0 loop, 1 once, 2 ping-pong, 3 backward */
    u8  reserved;
    u16 loop_start; u16 next_animation; u16 loop_count; u16 reserved2;
} MS_Animation;

typedef struct { u16 type; s16 value; } MS_StepEvent;   /* 4 bytes */

typedef struct {                 /* 16 bytes */
    u16 first_sample; u16 sample_count; u16 fps;
    u16 duration_ticks;          /* in video frames */
    u8  loop; u8 reserved; u16 reserved2[3];
} MS_Scene;

typedef struct { u8 palette; u8 swap; u16 first_cycle; u8 cycle_count; u8 reserved; u16 reserved2; } MS_PaletteEntry;  /* 8 */
typedef struct { u8 first; u8 count; u16 frames; u8 reverse; u8 reserved; u16 reserved2; } MS_ColourCycle;            /* 8 */

Hitboxes and points are already moved like the picture, relative to the draw position. Field meanings are those of the Mega Drive's records.

The tables

Table
ms_tile_tables[2] resident exports: the two sprite tables, 256 tiles each (8 KB, 4 bits a pixel in the SNES's planar format), as they go into video memory
ms_module_render_frames, ms_frame_render_frames u16 render frame per (mapping, module or frame): index mapping × count + index
ms_anim_steps, ms_animations the steps; one animation record per (mapping, animation)
ms_step_events the events the steps name
ms_scene_samples, ms_scenes u16 render frame per sample; one scene record per (mapping, scene)
ms_palette 16 BGR555 colours (0bbbbbgg gggrrrrr) per palette entry
ms_palette_entries, ms_colour_cycles as on the Mega Drive
ms_swap_entries u8 per (swap from 1, base palette): the entry swap s makes of palette p is at (s - 1) × base palettes + p
ms_module_flip_offsets two s16 per (mapping, module): its width less twice its pivot's x, its height less twice its pivot's y
names and ids ms_module_names(i), ms_module_ids(i), and the same for mappings, frames, animations, scenes, events, types, roles, swaps and palette entries

Mapping 0 is no mapping, then the exported mappings in order.

Tiles

A resident export packs the squares of the two sizes into the two tables, largest first, each at the first free place aligned to its size: a square of N pixels takes N/8 × N/8 tiles in a table 16 tiles wide, its first tile a multiple of N/8 in both directions, as the PPU finds them. Squares with the same pixels are stored once; a sprite's tile number (9 bits) counts from the first table.

Streamed exports (version 5)

The cartridge keeps the squares in strips: each frame's new squares, in the order frames first use them, side by side in rows of at most 16 tiles. Every render frame names a load list:

/* ms_render_frame_loads: a u16 load list per render frame (MS_NO_LIST: it shows nothing) */
typedef struct { u16 entries_offset; u8 entries_chunk; u8 group_count; u16 tile_count; u16 cost; } MS_LoadList;  /* 8 */
typedef struct { u8 chunk; u8 count; } MS_LoadGroup;          /* 2: the chunk its runs read, then count entries */
typedef struct { u16 vram; u16 source; u16 bytes; } MS_LoadEntry;   /* 6: one DMA run */
/* ms_load_list_rows: a u8 per list, the sprite-table rows it takes in a slot */

A list is group_count groups; each group names a chunk and holds count entries, each a DMA run copying bytes from source in that chunk to the slot's VRAM word address plus vram. Laid out in a slot of whole rows, each square aligned to its size, the runs give the tiles the render frame's sprites count from: a sprite's tile number is the slot's first tile plus the sprite's (an addition, not an or). cost is what the list takes of the upload budget: its bytes plus the set-up of its runs, groups and the list, measured in Mesen 2. Identical lists are stored once.

Drawing a render frame

const MS_RenderFrame *rf = ms_render_frame(index);
const u8 *at = MS_FAR(rf->sprites_chunk, rf->sprites_offset);
for (r = 0; r < rf->run_count; r++)
{
    const MS_Run *run = (const MS_Run *)at;
    u8 bits = priority | palette_bits(run->palette);     /* the OAM byte's priority and palette (bits 1-3) */
    at += sizeof(MS_Run);
    for (k = 0; k < run->count; k++, at += sizeof(MS_Sprite))
    {
        const MS_Sprite *s = (const MS_Sprite *)at;
        s16 size = s->size ? MS_LARGE_SIZE : MS_SMALL_SIZE;
        s16 x = (flip & 1) ? -s->x - size : s->x;         /* mirrored draws only */
        s16 y = (flip & 2) ? -s->y - size : s->y;
        u16 tile = (s->tile | ((s->attribute & 1) << 8)) + tile_base;   /* streamed: the slot's first tile */
        oam_put(draw_x + x, draw_y + y, tile,
                ((s->attribute & 0xC0) ^ flip_bits) | bits,  /* flip_bits: H 0x40, V 0x80 of the mirrored draw */
                s->size);
    }
}

The sprites are stored in OAM order, the first in front. The palette bits come from the run's entry as on the Mega Drive: under palette swap s an entry below the base palette count is drawn from ms_swap_entries[(s - 1) × base palettes + entry], an entry with MS_FIXED_ENTRY set from its own, each from the sprite palette it is loaded in. The runtime draws with priority 2.

Versions

Version What changed
5 (since 0.12) streamed exports: version 3 with the module flip offsets of version 4, and each load list's rows (ms_load_list_rows)
4 (since 0.12) resident exports: version 2 with each module's flip offset under each mapping
3 streamed exports only, never in a release: load lists, sprites counted from a slot
2 (0.10 to 0.11) the first released version

The generated files carry the version (MS_DATA_VERSION); data, generated code and runtime come from the same export and editor version.