object.h File Reference

Game object engine with physics and collision (CONTRIB module) More...

#include <snes/types.h>

Go to the source code of this file.

Classes
struct	t_objs
	Game object data structure. More...

Macros
#define	OB_MAX   80
	Maximum number of objects in the game.
#define	OB_SIZE   64
	Object size in bytes.
#define	OB_TYPE_MAX   64
	Maximum number of object types.

Functions
void	objCollidMap (u16 objhandle)
	Check object collision with map tiles.
void	objCollidMap1D (u16 objhandle)
	Check object collision with map (no gravity)
void	objCollidMapWithSlopes (u16 objhandle)
	Check object collision with map tiles including slopes.
u16	objCollidObj (u16 objhandle1, u16 objhandle2)
	Test collision between two objects.
void	objGetPointer (u16 objhandle)
	Get pointer to an object from its handle.
void	objInitEngine (void)
	Initialize the object engine.
void	objInitFunctions (u8 objtype, void *initfct, void *updfct, void *reffct)
	Register callback functions for an object type.
void	objInitGravity (u16 objgravity, u16 objfriction)
	Set gravity and friction values.
void	objKill (u16 objhandle)
	Kill an object.
void	objKillAll (void)
	Kill all active objects.
void	objLoadObjects (u8 *sourceO)
	Load objects from a data table.
u16	objNew (u8 objtype, u16 x, u16 y)
	Create a new object.
void	objRefreshAll (void)
	Refresh sprites for all on-screen objects.
void	objUpdateAll (void)
	Update all active objects.
void	objUpdateXY (u16 objindex)
	Update object position from velocity.

Variables
u16	objgetid
	Handle of the last object created by objNew()
u16	objptr
	Current object pointer (byte offset, for internal use)
u8	objtokill
	Set to 1 inside a callback to kill the current object.
t_objs	objWorkspace
	Object workspace (Bank $00)

Detailed Description

Game object engine with physics and collision (CONTRIB module)

Note

This is a contrib module, not core SDK. The implementation lives in lib/contrib/object.asm and is not transitively included by <snes.h>. Examples that use it must #include <snes/object.h> explicitly and list object in their Makefile's LIB_MODULES. See lib/contrib/README.md for the policy.

Provides managed game objects with:

• Linked-list management (up to 80 objects, 64 types)
• Type-based function dispatch (init, update, refresh callbacks)
• Map collision detection (with optional slope support)
• Fixed-point position and velocity
• Object-to-object collision detection

Workspace Pattern

Because the object buffer resides in Bank $7E (not directly accessible from C), a workspace pattern is used. Before each C callback, the engine copies the current object's data to objWorkspace (Bank $00). After the callback returns, changes are copied back.

#include <snes.h>
#include <snes/object.h>
 
void enemy_update(u16 idx) {
    // objWorkspace is pre-populated with current object data
    if (objWorkspace.action == ACT_WALK) {
        objWorkspace.xvel = 0x0100;
    }
    // Call engine functions (they sync workspace automatically)
    objCollidMap(idx);
    objUpdateXY(idx);
    // Read updated position from workspace
    u16 screenx = objWorkspace.xpos[1] | (objWorkspace.xpos[2] << 8);
}

Attribution

Based on: PVSnesLib object engine by Alekmaul Slope management: Nub1604 License: zlib (compatible with MIT)

Macro Definition Documentation

OB_MAX

#define OB_MAX   80

Maximum number of objects in the game.

OB_SIZE

#define OB_SIZE   64

Object size in bytes.

OB_TYPE_MAX

#define OB_TYPE_MAX   64

Maximum number of object types.

Function Documentation

objCollidMap()

void objCollidMap

(

u16

objhandle

)

Check object collision with map tiles.

Tests collision in Y (gravity/jumping) then X (walls). Updates tilestand, tileabove, tilesprop, tilebprop in objWorkspace. Applies friction to X velocity. Applies gravity if airborne.

Parameters

objhandle

Object index (as received in update callback)

Note

Syncs objWorkspace before and after — safe to call from C callbacks.

objCollidMap1D()

void objCollidMap1D

(

u16

objhandle

)

Check object collision with map (no gravity)

For top-down movement without gravity.

Parameters

objhandle

Object index

objCollidMapWithSlopes()

void objCollidMapWithSlopes

(

u16

objhandle

)

Check object collision with map tiles including slopes.

Like objCollidMap but also handles slope tiles (T_SLOPEU1..T_SLOPEUD2).

Parameters

objhandle

Object index

objCollidObj()

u16 objCollidObj	(	u16	objhandle1,
		u16	objhandle2
	)

Test collision between two objects.

Uses AABB (axis-aligned bounding box) collision.

Parameters

objhandle1	First object index
objhandle2	Second object index

Returns

1 if collision detected, 0 otherwise

objGetPointer()

void objGetPointer

(

u16

objhandle

)

Get pointer to an object from its handle.

Validates the handle and populates objWorkspace with the object's data. Sets objptr to the buffer offset (1-based), or 0 if invalid.

Parameters

objhandle

Object handle (from objNew/objgetid)

objInitEngine()

void objInitEngine

(

void

)

Initialize the object engine.

Clears all object buffers, resets linked lists, and sets default gravity/friction values. Call once at game start.

objInitFunctions()

void objInitFunctions	(	u8	objtype,
		void *	initfct,
		void *	updfct,
		void *	reffct
	)

Register callback functions for an object type.

Parameters

objtype	Object type index (0-63)
initfct	Init callback: void init(u16 xp, u16 yp, u16 type, u16 minx, u16 maxx)
updfct	Update callback: void update(u16 idx) — called per frame
reffct	Refresh callback: void refresh(u16 idx) — called for on-screen objects (or NULL)

objInitGravity()

void objInitGravity	(	u16	objgravity,
		u16	objfriction
	)

Set gravity and friction values.

Parameters

objgravity	Gravity acceleration per frame (default: 41)
objfriction	Horizontal friction deceleration (default: 16)

objKill()

void objKill

(

u16

objhandle

)

Kill an object.

Parameters

objhandle

Object handle

objKillAll()

void objKillAll

(

void

)

Kill all active objects.

objLoadObjects()

void objLoadObjects

(

u8 *

sourceO

)

Load objects from a data table.

Table format: [x:u16, y:u16, type:u16, minx:u16, maxx:u16]... terminated by 0xFFFF. Calls each type's init function for every object loaded.

Parameters

sourceO

Pointer to object data table

objNew()

u16 objNew	(	u8	objtype,
		u16	x,
		u16	y
	)

Create a new object.

Parameters

objtype	Object type (0-63)
x	Initial X position in map pixels
y	Initial Y position in map pixels

Returns

Object handle (0 if no space available). Also stored in objgetid.

Note

After objNew, the new object data is copied to objWorkspace. Set width, height, and other fields on objWorkspace before returning from the init callback.

objRefreshAll()

void objRefreshAll

(

void

)

Refresh sprites for all on-screen objects.

Calls the refresh function for objects that are on screen (-32 to 256 X, -32 to 224 Y). Useful to avoid flickering in scrolling games.

objUpdateAll()

void objUpdateAll

(

void

)

Update all active objects.

Iterates through all active objects. For each object within the "virtual screen" (-64 to 320 X, -64 to 288 Y), calls the type's update function with objWorkspace pre-populated.

objUpdateXY()

void objUpdateXY

(

u16

objindex

)

Update object position from velocity.

Adds xvel/yvel to xpos/ypos (24-bit fixed point).

Parameters

objindex

Raw object index (0-79), NOT the handle from objNew. Use the index passed to your update callback, or extract from handle with (handle & 0xFF).

Note

Syncs objWorkspace before and after.

Variable Documentation

objgetid

u16 objgetid

extern

Handle of the last object created by objNew()

objptr

u16 objptr

extern

Current object pointer (byte offset, for internal use)

objtokill

u8 objtokill

extern

Set to 1 inside a callback to kill the current object.

objWorkspace

t_objs objWorkspace

extern

Object workspace (Bank $00)

Single 64-byte workspace populated before each C callback. Read/write this in init, update, and refresh callbacks. Changes are automatically copied back to the object buffer.