koota-kit 0.1.1

package/dist/esm/eventLog.js

@@ -0,0 +1,78 @@
+// Scratch-backed event logs — the publish/drain seam between sim systems.
+//
+// A fixed-timestep sim needs one system to tell another that something HAPPENED,
+// not merely that some state now differs. The distinction is load-bearing: a
+// system cannot infer an event from state a lower priority band has already
+// consumed, so "a demon was struck this tick" has to be published as a fact
+// rather than reconstructed from health that has already changed.
+//
+// Every such log is the same shape: an array under a well-known scratch key,
+// appended by the owner, drained by exactly one consumer. Consuming systems
+// drain (the log must empty, or a cue plays twice); OBSERVERS — a dev harness, a
+// test, a HUD — must peek instead, because a reader that consumes what a consumer
+// needs is a race, and whichever runs first wins.
+//
+// That distinction is why this is a package module rather than a snippet. It was
+// re-derived ELEVEN times in one consuming game, and three of those sites had no
+// peek at all until an observer silently stole records from the audio bridge and
+// the missing sound was misdiagnosed as a missing swing. The pattern is not hard;
+// getting it wrong is quiet, and it costs a debugging session every time.
+/**
+ * Declare an event log under `key`.
+ *
+ * The array is created lazily on first use and lives in `handle.scratch`, so it
+ * lifecycles with the world: a new run starts with empty logs and cannot inherit
+ * the last one's events. That is not a detail — a log at module scope survives
+ * the world that produced it, and stale events replay into a fresh run.
+ *
+ * Keys should be namespaced by system (`"combat:hits"`, `"voices:events"`) for
+ * the same reason trait names are: scratch is one flat map shared by every
+ * system in the world. Empty keys are rejected, as is a collision with an
+ * existing non-array scratch value.
+ */
+export function defineEventLog(key) {
+    if (typeof key !== "string" || key.trim().length === 0) {
+        throw new TypeError("defineEventLog: key must be a non-empty string.");
+    }
+    const existingFor = (handle) => {
+        const existing = handle.scratch.get(key);
+        if (existing === undefined)
+            return undefined;
+        if (!Array.isArray(existing)) {
+            throw new TypeError(`Event log "${key}" cannot use its scratch key because it already holds a non-array value.`);
+        }
+        return existing;
+    };
+    const arrayFor = (handle) => {
+        const existing = existingFor(handle);
+        if (existing)
+            return existing;
+        const log = [];
+        handle.scratch.set(key, log);
+        return log;
+    };
+    return {
+        key,
+        push: (handle, event) => {
+            arrayFor(handle).push(event);
+        },
+        drain: (handle) => {
+            const log = existingFor(handle);
+            if (!log)
+                return [];
+            // Copy, then truncate IN PLACE rather than replacing the array: another
+            // system may already hold this reference, and swapping in a new array
+            // would leave that holder appending into an orphan nobody drains.
+            const out = log.slice();
+            log.length = 0;
+            return out;
+        },
+        peek: (handle) => existingFor(handle)?.slice() ?? [],
+        clear: (handle) => {
+            const log = existingFor(handle);
+            if (log)
+                log.length = 0;
+        },
+        size: (handle) => existingFor(handle)?.length ?? 0,
+    };
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,9 @@
+export { advanceClock, createActions, createSimWorld, destroySimWorld, relation, restoreWorldHeader, snapshotWorld, trait, } from "./world.js";
+export type { Entity, World, WorldHandle, WorldSnapshot } from "./world.js";
+export { chance, createRng, nextFloat, nextInt, nextU32, restoreLayers, restoreStream, snapshotLayers, snapshotStream, } from "./rng.js";
+export type { RngLayers, RngLayersSnapshot, RngSeeds, RngStream, RngStreamSnapshot, } from "./rng.js";
+export { defineEventLog } from "./eventLog.js";
+export type { EventLog } from "./eventLog.js";
+export { defineTrait } from "./traits/index.js";
+export type { SafeSchema } from "./traits/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,SAAS,EACT,OAAO,EACP,OAAO,EACP,aAAa,EACb,aAAa,EACb,cAAc,EACd,cAAc,GACf,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,14 @@
+// koota-kit — thin koota ECS conventions layer.
+//
+// Four modules, also importable as subpaths:
+//   ./world    — WorldHandle lifecycle (world + dual-stream rng + clock + scratch)
+//   ./rng      — dual-layer deterministic seedrandom PRNG with byte-exact
+//                snapshot/restore
+//   ./traits   — defineTrait AoS-aliasing guard (leaf module, zero sibling
+//                imports)
+//   ./eventLog — scratch-backed publish/drain event logs with a peek seam for
+//                observers (harnesses, tests, HUDs)
+export { advanceClock, createActions, createSimWorld, destroySimWorld, relation, restoreWorldHeader, snapshotWorld, trait, } from "./world.js";
+export { chance, createRng, nextFloat, nextInt, nextU32, restoreLayers, restoreStream, snapshotLayers, snapshotStream, } from "./rng.js";
+export { defineEventLog } from "./eventLog.js";
+export { defineTrait } from "./traits/index.js";

package/dist/esm/rng.d.ts

@@ -0,0 +1,86 @@
+import seedrandom from "seedrandom";
+type State = seedrandom.State.Arc4;
+type Stateful = seedrandom.StatefulPRNG<State>;
+export type RngStream = {
+    prng: Stateful;
+};
+export type RngLayers = {
+    gen: RngStream;
+    events: RngStream;
+};
+export type RngSeeds = {
+    /** World-generation seed (immutable, defines the world's identity). */
+    readonly gen: string | number;
+    /** Per-playthrough events seed (changes per cycle for new playthroughs of the same world). */
+    readonly events: string | number;
+};
+/**
+ * Create both RNG layers from their seeds. Called once at world creation
+ * (see `createSimWorld` in `./world`) — `gen` and `events` are independent
+ * seedrandom instances from this point on, so consuming one never perturbs
+ * the other's sequence.
+ */
+export declare function createRng(seeds: RngSeeds): RngLayers;
+/**
+ * Draw the next raw unsigned 32-bit integer from `stream` (range
+ * `[0, 2**32)`). The lowest-level draw primitive — `nextFloat`, `nextInt`,
+ * and `chance` are all expressed in terms of `quick()`, not this function;
+ * reach for `nextU32` directly only when you need the full 32 bits of
+ * entropy (e.g. seeding another PRNG, hashing).
+ */
+export declare function nextU32(stream: RngStream): number;
+/**
+ * Draw the next float from `stream` in the half-open range `[0, 1)`. The
+ * primitive every other draw helper in this module (`nextInt`, `chance`)
+ * is built on.
+ */
+export declare function nextFloat(stream: RngStream): number;
+/**
+ * Draw a random integer from `stream` in the half-open range
+ * `[minInclusive, maxExclusive)`. Bounds must be safe integers, the range must
+ * be non-empty and no larger than `2**32`, and valid calls consume exactly one
+ * `nextFloat` draw. Invalid calls do not consume the stream.
+ */
+export declare function nextInt(stream: RngStream, minInclusive: number, maxExclusive: number): number;
+/**
+ * Roll a boolean weighted by finite probability `p` in `[0, 1]` (`0` never
+ * true, `1` always true). Valid calls consume exactly one `nextFloat` draw
+ * from `stream`, so calling `chance` where a system might otherwise skip a
+ * draw entirely will shift every later draw on that stream — keep draw counts
+ * deterministic across codepaths that must replay identically.
+ */
+export declare function chance(stream: RngStream, p: number): boolean;
+export type RngStreamSnapshot = {
+    state: State;
+};
+export type RngLayersSnapshot = {
+    gen: RngStreamSnapshot;
+    events: RngStreamSnapshot;
+};
+/**
+ * Capture `stream`'s internal seedrandom state as a plain, JSON-serializable
+ * object (deep-cloned, so later draws on `stream` cannot mutate the
+ * snapshot). Restoring it with `restoreStream` reproduces every subsequent
+ * draw byte-exact.
+ */
+export declare function snapshotStream(stream: RngStream): RngStreamSnapshot;
+/**
+ * Snapshot both RNG layers at once. See `snapshotStream` — this just applies
+ * it to `gen` and `events` independently and returns both.
+ */
+export declare function snapshotLayers(rng: RngLayers): RngLayersSnapshot;
+/**
+ * Rebuild an `RngStream` from a snapshot taken by `snapshotStream`. The next
+ * draw on the returned stream reproduces the exact next draw the snapshotted
+ * stream would have produced — the seed string passed to `seedrandom` here
+ * is irrelevant because `{ state: snap.state }` fully overrides it. Malformed
+ * persisted state is rejected before seedrandom sees it.
+ */
+export declare function restoreStream(snap: RngStreamSnapshot): RngStream;
+/**
+ * Rebuild both RNG layers from a snapshot taken by `snapshotLayers`. See
+ * `restoreStream` — applied independently to `gen` and `events`.
+ */
+export declare function restoreLayers(snap: RngLayersSnapshot): RngLayers;
+export {};
+//# sourceMappingURL=rng.d.ts.map

package/dist/esm/rng.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng.d.ts","sourceRoot":"","sources":["../../src/rng.ts"],"names":[],"mappings":"AAqBA,OAAO,UAAU,MAAM,YAAY,CAAC;AAEpC,KAAK,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;AACnC,KAAK,QAAQ,GAAG,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;AAE/C,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,QAAQ,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CAClC,CAAC;AAgBF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAUpD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAc7F;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED,MAAM,MAAM,iBAAiB,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AACjD,MAAM,MAAM,iBAAiB,GAAG;IAAE,GAAG,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEtF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,iBAAiB,CAGnE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,SAAS,GAAG,iBAAiB,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAqBhE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAKhE"}

package/dist/esm/rng.js

@@ -0,0 +1,154 @@
+// Dual-layer deterministic PRNG (seedrandom-backed).
+//
+// `gen` — worldgen / layouts / spawn locations / map composition / one-time
+//   seeded decisions. Replays a world reliably from the gen seed alone, even
+//   when play diverges. Snapshot it once at world creation and you can
+//   re-derive the same world forever.
+//
+// `events` — per-tick runtime decisions (weather rolls, event triggers, mood
+//   drift, combat dice). Diverges based on play history. Snapshot/restore
+//   independently so a worldgen replay doesn't carry play state with it.
+//
+// Why two streams: a single stream couples worldgen to play, so seeding a
+// "same map, fresh playthrough" scenario requires you to either re-derive
+// worldgen mid-restore (fragile) or snapshot the stream at the exact tick
+// worldgen finished (brittle to system ordering). Two streams: snapshot gen
+// once, never touch it again; snapshot events on demand. Each layer's
+// determinism contract is independent.
+//
+// Forbidden in sim code: `Math.random()`. Use `nextFloat(rng.gen)` or
+// `nextFloat(rng.events)` depending on the layer.
+import seedrandom from "seedrandom";
+function assertSeed(seed, name) {
+    if (typeof seed !== "string" && typeof seed !== "number") {
+        throw new TypeError(`createRng: seeds.${name} must be a string or finite number.`);
+    }
+    if (typeof seed === "number" && !Number.isFinite(seed)) {
+        throw new RangeError(`createRng: seeds.${name} must be finite; received ${String(seed)}.`);
+    }
+}
+function makeStream(seed) {
+    const prng = seedrandom(String(seed), { state: true });
+    return { prng };
+}
+/**
+ * Create both RNG layers from their seeds. Called once at world creation
+ * (see `createSimWorld` in `./world`) — `gen` and `events` are independent
+ * seedrandom instances from this point on, so consuming one never perturbs
+ * the other's sequence.
+ */
+export function createRng(seeds) {
+    if (typeof seeds !== "object" || seeds === null) {
+        throw new TypeError("createRng: seeds must be an object with gen and events values.");
+    }
+    assertSeed(seeds.gen, "gen");
+    assertSeed(seeds.events, "events");
+    return {
+        gen: makeStream(seeds.gen),
+        events: makeStream(seeds.events),
+    };
+}
+/**
+ * Draw the next raw unsigned 32-bit integer from `stream` (range
+ * `[0, 2**32)`). The lowest-level draw primitive — `nextFloat`, `nextInt`,
+ * and `chance` are all expressed in terms of `quick()`, not this function;
+ * reach for `nextU32` directly only when you need the full 32 bits of
+ * entropy (e.g. seeding another PRNG, hashing).
+ */
+export function nextU32(stream) {
+    return stream.prng.int32() >>> 0;
+}
+/**
+ * Draw the next float from `stream` in the half-open range `[0, 1)`. The
+ * primitive every other draw helper in this module (`nextInt`, `chance`)
+ * is built on.
+ */
+export function nextFloat(stream) {
+    return stream.prng.quick();
+}
+/**
+ * Draw a random integer from `stream` in the half-open range
+ * `[minInclusive, maxExclusive)`. Bounds must be safe integers, the range must
+ * be non-empty and no larger than `2**32`, and valid calls consume exactly one
+ * `nextFloat` draw. Invalid calls do not consume the stream.
+ */
+export function nextInt(stream, minInclusive, maxExclusive) {
+    if (!Number.isSafeInteger(minInclusive) || !Number.isSafeInteger(maxExclusive)) {
+        throw new TypeError("nextInt: bounds must be safe integers.");
+    }
+    if (maxExclusive <= minInclusive) {
+        throw new RangeError(`nextInt: maxExclusive (${maxExclusive}) must be greater than minInclusive (${minInclusive}).`);
+    }
+    if (maxExclusive - minInclusive > 2 ** 32) {
+        throw new RangeError("nextInt: the requested range cannot exceed 2**32 values.");
+    }
+    const span = maxExclusive - minInclusive;
+    return minInclusive + Math.floor(nextFloat(stream) * span);
+}
+/**
+ * Roll a boolean weighted by finite probability `p` in `[0, 1]` (`0` never
+ * true, `1` always true). Valid calls consume exactly one `nextFloat` draw
+ * from `stream`, so calling `chance` where a system might otherwise skip a
+ * draw entirely will shift every later draw on that stream — keep draw counts
+ * deterministic across codepaths that must replay identically.
+ */
+export function chance(stream, p) {
+    if (!Number.isFinite(p) || p < 0 || p > 1) {
+        throw new RangeError(`chance: probability must be a finite number in [0, 1]; received ${p}.`);
+    }
+    return nextFloat(stream) < p;
+}
+/**
+ * Capture `stream`'s internal seedrandom state as a plain, JSON-serializable
+ * object (deep-cloned, so later draws on `stream` cannot mutate the
+ * snapshot). Restoring it with `restoreStream` reproduces every subsequent
+ * draw byte-exact.
+ */
+export function snapshotStream(stream) {
+    const state = stream.prng.state();
+    return { state: { i: state.i, j: state.j, S: [...state.S] } };
+}
+/**
+ * Snapshot both RNG layers at once. See `snapshotStream` — this just applies
+ * it to `gen` and `events` independently and returns both.
+ */
+export function snapshotLayers(rng) {
+    return { gen: snapshotStream(rng.gen), events: snapshotStream(rng.events) };
+}
+/**
+ * Rebuild an `RngStream` from a snapshot taken by `snapshotStream`. The next
+ * draw on the returned stream reproduces the exact next draw the snapshotted
+ * stream would have produced — the seed string passed to `seedrandom` here
+ * is irrelevant because `{ state: snap.state }` fully overrides it. Malformed
+ * persisted state is rejected before seedrandom sees it.
+ */
+export function restoreStream(snap) {
+    const state = snap?.state;
+    if (!state ||
+        !Number.isInteger(state.i) ||
+        state.i < 0 ||
+        state.i > 255 ||
+        !Number.isInteger(state.j) ||
+        state.j < 0 ||
+        state.j > 255 ||
+        !Array.isArray(state.S) ||
+        state.S.length !== 256 ||
+        state.S.some((value) => !Number.isInteger(value) || value < 0 || value > 255) ||
+        new Set(state.S).size !== 256) {
+        throw new TypeError("restoreStream: snapshot must contain a valid seedrandom ARC4 state.");
+    }
+    // Clone the permutation so the same immutable snapshot can safely seed more
+    // than one replay, even if seedrandom changes its internal copy behavior.
+    const prng = seedrandom("", { state: { i: state.i, j: state.j, S: [...state.S] } });
+    return { prng };
+}
+/**
+ * Rebuild both RNG layers from a snapshot taken by `snapshotLayers`. See
+ * `restoreStream` — applied independently to `gen` and `events`.
+ */
+export function restoreLayers(snap) {
+    if (typeof snap !== "object" || snap === null) {
+        throw new TypeError("restoreLayers: snapshot must contain gen and events stream states.");
+    }
+    return { gen: restoreStream(snap.gen), events: restoreStream(snap.events) };
+}

package/dist/esm/traits/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `src/traits/` — trait-authoring conventions, kept in a LEAF sub-package.
+ *
+ * Packaging pattern (from medieval-hexagon-gameboard): trait declarations
+ * live in a leaf sub-package with ZERO sibling imports — this file imports
+ * only `koota` (the npm dep) and pure types, never runtime values from
+ * sibling modules like ./world or ./rng. That is what prevents the
+ * koota ↔ world-facade ↔ game-scenario top-level evaluation cycle that a
+ * flat layout only dodges accidentally. Games adopting this package should
+ * follow the same rule: declare traits in their own leaf module, exported
+ * from exactly one location so trait reference-identity holds regardless of
+ * which subpath a consumer imports from.
+ *
+ * The AoS-aliasing footgun this module guards against (timber-town's
+ * documented convention): object-valued fields in a SoA schema must use the
+ * AoS-factory pattern (`() => ({...})`) so each entity gets its own object
+ * instance — koota's SoA pattern would otherwise alias state across
+ * entities (one shared object literal mutated by every entity that has the
+ * trait).
+ *
+ * @module
+ */
+import type { Norm, Schema, Trait } from "koota";
+/**
+ * Compile-time guard: any object-valued field in a SoA schema must be an
+ * AoS factory (`() => ({...})`), never a bare object literal. Fields that
+ * are functions, primitives, null, or undefined pass through unchanged;
+ * bare object/array literals map to `never`, producing a type error at the
+ * call site.
+ */
+export type SafeSchema<S> = S extends (...args: never[]) => unknown ? S : {
+    [K in keyof S]: S[K] extends (...args: never[]) => unknown ? S[K] : S[K] extends object ? never : S[K];
+};
+/**
+ * Thin wrapper over koota's `trait()` that enforces the AoS-factory
+ * convention for object-valued fields, at both type level (see SafeSchema)
+ * and runtime (throws with an explanation instead of silently aliasing).
+ *
+ * Accepted forms:
+ *   defineTrait({ count: 0, label: "x" })            // SoA, primitives
+ *   defineTrait({ pos: () => ({ x: 0, y: 0 }) })     // SoA, per-field factory
+ *   defineTrait(() => ({ pos: { x: 0, y: 0 } }))     // whole-trait AoS factory
+ *
+ * Rejected (the footgun):
+ *   defineTrait({ pos: { x: 0, y: 0 } })             // shared literal → aliased
+ */
+export declare function defineTrait<S extends Schema>(schema: S & SafeSchema<S>): Trait<Norm<S>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/traits/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/traits/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAGjD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GAC/D,CAAC,GACD;KACG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GACtD,CAAC,CAAC,CAAC,CAAC,GACJ,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GACjB,KAAK,GACL,CAAC,CAAC,CAAC,CAAC;CACX,CAAC;AAEN;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAgBvF"}

package/dist/esm/traits/index.js

@@ -0,0 +1,51 @@
+/**
+ * `src/traits/` — trait-authoring conventions, kept in a LEAF sub-package.
+ *
+ * Packaging pattern (from medieval-hexagon-gameboard): trait declarations
+ * live in a leaf sub-package with ZERO sibling imports — this file imports
+ * only `koota` (the npm dep) and pure types, never runtime values from
+ * sibling modules like ./world or ./rng. That is what prevents the
+ * koota ↔ world-facade ↔ game-scenario top-level evaluation cycle that a
+ * flat layout only dodges accidentally. Games adopting this package should
+ * follow the same rule: declare traits in their own leaf module, exported
+ * from exactly one location so trait reference-identity holds regardless of
+ * which subpath a consumer imports from.
+ *
+ * The AoS-aliasing footgun this module guards against (timber-town's
+ * documented convention): object-valued fields in a SoA schema must use the
+ * AoS-factory pattern (`() => ({...})`) so each entity gets its own object
+ * instance — koota's SoA pattern would otherwise alias state across
+ * entities (one shared object literal mutated by every entity that has the
+ * trait).
+ *
+ * @module
+ */
+import { trait } from "koota";
+/**
+ * Thin wrapper over koota's `trait()` that enforces the AoS-factory
+ * convention for object-valued fields, at both type level (see SafeSchema)
+ * and runtime (throws with an explanation instead of silently aliasing).
+ *
+ * Accepted forms:
+ *   defineTrait({ count: 0, label: "x" })            // SoA, primitives
+ *   defineTrait({ pos: () => ({ x: 0, y: 0 }) })     // SoA, per-field factory
+ *   defineTrait(() => ({ pos: { x: 0, y: 0 } }))     // whole-trait AoS factory
+ *
+ * Rejected (the footgun):
+ *   defineTrait({ pos: { x: 0, y: 0 } })             // shared literal → aliased
+ */
+export function defineTrait(schema) {
+    if (typeof schema !== "function") {
+        for (const [key, value] of Object.entries(schema)) {
+            if (value !== null && typeof value === "object") {
+                throw new TypeError(`defineTrait: field "${key}" is a bare object literal. koota's SoA layout ` +
+                    `would share this single instance across every entity holding the trait ` +
+                    `(state aliasing). Use an AoS factory instead: ${key}: () => ({...}).`);
+            }
+        }
+    }
+    // Pin Koota's normalization generic to the caller's schema. Passing the
+    // guard intersection through inference makes Koota 0.6.x normalize
+    // `S & SafeSchema<S>` and produces a narrower, incompatible Trait type.
+    return trait(schema);
+}

package/dist/esm/world.d.ts

@@ -0,0 +1,83 @@
+import type { World } from "koota";
+import { createActions, relation, trait } from "koota";
+import type { RngLayers, RngLayersSnapshot, RngSeeds } from "./rng.js";
+export type { Entity } from "koota";
+export type { World };
+export { createActions, relation, trait };
+export type WorldHandle = {
+    readonly world: World;
+    rng: RngLayers;
+    /**
+     * The immutable seeds this world was created from. Stored so systems
+     * can derive deterministic per-entity seeds (e.g. noise keyed on an
+     * entity's stable grid coordinates) WITHOUT lazily consuming the
+     * rng.gen stream in query-iteration order — koota entity ids are not
+     * reset between worlds, so iteration-order rng draws are
+     * non-deterministic across two runs in one process. Derive from
+     * `seeds.gen`, never a lazy draw.
+     */
+    readonly seeds: Readonly<RngSeeds>;
+    clock: {
+        tickIndex: number;
+        simSeconds: number;
+    };
+    /**
+     * Per-system scratch caches owned by the WorldHandle (so they lifecycle with
+     * the world, not at module scope). Systems read/write via well-known keys.
+     * Examples: per-region noise fns, pathfinding grids, behavior-tree instances.
+     */
+    readonly scratch: Map<string, unknown>;
+};
+/**
+ * Create a fresh `WorldHandle`: a new koota world, both RNG layers seeded
+ * from `seeds`, a zeroed clock, and an empty scratch map. This is the one
+ * entry point for standing up a sim — call it once per world (per game
+ * session, per test, per worldgen run) rather than constructing the koota
+ * world and RNG separately, so the facade's invariants (immutable `seeds`,
+ * clock starting at zero, scratch starting empty) always hold.
+ */
+export declare function createSimWorld(seeds: RngSeeds): WorldHandle;
+/**
+ * Tear down a simulation handle. This clears facade-owned scratch state and
+ * releases Koota's process-global world id. The operation is idempotent, which
+ * makes it safe to call from cleanup paths that may run more than once.
+ */
+export declare function destroySimWorld(handle: WorldHandle): void;
+/**
+ * Advance `handle`'s clock by one fixed-timestep tick: increments
+ * `tickIndex` by 1 and accumulates `dt` seconds into `simSeconds`. Call once
+ * per sim tick, before running that tick's systems, so `clock` always
+ * reflects "how far the sim has progressed" rather than "how far it will
+ * have progressed after this tick's work."
+ */
+export declare function advanceClock(handle: WorldHandle, dt: number): void;
+/**
+ * The serializable "header" of a world: both RNG layers' byte-exact state
+ * plus the clock. Deliberately excludes entity/component state — koota
+ * entities are the caller's data to serialize however their game needs
+ * (full ECS dump, delta log, etc.); this snapshot only covers what the
+ * facade itself owns.
+ */
+export type WorldSnapshot = {
+    rng: RngLayersSnapshot;
+    clock: {
+        tickIndex: number;
+        simSeconds: number;
+    };
+};
+/**
+ * Capture `handle`'s RNG state and clock into a plain, JSON-serializable
+ * `WorldSnapshot`. Pair with `restoreWorldHeader` for save/load — restoring
+ * a snapshot reproduces every subsequent RNG draw on both layers byte-exact
+ * and resumes the clock from the exact tick/second it was captured at.
+ */
+export declare function snapshotWorld(handle: WorldHandle): WorldSnapshot;
+/**
+ * Restore `handle`'s RNG layers and clock from a `WorldSnapshot` taken by
+ * `snapshotWorld`. Mutates `handle` in place (replaces `handle.rng` and
+ * `handle.clock` with freshly rebuilt values) — entity/component state is
+ * untouched, since the facade never captured it in the first place; restore
+ * that separately using whatever serialization your game chose.
+ */
+export declare function restoreWorldHeader(handle: WorldHandle, snap: WorldSnapshot): void;
+//# sourceMappingURL=world.d.ts.map

package/dist/esm/world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../src/world.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,EAAE,aAAa,EAAe,QAAQ,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGvE,YAAY,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACpC,YAAY,EAAE,KAAK,EAAE,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAE1C,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,GAAG,EAAE,SAAS,CAAC;IACf;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,CAY3D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAKzD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAiBlE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,iBAAiB,CAAC;IACvB,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,CAKhE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAkBjF"}

package/dist/esm/world.js

@@ -0,0 +1,101 @@
+// World facade. Wraps koota's createWorld + trait helper so the rest of a
+// game's codebase imports from here and lifecycle/determinism conventions stay
+// behind one boundary.
+//
+// Games declare their traits with `defineTrait` (see ./traits) and drive the
+// sim through the WorldHandle: world creation, trait re-export, tick clock,
+// dual-layer RNG plumbing.
+import { createActions, createWorld, relation, trait } from "koota";
+import { createRng, restoreLayers, snapshotLayers } from "./rng.js";
+export { createActions, relation, trait };
+/**
+ * Create a fresh `WorldHandle`: a new koota world, both RNG layers seeded
+ * from `seeds`, a zeroed clock, and an empty scratch map. This is the one
+ * entry point for standing up a sim — call it once per world (per game
+ * session, per test, per worldgen run) rather than constructing the koota
+ * world and RNG separately, so the facade's invariants (immutable `seeds`,
+ * clock starting at zero, scratch starting empty) always hold.
+ */
+export function createSimWorld(seeds) {
+    // Validate before allocating a Koota world: invalid input must not consume a
+    // process-global world id or leave a world that the caller cannot destroy.
+    const rng = createRng(seeds);
+    const immutableSeeds = Object.freeze({ gen: seeds.gen, events: seeds.events });
+    return {
+        world: createWorld(),
+        rng,
+        seeds: immutableSeeds,
+        clock: { tickIndex: 0, simSeconds: 0 },
+        scratch: new Map(),
+    };
+}
+/**
+ * Tear down a simulation handle. This clears facade-owned scratch state and
+ * releases Koota's process-global world id. The operation is idempotent, which
+ * makes it safe to call from cleanup paths that may run more than once.
+ */
+export function destroySimWorld(handle) {
+    handle.scratch.clear();
+    if (handle.world.isInitialized) {
+        handle.world.destroy();
+    }
+}
+/**
+ * Advance `handle`'s clock by one fixed-timestep tick: increments
+ * `tickIndex` by 1 and accumulates `dt` seconds into `simSeconds`. Call once
+ * per sim tick, before running that tick's systems, so `clock` always
+ * reflects "how far the sim has progressed" rather than "how far it will
+ * have progressed after this tick's work."
+ */
+export function advanceClock(handle, dt) {
+    if (!Number.isFinite(dt) || dt < 0) {
+        throw new RangeError(`advanceClock: dt must be a finite, non-negative number; received ${dt}.`);
+    }
+    if (!Number.isSafeInteger(handle.clock.tickIndex) || handle.clock.tickIndex < 0) {
+        throw new RangeError("advanceClock: clock.tickIndex must be a non-negative safe integer.");
+    }
+    if (!Number.isFinite(handle.clock.simSeconds) || handle.clock.simSeconds < 0) {
+        throw new RangeError("advanceClock: clock.simSeconds must be finite and non-negative.");
+    }
+    const tickIndex = handle.clock.tickIndex + 1;
+    const simSeconds = handle.clock.simSeconds + dt;
+    if (!Number.isSafeInteger(tickIndex) || !Number.isFinite(simSeconds)) {
+        throw new RangeError("advanceClock: advancing the clock would exceed its numeric range.");
+    }
+    handle.clock.tickIndex = tickIndex;
+    handle.clock.simSeconds = simSeconds;
+}
+/**
+ * Capture `handle`'s RNG state and clock into a plain, JSON-serializable
+ * `WorldSnapshot`. Pair with `restoreWorldHeader` for save/load — restoring
+ * a snapshot reproduces every subsequent RNG draw on both layers byte-exact
+ * and resumes the clock from the exact tick/second it was captured at.
+ */
+export function snapshotWorld(handle) {
+    return {
+        rng: snapshotLayers(handle.rng),
+        clock: { tickIndex: handle.clock.tickIndex, simSeconds: handle.clock.simSeconds },
+    };
+}
+/**
+ * Restore `handle`'s RNG layers and clock from a `WorldSnapshot` taken by
+ * `snapshotWorld`. Mutates `handle` in place (replaces `handle.rng` and
+ * `handle.clock` with freshly rebuilt values) — entity/component state is
+ * untouched, since the facade never captured it in the first place; restore
+ * that separately using whatever serialization your game chose.
+ */
+export function restoreWorldHeader(handle, snap) {
+    const clock = snap?.clock;
+    if (!clock ||
+        !Number.isSafeInteger(clock.tickIndex) ||
+        clock.tickIndex < 0 ||
+        !Number.isFinite(clock.simSeconds) ||
+        clock.simSeconds < 0) {
+        throw new TypeError("restoreWorldHeader: snapshot.clock must contain a non-negative safe integer tickIndex and finite, non-negative simSeconds.");
+    }
+    // Build and validate every replacement before mutating the handle so a bad
+    // persisted snapshot cannot leave it half-restored.
+    const rng = restoreLayers(snap.rng);
+    handle.rng = rng;
+    handle.clock = { tickIndex: clock.tickIndex, simSeconds: clock.simSeconds };
+}