Syncromesh/Simulation - SyncroMesh Documentation

Entity creation, queries, and physics operations belong to child boards. The orchestrator exposes only lifecycle controls through this module, including quit. Examples below run inside a board script; see First simulation for setup.

Controls the simulation lifecycle and manages the entity pool. Entities are created with spawn and removed with destroy. The simulation owns the Box2D physics world, provides AABB-based spatial queries, and can create Box2D constraints (joints) between entity bodies.

Import #

Functions #

spawn

Creates a new entity and returns its ID.

See Spawn Options for the full shape of the options object.
The returned ID is used with all Syncromesh/Entity functions.

spawn(options: SpawnOptions): Promise<number>

destroy

Marks an entity for destruction.

destroy(id: number): Promise<void>

query

Returns entity IDs whose physics bodies overlap the given AABB.

Only entities with a physics body are included.
AABB shape: { min: { x, y }, max: { x, y } }.

query(area: AABB): Promise<number[]>

createConstraint

Creates a physics constraint (joint) and returns its constraint ID.

Supported types: distance, weld, prismatic, revolute.
Both entities must be active and have physics bodies.

createConstraint(options: ConstraintDef): Promise<number>

destroyConstraint

Destroys a previously created constraint.

destroyConstraint(constraintId: number): Promise<boolean>

isConstraintActive

Returns whether a constraint ID is currently active.

isConstraintActive(constraintId: number): Promise<boolean>

getEntityConstraints

Lists active constraint IDs attached to an entity.

getEntityConstraints(id: number): Promise<number[]>

getPhysicsSettings

Returns the current physics solver settings.

getPhysicsSettings(): Promise<PhysicsSettings>

setPhysicsSettings

Updates physics solver settings used for future simulation steps.

velocityIterations and positionIterations are clamped to the range 1..100.
Higher iteration counts can improve fast-body and constraint stability at higher CPU cost.

setPhysicsSettings(settings: Partial<PhysicsSettings>): Promise<void>

setRunState

Sets the engine run state.

See the RunState table below for values.

setRunState(state: number): Promise<void>

quit

Signals the engine to quit.

quit(): Promise<void>

Spawn options #

SpawnOptions

Configuration object passed to spawn().

position Point optional - Initial world position { x, y }.
body BodyOptions optional - Physics body configuration. Omit for a non-physical entity.
renderable RenderDescriptor[] optional - Array of renderable descriptors to attach at spawn time. Includes GPU particle emitters; see GPU Particles.

BodyOptions

Physics body definition.

type string - "static", "dynamic", or "kinematic". Defaults to static.
linearDamping number optional - Linear velocity damping factor.
bullet boolean optional - Enables Box2D bullet mode for fast dynamic bodies to reduce tunneling through other moving bodies. Use sparingly.
fixture FixtureDef[] optional - Array of fixture definitions to attach to the body.

PhysicsSettings

Physics solver settings used when stepping the Box2D world.

velocityIterations number - Box2D velocity solver iterations. Defaults to 2.
positionIterations number - Box2D position solver iterations. Defaults to 2.

Constraint options #

ConstraintDef

Base shape for all createConstraint() options.

type string - "distance", "weld", "prismatic", or "revolute".
entityA number - First entity ID.
entityB number - Second entity ID.
collideConnected boolean optional - If true, attached bodies can still collide.

DistanceConstraintDef

Distance (spring/rope-like) constraint in world space.

type string - "distance"
anchorA Point optional - World-space anchor on entityA (defaults to body center).
anchorB Point optional - World-space anchor on entityB (defaults to body center).
length number optional - Rest length.
minLength number optional - Minimum allowed length.
maxLength number optional - Maximum allowed length.
stiffness number optional - Linear stiffness.
damping number optional - Linear damping.

WeldConstraintDef

Weld (rigid attach) constraint.

type string - "weld"
anchor Point optional - World-space weld anchor (defaults to body center of entityA).
referenceAngle number optional - Reference bodyB-bodyA angle in radians.
stiffness number optional - Rotational stiffness.
damping number optional - Rotational damping.

PrismaticConstraintDef

Prismatic (slider) constraint.

type string - "prismatic"
anchor Point optional - World-space anchor (defaults to body center of entityA).
axis Point optional - World-space axis direction (defaults to { x: 1, y: 0 }).
referenceAngle number optional - Reference bodyB-bodyA angle in radians.
enableLimit boolean optional - Enable translation limits.
lowerTranslation number optional - Lower translation limit.
upperTranslation number optional - Upper translation limit.
enableMotor boolean optional - Enable motor.
motorSpeed number optional - Motor speed.
maxMotorForce number optional - Maximum motor force.

RevoluteConstraintDef

Revolute (hinge) constraint.

type string - "revolute"
anchor Point optional - World-space hinge anchor (defaults to body center of entityA).
referenceAngle number optional - Reference bodyB-bodyA angle in radians.
enableLimit boolean optional - Enable angular limits.
lowerAngle number optional - Lower angle limit in radians.
upperAngle number optional - Upper angle limit in radians.
enableMotor boolean optional - Enable motor.
motorSpeed number optional - Motor speed in radians/sec.
maxMotorTorque number optional - Maximum motor torque.

RunState #

Value	Name
0	STOPPED
1	HEADLESS
2	START
3	RUNNING
4	PAUSED
5	STOP
6	QUIT
7	RELOAD

Examples #

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

// Spawn two dynamic entities
const a = await Simulation.spawn({
    position: { x: 100, y: 50 },
    body: { type: 'dynamic', fixture: [{ type: 'box', size: { x: 1, y: 1 }, density: 1.0 }] }
});
const b = await Simulation.spawn({
    position: { x: 104, y: 50 },
    body: { type: 'dynamic', fixture: [{ type: 'box', size: { x: 1, y: 1 }, density: 1.0 }] }
});

// Connect them with a distance constraint
const constraintId = await Simulation.createConstraint({
    type: 'distance',
    entityA: a,
    entityB: b,
    length: 4.0,
    stiffness: 4.0,
    damping: 0.8
});

// Query nearby entities
const nearby = await Simulation.query({
    min: { x: 90, y: 40 },
    max: { x: 110, y: 60 }
});

// Cleanup
await Simulation.destroyConstraint(constraintId);
await Simulation.destroy(a);
await Simulation.destroy(b);

<- SyncroMesh: 0.5.0 → 0.6.0 migration Syncromesh/Entity ->