Skip to content

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 seed the engine picks a new one each time; read it back from engine.random.seed, say to log it with an error and replay the run.
  • random.state is 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 pitch variation) use engine.random.
  • Random is also exported on its own: new Random(seed), or new Random() for a seed from Random.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 by engine.step(), with engine.random seeded by TEST_SEED (1). Any EngineConfig goes over these defaults.
  • runFor(engine, seconds, { step }) steps the engine through seconds in equal frames (TEST_STEP, 1/60 s, unless step says otherwise) and returns how many ran.
  • runUntil(engine, done, { step, timeout }) steps until done() is true and returns the seconds it took; after timeout seconds (60 by default) it throws.
  • Drive the pointer from code with Pointer's moveTo, press and release; 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.selected is the entity the inspector shows (select(undefined) clears it).
  • The backquote key shows and hides the overlay; toggleKey changes it ("" for none). visible sets whether it starts shown.
  • Clicking an entity while the overlay is shown selects it, once the engine has a Pointer; enablePick: false turns that off.
  • stats holds fps, phaseMs (milliseconds in systems per phase), systemsMs (all phases), entities and traits (entities per registered trait, most first, without zeros).
  • stats is averaged over interval seconds (0.5 by default) and subscribe(listener) hears each update and each new selection. Without a page (a test, a server), or with enableOverlay: false, Debug only 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 from defineTrait once registered with engine.traits.register(Trait); see Saving scenes.