@arcane-engine/runtime 0.1.0

package/src/state/prng.ts

@@ -0,0 +1,162 @@
+/** Opaque PRNG state — serializable, deterministic (xoshiro128**) */
+export type PRNGState = Readonly<{
+  readonly __brand: "PRNGState";
+  seed: number;
+  s0: number;
+  s1: number;
+  s2: number;
+  s3: number;
+}>;
+
+/** Create a seeded PRNG */
+export function seed(n: number): PRNGState {
+  // Initialize state from seed using splitmix32
+  let s = n | 0;
+  const s0 = splitmix32(s);
+  s = s0.state;
+  const s1 = splitmix32(s);
+  s = s1.state;
+  const s2 = splitmix32(s);
+  s = s2.state;
+  const s3 = splitmix32(s);
+
+  return {
+    __brand: "PRNGState" as const,
+    seed: n,
+    s0: s0.value,
+    s1: s1.value,
+    s2: s2.value,
+    s3: s3.value,
+  };
+}
+
+/** Dice notation: "2d6+3" */
+export type DiceNotation = string & { readonly __dice: true };
+
+/** Parsed dice specification */
+export type DiceSpec = Readonly<{
+  count: number;
+  sides: number;
+  modifier: number;
+}>;
+
+/** Parse dice notation string into a spec */
+export function parseDice(notation: string): DiceSpec {
+  const match = notation.match(/^(\d+)d(\d+)([+-]\d+)?$/);
+  if (!match) {
+    throw new Error(
+      `Invalid dice notation: "${notation}". Expected format: NdS or NdS+M (e.g. "2d6+3")`,
+    );
+  }
+  return {
+    count: parseInt(match[1], 10),
+    sides: parseInt(match[2], 10),
+    modifier: match[3] ? parseInt(match[3], 10) : 0,
+  };
+}
+
+/** Roll dice. Returns [result, newRngState] */
+export function rollDice(
+  rng: PRNGState,
+  spec: DiceSpec | string,
+): [number, PRNGState] {
+  const parsed = typeof spec === "string" ? parseDice(spec) : spec;
+  let total = parsed.modifier;
+  let current = rng;
+
+  for (let i = 0; i < parsed.count; i++) {
+    const [roll, next] = randomInt(current, 1, parsed.sides);
+    total += roll;
+    current = next;
+  }
+
+  return [total, current];
+}
+
+/** Random integer in [min, max] inclusive */
+export function randomInt(
+  rng: PRNGState,
+  min: number,
+  max: number,
+): [number, PRNGState] {
+  const [f, next] = randomFloat(rng);
+  const range = max - min + 1;
+  const value = min + Math.floor(f * range);
+  return [value, next];
+}
+
+/** Random float in [0, 1) */
+export function randomFloat(rng: PRNGState): [number, PRNGState] {
+  const next = advance(rng);
+  const result = (xoshiro128ss(rng) >>> 0) / 4294967296;
+  return [result, next];
+}
+
+/** Pick one random element */
+export function randomPick<T>(
+  rng: PRNGState,
+  items: readonly T[],
+): [T, PRNGState] {
+  const [index, next] = randomInt(rng, 0, items.length - 1);
+  return [items[index], next];
+}
+
+/** Shuffle array (Fisher-Yates). Returns new array. */
+export function shuffle<T>(
+  rng: PRNGState,
+  items: readonly T[],
+): [readonly T[], PRNGState] {
+  const result = [...items];
+  let current = rng;
+
+  for (let i = result.length - 1; i > 0; i--) {
+    const [j, next] = randomInt(current, 0, i);
+    current = next;
+    const temp = result[i];
+    result[i] = result[j];
+    result[j] = temp;
+  }
+
+  return [result, current];
+}
+
+// --- Internal: xoshiro128** ---
+
+function xoshiro128ss(state: PRNGState): number {
+  const result = Math.imul(rotl(Math.imul(state.s1, 5), 7), 9);
+  return result | 0;
+}
+
+function advance(state: PRNGState): PRNGState {
+  const t = state.s1 << 9;
+
+  let s2 = state.s2 ^ state.s0;
+  let s3 = state.s3 ^ state.s1;
+  const s1 = state.s1 ^ s2;
+  const s0 = state.s0 ^ s3;
+
+  s2 = s2 ^ t;
+  s3 = rotl(s3, 11);
+
+  return {
+    __brand: "PRNGState" as const,
+    seed: state.seed,
+    s0,
+    s1,
+    s2,
+    s3,
+  };
+}
+
+function rotl(x: number, k: number): number {
+  return (x << k) | (x >>> (32 - k));
+}
+
+function splitmix32(state: number): { value: number; state: number } {
+  state = (state + 0x9e3779b9) | 0;
+  let z = state;
+  z = Math.imul(z ^ (z >>> 16), 0x85ebca6b);
+  z = Math.imul(z ^ (z >>> 13), 0xc2b2ae35);
+  z = z ^ (z >>> 16);
+  return { value: z, state };
+}

package/src/state/query.test.ts

@@ -0,0 +1,208 @@
+import { describe, it, assert } from "../testing/harness.ts";
+import {
+  query,
+  get,
+  has,
+  lt,
+  gt,
+  lte,
+  gte,
+  eq,
+  neq,
+  oneOf,
+  within,
+  allOf,
+  anyOf,
+  not,
+} from "./query.ts";
+
+const state = {
+  turn: 3,
+  party: [
+    { id: "alice", hp: 20, maxHp: 20, position: { x: 1, y: 2 }, role: "fighter" },
+    { id: "bob", hp: 8, maxHp: 15, position: { x: 3, y: 4 }, role: "mage" },
+    { id: "carol", hp: 0, maxHp: 12, position: { x: 5, y: 6 }, role: "rogue" },
+  ],
+  dungeon: {
+    level: 2,
+    rooms: [
+      { id: "r1", type: "corridor" },
+      { id: "r2", type: "treasure" },
+      { id: "r3", type: "corridor" },
+    ],
+  },
+};
+
+describe("get", () => {
+  it("gets a top-level value", () => {
+    assert.equal(get(state, "turn"), 3);
+  });
+
+  it("gets a nested value", () => {
+    assert.equal(get(state, "dungeon.level"), 2);
+  });
+
+  it("gets an array element by index", () => {
+    const alice = get<typeof state, typeof state.party[0]>(state, "party.0");
+    assert.equal(alice!.id, "alice");
+  });
+
+  it("gets a deeply nested value through array index", () => {
+    assert.equal(get(state, "party.1.hp"), 8);
+  });
+
+  it("returns undefined for missing paths", () => {
+    assert.equal(get(state, "nonexistent"), undefined);
+    assert.equal(get(state, "party.0.nonexistent"), undefined);
+    assert.equal(get(state, "a.b.c.d"), undefined);
+  });
+
+  it("supports wildcard paths to get all values", () => {
+    const hps = get(state, "party.*.hp");
+    assert.deepEqual(hps, [20, 8, 0]);
+  });
+});
+
+describe("has", () => {
+  it("returns true for existing paths", () => {
+    assert.equal(has(state, "turn"), true);
+    assert.equal(has(state, "party.0.hp"), true);
+  });
+
+  it("returns false for missing paths", () => {
+    assert.equal(has(state, "nonexistent"), false);
+  });
+
+  it("checks a predicate when provided", () => {
+    assert.equal(has(state, "turn", (v) => (v as number) > 2), true);
+    assert.equal(has(state, "turn", (v) => (v as number) > 5), false);
+  });
+});
+
+describe("query", () => {
+  it("returns an array at a path", () => {
+    const result = query(state, "party");
+    assert.equal(result.length, 3);
+  });
+
+  it("filters with a predicate function", () => {
+    const alive = query<typeof state, typeof state.party[0]>(
+      state,
+      "party",
+      (member) => member.hp > 0,
+    );
+    assert.equal(alive.length, 2);
+    assert.equal(alive[0].id, "alice");
+    assert.equal(alive[1].id, "bob");
+  });
+
+  it("filters with an object filter (property matching)", () => {
+    const fighters = query(state, "party", { role: "fighter" });
+    assert.equal(fighters.length, 1);
+  });
+
+  it("filters with predicate values in object filter", () => {
+    const wounded = query(state, "party", { hp: lt(15) });
+    assert.equal(wounded.length, 2); // bob (8) and carol (0)
+  });
+
+  it("wraps a non-array value as a single-element array", () => {
+    const result = query(state, "dungeon.level");
+    assert.deepEqual(result, [2]);
+  });
+
+  it("returns empty for missing paths", () => {
+    const result = query(state, "nonexistent");
+    assert.deepEqual(result, []);
+  });
+
+  it("queries nested arrays", () => {
+    const corridors = query(state, "dungeon.rooms", { type: "corridor" });
+    assert.equal(corridors.length, 2);
+  });
+});
+
+describe("filter combinators", () => {
+  it("lt", () => {
+    const f = lt(10);
+    assert.equal(f(5), true);
+    assert.equal(f(10), false);
+    assert.equal(f(15), false);
+  });
+
+  it("gt", () => {
+    const f = gt(10);
+    assert.equal(f(15), true);
+    assert.equal(f(10), false);
+    assert.equal(f(5), false);
+  });
+
+  it("lte", () => {
+    const f = lte(10);
+    assert.equal(f(10), true);
+    assert.equal(f(11), false);
+  });
+
+  it("gte", () => {
+    const f = gte(10);
+    assert.equal(f(10), true);
+    assert.equal(f(9), false);
+  });
+
+  it("eq", () => {
+    const f = eq("fighter");
+    assert.equal(f("fighter"), true);
+    assert.equal(f("mage"), false);
+  });
+
+  it("neq", () => {
+    const f = neq(0);
+    assert.equal(f(1), true);
+    assert.equal(f(0), false);
+  });
+
+  it("oneOf", () => {
+    const f = oneOf("fighter", "mage");
+    assert.equal(f("fighter"), true);
+    assert.equal(f("mage"), true);
+    assert.equal(f("rogue"), false);
+  });
+
+  it("within", () => {
+    const f = within({ x: 0, y: 0 }, 5);
+    assert.equal(f({ x: 3, y: 4 }), true);  // distance = 5
+    assert.equal(f({ x: 4, y: 4 }), false); // distance > 5
+    assert.equal(f({ x: 0, y: 0 }), true);  // distance = 0
+  });
+
+  it("allOf", () => {
+    const f = allOf(gt(0), lt(20));
+    assert.equal(f(10), true);
+    assert.equal(f(0), false);
+    assert.equal(f(20), false);
+  });
+
+  it("anyOf", () => {
+    const f = anyOf(eq(0), eq(20));
+    assert.equal(f(0), true);
+    assert.equal(f(20), true);
+    assert.equal(f(10), false);
+  });
+
+  it("not", () => {
+    const f = not(eq(0));
+    assert.equal(f(0), false);
+    assert.equal(f(1), true);
+  });
+
+  it("composing combinators", () => {
+    // Find party members who are alive and wounded (hp > 0 but hp < maxHp)
+    const aliveAndWounded = query<typeof state, typeof state.party[0]>(
+      state,
+      "party",
+      (member) => allOf(gt(0), lt(member.maxHp))(member.hp),
+    );
+    assert.equal(aliveAndWounded.length, 1);
+    assert.equal(aliveAndWounded[0].id, "bob");
+  });
+});

package/src/state/query.ts

@@ -0,0 +1,144 @@
+import type { Vec2 } from "./types.ts";
+
+/** A predicate function for filtering */
+export type Predicate<T> = (item: T) => boolean;
+
+/** Query an array at a path, with optional filtering */
+export function query<S, R = unknown>(
+  state: S,
+  path: string,
+  filter?: Predicate<R> | Record<string, unknown>,
+): readonly R[] {
+  const value = getByPath(state, path);
+
+  if (!Array.isArray(value)) {
+    return value !== undefined ? ([value] as unknown as readonly R[]) : [];
+  }
+
+  if (!filter) return value as readonly R[];
+
+  if (typeof filter === "function") {
+    return value.filter(filter) as readonly R[];
+  }
+
+  // Object filter: match properties
+  return value.filter((item) => {
+    if (typeof item !== "object" || item === null) return false;
+    const record = item as Record<string, unknown>;
+    for (const [key, expected] of Object.entries(filter)) {
+      if (typeof expected === "function") {
+        if (!(expected as Predicate<unknown>)(record[key])) return false;
+      } else if (record[key] !== expected) {
+        return false;
+      }
+    }
+    return true;
+  }) as readonly R[];
+}
+
+/** Get a single value at a path */
+export function get<S, R = unknown>(state: S, path: string): R | undefined {
+  return getByPath(state, path) as R | undefined;
+}
+
+/** Check existence at a path, optionally with a predicate */
+export function has<S>(
+  state: S,
+  path: string,
+  predicate?: Predicate<unknown>,
+): boolean {
+  const value = getByPath(state, path);
+  if (value === undefined) return false;
+  if (predicate) return predicate(value);
+  return true;
+}
+
+// --- Filter combinators ---
+
+/** Less than */
+export function lt(value: number): Predicate<number> {
+  return (item: number) => item < value;
+}
+
+/** Greater than */
+export function gt(value: number): Predicate<number> {
+  return (item: number) => item > value;
+}
+
+/** Less than or equal */
+export function lte(value: number): Predicate<number> {
+  return (item: number) => item <= value;
+}
+
+/** Greater than or equal */
+export function gte(value: number): Predicate<number> {
+  return (item: number) => item >= value;
+}
+
+/** Strict equality */
+export function eq<T>(value: T): Predicate<T> {
+  return (item: T) => item === value;
+}
+
+/** Not equal */
+export function neq<T>(value: T): Predicate<T> {
+  return (item: T) => item !== value;
+}
+
+/** Value is one of the given options */
+export function oneOf<T>(...values: T[]): Predicate<T> {
+  return (item: T) => values.includes(item);
+}
+
+/** Position within radius of a center point */
+export function within(center: Vec2, radius: number): Predicate<Vec2> {
+  return (pos: Vec2) => {
+    const dx = pos.x - center.x;
+    const dy = pos.y - center.y;
+    return dx * dx + dy * dy <= radius * radius;
+  };
+}
+
+/** Combine predicates: all must pass */
+export function allOf<T>(...predicates: Predicate<T>[]): Predicate<T> {
+  return (item: T) => predicates.every((p) => p(item));
+}
+
+/** Combine predicates: any must pass */
+export function anyOf<T>(...predicates: Predicate<T>[]): Predicate<T> {
+  return (item: T) => predicates.some((p) => p(item));
+}
+
+/** Negate a predicate */
+export function not<T>(predicate: Predicate<T>): Predicate<T> {
+  return (item: T) => !predicate(item);
+}
+
+// --- Internal: path traversal with wildcard support ---
+
+function getByPath(obj: unknown, path: string): unknown {
+  const segments = path.split(".");
+  return resolveSegments(obj, segments);
+}
+
+function resolveSegments(obj: unknown, segments: string[]): unknown {
+  if (segments.length === 0) return obj;
+
+  const [head, ...rest] = segments;
+
+  if (head === "*") {
+    // Wildcard: expand across array elements
+    if (!Array.isArray(obj)) return undefined;
+    if (rest.length === 0) return obj;
+    return obj.flatMap((item) => {
+      const result = resolveSegments(item, rest);
+      return Array.isArray(result) ? result : [result];
+    });
+  }
+
+  if (obj === null || obj === undefined) return undefined;
+  if (typeof obj !== "object") return undefined;
+
+  const next = (obj as Record<string, unknown>)[head];
+  return resolveSegments(next, rest);
+}