A scrolling platformer that combines the map engine (tile-based world scrolling) with the object engine (entity management with physics and collision). A player character (Mario) walks and jumps through a side-scrolling level populated with enemies (Goombas and Koopa Troopas) that patrol back and forth. This example demonstrates how real SNES games organize their world and entity logic.
What You'll Learn
- How to use the map engine for tile-based level scrolling with collision data
- How to use the object engine to manage multiple entities with init/update callbacks
- How to implement enemy AI with patrol boundaries and animation
- How to build a multi-file C project on the SNES (separate .c files per entity)
- How the dynamic sprite engine streams sprite tiles into VRAM on demand
SNES Concepts
Map Engine and Tile Collision
The SNES PPU renders backgrounds from tilemaps in VRAM, but it has no built-in concept of "solid ground." The map engine bridges this gap by maintaining a collision attribute table (tilesetatt / .b16 file) that marks each tile as solid, passable, or hazardous. When objCollidMap() is called, it checks the object's position against this table and adjusts velocity accordingly – stopping downward movement when standing on a solid tile, for example. The tilemap sits at VRAM $6800 in a 64x32 layout (SC_64x32), giving a world 512 pixels wide – wider than the 256-pixel screen, which is what enables scrolling.
Object Engine
The object engine manages a pool of game entities. Each object type registers two callbacks: an init function and an update function. These callbacks are registered in assembly (data.asm) because the 65816 requires 24-bit addresses (16-bit pointer + 8-bit bank byte) and the C compiler only emits 16-bit pointers. Each frame, objUpdateAll() iterates over all active objects, loads their state into objWorkspace, and calls their update function.
Dynamic Sprites
Unlike static sprite allocation where tiles live at fixed VRAM addresses, the dynamic sprite engine (oamDynamicInit, oamDynamicDraw) uploads only the tiles that are visible each frame. This is essential when you have multiple animated characters, since SNES OBJ VRAM is limited to 32 KB. Sprite graphics are stored in ROM and streamed to VRAM as needed during VBlank — the NMI handler auto-flushes the VRAM tile queue, so the main loop just calls oamDynamicDraw(id) per sprite.
Controls
| Button | Action |
|---|---|
| D-Pad Left/Right | Walk |
| A | Jump (short hop) |
| Up + A | High jump |
How It Works
1. Initialize the Map and Sprite System
The tileset is loaded to VRAM $2000, and the tilemap pointer is set to $6800 with a 64x32 tile layout. The dynamic sprite engine is initialized with large sprites at VRAM $0000 and small sprites at $1000.
2. Register Object Types in Assembly
Each object type (Mario=0, Goomba=1, Koopa Troopa=2) has its init and update function pointers stored with correct bank bytes. This must be done in assembly because C cannot express 24-bit far pointers:
3. Load Objects from Map Data
Objects are defined in the level editor and stored in a .o16 file. The object engine parses this data, calling each type's init function to spawn entities at their map positions:
4. Main Loop: Update, Draw, Sync
Every frame: update the map scroll state, update all objects (physics + AI), wait for VBlank, then let mapVblank() flush tilemap changes. The NMI handler auto-flushes the dynamic sprite engine — no oamInitDynamicSpriteEndFrame or oamVramQueueUpdate calls needed in the main loop.
5. Enemy AI (Goomba Example)
Each Goomba patrols between xmin and xmax boundaries. A frame counter triggers animation and direction changes every 10 ticks. Screen position is computed by subtracting the camera scroll (x_pos, y_pos):
Project Structure
Build & Run
Then open mapandobjects.sfc in your emulator (Mesen2 recommended).
