A serialisable capture of an Rng's full internal state.

seed is the stream's identity and never changes with drawing; state is the cursor and advances once per draw. Both are uint32, so this round-trips through JSON losslessly — which is what lets persist store a stream mid-run and resume the exact sequence. Store only one of the two fields and the resumed run either repeats itself or diverges.

One deterministic random stream (mulberry32).

Instances are mutable — each draw advances the cursor — and must not be shared between subsystems. Two subsystems on one stream means the contents of each depend on how often the other drew, which is a bug that only ever shows up as "the world changed when I opened the menu". Use Rng.derive instead; that is the entire reason it exists.

Construct with createRng, or with Rng.fromSnapshot to resume a saved one.

Create a stream from a numeric or string seed.

The seed is hashed first, so 1, 2, 3 — or 'level-1', 'level-2' — are well-separated streams and not correlated ones. Pass the key itself, not a pre-hash of it: createRng(hashString(key)) hashes twice, which is harmless but reads as though the first hash were load-bearing, and someone will later optimize away the wrong one.

This is also the answer to "materialise a stream from a key that already identifies the thing": per-instance sprite variation from createRng(spriteKey) is identical whether the sprite is drawn directly, drawn into a cache, or redrawn after an eviction. Allocation is fine there — an Rng is a two-field object and one per cache miss is nothing. One per sprite per frame is not; that case wants hash2/hash3 with toUnit, which allocates nothing and needs no stream at all.

murmurhash3's 32-bit finaliser (fmix32) — an avalanche bijection over uint32.

Why it exists: seeds arrive in narrow ranges (0, 1, 2; tick indices; entity ids). Fed to a generator raw, adjacent inputs produce visibly correlated first draws — three worlds that share their first tree. This spreads them across the whole 32-bit space first, so 1 and 2 are unrelated rather than adjacent.

Being a bijection, it never collides and it has exactly one fixed point: mix32(0) is 0. Do not read a zero result as "this value was never hashed", and do not build a fold out of mix32 and ^ alone — see hashStep.

value is taken modulo 2^32 (ToUint32), so fractions truncate toward zero and negatives wrap; non-finite input becomes 0 rather than throwing, because this is the primitive every other function here is built from and a throw belongs at the boundary.

Deterministic 32-bit hash of a string (xmur3-style mixing, fmix32 finalise).

Hashes by UTF-16 code unit, so 'é' as U+00E9 and as U+0065 U+0301 hash differently, and an astral-plane character is hashed as its two surrogates. Normalize (value.normalize('NFC')) before hashing anything that crosses a platform boundary or a save file: a player name typed on macOS and on Windows otherwise seeds two different worlds, and the bug reproduces on nobody's machine. This is the one portability seam in the package, and it is a seam rather than a defect because normalising here would cost every call site an allocation to protect the few that need it.

The length is folded in, so 'a\0' and 'a' differ. 32 bits is a birthday collision at ~77,000 distinct inputs: plenty for cache keys and corruption detection, not a content-address, and never cryptographic.

Fold an arbitrary finite number into a uint32 without discarding its high bits.

Timestamps (~1.7e12) and generated ids both exceed 2^32, and a bare value >>> 0 throws away everything above bit 31 — so a million distinct ids collapse onto a few thousand hashes and two saves an hour apart key the same cache entry. This truncates toward zero and mixes the high and low halves together instead.

hashNumber(0) is 0, inherited from mix32's fixed point. That is safe for a seed (mulberry32's increment is odd, so a zero state is an ordinary state) and is exactly why hashStep carries an odd constant.

Fold one more value into a running hash. This is the general mechanism; everything below is a convenience over it.

hash2 and hash3 are literally two and three of these, unrolled — not separate algorithms — which is why there is no hash4 and never will be. Four coordinates is hashStep(hashStep(hashStep(hashStep(seed, a), b), c), d): still one expression, still allocation-free, still the same avalanche. A package that needs five does the same thing, and nothing gets added to core.

The step avalanches the incoming value before combining it and avalanches the accumulator after, which is what makes the result non-linear in every argument independently. Combining raw (31 * x + 17 * y, then one mix at the end) passes a naive uniformity test and still bands diagonally, because equal values of 31x + 17y lie on a line and no single final mix can separate them again.

It is order-sensitive by construction — the nesting differs, so (a, b) and (b, a) fold to different values.

value is truncated to int32 (ToUint32 semantics); accumulator likewise.

Combine parts into one uint32, non-commutatively: hashParts('a', 'b') and hashParts('b', 'a') differ. That is what makes (worldSeed, chunkX, chunkY) a usable key rather than one that aliases its own transpose.

A hashStep fold, with string parts routed through hashString first. The part count participates, so hashParts('a', 'b') and hashParts('ab') also differ.

Variadic, so it allocates a rest array, and it accepts strings. Setup and cache keys, not the hot path — use hash2, hash3 or hashStep for numbers in a loop.

White noise from a coordinate pair: a uint32 that is a pure function of (seed, x, y) and nothing else. No stream, no cursor, no allocation.

This is the per-tile variation primitive — grass tint, prop rotation, whether this cobble is the cracked one. Drawing that from an Rng instead ties every tile's appearance to the order tiles were visited, so the valley reshuffles the first time anything culls, batches or re-sorts, and the bug presents as "the world changed when I bought a lamp". The stateless form is toUnit(hash2(seed, tx, ty)) < 0.1.

The seed argument is not optional and not decorative: two systems sampling the same tile (tree jitter and grass tint) must not receive the same number, or the jitter and the tint correlate and the field reads as a visible grid. Give each system its own constant, or rng.derive('grass').seed.

x and y are truncated to int32. Fractional coordinates therefore hash to their integer cell — which is what a tile lookup wants, and a surprise to anyone passing world pixels. Truncation is toward zero and not Math.floor, so -0.5 and 0.5 land in the same cell 0: west and south of the origin, a fractional coordinate belongs to the cell on the origin's side of it. Floor the coordinate yourself if the cells must be uniform across the axes — which they must be for anything the player can walk past.

The same, over three integers — hash2 plus one hashStep.

It exists because two packages arrived at it independently from different domains: iso samples a tile grid by (x, y) and needed a third axis for layers; audio's sequencer rolls per (bar, step, track), where there is no stream position to advance and no ordering guarantee between tracks — a track muted at load must not shift what every other track plays.

Beyond three axes, fold with hashStep directly. That is the whole point of hashStep being exported.

Digest an integer array — a frame buffer, a serialized save, any byte sequence.

draw's headless renderer digests a rendered frame to compare against a golden; persist digests a serialized save to detect corruption. Neither can reach hashString without first turning a megabyte of bytes into a string, which allocates the megabyte again to hash it once.

Values are truncated to int32, like every other input in this module. That is correct for Uint8Array, Uint8ClampedArray and integer arrays generally, and silently wrong for a Float32Array — every value between -1 and 1 truncates to zero, so the digest of a normalized buffer becomes a digest of its length and two completely different frames compare equal. View the bytes instead: new Uint8Array(floats.buffer, floats.byteOffset, floats.byteLength).

The length is folded in first, so a run of trailing zeroes cannot be dropped without changing the digest — which is how a truncated save otherwise passes its own checksum. A hole in a sparse array counts as 0.

A uint32 as a float in [0, 1) — exactly hashed / 2**32, the same normalization Rng.next uses, so a hashed value and a drawn value are interchangeable in any threshold test.

It must be / 4294967296 and not / (2**32 - 1) or * 2.3283064365386963e-10: the first is not a power of two so the division rounds, and the second is a rounded literal of the same thing. Either one quietly stops the result being bit-identical, which is the whole promise being made here.

Exists so hash2 can stay integer-valued — a caller who wants a bucket wants % n, not a float they immediately re-scale — without every consumer writing the magic constant. Input is reduced with >>> 0, so a signed int32 from a caller's own bit twiddling cannot produce a negative "probability".

2D gradient noise in [-1, 1]. A pure function of (seed, x, y): no cursor, no setup, no permutation table.

Integer coordinates land on lattice points and return exactly 0 (positive zero, so Object.is(noise2(s, 1, 1), 0) holds and a saved value survives a JSON round trip) — sample at a fractional scale (x * 0.06) or you will get a field of zeroes and conclude the noise is broken. That is a property of gradient noise and not a bug: the gradient at a lattice point is dotted with a zero distance vector.

The seed argument separates fields that sample the same coordinates. Two systems on one seed (height and moisture, say) receive the same field and the map reads as one feature painted twice; give each its own constant or rng.derive('moisture').seed.

Coordinates must stay under ~2^24 in magnitude. Beyond that the fractional part loses resolution and the field visibly flattens; beyond 2^31 the lattice indices wrap, and the field repeats.

3D gradient noise in [-1, 1].

The third axis is usually time — which is how a zero-asset kit animates water, smoke and glow without storing a single frame. Advance z by elapsed * rate and the field flows; because it is a pure function, the same z always renders the same frame, so a replay and a screenshot test both stay stable.

Same contract as noise2: integer coordinates return exactly 0, and every axis must stay under ~2^24.

Fractal Brownian motion: octaves layers of noise2, each at twice the frequency and gain times the amplitude, normalized back into [-1, 1].

The normalization is the point. Un-normalized fBm has a range that depends on the octave count, so raising the detail of a terrain silently changes its sea level — the coastline moves and nobody connects it to the slider they nudged.

Each octave is sampled from its own derived seed rather than from the same field at a doubled frequency, so no two layers share lattice points and the sum has no residual grid in it.

Lacunarity is fixed at 2 rather than exposed: it is the only value anyone uses, it is a power of two (so the frequency ladder stays exact), and a fourth positional number here would be write-only code at every call site.

fBm over noise3. Same contract, same normalization, same octave separation.

Full turn in radians.

Present because 2 * Math.PI otherwise appears in every package in the kit and half of them eventually write 6.28, which is a fifth of a degree short and shows up as a seam where a swept arc fails to close.

The kit's default comparison tolerance: 1e-9.

Deliberately not Number.EPSILON, which is the gap between representable doubles near 1.0 (~2.2e-16) and is a property of the format rather than of the game. Comparing world positions against Number.EPSILON means "approximately" never returns true and every settle-detection loop runs forever.

Constrain value to [min, max].

NaN propagates rather than snapping to a bound: both comparisons are false, so a NaN comes back out. That is the wanted behavior — a clamp that silently turned NaN into min would hide the division by zero that produced it until it reached the screen.

clamp(value, 0, 1). The normalized-time and normalized-progress case, which is most of them; spelled out so call sites do not carry two magic numbers.

Linear interpolation, in the precise form (1 - t) * a + t * b.

NOT a + (b - a) * t, which is one operation cheaper and does not return exactly b at t === 1. A tween that ends at 0.9999999 of its target leaves a sprite a sub-pixel off its tile forever, which presents as text that looks slightly blurry and never as a bug in the tween. No test that checks "approximately" catches it, so the form is the contract: lerp(a, b, 0) === a and lerp(a, b, 1) === b, exactly, for every finite pair.

Unclamped: t outside [0, 1] extrapolates, which is what makes it usable for overshoot.

Where value sits between a and b, as a fraction. The inverse of lerp.

Returns 0 when a === b rather than NaN, because the degenerate case is a progress bar with no range or a gradient with one stop — a display with nothing to show, not an arithmetic fault. A NaN here would propagate through the whole layout before anyone saw it, and it would surface as an invisible element rather than as a divide by zero.

Move value from one range to another: inverseLerp then lerp, unclamped.

The workhorse for turning a noise sample in [-1, 1] into a game quantity, or a progress value into a pixel. Unclamped because clamping is a separate decision — a caller that wants the ends held calls clamp on the result and can see it doing so; a caller that wants extrapolation cannot recover it from a version that clamped.

A zero-width input range yields outMin, following inverseLerp.

Hermite smoothstep, clamped to [0, 1].

The zero derivative at both endpoints is the entire point: a linear fade meets flat color at an angle, and the eye reads that discontinuity in the slope as a visible band even though the value itself is continuous. Fog, vignettes, distance culling and audio crossfades all want this rather than clamp01.

edge0 === edge1 returns 0 rather than NaN, per inverseLerp.

Euclidean modulo: the result carries the sign of divisor, never of value.

-1 % 8 is -1 in JavaScript, which indexes off the front of every wrap-around table in the kit — tile lookups west of the origin, hue wrapping below zero, a ring buffer stepped by a negative delta. Each of those reads as a rendering glitch in one quadrant of the map, never as an arithmetic mistake. Use this and never the operator on a value that can be negative.

mod(v, 0) is NaN, as the operator is: a zero divisor has no answer to give.

Wrap value into the half-open range [min, max).

Half-open on purpose: max maps back to min, so an angle of exactly TAU and an angle of 0 are the same heading and a tiling coordinate at the seam belongs to exactly one tile. A closed range would let two representations of one position compare unequal.

Built on mod, so negative inputs behave.

Step at most maxDelta toward target, never overshooting.

The Tier A alternative to damp for anything a replay depends on: constant speed, exact arithmetic, and it arrives — it reaches target exactly and stays, where exponential smoothing only ever approaches. Use it for a build timer, a resource transfer, or any motion whose end state is compared for equality.

A negative maxDelta holds position rather than stepping away from the target: a negative distance is a sign error at the call site, and turning it into motion nobody ordered is how it stays hidden.

Frame-rate-independent exponential smoothing — the correct form of "ease toward target".

current += (target - current) * 0.1, the version everyone writes, converges at a rate proportional to frame rate: twice as fast at 120Hz as at 60Hz, and differently again on a machine that drops frames. The camera then follows tighter on a better monitor, which nobody files a bug for and everybody feels. This takes dt and a rate lambda (larger is snappier, units of 1/second) and lands in the same place at any step size.

lambda * dt is the whole model: at lambda = 1 the remaining distance falls by a factor of e per second.

Absolute-difference comparison against epsilon (default EPSILON), inclusive.

Named approx and not equals so that no call site can be read as an exact comparison — the name is the documentation at the place it is needed. Use it for settle detection and for tests; never for a value that keys a map or gates a save, where two "equal" values must be Object.is-equal.

NaN is never approximately anything, including itself.

A curve from normalized time to normalized progress.

The contract a consumer may rely on: e(0) === 0 and e(1) === 1 exactly, and e is finite across [0, 1]. Inputs outside [0, 1] are the caller's problem — most curves here extrapolate rather than clamp, so a tween that overruns its duration must clamp t before the call, not after.

The name of a built-in curve.

A union of string literals rather than an enum so that { ease: 'backOut' } in a config file, a level definition or a save is checked by the compiler with no import and no runtime value. Adding a name here is a breaking change for anything that persisted the old one.

Identity. Present so that "no easing" is a value rather than a null check at every call site that takes an Easing.

Accelerates from rest. Use for something leaving the screen — an object that starts slow and speeds up reads as departing, and the reverse reads as arriving.

Decelerates into rest. The default for anything appearing: it is the cheapest curve that does not stop dead.

Symmetric ease-in-out. The general-purpose move between two resting states.

Accelerates harder than quadIn.

Decelerates harder than quadOut, and the most-reached-for curve in the kit: most of the motion happens in the first third, so the eye registers the change immediately and the settle is still smooth.

Symmetric cubic ease-in-out.

Decelerates harder still — the "expensive" feel for a panel that slides in. This is the curve to reach for instead of an expo easing, which would cost the module its Tier A guarantee for a difference nobody can see.

Pulls back below 0 before moving. Anticipation without a spring simulation.

Because it leaves [0, 1], never drive an index, an array position, a color channel or anything clamped with it — the excursion is the effect, and clamping it away leaves a curve that visibly stalls at its start.

Written as t³ + c·t²(t - 1) rather than the textbook (c+1)t³ - c·t². They are the same polynomial and they are not the same arithmetic: the textbook form ends at 0.9999999999999998 and starts at -0, and this one is exact at both ends.

Overshoots past 1 and settles back. The same warning as backIn: it leaves [0, 1].

Four decaying bounces, piecewise quadratic.

Chosen over the usual damped sine so the whole module stays Tier A — see the module note. It stays inside [0, 1] and touches 1 at each bounce apex, so it is safe on a clamped value, unlike the back pair.

smoothstep(0, 1, t): symmetric, zero derivative at both ends. Clamped, so — with smoother — it is one of the two curves here that tolerate a t outside [0, 1] rather than extrapolating into a shape nobody designed.

Ken Perlin's quintic: zero second derivative at both ends as well as the first.

Use it when the curve drives a value that is itself differentiated — a camera pan, where a discontinuity in acceleration reads as a jolt at the start and end of the move even though the position and the velocity are both continuous.

Every curve above, keyed by name.

This is what lets a tween be authored as data — { ease: 'backOut' } in a config object, a level file or a save — without every consumer growing its own string-to-function switch, each with a different fallback for an unknown name. loop's tween API takes Easing | EasingName and resolves through this table.

A frozen object literal, not a table built by a loop: a loop would run on every import of the package, including in a bundle that only wanted clamp.

Run a curve backwards: reverse(quadIn) is the corresponding out-curve.

A combinator instead of thirty more constants — and the reason the table above has no quartIn or bounceIn. Allocates one closure per call, so hoist it to module scope or build it at setup; calling reverse inside a frame allocates a function per frame, which is the shape of garbage collection pause that non-negotiable #7 exists to prevent.

Endpoints survive: if e(0) === 0 and e(1) === 1, so does the reversal.

Mirror an in-curve into a symmetric in-out curve: the first half is the curve at double speed and half scale, the second half is its reflection.

Same reason as reverse, and the same allocation warning. inOut(quadIn) reproduces quadInOut to within rounding; the named constants exist because they are one polynomial rather than two calls, and this exists for the curves that have no named in-out form.

A mutable 2D point — the storage, scratch and output type of the whole kit.

Mutable on purpose: an out-parameter API cannot take a readonly type, and making the fields readonly here would force a second writable interface into every signature that fills one. Declare your variables and your entity fields as this — there is deliberately no MutableVec2 in the kit, because there is only ever one type a caller declares.

The read side. Use it for any parameter a function does not write to.

Vec2 is assignable to it, so a caller never converts and no call site has to choose. The reverse is not, which is what stops a frozen shared constant — const ORIGIN: ReadonlyVec2 = Object.freeze(v2(0, 0)) — being handed in as an output parameter. That rejection happens at compile time, where the alternative is a TypeError thrown in strict mode on the one frame that path executes, in the one build nobody type-checked.

Allocate a vector.

The one function here that allocates, and the reason every other one does not. Call it at setup, when an entity is created, or to build the scratch vectors a system reuses — never inside a loop that runs per frame or per entity. If you find yourself writing v2( inside a render pass, the fix is a scratch vector hoisted to module or system scope.

Write components into out. The assignment form, so a system can set a position without naming both fields at every call site and without allocating a temporary to copy from.

Copy a into out. This — not assignment — is how a value escapes a scratch vector: p = scratch aliases the scratch and every later write to it silently moves p.

out = a + b.

out = a - b. Note the order: this is the vector from b to a, which is the direction a "look at" or a separation impulse needs reversed.

out = a * scalar.

out = a + b * scalar — the integration step, without a temporary.

v2AddScaled(pos, pos, velocity, dt) is one call where the obvious spelling is a scale into a scratch and then an add. It exists because that scratch is per entity per frame in the only code path that runs for every entity every frame.

out = (1 - t) * a + t * b, component-wise and unclamped.

Written in the same expensive form as lerp for the same reason: at t === 1 it lands on b exactly, so a tween that finishes leaves the sprite on its tile rather than a sub-pixel off it forever.

Dot product. Zero when perpendicular; its sign says whether b points with or against a, which is how a facing test is written without a single trig call.

The z component of the 3D cross product.

The sign tells you which side of a the point b lies on — positive is counter-clockwise. This is how iso decides facing and polygon winding, and it is exact: a comparison of two cross products orders two directions without an atan2 anywhere, which keeps depth sorting in Tier A.

Squared length. Prefer it to v2Len for comparisons and radius tests: it is exact where the square root is merely correctly rounded, and it is a multiply instead of a sqrt.

Length. Math.sqrt is one of the operations ECMA-262 specifies exactly, so this stays Tier A — unlike Math.hypot, which is not specified exactly and is slower.

Squared distance. The one to use inside a proximity loop — see v2LenSq.

Distance between two points.

Unit vector in the direction of a, or (0, 0) when a has no length.

Returning (0, 0) rather than NaN is deliberate and is the single most valuable decision in this module. A NaN position propagates silently through a whole scene graph — every add, every lerp, every projection downstream of it — and surfaces as an invisible sprite three systems away from the zero-length subtraction that caused it. A zero vector is wrong in an obvious, local, debuggable way.

A NaN or infinite input yields (0, 0) for the same reason, as does a vector whose squared length overflows to Infinity (components beyond ~1e154) — there is no direction to recover once the sum has saturated, and the alternative is NaN again.

The squared length is also where the precision floor sits: components below ~1e-154 square into the subnormal range and the direction loses digits, and below ~1e-162 they underflow to zero and this returns (0, 0). No game coordinate is within a hundred orders of magnitude of that, which is why the fast form is the right one.

Rotate 90° counter-clockwise: (-y, x).

Exact, no trigonometry, and it is what almost every "perpendicular" in a game actually needs — a normal for a wall segment, an offset for a parallel line, the side vector of a heading. Note the local reads in the body: written the obvious way, v2Perp(a, a) would clobber a.x before reading it and produce (-y, -y).

Component-wise comparison within epsilon (default EPSILON), inclusive. Named approx and not equals so that no call site reads as exact — two positions that pass this may still hash and serialize differently.

Rotate a counter-clockwise by radians.

The direction of a as an angle in (-PI, PI], measured counter-clockwise from +x.

v2Angle(0, 0) is 0 because that is what Math.atan2(0, 0) returns — a zero vector has no direction, and the value is meaningless rather than wrong. Check the length first if the distinction matters.

Build a vector of the given length (default 1) pointing at radians.

Milliseconds since the Unix epoch — wall-clock calendar time, as Date.now() returns it.

It answers "what time is it", it survives a reload, and it is the only kind of time that may be written to a save file. It can also jump backwards: an NTP correction, a timezone change, or a player setting their clock forward to skip a build timer all move it. Anything that subtracts two of these must tolerate a negative result — and must never feed it to an integrator as a frame delta, which runs the simulation backwards.

Branded, so a monotonic reading cannot be assigned here by accident. The brand is erased at runtime: it costs one call to asEpochMillis at the single Date.now() the kit permits, plus a re-brand after arithmetic, because epoch + 1000 widens to number. That widening is a feature — epochA - epochB is a duration, not an instant, and the type saying so out loud is worth the keystroke.

Milliseconds from an arbitrary origin — monotonic time, as performance.now() returns it.

It answers "how long since", it never goes backwards, and it is meaningless in a save file: the origin is the document, so a value stamped before a reload compares against a different zero afterwards. It may also freeze while the machine sleeps, which is why loop clamps catch-up and credits nothing for the gap.

Branded for symmetry, and because the confusion runs both ways: using a calendar reading as a frame delta is trap 29, and it is just as expensive.

The calendar: the game's single wall-clock reading, injected.

There is exactly one of these per application, the game owns it, and it is almost always () => asEpochMillis(Date.now()). persist takes one to stamp a save; sim takes one to integrate to the present. Injecting it is what lets a test run a year of offline accrual in a millisecond, and what lets lint ban the global read everywhere else.

The stopwatch: a monotonic reading, injected. Usually () => asMonotonicMillis(performance.now()).

A separate type from Now so the two cannot be swapped at an injection site — which is the failure this whole module exists to prevent, and which no amount of documentation on a number prevents on its own. Use it for cadence and elapsed time; use Now for the calendar.

Brand a number as calendar time, at the one boundary where a real clock is read — or where a stored value is read back.

Use it rather than value as EpochMillis. The brand is erased at runtime, so a cast is a claim about data you did not produce: a save hand-edited to "lastSeen": null becomes an EpochMillis of null under a cast, and every later subtraction is NaN with no exception anywhere near the cause. This function is a real check.

Validates finite and nothing else, deliberately. A range check that rejected "this looks like seconds, not milliseconds" would also reject 0 and 1000, which is what every manual clock in every test starts at — so the unit lives in the name and nowhere else. Never divide an EpochMillis by 1000 and keep the type.

The check is guard's expectFinite, not a hand-written one, so this error reads like every other error in the package.

Brand a number as a monotonic reading. As asEpochMillis, for the stopwatch.

The same finite-only check, and the same reason: an origin is arbitrary, so no range is wrong. Note that this cannot tell you the value really came from a monotonic source — it brands what you hand it. Call it at the injection site, next to the performance.now(), and nowhere else.

Undo one thing.

Idempotent by contract. Calling a disposer twice must be safe and must not undo something else. The failure this rule exists to prevent: a handle is released, its slot is reused by somebody else, and the second call to the stale disposer releases their handle — a bug that presents as a completely unrelated subsystem losing its subscription. Every disposer the kit returns satisfies it, and every disposer a game writes is expected to.

A Scope calls each disposer exactly once, so idempotence is not for the scope's benefit: it is for the caller that also holds the disposer directly and disposes early.

A teardown tree. One per scene, screen, or anything else with a lifetime.

The shape input proved and the kit adopts: a package ships no free-function binder, so a listener can only be created through a scope and an unowned listener is unconstructable. That turns "remember to unsubscribe" from documentation into something the type system enforces, which is the difference between a guarantee and a hope.

This is an interface with a factory rather than a class, deliberately. input had already built one before this module existed; a structural type lets it conform without inheriting anything. Five packages agreeing on a shape is the goal — five packages extending a base class is a different and worse thing.

Build an empty scope.

No arguments and no options on purpose — a scope with a policy would be a second thing to agree on, and the whole value of this module is that there is only one.

A typed synchronous emitter.

Declare the event map as an interface and the payloads type-check at every call site:

interface GameEvents { built: { id: string }; ready: void }
const events = new Emitter<GameEvents>();
const off = events.on('built', ({ id }) => place(id));
events.emit('built', { id: 'mine' });
events.emit('ready', undefined);   // a payload-free event is typed `void`
off();

An event with no payload is typed void and emitted as emit('ready', undefined). The explicit undefined is deliberate: an optional second argument would make emit('built') — a payload-carrying event with its payload forgotten — compile.

The type parameter is constrained to object rather than Record<string, unknown> so that an interface map works. TypeScript gives implicit index signatures to type aliases and not to interfaces, and an emitter that rejects the more natural of the two declarations would be a papercut on every consumer.

How a pool builds, resets and bounds the instances it hands out.

A fixed-shape allocator for one type of object.

const sparks = new Pool({
  create: () => ({ x: 0, y: 0, owner: undefined as Entity | undefined }),
  reset: (s) => { s.x = 0; s.y = 0; s.owner = undefined; },
  initial: 64,
  max: 512,
});
const spark = sparks.acquire();
sparks.release(spark);

A released instance must not be touched again. The pool cannot enforce that — enforcing it would mean a wrapper per instance, which is the allocation the pool exists to avoid — so it is the caller's discipline, and checked: true in tests is how it is verified.

Reject NaN and both infinities.

The guard for anything that will be multiplied into a position, a volume or a rate. NaN is the value that spreads: one of them in a velocity turns a position into NaN, which turns a camera target into NaN, and the screen goes blank a hundred frames from where the mistake was made. Catching it at the entry point is the difference between a stack trace and an afternoon.

Reject anything that is not a whole number, including NaN and the infinities.

For the things that are counted rather than measured: tile coordinates, octave counts, item quantities. A fractional tile index silently floors somewhere downstream, and the tile that gets drawn is one the caller never asked about.

Inclusive on both ends: min <= value <= max.

NaN fails, because the comparison is written so that it must — !(value >= min && value <= max) rather than value < min || value > max, which lets NaN through both tests and is the single most common way a range check does nothing at all.

An integer index in [0, length) — the half-open interval arrays actually use.

Returns the index, so it sits inside the subscript: items[expectIndex(i, items.length, 'tileMap.at')]. Under noUncheckedIndexedAccess an out-of-range read is undefined and the type system tells you so; this is for the cases where the index came from outside and the caller wants the mistake named rather than propagated as an undefined.

Reject an empty array, returning it otherwise.

The guard for every "pick one of these" API. An empty weight table, an empty biome list, an empty palette: each of them returns undefined from an index that the code around it treats as always present, which is how a ! gets added and how a black screen ships.

Reject a number that will not survive JSON.stringify — the save-path guard.

JSON.stringify(Infinity) is "null", and so is NaN. That is the worst corruption shape in the kit: the bytes are intact, the checksum matches, the schema is the right shape, and an infinite stock silently returns as nothing. No layer downstream can detect it, which is why the check belongs at the moment of writing rather than the moment of reading.

Normalizes -0 to 0, because JSON.stringify(-0) is "0" and a value that changes across a round trip fails an integrity comparison for a reason nobody will ever find.

This is not a magnitude cap. 2 ** 60 and 1e308 pass, and they round-trip through JSON exactly — 2^53 is an arithmetic limit, not a serialization one, and the guard for that is expectSafeInteger.

The non-throwing form — the load-path predicate.

persist's invariant is that a corrupt save degrades to a fresh one with a reported reason and never throws on boot, so the load path needs to ask rather than assert. Same rule as expectSerializable, both directions of the boundary: it returns false for exactly the inputs that make the other throw, and for no others.

Reject a count that has left the exactly-representable integers.

For quantities that are counted rather than measured: buildings owned, ticks elapsed, entity ids. Above 2^53 a double cannot hold consecutive integers, so n + 1 quietly becomes n and two different logical values compare equal — an id allocator stops allocating and every entity after it is the same entity.

Deliberately not applied to an idle economy's stocks: those are measured quantities from a closed-form curve, 1e40 is a perfectly good double, and capping them would break the genre. Count with this; measure without it.

Exhaustiveness check for a discriminated union.

In the default branch of a switch, unreachable(kind, 'building.kind') stops compiling the day a case is added — which is the only kind of error worth having, because it is found by the person adding the case rather than by a player finding a building that does nothing.

The runtime throw is the backstop for the value that arrived from outside the type system — a save file, a network message, a hand-edited config — and it is a TypeError because the value is of a kind this code has never heard of.

Narrow an unknown to a plain object with string keys.

The one non-numeric guard here, and it exists because every save recognizer in the kit was otherwise hand-rolling the same six lines. A recognizer receives whatever JSON.parse produced — which may be null, an array, a string, or a number — and has to get from unknown to something it can read a field off. Without this, each one writes its own typeof x === 'object' && x !== null && !Array.isArray(x) and half of them forget one of the three clauses.

All three matter, and the two that get forgotten are the interesting ones. typeof null is 'object', so a save whose payload is the literal null sails past a naive check and fails later on a property read, at a point that no longer names the save. And an array is an object, so a payload that was serialized as […] when the schema expected {…} reads as valid until a field comes back undefined — which a permissive migration will then happily carry forward as a default.

Returns a Record<string, unknown> rather than a generic T, deliberately. Narrowing to the caller's own type is a claim, and this function has checked only the shape; handing back T would let a recognizer skip the field checks that are the entire reason it exists.

Narrow an unknown to a plain object whose every value is a finite number.

The shape a stock vector, a resource wallet or a settings blob arrives in, and the one a recognizer most often wants. Checking the values here rather than at first use is what lets a corrupt save be reported as corrupt instead of turning into NaN three subsystems later — and NaN is the value that spreads, so the distance between the bad byte and the blank screen is otherwise arbitrary.

Note that this rejects a value that is merely non-finite as firmly as one that is not a number at all, and it should: Infinity does not survive JSON.stringify — it becomes null, with a perfectly valid checksum over it — so a stock that reads back as null is evidence of a write that should never have happened.

The magnitude ladder: ['', 'K', 'M', 'B', 'T', 'Qa', 'Qi', 'Sx', 'Sp', 'Oc'].

Exported so a game can render its own ladder in the same tiers, and so a test can assert the boundary behavior at every tier without duplicating the table. Frozen, because a consumer that mutated it would change every number in the game from one line in one file.

The ladder tops out at Oc = 10^27. Past that fmtCompact switches to exponential form rather than inventing suffixes nobody can rank — an idle economy really does reach 1e40, and 'Qig' communicates nothing while '1e40' communicates everything.

Compact magnitude: 12500 → '12.5K'.

An idle game lives on this function — a player reads a magnitude in a glance with their thumb already moving. Output is never wider than six characters, sign included, for every finite double up to 1e308, so a resource pill never reflows and a wallet that changes width as you play never makes the HUD feel unstable.

The width bound is what decides the decimals, not the other way round. 999_900 is '999.9K' at six characters, -999_900 is '-999K' at five: when the decimal will not fit, it goes, because a truncated digit costs less than a moving layout. Below the first suffix a whole number stays whole — 250 is '250', never '250.0'.

Values are truncated, never rounded up across a tier: 999_950 is '999.9K' and never '1000.0K'. Non-finite input returns '—'; a HUD showing NaN reads as a broken game.

Compact magnitude with an explicit sign on positives: '+12.5K'.

For deltas, where the sign is the information — an offline-earnings summary, a trade preview, a stat comparison. Zero is rendered without a sign: '+0' next to a stalled production line reads as progress, which is the one thing it is not.

Grouped integer: 1234567 → '1,234,567'.

Always an ASCII comma — a locale-aware separator would make a screenshot test engine- dependent, and a save file that embedded one would be worse. Unlike fmtCompact this is unbounded in width, so it belongs in a tooltip or a detail panel, not in a HUD pill.

Rounds to the nearest integer, and falls back to compact form above 1e21, where a double has no exact digit string to group and String() itself switches to exponential.

A per-second rate: '1.2/s'.

Rates get an extra decimal below one, because early-game rates are below one and '0/s' next to a visibly filling bar is the kind of thing players file bugs about. Below one hundredth of a unit the readout becomes '<0.01/s' rather than rounding to zero — the same complaint, one order of magnitude down, and the < is honest where '0.00' is not.

0.075 → '7.5%'.

Takes a fraction, not a percentage, so there is one convention in the kit and not two. The bug this prevents is silent and permanent: a progress bar fed 0.5 where it wanted 50 looks plausible at every value, and nobody notices until a designer asks why nothing ever fills.

Width is deliberately fixed by decimals rather than trimmed — a percentage that switches between '7.5%' and '8%' as it changes makes a row of stats jitter.

How fmtDuration renders.

'short' reads better in prose and in a tooltip; 'clock' is width-stable for a countdown, which matters because a timer that changes width every ten seconds drags the layout around it once a second.

'2m 30s' (short) or '02:30' (clock).

Seconds in, always — never milliseconds. Negative input clamps to zero, because the only things that produce a negative duration are a clock correction and a subtraction in the wrong order, and '-3s remaining' on a build timer is worse than '0s'.

Rounds before splitting, not after: rounding each component separately is how 59.6 becomes '0m 60s'. Short style carries at most two units, largest first, and drops a trailing zero unit — '2h', not '2h 0m'.