@jgengine/shell 0.11.0 → 0.12.0

package/dist/world/PlaceScene.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { DefaultSurface } from "../render/defaultSurface.js";
+/** Render extent (m) standing in for an `Infinity` flat-ground axis — far past the default fog. */
+const UNBOUNDED_RENDER_EXTENT = 2048;
+const GROUND_COLOR = "#5c6b52";
+function clampExtent(value) {
+    return Number.isFinite(value) ? value : UNBOUNDED_RENDER_EXTENT;
+}
+/**
+ * The substrate of a place world, rendered plainly: a flat slab or a round planet under the engine
+ * default sky. This is deliberately not a diorama — sky look, foliage, props, and sculpt are scene
+ * content the editor authors; `voxel` grounds are realized by the game's generation systems and
+ * `board` grounds by the game's own 2D face, so both mount nothing here.
+ * @internal
+ */
+export function PlaceScene({ feature }) {
+    const ground = feature.ground;
+    const size = useMemo(() => ground.mode === "flat" ? [clampExtent(ground.size.x), clampExtent(ground.size.z)] : undefined, [ground]);
+    if (ground.mode === "flat" && size !== undefined) {
+        return (_jsxs("mesh", { "rotation-x": -Math.PI / 2, receiveShadow: true, children: [_jsx("planeGeometry", { args: [size[0], size[1]] }), _jsx(DefaultSurface, { color: GROUND_COLOR, roughness: 0.95 })] }));
+    }
+    if (ground.mode === "round") {
+        return (_jsxs("mesh", { position: [0, -ground.size.radius, 0], receiveShadow: true, children: [_jsx("sphereGeometry", { args: [ground.size.radius, 64, 48] }), _jsx(DefaultSurface, { color: GROUND_COLOR, roughness: 0.95 })] }));
+    }
+    return null;
+}

package/dist/world/WorldScene.js

@@ -4,6 +4,7 @@ import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { objectVisualScale } from "@jgengine/core/scene/objectStore";
 import { WORLD_ITEM_ENTITY_NAME } from "@jgengine/core/game/worldItem";
+import { beginFallbackSeam, endFallbackPass, reportFallbackSeam, } from "@jgengine/core/devtools/fallbackSeams";
 import { useGameContext } from "@jgengine/react/provider";
 import { useSceneEntityIds, useSceneObjectIds, useGameStore, usePlayer, useTarget } from "@jgengine/react/hooks";
 import { colorFromId } from "../worldSky.js";
@@ -118,8 +119,12 @@ function RockField() {
     return (_jsx(_Fragment, { children: rocks.map((rock) => (_jsxs("mesh", { position: [rock.x, 0.25 * rock.scale, rock.z], rotation: [0.1, rock.rotation, -0.08], scale: [rock.scale * 1.4, rock.scale * 0.7, rock.scale], castShadow: true, receiveShadow: true, children: [_jsx("dodecahedronGeometry", { args: [0.8, 1] }), _jsx(DefaultSurface, { color: "#6b6f63", roughness: 0.95 })] }, rock.id))) }));
 }
 function WorldEnvironment({ environment: Environment }) {
+    // Dev diagnostic (no-op unless armed): a missing environment component means the default green
+    // ground/rocks stand in for an unauthored scene. Re-zero then report so this is idempotent.
+    beginFallbackSeam("ground");
     if (Environment !== undefined)
         return _jsx(Environment, {});
+    reportFallbackSeam("ground", "noScene");
     return (_jsxs(_Fragment, { children: [_jsx(GroundPlane, {}), _jsx(RockField, {})] }));
 }
 function WorldActors({ entitySprites, entityModels, objectModels, objectStyles, assets, renderEntity, renderObject, selectedIds, hideLocalActor, }) {
@@ -133,22 +138,44 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
         const relation = ctx.scene.entity.canReceive(entity.id, "damage") === null ? "hostile" : "friendly";
         ctx.scene.entity.setTarget(controlledId, relation === "hostile" || entity.role === "npc" ? entity.id : null);
     };
+    // Dev diagnostic (no-op unless armed): re-zero the entity/object seams before this render re-tallies
+    // which actors fall back to primitives. Committing the log runs in a useEffect after the render.
+    beginFallbackSeam("entity");
+    beginFallbackSeam("object");
+    useEffect(() => {
+        endFallbackPass();
+    });
     return (_jsxs(_Fragment, { children: [entityIds.map((entityId) => {
                 const entity = ctx.scene.entity.get(entityId);
                 if (entity === null || entity.name === WORLD_ITEM_ENTITY_NAME)
                     return null;
                 if (hideLocalActor && entityId === controlledId)
                     return null;
-                return (_jsx(EntityMarker, { entity: entity, custom: renderEntity?.(entity), model: resolveEntityModel(entityModels?.[entity.name], assets, entity.name), sprite: entitySprites?.[entity.name], isLocal: entityId === controlledId, targeted: entityId === targetId, selected: selectedIds.has(entityId), onSelect: handleSelect }, entityId));
+                const custom = renderEntity?.(entity);
+                const model = resolveEntityModel(entityModels?.[entity.name], assets, entity.name);
+                const sprite = entitySprites?.[entity.name];
+                // Entity models resolve via the hard resolveModel (throws on a present-but-missing id), so
+                // reaching the primitive capsule with no model or sprite means the mapping was omitted.
+                if ((custom === undefined || custom === null) && model === undefined && sprite === undefined) {
+                    reportFallbackSeam("entity", "omittedMapping");
+                }
+                return (_jsx(EntityMarker, { entity: entity, custom: custom, model: model, sprite: sprite, isLocal: entityId === controlledId, targeted: entityId === targetId, selected: selectedIds.has(entityId), onSelect: handleSelect }, entityId));
             }), objectIds.map((instanceId) => {
                 const object = ctx.scene.object.get(instanceId);
                 if (object === null)
                     return null;
+                const custom = renderObject?.(object);
                 const model = resolveModel(objectModels?.[object.catalogId], assets, {
                     seam: "objectModels",
                     key: object.catalogId,
                 }) ?? tryResolveCatalogModel(object.catalogId, assets);
-                return (_jsx(ObjectMarker, { object: object, custom: renderObject?.(object), model: model, style: objectStyles?.[object.catalogId] }, instanceId));
+                const style = objectStyles?.[object.catalogId];
+                // Reaching the primitive box means no model resolved. A present-but-unresolved objectModels
+                // key implies its asset pack is not pulled; an absent key is an omitted (often intended) mapping.
+                if ((custom === undefined || custom === null) && model === undefined && style?.hidden !== true) {
+                    reportFallbackSeam("object", objectModels?.[object.catalogId] === undefined ? "omittedMapping" : "unpulledPack");
+                }
+                return (_jsx(ObjectMarker, { object: object, custom: custom, model: model, style: style }, instanceId));
             })] }));
 }
 export function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, }) {

package/dist/worldSky.d.ts

@@ -1,5 +1,11 @@
 import type { SkyEnvironmentDescriptor, WorldFeature } from "@jgengine/core/world/features";
-/** The world's declared sky, when its world feature is an environment with one (#196.1). @internal */
+/**
+ * The sky in effect for a world feature (#196.1). Environments answer their declared sky; place
+ * worlds (`world()` — substrate + laws, no sky fields) get the engine default sky for 3D grounds,
+ * while `board` grounds get none (the game owns the 2D face it draws). An authored scene document's
+ * sky arrives through `backdrop`/`lighting`, which wins over this at the presentation layer.
+ * @internal
+ */
 export declare function resolveWorldSky(world: WorldFeature | undefined): SkyEnvironmentDescriptor | undefined;
 /** Deterministic HSL color from a stable instance id (default entity/object tint). @internal */
 export declare function colorFromId(id: string): string;

package/dist/worldSky.js

@@ -1,5 +1,15 @@
-/** The world's declared sky, when its world feature is an environment with one (#196.1). @internal */
+/** The engine default sky a 3D place world renders when no sky is authored in its scene document. */
+const PLACE_DEFAULT_SKY = { kind: "sky", preset: "day", timeOfDay: false };
+/**
+ * The sky in effect for a world feature (#196.1). Environments answer their declared sky; place
+ * worlds (`world()` — substrate + laws, no sky fields) get the engine default sky for 3D grounds,
+ * while `board` grounds get none (the game owns the 2D face it draws). An authored scene document's
+ * sky arrives through `backdrop`/`lighting`, which wins over this at the presentation layer.
+ * @internal
+ */
 export function resolveWorldSky(world) {
+    if (world?.kind === "place")
+        return world.ground.mode === "board" ? undefined : PLACE_DEFAULT_SKY;
     return world?.kind === "environment" ? world.sky : undefined;
 }
 /** Deterministic HSL color from a stable instance id (default entity/object tint). @internal */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.11.0",
-    "@jgengine/react": "^0.11.0",
-    "@jgengine/ws": "^0.11.0"
+    "@jgengine/core": "^0.12.0",
+    "@jgengine/react": "^0.12.0",
+    "@jgengine/ws": "^0.12.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/game-design/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: game-design
+description: Design, audit, implement, and validate player experience, loops, systems, progression, and balance.
+---
+
+# Game design
+
+## Ownership
+
+Own the intended player experience and the rules that produce it: fantasy, pillars, verbs, decisions, feedback, loops, resources, progression, challenge, failure, onboarding, and social dynamics. Treat design claims as hypotheses proved by play, not a feature inventory or genre imitation — no genre kits, presets, or archetypes; every game is a custom composition of needs (see [AGENTS.md](../../../AGENTS.md)).
+
+Use `level-design` for spatial realization; route implementation to `jgengine-gameplay`, `jgengine-world`, `jgengine-combat`, `jgengine-ui`, `jgengine-multiplayer` once intent is coherent.
+
+Read [references/application-playbook.md](references/application-playbook.md) only when the task explicitly calls for design depth — a design brief, a redesign, or "make this fun/better" work; it is not a mandatory step of creating a game. Read [references/field-guide.md](references/field-guide.md) when the task needs deeper loop, economy, progression, genre, accessibility, or research guidance.
+
+## Choose the mode
+
+Greenfield: produce a vertical-slice contract (promise, pillars, core decision, loops, progression, failure/recovery) and build the smallest slice testing the riskiest assumption — see playbook §1. Existing game: reconstruct what it actually does from code and play, rank root problems by impact/confidence/reach/effort — see playbook §2.
+
+“Improve with game design” is an implementation request, not just an audit: select the highest-leverage intervention, implement it through shared engine seams, and prove the changed player behavior.
+
+## Required output contract
+
+Every design pass yields an observed journey, a north star (promise, pillars, anti-pillars, core decision), a loop/flow model, a ranked bottleneck list with cited evidence, an intervention stack, a chosen design slice, and acceptance evidence. See [references/application-playbook.md](references/application-playbook.md) for the full contract and execution rules (verb->feedback->consequence chains, loop/progression/challenge discipline, upstream ownership).
+
+## Completion
+
+An audit is not completion for a build/improve request. Finish when the slice is playable, a fresh player can state goal/choice/consequence, failure/recovery behave as intended, and evidence supports the pillars. Use `jgengine-verify` and `workflow` to ship.

package/skills/game-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Game Design"
+  short_description: "Design coherent game loops and systems"
+  default_prompt: "Use $game-design to audit or design this game, implement its highest-leverage design slice, and prove the changed player behavior."

package/skills/game-design/references/application-playbook.md

@@ -0,0 +1,170 @@
+# Applying game design
+
+Use this playbook to turn a pitch or an existing game into implemented, testable change. Its purpose is to prevent “design work” from ending as generic advice.
+
+## Contents
+
+1. Greenfield procedure
+2. Existing-game audit
+3. Mandatory models
+4. Ranking interventions
+5. Design-slice specification
+6. Implementation and proof
+7. Failure modes
+
+## 1. Greenfield procedure
+
+### Frame the bet
+
+Write a compact contract before broad code or content:
+
+| Field | Required form |
+| --- | --- |
+| audience/context | prior skills, player count, platform/input, session length, accessibility assumptions |
+| player promise | “The player repeatedly [verb/decision] so they feel [specific experience]” |
+| pillars | two or three observable behaviors or feelings |
+| anti-pillars | experiences the game must not drift toward |
+| core decision | situation, known information, viable options, tradeoff, consequence, recurrence |
+| completion proof | one end-to-end scenario a target player can perform and explain |
+| falsifier | observation that would show the design does not work |
+
+### Build the minimum design
+
+1. Model each core verb from cue through future consequence.
+2. Draw moment, encounter, session, and meta loops.
+3. Draw resources and feedback structures.
+4. Map player skills and progression channels.
+5. Define failure, recovery, stopping, and replay.
+6. Create a content grammar: a small set of mechanics crossed with contexts and constraints.
+7. Select the riskiest assumption and build one vertical design slice around it.
+
+Do not build the entire feature list first. A vertical slice contains real input, meaningful state, feedback, one decision that recurs, failure/recovery, and a downstream consequence.
+
+## 2. Existing-game audit
+
+### Reconstruct reality
+
+Inspect actual code, catalogs, scene documents, UI, tests, captures, and live play. Do not infer the game from its title or README.
+
+Trace four journeys when applicable:
+
+- **first minute:** first input, goal, threat, reward, confusion, and reason to continue
+- **first objective:** learning sequence, decisions, failure, recovery, payoff, and next goal
+- **representative session:** loop renewal, variety, resource pressure, build choices, pacing, and stopping point
+- **campaign/meta:** unlock cadence, content reuse, escalation, economy stability, mastery, and ending/replay
+
+For each journey, record timestamps or event order:
+
+`cue -> player belief -> action -> system response -> feedback -> state change -> next choice`
+
+Mark dead time, repeated decisions, forced actions, hidden consequences, false affordances, unexplained failure, and rewards that do not alter later play.
+
+### Build a system-coupling map
+
+Inventory verbs, enemies/problems, items/tools, progression, economy, quests/objectives, world states, social systems, and failure. For each system ask:
+
+- Which pillar does it serve?
+- Which loop consumes its output?
+- What player decision does it create or transform?
+- Where is it taught, tested, combined, and mastered?
+- What happens if it is removed?
+
+Flag systems that are present but disconnected, content whose only variation is numbers or nouns, and rewards that bypass the core play.
+
+### Diagnose decision density
+
+Do not maximize decisions per second. Find long spans where the player executes an already-solved action without new information, tradeoffs, expression, pressure, or mastery. Measure:
+
+- time to first meaningful decision
+- meaningful decisions per encounter/objective
+- time between new information and commitment
+- percentage of objectives using each verb or decision type
+- repeated content before context changes
+- time from failure to a useful retry
+
+## 3. Mandatory models
+
+### Loop table
+
+| Horizon | Cue/goal | Decision/action | Feedback | State changed | Why repeat? | Failure risk |
+| --- | --- | --- | --- | --- | --- | --- |
+
+Reject any row whose “state changed” or “why repeat” is empty.
+
+### Resource-flow table
+
+| Resource | Source | Store/cap | Spend/convert | Sink | Player decision | Feedback/runaway risk |
+| --- | --- | --- | --- | --- | --- | --- |
+
+Include time, health, space, information, attention, action opportunities, and social trust when relevant.
+
+### Progression table
+
+| Unlock/reward | Channel | New decision or capability | Content it recontextualizes | Risk of invalidation/grind | Proof |
+| --- | --- | --- | --- | --- | --- |
+
+Channels are mastery, access, breadth, power, and expression/status. Passive percentages without a changed decision must justify their place.
+
+### Objective/encounter variety matrix
+
+Cross objective verbs with information state, constraints, enemy/problem behavior, topology, resource pressure, failure condition, and consequence. This exposes campaigns where every mission is the same verb with different nouns.
+
+## 4. Ranking interventions
+
+Separate symptoms from root causes. “Quests are boring” is a symptom. “Every quest uses the same kill-count transition and no objective changes space, resources, or strategy” is a testable cause.
+
+Rank each candidate:
+
+| Candidate | Player behavior changed | Pillar impact | Reach | Evidence/confidence | Effort/risk | Dependencies | Shared owner |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+
+Use three horizons:
+
+- **Minimum correction:** remove the largest contradiction or unblock the loop.
+- **Strong target:** make one representative slice deliver the promise end to end.
+- **Multiplier:** expand the proven grammar across content, progression, social play, or replay.
+
+Choose by leverage, not novelty. Prefer a change that improves many encounters or future games over bespoke content with the same underlying decision.
+
+## 5. Design-slice specification
+
+The selected slice must state:
+
+- before behavior and evidence
+- target behavior and player belief
+- mechanics/dynamics expected to cause the change
+- objective/encounter sequence and pacing beats
+- resources, rewards, failure, recovery, and downstream consequence
+- affected catalogs/config, shared package seams, scene semantics, UI feedback, and tests
+- tuning variables with starting hypotheses and safe bounds
+- explicit non-goals and content held constant
+- acceptance scenario and falsifiers
+
+If another game could use the mechanic, define the package primitive first and adopt it here. Keep game-local code for content and feel.
+
+## 6. Implementation and proof
+
+When the user asks to build or improve:
+
+1. Implement the shared primitive or use an existing capability.
+2. Adopt it in one complete game slice.
+3. Author spatial content through `level-design` and the editor.
+4. Add deterministic tests for transitions, resources, failure, and progression.
+5. Exercise the observable scenario with representative input.
+6. Capture before/after evidence for behavior, not only appearance.
+7. Evaluate the falsifier honestly; revise or remove a failed intervention.
+
+Useful evidence includes time to first decision, objective completion, route choice, build choice, resource state, failure cause, retry time, objective-verb distribution, and a player’s ability to explain goal/action/consequence. Metrics need a named hypothesis; do not optimize them in isolation.
+
+## 7. Failure modes
+
+- producing a long GDD instead of a playable slice
+- listing features without naming changed decisions
+- adding content to a shallow objective grammar
+- using passive progression to disguise unchanged play
+- copying a genre’s surface without its causal dynamics
+- treating more rewards as more motivation
+- fixing comprehension only with text or HUD
+- reporting a diagnosis after the user asked for improvement
+- calling deterministic tests proof that the experience works
+- calling a prettier screenshot proof that the loop works

package/skills/game-design/references/field-guide.md

@@ -0,0 +1,288 @@
+# Game design field guide
+
+Use this reference when a task needs more than the canonical workflow in [`SKILL.md`](../SKILL.md). It is a synthesis of research and shipped-game practice, not a universal formula. Select the tools that expose the current design risk and validate them with players.
+
+## Contents
+
+1. Experience hypotheses
+2. Actions, feedback, and decisions
+3. Nested loops
+4. Systems and economies
+5. Progression and challenge
+6. Onboarding and accessibility
+7. Multiplayer and social play
+8. Content structure and genre lenses
+9. Prototyping and playtesting
+10. JGengine translation
+11. Diagnostic questions
+12. Research basis
+
+## 1. Experience hypotheses
+
+### Write a working contract
+
+Use a compact table in the issue, task, or conversation. Do not preserve speculative prose as a large design document.
+
+| Question | Useful answer | Weak answer |
+| --- | --- | --- |
+| Who plays, where, and for how long? | “Two friends, 20-minute online co-op runs” | “Everyone” |
+| What do they repeatedly do? | “Scout, plan a breach, improvise when it fails” | “Experience action” |
+| What should dominate the experience? | “Tense coordination, expressive tools, recoverable chaos” | “Fun and immersive” |
+| What must it not become? | “Inventory chores, solved loadouts, long spectator time” | “Not boring” |
+| What proves the loop? | “A new pair completes one objective, explains its failure, and chooses a different second approach” | “Players like it” |
+
+Treat pillars as prioritization constraints. Make each pillar observable and give it an anti-pillar. When two features conflict, the pillar decides which survives.
+
+### Trace experience in both directions
+
+Use the Mechanics-Dynamics-Aesthetics separation as a causal check:
+
+- **Experience:** the intended emotional or social response.
+- **Dynamics:** the behavior that should emerge during play.
+- **Mechanics:** the rules, data, controls, and feedback likely to produce that behavior.
+
+Design backward from experience, then simulate forward from mechanics. A stealth meter does not guarantee tension; examine whether information, enemy response, recovery, and level geometry actually produce cautious planning.
+
+Use autonomy, competence, and relatedness as diagnostics, not mandatory quotas:
+
+- **Autonomy:** choices allow ownership and expression rather than cosmetic branching.
+- **Competence:** players can understand improvement and attribute outcomes to actions.
+- **Relatedness:** players can contribute, recognize others, and form meaningful social context.
+
+## 2. Actions, feedback, and decisions
+
+### Model a playable verb
+
+For every core verb, specify:
+
+1. cue and available information
+2. player intention and input
+3. target and eligibility rules
+4. simulation/state transition
+5. immediate visual, audio, haptic, and systemic feedback
+6. consequence that affects a later choice
+7. skill the player is expected to learn
+8. counterplay, cost, risk, or limitation
+
+An animation without a state consequence is presentation. A state change the player cannot perceive cannot reliably teach. Good moment-to-moment feel combines predictable physical response, amplified event importance, and assistance that honors player intention.
+
+### Test whether a choice is meaningful
+
+A decision usually needs:
+
+- at least two viable options the player can distinguish
+- enough information to form a plan, with uncertainty appropriate to the fantasy
+- a tradeoff rather than a universally dominant answer
+- a perceivable consequence at the promised time scale
+- an effect on future state, knowledge, position, relationships, or opportunity
+
+Not every input needs strategic depth. Execution, expression, discovery, role-play, and timing can carry play. Be precise about which kind of agency the design promises.
+
+Audit common choice failures:
+
+- **blind:** relevant information arrives only after commitment
+- **fake:** outcomes converge without expressive or narrative value
+- **solved:** one option dominates across contexts
+- **noisy:** feedback cannot be attributed to the choice
+- **overloaded:** too many new variables must be evaluated at once
+- **inert:** consequence does not alter anything the player values
+
+## 3. Nested loops
+
+### Loop anatomy
+
+Write each loop as:
+
+`state/cue -> goal -> informed action -> simulation -> feedback -> changed state -> next decision`
+
+The return state must differ in a useful way: new information, depleted or gained resources, changed position, higher mastery, altered relationships, new capability, or escalated world state. “Fight enemies, get loot, repeat” is incomplete until the design explains how loot changes subsequent fights and why choices remain interesting.
+
+### Time horizons
+
+| Horizon | Typical concern | Validation |
+| --- | --- | --- |
+| moment-to-moment | control, targeting, timing, feedback | Can players predict and correct an action? |
+| encounter/task | tactics, puzzle, risk, recovery | Do multiple verbs and resources create decisions? |
+| session/run | pacing, goals, build arc, stopping | Does the session reach a satisfying change or climax? |
+| campaign/meta | progression, variety, mastery, expression | Do unlocks create new play instead of only larger numbers? |
+| community | cooperation, competition, identity, shared stories | Can players contribute and recover from social friction? |
+
+Check coupling. The short loop must feed the long loop, and long-loop rewards must renew rather than trivialize the short loop.
+
+## 4. Systems and economies
+
+### Map flows before tuning
+
+For every tangible or abstract resource, record:
+
+- **source:** creates it
+- **pool/store:** holds it and defines capacity or decay
+- **converter:** changes it into another resource or state
+- **trade:** exchanges resources between owners
+- **gate:** requires a threshold or condition
+- **sink:** removes it from circulation
+
+Include time, attention, space, health, information, social trust, action opportunities, and risk when they behave like resources. Draw connections and simulate several player strategies before choosing numbers.
+
+### Audit feedback structures
+
+- Positive feedback amplifies an advantage; it can make growth satisfying but also cause runaway leaders.
+- Negative feedback resists deviation; it can stabilize play but feel punitive when it erases earned advantage.
+- A loop’s speed, delay, visibility, durability, and cap matter as much as its sign.
+- Randomness changes distribution, not only average outcome. Examine worst cases, streaks, and player control.
+
+Give resources clear jobs. A currency with no recurring sink accumulates into irrelevance; a sink without valued outcomes becomes tax. Use opportunity costs to create decisions, and cap or decay stockpiles only when that behavior supports the experience.
+
+### Balance relationships, not isolated values
+
+Maintain a tuning table with units, baseline, min/max, dependency, player-facing purpose, and test evidence. Derive related values from a small set of legible baselines. Inspect:
+
+- time-to-effect and time-to-recover
+- expected value and variance
+- throughput, capacity, scarcity, and replacement rate
+- breakpoints where an option changes from viable to dominant
+- compounding across upgrades and feedback loops
+- edge cases at zero, maximum, and repeated use
+
+## 5. Progression and challenge
+
+### Separate progression channels
+
+- **Mastery:** the player learns execution, planning, recognition, or social coordination.
+- **Content:** new spaces, problems, opponents, or stories become available.
+- **Breadth:** new tools or combinations expand the possibility space.
+- **Power:** existing actions become numerically stronger.
+- **Expression/status:** appearance, identity, collection, or public accomplishment changes.
+
+Prefer unlocks that create new decisions or recontextualize mastered skills. Numerical power is useful when it makes growth legible, but unchecked vertical scaling invalidates content and narrows viable options.
+
+Build a skill graph: assumed prior skills -> introduced skill -> safe practice -> independent test -> combination -> transformed use -> mastery proof. Provide fast paths or optional refreshers for players who arrive with different prior knowledge.
+
+### Treat difficulty as a vector
+
+Tune cognitive load, precision, timing, planning depth, memory, sensory discrimination, resource pressure, punishment, uncertainty, coordination, and persistence separately. A single easy/normal/hard multiplier cannot serve every barrier.
+
+Failure should answer:
+
+- What happened and why?
+- What can the player try differently?
+- How much meaningful progress is lost?
+- How quickly can the player act again?
+- Does recovery preserve tension without demanding repetition already mastered?
+
+Dynamic adjustment can change pressure frequency, assistance, resource supply, or challenge amplitude, but it must remain predictable enough for players to learn and must not counterfeit achievement.
+
+## 6. Onboarding and accessibility
+
+Teach inside representative play:
+
+1. prime attention before the mechanic matters
+2. invite the action with low failure cost
+3. give immediate, redundant feedback
+4. allow repetition or experimentation
+5. test without step-by-step prompting
+6. combine with one known mechanic
+7. make help recallable and skippable where appropriate
+
+Do not assume genre literacy, dual-stick control, rapid reading, color discrimination, precise timing, hearing, or uninterrupted attention. Preserve the intended experience through remapping, simplified input, adjustable timing, pause, granular challenge assists, redundant cues, readable objectives, and reduced repetition.
+
+## 7. Multiplayer and social play
+
+Design the social system before selecting transport:
+
+- define cooperative and competitive relationships, team sizes, and information boundaries
+- ensure every role has understandable contribution and moments of agency
+- limit involuntary downtime and give eliminated players meaningful next actions
+- specify join, leave, disconnect, reconnect, and uneven-player behavior
+- distinguish team comeback from hidden punishment of skilled play
+- bound griefing, collusion, kingmaking, smurfing, spawn abuse, and reward farming
+- test communication-light play and accessibility of coordination signals
+
+For persistent systems, model inflation, hoarding, market manipulation, time-zone advantage, seasonal resets, and what happens when population is sparse.
+
+## 8. Content structure and genre lenses
+
+Create a content matrix from mechanics and contexts rather than brainstorming isolated features. Useful axes include verb, target, constraint, topology, information state, resource state, opponent behavior, time pressure, social relationship, and consequence. Combine a few axes at a time and reserve unexplored combinations for progression.
+
+Apply genre lenses without treating them as templates:
+
+- **action/combat:** readability, positioning, threat priority, counterplay, recovery, expressive kit
+- **platforming/racing:** movement mastery, line choice, anticipation, risk, restart cost, readable boundaries
+- **puzzle:** information sufficiency, hypothesis formation, state legibility, undo/reset, insight rather than busywork
+- **strategy/management:** forecasts, opportunity cost, feedback loops, viable plans, recovery from early errors
+- **survival/crafting:** scarcity rhythms, transformation chains, expedition risk, homeward payoff, anti-grind
+- **narrative/social:** role expression, relationship consequences, authored versus emergent story, respectful irreversibility
+- **sandbox/open world:** self-directed goals, systemic interaction, discovery density, world response, return value
+
+## 9. Prototyping and playtesting
+
+### Prototype risk, not polish
+
+Name the riskiest assumption: control feel, decision depth, loop renewal, economy stability, social coordination, or content feasibility. Build the smallest slice that can disprove it with real input, real state transitions, and representative feedback.
+
+### Use a test protocol
+
+Record:
+
+- hypothesis and decision the test will inform
+- participant profile and prior skills
+- build/version, scenario, starting state, and task
+- observable success/failure thresholds
+- events and metrics to capture
+- moderator script that avoids teaching or defending the design
+- findings separated into behavior, interpretation, severity, confidence, and proposed cause
+
+Observe before interviewing. Ask players what they thought was happening, what they planned, and what evidence shaped the plan. Preferences are valuable but do not replace behavior. Telemetry describes what happened at scale; it rarely explains why.
+
+Use rapid iterative testing for obvious, high-confidence usability defects: make a small fix, test it with the next appropriate participant, and verify that it solves the problem without creating another. Do not churn balance or appeal based on one participant.
+
+Classify findings:
+
+- **comprehension:** goal, rule, state, or feedback misunderstood
+- **execution:** intention clear but control/precision/timing blocks action
+- **balance:** options or outcomes violate intended tradeoffs
+- **pacing:** pressure, rest, novelty, or payoff arrives at the wrong rate
+- **motivation:** player sees no valued reason to continue
+- **accessibility:** an avoidable barrier excludes a player
+- **technical:** implementation differs from the design contract
+
+## 10. JGengine translation
+
+- Keep the design contract and acceptance criteria in the tracked issue/PR, not a speculative document tree.
+- Put definitions, costs, rewards, tiers, recipes, and formulas in typed catalogs or config.
+- Put mutable state in serializable shared primitives and transitions in systems/commands.
+- Put placement, routes, terrain, markers, zones, foliage, and asset instances in `editor.scene.json` via `jgengine-editor`.
+- Query authored ids and semantics through `jgengine-world`; never copy coordinates into rules.
+- Use deterministic injected randomness and headless tests for loops, economies, and failure states.
+- Add telemetry only for a named design question and avoid collecting unnecessary player data.
+- If a reusable rule is missing, implement the narrow package primitive with the game as first adopter.
+
+## 11. Diagnostic questions
+
+Before calling a design coherent, ask:
+
+- Can a player state the immediate goal, available verbs, and likely consequences?
+- What interesting decision repeats, and how does context stop it becoming solved?
+- What does the player learn in the first minute, first session, and tenth session?
+- Which state changes make each loop worth repeating?
+- What behavior does each reward actually incentivize?
+- Where can positive feedback create a runaway result?
+- Which barriers are intentional challenge and which are accidental exclusion?
+- What happens after failure, success, mastery, interruption, and return?
+- What breaks with one player, the maximum player count, or a disconnect?
+- What evidence would cause the team to remove or redesign the feature?
+
+## 12. Research basis
+
+These sources provide lenses and evidence, not commandments:
+
+- Robin Hunicke, Marc LeBlanc, and Robert Zubek, [“MDA: A Formal Approach to Game Design and Game Research”](https://users.cs.northwestern.edu/~hunicke/MDA.pdf): trace mechanics, runtime dynamics, and intended experience causally and avoid using “fun” as the whole vocabulary.
+- Richard Ryan and collaborators, [Player Experience of Needs Satisfaction](https://selfdeterminationtheory.org/player-experience-of-needs-satisfaction-pens/): empirical motivation lens around autonomy, competence, and relatedness.
+- Joris Dormans, [“Simulating Mechanics to Study Emergence in Games”](https://ojs.aaai.org/index.php/AIIDE/article/view/12477): model resource flows, internal economies, and emergent feedback before implementation.
+- Daniel Cook, [“The Chemistry of Game Design”](https://www.gamedeveloper.com/design/the-chemistry-of-game-design): action/simulation/feedback/learning atoms and skill-chain analysis.
+- Robin Hunicke and Vernell Chapman, [“AI for Dynamic Difficulty Adjustment in Games”](https://users.cs.northwestern.edu/~hunicke/pubs/Hamlet.pdf): difficulty, resource supply, uncertainty, and the limitations of adjustment systems.
+- Christiane Birk and colleagues, [“Designing Game Feel: A Survey”](https://arxiv.org/abs/2011.09201): physical tuning, feedback amplification, and intent-supporting streamlining.
+- GDC, [“Prime, Teach, Observe”](https://gdcvault.com/play/1021120/Prime-Teach-Observe-Tutorializing-Innovative): teach mechanics through player modeling and iterative observation.
+- Microsoft Games Studios, [“Using the RITE Method to Improve Products”](https://jpattonassociates.com/wp-content/uploads/2015/04/rite_method.pdf): rapidly fix and empirically verify high-confidence usability problems.
+- Microsoft, [Xbox Accessibility Guidelines](https://learn.microsoft.com/en-us/xbox/accessibility/guidelines): player-informed guidance for input, objectives, feedback, difficulty, timing, sensory access, and communication.
+- Matthias Worch, [“Decisions That Matter”](https://gdcvault.com/play/1020570/): connect informed choice, agency, consequence, and level context.