@jgengine/core 0.11.0 → 0.13.0

package/skills/jgengine-gameplay/capabilities.md

@@ -8,6 +8,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `advanceLedger` (function) · `import { advanceLedger } from "@jgengine/core/gameplay"`
 
+## auction-book — timed bid auctions with escrowed bids, buyout, anti-snipe close extension, and collection-box settlement
+
+- `createAuctionBook` (function) · `import { createAuctionBook } from "@jgengine/core/gameplay"`
+
 ## best-record — persist personal-best times/scores with safe storage fallback
 
 - `createRecordBook` (function) · `import { createRecordBook } from "@jgengine/core/gameplay"`
@@ -24,6 +28,19 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `cancelJob` (function) · `import { cancelJob } from "@jgengine/core/gameplay"`
 
+## carry-encumbrance — carried mass vs capacity into movement penalty tiers and a speed multiplier
+
+- `resolveEncumbrance` (function) · `import { resolveEncumbrance } from "@jgengine/core/inventory/encumbrance"`
+
+## carry-load — sum carried mass from item stacks via an injected mass resolver
+
+- `totalLoad` (function) · `import { totalLoad } from "@jgengine/core/inventory/encumbrance"`
+
+## clip-roles — map a rigged asset's pack-specific clip name to its semantic animation role
+
+- `classifyClip` (function) · `import { classifyClip } from "@jgengine/core/game/clipRoles"`
+- `defaultAnimationForClips` (function) · `import { defaultAnimationForClips } from "@jgengine/core/game/clipRoles"`
+
 ## compose-game-loop — fold composable systems into the game loop without a manual tick fan-out
 
 - `composeGameLoop` (function) · `import { composeGameLoop } from "@jgengine/core/gameplay"`
@@ -36,6 +53,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createCosmetics` (function) · `import { createCosmetics } from "@jgengine/core/gameplay"`
 
+## creature-breeding — deterministic stat inheritance, mutation, and lineage genetics for taming games
+
+- `breedOffspring` (function) · `import { breedOffspring } from "@jgengine/core/game/breeding"`
+
 ## decay-meter — survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
 
 - `createDecayMeterSet` (function) · `import { createDecayMeterSet } from "@jgengine/core/gameplay"`
@@ -51,9 +72,9 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `evaluatePredicate` (function) · `import { evaluatePredicate } from "@jgengine/core/gameplay"`
 - `readPath` (function) · `import { readPath } from "@jgengine/core/gameplay"`
 
-## define-game — single public game-authoring path — compose systems, world, and loop in one definition
+## define-system — composable game behavior — pure data + hooks the engine schedules; pass via `defineGame({ systems })`
 
-- `defineGame` (function) · `import { defineGame } from "@jgengine/core/gameplay"`
+- `defineSystem` (function) · `import { defineSystem } from "@jgengine/core/gameplay"`
 
 ## detect — fire-once threshold/milestone/tier crossings when a value moves
 
@@ -67,6 +88,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `applyWear` (function) · `import { applyWear } from "@jgengine/core/gameplay"`
 
+## encumbrance-move-curve — progressive move-speed multiplier from a carry-load fraction
+
+- `encumbranceMoveMultiplier` (function) · `import { encumbranceMoveMultiplier } from "@jgengine/core/inventory/encumbrance"`
+
 ## enqueue-work — reserve inputs and add a timed job, honoring capacity and validation policy
 
 - `enqueue` (function) · `import { enqueue } from "@jgengine/core/gameplay"`
@@ -87,6 +112,30 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `SystemDefinition` (interface) · `import { SystemDefinition } from "@jgengine/core/gameplay"`
 
+## imprint-bonus — apply imprint stat and handler bonuses at an imprint fraction
+
+- `applyImprintBonus` (function) · `import { applyImprintBonus } from "@jgengine/core/game/breeding"`
+
+## imprint-increment — per-care-request imprint gain across a maturation schedule
+
+- `imprintIncrementPerRequest` (function) · `import { imprintIncrementPerRequest } from "@jgengine/core/game/breeding"`
+
+## incubation-tick — advance egg incubation health inside/outside its temperature range
+
+- `tickIncubation` (function) · `import { tickIncubation } from "@jgengine/core/game/breeding"`
+
+## incubation-viability — test whether an egg incubation still has health to hatch
+
+- `incubationViable` (function) · `import { incubationViable } from "@jgengine/core/game/breeding"`
+
+## inventory-grid — a bag of stackable items with add, remove, and move
+
+- `createEmptyInventory` (function) · `import { createEmptyInventory } from "@jgengine/core/inventory/inventoryModel"`
+
+## inventory-split — split a stack into a target or first-empty slot
+
+- `splitStack` (function) · `import { splitStack } from "@jgengine/core/inventory/inventoryModel"`
+
 ## item-generation — compose constraints, weighted pools, transforms, and provenance into a deterministic generated item
 
 - `generate` (function) · `import { generate } from "@jgengine/core/gameplay"`
@@ -126,6 +175,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createLeaderboard` (function) · `import { createLeaderboard } from "@jgengine/core/gameplay"`
 
+## leveling-track — grant XP, resolve level-ups against a curve, and write level+xp stats back through a stat adapter
+
+- `leveling` (function) · `import { leveling } from "@jgengine/core/gameplay"`
+
 ## lifecycle — declarative start/restart run flow — the engine owns the command glue and phase sync, the game supplies pure state transitions
 
 - `LifecycleConfig` (interface) · `import { LifecycleConfig } from "@jgengine/core/gameplay"`
@@ -160,6 +213,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `createLootRegistry` (function) · `import { createLootRegistry } from "@jgengine/core/gameplay"`
 - `lootTable` (function) · `import { lootTable } from "@jgengine/core/gameplay"`
 
+## maturation-stage — resolve the baby/juvenile/adolescent/adult stage from elapsed maturation
+
+- `maturationStage` (function) · `import { maturationStage } from "@jgengine/core/game/breeding"`
+
 ## modular-item — attach parts into item mount slots to compute combined stats
 
 - `slotAccepts` (function) · `import { slotAccepts } from "@jgengine/core/gameplay"`
@@ -190,6 +247,11 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `resolveSelection` (function) · `import { resolveSelection } from "@jgengine/core/gameplay"`
 - `validateLayers` (function) · `import { validateLayers } from "@jgengine/core/gameplay"`
 
+## part-motion — sample the root bob/sway/squash/flinch/death pose for a rig-less part-composed character
+
+- `sampleBodyPose` (function) · `import { sampleBodyPose } from "@jgengine/core/game/partAnimation"`
+- `samplePartPose` (function) · `import { samplePartPose } from "@jgengine/core/game/partAnimation"`
+
 ## pause-scheduled-rule — stop a scheduled rule from firing while retaining its cursor
 
 - `pauseRule` (function) · `import { pauseRule } from "@jgengine/core/gameplay"`
@@ -230,10 +292,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `thresholdScale` (function) · `import { thresholdScale } from "@jgengine/core/gameplay"`
 
+## price-history — rolling per-item sale records aggregated into market price stats
+
+- `createPriceHistory` (function) · `import { createPriceHistory } from "@jgengine/core/gameplay"`
+
 ## production-building — a factory building converting inputs to outputs over time
 
 - `createProductionState` (function) · `import { createProductionState } from "@jgengine/core/gameplay"`
 
+## progression-curve — evaluate a level/rank curve (const, linear, power, geometric, steps, piecewise) at a point
+
+- `evalCurve` (function) · `import { evalCurve } from "@jgengine/core/gameplay"`
+
 ## quest-log — track accepted quests and their per-objective progress
 
 - `createQuestJournal` (function) · `import { createQuestJournal } from "@jgengine/core/gameplay"`
@@ -281,6 +351,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createRunDraft` (function) · `import { createRunDraft } from "@jgengine/core/gameplay"`
 
+## seeded-random — injected deterministic randomness for game logic — never `Math.random` in a simulation
+
+- `seededRng` (function) · `import { seededRng } from "@jgengine/core/gameplay"`
+
 ## set — a bounded keyed value in a caller-owned serializable record
 
 - `setValue` (function) · `import { setValue } from "@jgengine/core/gameplay"`
@@ -318,6 +392,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `touchButtonShape` (function) · `import { touchButtonShape } from "@jgengine/core/gameplay"`
 
+## tribe-group — shared-ownership group (tribe/guild/clan) with ranked permissions, group vs personal assets, alliances, and a bounded event log
+
+- `createTribe` (function) · `import { createTribe } from "@jgengine/core/game/tribe"`
+
+## tribe-registry — registry of tribes with mutual alliances and cross-tribe relation lookup
+
+- `createTribeRegistry` (function) · `import { createTribeRegistry } from "@jgengine/core/game/tribe"`
+
 ## triggered-rules — event-conditioned effects with declarative predicates, lifetimes, and stacking
 
 - `createTriggeredRuleEngine` (function) · `import { createTriggeredRuleEngine } from "@jgengine/core/gameplay"`
@@ -325,10 +407,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `listRuleEffects` (function) · `import { listRuleEffects } from "@jgengine/core/gameplay"`
 - `registerRuleEffect` (function) · `import { registerRuleEffect } from "@jgengine/core/gameplay"`
 
+## typed-keyed-store — a cast-free typed handle onto a per-owner keyed family of reactive game-store slots, replayable and host-authoritative
+
+- `defineKeyedStore` (function) · `import { defineKeyedStore } from "@jgengine/core/store/defineKeyedStore"`
+
+## typed-store — a cast-free typed handle onto one reactive game-store slot, replayable and host-authoritative
+
+- `defineStore` (function) · `import { defineStore } from "@jgengine/core/store/defineStore"`
+
 ## unit-training — compose a timed work queue that trains catalog units into spawn orders
 
 - `unitTrainingConfig` (function) · `import { unitTrainingConfig } from "@jgengine/core/gameplay"`
 
+## unlock-points — spendable point pool earned per level and spent to unlock nodes, with refund and respec
+
+- `createUnlockPoints` (function) · `import { createUnlockPoints } from "@jgengine/core/economy/unlockPoints"`
+
 ## unlockables — gate content behind unlock conditions the player earns
 
 - `createUnlockCatalog` (function) · `import { createUnlockCatalog } from "@jgengine/core/gameplay"`

package/skills/jgengine-gameplay/recipes/portable-xp-leveling.md

@@ -0,0 +1,168 @@
+# Add XP and leveling to an existing store
+
+Use this recipe when an existing JavaScript/TypeScript project owns its player
+state and save format but wants JGengine's deterministic XP curves,
+multi-level grants, and per-level events. No `GameContext`, renderer, React,
+entity store, or JGengine loop is required.
+
+## Install and focused imports
+
+```sh
+bun add @jgengine/core
+```
+
+```ts
+import {
+  leveling,
+  type LevelingStatAccess,
+} from "@jgengine/core/game/progression";
+```
+
+## Caller-owned save data
+
+```ts
+interface SavedPool {
+  current: number;
+  max: number;
+}
+
+interface PlayerSave {
+  experience: SavedPool;
+  rank: SavedPool;
+  unlockedAbilities: string[];
+}
+
+interface ExistingSave {
+  players: Record<string, PlayerSave>;
+}
+
+let save: ExistingSave = {
+  players: {
+    player_1: {
+      experience: { current: 0, max: 100 },
+      rank: { current: 1, max: 20 },
+      unlockedAbilities: [],
+    },
+  },
+};
+```
+
+## Minimal adapter
+
+```ts
+const stats: LevelingStatAccess = {
+  get(userId, statId) {
+    const player = save.players[userId];
+    if (player === undefined) return null;
+    if (statId === "experience") return player.experience;
+    if (statId === "rank") return player.rank;
+    return null;
+  },
+  set(userId, statId, patch) {
+    const player = save.players[userId];
+    if (player === undefined) return false;
+    const previous = statId === "experience"
+      ? player.experience
+      : statId === "rank"
+        ? player.rank
+        : null;
+    if (previous === null) return false;
+    const next = {
+      current: patch.current ?? previous.current,
+      max: patch.max ?? previous.max,
+    };
+    const nextPlayer = statId === "experience"
+      ? { ...player, experience: next }
+      : { ...player, rank: next };
+    save = {
+      ...save,
+      players: {
+        ...save.players,
+        [userId]: nextPlayer,
+      },
+    };
+    return true;
+  },
+};
+```
+
+The adapter may call a Zustand `set`, dispatch a Redux action, write an ECS
+component, or replace plain data as above. It never mirrors the player into a
+JGengine store.
+
+## Configure and grant XP
+
+```ts
+const emitted: unknown[] = [];
+const existingEvents = {
+  emit(name: string, payload: unknown) {
+    emitted.push({ name, payload });
+  },
+};
+
+const playerLevel = leveling({
+  xpForLevel: {
+    kind: "power",
+    base: 80,
+    exponent: 1.35,
+    round: "floor",
+  },
+  maxLevel: 20,
+  xpStat: "experience",
+  levelStat: "rank",
+});
+
+const levelEvents: number[] = [];
+const levelsGained = playerLevel.grantXp(
+  stats,
+  "player_1",
+  900,
+  (level) => {
+    levelEvents.push(level);
+    existingEvents.emit("player-level-up", { playerId: "player_1", level });
+  },
+);
+```
+
+`levelsGained` is the count returned to the caller. The callback fires once for
+every reached level in ascending order, so a large reward can unlock each
+milestone deterministically instead of collapsing them into one final event.
+
+Use `playerLevel.resolve(level, xp)` when prediction/UI needs the same math
+without writing through the adapter.
+
+## Save and restore
+
+The adapter's authoritative values already live in the existing save:
+
+```ts
+const encoded = JSON.stringify(save);
+save = JSON.parse(encoded) as ExistingSave;
+
+// Recreate an adapter over the restored store, then continue normally.
+playerLevel.grantXp(stats, "player_1", 75, (level) => {
+  existingEvents.emit("player-level-up", { playerId: "player_1", level });
+});
+```
+
+The leveling track is immutable configuration; recreate it from the same curve
+after load. Version curve changes in the existing project's migration layer.
+
+## Ownership
+
+The existing project retains player identity, store updates, save schema,
+curve/content choice, reward sources, event bus, unlock handling, UI, backend,
+and when XP is granted. JGengine owns curve evaluation, surplus rollover,
+level caps, ordered level events, and the two-method stat adapter contract.
+
+## Common traps
+
+- Initialize both configured stat ids; `grantXp` returns `0` when either is
+  missing.
+- Treat positive and negative XP policy as game-owned input validation;
+  sanitize rewards before calling when XP loss is not allowed.
+- The default threshold mode is `perLevel`. Use `cumulative` only when the curve
+  represents total lifetime XP required to reach each level.
+- Keep `rank.max` aligned with `maxLevel` in the caller's schema.
+- Apply milestone rewards from each callback invocation; do not assume a large
+  grant emits only the final reached level.

package/skills/jgengine-gameplay/reference-systems.md

@@ -1,6 +1,15 @@
 # Composable systems (`defineSystem`)
 
-Single public authoring path: `defineGame({ systems, loop?, … })` from `@jgengine/shell/defineGame` (or core). Systems are meaningful capabilities — not micro-ticks.
+Single public authoring path: `defineGame({ systems, loop?, … })` from `@jgengine/shell/defineGame`. Systems are meaningful capabilities — not micro-ticks.
+
+## Portable XP and leveling
+
+`leveling` (`@jgengine/core/game/progression`) is usable without a scheduled
+system or game context. Its `LevelingStatAccess` reads and replaces two
+caller-named pools in an existing store; `grantXp` writes settled XP/threshold
+and level state, then emits every reached level in ascending order. State stays
+in the caller's save format and round-trips as ordinary JSON. See the
+[portable XP/leveling recipe](recipes/portable-xp-leveling.md).
 
 ## API
 
@@ -50,10 +59,6 @@ Multiple systems may share a channel. Order is stage tables + optional `before`/
 
 Default stages: fixed `input → movement → combat → ai → activities → cleanup`; frame includes those plus `animation → camera → effects`.
 
-## Cartridge path
-
-Cartridge remains a convenience wrapper. Express the same shape as ordinary systems (`runFlow`, wave director, combat) under `defineGame({ systems })` when you outgrow the cartridge schema — one authoring model, no rewrite cliff.
-
 ## Ownership
 
 - **Save / replicate** — system modules register via `ctx.game.registerSave` / `registerReplicate` at install.

package/skills/jgengine-world/SKILL.md

@@ -11,8 +11,16 @@ This skill owns runtime spatial behavior: authored-scene consumption, environmen
 
 Search [capabilities.md](capabilities.md) by intent before designing a primitive. Use [api.md](api.md) for exact exports and [reference.md](reference.md) for environment, camera, navigation, physics, audio, and authored-scene recipes.
 
+For a *connected* walkthrough that wires several primitives into a running loop, read the goal-oriented recipes under [recipes/](recipes/) — organized by composition seam (what connects to what), never by genre. Start there before reading a game's source to learn how pieces fit; a hybrid game is just a different composition of the same primitives.
+
+- [recipes/commanding-entities.md](recipes/commanding-entities.md) — select → order → tick → resolve: direct command over a group of entities (the command loop behind squad control, base-defense, herding, autobattle, or a mutating game's real-time phase).
+
 ## Canonical workflows
 
+### Declare the place
+
+A world is the place you play in: substrate + laws, via `world()` from `@jgengine/core/world/place` — `{ id, ground: { mode: flat|round|voxel|board, size, surface?, generator? }, physics? }`. Thin is complete: flat with `Infinity` axes for 3D, `board` for 2D, or omit `world` for pure UI/rules games. Never put seed, sky, or vegetation in a world definition — seeds derive from world id + save/run (`seedForPlace`); sky look and foliage scatter are editor-authored scene content, with the engine default sky when the document has none. `ground.surface` carries matter/feel laws (metal vs slime vs felt) that the same rule systems read — swap the surface, not the rules. See [reference.md](reference.md) for the full shape; `environment()` is the legacy consumption path for editor/preset-written scene data, never the starter.
+
 ### Authored world
 
 1. Load the scene document through the shared authored-scene feature.
@@ -28,8 +36,13 @@ Choose input intent, controller/motor, collision/navigation, and camera as separ
 
 Compose perception, selection, planning/behavior, movement, and lifecycle independently. Inject randomness and scheduling. Use spatial indexes, interest tiers, or bounded candidate sets for scale.
 
+### Fallback-seam diagnostics
+
+Render seams fall back to placeholders when content is unauthored: default green ground (no environment), primitive capsule/box actors (no `entityModels`/`objectModels` mapping), stylized proxy foliage (no scatter `resolveItem`). These placeholders are sometimes intended, so runtime never changes — but a dev-only, opt-in probe (`@jgengine/core/devtools/fallbackSeams`) tells "unauthored/misconfigured" apart from "intended". The shell arms it via `armFallbackSeams(devtoolsEnabled)`; each seam reports at its choice site (`reportFallbackSeam`), and counts surface through the devtools `fallbacks` probe. Disarmed (production) it is a pure, allocation-free no-op.
+
 ## Traps
 
+- Do not put seed, sky presets, or vegetation/scatter fields in a world definition — `world()` rejects them; dressing belongs to the editor's scene document.
 - Do not put UI layout, touch chrome, combat resolution, or asset acquisition here.
 - Do not duplicate editor coordinates in runtime state.
 - Public APIs accept semantic policies and caller data, not renderer mechanics or internal tuning rolls.