object.h

Go to the documentation of this file.

 
#ifndef OPENSNES_OBJECT_H
#define OPENSNES_OBJECT_H
 
#include <snes/types.h>
 
/*============================================================================
 * Constants
 *============================================================================*/

#define OB_MAX              80

#define OB_TYPE_MAX         64

#define OB_SIZE             64
 
/*============================================================================
 * Object Structure (64 bytes, packed)
 *============================================================================*/

typedef struct {
    u16 prev;           
    u16 next;           
    u8 type;            
    u8 nID;             
    u16 sprnum;         
    u16 sprid3216;      
    u16 sprblk3216;     
    u8 sprflip;         
    u8 sprpal;          
    u16 sprframe;       
    u8 xpos[3];         
    u8 ypos[3];         
    u16 xofs;           
    u16 yofs;           
    u16 width;          
    u16 height;         
    u16 xmin;           
    u16 xmax;           
    s16 xvel;           
    s16 yvel;           
    u16 tilestand;      
    u16 tileabove;      
    u16 tilesprop;      
    u16 tilebprop;      
    u16 action;         
    u8 status;          
    u8 tempo;           
    u8 count;           
    u8 dir;             
    u16 parentID;       
    u8 hitpoints;       
    u8 sprrefresh;      
    u8 onscreen;        
    u8 objnotused[7];   
} t_objs;
 
/*============================================================================
 * Compile-time struct layout assertions
 * Must match the .STRUCT t_objs in object.asm exactly.
 *============================================================================*/
 
_Static_assert(sizeof(t_objs) == 64, "t_objs must be 64 bytes");
_Static_assert(__builtin_offsetof(t_objs, xpos) == 16, "xpos offset mismatch");
_Static_assert(__builtin_offsetof(t_objs, ypos) == 19, "ypos offset mismatch");
_Static_assert(__builtin_offsetof(t_objs, xvel) == 34, "xvel offset mismatch");
_Static_assert(__builtin_offsetof(t_objs, yvel) == 36, "yvel offset mismatch");
_Static_assert(__builtin_offsetof(t_objs, action) == 46, "action offset mismatch");
_Static_assert(__builtin_offsetof(t_objs, type) == 4, "type offset mismatch");
_Static_assert(__builtin_offsetof(t_objs, width) == 26, "width offset mismatch");
_Static_assert(__builtin_offsetof(t_objs, height) == 28, "height offset mismatch");
_Static_assert(__builtin_offsetof(t_objs, status) == 48, "status offset mismatch");
_Static_assert(__builtin_offsetof(t_objs, onscreen) == 56, "onscreen offset mismatch");
 
/*============================================================================
 * Exported Variables
 *============================================================================*/
 
/* --- Bank $00 SLOT 1 (C-accessible, < $2000) --- */

extern FAR t_objs objWorkspace;
 
/* Three more variables were exported here until 2026-10-03 (API decision D4:
 * a public header must not claim unprefixed names):
 *   objgetid  -> objGetCurrentId()
 *   objtokill -> objKillCurrent()            (was `objtokill = 1;`)
 *   objptr    -> the return value of objGetPointer()
 * Assembly reads obj_current_id, obj_kill_flag and obj_ptr. */
 
/* --- Bank $7E SLOT 2 (NOT C-accessible, ASM-only) --- */
/* The actual object buffer array lives in Bank $7E:
 *   objbuffers[OB_MAX]  — 80 x 64 = 5120 bytes
 *   objfctinit/upd/ref  — function pointer tables (256 bytes each)
 * The workspace is owner-tracked (since 2026-09-19): it remembers which slot
 * it mirrors, flushes to that slot before any reload (objNew, objGetPointer,
 * objKill), and every write-back goes to the owner. A callback may therefore
 * look at another object without corrupting its own record.
 *
 * Access these ONLY through the workspace pattern:
 *   objGetPointer(handle) copies objbuffers[N] → objWorkspace
 *   Engine functions copy objWorkspace → objbuffers[N] after callbacks
 */
 
/*============================================================================
 * Functions
 *============================================================================*/

void objInitEngine(void);

void objInitGravity(u16 objgravity, u16 objfriction);

void objInitFriction1D(u16 friction);

typedef void (*ObjInitFn)(u16 xp, u16 yp, u16 type, u16 minx, u16 maxx);

typedef void (*ObjUpdateFn)(u16 idx);

void objInitFunctions(u8 objtype, ObjInitFn initfct, ObjUpdateFn updfct, ObjUpdateFn reffct);

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

u16 objGetPointer(u16 objhandle);

u16 objGetCurrentId(void);

void objKillCurrent(void);

void objKill(u16 objhandle);

void objKillAll(void);

void objLoadObjects(const u8 *sourceO);

void objUpdateAll(void);

void objRefreshAll(void);

void objCollidMap(u16 objindex);

void objCollidMapWithSlopes(u16 objindex);

void objCollidMap1D(u16 objindex);

u16 objCollidObj(u16 idx1, u16 idx2);

void objUpdateXY(u16 objindex);
 
#endif /* OPENSNES_OBJECT_H */