@jgengine/convex 0.50.0 → 0.52.0

package/skills/jgengine/recipes/cookbook.md

@@ -0,0 +1,752 @@
+# Cookbook
+
+<!-- GENERATED by `bun run gen recipes` from packages/core/src/recipes/*.recipe.test.ts - edit the test, not this file. -->
+
+Each common feature built from the parts in a few lines. The code is the test body, so it runs; the lines after the blank line check that it behaves.
+
+## Growth stages
+
+Phases the game names, each applying its own Modifiers source to size and strength as it begins.
+
+```ts
+import { createPhaseSchedule, createStatGraph } from "@jgengine/core/parts";
+
+const stages = createPhaseSchedule({
+  phases: [{ state: "hatchling", durationSeconds: 100 }, { state: "juvenile", durationSeconds: 300 }, { state: "adult" }],
+});
+const body = createStatGraph({ inputs: [{ id: "size", base: 1 }, { id: "strength", base: 2 }] }).create();
+const scale = { hatchling: 0.25, juvenile: 0.6, adult: 1 };
+const grow = (dt: number) => {
+  for (const t of stages.tick(dt)) body.addSource("stage", { size: { source: t.to, op: "mul", value: scale[t.to] } });
+};
+
+grow(100);
+expect(stages.state()).toBe("juvenile");
+expect(body.get("size")).toBe(0.6);
+grow(300);
+expect(stages.state()).toBe("adult");
+expect(body.get("size")).toBe(1);
+```
+
+## Ammo and reload
+
+The magazine and the reserve are two Meters, and a countdown gates firing while the reload runs.
+
+```ts
+import { changeStatPool, createStatPool } from "@jgengine/core/parts";
+import { tickCooldown } from "@jgengine/core/time/cooldown";
+
+let magazine = createStatPool({ max: 30 });
+let reserve = createStatPool({ max: 120, current: 40 });
+let reloading = 0;
+const fire = () => reloading === 0 && magazine.current > 0 && ((magazine = changeStatPool(magazine, -1).pool), true);
+const reload = () => {
+  const moved = changeStatPool(reserve, -(magazine.max - magazine.current)).applied;
+  reserve = changeStatPool(reserve, moved).pool;
+  magazine = changeStatPool(magazine, -moved).pool;
+  reloading = 2;
+};
+
+for (let n = 0; n < 30; n += 1) fire();
+expect(fire()).toBe(false);
+reload();
+expect(fire()).toBe(false);
+reloading = tickCooldown(reloading, 2);
+expect([fire(), magazine.current, reserve.current]).toEqual([true, 29, 10]);
+```
+
+## Boss with phases
+
+A Meter holds the boss's health, a Ladder of health cut points reports each one crossed, and Phases advance by event, not by time.
+
+```ts
+import { changeStatPool, createPhaseSchedule, createStatPool, crossThresholds } from "@jgengine/core/parts";
+
+let health = createStatPool({ max: 1000 });
+const phases = createPhaseSchedule({ phases: [{ state: "ranged" }, { state: "melee" }, { state: "enraged" }] });
+const cuts = [{ id: "melee", at: 600 }, { id: "enraged", at: 300 }];
+const hit = (damage: number) => {
+  const hit = changeStatPool(health, -damage);
+  for (const _ of crossThresholds(cuts, health.current, hit.pool.current)) phases.advance();
+  health = hit.pool;
+};
+
+expect(phases.state()).toBe("ranged");
+hit(500);
+expect(phases.state()).toBe("melee");
+hit(450);
+expect(phases.state()).toBe("enraged");
+hit(900);
+expect(health.current).toBe(0);
+```
+
+## Bounty board
+
+Slots hold one bounty each and refill a while after one is done, a Table draws the next target, and a Requirement gates who may take it.
+
+```ts
+import { createRefillSlots, evaluatePredicate, pickWeighted } from "@jgengine/core/parts";
+import { seededRng } from "@jgengine/core/random/rng";
+
+const rng = seededRng("bounties");
+const board = createRefillSlots({ slots: ["a", "b", "c"], refillSeconds: [100, 100] }, rng);
+const targets = [{ name: "bandit", weight: 3 }, { name: "wolf king", weight: 1 }];
+const posted: Record<string, string> = {};
+const post = (now: number) => board.ready(now).forEach((slot) => ((posted[slot] = pickWeighted(rng, targets, (t) => t.weight)?.name ?? ""), board.fill(slot)));
+const take = (slot: string, renown: number, now: number) => {
+  if (!board.isFilled(slot) || !evaluatePredicate({ gte: ["renown", 5] }, { renown })) return false;
+  board.empty(slot, now);
+  return true;
+};
+
+post(0);
+expect(Object.keys(posted)).toEqual(["a", "b", "c"]);
+expect(take("a", 2, 10)).toBe(false);
+expect(take("a", 8, 10)).toBe(true);
+post(50);
+expect(board.isFilled("a")).toBe(false);
+post(110);
+expect(board.isFilled("a")).toBe(true);
+```
+
+## Buff stack
+
+Modifiers stack named add and multiply sources on a stat, and a plain countdown removes a buff when it runs out.
+
+```ts
+import { createStatGraph } from "@jgengine/core/parts";
+import { tickCooldown } from "@jgengine/core/time/cooldown";
+
+const sheet = createStatGraph({ inputs: [{ id: "speed", base: 10 }] }).create();
+const buffs = new Map([["haste", 5], ["boots", 60]]);
+sheet.addSource("boots", { speed: { source: "boots", op: "add", value: 2 } });
+sheet.addSource("haste", { speed: { source: "haste", op: "mul", value: 1.5 } });
+const tick = (dt: number) => {
+  for (const [id, left] of buffs) {
+    buffs.set(id, tickCooldown(left, dt));
+    if (buffs.get(id) === 0) sheet.removeSource(id);
+  }
+};
+
+expect(sheet.get("speed")).toBe(18);
+tick(5);
+expect(sheet.hasSource("haste")).toBe(false);
+expect(sheet.get("speed")).toBe(12);
+expect(sheet.explain("speed").steps.map((s) => s.source)).toContain("boots");
+```
+
+## Checkpoint respawn
+
+Placement records where you may come back, and a Meter says when you are down; respawning refills the meter and moves you there.
+
+```ts
+import { changeStatPool, createSpawnPoints, createStatPool } from "@jgengine/core/parts";
+
+const spawns = createSpawnPoints();
+const poses = new Map<string, { position: { x: number; y: number; z: number } }>();
+let health = createStatPool({ max: 100 });
+spawns.record("camp", { x: 40, y: 0, z: -5 });
+const hurt = (amount: number, checkpoint: string) => {
+  health = changeStatPool(health, -amount).pool;
+  if (health.current > 0) return false;
+  health = createStatPool({ max: health.max });
+  return spawns.respawn({ setPose: (id, pose) => !!poses.set(id, pose) }, "player", checkpoint);
+};
+
+expect(hurt(60, "camp")).toBe(false);
+expect(hurt(60, "camp")).toBe(true);
+expect(poses.get("player")?.position).toEqual({ x: 40, y: 0, z: -5 });
+expect(health.current).toBe(100);
+expect(hurt(100, "missing")).toBe(false);
+```
+
+## Combo meter
+
+A Meter that fills on every hit and drains once you stop for a moment, with a Ladder naming the multiplier.
+
+```ts
+import { changeMeter, createMeter, tickMeter, tierAt } from "@jgengine/core/parts";
+
+let combo = createMeter({ max: 20, current: 0 });
+const multipliers = [{ id: 1, at: 0 }, { id: 2, at: 5 }, { id: 3, at: 10 }];
+const hit = () => (combo = changeMeter(combo, 1).meter);
+const wait = (dt: number) => (combo = tickMeter(combo, { decay: 4, decayDelay: 2 }, dt).meter);
+const multiplier = () => tierAt(multipliers, combo.pool.current)?.id;
+
+for (let n = 0; n < 12; n += 1) hit();
+expect(multiplier()).toBe(3);
+wait(1.9);
+expect(multiplier()).toBe(3);
+wait(1.1);
+expect(multiplier()).toBe(2);
+wait(10);
+expect(multiplier()).toBe(1);
+```
+
+## Cooldown ability
+
+A cost drawn from a Meter and a countdown that gates the next cast.
+
+```ts
+import { changeStatPool, createStatPool } from "@jgengine/core/parts";
+import { tickCooldown } from "@jgengine/core/time/cooldown";
+
+let mana = createStatPool({ max: 100 });
+let cooldown = 0;
+const cast = () => {
+  if (cooldown > 0 || mana.current < 30) return false;
+  mana = changeStatPool(mana, -30).pool;
+  cooldown = 5;
+  return true;
+};
+
+expect(cast()).toBe(true);
+expect(cast()).toBe(false);
+cooldown = tickCooldown(cooldown, 4);
+expect(cast()).toBe(false);
+cooldown = tickCooldown(cooldown, 1);
+expect([cast(), mana.current]).toEqual([true, 40]);
+cooldown = tickCooldown(cooldown, 5);
+expect(cast()).toBe(true);
+cooldown = tickCooldown(cooldown, 5);
+expect(cast()).toBe(false);
+```
+
+## Day and night
+
+Phases that loop: each day part holds for its own seconds and the cycle wraps from night back to dawn.
+
+```ts
+import { createPhaseSchedule } from "@jgengine/core/parts";
+
+const clock = createPhaseSchedule({
+  loop: true,
+  phases: [
+    { state: "dawn", durationSeconds: 60 },
+    { state: "day", durationSeconds: 300 },
+    { state: "dusk", durationSeconds: 60 },
+    { state: "night", durationSeconds: 180 },
+  ],
+});
+
+expect(clock.state()).toBe("dawn");
+expect(clock.tick(60).map((t) => t.to)).toEqual(["day"]);
+expect(clock.tick(360).map((t) => t.to)).toEqual(["dusk", "night"]);
+expect(clock.tick(180).map((t) => t.wrapped)).toEqual([true]);
+expect(clock.state()).toBe("dawn");
+```
+
+## Difficulty scaling
+
+A Ladder over a skill score picks the difficulty, and that level's Modifiers source scales enemy health and damage.
+
+```ts
+import { createStatGraph, tierAt } from "@jgengine/core/parts";
+
+const enemy = createStatGraph({ inputs: [{ id: "health", base: 100 }, { id: "damage", base: 10 }] }).create();
+const levels = [{ id: "easy", at: 0, health: 0.75, damage: 0.5 }, { id: "normal", at: 40, health: 1, damage: 1 }, { id: "hard", at: 80, health: 1.5, damage: 1.5 }];
+const rescale = (score: number) => {
+  const level = tierAt(levels, score)?.id ?? "easy";
+  const set = levels.find((l) => l.id === level) ?? levels[0];
+  enemy.addSource("difficulty", { health: { source: level, op: "mul", value: set?.health ?? 1 }, damage: { source: level, op: "mul", value: set?.damage ?? 1 } });
+  return level;
+};
+
+expect(rescale(10)).toBe("easy");
+expect(enemy.get("health")).toBe(75);
+expect(rescale(90)).toBe("hard");
+expect([enemy.get("health"), enemy.get("damage")]).toEqual([150, 15]);
+```
+
+## Dog breeding
+
+Inheritance gives the pup its values from both parents with a rare mutation, and Phases grow it from puppy to adult.
+
+```ts
+import { createPhaseSchedule, inheritValues } from "@jgengine/core/parts";
+import { seededRng } from "@jgengine/core/random/rng";
+
+const rng = seededRng("pups");
+const mother = { health: 80, speed: 6, bite: 4 };
+const father = { health: 100, speed: 5, bite: 7 };
+const pup = inheritValues(mother, father, rng, { mutation: { rolls: 2, chance: 0.05, amount: 3, fields: ["health", "speed", "bite"] } });
+const growth = createPhaseSchedule({ phases: [{ state: "puppy", durationSeconds: 600 }, { state: "adult" }] });
+
+expect([80, 100]).toContain(pup.values.health - 3 * pup.mutations.filter((f) => f === "health").length);
+expect(growth.state()).toBe("puppy");
+growth.tick(599);
+expect(growth.state()).toBe("puppy");
+growth.tick(1);
+expect(growth.state()).toBe("adult");
+```
+
+## Crafting recipe with station requirement
+
+A Requirement names the station and skill, and the materials are Meters the craft drains.
+
+```ts
+import { changeStatPool, createStatPool, evaluatePredicate, type Predicate } from "@jgengine/core/parts";
+
+let iron = createStatPool({ max: 99, current: 5 });
+const sword: Predicate = { all: [{ eq: ["station", "forge"] }, { gte: ["skill.smithing", 2] }, { gte: ["iron", 3] }] };
+const craft = (station: string) => {
+  if (!evaluatePredicate(sword, { station, skill: { smithing: 2 }, iron: iron.current })) return false;
+  iron = changeStatPool(iron, -3).pool;
+  return true;
+};
+
+expect(craft("workbench")).toBe(false);
+expect(craft("forge")).toBe(true);
+expect(iron.current).toBe(2);
+expect(craft("forge")).toBe(false);
+```
+
+## Hunger and thirst
+
+Two Meters that decay at their own rates, a Ladder that names how bad it is, and eating is a fill.
+
+```ts
+import { changeMeter, createMeter, tickMeter, tierAt } from "@jgengine/core/parts";
+
+let hunger = createMeter({ max: 100 });
+let thirst = createMeter({ max: 100 });
+const bands = [{ id: "starving", at: 0 }, { id: "hungry", at: 25 }, { id: "fed", at: 60 }];
+const live = (dt: number) => {
+  hunger = tickMeter(hunger, { decay: 0.5 }, dt).meter;
+  thirst = tickMeter(thirst, { decay: 1 }, dt).meter;
+};
+
+live(140);
+expect(tierAt(bands, hunger.pool.current)?.id).toBe("hungry");
+expect(thirst.pool.current).toBe(0);
+live(30);
+expect(tierAt(bands, hunger.pool.current)?.id).toBe("starving");
+hunger = changeMeter(hunger, 20).meter;
+expect(tierAt(bands, hunger.pool.current)?.id).toBe("hungry");
+```
+
+## Patrol route
+
+A Motion track per leg between waypoints; when one arrives the next starts, and the last leg returns to the first.
+
+```ts
+import { createMotionTrack } from "@jgengine/core/parts";
+import type { Vec3 } from "@jgengine/core/world/geometry";
+
+const stops: Vec3[] = [[0, 0, 0], [10, 0, 0], [10, 0, 10]];
+const leg = (i: number, startAt: number) =>
+  createMotionTrack({ points: [stops[i % 3] ?? [0, 0, 0], stops[(i + 1) % 3] ?? [0, 0, 0]], speed: 2, startAt });
+let index = 0;
+let track = leg(0, 0);
+const at = (now: number): Vec3 => {
+  if (track.justArrived(now)) track = leg(++index, now);
+  const out: [number, number, number] = [0, 0, 0];
+  track.sampleInto(now, out);
+  return out;
+};
+
+expect(at(2.5)).toEqual([5, 0, 0]);
+expect(at(5)).toEqual([10, 0, 0]);
+expect(at(7.5)).toEqual([10, 0, 5]);
+expect(at(10)).toEqual([10, 0, 10]);
+expect(at(13.5)[0]).toBeCloseTo(10 - 7 / Math.SQRT2, 5);
+```
+
+## Quest gate
+
+A Requirement over facts the game names: level, quests done, items held. No code in the saved quest, only data.
+
+```ts
+import { evaluatePredicate, type Predicate } from "@jgengine/core/parts";
+
+const dragonQuest: Predicate = {
+  all: [{ gte: ["player.level", 10] }, { includes: ["quests.done", "intro"] }, { includes: ["items", "dragonKey"] }],
+};
+const mayStart = (facts: Record<string, unknown>) => evaluatePredicate(dragonQuest, facts);
+const facts = { player: { level: 12 }, quests: { done: ["intro"] }, items: ["torch"] };
+
+expect(mayStart(facts)).toBe(false);
+facts.items.push("dragonKey");
+expect(mayStart(facts)).toBe(true);
+facts.player.level = 4;
+expect(mayStart(facts)).toBe(false);
+```
+
+## Weather event
+
+A Schedule decides when weather rolls in, a Table picks which, and Phases hold it for a while before clear skies return.
+
+```ts
+import { createPacedSchedule, createPhaseSchedule, pickWeighted } from "@jgengine/core/parts";
+import { seededRng } from "@jgengine/core/random/rng";
+
+const rng = seededRng("weather");
+const rolls = createPacedSchedule({ firstAt: 300, every: 600, jitter: 60 }, rng);
+const sky = createPhaseSchedule({
+  phases: [{ state: "clear" }, { state: "rain", durationSeconds: 120, next: "clear" }, { state: "storm", durationSeconds: 60, next: "clear" }],
+});
+const weather = [{ id: "rain", weight: 3 }, { id: "storm", weight: 1 }];
+const update = (now: number, dt: number) => {
+  if (rolls.due(now).length > 0) sky.enter(pickWeighted(rng, weather, (w) => w.weight)?.id === "storm" ? "storm" : "rain");
+  sky.tick(dt);
+};
+
+update(299, 1);
+expect(sky.state()).toBe("clear");
+update(300, 1);
+expect(sky.state()).not.toBe("clear");
+update(301, 130);
+expect(sky.state()).toBe("clear");
+```
+
+## Rank ladder
+
+A Ladder over rating points names the rank, and the crossings between old and new points are the promotions.
+
+```ts
+import { crossThresholds, tierAt } from "@jgengine/core/parts";
+
+const ranks = [{ id: "bronze", at: 0 }, { id: "silver", at: 100 }, { id: "gold", at: 300 }];
+let points = 90;
+const win = (gain: number) => {
+  const promoted = crossThresholds(ranks, points, points + gain).map((c) => c.id);
+  points += gain;
+  return promoted;
+};
+
+expect(tierAt(ranks, points)?.id).toBe("bronze");
+expect(win(20)).toEqual(["silver"]);
+expect(win(250)).toEqual(["gold"]);
+expect(tierAt(ranks, points)?.id).toBe("gold");
+expect(crossThresholds(ranks, points, 50).map((c) => c.id)).toEqual(["gold", "silver"]);
+```
+
+## Loot table by rarity
+
+A Ladder turns a roll into a rarity, and a Table per rarity picks the item.
+
+```ts
+import { pickWeighted, tierAt } from "@jgengine/core/parts";
+import { seededRng } from "@jgengine/core/random/rng";
+
+const rng = seededRng("loot");
+const rarities = [{ id: "common", at: 0 }, { id: "rare", at: 80 }, { id: "epic", at: 97 }];
+const pools: Record<string, string[]> = { common: ["stick", "rag"], rare: ["sword"], epic: ["crown"] };
+const drop = () => {
+  const rarity = tierAt(rarities, rng() * 100)?.id ?? "common";
+  return { rarity, item: pickWeighted(rng, pools[rarity] ?? [], () => 1) };
+};
+
+const drops = Array.from({ length: 2000 }, drop);
+const count = (rarity: string) => drops.filter((d) => d.rarity === rarity).length;
+expect(drops.every((d) => pools[d.rarity]?.includes(d.item ?? ""))).toBe(true);
+expect(count("common")).toBeGreaterThan(count("rare"));
+expect(count("rare")).toBeGreaterThan(count("epic"));
+expect(count("epic")).toBeGreaterThan(0);
+```
+
+## Reputation tiers
+
+A Ladder over a standing number, with a dead band so a value hovering on a line does not flip the tier back and forth.
+
+```ts
+import { crossThresholds, tierAt } from "@jgengine/core/parts";
+
+const tiers = [{ id: "hostile", at: -100 }, { id: "neutral", at: -10 }, { id: "friendly", at: 25 }];
+let standing = 20;
+const shift = (by: number) => {
+  const changed = crossThresholds(tiers, standing, standing + by, { hysteresis: 5 }).map((c) => `${c.id}:${c.direction}`);
+  standing += by;
+  return changed;
+};
+
+expect(tierAt(tiers, standing)?.id).toBe("neutral");
+expect(shift(6)).toEqual([]);
+expect(shift(5)).toEqual(["friendly:up"]);
+expect(shift(-8)).toEqual([]);
+expect(shift(-10)).toEqual(["friendly:down"]);
+```
+
+## Respawning resource node
+
+Slots hold one node per spot and make it ready again a while after it is mined; a Table picks what it yields.
+
+```ts
+import { createRefillSlots, pickWeighted } from "@jgengine/core/parts";
+import { seededRng } from "@jgengine/core/random/rng";
+
+const rng = seededRng("ore");
+const nodes = createRefillSlots({ slots: ["vein-a", "vein-b"], refillSeconds: [60, 120] }, rng);
+const yields = [{ item: "iron", weight: 4 }, { item: "gold", weight: 1 }];
+const mine = (node: string, now: number) => {
+  nodes.empty(node, now);
+  return pickWeighted(rng, yields, (y) => y.weight)?.item;
+};
+
+for (const node of nodes.ready(0)) nodes.fill(node);
+expect(nodes.ready(0)).toEqual([]);
+expect(["iron", "gold"]).toContain(mine("vein-a", 10));
+expect(nodes.isFilled("vein-a")).toBe(false);
+expect(nodes.ready(69)).toEqual([]);
+expect(nodes.ready(131)).toEqual(["vein-a"]);
+```
+
+## Shop with prices and stock
+
+Gold is a Meter, each item's stock is a Meter that regenerates (the restock), and the price is data beside it.
+
+```ts
+import { changeStatPool, createMeter, createStatPool, tickMeter } from "@jgengine/core/parts";
+
+let gold = createStatPool({ max: 1000, current: 120 });
+let potion = createMeter({ max: 3 });
+const price = 50;
+const buy = () => {
+  if (potion.pool.current < 1 || gold.current < price) return false;
+  gold = changeStatPool(gold, -price).pool;
+  potion = { ...potion, pool: changeStatPool(potion.pool, -1).pool };
+  return true;
+};
+
+expect([buy(), buy(), buy()]).toEqual([true, true, false]);
+expect(gold.current).toBe(20);
+gold = changeStatPool(gold, 500).pool;
+expect(buy()).toBe(true);
+expect(potion.pool.current).toBe(0);
+potion = tickMeter(potion, { regen: 1 / 60 }, 120).meter;
+expect(potion.pool.current).toBe(2);
+```
+
+## Skill tree unlock
+
+Skill points are a Meter, each node's prerequisite is a Requirement, and an unlocked node adds a Modifiers source.
+
+```ts
+import { changeStatPool, createStatGraph, createStatPool, evaluatePredicate, type Predicate } from "@jgengine/core/parts";
+
+let points = createStatPool({ max: 10, current: 2 });
+const sheet = createStatGraph({ inputs: [{ id: "health", base: 100 }] }).create();
+const nodes: Record<string, { needs: Predicate; health: number }> = {
+  tough: { needs: { gte: ["level", 1] }, health: 20 },
+  tougher: { needs: { includes: ["unlocked", "tough"] }, health: 30 },
+};
+const unlocked: string[] = [];
+const unlock = (id: string) => {
+  const node = nodes[id];
+  if (node === undefined || points.current < 1 || !evaluatePredicate(node.needs, { level: 1, unlocked })) return false;
+  points = changeStatPool(points, -1).pool;
+  sheet.addSource(id, { health: { source: id, op: "add", value: node.health } });
+  unlocked.push(id);
+  return true;
+};
+
+expect(unlock("tougher")).toBe(false);
+expect([unlock("tough"), unlock("tougher")]).toEqual([true, true]);
+expect(sheet.get("health")).toBe(150);
+expect(points.current).toBe(0);
+```
+
+## Spawn director by pressure
+
+A pressure Meter, a Ladder of pressure bands, and a Schedule retuned to each band's pace, with a Table per band.
+
+```ts
+import { changeStatPool, createPacedSchedule, createStatPool, pickWeighted, tierAt } from "@jgengine/core/parts";
+import { seededRng } from "@jgengine/core/random/rng";
+
+const rng = seededRng("director");
+let pressure = createStatPool({ max: 100, current: 0 });
+const bands = [{ id: "calm", at: 0, every: 20, mix: ["rat"] }, { id: "tense", at: 40, every: 8, mix: ["rat", "wolf"] }, { id: "frantic", at: 80, every: 3, mix: ["wolf", "ogre"] }];
+const pace = createPacedSchedule({ firstAt: 0, every: 20 }, rng);
+const spawn = (now: number) => {
+  const band = tierAt(bands, pressure.current)?.id;
+  const chosen = bands.find((b) => b.id === band) ?? bands[0];
+  pace.retune({ every: chosen?.every ?? 20 });
+  return pace.due(now).map(() => pickWeighted(rng, chosen?.mix ?? [], () => 1));
+};
+
+expect(spawn(0)).toEqual(["rat"]);
+pressure = changeStatPool(pressure, 85).pool;
+expect(spawn(20)).toHaveLength(1);
+expect(pace.remaining(20)).toBe(3);
+expect(spawn(26).every((id) => id === "wolf" || id === "ogre")).toBe(true);
+```
+
+## Stamina sprint
+
+A Meter drained while sprinting that only regenerates a moment after the last drain.
+
+```ts
+import { changeMeter, createMeter, tickMeter } from "@jgengine/core/parts";
+
+let stamina = createMeter({ max: 100 });
+const rest = (dt: number) => (stamina = tickMeter(stamina, { regen: 15, regenDelay: 1.5 }, dt).meter);
+const sprint = (dt: number) => {
+  if (stamina.pool.current <= 0) return false;
+  stamina = changeMeter(stamina, -20 * dt).meter;
+  return true;
+};
+
+for (let second = 0; second < 5; second += 1) sprint(1);
+expect(stamina.pool.current).toBe(0);
+expect(sprint(1)).toBe(false);
+rest(1);
+expect(stamina.pool.current).toBe(0);
+rest(3);
+expect(stamina.pool.current).toBeGreaterThan(0);
+expect(sprint(1)).toBe(true);
+```
+
+## Supply drop
+
+A Schedule says when, Placement where, a Ladder names the rarity, a Table fills the crate, a Motion track is the fall, a Requirement gates opening it, and Slots hold one crate per site.
+
+```ts
+import { createMotionTrack, createPacedSchedule, createRefillSlots, discRegion, evaluatePredicate, pickWeighted, samplePoint, tierAt } from "@jgengine/core/parts";
+import { seededRng } from "@jgengine/core/random/rng";
+
+const rng = seededRng("supply-drop");
+const schedule = createPacedSchedule({ firstAt: 60, every: 120 }, rng);
+const sites = createRefillSlots({ slots: ["north", "south"], refillSeconds: [30, 30] }, rng);
+const rarity = tierAt([{ id: "white", at: 0 }, { id: "purple", at: 80 }], rng() * 100)?.id ?? "white";
+const pool = { white: ["bandage", "ammo"], purple: ["rifle"] }[rarity] ?? [];
+const spawnSupplyDrop = (site: string, now: number) => {
+  const [x = 0, z = 0] = samplePoint({ region: discRegion([0, 0], 40), rng }).point ?? [];
+  sites.fill(site);
+  return { site, rarity, loot: pickWeighted(rng, pool, () => 1), fall: createMotionTrack({ points: [[x, 80, z], [x, 0, z]], duration: 8, startAt: now }) };
+};
+const mayOpen = (level: number) => evaluatePredicate({ gte: ["player.level", rarity === "purple" ? 10 : 1] }, { player: { level } });
+
+expect(schedule.due(60)).toEqual([0]);
+const drop = spawnSupplyDrop(sites.ready(60)[0] ?? "north", 60);
+expect(drop.fall.arrivesAt()).toBe(68);
+expect(pool).toContain(drop.loot);
+expect(sites.isFilled("north")).toBe(true);
+sites.empty("north", 70);
+expect(sites.ready(100)).toContain("north");
+expect(mayOpen(rarity === "purple" ? 3 : 1)).toBe(rarity !== "purple");
+```
+
+## Taming by feeding
+
+A taming Meter filled by food, worth more when a Requirement says it is the creature's favourite, and draining if you stop.
+
+```ts
+import { changeMeter, createMeter, evaluatePredicate, tickMeter } from "@jgengine/core/parts";
+
+let trust = createMeter({ max: 100, current: 0 });
+const favourite = { in: ["food", ["berry", "meat"]] } as const;
+const worth = (food: string) => (evaluatePredicate(favourite, { food }) ? 30 : 10);
+const feed = (food: string) => (trust = changeMeter(trust, worth(food)).meter);
+const wait = (dt: number) => (trust = tickMeter(trust, { decay: 1, decayDelay: 20 }, dt).meter);
+
+feed("bread");
+expect(trust.pool.current).toBe(10);
+wait(40);
+expect(trust.pool.current).toBe(0);
+for (let n = 0; n < 3; n += 1) feed("berry");
+expect(trust.pool.current).toBe(90);
+feed("meat");
+expect(changeMeter(trust, 0).change.hitMax).toBe(true);
+```
+
+## Thrown item arc
+
+A Motion track through points sampled along a parabola; the track reports where the item is and when it lands.
+
+```ts
+import { createMotionTrack } from "@jgengine/core/parts";
+
+const arc = Array.from({ length: 9 }, (_, i) => {
+  const t = i / 8;
+  return [12 * t, 1 + 12 * t * (1 - t) - t, 0] satisfies [number, number, number];
+});
+const flight = createMotionTrack({ points: arc, duration: 1.2, startAt: 0 });
+const where: [number, number, number] = [0, 0, 0];
+
+flight.sampleInto(0.6, where);
+expect(where[1]).toBeGreaterThan(3);
+expect(flight.justArrived(1.1)).toBe(false);
+flight.sampleInto(1.2, where);
+expect(where).toEqual([12, 0, 0]);
+expect(flight.justArrived(1.2)).toBe(true);
+```
+
+## Door that opens over time
+
+A Requirement decides who may open it, and a Motion track with easing slides it up and, reversed, back down.
+
+```ts
+import { easeInOutCubic } from "@jgengine/core/anim/easing";
+import { createMotionTrack, evaluatePredicate } from "@jgengine/core/parts";
+
+const needsKey = { includes: ["keys", "red"] } as const;
+const slide = (up: boolean, startAt: number) =>
+  createMotionTrack({ points: up ? [[0, 0, 0], [0, 3, 0]] : [[0, 3, 0], [0, 0, 0]], duration: 1.5, easing: easeInOutCubic, startAt });
+const open = (keys: string[], now: number) => (evaluatePredicate(needsKey, { keys }) ? slide(true, now) : null);
+const height = (door: ReturnType<typeof slide>, now: number) => {
+  const out: [number, number, number] = [0, 0, 0];
+  door.sampleInto(now, out);
+  return out[1];
+};
+
+expect(open(["blue"], 0)).toBeNull();
+const door = open(["red"], 10);
+expect(door && height(door, 10.75)).toBeCloseTo(1.5, 5);
+expect(door && height(door, 12)).toBe(3);
+expect(height(slide(false, 20), 20.75)).toBeCloseTo(1.5, 5);
+```
+
+## Timed event
+
+A Schedule opens the event, Phases hold it open for a while, and while it is open a Modifiers source doubles experience.
+
+```ts
+import { createPacedSchedule, createPhaseSchedule, createStatGraph } from "@jgengine/core/parts";
+import { seededRng } from "@jgengine/core/random/rng";
+
+const opens = createPacedSchedule({ firstAt: 100, every: 1000 }, seededRng("event"));
+const event = createPhaseSchedule({ phases: [{ state: "closed" }, { state: "open", durationSeconds: 300, next: "closed" }] });
+const xp = createStatGraph({ inputs: [{ id: "gain", base: 10 }] }).create();
+const update = (now: number, dt: number) => {
+  if (opens.due(now).length > 0) event.enter("open");
+  for (const t of event.tick(dt)) if (t.to === "closed") xp.removeSource("double");
+  if (event.state() === "open") xp.addSource("double", { gain: { source: "double", op: "mul", value: 2 } });
+};
+
+update(50, 50);
+expect(xp.get("gain")).toBe(10);
+update(100, 50);
+expect(xp.get("gain")).toBe(20);
+update(150, 300);
+expect(event.state()).toBe("closed");
+expect(xp.get("gain")).toBe(10);
+```
+
+## Wave schedule
+
+A Schedule fires each wave on a pace, a Table picks the enemy for every spawn, and the wave index sets how many.
+
+```ts
+import { createPacedSchedule, pickWeighted } from "@jgengine/core/parts";
+import { seededRng } from "@jgengine/core/random/rng";
+
+const rng = seededRng("waves");
+const waves = createPacedSchedule({ firstAt: 10, every: 30, count: 3 }, rng);
+const enemies = [{ id: "grunt", weight: 5 }, { id: "brute", weight: 1 }];
+const spawned: string[] = [];
+const tick = (now: number) => {
+  for (const wave of waves.due(now)) {
+    for (let n = 0; n < 5 + wave * 2; n += 1) spawned.push(pickWeighted(rng, enemies, (e) => e.weight)?.id ?? "grunt");
+  }
+};
+
+tick(9);
+expect(spawned).toHaveLength(0);
+tick(10);
+expect(spawned).toHaveLength(5);
+tick(100);
+expect(spawned).toHaveLength(5 + 7 + 9);
+expect(waves.done()).toBe(true);
+expect(spawned.filter((id) => id === "grunt").length).toBeGreaterThan(spawned.length / 2);
+```