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/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.

poem.txt

@@ -1,3 +0,0 @@
-Bugs hide in the dark,
-Tests bring them into the light,
-Code stands strong and clear.

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