Appearance
Testing and debugging
An engine runs headless: without a canvas it skips drawing, and with a ManualDriver time moves only when the code says so. That makes game and dashboard logic testable with any test runner; Headless shows what runs without a page and how to write a scene for both. Three things help.
Random numbers from a seed
engine.random gives random numbers from a seed. The same seed gives the same numbers, so a run with a seed plays out the same way every time: in a test, a replay or a bug report. Use it instead of Math.random() in systems and behaviors.
ts
import { Engine } from "@pawnjs/core";
const engine = new Engine({ canvas, seed: 42 });
const { random } = engine;
random.next(); // 0..1, like Math.random()
random.range(-1, 1); // -1 up to (not including) 1
random.int(1, 6); // a die: 1, 2, 3, 4, 5 or 6
random.chance(0.1); // true one time in ten
random.pick(["runner", "tank"]);
random.shuffle([1, 2, 3]);- Without
seedthe engine picks a new one each time; read it back fromengine.random.seed, say to log it with an error and replay the run. random.stateis where the sequence is: save it and set it back to repeat the numbers from that point.random.reseed(seed)starts over.- Core behaviors that need chance (
burst,SoundOn's pitchvariation) useengine.random. Randomis also exported on its own:new Random(seed), ornew Random()for a seed fromRandom.newSeed()(Math.random()).
Test helpers
@pawnjs/core/testing creates engines for tests and moves them through time.
ts
import { Position, Velocity } from "@pawnjs/core";
import { createTestEngine, runFor, runUntil } from "@pawnjs/core/testing";
const engine = createTestEngine();
const ball = engine.world.spawn(Position, Velocity({ y: 1 }));
runFor(engine, 2); // two seconds in frames of 1/60 s
ball.get(Position)?.y; // 2
const seconds = runUntil(engine, () => (ball.get(Position)?.y ?? 0) > 5);
engine.dispose();createTestEngine(config?)is a headless engine driven only byengine.step(), withengine.randomseeded byTEST_SEED(1). AnyEngineConfiggoes over these defaults.runFor(engine, seconds, { step })steps the engine throughsecondsin equal frames (TEST_STEP, 1/60 s, unlessstepsays otherwise) and returns how many ran.runUntil(engine, done, { step, timeout })steps untildone()is true and returns the seconds it took; aftertimeoutseconds (60 by default) it throws.- Drive the pointer from code with
Pointer'smoveTo,pressandrelease; see Input.
Debug overlay and inspector
Debug shows what the engine is doing while an app is built: frames a second, milliseconds spent in each phase's systems, entities in the world and how many have each trait. Click an entity to inspect it: the panel lists its traits with their values, and numbers, switches, text and choices can be changed live.
ts
import { Debug } from "@pawnjs/core";
engine.use(new Debug({ visible: false })); // e.g. in development builds only
const debug = engine.plugin(Debug);
debug.visible = true; // or press ` (backquote, left of 1)
debug.select(entity);
const { fps, entities, phaseMs } = debug.stats;debug.selectedis the entity the inspector shows (select(undefined)clears it).- The backquote key shows and hides the overlay;
toggleKeychanges it (""for none).visiblesets whether it starts shown. - Clicking an entity while the overlay is shown selects it, once the engine has a
Pointer;enablePick: falseturns that off. statsholdsfps,phaseMs(milliseconds in systems per phase),systemsMs(all phases),entitiesandtraits(entities per registered trait, most first, without zeros).statsis averaged overintervalseconds (0.5 by default) andsubscribe(listener)hears each update and each new selection. Without a page (a test, a server), or withenableOverlay: false,Debugonly gathers the data.inspect(entity)returns the entity's traits, their params and values as data, for a panel of your own.- The inspector lists the traits in
engine.traits: core transforms,Tint,Shape, behaviors, and your own traits fromdefineTraitonce registered withengine.traits.register(Trait); see Saving scenes.