Appearance
Instancing
A Visual per entity means one Object3D and usually one draw call each. For thousands of similar entities, draw them as instances of one InstancedMesh instead:
ts
import { Instance, InstanceBatch, Position } from "@pawnjs/core";
import { Color, IcosahedronGeometry, MeshStandardMaterial } from "three";
// One batch, one draw call, however many entities point at it.
const batch = new InstanceBatch({
geometry: new IcosahedronGeometry(0.1),
material: new MeshStandardMaterial(),
capacity: 10_000, // optional; grows by doubling when full (default 1024)
});
const color = new Color();
for (let i = 0; i < 10_000; i++) {
const entity = engine.world.spawn(
Position({ x: engine.random.range(0, 10), y: 0, z: engine.random.range(0, 10) }),
Instance(batch),
);
batch.setColor(entity, color.setHSL(i / 10_000, 0.8, 0.6));
}Here 4,900 boxes of one batch ride a wave, in one draw call:
ts
import {
Engine,
Instance,
InstanceBatch,
Position,
type System,
View,
} from "@pawnjs/core";
import { trait } from "koota";
import {
AmbientLight,
BoxGeometry,
Color,
DirectionalLight,
MeshStandardMaterial,
PerspectiveCamera,
} from "three";
const SIDE = 70; // 4,900 boxes, one draw call
/** Where an entity sits on the floor, for the wave. */
const Cell = trait({ x: 0, z: 0 });
const wave: System = ({ world, elapsed }) => {
world.query(Cell, Position).updateEach(([cell, position]) => {
const d = Math.hypot(cell.x, cell.z);
position.y = Math.sin(d * 0.35 - elapsed * 2.5) * 0.6;
});
};
export default function instancing(canvas: HTMLCanvasElement): Engine {
canvas.style.cssText = "display:block;width:100%;height:100%";
const engine = new Engine({ canvas });
engine.addSystem(wave);
engine.scene.add(new AmbientLight(0xffffff, 0.6));
const sun = new DirectionalLight(0xffffff, 2);
sun.position.set(5, 10, 3);
engine.scene.add(sun);
const batch = new InstanceBatch({
geometry: new BoxGeometry(0.8, 0.8, 0.8),
material: new MeshStandardMaterial(),
capacity: SIDE * SIDE,
});
const color = new Color();
for (let i = 0; i < SIDE; i++) {
for (let j = 0; j < SIDE; j++) {
const x = i - SIDE / 2;
const z = j - SIDE / 2;
const box = engine.world.spawn(
Position({ x, z }),
Cell({ x, z }),
Instance(batch),
);
batch.setColor(box, color.setHSL(0.6 + (i + j) / (SIDE * 8), 0.7, 0.6));
}
}
const camera = new PerspectiveCamera(45, 1, 0.1, 200);
camera.position.set(0, 30, 45);
camera.lookAt(0, -4, 0);
engine.views.add(new View({ camera, background: 0x09090b }));
engine.fitToElement(canvas);
engine.start();
return engine;
}- Adding
Instancealso addsPosition,RotationandScalewhen missing. Keep them while the entity is instanced. - The engine writes instance matrices from the transform traits in the
renderphase; noObject3Dexists per entity. batch.setColor(entity, color)sets a per-instance color, multiplied with the material color. New instances start white;batch.getColor(entity, target)reads it back.batch.setMatrix(entity, matrix)writes an instance's matrix at once (for picking before the next render); the next render writes it again from the transform traits.batch.indexOf(entity)andbatch.entityAt(index)map between entities and instance indices, e.g. for a raycast hit'sinstanceId.- The batch's mesh joins the scene with its first entity and leaves it when the batch empties. Settings on
batch.mesh(shadows, for example) survive growth. - Picking maps the hit instance back to its entity, like a
Visual. - Use either
InstanceorVisualon an entity, not both. - Instances are drawn in world space and ignore
ChildOf.
Geometry and material belong to you. batch.dispose() releases only the batch's own instance buffers.
Instanced shapes
A Shape with enableInstancing is drawn as an instance without a batch of your own: the engine keeps one batch per kind of shape and colors each instance with the shape's color.
ts
import { Position, Scale, Shape } from "@pawnjs/core";
for (let i = 0; i < 1000; i++) {
engine.world.spawn(
Shape({ kind: "sphere", color: "#38bdf8", enableInstancing: true }),
Position({ x: engine.random.range(-10, 10), z: engine.random.range(-10, 10) }),
Scale({ x: 0.2, y: 0.2, z: 0.2 }),
);
}Tint, hover and clicks work on instanced shapes as on meshes.- Changing
kindmoves the entity to that kind's batch; turningenableInstancingoff gives it a mesh of its own again. - Instances are drawn in world space, so a shape under a
ChildOfparent stays a mesh. burst()throws instanced spheres.
Measured
Measured headless with 100,000 moving entities (bun run bench in packages/core), a frame takes about 12 ms with Instance or instanced Shape, about 46 ms with a Shape mesh each and about 100 ms with a Visual each; drawing, which instancing cuts to one call per batch, comes on top. The Swarm example shows it live.