nEngine/docs/boundaries.md

Engine / Game Boundary

Where the engine ends and the game begins. Produced by a grilling session over the question: "What should a game engine do, and what should be left to the game itself?"

Source of truth for WHY a feature is (or is not) engine-built. Complements decisions.md (recorded as D19). Changes to this file must be reflected in decisions.md in the same change (D-op2).

The Criterion

A feature is built into the engine iff all three of these hold simultaneously:

1. Dataization value — the feature is meaningfully expressible as content data (YAML), so creators can author it without code.
2. Mod hook demand — gameplay-relevant subsystems need typed hook points Mods can register against.
3. MCP manipulability — agents/creators need tools to introspect or drive the feature.

Failure of any one → push the feature down (to fields + behavior language, or to the render layer / Mods entirely).

Ownership Model

Layer	Contents	Owner
L0 Infrastructure	Content pipeline, world/entity store, system host, event bus, Mod loader, MCP gateway, save serialization	Engine (built)
L1 Simulation mechanisms	General mechanisms passable by the criterion — dialogue, weather, placement, movement primitives	Engine (judged case-by-case)
L2 Expression layer	Behavior data language (conditions v1, state machines v2) — the escape hatch for most game logic	Engine (built)
L3 Game strategy	What to build, when to save, what prices to charge, what quests exist, minigames	Creators (100%)

Feature Verdicts

Feature	Verdict	Where it lives	Rationale
NPC	Movement primitive in engine; schedules → behavior language v2	npc entity + moveTo(x,y); schedules = time-triggered state machines	Schedules are state machines; a dedicated schedule system re-invents the state machine
Behavior language v2 (state machines)	Engine, Tier 2 lead item	v2 = v1 triggers + state machine syntax + onTime/onSchedule primitives	Critical path for NPC schedules, quests, events
Dialogue/story	Engine system	dialogue content (nodes/options/conditions), DialogueSystem, MCP dialogue.*, hooks onDialogueStart/onDialogueEnd	Dialogue is a content document, not a state machine; AI-authored dialogue is a core creation scenario (all three criteria met)
Friendship/affection	Field-level, data layer	npc.affection entity field; read/write via behavior language	Deterministic numeric rule — zero new engine code
Quests/events	Behavior language v2	State = quest stage; transitions = events/conditions; actions = rewards (give-item); progress in player.questProgress.<id>; authoring via behavior.* MCP	Quests are isomorphic to state machines; a QuestSystem re-invents the state machine
Weather	Lightweight engine system	world.weather field, content/weather.yaml (season→weather probability table), roll on day-start, weather-change event, hook onWeatherChange	"Roll a probability table" is a mechanism; the behavior language has no randomness
Stamina/fatigue	Field-level BUILT + demo'd (D29)	player.stamina field seeded by the engine (seedWorld: stamina: 100); rules via behavior language + Mods — the sample-game's daily-stamina machine restores stamina on day-start (set-state) and alerts on a condition (player.stamina lte 30, matching the fishing Mod's drain); the fishing Mod deducts stamina per cast	"Insufficient → block" is strategy; mechanism-izing it is brittle. No StaminaSystem
Buildings/placement	Placement primitive in engine	PlacementSystem: grid occupancy (footprint, overlap checks, buildability read from map data), place/remove type:"building" entities; building definitions (footprint/appearance/function) are data	Grid occupancy + overlap validation is geometric mechanism the behavior language can't express
Animals	Reuse existing mechanisms + data	type:"animal" entity + animal schema (growth cycle/output table/feed needs); GrowthSystem generalized to age field; output/feed rules via behavior language	Animals are isomorphic to crops — no new system
UI/HUD	Engine exposes UI logic state, render layer draws	Engine tracks current dialogue node / inventory / shop prices / quest progress, exposed via MCP + WebSocket; render layer draws freely	Zero UI-framework code in engine
Presentation data (sprites/sounds)	BUILT (D26 data/protocol + D27 render half + D31 asset pipeline)	sprite content kind (content/sprites/, programmatic draw instructions — rect/circle layers + the D31 image layer {src: assetId, x?, y?, w?, h?} referencing content/assets/ binaries) + sound content kind (content/sounds/, synth specs + D31 src audio asset references) + MCP sprite.*/sound.* + optional spriteRef appearance hints on crop/animal stages, buildings, and the player; binary assets (content/assets/) are NOT a content kind — a plain file table (registry.assets/engine.assets, base64) that YAML references by id (D31); both catalogs + the asset table ride the WS snapshot; render layer consumes them (D27/D31) — packages/render draws spriteRef frames (pure sprite-draw.ts: durationTicks-weighted animation clock at a documented default 10 fps, building footprint scaling, image commands with source-crop), draws map.tiles image textures (palette tileColor fallback), and plays sound defs on sound-play (synth via Web Audio OR src via decodeAudioData, lazy AudioContext)	Presentation is content-as-data (D4); the render layer consumes the draw instructions / synth specs / asset table / sound-play events and plays. Assets are filesystem content referenced by id — no schema, no MCP namespace (D31)
Audio	Event mechanism BUILT (D26) + playback BUILT (D27/D31)	play-sound action emits the sound-play bus event {soundId} (behavior-language-matchable, broadcast as an event frame); sound defs (content/sounds/) carry the synth spec and/or a D31 src audio asset id; the render layer's createSoundPlayer (packages/render/src/sound.ts) synthesizes the synth spec (OscillatorNode wave/freq/durationMs/gain/slideTo ramp) or decodes the src asset (base64 → decodeAudioData → AudioBufferSourceNode, buffers cached by id, src takes precedence over synth; AudioContext created lazily on the first user gesture per the autoplay policy)	Zero audio-library code in engine; playback is render-layer freedom (D1)
Multiplayer	Multi-viewport mechanism BUILT (D8/D24); multiplayer gameplay blank	N WebSocket clients subscribe to world state (render/sync BUILT 2026-08-12: apps/mcp-server --ws-port broadcast channel + connectWs browser client + snapshot-driven viewport drawing); multiplayer gameplay (multiple player entities, trading, permissions) left to creators	Multi-viewport sync is a mechanism; multiplayer rules are game content
Skills/proficiency	Field-level BUILT + demo'd (D29)	player.skills.{mining,farming,...} fields seeded by the engine (skills: {}); accumulation via set-state/Mod mutation + gte threshold unlocks — the sample-game's fishing Mod increments player.skills.fishing per catch	Same shape as stamina/affection; the D29 fishing Mod is the accumulation demonstration
Movement primitives	Grid movement + blocking check	moveTo tile-to-tile, simple blocking (non-walkable tiles, occupying entities), npc-move event with from/to	Pathfinding (A*/BFS) and collision systems stay out for now
Player input	Intent primitive BUILT (D25) + keyboard BUILT (D27) + onPlayerIntent hook (D29)	IntentSystem (id "intent"): handle(action, args) — move (player to a walkable tile, shared map-grid/placement helpers) and interact (smart plot action: harvest mature → water planted → sow first seed → till → error), player-intent bus event per call (success AND failure). Channels: MCP player.intent, WS {"type":"intent"}, connectLocal.intent — all thin adapters over the same mechanism. Hook (D29): player-intent → onPlayerIntent (16th hook; reverses D25.4's bus-only stance — Mods can't subscribe to raw bus events, and the intent payload is transient, so the "Mod hook demand" arm holds; the fishing Mod is the consumer). Keyboard (D27): the dev app's arrow-key keydown → sync.input("key:Arrow<…>") — ws mode sends the D26 raw input message (server maps arrows → IntentSystem.move), local mode maps the same arrowDirection delta client-side	Interact priority order is the v1 engine default (content-izable later); a seed picker is future UI; the browser toolbar UI is render-layer freedom (D24)
Math / randomness	Seeded RNG mechanism BUILT (D28)	RandomSource (packages/core/src/random.ts, mulberry32-style mirroring LÖVE's love.math.RandomGenerator): seedRandom(seed) / randomSeed(); engine-owned engine.rng (seeded via createEngine({seed?})), injected into systems via SystemInitCtx.rng — WeatherSystem day-start rolls and PlantingSystem harvest drop chances draw from it; MCP rng.* debug surface (rng.get/rng.set/rng://state); save.* carries rngState {seed, calls} and restore re-anchors the seed	Determinism is a mechanism (replay/tests/Mods); "draw from the engine RNG" replaces scattered Math.random calls. Declined LÖVE gaps (D28 adjudication): text rendering / particles → render-layer freedom; image-atlas + audio files → ADOPTED (D31) — the asset pipeline builds them as content/assets/ binaries referenced by id (sprite image layer, map.tiles, sound.src); physics/threading/compression/window/video/sensor/joystick → not applicable; Tauri → deferred
Minigames (fishing/mining/festivals)	Mod / render layer — fishing demo'd (D29)	Engine guarantees trigger conditions + reward settlement (give-item) + progress (entity fields) via data + language; the minigame body lives in the Mod — the sample-game's fishing Mod hooks onPlayerIntent, settles the catch on water tiles (fish grant, stamina cost, skills.fishing, mod:fish-caught/mod:fish-too-tired events the language matches), and the fishing-treat machine turns mod:fish-caught into a reward	No built-in minigame framework; D29 is the escape-hatch demonstration (D5/D19)

Pattern Cheat-Sheet

Feature kind	Destination
Content document (dialogue, shops, crops)	Engine system + content schema
Random mechanism (weather rolls, drop chances)	Engine system + shared seeded RNG (D28) — engine.rng via SystemInitCtx.rng
Geometry/spatial (placement, movement)	Engine primitive
Temporal state (schedules, quests)	Behavior language v2 (state machines)
Deterministic numeric + rules (affection, stamina, skills)	Entity fields + behavior language

Tier 2 Build List (derived from this session)

1. Behavior language v2 — state machine syntax + onTime/onSchedule triggers (lead item; critical path for NPC schedules/quests/events) BUILT (2026-08-12): statemachine content kind + behavior.statemachine.* MCP tools + onSchedule time primitive + onStateChange hook. See decisions.md D20, mcp.md §behavior, api.md §4/§7.
2. Dialogue system — dialogue schema + DialogueSystem + MCP dialogue.* + onDialogueStart/onDialogueEnd hooks BUILT (2026-08-12): dialogue content kind (content/dialogues/<id>.yaml) + DialogueSystem (active state on the dialogue:active world entity) + MCP dialogue.* (7 tools incl. debug start/choose + 2 resources + 1 prompt) + onDialogueStart/onDialogueEnd hooks. See decisions.md D21, mcp.md §dialogue, api.md §4/§7.
3. WeatherSystem — weather.yaml + weather-change event + onWeatherChange hook BUILT (2026-08-12): weather single-file content kind (content/weather.yaml) + WeatherSystem (weighted roll on day-start, injectable RNG, state on the weather world entity) + weather-change event + onWeatherChange hook + MCP weather.* (2 debug tools + 1 resource). See decisions.md D21, mcp.md §weather, api.md §4/§7.
4. PlacementSystem — grid occupancy (footprint/overlap/buildability) BUILT (2026-08-12): building content kind (content/buildings/<id>.yaml) + PlacementSystem (grid footprint/overlap/buildability-from-map-data, place/remove type:"building" entities) + placement-change event + onPlacementChange hook + MCP placement.* (5 building lifecycle tools + 4 debug tools + 3 resources + 1 prompt). See decisions.md D22, mcp.md §placement, api.md §4/§7.
5. NPC grid-movement primitive — moveTo + blocking check + npc-move event BUILT (2026-08-12): MovementSystem (id movement) — moveTo tile-to-tile with a simple blocking check (unwalkable "water" tiles, blocksMovement buildings via PlacementSystem.occupies) + npc-move event with from/to + MCP npc.* (5 debug tools + 1 resource, no prompts). No pathfinding (A*/BFS), no collision system, no NPC schedules (those are behavior language v2 content). See decisions.md D22, mcp.md §npc, api.md §4.
6. Reuse/generalization: GrowthSystem generalized to animal age BUILT (2026-08-12): animal content kind (content/animals/<id>.yaml — growth cycle + produce table, data only) + GrowthSystem generalized to advance BOTH type:"plot" (CropDef) and type:"animal" entities (AnimalDef) — animal entities carry {animalId, stageIndex?, daysInStage?, fed?}, feedRequired mirrors waterRequired, feed mirrors water; feed/produce RULES are behavior-language content hooking the animal-grow/animal-produce/animal-fed bus events; hooks onAnimalGrow/onAnimalProduce; MCP animal.* (9 tools + 2 resources + 1 prompt). See decisions.md D23, mcp.md §animal, api.md §4/§7. Tier 2 core is now complete (items 1–6 with the tick loop from Task A).
7. Multi-viewport sync (render/sync) — optional render-layer extension BUILT (2026-08-12, D24): the final Tier 2 item. apps/mcp-server gains an optional --ws-port <port>/FARM_WS_PORT WebSocket broadcast channel in the same process (snapshot on connect + on {"type":"sync"}, event frames per bus emission, defensive JSON serialization); packages/render/src/sync/ws.ts connectWs (browser-native WebSocket, same handle shape as connectLocal); viewport.render(snapshot?) draws map + basic entity shapes (pure shapes.ts geometry — plots/buildings/dots, no art); apps/dev parameterized (?contentDir=/?modsDir=/?sync=ws&url=ws://...). MCP surface unchanged. See decisions.md D24, mcp.md transport section, api.md §1. Tier 2 is now fully complete.

Change Log

Date	Change	Files
2026-08-13	Asset pipeline BUILT (D31) — the D28 "image-atlas + audio files" gap is adopted, closing the D26-reserved atlas/audio-file capability. Presentation data row: sprite gains the image layer (src = asset id), sound.src becomes a real audio asset id, map gains tiles (tile-id → asset id); binary assets (content/assets/, .png/.ogg) are NOT a content kind — the loader builds an asset table (registry.assets/engine.assets, base64) that YAML references by id; the table rides the bundle and the WS snapshot. Render: image layers draw via PixiJS textures (data: URLs, cache by id, async + redraw-on-ready), map tiles draw from map.tiles, sound.src plays via decodeAudioData (buffers cached). Audio row: src playback added (src takes precedence over synth). Math/randomness row: the D28 declined "image-atlas + audio files" verdict flips to ADOPTED (D31) — no atlas format (single-tile assets by id, sprite-sheet atlas documented as future). MCP surface unchanged — no assets.* namespace (D31.8).	boundaries.md, decisions.md (D31), mcp.md, api.md, AGENTS.md, examples/sample-game/README.md
2026-08-12	Tier 3 content round (D29): stamina/skills field-level rows marked BUILT + demo'd, minigame row demo'd, onPlayerIntent hook adjudicated. Stamina/fatigue and Skills/proficiency verdict rows flip from "Field-level, data layer" to Field-level BUILT + demo'd (D29): the engine seeds player.stamina: 100 and player.skills: {} (data, not systems); the sample-game's daily-stamina machine demonstrates both a condition on player.stamina (low-stamina alert) and a day-start restore (set-state), and the fishing Mod accumulates player.skills.fishing. Minigames row flips to Mod / render layer — fishing demo'd (D29): the fishing Mod hooks the new onPlayerIntent (16th hook — see the player-input row) and settles catches on water tiles (fish grant, stamina cost, mod:fish-caught/mod:fish-too-tired custom events the behavior language matches via fishing-treat). Player-input row gains the D29 hook adjudication.	boundaries.md, decisions.md (D29), mcp.md, api.md, AGENTS.md, examples/sample-game/README.md
2026-08-12	Deterministic seeded RNG BUILT (D28) — the ONE gap adopted from the engine-vs-LÖVE grill; all other LÖVE gaps consciously declined and recorded. New "Math / randomness" verdict row (mechanism BUILT): RandomSource (packages/core/src/random.ts, mulberry32-style mirroring love.math.RandomGenerator — seedRandom(seed)/randomSeed(), next()/nextInt(max)/setSeed/state(): {seed, calls}); engine-owned engine.rng (createEngine({seed?})) injected into systems via SystemInitCtx.rng — WeatherSystem day-start rolls and PlantingSystem harvest drop chances now draw from it (the only two randomness consumers); MCP rng.* debug namespace (18th: rng.get/rng.set/rng://state, no prompts); save.* snapshot carries rngState {seed, calls} and restore re-anchors the seed (calls reset to 0, draw replay not built). The cheat-sheet's random-mechanism row now points at the shared seeded RNG. Declined gaps (adjudicated in D28, NOT built): text rendering + particles → render-layer freedom (D1/D6); image/atlas + audio files → reserved Tier 3 (D26 maintained); physics → grid-blocking covers collision; threading/compression/window/video/sensors/joystick → not applicable; Tauri → deferred.	boundaries.md, decisions.md (D28), mcp.md, api.md, AGENTS.md
2026-08-12	Player input mechanism BUILT (D25) — the engine's first direct player-input primitive (previously input was MCP-debug-only per D3's "runtime MCP is debug-only"; D25 adds the mechanism for human play while keeping MCP as one debug adapter). IntentSystem (id "intent", auto-booted): handle(action, args) for move {tile} (walkability + blocking via the shared map-grid/placement helpers, NOT MovementSystem.moveTo — npc-move untouched) and interact {tile} (v1 priority order harvest → water → sow-first-seed → till → error, delegating to PlantingSystem); every call emits player-intent (success AND failure). Three thin channels over the same mechanism: MCP player.intent + player://state (15th namespace), WS {"type":"intent"} message + snapshot gains time, connectLocal.intent. Sync handles are now uniform (intent/setTimeLabel/refresh/destroy); viewport.tileAt + an Interact/Move toolbar make the dev app playable in both local and ws modes. The interact priority order is the v1 hardcoded engine default (content-izable later); the browser toolbar/HUD is render-layer freedom (D24 — the engine exposes the intent result + world state, the render layer draws).	boundaries.md, decisions.md (D25), mcp.md, api.md, architecture.md, AGENTS.md
2026-08-12	Tier 2 item 7 built: multi-viewport sync (render/sync) — Tier 2 fully complete. Item 7 (previously "optional render-layer extension") is now BUILT per D24: apps/mcp-server hosts an optional --ws-port <port>/FARM_WS_PORT WebSocket broadcast channel in the same process (snapshot on connect/sync request; event frames broadcast to all clients per bus emission; defensive JSON serialization — non-serializable payloads skipped, never a crash); packages/render/src/sync/ws.ts connectWs implements the LocalSyncHandle shape client-side (browser-native WebSocket, auto-reconnect, fresh-snapshot re-sync per event frame, time label from day-start/time-tick-style payloads); viewport.render(snapshot?) now draws map + basic entity shapes (pure shapes.ts geometry: plots tilled/watered/crop-stage, buildings as footprint blocks, npc/player/animal dots — no art); apps/dev parameterized via ?contentDir=/?modsDir=/?sync=ws&url=ws://.... The engine event bus is exposed as engine.events (readonly) for the broadcast subscriber — the only core change. MCP surface unchanged (85 tools / 22 resources / 10 prompts / 14 namespaces); the WS channel is NOT a namespace. Multiplayer gameplay (multiple players, trading, permissions) remains creator content.	boundaries.md, decisions.md (D24), mcp.md, api.md, architecture.md, AGENTS.md
2026-08-12	Tier 2 items 5 & 6 (tick loop + animal age) built — Tier 2 core complete. Item 5's "fine-grained intra-day timing awaits a tick loop" limitation is now resolved: engine.tick(dt) (dt in ticks) is the authoritative explicit driver (D8 — no render loop), driving TimeSystem (boundary events + new time-tick {day, season, tickInDay} per step) and every system's step in registration order (GrowthSystem accumulates day-fractions); onSchedule gains at: {tickInDay: n} evaluated on time-tick; optional auto-tick via createEngine({tickIntervalMs}) (OFF by default). Item 6's animal generalization: animal content kind + GrowthSystem advancing type:"animal" entities through AnimalDef stages with a fed flag mirroring watered; feed/produce rules remain behavior-language content (decision #9 — engine emits animal-grow/animal-produce/animal-fed, grants nothing); MCP animal.* namespace + hooks onAnimalGrow/onAnimalProduce. The last remaining Tier 2 item is the optional multi-viewport sync (render/sync), which is a render-layer concern.	boundaries.md, decisions.md (D23), mcp.md, api.md
2026-08-12	Initial draft (grilling session: engine vs game boundary)	boundaries.md, decisions.md (D19), AGENTS.md
2026-08-12	Tier 2 item 1 built: behavior language v2 (state machine syntax + onSchedule time primitive). The "temporal state → behavior language v2" row of the pattern cheat-sheet now has a concrete mechanism: schedules/quests/events are content state machines. NPC schedules and quests remain creator content built on this language (no dedicated schedule/quest system — per D19, a dedicated system would re-invent the state machine). Fine-grained intra-day timing still awaits a tick loop (documented limitation in mcp.md/api.md).	boundaries.md, decisions.md (D20), mcp.md, api.md
2026-08-12	Tier 2 items 2 & 3 built: dialogue + weather. Dialogue is a content-document system (nodes/choices/conditions — a document, not a state machine, per D19), confirming the "content document → engine system" cheat-sheet row; weather is a lightweight probability-roll system ("roll from a probability table" is a mechanism; the behavior language has no randomness). Both snapshot via world entities (dialogue:active, weather).	boundaries.md, decisions.md (D21), mcp.md, api.md
2026-08-12	Tier 2 items 4 & 5 built: placement + NPC grid movement. Both confirm the "geometry/spatial → engine primitive" cheat-sheet row — they are the two final Tier 2 engine subsystems. Placement: building content kind (footprint/buildable/blocksMovement are data), PlacementSystem (grid footprint, overlap, buildability from map data, place/remove building entities), placement-change event + onPlacementChange hook. Movement: MovementSystem moveTo + simple blocking (unwalkable tiles + blocksMovement buildings) + npc-move event. No pathfinding/collision systems, no NPC schedules (state-machine content). Tier 2 remains open only for item 6 (GrowthSystem→animal age generalization + multi-viewport sync).	boundaries.md, decisions.md (D22), mcp.md, api.md