WIP checkpoint: Plan: Creator Studio — Extended Authoring Tools

.gitignore

@@ -8,6 +8,3 @@ export/
 # OS
 .DS_Store
 Thumbs.db
-
-# Godot UID files (regenerated from path)
-*.uid

backend/app/config.py

@@ -30,7 +30,6 @@ class Settings(BaseSettings):
     # File uploads
     UPLOAD_DIR: str = "uploads"
     MAX_UPLOAD_SIZE_MB: int = 100
-    GLTF_MAX_FILE_SIZE_MB: int = 200
 
     model_config = SettingsConfigDict(
         env_file=".env",

backend/app/routers/assets.py

@@ -1,6 +1,5 @@
 """Asset management router."""
 
-import json
 import os
 from pathlib import Path
 from typing import Optional
@@ -14,7 +13,6 @@ from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.asset import Asset, AssetType
 from app.models.world import World
-from app.services import gltf as gltf_service
 from pydantic import BaseModel, Field
 
 router = APIRouter()
@@ -66,14 +64,6 @@ def _sanitize_filename(filename: str) -> str:
     return safe or "file"
 
 
-def _detect_asset_type(filename: Optional[str], content: bytes) -> AssetType:
-    """Detect the asset type from filename and content."""
-    if filename and gltf_service.looks_like_gltf(content, filename):
-        return AssetType.MODEL_3D
-    # Fallback: let the caller decide based on mime_type or default.
-    return AssetType.OTHER
-
-
 # --- Endpoints ---
 
 @router.post("/", response_model=AssetResponse, status_code=201)
@@ -193,16 +183,10 @@ async def upload_asset_file(
     # Sanitize filename to prevent path traversal.
     safe_filename = _sanitize_filename(file.filename or f"asset_{asset_id}")
 
-    # Read the file content.
+    # Validate file size against configured maximum.
+    max_bytes = settings.MAX_UPLOAD_SIZE_MB * 1024 * 1024
     content = await file.read()
     file_size = len(content)
-
-    # Determine which size limit to apply.
-    if gltf_service.looks_like_gltf(content, file.filename):
-        max_bytes = settings.GLTF_MAX_FILE_SIZE_MB * 1024 * 1024
-    else:
-        max_bytes = settings.MAX_UPLOAD_SIZE_MB * 1024 * 1024
-
     if file_size > max_bytes:
         raise HTTPException(
             status_code=413,
@@ -216,28 +200,10 @@ async def upload_asset_file(
     file_path = upload_dir / stored_name
     file_path.write_bytes(content)
 
-    # Detect asset type from content/filename.
-    detected_type = _detect_asset_type(file.filename, content)
-
-    # Update asset record.
     asset.file_path = str(file_path)
     asset.mime_type = file.content_type
     asset.file_size = file_size
 
-    # If this is a glTF file, extract and store metadata.
-    if detected_type == AssetType.MODEL_3D:
-        try:
-            metadata = gltf_service.extract_gltf_metadata(content)
-            asset.metadata_json = json.dumps(metadata)
-            # Also set the asset type to model_3d if it was auto-detected.
-            if asset.asset_type == AssetType.OTHER:
-                asset.asset_type = AssetType.MODEL_3D
-        except ValueError as exc:
-            raise HTTPException(
-                status_code=400,
-                detail=f"Invalid glTF file: {exc}",
-            )
-
     await db.commit()
     await db.refresh(asset)
     return asset

backend/app/services/gltf.py

@@ -1,197 +0,0 @@
-"""Lightweight glTF / GLB metadata extraction.
-
-This module intentionally avoids heavyweight dependencies such as trimesh or
-pygltflib. For the metadata fields the asset upload pipeline needs (mesh and
-vertex counts, animation presence, texture references, and the bounding box)
-a small amount of glTF-specific parsing is sufficient and keeps the backend
-dependency-free.
-"""
-
-from __future__ import annotations
-
-import json
-import struct
-from typing import Any, Optional
-
-# GLB binary header magic bytes ("glTF").
-_GLB_MAGIC = b"glTF"
-_GLB_MAGIC_INT = 0x46546C67  # b"glTF" interpreted as little-endian uint32
-_GLB_JSON_CHUNK_TYPE = 0x4E4F534A  # "JSON"
-_GLB_BIN_CHUNK_TYPE = 0x004E4942  # "BIN\0"
-
-# Whitespace allowed around a GLB JSON chunk. The spec pads with spaces (0x20),
-# but be lenient with null bytes and other whitespace that real exporters emit.
-_JSON_CHUNK_TRIM = b" \t\r\n\x00"
-
-
-def looks_like_gltf(content: bytes, filename: Optional[str] = None) -> bool:
-    """Return True when the bytes or filename indicate a glTF/GLB asset."""
-    if content.startswith(_GLB_MAGIC):
-        return True
-
-    if filename:
-        lowered = filename.lower()
-        if lowered.endswith(".gltf") or lowered.endswith(".glb"):
-            return True
-
-    # A bare JSON buffer (e.g. uploaded without an extension) that has the
-    # glTF asset marker is also a glTF file.
-    stripped = content.lstrip()
-    if stripped.startswith(b"{"):
-        try:
-            payload = json.loads(stripped.decode("utf-8"))
-        except (ValueError, UnicodeDecodeError):
-            return False
-        return isinstance(payload, dict) and "asset" in payload and "version" in payload.get("asset", {})
-
-    return False
-
-
-def _parse_glb(content: bytes) -> dict[str, Any]:
-    """Parse the JSON chunk of a GLB binary container."""
-    if len(content) < 12:
-        raise ValueError("GLB file is too short")
-
-    magic, _version, _length = struct.unpack_from("<III", content, 0)
-    if magic != _GLB_MAGIC_INT:
-        raise ValueError("invalid GLB magic")
-
-    offset = 12
-    json_chunk: Optional[dict[str, Any]] = None
-
-    while offset + 8 <= len(content):
-        chunk_length, chunk_type = struct.unpack_from("<II", content, offset)
-        offset += 8
-        chunk_end = offset + chunk_length
-        if chunk_end > len(content):
-            raise ValueError("GLB chunk overruns file boundary")
-
-        chunk_data = content[offset:chunk_end]
-        if chunk_type == _GLB_JSON_CHUNK_TYPE:
-            try:
-                json_chunk = json.loads(chunk_data.strip(_JSON_CHUNK_TRIM).decode("utf-8"))
-            except (ValueError, UnicodeDecodeError) as exc:
-                raise ValueError(f"invalid GLB JSON chunk: {exc}") from exc
-
-        offset = chunk_end
-
-    if json_chunk is None:
-        raise ValueError("GLB file does not contain a JSON chunk")
-
-    return json_chunk
-
-
-def _parse_gltf_json(content: bytes) -> dict[str, Any]:
-    """Parse a plain .gltf JSON file."""
-    stripped = content.lstrip()
-    try:
-        payload = json.loads(stripped.decode("utf-8"))
-    except (ValueError, UnicodeDecodeError) as exc:
-        raise ValueError(f"invalid glTF JSON: {exc}") from exc
-
-    if not isinstance(payload, dict):
-        raise ValueError("glTF JSON root must be an object")
-    return payload
-
-
-def _position_accessor_counts(gltf: dict[str, Any]) -> list[int]:
-    """Return POSITION accessor counts for every mesh primitive."""
-    counts: list[int] = []
-    accessors = gltf.get("accessors", [])
-    for mesh in gltf.get("meshes", []):
-        for primitive in mesh.get("primitives", []):
-            attributes = primitive.get("attributes", {})
-            position_index = attributes.get("POSITION")
-            if position_index is None:
-                continue
-            try:
-                accessor = accessors[int(position_index)]
-            except (IndexError, TypeError, ValueError):
-                continue
-            count = accessor.get("count")
-            if isinstance(count, int):
-                counts.append(count)
-    return counts
-
-
-def _position_bounds(gltf: dict[str, Any]) -> list[list[float]]:
-    """Return min/max bounds for every POSITION accessor that declares them."""
-    bounds: list[list[float]] = []
-    accessors = gltf.get("accessors", [])
-    for mesh in gltf.get("meshes", []):
-        for primitive in mesh.get("primitives", []):
-            attributes = primitive.get("attributes", {})
-            position_index = attributes.get("POSITION")
-            if position_index is None:
-                continue
-            try:
-                accessor = accessors[int(position_index)]
-            except (IndexError, TypeError, ValueError):
-                continue
-            minimum = accessor.get("min")
-            maximum = accessor.get("max")
-            if isinstance(minimum, list) and isinstance(maximum, list):
-                bounds.append([float(x) for x in minimum])
-                bounds.append([float(x) for x in maximum])
-    return bounds
-
-
-def _texture_refs(gltf: dict[str, Any]) -> list[str]:
-    """Collect external texture source references from the image array."""
-    refs: list[str] = []
-    for index, image in enumerate(gltf.get("images", [])):
-        uri = image.get("uri")
-        if isinstance(uri, str) and not uri.startswith("data:"):
-            refs.append(uri)
-            continue
-
-        name = image.get("name")
-        if isinstance(name, str) and name:
-            refs.append(name)
-            continue
-
-        if isinstance(uri, str):
-            # Embedded data URI; keep a stable, non-huge reference.
-            refs.append(f"data:{index}")
-            continue
-
-        buffer_view = image.get("bufferView")
-        if buffer_view is not None:
-            refs.append(f"bufferView:{buffer_view}")
-            continue
-
-        refs.append(f"image:{index}")
-
-    return refs
-
-
-def extract_gltf_metadata(content: bytes) -> dict[str, Any]:
-    """Extract upload-relevant metadata from glTF/GLB bytes.
-
-    Raises ValueError for malformed glTF content. The returned dict contains:
-        mesh_count, vertex_count, has_animation, texture_refs,
-        bounding_box_min, bounding_box_max.
-    """
-    if content.startswith(_GLB_MAGIC):
-        gltf = _parse_glb(content)
-    else:
-        gltf = _parse_gltf_json(content)
-
-    position_counts = _position_accessor_counts(gltf)
-    bounds = _position_bounds(gltf)
-
-    if bounds:
-        bounding_box_min = [min(axis) for axis in zip(*bounds[::2])]
-        bounding_box_max = [max(axis) for axis in zip(*bounds[1::2])]
-    else:
-        bounding_box_min = [0.0, 0.0, 0.0]
-        bounding_box_max = [0.0, 0.0, 0.0]
-
-    return {
-        "mesh_count": len(gltf.get("meshes", [])),
-        "vertex_count": sum(position_counts),
-        "has_animation": bool(gltf.get("animations")),
-        "texture_refs": _texture_refs(gltf),
-        "bounding_box_min": bounding_box_min,
-        "bounding_box_max": bounding_box_max,
-    }

backend/requirements.txt

@@ -9,14 +9,6 @@ pydantic==2.10.3
 pydantic-settings==2.7.0
 python-jose[cryptography]==3.3.0
 passlib[bcrypt]==1.7.4
-# passlib 1.7.4 (last release, unmaintained since ~2020) detects its bcrypt
-# backend via bcrypt.__about__.__version__, which bcrypt>=4.1 removed --
-# hashing/verifying a password then raises "password cannot be longer than
-# 72 bytes" (a misleading downstream symptom of the real AttributeError:
-# module 'bcrypt' has no attribute '__about__') on every call. Without this
-# pin, `pip install -r requirements.txt` silently grabs whatever the latest
-# bcrypt is and breaks register/login outright. Pin below 4.1 explicitly.
-bcrypt==4.0.1
 python-multipart==0.0.20
 email-validator==2.2.0
 httpx==0.28.1

backend/tests/test_gltf_metadata.py

@@ -1,220 +0,0 @@
-"""Tests for the lightweight glTF metadata extraction service."""
-
-import json
-import struct
-import pytest
-
-from app.services.gltf import (
-    extract_gltf_metadata,
-    looks_like_gltf,
-    _parse_glb,
-    _parse_gltf_json,
-)
-
-
-# ---------------------------------------------------------------------------
-# Test data helpers
-# ---------------------------------------------------------------------------
-
-def _make_gltf_json(
-    meshes: int = 1,
-    vertices_per_mesh: int = 24,
-    has_animations: bool = False,
-    images: list[dict] | None = None,
-) -> dict:
-    """Build a minimal glTF JSON structure."""
-    accessors = []
-    meshes_data = []
-    for i in range(meshes):
-        acc_index = len(accessors)
-        accessors.append({
-            "bufferView": 0,
-            "componentType": 5126,  # FLOAT
-            "count": vertices_per_mesh,
-            "type": "VEC3",
-            "max": [1.0, 1.0, 1.0],
-            "min": [-1.0, -1.0, -1.0],
-        })
-        meshes_data.append({
-            "primitives": [{
-                "attributes": {"POSITION": acc_index},
-            }],
-        })
-    gltf = {
-        "asset": {"version": "2.0"},
-        "accessors": accessors,
-        "meshes": meshes_data,
-    }
-    if has_animations:
-        gltf["animations"] = [{"name": "anim1", "channels": [], "samplers": []}]
-    if images:
-        gltf["images"] = images
-    return gltf
-
-
-def _make_glb(gltf_json: dict) -> bytes:
-    """Wrap *gltf_json* in a minimal GLB binary container."""
-    json_bytes = json.dumps(gltf_json).encode("utf-8")
-    json_length = len(json_bytes)
-    # Pad JSON chunk to 4-byte boundary.
-    json_padding = (4 - json_length % 4) % 4
-    json_chunk = json_bytes + b"\x00" * json_padding
-    json_chunk_type = 0x4E4F534A  # "JSON"
-    # No BIN chunk.
-    bin_length = 0
-    bin_chunk_type = 0x004E4942
-    total_length = 12 + 8 + len(json_chunk) + 8 + bin_length
-    header = struct.pack("<III", 0x46546C67, 2, total_length)  # magic, version, length
-    json_header = struct.pack("<II", len(json_chunk), json_chunk_type)
-    if bin_length > 0:
-        bin_header = struct.pack("<II", bin_length, bin_chunk_type)
-    else:
-        bin_header = b""
-    return header + json_header + json_chunk + bin_header
-
-
-# ---------------------------------------------------------------------------
-# looks_like_gltf
-# ---------------------------------------------------------------------------
-
-class TestLooksLikeGltf:
-    def test_glb_magic(self):
-        assert looks_like_gltf(b"glTF\x00\x00\x00\x00") is True
-
-    def test_gltf_extension(self):
-        assert looks_like_gltf(b'{"asset":{"version":"2.0"}}', "model.gltf") is True
-
-    def test_glb_extension(self):
-        assert looks_like_gltf(b"some binary", "model.glb") is True
-
-    def test_json_with_asset_version(self):
-        payload = json.dumps({"asset": {"version": "2.0"}}).encode()
-        assert looks_like_gltf(payload) is True
-
-    def test_plain_json_no_asset(self):
-        payload = json.dumps({"foo": "bar"}).encode()
-        assert looks_like_gltf(payload) is False
-
-    def test_non_json_bytes(self):
-        assert looks_like_gltf(b"\x89PNG\r\n\x1a\n") is False
-
-
-# ---------------------------------------------------------------------------
-# _parse_glb
-# ---------------------------------------------------------------------------
-
-class TestParseGlb:
-    def test_parses_valid_glb(self):
-        gltf_json = _make_gltf_json()
-        glb = _make_glb(gltf_json)
-        result = _parse_glb(glb)
-        assert result["asset"]["version"] == "2.0"
-        assert len(result["meshes"]) == 1
-
-    def test_rejects_too_short(self):
-        with pytest.raises(ValueError, match="too short"):
-            _parse_glb(b"glTF\x00\x00")
-
-    def test_rejects_invalid_magic(self):
-        with pytest.raises(ValueError, match="invalid GLB magic"):
-            _parse_glb(b"NOTglTF\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00")
-
-
-# ---------------------------------------------------------------------------
-# _parse_gltf_json
-# ---------------------------------------------------------------------------
-
-class TestParseGltfJson:
-    def test_parses_valid_gltf(self):
-        gltf_json = _make_gltf_json()
-        result = _parse_gltf_json(json.dumps(gltf_json).encode())
-        assert result["asset"]["version"] == "2.0"
-
-    def test_rejects_non_object(self):
-        with pytest.raises(ValueError, match="root must be an object"):
-            _parse_gltf_json(b"[1, 2, 3]")
-
-
-# ---------------------------------------------------------------------------
-# extract_gltf_metadata  (GLB path)
-# ---------------------------------------------------------------------------
-
-class TestExtractGltfMetadataGlb:
-    def test_basic_glb(self):
-        gltf_json = _make_gltf_json(meshes=1, vertices_per_mesh=24)
-        glb = _make_glb(gltf_json)
-        meta = extract_gltf_metadata(glb)
-        assert meta["mesh_count"] == 1
-        assert meta["vertex_count"] == 24
-        assert meta["has_animation"] is False
-        assert meta["bounding_box_min"] == [-1.0, -1.0, -1.0]
-        assert meta["bounding_box_max"] == [1.0, 1.0, 1.0]
-        assert meta["texture_refs"] == []
-
-    def test_multiple_meshes(self):
-        gltf_json = _make_gltf_json(meshes=3, vertices_per_mesh=12)
-        glb = _make_glb(gltf_json)
-        meta = extract_gltf_metadata(glb)
-        assert meta["mesh_count"] == 3
-        assert meta["vertex_count"] == 36
-
-    def test_with_animation(self):
-        gltf_json = _make_gltf_json(has_animations=True)
-        glb = _make_glb(gltf_json)
-        meta = extract_gltf_metadata(glb)
-        assert meta["has_animation"] is True
-
-    def test_with_external_texture(self):
-        gltf_json = _make_gltf_json(images=[{"uri": "textures/rock.png"}])
-        glb = _make_glb(gltf_json)
-        meta = extract_gltf_metadata(glb)
-        assert meta["texture_refs"] == ["textures/rock.png"]
-
-    def test_with_named_texture(self):
-        gltf_json = _make_gltf_json(images=[{"name": "my_texture"}])
-        glb = _make_glb(gltf_json)
-        meta = extract_gltf_metadata(glb)
-        assert meta["texture_refs"] == ["my_texture"]
-
-    def test_empty_meshes(self):
-        gltf_json = _make_gltf_json(meshes=0)
-        glb = _make_glb(gltf_json)
-        meta = extract_gltf_metadata(glb)
-        assert meta["mesh_count"] == 0
-        assert meta["vertex_count"] == 0
-        assert meta["bounding_box_min"] == [0.0, 0.0, 0.0]
-        assert meta["bounding_box_max"] == [0.0, 0.0, 0.0]
-
-
-# ---------------------------------------------------------------------------
-# extract_gltf_metadata  (plain .gltf JSON path)
-# ---------------------------------------------------------------------------
-
-class TestExtractGltfMetadataGltfJson:
-    def test_plain_gltf(self):
-        gltf_json = _make_gltf_json(meshes=2, vertices_per_mesh=8)
-        raw = json.dumps(gltf_json).encode()
-        meta = extract_gltf_metadata(raw)
-        assert meta["mesh_count"] == 2
-        assert meta["vertex_count"] == 16
-        assert meta["has_animation"] is False
-
-    def test_plain_gltf_with_animation(self):
-        gltf_json = _make_gltf_json(has_animations=True)
-        raw = json.dumps(gltf_json).encode()
-        meta = extract_gltf_metadata(raw)
-        assert meta["has_animation"] is True
-
-
-# ---------------------------------------------------------------------------
-# Error handling
-# ---------------------------------------------------------------------------
-
-class TestExtractGltfMetadataErrors:
-    def test_invalid_glb(self):
-        with pytest.raises(ValueError):
-            extract_gltf_metadata(b"not a glb")
-
-    def test_invalid_gltf_json(self):
-        with pytest.raises(ValueError):
-            _parse_gltf_json(b"[1, 2, 3]")

docs/planning/client-server-wiring.md

@@ -23,9 +23,10 @@ explicitly out of scope.
 | # | Type | Task | Depends on |
 |---|------|------|-----------|
 | 1 | architecture | `ApiClient` autoload: HTTP + JWT storage + error contract | — |
-| 2 | implementation | Main-menu **login + register** UI built & wired (form-encoded + JSON/age gate) | 1 |
-| 3 | implementation | **World list** screen consuming `GET /api/worlds` | 1 |
-| 4 | testing | End-to-end headless smoke test + manual verify | 1,2,3 |
+| 2 | implementation | Main-menu **login** wiring (form-encoded) | 1 |
+| 3 | implementation | Main-menu **register** wiring (JSON + age gate) | 2 |
+| 4 | implementation | **World list** screen consuming `GET /api/worlds` | 2 |
+| 5 | testing | End-to-end headless smoke test + manual verify | 1,3,4 |
 
 ## Design decisions captured (resolved in task 1)
 - Token storage: in-memory singleton property for the MVP; a `save_to_disk` seam is left
@@ -34,8 +35,3 @@ explicitly out of scope.
   never crash on network failure; non-2xx surfaces `{status, detail}` from the backend.
 - Base URL: read from a ProjectSetting, defaulting to `http://127.0.0.1:8000`.
 - Login is form-encoded; register is JSON — the client helper must support both content types.
-
-## Notes
-- The main-menu auth UI does **not** exist yet (main_menu.gd currently has only Play/Quit
-  stubs). Task 2 must **build** the login/register UI, not merely wire an existing one.
-- The world-list screen also needs to be **built** (a new scene), not just wired.

docs/planning/creator_studio.md

@@ -0,0 +1,182 @@
+# Creator Studio — Extended Authoring Tools
+
+> **Feature:** Creator Studio — Extended Authoring Tools
+> **Status:** Planning
+> **Owner:** Platform team
+
+## Feature Overview
+
+Extends the in-game world editor (M6) toward a real authoring tool with:
+1. **Asset import pipeline** (glTF models/textures)
+2. **Script editor** with sandboxed API surface exposed clearly
+3. **Experience publishing flow** (draft → review → live)
+4. **Basic analytics** for creators (plays, session length)
+
+## User Stories
+
+### US-1: Asset Import Pipeline
+_As a creator, I can import glTF models and textures into my experience so that I can use custom 3D assets._
+
+### US-2: Script Editor with Sandboxed API
+_As a creator, I can write and test scripts in the editor with autocomplete/docs for the available API surface._
+
+### US-3: Experience Publishing Flow
+_As a creator, I can publish my experience through a draft → review → live pipeline so that players can discover and play it._
+
+### US-4: Creator Analytics
+_As a creator, I can see how many plays and average session length my experiences receive so that I can understand player engagement._
+
+---
+
+## Task Breakdown
+
+### US-1: Asset Import Pipeline
+
+#### T1.1: Backend — glTF Asset Upload with Metadata Extraction
+- **Type:** implementation
+- **Files:** `backend/app/routers/assets.py` (extend upload endpoint), `backend/app/models/asset.py` (add glTF-specific metadata fields)
+- **Scope:** Extend the existing `upload_asset_file` endpoint in `assets.py` to detect `.glb`/`.gltf` files and extract glTF metadata (mesh_count, vertex_count, has_animation, texture_refs, bounding_box) from the embedded JSON. Store extracted metadata in `metadata_json`. Add a `has_gltf_metadata` computed property. The Asset model already has `asset_type = MODEL_3D` and `metadata_json` — this task adds the extraction logic.
+- **Acceptance:** POST `/api/assets/{id}/upload` with a `.glb` file returns asset with `metadata_json` containing `mesh_count`, `vertex_count`, `has_animation`, `texture_refs`. GET lists include these fields. File stored on disk. Non-glTF files are unaffected.
+- **Dependencies:** None (builds on existing asset infrastructure)
+
+#### T1.2: Backend — Public Asset Catalog Endpoint
+- **Type:** implementation
+- **Files:** `backend/app/routers/assets.py` (new endpoint)
+- **Scope:** Add `GET /api/assets/catalog` endpoint that returns all public glTF assets with their metadata (name, thumbnail_url, mesh_count, vertex_count, tags). Add filtering by tags and pagination. This is what the editor's asset palette queries. Uses the existing `Asset.is_public` field.
+- **Acceptance:** Catalog endpoint returns paginated list of public assets; filtering by tag works; pagination params respected; returns 401 without auth.
+- **Dependencies:** T1.1
+
+#### T1.3: Godot — glTF Import Utility (Editor-Side)
+- **Type:** implementation
+- **Files:** `scripts/gltf_importer.gd` (new), `scripts/asset_catalog.gd` (new)
+- **Scope:** Godot-side utility that connects to the catalog API, downloads glTF files, and converts them to Godot-compatible resources (`.res` files with embedded mesh data). Provides `import_gltf(url: String) -> Resource` function. Handles texture extraction and mesh merging. Uses the ApiClient autoload (from client-server-wiring plan) for HTTP.
+- **Acceptance:** `import_gltf()` downloads a glTF from the catalog, converts mesh to `Mesh` resource, returns a ready-to-use Godot resource. Texture files stored in `user://assets/`.
+- **Dependencies:** T1.2, client-server-wiring ApiClient (task 1 from that plan)
+
+### US-2: Script Editor with Sandboxed API
+
+> **Design note from `scripting_sandbox.md`:** Godot 4 has no built-in GDScript sandbox. The recommended approach is a **data-driven DSL** (JSON/Resource) interpreted by trusted GDScript, not arbitrary code execution. This task follows that recommendation.
+
+#### T2.1: Backend — Script Model & CRUD Endpoints
+- **Type:** architecture
+- **Files:** `backend/app/models/script.py` (new), `backend/app/routers/scripts.py` (new), `backend/app/main.py` (register router), `backend/app/models/__init__.py` (export)
+- **Scope:** Create `Script` model (id, name, world_id, owner_id, source_code TEXT, version INT, script_type ENUM[gdscript, dsl], dsl_payload JSON, created_at, updated_at). Add full CRUD endpoints: `POST /api/scripts/` (create), `GET /api/scripts/` (list), `GET /api/scripts/{id}` (get), `PUT /api/scripts/{id}` (update), `DELETE /api/scripts/{id}` (delete). Scripts are owned by users and associated with a world. `dsl_payload` stores the JSON/Resource data for the DSL approach; `source_code` stores raw GDScript if used.
+- **Acceptance:** All CRUD endpoints work; scripts are owned by creator; list endpoint filters by owner/world; update increments version; DSL and gdscript types supported.
+- **Dependencies:** None (new model + router)
+
+#### T2.2: Godot — Script API Surface Definition
+- **Type:** architecture
+- **Files:** `scripts/editor_script_api.gd` (new)
+- **Scope:** Define the public API surface available to creator scripts. This is a `RefCounted` class that wraps the Godot engine's capabilities into a safe, documented interface. Includes: `WorldAPI` (get_tile, get_object, set_property), `PlayerAPI` (get_position, get_health), `AudioAPI` (play_sound, play_music), `NetworkAPI` (send_event, broadcast). Each method has documented parameters and return types. Self-documenting via `##` doc comments for autocomplete.
+- **Acceptance:** `EditorScriptAPI` class exposes all documented methods; methods are callable from user scripts; API surface is self-documenting.
+- **Dependencies:** None (standalone definition)
+
+#### T2.3: Godot — In-Game Script Editor UI
+- **Type:** implementation
+- **Files:** `scenes/editor_script_editor.tscn` (new), `scripts/editor_script_editor.gd` (new)
+- **Scope:** A `Control`-based UI panel that provides a script editor within the game. Features: code editor with syntax highlighting (basic), autocomplete dropdown, run button (calls backend `/run` endpoint), output console (shows stdout/stderr), API reference panel (shows available methods). Integrates with the existing editor toolbar.
+- **Acceptance:** Editor panel opens from toolbar; code editor accepts input; autocomplete shows API methods; run button executes script and shows output; API reference panel is browsable.
+- **Dependencies:** T2.1, T2.2
+
+### US-3: Experience Publishing Flow
+
+#### T3.1: Backend — Experience Model & Status Transitions
+- **Type:** architecture
+- **Files:** `backend/app/models/experience.py` (new), `backend/app/routers/experiences.py` (new), `backend/app/main.py` (register router), `backend/app/models/__init__.py` (export)
+- **Scope:** Create `Experience` model (id, world_id FK→worlds, title, description, status ENUM[DRAFT,SUBMITTED,IN_REVIEW,APPROVED,REJECTED,LIVE], published_at, review_notes, reviewer_id FK→users). Status transitions enforced: DRAFT→SUBMITTED→IN_REVIEW→APPROVED→LIVE; REJECTED→DRAFT (resubmit). Add endpoints: `POST /api/experiences/` (create draft), `POST /api/experiences/{id}/submit` (submit for review), `POST /api/experiences/{id}/approve` (approve), `POST /api/experiences/{id}/reject` (reject), `GET /api/experiences/` (list with status filter). An experience is a **publishing wrapper** around a World — the world's visibility is set to PUBLIC when experience goes LIVE.
+- **Acceptance:** All CRUD + transition endpoints work; status transitions enforced; rejected can be resubmitted; list filters by status; approve sets world visibility to PUBLIC; only world owner can submit; only moderators can approve/reject.
+- **Dependencies:** None (new model + router)
+
+#### T3.2: Backend — Review Queue & Moderation Integration
+- **Type:** implementation
+- **Files:** `backend/app/routers/experiences.py` (add endpoints)
+- **Scope:** Add review queue endpoint `GET /api/experiences/review-queue` (returns experiences in IN_REVIEW status). Add `POST /api/experiences/{id}/review` endpoint for moderators to add review notes and change status. Integrates with content moderation: when an experience is submitted, its world's content flags are computed and attached to the review.
+- **Acceptance:** Review queue returns IN_REVIEW experiences; review endpoint accepts notes and status change; content flags attached on submit; only moderators can review.
+- **Dependencies:** T3.1
+
+#### T3.3: Godot — Publishing UI Panel
+- **Type:** implementation
+- **Files:** `scenes/editor_publish_panel.tscn` (new), `scripts/editor_publish_panel.gd` (new)
+- **Scope:** A `Control`-based panel in the editor that lets creators manage their experience's publishing state. Features: title/description editor, status badge (DRAFT/SUBMITTED/LIVE), submit button, review notes display, publish history timeline. Integrates with the existing editor toolbar.
+- **Acceptance:** Panel shows current status; submit button calls backend; review notes displayed; publish history shown; status badge updates on refresh.
+- **Dependencies:** T3.1, T3.2
+
+#### T3.4: Godot — Experience List & Discovery
+- **Type:** implementation
+- **Files:** `scenes/experience_list.tscn` (new), `scripts/experience_list.gd` (new)
+- **Scope:** A UI panel that lists all experiences available to the player (LIVE status). Features: search/filter, experience cards (title, description, creator, play count), join button. Queries `GET /api/experiences/?status=LIVE` and displays results.
+- **Acceptance:** Lists LIVE experiences; search filters by title/description; cards show metadata; join button loads the experience's world.
+- **Dependencies:** T3.1
+
+### US-4: Creator Analytics
+
+#### T4.1: Backend — Session & Play Tracking Models
+- **Type:** architecture
+- **Files:** `backend/app/models/analytics.py` (new), `backend/app/routers/analytics.py` (new), `backend/app/main.py` (register router), `backend/app/models/__init__.py` (export)
+- **Scope:** Create `PlaySession` model (id, experience_id FK→experiences, player_id FK→users, started_at, ended_at, duration_seconds, chunk_loads INT, interactions_count INT). Create `PlayEvent` model (id, experience_id FK→experiences, player_id FK→users, event_type, payload JSON, created_at). Add endpoints: `POST /api/analytics/session/start` (start session), `POST /api/analytics/session/end` (end session), `POST /api/analytics/event` (log event). Note: `sessions` table is taken by auth tokens; this uses `play_sessions` table name.
+- **Acceptance:** Session start/end endpoints work; events logged; duration calculated correctly; endpoints accept valid experience/player IDs.
+- **Dependencies:** None (new models + routers)
+
+#### T4.2: Backend — Creator Dashboard Analytics Endpoint
+- **Type:** implementation
+- **Files:** `backend/app/routers/analytics.py` (add endpoint)
+- **Scope:** Add `GET /api/analytics/experience/{id}` endpoint that returns aggregated analytics for an experience: total_plays, unique_players, avg_session_length, total_play_time, plays_over_time (daily breakdown), top_chunks_loaded, top_interactions. Data is aggregated from PlaySession and PlayEvent tables.
+- **Acceptance:** Returns all aggregated metrics; daily breakdown covers last 30 days; only owner or moderator can view; empty experience returns zeros.
+- **Dependencies:** T4.1
+
+#### T4.3: Godot — Analytics Tracking in Game
+- **Type:** implementation
+- **Files:** `scripts/analytics_tracker.gd` (new)
+- **Scope:** A singleton-like service that tracks player sessions and events during gameplay. Automatically starts session on world load, tracks chunk loads, interactions, and time spent. Sends periodic heartbeat events to backend. Handles session end on world unload or disconnect.
+- **Acceptance:** Session starts on world load; events logged during play; heartbeat sends every 60s; session ends on world unload; handles disconnect gracefully.
+- **Dependencies:** T4.1
+
+#### T4.4: Godot — Creator Analytics Dashboard UI
+- **Type:** implementation
+- **Files:** `scenes/creator_analytics_panel.tscn` (new), `scripts/creator_analytics_panel.gd` (new)
+- **Scope:** A `Control`-based panel in the editor that displays analytics for the current experience. Features: total plays counter, avg session length, plays over time chart (simple bar chart), top chunks, top interactions. Queries `GET /api/analytics/experience/{id}` and renders data.
+- **Acceptance:** Panel shows all metrics; chart renders bar chart of daily plays; data refreshes on button press; handles empty data gracefully.
+- **Dependencies:** T4.2, T4.3
+
+---
+
+## Database Migration Plan
+
+New tables needed (in order):
+1. `scripts` — script storage
+2. `experiences` — publishing state (wraps worlds)
+3. `play_sessions` — session tracking (note: `sessions` table already exists for auth tokens)
+4. `play_events` — granular events
+
+Migration file: `backend/alembic/versions/0003_creator_studio.py`
+
+---
+
+## Task Dependencies Summary
+
+```
+T1.1 (glTF upload) ──→ T1.2 (catalog API) ──→ T1.3 (Godot importer)
+T2.1 (script model) ──→ T2.3 (editor UI)
+T2.2 (API surface) ──→ T2.3 (editor UI)
+T3.1 (experience model) ──→ T3.2 (review queue) ──→ T3.3 (publish UI)
+T3.1 ──→ T3.4 (discovery list)
+T4.1 (tracking model) ──→ T4.2 (dashboard endpoint) ──→ T4.4 (analytics UI)
+T4.1 ──→ T4.3 (game tracker) ──→ T4.4 (analytics UI)
+```
+
+## Implementation Order Recommendation
+
+1. **T1.1** — Foundation: asset upload with glTF metadata extraction
+2. **T2.1** — Foundation: script model + CRUD
+3. **T3.1** — Foundation: experience model + status transitions
+4. **T4.1** — Foundation: analytics tracking model
+5. **T1.2** — Asset catalog for editor
+6. **T2.2** — Script API surface definition
+7. **T3.2** — Review queue integration
+8. **T4.2** — Analytics dashboard endpoint
+9. **T1.3** — Godot glTF importer (depends on ApiClient from client-server-wiring)
+10. **T2.3** — Script editor UI
+11. **T3.3** — Publishing UI panel
+12. **T3.4** — Experience discovery list
+13. **T4.3** — Analytics tracker in game
+14. **T4.4** — Analytics dashboard UI

docs/testing/README.md

@@ -1,50 +0,0 @@
-# Testing at Package Checkpoints
-
-A Package Checkpoint (PC1, PC2, ...) is a periodic review point — every few
-real milestones, the client and server builds get packaged together and
-independently reviewed before anyone calls anything actually done. See
-`project_agp` in Claude's memory, or ask, for the full definition; this
-doc is just the mechanical "how do I run the tests" part of that review.
-
-## Running the suite
-
-```
-python scripts/run_checkpoint_tests.py
-```
-
-Brings up a throwaway Postgres, runs Alembic migrations against it, runs the
-backend pytest suite, starts the backend server, and runs every Godot
-headless smoke test (`scripts/smoke_test_*.gd`) against it. Tears the
-Postgres container down afterward (`--keep-postgres` to skip that if you
-want to poke at the DB after a failure).
-
-If port 5432 is already taken on the machine, pass `--postgres-port` with
-something else.
-
-Exit code is 0 only if everything that actually ran passed — suites with
-nothing to run yet (no Godot binary found, no smoke test scripts yet) are
-reported SKIPPED, not treated as a failure.
-
-## What this does and doesn't prove
-
-Passing this script means: migrations apply cleanly to a genuinely empty
-database, the backend's unit-level logic is correct, and whatever Godot
-smoke tests exist actually round-trip against a live backend. It does
-**not** mean full endpoint/integration coverage exists — see
-`test_inventory.md` for the current, honest list of what's tested and what
-isn't. A checkpoint review should still involve reading the actual diffs
-for anything this script's current coverage doesn't reach, not just running
-green and calling it done.
-
-## Growing this over time
-
-As real integration tests get added (endpoint tests hitting the FastAPI app,
-more Godot smoke coverage beyond `health_check`), they should land under
-`backend/tests/` / `scripts/smoke_test_*.gd` respectively — this script
-picks up new files automatically, nothing to register by hand. Update
-`test_inventory.md`'s tables when you do, so the inventory stays a source
-of truth instead of quietly going stale.
-
-Eventual goal (not implemented yet): gate merges to `main` on this script
-passing, the same way a real CI pipeline would. For now it's a manual step
-run at checkpoint review time.

docs/testing/test_inventory.md

@@ -1,78 +0,0 @@
-# Test Inventory
-
-What automated coverage actually exists, what it actually verifies, and what
-doesn't have coverage yet. Keep this current as tests are added — it's the
-thing a Package Checkpoint review (see `docs/testing/README.md`) reads first
-to know what "run the tests" actually checked.
-
-Run everything below in one shot with `scripts/run_checkpoint_tests.py`.
-
-Last verified against `main`: 2026-08-19 (commit `1c75367`).
-
-## Backend — `backend/tests/` (pytest)
-
-Run: `cd backend && python -m pytest -v` (needs `DATABASE_URL` pointed at a
-reachable Postgres — see the runner script; most of these tests don't
-actually touch the DB, but the app's import chain requires a valid URL to
-construct).
-
-**Current total: 38 tests, all passing on a clean `main` checkout.**
-
-| File | Tests | What it covers |
-|---|---|---|
-| `test_auth_age_gate.py` | 10 | `calculate_age()` date-math correctness (exact boundary, leap years, birthday-not-yet-this-year) + `RegisterRequest` date-of-birth validation (parametrized valid/invalid date rejection). Backs the 18+ registration gate (PR #23). |
-| `test_gltf_metadata.py` | 21 | glTF/GLB binary + JSON parsing: magic-byte detection, chunk-padding handling, mesh/animation/texture-reference metadata extraction, malformed-input rejection. Backs the asset-import pipeline (PR #27). |
-
-**What these are, honestly:** pure unit tests of standalone functions
-(`calculate_age`, the glTF parser, Pydantic validators). None of them spin
-up the FastAPI app or hit a real endpoint — they run in ~1s and don't
-actually need Postgres reachable at all (the import chain just needs a
-syntactically valid `DATABASE_URL`, nothing connects during collection).
-
-**Known coverage gaps** (real gaps, not placeholders — nothing enforces filling
-these yet):
-- No integration/endpoint tests at all — `/register`, `/login`, `/refresh`,
-  `/worlds`, `/assets/*` have zero tests that actually call them through
-  the FastAPI app (e.g. via `httpx.AsyncClient` + `ASGITransport`) against a
-  real (or test) database. Everything currently shipped works because it
-  was manually verified at merge time (checkpoint review), not because a
-  test asserts it.
-- No tests for the RS256 auth upgrade (key generation, refresh-token
-  issuance/persistence) — PR #30, pending review as of this writing,
-  manually verified (correct key usage, all 38 existing tests still pass)
-  but not covered by an automated test of its own yet.
-- No tests for the moderation schema/migration (in progress as of this
-  writing) beyond "the migration runs."
-
-## Godot client — `scripts/smoke_test_*.gd`
-
-**Nothing merged into `main` yet as of this writing** — `sandbox_probe/test_script.gd`
-is the only Godot script on `main` right now, and it's **not a real
-test** (a leftover manual probe, returns a hardcoded string, asserts
-nothing). Don't count it toward coverage; delete or repurpose it if anyone
-actually needs a sandbox probe again.
-
-`scripts/smoke_test_api.gd` (PC1, PR #29, pending review as of this writing)
-will be the first real one once merged — `ApiClient` autoload's
-`health_check()` against a **live backend** (set `AGP_API_BASE_URL` to point
-at one), verified by hand end-to-end before opening the PR: exercises the
-real HTTP request path (`HTTPRequest` node lifecycle, JSON parse, the
-result-dictionary contract), not just that the script compiles. Exits 1 on
-failure, so it's CI/script-friendly.
-
-Run (once merged): `godot --headless --path . --import` once (builds the
-class cache — skip this and every `class_name`-declared class falsely
-errors as undeclared), then for each `scripts/smoke_test_*.gd`:
-`godot --headless --path . --script res://scripts/<name>.gd`
-
-**Known gap once it lands:** only `health_check()` is exercised end-to-end.
-`login`, `register`, `get_worlds`, `get_me` are implemented (see
-`scripts/api_client.gd`) but have no smoke coverage yet — each would need a
-real user/world fixture in the target backend to test against meaningfully.
-
-## What "full coverage" should eventually mean here
-
-Not defined precisely yet — the honest target as of 2026-08-19 is just
-"more than pure-function unit tests." As real integration/endpoint tests get
-added, update the tables above rather than letting this doc drift stale;
-a wrong inventory is worse than no inventory.

export_presets.cfg

@@ -1,74 +0,0 @@
-[preset.0]
-
-name="Linux"
-platform="Linux/X11"
-runnable=true
-advanced_options=false
-dedicated_server=false
-custom_features=""
-export_filter="all_resources"
-include_filter=""
-exclude_filter=""
-export_path="export/linux/agp-game.x86_64"
-encryption_include_filters=""
-encryption_exclude_filters=""
-encrypt_pck=false
-encrypt_directory=false
-script_export_mode=2
-
-[preset.0.options]
-
-custom_template/debug=""
-custom_template/release=""
-debug/export_console_wrapper=1
-binary_format/embed_pck=false
-texture_format/bptc=true
-texture_format/s3tc=true
-texture_format/etc=false
-texture_format/etc2=false
-binary_format/architecture="x86_64"
-ssh_remote_deploy/enabled=false
-
-[preset.1]
-
-name="Windows Desktop"
-platform="Windows Desktop"
-runnable=true
-advanced_options=false
-dedicated_server=false
-custom_features=""
-export_filter="all_resources"
-include_filter=""
-exclude_filter=""
-export_path="export/windows/agp-game.exe"
-encryption_include_filters=""
-encryption_exclude_filters=""
-encrypt_pck=false
-encrypt_directory=false
-script_export_mode=2
-
-[preset.1.options]
-
-custom_template/debug=""
-custom_template/release=""
-debug/export_console_wrapper=1
-binary_format/embed_pck=false
-texture_format/bptc=true
-texture_format/s3tc=true
-texture_format/etc=false
-texture_format/etc2=false
-binary_format/architecture="x86_64"
-codesign/enable=false
-application/icon=""
-application/console_wrapper_icon=""
-application/icon_interpolation=4
-application/file_version=""
-application/product_version=""
-application/company_name=""
-application/product_name=""
-application/file_description=""
-application/copyright=""
-application/trademarks=""
-application/export_angle=0
-application/export_d3d12=0
-d3d12/agility_sdk_multizip=0

project.godot

@@ -9,12 +9,9 @@ config_version=5
 config/name="AGP-Game"
 run/main_scene="res://scenes/main_menu.tscn"
 config/features=PackedStringArray("4.6.2")
-agp/api_base_url="http://127.0.0.1:8000"
 
 [autoload]
 
-ApiClient="*res://scripts/api_client.gd"
-
 [display]
 
 window/size/viewport_width=1920

scripts/api_client.gd

@@ -1,292 +0,0 @@
-extends Node
-## Central HTTP client singleton (autoload name: "ApiClient").
-##
-## Every network call in the game flows through this class. Callers use the
-## high-level helpers ([method login], [method register], [method get_worlds],
-## [method health_check], [method get_me]) or the generic [method request]
-## primitive. All results conform to the result-dictionary contract below.
-##
-## [b]Result Dictionary Contract[/b]
-## Every public method returns (after `await`) a Dictionary with this shape:
-##
-##     {
-##         "ok":     bool,     # true for HTTP 2xx, false otherwise
-##         "status": int,      # HTTP status code (0 on network failure)
-##         "data":   Variant,  # parsed JSON body on success (null otherwise)
-##         "detail": String,   # human-readable message
-##     }
-##
-## Network failures (timeout / DNS / refused connection) return `status == 0`
-## with a `detail` describing the transport failure. Non-2xx responses return
-## the real HTTP status and the backend's `detail` field from the JSON error
-## body when present. No caller can crash on a failed request.
-##
-## [b]Token storage[/b]
-## JWTs are kept in memory. [method set_token] is the single seam for future
-## disk persistence (override it to save to `user://`).
-##
-## [b]Usage[/b]
-##     var result: Dictionary = await ApiClient.login("alice", "secret")
-##     if result.ok:
-##         print("Logged in!")
-##     else:
-##         print("Error: ", result.detail)
-
-# ---------------------------------------------------------------------------
-# Token storage
-# ---------------------------------------------------------------------------
-
-var _access_token: String = ""
-var _token_type: String = "Bearer"
-
-## Full Authorization header value, e.g. "Bearer eyJ...". Empty if no token.
-var bearer_token: String:
-	get:
-		return _token_type + " " + _access_token if _access_token != "" else ""
-
-
-## Whether an access token is currently stored.
-func has_token() -> bool:
-	return _access_token != ""
-
-
-## Set the access token (called after login / register / token refresh).
-## This is the persistence seam: override to also write to disk.
-func set_token(access_token: String, token_type: String = "Bearer") -> void:
-	_access_token = access_token
-	_token_type = token_type
-
-
-## Clear stored tokens.
-func clear_token() -> void:
-	_access_token = ""
-	_token_type = "Bearer"
-
-
-# ---------------------------------------------------------------------------
-# Configuration
-# ---------------------------------------------------------------------------
-
-var _base_url: String = "http://127.0.0.1:8000"
-
-## Request timeout in seconds. 0 disables the timeout.
-var timeout_seconds: float = 10.0
-
-
-func _ready() -> void:
-	# Environment variable override (e.g. for headless smoke tests against a
-	# backend on a non-default port). Falls back to the ProjectSetting, then
-	# to the documented default.
-	var env_url := OS.get_environment("AGP_API_BASE_URL")
-	if env_url != "":
-		_base_url = env_url.rstrip("/")
-	else:
-		_base_url = str(ProjectSettings.get_setting(
-			"application/agp/api_base_url",
-			"http://127.0.0.1:8000"
-		)).rstrip("/")
-
-
-# ---------------------------------------------------------------------------
-# Core request primitive
-# ---------------------------------------------------------------------------
-
-## Generic request primitive. Awaitable via `await`.
-##
-## Uses a dedicated HTTPRequest node per call so concurrent requests can never
-## cross-talk, and so the result maps 1:1 to the awaiting caller.
-##
-## @param method       HTTPClient.Method enum value (GET/POST/PUT/PATCH/DELETE).
-## @param path         URL path, e.g. "/api/health".
-## @param body         Request body string (JSON or form-encoded).
-## @param content_type "application/json" or "application/x-www-form-urlencoded".
-## @param require_auth If true, attach the stored bearer token when present.
-## @return Result dictionary conforming to the contract.
-func request(
-	method: HTTPClient.Method,
-	path: String,
-	body: String = "",
-	content_type: String = "application/json",
-	require_auth: bool = false
-) -> Dictionary:
-	var http := HTTPRequest.new()
-	http.timeout = timeout_seconds
-	http.max_redirects = 8
-	http.accept_gzip = true
-	add_child(http)
-
-	var headers := PackedStringArray()
-	headers.append("Accept: application/json")
-	if content_type != "":
-		headers.append("Content-Type: " + content_type)
-	if require_auth and has_token():
-		headers.append("Authorization: " + bearer_token)
-
-	var url := _base_url + path
-	var err := http.request(url, headers, method, body)
-	if err != OK:
-		http.queue_free()
-		return _make_result(false, 0, null, "Failed to start request: " + _error_string(err))
-
-	# request_completed emits (result, response_code, headers, body).
-	var args: Array = await http.request_completed
-	var result_code: int = args[0]
-	var response_code: int = args[1]
-	var response_body: PackedByteArray = args[3]
-	http.queue_free()
-
-	# Transport-level failure (timeout / DNS / refused / TLS, etc.).
-	if result_code != HTTPRequest.RESULT_SUCCESS:
-		return _make_result(false, 0, null, _transport_error_detail(result_code))
-
-	# Server accepted the connection but returned no HTTP status line.
-	if response_code == 0:
-		return _make_result(false, 0, null, "No response received from server.")
-
-	var json_string := response_body.get_string_from_utf8()
-	var ok := response_code >= 200 and response_code < 300
-
-	if ok:
-		var data: Variant = _parse_json(json_string)
-		return _make_result(true, response_code, data, "OK")
-
-	# Non-2xx: surface the backend's "detail" message when available.
-	var detail := "HTTP error %d" % response_code
-	var parsed: Variant = _parse_json(json_string)
-	if parsed is Dictionary and (parsed as Dictionary).has("detail"):
-		detail = str((parsed as Dictionary)["detail"])
-	return _make_result(false, response_code, null, detail)
-
-
-# ---------------------------------------------------------------------------
-# High-level helpers
-# ---------------------------------------------------------------------------
-
-## Log in with username/password (OAuth2PasswordRequestForm).
-## On success stores the returned access token.
-func login(username: String, password: String) -> Dictionary:
-	var form := "username=" + username.uri_encode() + "&password=" + password.uri_encode()
-	var result := await request(
-		HTTPClient.METHOD_POST,
-		"/api/auth/login",
-		form,
-		"application/x-www-form-urlencoded",
-		false
-	)
-	_store_token_from_result(result)
-	return result
-
-
-## Register a new user. On success stores the returned access token.
-## @param date_of_birth ISO date string "YYYY-MM-DD".
-func register(
-	username: String,
-	email: String,
-	password: String,
-	date_of_birth: String
-) -> Dictionary:
-	var payload := {
-		"username": username,
-		"email": email,
-		"password": password,
-		"date_of_birth": date_of_birth,
-	}
-	var result := await request(
-		HTTPClient.METHOD_POST,
-		"/api/auth/register",
-		JSON.stringify(payload),
-		"application/json",
-		false
-	)
-	_store_token_from_result(result)
-	return result
-
-
-## List worlds visible to the current user (requires auth).
-## @param visibility Optional filter: "public", "private", "friends_only".
-func get_worlds(skip: int = 0, limit: int = 50, visibility: String = "") -> Dictionary:
-	var path := "/api/worlds/?skip=%d&limit=%d" % [skip, limit]
-	if visibility != "":
-		path += "&visibility=" + visibility.uri_encode()
-	return await request(HTTPClient.METHOD_GET, path, "", "application/json", true)
-
-
-## Ping the backend health endpoint (no auth).
-func health_check() -> Dictionary:
-	return await request(HTTPClient.METHOD_GET, "/api/health", "", "application/json", false)
-
-
-## Fetch the current user's profile from the stored JWT (requires auth).
-func get_me() -> Dictionary:
-	return await request(HTTPClient.METHOD_GET, "/api/users/me", "", "application/json", true)
-
-
-# ---------------------------------------------------------------------------
-# Internals
-# ---------------------------------------------------------------------------
-
-func _store_token_from_result(result: Dictionary) -> void:
-	if result.ok and result.data is Dictionary:
-		var token: String = str((result.data as Dictionary).get("access_token", ""))
-		if token != "":
-			set_token(token)
-
-
-func _parse_json(text: String) -> Variant:
-	if text == "":
-		return null
-	var parsed: Variant = JSON.parse_string(text)
-	if parsed == null:
-		# null is ambiguous (valid JSON "null" vs parse failure). Fall back to
-		# the raw string so callers never lose the body entirely.
-		return text if text != "null" else null
-	return parsed
-
-
-func _make_result(ok: bool, status: int, data: Variant, detail: String) -> Dictionary:
-	return {
-		"ok": ok,
-		"status": status,
-		"data": data,
-		"detail": detail,
-	}
-
-
-func _transport_error_detail(result_code: int) -> String:
-	match result_code:
-		HTTPRequest.RESULT_CANT_CONNECT:
-			return "Could not connect to server. Is it running?"
-		HTTPRequest.RESULT_CANT_RESOLVE:
-			return "Could not resolve server hostname."
-		HTTPRequest.RESULT_CONNECTION_ERROR:
-			return "Connection error."
-		HTTPRequest.RESULT_TLS_HANDSHAKE_ERROR:
-			return "TLS handshake failed."
-		HTTPRequest.RESULT_NO_RESPONSE:
-			return "No response from server."
-		HTTPRequest.RESULT_BODY_SIZE_LIMIT_EXCEEDED:
-			return "Response body too large."
-		HTTPRequest.RESULT_BODY_DECOMPRESS_FAILED:
-			return "Failed to decompress response body."
-		HTTPRequest.RESULT_REQUEST_FAILED:
-			return "Request failed."
-		HTTPRequest.RESULT_TIMEOUT:
-			return "Request timed out."
-		_:
-			return "Network error (code %d)." % result_code
-
-
-func _error_string(err_code: int) -> String:
-	match err_code:
-		OK:
-			return "OK"
-		ERR_UNCONFIGURED:
-			return "HTTPRequest not configured (not in tree)."
-		ERR_BUSY:
-			return "HTTPRequest is busy with a previous request."
-		ERR_INVALID_PARAMETER:
-			return "Invalid URL format."
-		ERR_CANT_CONNECT:
-			return "Cannot connect to host."
-		_:
-			return "Unknown error (%d)." % err_code

scripts/api_client.gd.uid

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

scripts/build.sh

@@ -1,42 +0,0 @@
-#!/usr/bin/env bash
-# Headless CI export for Linux and Windows.
-#
-# Requires:
-#   - Godot 4.6.2 (the exact version this project + export_presets.cfg were
-#     built against; a different Godot minor version's export templates are
-#     not guaranteed compatible)
-#   - The matching export templates installed at
-#     ~/.local/share/godot/export_templates/4.6.2.stable/
-#     (download: https://godotengine.org/download/archive/4.6.2-stable/,
-#     "Export templates" -- NOT the same as the editor download)
-#   - godot on PATH (or set GODOT_BIN below)
-#
-# Usage: scripts/build.sh
-# Output: export/linux/agp-game.x86_64, export/windows/agp-game.exe
-
-set -euo pipefail
-cd "$(dirname "$0")/.."
-
-GODOT_BIN="${GODOT_BIN:-godot}"
-if ! command -v "$GODOT_BIN" >/dev/null 2>&1; then
-    if [ -x "$HOME/godot/godot" ]; then
-        GODOT_BIN="$HOME/godot/godot"
-    else
-        echo "godot binary not found (checked PATH and ~/godot/godot)." >&2
-        exit 1
-    fi
-fi
-
-echo "Godot version: $("$GODOT_BIN" --version)"
-
-mkdir -p export/linux export/windows
-
-echo "=== Exporting Linux/X11 ==="
-"$GODOT_BIN" --headless --path . --export-release "Linux" export/linux/agp-game.x86_64
-
-echo "=== Exporting Windows Desktop ==="
-"$GODOT_BIN" --headless --path . --export-release "Windows Desktop" export/windows/agp-game.exe
-
-echo ""
-echo "Build artifacts:"
-ls -la export/linux export/windows

scripts/main_menu.gd.uid

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

scripts/run_checkpoint_tests.py

@@ -1,170 +0,0 @@
-#!/usr/bin/env python3
-"""Run the full automated test inventory for a Package Checkpoint review.
-
-See docs/testing/test_inventory.md for what each suite actually covers (and
-doesn't) -- keep that doc in sync as tests are added, this script just runs
-whatever's there.
-
-Usage:
-    python scripts/run_checkpoint_tests.py [--keep-postgres] [--postgres-port PORT]
-
-Exits 0 if everything that ran passed, 1 otherwise. Suites with nothing to
-run (e.g. no scripts/smoke_test_*.gd yet, or no Godot binary found) are
-reported as SKIPPED, not counted as a failure.
-"""
-import argparse
-import glob
-import os
-import shutil
-import subprocess
-import sys
-import time
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent
-BACKEND = ROOT / "backend"
-
-
-def run(cmd, cwd=None, env=None, capture=False):
-    print(f"$ {' '.join(cmd)}" + (f"  (cwd={cwd})" if cwd else ""))
-    return subprocess.run(cmd, cwd=cwd, env=env, capture_output=capture, text=True)
-
-
-def find_godot():
-    for candidate in ("godot", str(Path.home() / "godot" / "godot")):
-        if shutil.which(candidate) or Path(candidate).is_file():
-            return candidate
-    return None
-
-
-def wait_for_http(url: str, timeout_s: int = 20) -> bool:
-    import urllib.request
-    import urllib.error
-
-    deadline = time.time() + timeout_s
-    while time.time() < deadline:
-        try:
-            with urllib.request.urlopen(url, timeout=2) as resp:
-                if resp.status == 200:
-                    return True
-        except (urllib.error.URLError, ConnectionError, OSError):
-            pass
-        time.sleep(1)
-    return False
-
-
-def main():
-    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    parser.add_argument("--keep-postgres", action="store_true",
-                         help="Don't tear down the checkpoint Postgres container afterward")
-    parser.add_argument("--postgres-port", default=os.environ.get("CHECKPOINT_POSTGRES_PORT", "5432"),
-                         help="Host port for the checkpoint's own Postgres container (default 5432 -- "
-                              "override if that's already in use on this machine)")
-    parser.add_argument("--backend-port", default=os.environ.get("CHECKPOINT_BACKEND_PORT", "18080"),
-                         help="Port to run the backend server on for the Godot smoke tests")
-    args = parser.parse_args()
-
-    results = {}
-
-    # --- Backend: bring up Postgres ---
-    compose_env = os.environ.copy()
-    compose_env["COMPOSE_PROJECT_NAME"] = "agp-checkpoint"
-    compose_env["POSTGRES_HOST_PORT"] = args.postgres_port
-    compose_env["POSTGRES_PORT"] = args.postgres_port  # some branches use this name instead, see tools/definitions.py
-    print("=== Backend: bringing up Postgres ===")
-    run(["docker", "compose", "up", "-d", "postgres"], cwd=BACKEND, env=compose_env)
-
-    print("Waiting for Postgres to be ready...")
-    pg_ready = False
-    for _ in range(20):
-        r = run(["docker", "compose", "exec", "-T", "postgres", "pg_isready", "-U", "agp_user", "-d", "agp_db"],
-                cwd=BACKEND, env=compose_env, capture=True)
-        if r.returncode == 0:
-            pg_ready = True
-            break
-        time.sleep(1)
-    if not pg_ready:
-        print("Postgres never became ready -- aborting.")
-        sys.exit(1)
-
-    db_url = f"postgresql+asyncpg://agp_user:agp_password@localhost:{args.postgres_port}/agp_db"
-    backend_env = os.environ.copy()
-    backend_env["DATABASE_URL"] = db_url
-
-    print("\n=== Backend: alembic upgrade head ===")
-    r = run([sys.executable, "-m", "alembic", "upgrade", "head"], cwd=BACKEND, env=backend_env)
-    results["migrations (fresh DB)"] = r.returncode == 0
-
-    print("\n=== Backend: pytest ===")
-    r = run([sys.executable, "-m", "pytest", "-v"], cwd=BACKEND, env=backend_env)
-    results["backend pytest"] = r.returncode == 0
-
-    # --- Godot: headless smoke tests (need a live backend server) ---
-    godot_bin = find_godot()
-    smoke_tests = sorted(glob.glob(str(ROOT / "scripts" / "smoke_test_*.gd")))
-
-    if not godot_bin:
-        print("\n=== Godot: binary not found (checked PATH and ~/godot/godot), skipping smoke tests ===")
-        results["godot smoke tests"] = None
-    elif not smoke_tests:
-        print("\n=== Godot: no scripts/smoke_test_*.gd found yet, nothing to run ===")
-        results["godot smoke tests"] = None
-    else:
-        print(f"\n=== Backend: starting server on :{args.backend_port} for Godot smoke tests ===")
-        server_proc = subprocess.Popen(
-            [sys.executable, "-m", "uvicorn", "app.main:app", "--host", "127.0.0.1", "--port", args.backend_port],
-            cwd=BACKEND, env=backend_env,
-            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
-        )
-        try:
-            base_url = f"http://127.0.0.1:{args.backend_port}"
-            if not wait_for_http(f"{base_url}/api/health"):
-                print("Backend server never became healthy -- skipping Godot smoke tests.")
-                results["godot smoke tests"] = False
-            else:
-                godot_env = os.environ.copy()
-                godot_env["AGP_API_BASE_URL"] = base_url
-
-                print("=== Godot: import pass (builds the class cache) ===")
-                run([godot_bin, "--headless", "--path", str(ROOT), "--import"], env=godot_env)
-                run([godot_bin, "--headless", "--path", str(ROOT), "--quit"], env=godot_env)
-
-                godot_ok = True
-                for test in smoke_tests:
-                    rel = os.path.relpath(test, ROOT)
-                    print(f"\n--- {rel} ---")
-                    r = run([godot_bin, "--headless", "--path", str(ROOT), "--script", f"res://{rel}"], env=godot_env)
-                    if r.returncode != 0:
-                        godot_ok = False
-                results["godot smoke tests"] = godot_ok
-        finally:
-            server_proc.terminate()
-            try:
-                server_proc.wait(timeout=10)
-            except subprocess.TimeoutExpired:
-                server_proc.kill()
-
-    if not args.keep_postgres:
-        print("\n=== Backend: tearing down checkpoint Postgres ===")
-        run(["docker", "compose", "down", "-v", "postgres"], cwd=BACKEND, env=compose_env)
-
-    # --- Summary ---
-    print("\n" + "=" * 50)
-    print("SUMMARY")
-    print("=" * 50)
-    overall_ok = True
-    for name, ok in results.items():
-        if ok is None:
-            print(f"  {name}: SKIPPED")
-        elif ok:
-            print(f"  {name}: PASS")
-        else:
-            print(f"  {name}: FAIL")
-            overall_ok = False
-
-    print("\nSee docs/testing/test_inventory.md for what each suite actually covers (and doesn't).")
-    sys.exit(0 if overall_ok else 1)
-
-
-if __name__ == "__main__":
-    main()

scripts/smoke_test_api.gd

@@ -1,46 +0,0 @@
-extends SceneTree
-## Headless smoke test for the ApiClient autoload.
-##
-## Run with:
-##     godot --headless --path . --script res://scripts/smoke_test_api.gd
-##
-## Requires the backend to be running (default base URL
-## `application/agp/api_base_url` -> http://127.0.0.1:8000).
-##
-## Calls the real autoload's `health_check()` (which exercises the generic
-## `request()` primitive) and exits 0 on a `status == "ok"` response, 1
-## otherwise. This script is intentionally NOT wired into any game scene.
-
-
-func _initialize() -> void:
-	_run()
-
-
-func _run() -> void:
-	# _initialize() fires before the SceneTree has processed its first frame,
-	# so a freshly add_child()'d HTTPRequest node isn't reliably considered
-	# "inside tree" yet (request_raw fails with !is_inside_tree()). One frame
-	# of delay is enough; this only matters for --script mode, not a real
-	# running game.
-	await process_frame
-
-	# Godot's --script/SceneTree runner doesn't resolve autoload singletons
-	# as bare global identifiers at compile time (the node exists at
-	# runtime -- root.has_node("ApiClient") is true -- but referencing it as
-	# a plain identifier fails with "Identifier not found: ApiClient" during
-	# script compilation). get_node sidesteps compile-time resolution
-	# entirely. This only affects --script mode; a real game scene resolves
-	# the bare autoload name normally.
-	var api_client := root.get_node("ApiClient")
-	print("SMOKE: calling ApiClient.health_check() ...")
-	var result: Dictionary = await api_client.health_check()
-	print("SMOKE: result = ", result)
-
-	if result.ok \
-			and result.data is Dictionary \
-			and str((result.data as Dictionary).get("status", "")) == "ok":
-		print("SMOKE RESULT: PASS (status=ok)")
-		quit(0)
-	else:
-		printerr("SMOKE RESULT: FAIL")
-		quit(1)