meat/.agents/plans/levels-and-editor.md

Levels & the in-game editor — direction note

Status: historical proposal, partially superseded. Captures a brainstorm so the next session starts from the conclusion, not a cold read. Nothing here is committed code; it's the shape we want and why.

Architecture note (2026-08-20): Naming and ownership sections below are superseded by docs/adr/0001-engine-owns-world-concepts.md and CONTEXT.md. Canonical terms are now engine LevelDefinition (live-level creation input), engine Level (live runtime), and clone-safe engine RenderScene; game owns concrete definitions and values. A future serializable editor document needs its own name rather than overloading these runtime terms. References below to game-owned world contracts, content kind fields/registries, game/Terrain.ts, or game/renderScene.ts describe the old code only. Editor goals remain valid but must use the canonical boundary.

The pivot

The game is heading toward a multiplayer twitch shooter. Each match loads a fresh, isolated level. Consequences that shape everything below:

• Maps are hand-made, not procedural. Procedural scatter is demoted to a tool (a starting-block generator), never the runtime map path. This is the whole reason the editor matters — the editor is the map pipeline.
• Real authoritative server. The server bakes the same map the clients do and runs the authoritative sim.
• No in-world level switching. You don't walk through a portal to another world; the match lifecycle loads a level at start. → portals / transition triggers are explicitly not needed.
• Persistence and player carry-over are YAGNI for now — but must not be walled off (see hedges).

Historical naming proposal: Level (data) vs Scene (runtime)

Agreed vocabulary — reads as "bake a Level into a Scene." Fits the type + namespace convention.

• Level = the authored, serializable data document (what an earlier draft called LevelSpec). Pure plain data. The editor's output; the network's payload; the server's and client's input.
• Scene = the baked runtime instance — the assembled world you render and simulate.

Repurposing note (so nobody trips): today the names mean something narrower — Level (game/level.ts:69) is a bake output and Scene (renderScene.ts:19) is a render-only, worker-cloneable subset. Under the new vocabulary:

• The name Level is freed for the authored data document.
• Scene grows to be the whole runtime instance — it absorbs the colliders
  • live mob array + terrain sampler that currently hang off Level. The thing cloned to workers stays a render-subset projection of the Scene (no colliders, no live mobs — those are main-thread only), exactly as the current Scene already is. This collapses today's incidental Level/Scene split (main.ts copies fields across) into two clear things.

So the pipeline is:

generator(params) → Level (data)   →   bake(level, textures) → Scene (runtime)
   (a TOOL: script / editor / never runtime)        (the runtime path)

(bake is today's buildLevel, renamed and re-typed to take a Level document. Namespace home — Scene.from(level) vs Level.bake() — is an open detail.)

The spine: the Level document

One serializable, explicit map document is the center of gravity. Four consumers, one artifact:

• Editor writes it.
• Server reads it — bakes headless, runs authoritative collision/sim.
• Client reads it — bakes the identical Scene to render + predict.
• Network ships it (or its id) at match start.

Because the bake is deterministic, server and every client bake byte-identical geometry and collision from the same Level — so only the document (or its id) crosses the wire, never geometry.

The one real refactor

Today the map definition is module-level constants welded inside buildLevel(). Split generation from baking: the generator produces an explicit Level; bake consumes it. bake should treat the explicit document (a list of placements) as canonical — the generator emits that form. This one cut serves three futures at once: multiplayer sync, the editor, and (later) persistence.

Build order

1. Level document + bake(level) + the gen/bake split. Pure game/, headless, unit-testable, no UI, no netcode. The whole foundation — do it first, on its own.
2. Then, in parallel — both ride the document, neither blocks the other:
   • Editor — in-engine, browser, app/. Emits a Level file.
   • Server — real authoritative, imports game/, bakes the Level headless.

The editor shape

• In-game, single-player, edit↔play toggle. Same running client: an edit mode to author the Level live, and a button that flips to play mode and drops you into the environment you're building. "Everything works except multiplayer" — full local sim (player, mobs, collision, later weapons) runs in play mode; no server, no netcode in the editor.
• The play toggle is a re-bake + mode switch — a loading beat, not a hot path. So it may freely re-bake and even reuse the existing worker respawn/reconfigure path; there is no match, so no live-worker-resync problem (the one genuinely hard sub-problem, thereby dodged).
• The engine already provides the hard parts: live first-person view, deterministic bake, and camera + Terrain.height for "where's the ground under the cursor" (raycast/picking). The remaining weight is UI/interaction. AGENTS.md notes "no DOM-built UI yet (deliberate)" — the editor is where that ends.

Editor features (the brainstorm)

Three feature buckets. For each: what's already there, the real new work, the catch.

1. Sidebar tree — level config + contents

A property inspector over the Level document. If the document is clean data, the tree is literally a view of it: each node = a field or an instance; edit a field = mutate the document + re-bake.

• World config already exists as data, just scattered: SkyConfig, the CloudLayer union (basicCumulus/fancyCumulus + params), TERRAIN (amplitude/frequency/peaks/inner/blend), GROUND_UV, room dims. Parameterizing = moving these constants into the Level.
• The tree forces one categorization: world property vs client look-preset. RenderConfig (internalWidth, colorDepth, dither, lodDistance, filters) is a per-viewer PS1 dial — stays client-side. Sky/clouds/terrain = per-map, in the document. But fog + lighting live in RenderConfig today, and in a shooter fog density = sightlines = a gameplay/map property → fog probably moves into the Level. Decide the world-vs-viewer line once, up front.
• Re-bake blast radius varies wildly: sky color = re-run sky, no chunk touch; one tree = re-bake 1–2 chunks; terrain amplitude = re-bake every chunk. For a tool, full re-bake per edit is fine to start; scope to dirty cells only if it janks.
• Anti-overengineering line: "everything parameterized" = document completeness (every knob is data — yes). It is not a mandate for a generic reflection-UI framework. Hand-wire panels for the handful of config sections; generalize to type-driven widgets only if it hurts.

2. Object tools — add / select / move / rotate

• Add — palette pick + raycast ground (camera + Terrain.height) → drop an instance record → re-bake. Easy.
• Select / pick — no GPU picking needed. Props bake to anonymous triangles, but the document retains the instance list with positions → ray-vs-instance-bounds test in JS, nearest hit wins. (Another reason instances must live on the document.)
• Move — drag → raycast ground → update position → re-bake touched cell(s). Crossing a chunk boundary re-bakes 2 (cell membership is by base position).
• Rotate — the one real engine gap. Props have no orientation today (Tree/ Boulder/Bush/Flower carry position + seed + size, no yaw; only mobs have heading, applied live via Mat4.compose). Fix by separating the per-instance transform from geometry-gen: build emits the instance's unique local-space geometry (keep seed/growth = shape), and the baker applies position + rotation + scale when appending to the chunk mesh. This mirrors what mobs already do (TRS via Mat4.compose) — props become "unique local mesh × transform," baked-in (static) where mobs are live (dynamic). This is the non-trivial refactor the object tools demand; do it early since it touches every prop builder.
• Gizmos — the rasterizer draws textured tris only, no line primitive. A move/rotate gizmo (and selection highlight / wireframe AABB) needs either thin-box tris or a new line-draw path. Start gizmo-less (drag on ground = XZ move, scroll/key = yaw; tinted re-draw for selection) and add handles later.

3. Terrain brushes — elevation + texture (the biggest new capability)

• Elevation needs a stored, editable heightfield — the thing that doesn't exist yet. Terrain.height is a pure analytic function of noise params; a brush has nowhere to write. So: the Level owns a height grid; procedural gen initializes it; brushes edit it directly; Terrain.height bilinear-samples the grid. ("Seeding is a tool," made concrete — noise seeds the grid, then you sculpt.)
  • Collision comes free — player + mobs already sample Terrain.height, so once it samples the grid, gameplay collision follows. No separate collision bake.
  • Welds still hold — patches weld by sampling shared height at shared world positions; grid-as-source keeps that. Re-bake only the brushed cells.
  • Side effect: the room "hole" + flat-inner-clearing special cases dissolve into authored terrain. An arena may drop the room concept entirely — the map is the sculpted terrain.
• Texture brush fits the engine shockingly well — the chunk baker already accumulates one mesh per material key and the renderer draws by DrawGroup list. Ground is one grass material today; painting = ground goes to N materials, each painted tri routed to its material's mesh by a per-vertex/per-cell material id — the exact routing the baker already does for props. No rasterizer change. Hard edges between materials (no blend) suit the PS1 look; soft splat-blending would need per-pixel multi-texture rasterizer work — skip it, add later only if missed.

Threads that cut across

1. The Level document gains three responsibilities: retain instance lists (pick/move), own an editable height grid (elevation), own a ground-material map (texture paint). All still pure data — the document grew, the architecture didn't strain.
2. One engine refactor unlocks the object tools: pull per-instance transform (pos/rot/scale) out of prop build into the baker — props become "unique local mesh × transform," matching mobs.
3. Terrain flips from function to data — analytic → stored grid. Biggest single change, but it's what "hand-made maps" means, and collision + welds fall out free.
4. Almost none of this needs new rendering — picking is JS, texture paint reuses per-material DrawGroups, terrain is more patch bake. The only genuinely new render bit is small + optional: line-draw for gizmos/selection.

Why the architecture already fits (the two bets that pre-paid for this)

• Deterministic bake — the world is byte-identical from a Level every run → multiplayer world-sync is nearly free (ship the document, everyone bakes the same).
• DOM-free engine/game, layering test-enforced — the authoritative server runs bake(level) + sim with no renderer; app/ is client-only glue. The layering seam already enforced (tests/layering.test.ts) is the client/server seam. Keep the Level document + bake in game/; editor UI in app/; server imports game/.

Cheap hedges (do now, save pain later)

• The Level document is pure serializable data — no closures, no behavior baked in (behavior stays code, imported per-side, as Entity already does it).
• A Level has an id/name — "load level X" is a reference; later persistence keys off it for free.
• Player state stays out of the Level/Scene (already true) — carry-over later touches the player, never the map.
• bake eats the explicit document as canonical — keeps the recipe-vs-explicit network choice open.
• No hardcoded buffer sizes tied to today's world — mob/framebuffer sizing already re-runs on setup; keep it so odd-shaped match maps just work.

Historical current-state facts (before 2026-08-20)

• buildLevel(textures): Level (game/level.ts:175) is the single entry, called once in app/main.ts. Today's Level (game/level.ts:69-81) is a bake result (chunks/meshes/colliders/mobs) — under the new naming it becomes part of Scene; the authored Level document is the missing input half. buildLevel becomes bake(level, textures) → Scene.
• Placement (placeTrees/placeBoulders/placeBushes/placeFlowers/placeMobs, game/level.ts:359+) is procedural from fixed seeds + counts, fully deterministic. These become the generator (emit a Level) rather than running inside the bake.
• Prop instances are discarded after bake — only anonymous triangles survive in per-chunk per-material meshes (buildChunks, game/level.ts:251). No level.trees to iterate. The editor edits the document, then re-bakes — never mutates baked meshes in place.
• Mobs are the exception — retained live, simulated each frame, crossing to workers as packed floats. Add/move/delete is cheap, no worker resync (caveat: mob shared buffer sized once to scene.mobCount in app/renderer.ts — growing past it needs a re-setup).
• Instance shapes are already small plain records (position + seed + kind/size/color/ growth) — editor-friendly, directly serializable. See game/actors/{Tree,Boulder,Bush,Flower,Mob}.ts.
• Prop geometry currently bakes position into world-space verts inside build, with seed/growth driving unique shape — hence the "separate transform from geometry-gen" refactor needed for rotate/scale (see Object tools).
• Terrain.height (game/Terrain.ts) is a pure analytic function, no stored heightfield — hence the elevation-brush needs a stored grid (see Terrain brushes).
• The render Scene (renderScene.ts:19) is the render-only subset already; the chunk baker already routes geometry to one mesh per material key — the mechanism the texture brush reuses.
• Workers hold a one-time structured clone of the render subset from init (app/renderer.ts setup); per-frame only camera/matrix/visible/mob buffers cross. Chunk-geometry edits reach workers only via a re-send (reconfigure→setup, respawns them — the same path keys 1/2/3 use). Fine for a mode-switch re-bake; would be the wall for live in-match editing, which we are not doing.

Explicitly out of scope / dropped

Portals & in-world transitions · persistence · player carry-over · procedural as the primary map path · any live-edit-during-a-multiplayer-match capability · GPU picking · soft terrain-texture blending (hard-edged materials first).