Skip to main content

Composable entities

When no single factory matches what you need, start from create() and attach parts with .add(...). Parts are BaseNode children produced by mesh and collision helpers exported from @zylem/game-lib/entity. The composable API is how built-in factories such as createBox are implemented, and it is the extension point for custom shapes that still participate in spawn, clone, and collision registration.

Minimal example​

website/snippets/entities/composable-entities.ts:

import { create, boxMesh, boxCollision } from '@zylem/game-lib/entity';

const customBlock = create({ name: 'custom-block', position: { x: -1, y: 1, z: 0 } })
  .add(boxMesh({ size: { x: 2, y: 2, z: 2 }, color: '#4488ff' }))
  .add(boxCollision({ size: { x: 2, y: 2, z: 2 }, static: true }));

Mesh parts​

HelperGeometry
boxMeshBox
sphereMeshSphere
coneMeshCone
cylinderMeshCylinder
pyramidMeshPyramid
pillMeshCapsule-style pill

Mesh helpers accept size, color, and material overrides consistent with primitive factories.

Collision parts​

HelperRapier shape
boxCollisionBox
sphereCollisionBall
coneCollisionCone
cylinderCollisionCylinder
pyramidCollisionConvex hull
pillCollisionCapsule
planeCollisionStatic box under a plane
zoneCollisionSensor volume (see Zones)

Each collision part implements CollisionComponent so the entity builder can register bodies with the simulation.

Advanced composition​

  • Order — add mesh parts before collision parts if you rely on debug visualization; the builder merges all parts at spawn.
  • Bare entity — create() alone has no render or physics until you .add(...) at least one part.
  • Custom factories — wrap create(...).add(...) in your own function and pass the result through createEntityFactory for template spawning.

Pitfalls​

  • Mismatched mesh and collider dimensions produce visible gaps or invisible walls—keep size (or shape-specific fields) aligned.
  • Collision parts honor static, sensor, and filter fields on the part options as well as top-level GameEntityOptions.
  • Only entities from official helpers support clone(); if you subclass GameEntity directly, wire finalizeEntityCloneSupport the way built-in factories do.

API reference​