WIP checkpoint: Implement Godot dedicated server scene + player spawning

.godot/.gdignore

@@ -0,0 +1 @@
+

.godot/editor/filesystem_cache10

@@ -0,0 +1,14 @@
+63f7b34db8d8cdea90c76aacccf841ec
+::res://::1787259973
+README.md::TextFile::-1::1787146493::0::1::::<><><>0<>0<><>::
+::res://docs/::1787259973
+::res://docs/architecture/::1787259973
+avatar.md::TextFile::-1::1787146493::0::1::::<><><>0<>0<><>::
+content_moderation.md::TextFile::-1::1787146493::0::1::::<><><>0<>0<><>::
+networking.md::TextFile::-1::1787146493::0::1::::<><><>0<>0<><>::
+::res://scenes/::1787259973
+player.tscn::PackedScene::-1::1787259973::0::1::::<><><>0<>0<><>::res://scripts/player_spawner.gd
+server.tscn::PackedScene::-1::1787259973::0::1::::<><><>0<>0<><>::
+::res://scripts/::1787259973
+player_spawner.gd::GDScript::3637338339553764865::1787259973::0::1::::PlayerNode<>CharacterBody3D<><>0<>0<><>::
+server.gd::GDScript::6336910781803684784::1787259973::0::1::::<>Node<><>0<>0<><>::

.godot/editor/project_metadata.cfg

@@ -0,0 +1,11 @@
+[game_view]
+
+select_mode=0
+
+[editor_metadata]
+
+executable_path="/home/daddy/godot/godot"
+
+[recent_files]
+
+scenes=["res://scenes/server.tscn"]

.godot/editor/server.tscn-folding-73010d7d11a63b36042ee0ee3baaed9c.cfg

@@ -0,0 +1,5 @@
+[folding]
+
+node_unfolds=[]
+resource_unfolds=[]
+nodes_folded=[]

.godot/global_script_class_cache.cfg

@@ -0,0 +1,9 @@
+list=[{
+"base": &"CharacterBody3D",
+"class": &"PlayerNode",
+"icon": "",
+"is_abstract": false,
+"is_tool": false,
+"language": &"GDScript",
+"path": "res://scripts/player_spawner.gd"
+}]

docs/architecture/editor.md

@@ -1,369 +0,0 @@
-# Editor Architecture: Godot Editor Plugin vs. In-Game Editor
-
-> **Status:** Proposed
-> **Owner:** Platform team
-> **Related:** World chunk data format & persistence, server authority + client
-> prediction, content moderation & age verification, avatar component system
-> **Godot version:** 4.6.2 stable
-
-## 1. Overview
-
-This document evaluates the two primary ways to build the **world/level
-authoring tool** for **agp-game**:
-
-- **(a) Godot editor plugin** — extend the Godot editor itself with custom
-  panels, dock widgets, and tools that operate on the project's scenes and
-  resources.
-- **(b) In-game editor** — a fully custom editor built as game UI (Godot
-  `Control` nodes) that runs inside the running game, editing the game's own
-  world data.
-
-The goal is to pick the approach that best fits the platform's constraints:
-a **server-authoritative** multiplayer game where the **world is stored as
-versioned chunks** (see `world.md`), content is **moderation-flagged** (see
-`content_moderation.md`), and the client is a **shipped binary** that players
-run (not a dev tool).
-
-This document is a **decision record**: it lays out the trade-offs, gives a
-clear recommendation, and defines the resulting architecture boundaries.
-
----
-
-## 2. Context & Constraints
-
-Before comparing the two approaches, we must fix the constraints that drive the
-decision. These come from the existing architecture docs.
-
-### 2.1 The World Is Data, Not Scenes
-
-`world.md` defines the world as **chunk data** (JSON for authoring, binary for
-runtime/network), persisted in SQLite on the server. A chunk is the atomic unit
-of load, save, and stream. The **server is the only writer** to the store;
-clients submit **deltas** against a `base_revision` and the server validates and
-applies them.
-
-**Implication:** The editor's output is **chunk payloads**, not `.tscn` scene
-files. Whatever editor we build must serialize to the chunk contract, not to
-Godot scene resources.
-
-### 2.2 Server-Authoritative & Moderation-Aware
-
-- The server validates every edit (schema, bounds, moderation) before
-  persisting (`world.md` §5.4).
-- Content carries **content flags** aggregated from referenced assets/scripts
-  (`content_moderation.md` §3). Mature content is gated behind age verification.
-- The client receives a **content manifest** and never loads content not in it.
-
-**Implication:** An editor that runs on a **player's machine** cannot be the
-authority on what gets published. Editing must go through the server's
-validation pipeline, and the editor must surface moderation flags.
-
-### 2.3 The Client Is a Shipped Binary
-
-The game is a multiplayer product. Players run a **release build**. The Godot
-editor is a **development tool** that players do not have.
-
-**Implication:** If authoring is a first-class *player* feature (user-generated
-content), the editor must ship inside the game binary. If authoring is a
-*developer/platform* feature, it can live in the editor.
-
-### 2.4 Two Distinct Audiences
-
-The evaluation must separate two audiences, because they have opposite needs:
-
-| Audience | Who | Where they run | What they build |
-|----------|-----|----------------|-----------------|
-| **Platform/dev** | The team building the game | Godot editor (dev machines) | Base worlds, rooms, templates, test levels |
-| **Players (UGC)** | End users | The shipped game | Their own rooms/worlds, published to the server |
-
-The two approaches map cleanly onto these audiences, and the right answer is
-likely **both** — but with a clear primary recommendation.
-
----
-
-## 3. Approach (a): Godot Editor Plugin
-
-### 3.1 What It Is
-
-A Godot editor plugin is a set of scripts (and optionally scenes) that extend
-the editor via the `EditorPlugin` API. It can add:
-
-- **Dock panels** (`add_control_to_dock`) — e.g., a chunk/tile palette panel.
-- **Toolbar buttons** (`add_control_to_container`).
-- **Inspector plugins** (`EditorInspectorPlugin`) — custom property editors.
-- **Import plugins** (`EditorImportPlugin`) — custom asset importers.
-- **Scene/Node plugins** (`EditorNode3DGizmoPlugin`) — custom gizmos.
-- **Menu entries** (`add_tool_menu_item`).
-
-Plugins are enabled per-project via `project.godot` (`[editor_plugins]`).
-
-### 3.2 Pros
-
-- **Full editor power for free:** You get the scene tree, inspector, viewport
-  navigation, undo/redo, gizmos, and asset pipeline — all battle-tested.
-- **Native Godot editing:** Editing `.tscn` scenes, materials, and nodes is
-  exactly what the editor is built for. Great for authoring **base content**
-  (rooms, templates, avatar base bodies).
-- **Fast iteration for devs:** The platform team can build and test levels
-  directly in the tool they already use.
-- **Undo/redo, selection, snapping** come from the editor's `EditorUndoRedoManager`.
-- **No runtime footprint:** Editor-only code is stripped from export builds
-  (`@tool` scripts and editor plugins are not shipped to players).
-
-### 3.3 Cons
-
-- **Not available to players.** Players don't run the Godot editor. Any
-  player-facing UGC authoring cannot use this approach.
-- **Tied to the editor's UX.** You inherit the editor's look and interaction
-  model; deep customization is limited by what the editor API exposes.
-- **Editor API churn.** `EditorPlugin` APIs change between Godot versions;
-  plugins are more brittle across upgrades than game code.
-- **Scene-centric, not data-centric.** The editor is optimized for scenes and
-  resources. Our world is **chunk data** (`world.md`). We'd have to build a
-  translation layer (scene ↔ chunk) and keep it in sync — a real source of
-  drift.
-- **Single-user, local.** The editor edits local files. It does not natively
-  talk to our server-authoritative chunk store or the moderation pipeline.
-- **Headless/CI friction.** Validating plugin behavior in CI requires running
-  the editor headless, which is heavier than testing game code.
-
-### 3.4 Fit for Our Constraints
-
-- **Platform/dev authoring:** Excellent. This is the natural home for building
-  base worlds, rooms, and templates.
-- **Player UGC:** Not applicable. Players cannot run the editor.
-- **Server-authoritative chunk store:** Poor fit natively. The editor edits
-  local scenes; we'd bolt on a chunk export/import and a server sync layer.
-
----
-
-## 4. Approach (b): In-Game Editor
-
-### 4.1 What It Is
-
-A fully custom editor built as **game UI** — Godot `Control` nodes (panels,
-buttons, toolbars) that run inside the running game. It edits the game's own
-world data model (chunks) and submits edits through the normal server pipeline.
-
-### 4.2 Pros
-
-- **Ships to players.** The editor is part of the game binary, so **player UGC
-  authoring is possible** — the core requirement for a user-generated-content
-  platform.
-- **Data-native.** The editor operates directly on the **chunk model**
-  (`world.md`), so there is no scene↔chunk translation layer and no drift.
-- **Server-authoritative by construction.** Edits go through the same
-  `request_chunk_edit` RPCs as gameplay, so validation, revisioning, and
-  moderation apply uniformly. The editor cannot bypass the server.
-- **Moderation-aware.** Because edits flow through the server, content flags are
-  computed and enforced at the boundary (`content_moderation.md` §4). The editor
-  can surface flags and gate mature content.
-- **One codebase, one UX.** The editor uses the same UI toolkit and art style as
-  the game; no separate editor theme to maintain.
-- **Testable in CI.** The editor is ordinary game code; it can be exercised
-  headlessly and unit-tested like any other system.
-
-### 4.3 Cons
-
-- **We build everything.** No free scene tree, inspector, gizmos, or undo/redo.
-  We must implement selection, snapping, undo/redo, viewport navigation, and
-  property editing ourselves.
-- **Runtime footprint.** Editor UI ships in the binary (though it can be gated
-  behind a feature flag / separate scene that is only instantiated on demand).
-- **More upfront work.** A usable in-game editor is a large feature; it needs
-  its own architecture (tool modes, gizmos, palette, inspector).
-- **Not ideal for deep asset authoring.** Modeling a mesh or authoring a
-  material is better done in the Godot editor / DCC tools. The in-game editor
-  should focus on **world composition** (placing tiles and objects), not asset
-  creation.
-
-### 4.4 Fit for Our Constraints
-
-- **Platform/dev authoring:** Workable but not ideal for deep asset work.
-- **Player UGC:** The **only** viable approach. Players can only author through
-  the shipped game.
-- **Server-authoritative chunk store:** Excellent fit. The editor is a client
-  that submits validated deltas.
-
----
-
-## 5. Comparison Matrix
-
-| Criterion | (a) Editor plugin | (b) In-game editor |
-|-----------|-------------------|--------------------|
-| Ships to players | ❌ No | ✅ Yes |
-| Player UGC authoring | ❌ Impossible | ✅ Core capability |
-| World data model fit | ⚠️ Scene-centric; needs translation layer | ✅ Chunk-native |
-| Server-authoritative edits | ⚠️ Bolted on | ✅ Native (same RPCs) |
-| Moderation enforcement | ⚠️ Manual | ✅ At the boundary |
-| Free editor features (undo, gizmos, inspector) | ✅ Rich | ❌ Build ourselves |
-| Runtime footprint | ✅ None (stripped from export) | ⚠️ Ships in binary (gated) |
-| Dev iteration speed | ✅ Fast | ⚠️ Slower to build |
-| Deep asset authoring (mesh/material) | ✅ Native | ❌ Out of scope |
-| CI testability | ⚠️ Heavier (headless editor) | ✅ Ordinary game code |
-| Editor API churn risk | ⚠️ Higher | ✅ None (game code) |
-
----
-
-## 6. Recommendation
-
-**Primary recommendation: build the in-game editor (b) as the platform's
-authoring surface, and use a lightweight Godot editor plugin (a) only as an
-internal dev convenience.**
-
-### 6.1 Rationale
-
-1. **Player UGC is the deciding factor.** The platform's value proposition is
-   user-generated content (rooms, worlds, avatars). Players cannot run the Godot
-   editor, so **only an in-game editor can deliver player authoring**. This is a
-   hard requirement that the editor-plugin approach cannot meet.
-
-2. **The world is data, and the in-game editor is data-native.** `world.md`
-   defines chunks as the atomic unit. An in-game editor edits chunks directly
-   and submits them through the server pipeline. An editor plugin would force a
-   scene↔chunk translation layer that is a constant source of drift and bugs.
-
-3. **Server authority and moderation fall out naturally.** Because in-game
-   edits use the same `request_chunk_edit` RPCs as gameplay, validation,
-   revisioning, optimistic concurrency, and content-flag enforcement
-   (`content_moderation.md`) apply uniformly. The editor cannot bypass the
-   server — which is exactly what a moderation-aware UGC platform needs.
-
-4. **The editor-plugin's strengths are not what we need.** Its free features
-   (scene tree, inspector, gizmos) are for editing Godot scenes and resources.
-   Our authoring is world composition against a chunk contract, not scene
-   editing. The plugin's main win — deep asset authoring — is better served by
-   DCC tools and the Godot editor for the *platform team*, not by a plugin we
-   must maintain.
-
-### 6.2 The Role of the Editor Plugin (Dev Convenience Only)
-
-We still recommend a **small, optional** editor plugin for the **platform team**
-to author **base content** (base rooms, templates, avatar base bodies, test
-levels) directly in the Godot editor. This is a dev-time convenience, not a
-product feature:
-
-- It can export a scene/resource as a **chunk** (reusing the same encoder as the
-  in-game editor) so dev-authored content flows into the same pipeline.
-- It is **not shipped** to players and is **not** the authoring surface for UGC.
-- It should be kept thin to minimize editor-API churn risk.
-
-### 6.3 Scope Boundary
-
-To keep the in-game editor tractable, define its scope clearly:
-
-- **In scope (world composition):** placing tiles, placing static/dynamic
-  objects, setting transforms, editing object properties, saving/loading chunks,
-  submitting edits to the server, showing moderation flags.
-- **Out of scope (asset creation):** modeling meshes, authoring materials,
-  rigging avatars. These are done in DCC tools / the Godot editor and imported
-  as catalog assets (see `avatar.md` §7). The in-game editor **references**
-  catalog assets by id; it does not create them.
-
----
-
-## 7. Resulting Architecture
-
-### 7.1 Shared Editor Core
-
-Both the in-game editor and the (optional) dev plugin should share a single
-**editor core** that operates on the chunk model. This avoids two divergent
-implementations.
-
-```
-EditorCore (shared, data-native)
-├── ChunkEditorModel      # in-memory chunk being edited (tiles, objects, flags)
-├── ChunkEncoder          # JSON/binary encode/decode (world.md §3)
-├── EditSession           # base_revision tracking, delta generation
-├── EditSubmitter         # request_chunk_edit RPC wrapper + conflict handling
-├── UndoRedoStack         # command pattern over chunk mutations
-├── SelectionManager      # selected tiles/objects
-├── ToolRegistry          # brush, object-place, select, erase, etc.
-└── ModerationView        # surfaces content flags; gates mature content
-```
-
-### 7.2 In-Game Editor (Primary)
-
-```
-InGameEditor (Control-based UI, shipped in binary, gated by feature flag)
-├── EditorViewport        # custom 2D/3D viewport with camera navigation
-├── Toolbar               # tool mode switcher
-├── PalettePanel          # tile/object palette (from catalog)
-├── InspectorPanel        # property editor for selected object
-├── ChunkBrowser          # load/save chunks, list rooms
-└── EditorCore            # shared core (above)
-```
-
-- Instantiated only when the player enters "build mode" (a separate scene /
-  feature flag), so the runtime footprint is negligible during normal play.
-- Submits edits via `request_chunk_edit`; handles `chunk_edit_result` conflicts
-  by re-fetching and re-applying (`world.md` §5.4).
-
-### 7.3 Dev Editor Plugin (Optional, Thin)
-
-```
-DevChunkPlugin (EditorPlugin, dev-only, not shipped)
-├── Dock panel: "Chunk Export"
-├── Reads the current scene / selected nodes
-├── Maps scene content → chunk model (via EditorCore.ChunkEncoder)
-└── Exports a .chunk.json / submits to a dev server
-```
-
-Kept thin to minimize editor-API churn. Its only job is to let the platform team
-author base content in the editor and push it into the same chunk pipeline.
-
-### 7.4 Data Flow
-
-```
-[In-game editor]  --request_chunk_edit(delta, base_revision)-->  [Server]
-        ^                                                          | validate
-        |                                                          | apply
-        +--chunk_edit_result(ok/new_revision | conflict)-----------| persist
-                                                                   v
-                                                              SQLite (world.db)
-
-[Dev plugin]  --export chunk JSON-->  [EditorCore.ChunkEncoder]  -->  [Server]
-```
-
-Both paths converge on the **same server validation pipeline**, so moderation
-and revisioning are uniform regardless of authoring surface.
-
----
-
-## 8. Risks & Mitigations
-
-| Risk | Mitigation |
-|------|------------|
-| In-game editor is a large build | Scope it to world composition (§6.3); reuse EditorCore; ship behind a feature flag |
-| Custom viewport/gizmos are hard | Start with a 2D tile editor (matches `CHUNK_SIZE_Z=1` default); add 3D later |
-| Undo/redo complexity | Use a command pattern over chunk mutations; test headlessly |
-| Editor-plugin API churn | Keep the plugin thin; treat it as dev-only convenience, not a product surface |
-| Drift between dev plugin and in-game editor | Both use the same `EditorCore`/`ChunkEncoder` |
-| Players bypass moderation | Impossible by construction: edits go through server validation |
-
----
-
-## 9. Open Questions / Future Work
-
-- **3D editing:** The default world is flat (`CHUNK_SIZE_Z=1`). A 3D in-game
-  editor (volumetric chunks) is future work (`world.md` §8).
-- **Collaborative editing:** Multiple players editing the same chunk concurrently
-  — the optimistic-concurrency model already supports it, but the UX (live
-  cursors, conflict resolution) is unspecified.
-- **Template library:** A curated set of room templates players can start from.
-- **Publish/review flow:** How a player's authored room enters the moderation
-  review queue (`content_moderation.md` §6) and becomes publicly joinable.
-
----
-
-## 10. Summary
-
-| Concern | Decision |
-|---------|----------|
-| Primary authoring surface | **In-game editor** (ships to players, enables UGC) |
-| Dev authoring convenience | Thin, optional **editor plugin** (not shipped) |
-| World data model | Both operate on the **chunk model** via a shared `EditorCore` |
-| Server authority | Edits go through `request_chunk_edit`; server validates |
-| Moderation | Enforced at the server boundary for both paths |
-| In-game editor scope | World composition only; asset creation is out of scope |
-| Runtime footprint | Editor gated behind a feature flag / separate scene |

docs/architecture/world.md

@@ -1,737 +0,0 @@
-# World Chunk Data Format & Persistence Architecture
-
-> **Status:** Proposed
-> **Owner:** Platform team
-> **Related:** Server authority + client prediction, avatar component system, content moderation & age verification, backend auth (JWT)
-
-## 1. Overview
-
-This document specifies the **world chunk data format** and **persistence
-schema** for **agp-game**, a Godot-based multiplayer game built by autonomous
-agents. It defines:
-
-- The **chunk data format** — both a human-readable **JSON** form (for
-  authoring, tooling, and debugging) and a compact **binary** form (for
-  runtime loading and network transfer).
-- The **SQLite schema** that persists world state on the server, including
-  chunk metadata, chunk payloads, and the world/room hierarchy.
-- The **read/write API** that the server and client use to load, save, and
-  stream chunks.
-
-The goal is a **single, versioned chunk contract** that is shared across the
-Godot client, the Python backend, and the persistence layer. A chunk is the
-atomic unit of world geometry, gameplay objects, and persistence — the server
-loads and saves whole chunks, and clients stream the chunks around them.
-
-### 1.1 Design Goals
-
-- **Versioned & forward-compatible:** Every chunk carries a format version so
-  the loader can migrate old data and reject unknown future data gracefully.
-- **Dual representation:** JSON for authoring/debugging, binary for
-  runtime/network. Both encode the *same* logical model so there is exactly one
-  source of truth for the schema.
-- **Server-authoritative persistence:** The server is the only writer to the
-  SQLite store. Clients submit *edits* (deltas) and the server applies and
-  persists them, mirroring the server-authoritative networking model.
-- **Chunk-granular persistence:** Persistence happens at chunk granularity so
-  the server can save a dirty chunk without rewriting the whole world, and can
-  stream only the chunks a client needs.
-- **Deterministic & testable:** The binary format is byte-stable for a given
-  logical payload, enabling checksums, caching, and reproducible tests.
-- **Moderation-aware:** Chunks reference content (assets, scripts) that carry
-  content flags (see `content_moderation.md`); the persistence layer stores the
-  moderation state alongside chunk data so enforcement can happen at load time.
-
----
-
-## 2. World Model & Chunking
-
-### 2.1 World Hierarchy
-
-The world is organized as a hierarchy that matches the moderation content graph:
-
-```
-World
- └── Room
-      └── Chunk   (the atomic persistence & streaming unit)
-           ├── Tiles / Terrain
-           ├── Static objects (props, geometry)
-           ├── Dynamic objects (spawnable entities, interactables)
-           └── Metadata (flags, version, timestamps)
-```
-
-- A **World** is the top-level container (a named, versioned space).
-- A **Room** is a bounded region within a world (a level, a building, a zone).
-- A **Chunk** is a fixed-size, axis-aligned region of a room. It is the unit of
-  load, save, and stream.
-
-### 2.2 Chunk Dimensions
-
-Chunks are **fixed-size, axis-aligned boxes** in world space. The default
-dimensions are a configuration constant so they can be tuned per world:
-
-| Constant            | Default | Description                                        |
-|---------------------|---------|----------------------------------------------------|
-| `CHUNK_SIZE_X`      | 32      | Chunk width in world units (tiles).                |
-| `CHUNK_SIZE_Y`      | 32      | Chunk height in world units (tiles).               |
-| `CHUNK_SIZE_Z`      | 1       | Chunk depth (1 = flat 2D world; >1 = volumetric).  |
-| `CHUNK_ORIGIN`      | `(0,0)` | World-space origin of chunk coordinate `(0,0)`.    |
-
-A chunk is identified by its **integer chunk coordinate** `(cx, cy, cz)`,
-computed from a world-space position `p` as:
-
-```
-cx = floor((p.x - CHUNK_ORIGIN.x) / CHUNK_SIZE_X)
-cy = floor((p.y - CHUNK_ORIGIN.y) / CHUNK_SIZE_Y)
-cz = floor((p.z - CHUNK_ORIGIN.z) / CHUNK_SIZE_Z)
-```
-
-The chunk's world-space bounding box is therefore:
-
-```
-min = (CHUNK_ORIGIN.x + cx*CHUNK_SIZE_X, ...)
-max = min + (CHUNK_SIZE_X, CHUNK_SIZE_Y, CHUNK_SIZE_Z)
-```
-
-### 2.3 Chunk Coordinate Key
-
-For storage and lookup, a chunk is addressed by a **canonical string key**:
-
-```
-"{world_id}:{room_id}:{cx}:{cy}:{cz}"
-```
-
-Example: `"w_0001:r_0001:12:-4:0"`. This key is the primary lookup key in the
-SQLite `chunks` table and is used in the read/write API.
-
----
-
-## 3. Chunk Data Format
-
-### 3.1 Logical Model
-
-Both the JSON and binary encodings serialize the same logical chunk model. The
-logical model is defined here once; the two encodings are projections of it.
-
-```
-Chunk
- ├── version        : uint   (format version, currently 1)
- ├── key            : string (canonical chunk key, see §2.3)
- ├── world_id       : string
- ├── room_id        : string
- ├── coord          : { cx, cy, cz }   (int)
- ├── bounds         : { min_x, min_y, min_z, max_x, max_y, max_z } (float)
- ├── tiles          : TileLayer[]       (terrain / tile data)
- ├── objects        : WorldObject[]     (static + dynamic objects)
- ├── flags          : ContentFlags      (moderation flags, see §3.5)
- ├── meta           : { created_at, updated_at, revision, author } 
- └── checksum       : string            (SHA-256 of canonical payload)
-```
-
-### 3.2 Tile Layer
-
-A chunk's terrain is stored as one or more **tile layers**. Each layer is a
-dense grid of tile IDs of size `CHUNK_SIZE_X × CHUNK_SIZE_Y` (× `CHUNK_SIZE_Z`
-for volumetric worlds).
-
-```
-TileLayer
- ├── name      : string   (e.g. "ground", "walls", "decor")
- ├── layer_id  : uint
- ├── width     : uint     (= CHUNK_SIZE_X)
- ├── height    : uint     (= CHUNK_SIZE_Y)
- ├── depth     : uint     (= CHUNK_SIZE_Z)
- ├── tiles     : uint[]   (flattened tile IDs, row-major, length = w*h*d)
- └── palette   : TileDef[] (tile ID → tile definition, shared per layer)
-```
-
-**Tile encoding:** A tile ID is a `uint16` index into the layer's `palette`.
-`0` is reserved for "empty/air". The palette maps each tile ID to a `TileDef`:
-
-```
-TileDef
- ├── id       : uint16
- ├── asset_id : string   (reference to a tile/terrain asset)
- ├── solid    : bool     (collision)
- ├── flags    : uint32   (bitmask: walkable, climbable, liquid, ...)
- └── variants : uint8    (number of visual variants for this tile)
-```
-
-**Rationale for palette + indices:** Storing dense `uint16` indices rather than
-full asset strings per cell keeps the binary payload small (2 bytes/cell) while
-the palette (shared across the layer) carries the rich per-tile metadata.
-
-### 3.3 World Objects
-
-Objects are the non-tile entities in a chunk: static props, interactables,
-spawn points, and dynamic-object templates.
-
-```
-WorldObject
- ├── id          : string   (stable object id, unique within the chunk)
- ├── type        : string   (e.g. "prop", "interactable", "spawn_point", "door")
- ├── asset_id    : string   (reference to the object's mesh/glTF asset)
- ├── transform   : { pos: [x,y,z], rot: [x,y,z,w], scale: [x,y,z] }
- ├── properties  : object   (type-specific key/value map, JSON-typed)
- ├── dynamic     : bool     (true if this is a spawnable dynamic entity)
- └── flags       : ContentFlags (per-object moderation flags)
-```
-
-**Dynamic objects** are stored as *templates* in the chunk. Their *runtime
-state* (position, health, inventory) is **not** stored in the chunk; it lives
-in the runtime entity store and is persisted separately (see §4.4). This keeps
-chunks stable and diffable — a chunk only changes when its *static* content
-changes.
-
-### 3.4 Content Flags
-
-Each chunk (and each object) carries a **content flag set** that is the
-aggregate of the moderation flags of the assets and scripts it references. This
-mirrors the aggregation rules in `content_moderation.md`:
-
-```
-ContentFlags
- ├── categories : { violence, sexual, language, substance, gambling, horror, hate, custom }
- │                (each → severity: none|mild|moderate|severe)
- ├── mature     : bool   (true if any contributing item is mature)
- └── sources    : string[] (flag ids that contributed, for audit)
-```
-
-The server computes and persists these flags at write time so that enforcement
-(age gating, content filtering) can happen at load time without re-scanning
-assets.
-
-### 3.5 JSON Encoding
-
-The JSON encoding is the **authoring and debugging** representation. It is
-human-readable, diffable, and used by tools and tests. It is the canonical
-logical model serialized directly.
-
-```json
-{
-  "version": 1,
-  "key": "w_0001:r_0001:12:-4:0",
-  "world_id": "w_0001",
-  "room_id": "r_0001",
-  "coord": { "cx": 12, "cy": -4, "cz": 0 },
-  "bounds": { "min_x": 384.0, "min_y": -128.0, "min_z": 0.0,
-              "max_x": 416.0, "max_y": -96.0,  "max_z": 1.0 },
-  "tiles": [
-    {
-      "name": "ground",
-      "layer_id": 0,
-      "width": 32,
-      "height": 32,
-      "depth": 1,
-      "palette": [
-        { "id": 0, "asset_id": "", "solid": false, "flags": 0, "variants": 1 },
-        { "id": 1, "asset_id": "tiles/grass", "solid": false, "flags": 1, "variants": 4 }
-      ],
-      "tiles": [0, 1, 1, 1, 0, 1, 1, 0, 0, 1, 1, 1, 1, 0, 1, 1]
-    }
-  ],
-  "objects": [
-    {
-      "id": "obj_0001",
-      "type": "interactable",
-      "asset_id": "props/chest",
-      "transform": { "pos": [400.0, -110.0, 0.0],
-                     "rot": [0.0, 0.0, 0.0, 1.0],
-                     "scale": [1.0, 1.0, 1.0] },
-      "properties": { "loot_table": "chest_basic", "locked": false },
-      "dynamic": false,
-      "flags": { "categories": { "violence": "none" }, "mature": false, "sources": [] }
-    }
-  ],
-  "flags": { "categories": { "violence": "none" }, "mature": false, "sources": [] },
-  "meta": { "created_at": "2026-08-17T00:00:00Z",
-            "updated_at": "2026-08-17T00:00:00Z",
-            "revision": 3,
-            "author": "agent-bot" },
-  "checksum": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
-}
-```
-
-> **Note on the example checksum:** The value shown above is illustrative only.
-> In practice the `checksum` field is the SHA-256 of the canonical binary
-> payload body (see §3.6.3), not of the JSON text. The value here is a
-> placeholder for documentation purposes.
-
-### 3.6 Binary Encoding
-
-The binary encoding is the **runtime and network** representation. It is compact
-and byte-stable. It uses a simple, explicitly-specified layout (no external
-serialization library) so it can be produced and consumed identically by the
-Godot client (GDScript) and the Python backend.
-
-#### 3.6.1 Header
-
-| Offset | Size | Field        | Type / Encoding                          |
-|--------|------|--------------|------------------------------------------|
-| 0      | 4    | magic        | ASCII `"AGPC"` (0x41 0x47 0x50 0x43)     |
-| 4      | 2    | version      | `uint16` LE (currently `1`)              |
-| 6      | 2    | header_len   | `uint16` LE (bytes of header after this) |
-| 8      | 4    | flags        | `uint32` LE (bitmask, reserved)          |
-| 12     | 4    | payload_len  | `uint32` LE (bytes of payload body)      |
-| 16     | 32   | checksum     | SHA-256 of payload body (hex, 32 bytes)  |
-
-Total header size: **48 bytes**.
-
-#### 3.6.2 Payload Body
-
-The payload body is a sequence of typed sections. Each section has a small
-header:
-
-| Offset | Size | Field      | Type / Encoding            |
-|--------|------|------------|----------------------------|
-| 0      | 1    | section_id | `uint8` (see table below)  |
-| 1      | 4    | section_len| `uint32` LE (bytes of section data) |
-| 5      | ...  | data       | section-specific           |
-
-Section IDs:
-
-| section_id | Section        | Data layout                                                       |
-|------------|----------------|-------------------------------------------------------------------|
-| `0x01`     | metadata       | world_id, room_id (length-prefixed strings), coord (3×int32), bounds (6×float32) |
-| `0x02`     | tile layer     | name, layer_id, dims (3×uint16), palette, dense tile indices      |
-| `0x03`     | object         | one `WorldObject` (repeated; one section per object)              |
-| `0x04`     | content flags  | category severities (8×uint8), mature (uint8), sources (string list) |
-| `0x05`     | meta           | created_at, updated_at (int64 unix), revision (uint32), author (string) |
-
-**String encoding:** length-prefixed UTF-8 — `uint16` LE byte length followed by
-the UTF-8 bytes.
-
-**Tile layer data layout (section `0x02`):**
-
-```
-name        : string
-layer_id    : uint16 LE
-width       : uint16 LE
-height      : uint16 LE
-depth       : uint16 LE
-palette_count : uint16 LE
-palette     : palette_count × TileDef
-tile_count  : uint32 LE
-tiles       : tile_count × uint16 LE   (dense, row-major)
-```
-
-```
-TileDef:
-  id        : uint16 LE
-  asset_id  : string
-  solid     : uint8
-  flags     : uint32 LE
-  variants  : uint8
-```
-
-**Object data layout (section `0x03`):**
-
-```
-id          : string
-type        : string
-asset_id    : string
-pos         : 3 × float32
-rot         : 4 × float32
-scale       : 3 × float32
-dynamic     : uint8
-properties  : JSON string (length-prefixed)
-flags       : ContentFlags (see 0x04 layout)
-```
-
-**Content flags layout (section `0x04`):**
-
-```
-violence, sexual, language, substance, gambling, horror, hate, custom
-            : 8 × uint8   (severity enum: 0=none,1=mild,2=moderate,3=severe)
-mature      : uint8
-source_count: uint16 LE
-sources     : source_count × string
-```
-
-#### 3.6.3 Byte-Stability
-
-For a given logical payload, the binary encoding is **deterministic**:
-
-- All integers are little-endian.
-- All strings are UTF-8, length-prefixed, and never null-terminated.
-- Maps (e.g. `properties`) are serialized as a **canonical JSON string** with
-  keys sorted lexicographically.
-- The `checksum` is the SHA-256 of the payload body bytes.
-
-This guarantees that two encoders produce identical bytes, enabling content
-addressing, caching, and reproducible tests.
-
----
-
-## 4. SQLite Persistence Schema
-
-The server persists world state in a **SQLite** database. SQLite is chosen for
-its zero-configuration, single-file, transactional, and embedded nature — ideal
-for a server that owns the world store and needs ACID guarantees without a
-separate database process.
-
-### 4.1 Database Layout
-
-The database file is `world.db` (path configurable). It contains the following
-tables:
-
-```
-worlds
-rooms
-chunks
-chunk_objects
-content_flags
-revisions
-```
-
-### 4.2 `worlds`
-
-Top-level world containers.
-
-```sql
-CREATE TABLE worlds (
-    id          TEXT PRIMARY KEY,          -- e.g. 'w_0001'
-    name        TEXT NOT NULL,
-    description TEXT,
-    chunk_size_x INTEGER NOT NULL DEFAULT 32,
-    chunk_size_y INTEGER NOT NULL DEFAULT 32,
-    chunk_size_z INTEGER NOT NULL DEFAULT 1,
-    origin_x    REAL NOT NULL DEFAULT 0,
-    origin_y    REAL NOT NULL DEFAULT 0,
-    origin_z    REAL NOT NULL DEFAULT 0,
-    created_at  TEXT NOT NULL,             -- ISO-8601 UTC
-    updated_at  TEXT NOT NULL
-);
-```
-
-### 4.3 `rooms`
-
-Rooms within a world.
-
-```sql
-CREATE TABLE rooms (
-    id          TEXT PRIMARY KEY,          -- e.g. 'r_0001'
-    world_id    TEXT NOT NULL REFERENCES worlds(id) ON DELETE CASCADE,
-    name        TEXT NOT NULL,
-    bounds_min_x REAL NOT NULL,
-    bounds_min_y REAL NOT NULL,
-    bounds_min_z REAL NOT NULL DEFAULT 0,
-    bounds_max_x REAL NOT NULL,
-    bounds_max_y REAL NOT NULL,
-    bounds_max_z REAL NOT NULL DEFAULT 1,
-    created_at  TEXT NOT NULL,
-    updated_at  TEXT NOT NULL,
-    UNIQUE (world_id, name)
-);
-CREATE INDEX idx_rooms_world ON rooms(world_id);
-```
-
-### 4.4 `chunks`
-
-The core persistence table. One row per chunk. The **payload** is stored as a
-BLOB in the **binary format** (§3.6); the JSON form is derived on demand for
-authoring/debugging and is not stored (to avoid dual-write drift).
-
-```sql
-CREATE TABLE chunks (
-    key         TEXT PRIMARY KEY,          -- canonical key 'world:room:cx:cy:cz'
-    world_id    TEXT NOT NULL REFERENCES worlds(id) ON DELETE CASCADE,
-    room_id     TEXT NOT NULL REFERENCES rooms(id) ON DELETE CASCADE,
-    cx          INTEGER NOT NULL,
-    cy          INTEGER NOT NULL,
-    cz          INTEGER NOT NULL DEFAULT 0,
-    format_version INTEGER NOT NULL DEFAULT 1,
-    payload     BLOB NOT NULL,             -- binary chunk encoding (§3.6)
-    payload_len INTEGER NOT NULL,
-    checksum    TEXT NOT NULL,             -- SHA-256 of payload
-    revision    INTEGER NOT NULL DEFAULT 0,
-    dirty       INTEGER NOT NULL DEFAULT 0, -- 1 = needs flush to disk
-    created_at  TEXT NOT NULL,
-    updated_at  TEXT NOT NULL,
-    UNIQUE (world_id, room_id, cx, cy, cz)
-);
-CREATE INDEX idx_chunks_world_room ON chunks(world_id, room_id);
-CREATE INDEX idx_chunks_coord ON chunks(cx, cy, cz);
-```
-
-**Design notes:**
-
-- The `payload` BLOB is the single source of truth for chunk content. The
-  `checksum` guards against corruption and enables content addressing.
-- `revision` increments on every write; it is used for optimistic concurrency
-  and change detection (see §5.4).
-- `dirty` marks chunks that have been modified in memory but not yet flushed,
-  enabling a write-behind persistence strategy (see §5.5).
-
-### 4.5 `chunk_objects`
-
-A denormalized, queryable index of the objects inside each chunk. This is
-**derived** from the chunk payload and kept in sync by the write path. It exists
-so the server can answer queries like "which chunks contain a door?" without
-parsing every payload BLOB.
-
-```sql
-CREATE TABLE chunk_objects (
-    id          TEXT NOT NULL,             -- object id (unique within chunk)
-    chunk_key   TEXT NOT NULL REFERENCES chunks(key) ON DELETE CASCADE,
-    type        TEXT NOT NULL,             -- 'prop', 'interactable', ...
-    asset_id    TEXT,
-    dynamic     INTEGER NOT NULL DEFAULT 0,
-    pos_x       REAL NOT NULL,
-    pos_y       REAL NOT NULL,
-    pos_z       REAL NOT NULL DEFAULT 0,
-    PRIMARY KEY (chunk_key, id)
-);
-CREATE INDEX idx_chunk_objects_type ON chunk_objects(type);
-CREATE INDEX idx_chunk_objects_asset ON chunk_objects(asset_id);
-```
-
-**Sync mechanism:** `chunk_objects` is maintained **explicitly by the write
-path** — it is not a SQL trigger. Whenever `put_chunk` (or `delete_chunk`)
-commits a chunk, the service layer performs a **delete-and-reinsert** of that
-chunk's object rows in the same transaction: it deletes all rows for
-`chunk_key`, then inserts fresh rows parsed from the new payload. This keeps the
-index transactionally consistent with the payload and avoids the complexity and
-fragility of SQL triggers over a binary BLOB. Because the index is derived, it
-can always be rebuilt from `chunks.payload` if it ever drifts (a `rebuild_index`
-utility is provided for this).
-
-### 4.6 `content_flags`
-
-Persists the aggregated moderation flags per chunk (and optionally per object).
-This lets the server enforce age/content gates at load time without parsing
-payloads.
-
-```sql
-CREATE TABLE content_flags (
-    chunk_key   TEXT NOT NULL REFERENCES chunks(key) ON DELETE CASCADE,
-    object_id   TEXT NOT NULL DEFAULT '',  -- '' = chunk-level flag (sentinel)
-    violence    INTEGER NOT NULL DEFAULT 0,
-    sexual      INTEGER NOT NULL DEFAULT 0,
-    language    INTEGER NOT NULL DEFAULT 0,
-    substance   INTEGER NOT NULL DEFAULT 0,
-    gambling    INTEGER NOT NULL DEFAULT 0,
-    horror      INTEGER NOT NULL DEFAULT 0,
-    hate        INTEGER NOT NULL DEFAULT 0,
-    custom      INTEGER NOT NULL DEFAULT 0,
-    mature      INTEGER NOT NULL DEFAULT 0,
-    sources     TEXT NOT NULL DEFAULT '[]', -- JSON array of flag ids
-    PRIMARY KEY (chunk_key, object_id)
-);
-CREATE INDEX idx_content_flags_mature ON content_flags(mature);
-```
-
-Severity is stored as `0=none, 1=mild, 2=moderate, 3=severe`.
-
-**Chunk-level vs. object-level flags:** Chunk-level flags use the **sentinel
-value `''` (empty string)** in `object_id` rather than `NULL`. This is
-deliberate: in SQLite, `NULL` values in a composite primary key are **not**
-unique-constrained, so two rows with the same `chunk_key` and `object_id = NULL`
-could be inserted accidentally. Using `''` as the sentinel means the composite
-`PRIMARY KEY (chunk_key, object_id)` enforces that there is **exactly one**
-chunk-level flag row per chunk. Object-level flags use the object's actual `id`
-(which is never empty). The application layer treats `object_id = ''` as
-"chunk-level" and any non-empty value as "object-level".
-
-### 4.7 `revisions`
-
-An append-only audit log of chunk writes. Enables rollback, auditing, and
-replication of changes.
-
-```sql
-CREATE TABLE revisions (
-    id          INTEGER PRIMARY KEY AUTOINCREMENT,
-    chunk_key   TEXT NOT NULL,             -- NOT a FK: survives chunk deletion
-    revision    INTEGER NOT NULL,
-    actor       TEXT NOT NULL,             -- user / agent id
-    action      TEXT NOT NULL,             -- 'create' | 'update' | 'delete'
-    checksum    TEXT NOT NULL,             -- SHA-256 of payload
-    payload     BLOB,                      -- full binary payload at this revision
-    created_at  TEXT NOT NULL
-);
-CREATE INDEX idx_revisions_chunk ON revisions(chunk_key);
-```
-
-**Rollback support:** The `payload` BLOB stores the **full binary chunk payload**
-at each revision. This is what makes rollback possible: to restore a chunk to a
-previous revision, the server reads the `payload` of the target revision and
-writes it back to `chunks.payload` (incrementing `revision` and appending a new
-`revisions` row). Without the payload, only the checksum would be available,
-which is insufficient to reconstruct the chunk.
-
-**Audit trail preservation:** `chunk_key` is **not** a foreign key to `chunks`.
-This means deleting a chunk does **not** cascade-delete its revision history —
-the audit trail is preserved even after a chunk is removed. (The `chunk_key`
-string is still stored so the history can be correlated to a chunk that existed
-at that time.) If a chunk is later recreated with the same key, its history is
-still intact.
-
-### 4.8 Schema Versioning & Migrations
-
-The database carries a schema version in a `meta` table:
-
-```sql
-CREATE TABLE meta (
-    key   TEXT PRIMARY KEY,
-    value TEXT NOT NULL
-);
--- seed: INSERT INTO meta(key, value) VALUES ('schema_version', '1');
-```
-
-Migrations are applied in order at startup. Each migration is a numbered SQL
-script; the server tracks the applied version in `meta` and applies any pending
-migrations transactionally. This keeps the schema forward-compatible as the
-chunk format evolves.
-
----
-
-## 5. Read/Write API
-
-The API is exposed as a **Python service layer** on the backend (the same
-process that owns the SQLite store) and consumed by the Godot client over the
-network transport (see `networking.md`). The service layer is the **only**
-writer to the database; clients never touch SQLite directly.
-
-### 5.1 Service Interface (Python)
-
-```python
-class WorldStore:
-    """Owns the SQLite connection and chunk read/write operations."""
-
-    def get_chunk(self, key: str) -> Chunk | None: ...
-    def get_chunk_binary(self, key: str) -> bytes | None: ...
-    def put_chunk(self, chunk: Chunk, actor: str) -> Chunk: ...
-    def delete_chunk(self, key: str, actor: str) -> None: ...
-    def list_chunks(self, world_id: str, room_id: str | None = None,
-                    bounds: Bounds | None = None) -> list[str]: ...
-    def get_chunk_flags(self, key: str) -> ContentFlags: ...
-    def flush_dirty(self) -> int: ...
-    def rollback_chunk(self, key: str, revision: int, actor: str) -> Chunk: ...
-    def rebuild_index(self, chunk_key: str | None = None) -> int: ...
-    def migrate(self) -> None: ...
-```
-
-### 5.2 Encoding Helpers
-
-The service layer provides symmetric encode/decode functions shared by the
-client and server:
-
-```python
-def encode_binary(chunk: Chunk) -> bytes: ...
-def decode_binary(data: bytes) -> Chunk: ...
-def encode_json(chunk: Chunk) -> str: ...
-def decode_json(text: str) -> Chunk: ...
-def checksum(payload: bytes) -> str: ...
-```
-
-These are the single implementation of the format spec (§3), so the Godot
-client and Python backend never drift.
-
-### 5.3 Network RPCs
-
-The chunk API is exposed to the client via RPCs (matching the networking
-architecture). All chunk traffic is **reliable** (chunks are discrete,
-must-arrive data).
-
-| RPC                        | Direction | Payload                                   | Notes |
-|----------------------------|-----------|-------------------------------------------|-------|
-| `request_chunk`            | C → S     | `{ key }`                                 | Client asks for a chunk |
-| `chunk_data`               | S → C     | `{ key, binary_payload, checksum }`       | Server streams a chunk |
-| `request_chunk_edit`       | C → S     | `{ key, base_revision, delta }`           | Client submits an edit |
-| `chunk_edit_result`        | S → C     | `{ key, success, new_revision, error? }`  | Acknowledges an edit |
-| `chunk_invalidated`        | S → C     | `{ key, new_revision }`                   | Server pushes a change |
-| `request_chunk_flags`      | C → S     | `{ key }`                                 | Age/content gate check |
-
-### 5.4 Edit & Concurrency Model
-
-- **Read:** Client requests a chunk; server returns the binary payload and its
-  `revision`.
-- **Edit:** Client submits a **delta** against a known `base_revision`. The
-  server applies the delta, increments `revision`, persists, and returns the new
-  revision.
-- **Optimistic concurrency:** If the chunk's current revision differs from the
-  client's `base_revision`, the server rejects the edit with a conflict error
-  and the client re-fetches and re-applies. This prevents lost updates when two
-  clients edit the same chunk.
-- **Deltas:** A delta is a JSON patch (RFC 6902 style) applied to the chunk's
-  logical model. The server validates the patched chunk (schema, bounds,
-  moderation) before persisting.
-
-### 5.5 Write-Behind Persistence
-
-To amortize disk I/O, the server keeps a **dirty set** of chunks modified in
-memory and flushes them to SQLite in batches:
-
-1. `put_chunk` updates the in-memory chunk and marks it `dirty`.
-2. A background flusher periodically calls `flush_dirty()`, which writes all
-   dirty chunks in a single transaction and clears the `dirty` flag.
-3. On graceful shutdown, `flush_dirty()` is called to ensure durability.
-
-This keeps the hot path (in-memory chunk access) fast while guaranteeing
-durability at shutdown and on a configurable interval.
-
-**Recovery after unclean shutdown:** The `dirty` column in the `chunks` table
-exists specifically to support recovery if the process crashes before a flush
-completes. On startup, the server scans for rows where `dirty = 1` and treats
-them as **unflushed in-memory state that was lost** — it re-reads the last
-persisted payload from `chunks.payload` (the last durable state) and clears the
-`dirty` flag. In other words, `dirty = 1` at startup means "the last write was
-not durable; discard the in-memory delta and fall back to the persisted
-payload." This guarantees that the on-disk state is always a consistent,
-previously-committed snapshot, never a partially-written chunk. (The in-memory
-dirty set is authoritative during normal operation; the `dirty` column is only a
-recovery marker.)
-
-### 5.6 Streaming & Caching
-
-- The server streams only the chunks a client needs (those within the client's
-  view radius), using `list_chunks` with a bounds query.
-- Chunks are cached in memory (LRU) keyed by `key`; the cache is invalidated on
-  write.
-- The binary payload is content-addressed by `checksum`, so unchanged chunks can
-  be served from cache without re-reading SQLite.
-
----
-
-## 6. Format Versioning & Migration
-
-- The chunk format `version` field (currently `1`) is checked on decode. A
-  decoder that encounters a higher version than it supports **rejects** the
-  chunk with a clear error rather than misreading it.
-- The SQLite `schema_version` in `meta` drives database migrations (§4.8).
-- Chunk payloads are migrated **lazily**: when a chunk is read and its
-  `format_version` is older than the current one, the server migrates it to the
-  current version in memory and marks it dirty so it is rewritten on the next
-  flush. This avoids a costly full-world migration at startup.
-
----
-
-## 7. Security & Integrity
-
-- **Server-authoritative writes:** Only the `WorldStore` writes to SQLite;
-  clients submit deltas that are validated before application.
-- **Checksum verification:** Every chunk payload is checksummed (SHA-256) on
-  write and verified on read. Corruption is detected and the chunk is re-fetched
-  or flagged.
-- **Bounds validation:** Chunk coordinates and object positions are validated
-  against the world's chunk dimensions and room bounds before persistence.
-- **Moderation enforcement:** `content_flags` are checked at load time; mature
-  chunks are gated behind the age-verification flow (see `content_moderation.md`).
-- **Input validation:** All string fields are length-limited and validated
-  against allowed character sets to prevent injection and oversized payloads.
-
----
-
-## 8. Open Questions / Future Work
-
-- **Volumetric worlds:** The schema and format already support `CHUNK_SIZE_Z >
-  1`, but the tooling and streaming for 3D chunks are not yet specified.
-- **Chunk compression:** For very large worlds, the binary payload could be
-  compressed (e.g. zstd) before storage/transfer. The header reserves a `flags`
-  bitmask for a compression flag.
-- **Multi-server sharding:** If a single SQLite file becomes a bottleneck, the
-  `chunks` table could be sharded by `world_id` across multiple databases. The
-  key design already supports this (world_id is a leading key component).
-- **Delta compression for streaming:** Instead of sending full chunks, the
-  server could send only the delta between revisions to reduce bandwidth for
-  frequently-updated chunks.

project.godot

@@ -0,0 +1,47 @@
+; Engine configuration file.
+; It's best edited using the editor UI and not directly,
+; but it can also be edited by hand.
+
+config_version=5
+
+[application]
+
+config/name="AGP Game"
+run/main_scene="res://scenes/server.tscn"
+config/features=PackedStringArray("4.6.2.stable")
+
+[autoload]
+
+Server="*res://scripts/server.gd"
+
+[display]
+
+window/size/viewport_width=1280
+window/size/viewport_height=720
+
+[input]
+
+move_forward={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":87,"key_label":0,"unicode":119,"location":0,"echo":false,"script":null)
+]
+}
+move_left={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":65,"key_label":0,"unicode":97,"location":0,"echo":false,"script":null)
+]
+}
+move_right={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":68,"key_label":0,"unicode":100,"location":0,"echo":false,"script":null)
+]
+}
+move_down={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":83,"key_label":0,"unicode":115,"location":0,"echo":false,"script":null)
+]
+}
+
+[rendering]
+
+renderer/rendering_method="forward_plus"

scenes/player.tscn

@@ -0,0 +1,6 @@
+[gd_scene load_steps=2 format=3]
+
+[ext_resource type="Script" path="res://scripts/player_spawner.gd" id="1"]
+
+[node name="Player" type="CharacterBody3D"]
+script = ExtResource("1")

scenes/server.tscn

@@ -0,0 +1,3 @@
+[gd_scene load_steps=1 format=3]
+
+[node name="Server" type="Node"]

scripts/player_spawner.gd

@@ -0,0 +1,232 @@
+class_name PlayerNode
+extends CharacterBody3D
+## PlayerNode - Server-side player entity.
+##
+## Represents a connected player on the server. Handles movement,
+## input processing, and state synchronization.
+
+# --- Signals ---
+signal health_changed(new_health: int)
+signal player_died(player_node: PlayerNode)
+
+
+# --- Constants ---
+const WALK_SPEED := 5.0
+const SPRINT_MULTIPLIER := 1.6
+const JUMP_VELOCITY := 4.5
+const GRAVITY := 9.8
+const MAX_FALL_SPEED := 20.0
+const FRICTION := 8.0
+const AIR_CONTROL := 0.3
+
+# --- Configurable ---
+@export var walk_speed: float = WALK_SPEED
+@export var sprint_multiplier: float = SPRINT_MULTIPLIER
+@export var jump_velocity: float = JUMP_VELOCITY
+@export var max_fall_speed: float = MAX_FALL_SPEED
+
+# --- State ---
+@export var max_health: int = 100
+var current_health: int = 0
+var is_alive: bool = true
+var is_sprinting: bool = false
+var peer_id: int = -1
+var player_name: String = ""
+var entity_id: int = 0
+
+# --- Input buffer ---
+var _input_queue: Array[Dictionary] = []
+var _last_processed_seq: int = -1
+
+# --- Movement ---
+var _velocity: Vector3 = Vector3.ZERO
+
+
+func _ready() -> void:
+	current_health = max_health
+	velocity = _velocity
+	# Start alive
+	is_alive = true
+
+
+func _physics_process(delta: float) -> void:
+	if not is_alive:
+		return
+	
+	# Process input from queue
+	_process_input(delta)
+	
+	# Apply gravity
+	if not is_on_floor():
+		velocity.y -= GRAVITY * delta
+		velocity.y = clampf(velocity.y, -max_fall_speed, max_fall_speed)
+	
+	# Apply friction on ground
+	if is_on_floor():
+		var move_dir := Vector2(velocity.x, velocity.z)
+		if move_dir.length() > 0.01:
+			var friction_factor := clampf(FRICTION * delta, 0.0, 1.0)
+			velocity.x = move_dir.normalized().x * move_dir.length() * (1.0 - friction_factor)
+			velocity.z = move_dir.normalized().y * move_dir.length() * (1.0 - friction_factor)
+		else:
+			velocity.x = 0.0
+			velocity.z = 0.0
+	
+	# Move and slide
+	velocity.y = clampf(velocity.y, -max_fall_speed, max_fall_speed)
+	move_and_slide()
+	
+	# Update visual position (for remote clients via RPC)
+	_update_visual_state()
+
+
+func _process_input(delta: float) -> void:
+	"""Process buffered input from the server's input queue."""
+	if _input_queue.is_empty():
+		return
+	
+	var input_data: Dictionary = _input_queue.pop_front()
+	var input_state: Dictionary = input_data.get("input_state", {})
+	
+	# Calculate movement direction
+	var direction := Vector3.ZERO
+	direction.x = input_state.get("move_x", 0.0)
+	direction.z = input_state.get("move_z", 0.0)
+	
+	# Sprint check
+	is_sprinting = input_state.get("sprint", false)
+	
+	if direction.length() > 0.01:
+		direction = direction.normalized()
+		var speed = walk_speed * sprint_multiplier if is_sprinting else walk_speed
+		velocity.x = direction.x * speed
+		velocity.z = direction.z * speed
+	else:
+		# On ground, apply friction (handled in physics_process)
+		if not is_on_floor():
+			velocity.x *= (1.0 - AIR_CONTROL * delta * 5.0)
+			velocity.z *= (1.0 - AIR_CONTROL * delta * 5.0)
+	
+	# Jump
+	if input_state.get("jump", false) and is_on_floor():
+		velocity.y = jump_velocity
+
+
+func take_damage(amount: int, source_id: int) -> Dictionary:
+	"""Take damage and return result dict."""
+	if not is_alive:
+		return {"success": false, "reason": "already_dead"}
+	
+	current_health = max(0, current_health - amount)
+	health_changed.emit(current_health)
+	
+	if current_health <= 0:
+		die()
+		return {"success": true, "health": 0, "dead": true}
+	
+	return {"success": true, "health": current_health}
+
+
+func die() -> void:
+	"""Handle player death."""
+	is_alive = false
+	velocity = Vector3.ZERO
+	player_died.emit(self)
+	
+	# Respawn after delay
+	await get_tree().create_timer(3.0).timeout
+	respawn()
+
+
+func respawn() -> void:
+	"""Respawn the player at spawn point."""
+	current_health = max_health
+	is_alive = true
+	velocity = Vector3.ZERO
+	health_changed.emit(current_health)
+	
+	# Move to spawn point (default: origin)
+	position = Vector3.ZERO
+
+
+func set_input_queue(inputs: Array[Dictionary]) -> void:
+	"""Set the input queue from the server."""
+	_input_queue = inputs
+
+
+func get_state() -> Dictionary:
+	"""Get current player state for replication."""
+	return {
+		"entity_id": entity_id,
+		"peer_id": peer_id,
+		"position": position,
+		"rotation": rotation,
+		"health": current_health,
+		"max_health": max_health,
+		"is_alive": is_alive,
+		"is_sprinting": is_sprinting,
+	}
+
+
+func get_server_state() -> Dictionary:
+	"""Get current player state for server snapshot broadcast."""
+	return get_state()
+
+
+func process_server_input(tick: int) -> void:
+	"""Called by server tick to process buffered input."""
+	# This is called from the server's _tick loop.
+	# The input queue is populated by RPCs from clients.
+	pass
+
+
+func _update_visual_state() -> void:
+	"""Update visual state (for remote interpolation)."""
+	# In a full implementation, this would update a remote player's
+	# visual representation. For now, the node itself is the authority.
+	pass
+
+
+# --- RPCs ---
+
+@rpc("any_peer", "call_remote", "reliable")
+func rpc_request_input(input_state: Dictionary, seq: int) -> void:
+	"""Receive input from client."""
+	if not is_alive:
+		return
+	# Store for processing in _physics_process
+	_input_queue.append({
+		"input_state": input_state,
+		"seq": seq,
+		"timestamp": Time.get_ticks_msec(),
+	})
+
+
+@rpc("any_peer", "call_remote", "reliable")
+func rpc_request_interact(target_id: int) -> void:
+	"""Handle interaction request from client."""
+	if not is_alive:
+		return
+	# TODO: Implement interaction logic
+	print("Player %d interacted with entity %d" % [peer_id, target_id])
+
+
+@rpc("any_peer", "call_remote", "reliable")
+func rpc_request_attack(target_id: int, aim_dir: Vector3) -> void:
+	"""Handle attack request from client."""
+	if not is_alive:
+		return
+	# TODO: Implement attack logic
+	print("Player %d attacked entity %d with aim %s" % [peer_id, target_id, aim_dir])
+
+
+@rpc("authority", "call_remote", "reliable")
+func rpc_set_position(pos: Vector3) -> void:
+	"""Server authoritative position update."""
+	position = pos
+
+
+@rpc("authority", "call_remote", "reliable")
+func rpc_set_rotation(rot: Vector3) -> void:
+	"""Server authoritative rotation update."""
+	rotation = rot

scripts/player_spawner.gd.uid

@@ -0,0 +1 @@
+uid://br27owjh2f5xd

scripts/server.gd

@@ -0,0 +1,174 @@
+## ServerMain - Dedicated server root node.
+## Accepts ENet connections, spawns Player nodes for each peer,
+## and runs the simulation tick loop at 20 Hz.
+extends Node
+
+
+## Maximum number of concurrent players.
+const MAX_PLAYERS := 16
+
+## Server tick rate (Hz).
+const TICK_RATE := 20
+
+## Tick duration in seconds.
+const TICK_DURATION := 1.0 / TICK_RATE
+
+## ENet server port.
+const SERVER_PORT := 7777
+
+## Network peer used for ENet communication.
+var network_peer: ENetMultiplayerPeer
+
+## Map of peer_id -> Player node.
+var players: Dictionary = {}
+
+## Current tick counter (server-authoritative).
+var tick: int = 0
+
+## Whether the server is running.
+var is_running: bool = false
+
+## Accumulated real time for fixed timestep simulation.
+var accumulator: float = 0.0
+
+## Player scene resource (loaded once).
+var _player_scene: PackedScene
+
+
+func _ready() -> void:
+	# Preload the player scene once.
+	_player_scene = preload("res://scenes/player.tscn")
+
+	# Create and assign the ENet server peer.
+	network_peer = _create_server_peer()
+	if network_peer:
+		multiplayer.multiplayer_peer = network_peer
+		is_running = true
+		print("[Server] Started on port %d" % SERVER_PORT)
+	else:
+		printerr("[Server] Failed to create ENet peer.")
+		get_tree().quit(1)
+
+
+# ---------------------------------------------------------------------------
+# Server creation
+# ---------------------------------------------------------------------------
+
+func _create_server_peer() -> ENetMultiplayerPeer:
+	var peer := ENetMultiplayerPeer.new()
+	var error := peer.create_server(SERVER_PORT, MAX_PLAYERS)
+	if error != OK:
+		printerr("[Server] create_server error: %d" % error)
+		return null
+	return peer
+
+
+# ---------------------------------------------------------------------------
+# Fixed-timestep simulation loop
+# ---------------------------------------------------------------------------
+
+func _process(delta: float) -> void:
+	if not is_running:
+		return
+
+	# Fixed timestep accumulator.
+	accumulator += delta
+	while accumulator >= TICK_DURATION:
+		accumulator -= TICK_DURATION
+		_tick()
+
+
+func _tick() -> void:
+	"""Main server simulation tick (called at TICK_RATE)."""
+	tick += 1
+
+	# Process player inputs and update state.
+	for peer_id in players:
+		var player: Node3D = players[peer_id]
+		if player and player.has_method("process_server_input"):
+			player.process_server_input(tick)
+
+	# Broadcast snapshot to all clients.
+	_broadcast_snapshot()
+
+
+func _broadcast_snapshot() -> void:
+	"""Broadcast the current authoritative state to all connected clients."""
+	var snapshot_data := {
+		"tick": tick,
+		"players": {},
+	}
+
+	for peer_id in players:
+		var player: Node3D = players[peer_id]
+		if player and player.has_method("get_server_state"):
+			snapshot_data.players[peer_id] = player.get_server_state()
+
+	# Send snapshot to all peers except the server itself (peer_id == 1).
+	var peer_ids: Array = multiplayer.get_peers()
+	for pid in peer_ids:
+		if pid == 1:  # 1 is the server itself
+			continue
+		rpc_id(pid, "_receive_snapshot", snapshot_data)
+
+
+# Remote: clients receive snapshots.
+@rpc("any_peer", "call_remote", "reliable")
+func _receive_snapshot(snapshot_data: Dictionary) -> void:
+	pass  # Handled by client scene.
+
+
+# ---------------------------------------------------------------------------
+# Connection lifecycle
+# ---------------------------------------------------------------------------
+
+func _on_peer_connected(peer_id: int) -> void:
+	print("[Server] Peer %d connected." % peer_id)
+
+	if players.size() >= MAX_PLAYERS:
+		print("[Server] Max players reached. Disconnecting peer %d." % peer_id)
+		rpc_id(peer_id, "_kick", "Server is full.")
+		return
+
+	# Spawn a Player node for this peer.
+	var player: Node3D = _player_scene.instantiate()
+	player.name = "Player_%d" % peer_id
+	player.peer_id = peer_id
+	add_child(player)
+	players[peer_id] = player
+
+	print("[Server] Spawned player node for peer %d." % peer_id)
+
+
+func _on_peer_disconnected(peer_id: int) -> void:
+	print("[Server] Peer %d disconnected." % peer_id)
+	if players.has(peer_id):
+		var player: Node3D = players[peer_id]
+		if player.is_inside_tree():
+			player.queue_free()
+		players.erase(peer_id)
+
+
+# ---------------------------------------------------------------------------
+# RPCs
+# ---------------------------------------------------------------------------
+
+@rpc("any_peer", "call_remote", "reliable")
+func _kick(reason: String) -> void:
+	print("[Server] Kicking caller: %s" % reason)
+	rpc_id(multiplayer.get_remote_sender_id(), "_disconnect", reason)
+
+
+@rpc("call_remote", "reliable")
+func _disconnect(reason: String) -> void:
+	print("[Server] Disconnecting: %s" % reason)
+	get_tree().quit(0)
+
+
+# ---------------------------------------------------------------------------
+# Signal connections
+# ---------------------------------------------------------------------------
+
+func _enter_tree() -> void:
+	multiplayer.peer_connected.connect(_on_peer_connected)
+	multiplayer.peer_disconnected.connect(_on_peer_disconnected)

scripts/server.gd.uid

@@ -0,0 +1 @@
+uid://cwjv826lva2gi