Standard Library: Entity System - SyncroMesh Documentation

Use these helpers within a board script; their registry is local to that JavaScript context. The application mount must contain the referenced /rom/std files. These wrappers are optional: the first simulation uses the native runtime API directly.

The standard library ships two helpers under /rom/std/ that provide a class-based entity pattern on top of the raw Syncromesh/Entity and Syncromesh/Simulation modules.

EntityBase #

A base class for game entities. Subclass it to define entity types with sprite sheets, frame-based animation, and per-frame update logic.

Import #

Static methods #

create

Spawns an entity and initialises sprite sheet metadata.

Calls Simulation.spawn(options) internally.
If the subclass defines an onUpdate(delta, time) method, it is automatically registered via Entity.registerUpdate.

static async create(options: SpawnOptions, sheetPath: string, textureSize: Point, spriteSize: Point): Promise<EntityBase>

Instance methods #

defineAnimtion

Builds sprite frames from a sprite sheet definition and creates a sprite renderable.

Each AnimDef has: name (string), row (tileset row), frames (count), origin (Point), and optional flip (boolean) for generating mirrored frames.
After calling, this.animationSet maps "<name>Start" and "<name>Length" to frame indices.

async defineAnimtion(definitions: AnimDef[]): Promise<void>

animate

Advances the sprite animation by frame time.

facing is 0 for normal or 1 for flipped (if flip was set in the definition).
onComplete is called when the animation reaches its last frame. Return true to reset, or omit to loop.

animate(time: number, name: string, frameTime: number, facing: number, onComplete?: (): boolean) : void

wrapAsyncUpdate #

wrapAsyncUpdate(instance, fn) wraps an async update function so it returns a numeric delay compatible with Entity.registerUpdate. The returned delay from the promise is cached and reused until the next resolution.

EntitySystem #

A singleton registry that maps entity IDs to class instances. Import it to spawn, look up, and destroy typed entities.

Import #

Methods #

spawn

Creates an entity using EntityClass.create(...args) and registers it by ID.

The first argument is the entity class (a subclass of EntityBase). Remaining arguments are forwarded to create().

async spawn(EntityClass, ...args): Promise<EntityBase>

byId

Returns the entity instance for the given ID, or undefined if not tracked.

byId(id: number): EntityBase | undefined

destroy

Removes the entity from the registry and calls Simulation.destroy().

async destroy(entity: EntityBase): Promise<void>

Examples #

import EntityBase from '/rom/std/EntityBase.js';
import EntitySystem from '/rom/std/EntitySystem.js';

class Player extends EntityBase
{
    async onUpdate (delta, time)
    {
        this.animate(time, 'idle', 0.15, 0);
        return 0;
    }
}

const player = await EntitySystem.spawn(
    Player,
    { position: { x: 0, y: 0 } },
    '/rom/sprites/player.png',
    { x: 16, y: 16 },
    { x: 16, y: 16 }
);

await player.defineAnimtion([
    { name: 'idle', row: 0, frames: 4, origin: { x: 8, y: 16 } },
    { name: 'walk', row: 1, frames: 6, origin: { x: 8, y: 16 }, flip: true }
]);

// Look up by ID
const found = EntitySystem.byId(player.id);

// Destroy
await EntitySystem.destroy(player);

<- Native scrolling