v0.5.0

Syncromesh/Entity

Per-entity control: movement, native component packs (identity/logic/data/locomotion/waypoint), physics, renderables, animations, tiles, and update handlers.

Operates on individual entities by ID. Covers travel (non-physics movement), physics forces and linear velocity, fixtures, renderables, sprite/tile/text manipulation, animations, and per-entity update callbacks.

Import #

import * as Entity from 'Syncromesh/Entity';

Movement #

setTravelVector
Sets the travel direction from a vector. A zero vector stops travel.
setTravelVector(id: number, vector: Point): Promise<void>
setTravelAngle
Sets the travel angle in degrees.
setTravelAngle(id: number, angle: number): Promise<void>
setTravelSpeed
Sets the travel speed (units per second).
setTravelSpeed(id: number, speed: number): Promise<void>
getTravelSpeed
Returns the current travel speed.
getTravelSpeed(id: number): Promise<number>
getLocomotionThrust
Returns the current world-space locomotion thrust vector. Zero means the locomotion controller is coasting or idle.
getLocomotionThrust(id: number): Promise<Point>
getPosition
Returns the entity's world position as { x, y }.
getPosition(id: number): Promise<Point>
getDirection
Returns the entity's current facing direction in degrees.
getDirection(id: number): Promise<number>
setTransform
Sets an entity's world position and facing direction in degrees. Physics bodies are moved and woken, and the interpolation transform is updated immediately.
setTransform(id: number, position: Point, directionDeg: number): Promise<boolean>

Board UI attachments #

A board-local UI element can follow a local or replicated entity without sending per-frame positions through JavaScript. Syncromesh projects the entity's interpolated world transform through the attached window camera immediately before drawing the board UI layer. Attachments are local presentation state and are not replicated. While attached, Syncromesh owns the element's enabled state so missing and offscreen entities can be hidden deterministically.

attachUI
Attaches a board UI element to an entity using native per-frame projection.
  • worldOffset is applied in board world coordinates before camera projection.
  • screenOffset is applied in UI pixels after projection.
  • hideOffscreen defaults to true.
  • The call is available in board script contexts. It returns false for an inactive entity, invalid window or element IDs, or a host-only script context.
  • An attachment records the entity activation it was created for, so a recycled local entity ID cannot capture an old overlay.
attachUI(id: number, windowId: number, elementId: number, options?: { worldOffset?: Point, screenOffset?: Point, hideOffscreen?: boolean }): Promise<boolean>
detachUI
Removes an exact entity-to-UI attachment. Destroyed UI elements are pruned automatically during rendering.
detachUI(id: number, windowId: number, elementId: number): Promise<boolean>
import * as Entity from 'Syncromesh/Entity';

await Entity.attachUI(shipId, windowId, healthBarId, {
    worldOffset: {x: 0, y: 2},
    screenOffset: {x: 0, y: -12},
    hideOffscreen: true
});

Native component packs #

setIdentity
Sets native identity metadata used by authoritative replication.
setIdentity(id: number, options: { enabled?: boolean, uid?: number, faction?: number, category?: number, handle?: string, label?: string }): Promise<void>
getIdentity
Reads native identity metadata.
getIdentity(id: number): Promise<{ enabled: boolean, uid: number, faction: number, category: number, handle: string, label: string }>
setLogic
Configures native logic execution settings for the entity.
setLogic(id: number, options: { enabled?: boolean, minIntervalSeconds?: number }): Promise<void>
getLogic
Reads native logic settings.
getLogic(id: number): Promise<{ enabled: boolean, minIntervalSeconds: number }>
defineDataField
Declares a typed native data field (for example: int32, float, string, boolean).
defineDataField(id: number, key: string, type: string): Promise<boolean>
setDataValue
Writes a value into a typed data field slot.
setDataValue(id: number, key: string, index: number, value: string): Promise<boolean>
getDataValue
Reads a value from a typed data field slot.
getDataValue(id: number, key: string, index: number): Promise<string | null>
getDataType
Returns the declared type name for a data field.
getDataType(id: number, key: string): Promise<string | null>
removeDataField
Removes a typed data field from the entity.
removeDataField(id: number, key: string): Promise<boolean>
listDataFields
Lists all declared typed data fields.
listDataFields(id: number): Promise<Array<{ key: string, type: string }>>
setLocomotion
Configures native locomotion steering parameters.
setLocomotion(id: number, options: { enabled?: boolean, maxSpeed?: number, adjust?: number, turn?: number, arriveDistance?: number, shortAdjustDistance?: number, faceTravelDirection?: boolean, directWaypointThrust?: boolean }): Promise<void>
getLocomotion
Reads native locomotion settings.
getLocomotion(id: number): Promise<{ enabled: boolean, maxSpeed: number, adjust: number, turn: number, arriveDistance: number, shortAdjustDistance: number, faceTravelDirection: boolean, directWaypointThrust: boolean }>
setWaypointOptions
Configures native waypoint-following behavior.
setWaypointOptions(id: number, options: { enabled?: boolean, closeEnoughDistance?: number }): Promise<void>
enqueueWaypoint
Adds a waypoint to the native queue.
enqueueWaypoint(id: number, target: Point): Promise<void>
popWaypoint
Removes the next waypoint from the queue.
popWaypoint(id: number): Promise<boolean>
clearWaypoints
Clears all queued waypoints.
clearWaypoints(id: number): Promise<void>
getWaypoints
Reads current waypoint queue state.
getWaypoints(id: number): Promise<{ enabled: boolean, active: boolean, closeEnoughDistance: number, points: Point[] }>

Physics #

addForce
Applies a force at a world point on the entity's physics body.
addForce(id: number, force: Point, point: Point): Promise<void>
addForceToCenter
Applies a force at the body's center of mass.
addForceToCenter(id: number, force: Point): Promise<void>
setLinearVelocity
Sets the Box2D linear velocity for the entity's body.
setLinearVelocity(id: number, velocity: Point): Promise<void>
getLinearVelocity
Returns the entity body's current Box2D linear velocity.
getLinearVelocity(id: number): Promise<Point>
setBodyBullet
Enables or disables Box2D bullet mode on an entity's physics body. Resolves true when a body was updated.
setBodyBullet(id: number, enabled: boolean): Promise<boolean>
getBodyAabb
Returns the entity body's exact world-space fixture bounds.
  • Bounds are computed by unioning each fixture shape's world-space AABB. This does not use Box2D broadphase fat AABBs.
  • hasBody reports whether the entity has a physics body. hasFixtures reports whether that body had any fixture shapes to union.
  • When hasFixtures is false, min, max, centre, center, and size are a zero-sized fallback.
getBodyAabb(id: number): Promise<{ hasBody: boolean, hasFixtures: boolean, min: Point, max: Point, centre: Point, center: Point, size: Point }>
createFixture
Adds a physics fixture to the entity's body.
  • See Physics for fixture shapes and properties.
createFixture(id: number, fixture: FixtureDef): Promise<void>
destroyFixtures
Removes all fixtures from the entity's physics body.
destroyFixtures(id: number): Promise<void>
setCollisionFilter
Replaces the Box2D collision filter on every fixture attached to an entity.
  • Existing contacts are refiltered by Box2D.
  • Use decimal or hexadecimal strings for 64-bit category and mask values outside JavaScript's safe integer range.
setCollisionFilter(id: number, filter: FixtureFilter): Promise<void>
getContacts
Returns IDs of entities currently in contact with this entity.
getContacts(id: number): Promise<number[]>

Renderables #

createRenderable
Attaches a renderable to the entity and returns its renderable index.
createRenderable(id: number, descriptor: RenderDescriptor): Promise<number>
getRenderable
Returns an opaque handle for a renderable attached to the entity.
  • Particle lifecycle functions in Helix/Renderable require this handle.
  • Entity/renderable access is board-script-only. See GPU Particles.
getRenderable(id: number, renderableIndex: number): Promise<number>
setSpriteFrame
Sets the active sprite frame by index.
setSpriteFrame(id: number, renderableIndex: number, frame: number): Promise<void>
getRenderScale
Returns the renderable's scale as { x, y }.
getRenderScale(id: number, renderableIndex: number): Promise<Point>
setRenderScale
Sets the renderable's scale.
setRenderScale(id: number, renderableIndex: number, scale: Point): Promise<void>
getRenderColour
Returns the renderable's colour or tint as { r, g, b, a }. getRenderColor is also available as an alias.
getRenderColour(id: number, renderableIndex: number): Promise<Colour>
setRenderColour
Sets the renderable's colour or tint. Supports box, circle, text, sprite, panel, and mesh renderables. setRenderColor is also available as an alias.
setRenderColour(id: number, renderableIndex: number, colour: Colour): Promise<void>
getRenderLayer
Returns the renderable's layer (draw order).
getRenderLayer(id: number, renderableIndex: number): Promise<number>
setRenderLayer
Sets the renderable's layer.
setRenderLayer(id: number, renderableIndex: number, layer: number): Promise<void>
getRenderOffset
Returns the renderable's position offset.
getRenderOffset(id: number, renderableIndex: number): Promise<Point>
setRenderOffset
Sets the renderable's position offset.
setRenderOffset(id: number, renderableIndex: number, offset: Point): Promise<void>
getRenderEnabled
Returns whether the renderable is visible.
getRenderEnabled(id: number, renderableIndex: number): Promise<boolean>
setRenderEnabled
Shows or hides a renderable.
setRenderEnabled(id: number, renderableIndex: number, enabled: boolean): Promise<void>

Tile maps #

getTileCoord
Converts a world-space point to tile coordinates for the given tile-map renderable.
getTileCoord(id: number, renderableIndex: number, worldPoint: Point): Promise<Point>
getTile
Returns the tile ID at the given tile coordinate.
getTile(id: number, renderableIndex: number, tileCoord: Point): Promise<number>
setTile
Sets the tile ID at the given tile coordinate.
setTile(id: number, renderableIndex: number, tileCoord: Point, tileId: number): Promise<void>
getMapData
Returns the full tile data array (row-major uint16 values).
getMapData(id: number, renderableIndex: number): Promise<number[]>
setMapData
Replaces the full tile data array.
setMapData(id: number, renderableIndex: number, data: number[]): Promise<void>

Text #

setText
Updates the text string on a text-type renderable. For markup-free character-range colouring, resolve its handle with getRenderable and use Text Colour Areas.
setText(id: number, renderableIndex: number, text: string): Promise<void>

Animations #

addAnimation
Adds a keyframe animation to a renderable and returns its animation ID.
addAnimation(id: number, renderableIndex: number, keyframes: KeyFrame[]): Promise<number>
startAnimation
Starts playback of an animation by ID.
startAnimation(id: number, renderableIndex: number, animationId: number): Promise<void>
updateAnimation
Replaces an animation definition while preserving its ID. Active animations transition from their current pose.
updateAnimation(id: number, renderableIndex: number, animationId: number, keyframes: KeyFrame[]): Promise<void>
stopAnimation
Stops the renderable's current animation.
stopAnimation(id: number, renderableIndex: number): Promise<void>
onAnimationEnd
Registers a callback invoked when the animation completes, or clears it when callback is null.
onAnimationEnd(id: number, renderableIndex: number, animationId: number, callback: ((time: number): void) | null) : Promise<void>

Update handlers #

registerUpdate
Registers a per-frame update callback for the entity.
  • The callback receives delta (seconds since last call) and time (engine time).
  • Return a number to set the minimum delay (seconds) before the next invocation. Return 0 for every-frame updates.
registerUpdate(id: number, callback: (delta: number, time: number): number) : Promise<void>
registerLocalUpdate
Registers a local-only per-frame update callback for the entity on client-only boards.
  • The callback receives delta (seconds since last call) and time (engine time).
  • Return a number to set the minimum delay (seconds) before the next invocation. Return 0 for every-frame updates.
  • This callback runs only when the board is configured as client-only (Network.setClientOnly(true)).
  • registerLocalUpdate is not gated by entity ownership. Use it for local presentation logic (for example selection FX or UI-driven helpers) that should run for replicas.
  • It does not run on server-capable boards (including sibling simulation boards).
registerLocalUpdate(id: number, callback: (delta: number, time: number): number) : Promise<void>
interrupt
Cancels the entity's registered update handler.
interrupt(id: number): Promise<void>

Examples #

import * as Entity from 'Syncromesh/Entity';
import * as Simulation from 'Syncromesh/Simulation';

const id = await Simulation.spawn({
    position: { x: 0, y: 0 },
    body: {
        type: 'dynamic',
        fixture: [{ type: 'circle', radius: 0.5, restitution: 1.0 }]
    }
});

// Attach a sprite
const spriteIdx = await Entity.createRenderable(id, {
    type: 'sprite',
    texture: '/rom/sprites/hero.png',
    layer: 100,
    frames: [{
        size: { x: 16, y: 16 },
        origin: { x: 8, y: 16 },
        aabb: { min: { x: 0, y: 0 }, max: { x: 16, y: 16 } }
    }]
});

// Move with physics velocity
await Entity.setLinearVelocity(id, { x: 5, y: 0 });

// Register a per-frame update
await Entity.registerUpdate(id, (delta, time) => {
    // Game logic here
    return 0; // call every frame
});
← Syncromesh/SimulationSyncromesh/Camera →