Syncromesh/Simulation — SyncroMesh Documentation

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 enum on the overview page 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);

← Standard Library: Entity System Syncromesh/Entity →