WIP checkpoint: PC2: Design the test level & player spawn approach

_show_authenticated() (the session-restore path, used when returning to
main_menu.tscn -- e.g. after clicking Back from world_list) only hid
EmailEdit/Over18Check, unlike _on_auth_complete() (the fresh-login path)
which hides the full form: UsernameEdit, PasswordEdit, EmailEdit,
Over18Check, AuthButton, AuthModeLabel. Play was correctly enabled and
the welcome message was correctly visible, so a check that stopped at
those two passed clean -- but the actual login fields were still on
screen, which is what a real user sees as "it's making me log in again."
Confirmed via live PC1 playtest today.

Reported by: real playtest, 2026-08-20 (yesterday's automated regression
test for this exact Play -> Back flow only asserted Play/welcome/auth
buttons row -- strengthened smoke_test_main_menu_back.gd to also check
the individual form fields, and confirmed it fails exactly this way with
the bug reintroduced before restoring the fix).

Verified against a live backend: 61/61 pytest (unaffected), 8/8 Godot
smoke tests (including 20/20 on the strengthened back-nav test).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M6rUEynmv2QmweocAQYARN

.gitignore

@@ -0,0 +1,13 @@
+# Godot 4 editor cache/import directory
+.godot/
+
+# Godot export artifacts
+export/
+*.tmp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Godot UID files (regenerated from path)
+*.uid

backend/.env.example

@@ -0,0 +1,23 @@
+# Database (async driver)
+DATABASE_URL=postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db
+
+# Redis
+REDIS_URL=redis://localhost:6379/0
+
+# JWT / Auth
+ALGORITHM=RS256
+ACCESS_TOKEN_EXPIRE_MINUTES=60
+REFRESH_TOKEN_EXPIRE_DAYS=30
+# Directory where the RSA keypair is loaded/generated at runtime.
+# Defaults to ~/.agp/keys (outside the repo). Keys are never committed to git.
+RSA_KEY_DIR=~/.agp/keys
+
+# App
+APP_NAME=AGP Backend
+APP_VERSION=0.1.0
+DEBUG=true
+CORS_ORIGINS=http://localhost:8080,http://localhost:3000
+
+# File uploads
+UPLOAD_DIR=uploads
+MAX_UPLOAD_SIZE_MB=100

backend/.gitignore

@@ -0,0 +1,4 @@
+.env
+__pycache__/
+*.pyc
+.venv/

backend/alembic.ini

@@ -0,0 +1,42 @@
+# Alembic configuration file.
+# Run: alembic upgrade head  (to apply migrations)
+# Run: alembic revision --autogenerate -m "description"  (to generate migration)
+
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+sqlalchemy.url = postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

backend/alembic/env.py

@@ -0,0 +1,65 @@
+"""Alembic environment configuration."""
+
+import asyncio
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from app.config import settings
+from app.database import Base
+from app.models import user, session, world, asset  # noqa: F401
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode."""
+    url = settings.DATABASE_URL
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection):
+    context.configure(connection=connection, target_metadata=target_metadata)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations():
+    """Run migrations in 'online' mode with async engine."""
+    connectable = create_async_engine(settings.DATABASE_URL, echo=False)
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

backend/alembic/script.py.mako

@@ -0,0 +1,27 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade database schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade database schema."""
+    ${downgrades if downgrades else "pass"}

backend/alembic/versions/0001_initial.py

@@ -0,0 +1,127 @@
+"""initial schema
+
+Revision ID: 0001_initial
+Revises:
+Create Date: 2024-01-01 00:00:00.000000
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0001_initial"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade database schema."""
+    # Create ENUM types
+    world_visibility = postgresql.ENUM(
+        "public", "private", "friends_only", name="world_visibility"
+    )
+    world_visibility.create(op.get_bind(), checkfirst=True)
+
+    asset_type = postgresql.ENUM(
+        "image", "audio", "video", "document", "model_3d", "other", name="asset_type"
+    )
+    asset_type.create(op.get_bind(), checkfirst=True)
+
+    # Create users table
+    op.create_table(
+        "users",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("username", sa.String(length=50), nullable=False),
+        sa.Column("email", sa.String(length=120), nullable=False),
+        sa.Column("hashed_password", sa.String(length=255), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.create_index(op.f("ix_users_email"), "users", ["email"], unique=True)
+    op.create_index(op.f("ix_users_id"), "users", ["id"], unique=False)
+    op.create_index(op.f("ix_users_username"), "users", ["username"], unique=True)
+
+    # Create sessions table
+    op.create_table(
+        "sessions",
+        sa.Column("id", sa.String(length=36), primary_key=True),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("token", sa.String(), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+    )
+    op.create_index(op.f("ix_sessions_token"), "sessions", ["token"], unique=True)
+
+    # Create worlds table
+    op.create_table(
+        "worlds",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("name", sa.String(length=255), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("owner_id", sa.Integer(), nullable=False),
+        sa.Column(
+            "visibility",
+            postgresql.ENUM(
+                "public", "private", "friends_only", name="world_visibility",
+                create_type=False,
+            ),
+            nullable=True,
+        ),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
+        sa.ForeignKeyConstraint(["owner_id"], ["users.id"]),
+    )
+    op.create_index(op.f("ix_worlds_id"), "worlds", ["id"], unique=False)
+
+    # Create assets table
+    op.create_table(
+        "assets",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("name", sa.String(length=255), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column(
+            "asset_type",
+            postgresql.ENUM(
+                "image", "audio", "video", "document", "model_3d", "other",
+                name="asset_type", create_type=False,
+            ),
+            nullable=False,
+        ),
+        sa.Column("file_path", sa.String(length=512), nullable=False),
+        sa.Column("file_size", sa.Integer(), nullable=True),
+        sa.Column("mime_type", sa.String(length=128), nullable=True),
+        sa.Column("metadata_json", sa.Text(), nullable=True),
+        sa.Column("world_id", sa.Integer(), nullable=True),
+        sa.Column("owner_id", sa.Integer(), nullable=False),
+        sa.Column("is_public", sa.Boolean(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        sa.ForeignKeyConstraint(["owner_id"], ["users.id"]),
+        sa.ForeignKeyConstraint(["world_id"], ["worlds.id"]),
+    )
+    op.create_index(op.f("ix_assets_id"), "assets", ["id"], unique=False)
+
+
+def downgrade() -> None:
+    """Downgrade database schema."""
+    op.drop_index(op.f("ix_assets_id"), table_name="assets")
+    op.drop_table("assets")
+    op.drop_index(op.f("ix_worlds_id"), table_name="worlds")
+    op.drop_table("worlds")
+    op.drop_index(op.f("ix_sessions_token"), table_name="sessions")
+    op.drop_table("sessions")
+    op.drop_index(op.f("ix_users_username"), table_name="users")
+    op.drop_index(op.f("ix_users_id"), table_name="users")
+    op.drop_index(op.f("ix_users_email"), table_name="users")
+    op.drop_table("users")
+
+    # Drop ENUM types
+    postgresql.ENUM(name="asset_type").drop(op.get_bind(), checkfirst=True)
+    postgresql.ENUM(name="world_visibility").drop(op.get_bind(), checkfirst=True)

backend/alembic/versions/0002_add_date_of_birth_to_users.py

@@ -0,0 +1,30 @@
+"""add date_of_birth column to users table
+
+Revision ID: 0002_add_date_of_birth_to_users
+Revises: 0001_initial
+Create Date: 2025-01-01 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0002_add_date_of_birth_to_users"
+down_revision: Union[str, None] = "0001_initial"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add date_of_birth column to users table."""
+    op.add_column(
+        "users",
+        sa.Column("date_of_birth", sa.Date(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    """Remove date_of_birth column from users table."""
+    op.drop_column("users", "date_of_birth")

backend/alembic/versions/0003_add_refresh_tokens_table.py

@@ -0,0 +1,36 @@
+"""add refresh_tokens table
+
+Revision ID: 0003_add_refresh_tokens_table
+Revises: 0002_add_date_of_birth_to_users
+Create Date: 2025-07-25 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0003_add_refresh_tokens_table"
+down_revision: Union[str, None] = "0002_add_date_of_birth_to_users"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create the refresh_tokens table."""
+    op.create_table(
+        "refresh_tokens",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("token", sa.String(512), unique=True, index=True, nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("is_active", sa.Boolean(), server_default=sa.text("true"), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+
+
+def downgrade() -> None:
+    """Drop the refresh_tokens table."""
+    op.drop_table("refresh_tokens")

backend/app/config.py

@@ -0,0 +1,127 @@
+"""Application configuration via pydantic-settings."""
+
+from functools import lru_cache
+from pathlib import Path
+
+from cryptography.hazmat.primitives.asymmetric.rsa import (
+    RSAPrivateKey,
+    RSAPublicKey,
+    generate_private_key,
+)
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+    load_pem_private_key,
+    load_pem_public_key,
+)
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _load_or_generate_rsa_keys(key_dir: Path) -> tuple[bytes, bytes]:
+    """Load existing RSA keys or generate a new pair.
+
+    Keys are stored as PEM files in *key_dir*.  The directory is created
+    if it does not exist.  Files are named ``private.pem`` and
+    ``public.pem`` and are **not** committed to git.
+    """
+    private_path = key_dir / "private.pem"
+    public_path = key_dir / "public.pem"
+
+    if private_path.exists() and public_path.exists():
+        private_pem = private_path.read_bytes()
+        public_pem = public_path.read_bytes()
+    else:
+        # Generate a new 2048-bit RSA key pair
+        private_key = generate_private_key(public_exponent=65537, key_size=2048)
+        private_pem = private_key.private_bytes(
+            Encoding.PEM,
+            PrivateFormat.PKCS8,
+            NoEncryption(),
+        )
+        public_pem = private_key.public_key().public_bytes(
+            Encoding.PEM,
+            PublicFormat.SubjectPublicKeyInfo,
+        )
+        key_dir.mkdir(parents=True, exist_ok=True)
+        private_path.write_bytes(private_pem)
+        public_path.write_bytes(public_pem)
+
+    return private_pem, public_pem
+
+
+class Settings(BaseSettings):
+    # App
+    APP_NAME: str = "AGP Backend"
+    APP_VERSION: str = "0.1.0"
+    DEBUG: bool = True
+
+    # Database (async)
+    DATABASE_URL: str = "postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db"
+
+    # Redis
+    REDIS_URL: str = "redis://localhost:6379/0"
+
+    # JWT / Auth
+    ALGORITHM: str = "RS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60
+    REFRESH_TOKEN_EXPIRE_DAYS: int = 30
+
+    # RS256 key storage.  Defaults to a directory outside the repo so the
+    # generated keypair is never accidentally committed.
+    RSA_KEY_DIR: str = str(Path.home() / ".agp" / "keys")
+
+    # CORS
+    CORS_ORIGINS: str = "http://localhost:8080,http://localhost:3000"
+
+    # 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",
+        env_file_encoding="utf-8",
+        case_sensitive=True,
+    )
+
+    @property
+    def cors_origins_list(self) -> list[str]:
+        return [origin.strip() for origin in self.CORS_ORIGINS.split(",")]
+
+    @property
+    def rsa_key_dir(self) -> Path:
+        return Path(self.RSA_KEY_DIR)
+
+    @property
+    def private_pem(self) -> bytes:
+        """Return the private key PEM bytes (loads/generates on first call)."""
+        private_pem, _ = _load_or_generate_rsa_keys(self.rsa_key_dir)
+        return private_pem
+
+    @property
+    def public_pem(self) -> bytes:
+        """Return the public key PEM bytes (loads/generates on first call)."""
+        _, public_pem = _load_or_generate_rsa_keys(self.rsa_key_dir)
+        return public_pem
+
+    @property
+    def private_key(self) -> RSAPrivateKey:
+        """Return the deserialized RSA private key object."""
+        return load_pem_private_key(self.private_pem, password=None)
+
+    @property
+    def public_key(self) -> RSAPublicKey:
+        """Return the deserialized RSA public key object."""
+        return load_pem_public_key(self.public_pem)
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """Return cached settings instance."""
+    return Settings()
+
+
+# Convenience singleton
+settings = get_settings()

backend/app/database.py

@@ -0,0 +1,42 @@
+"""Async database engine and session factory."""
+
+from sqlalchemy.ext.asyncio import (
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase
+
+from app.config import settings
+
+engine = create_async_engine(
+    settings.DATABASE_URL,
+    echo=settings.DEBUG,
+    pool_size=10,
+    max_overflow=20,
+)
+
+async_session_factory = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+async def get_db() -> AsyncSession:
+    """Dependency that yields an async database session.
+
+    Handlers are responsible for committing or rolling back their own
+    transactions.  This avoids the double-commit problem where the
+    session is committed both here and in the handler.
+    """
+    async with async_session_factory() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise

backend/app/dependencies.py

@@ -0,0 +1,55 @@
+"""Shared FastAPI dependencies, including JWT-based auth."""
+
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError, jwt
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import settings
+from app.database import get_db
+from app.models.user import User
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login")
+
+
+async def get_current_user(
+    token: Annotated[str, Depends(oauth2_scheme)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> User:
+    """Resolve the JWT bearer token to a User, or raise 401."""
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = jwt.decode(
+            token, settings.public_pem, algorithms=[settings.ALGORITHM]
+        )
+        user_id: str | None = payload.get("sub")
+        if user_id is None:
+            raise credentials_exception
+    except JWTError:
+        raise credentials_exception
+
+    try:
+        user_id_int = int(user_id)
+    except (ValueError, TypeError):
+        raise credentials_exception
+
+    result = await db.execute(select(User).where(User.id == user_id_int))
+    user = result.scalar_one_or_none()
+    if user is None:
+        raise credentials_exception
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User account is inactive",
+        )
+    return user
+
+
+CurrentUser = Annotated[User, Depends(get_current_user)]

backend/app/main.py

@@ -0,0 +1,46 @@
+"""FastAPI application entry point."""
+
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.config import settings
+from app.routers import auth, users, worlds, assets
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan: startup and shutdown events."""
+    # Startup: initialize database, connect to Redis, etc.
+    yield
+    # Shutdown: close connections, cleanup
+
+
+app = FastAPI(
+    title=settings.APP_NAME,
+    version=settings.APP_VERSION,
+    description="Agentic Game Platform - Backend API",
+    lifespan=lifespan,
+)
+
+# CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+app.include_router(auth.router, prefix="/api/auth", tags=["auth"])
+app.include_router(users.router, prefix="/api/users", tags=["users"])
+app.include_router(worlds.router, prefix="/api/worlds", tags=["worlds"])
+app.include_router(assets.router, prefix="/api/assets", tags=["assets"])
+
+
+@app.get("/api/health")
+async def health_check():
+    """Simple health check endpoint."""
+    return {"status": "ok", "app": settings.APP_NAME}

backend/app/models/__init__.py

@@ -0,0 +1,6 @@
+from app.models.user import User
+from app.models.session import Session
+from app.models.world import World
+from app.models.asset import Asset
+
+__all__ = ["User", "Session", "World", "Asset"]

backend/app/models/asset.py

@@ -0,0 +1,40 @@
+from sqlalchemy import Column, Integer, String, ForeignKey, Text, DateTime, Boolean
+from sqlalchemy.dialects.postgresql import ENUM
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+import enum
+
+from app.database import Base
+
+
+class AssetType(str, enum.Enum):
+    IMAGE = "image"
+    AUDIO = "audio"
+    VIDEO = "video"
+    DOCUMENT = "document"
+    MODEL_3D = "model_3d"
+    OTHER = "other"
+
+
+class Asset(Base):
+    __tablename__ = "assets"
+
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    asset_type = Column(
+        ENUM(AssetType, name="asset_type", create_type=False),
+        nullable=False,
+    )
+    file_path = Column(String(512), nullable=False)
+    file_size = Column(Integer, nullable=True)
+    mime_type = Column(String(128), nullable=True)
+    metadata_json = Column(Text, nullable=True)
+    world_id = Column(Integer, ForeignKey("worlds.id"), nullable=True)
+    owner_id = Column(Integer, ForeignKey("users.id"), nullable=False)
+    is_public = Column(Boolean, default=False, nullable=False)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+    owner = relationship("User", back_populates="assets")
+    world = relationship("World", back_populates="assets")

backend/app/models/session.py

@@ -0,0 +1,41 @@
+import uuid
+
+from sqlalchemy import Column, Integer, String, DateTime, ForeignKey, Boolean
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class Session(Base):
+    __tablename__ = "sessions"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    token = Column(String, unique=True, index=True, nullable=False)
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+    is_active = Column(Boolean, default=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+    user = relationship("User", back_populates="sessions")
+
+
+class RefreshToken(Base):
+    __tablename__ = "refresh_tokens"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    # RS256 JWTs are ~420+ chars; 512 is sufficient and matches the migration.
+    token = Column(String(512), unique=True, index=True, nullable=False)
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+    is_active = Column(Boolean, nullable=False, default=True, server_default="true")
+    created_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
+    updated_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+    user = relationship("User", back_populates="refresh_tokens")

backend/app/models/user.py

@@ -0,0 +1,38 @@
+from datetime import date
+from typing import Optional
+
+from sqlalchemy import Column, Integer, String, Boolean, DateTime, Date
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True, index=True)
+    username = Column(String(50), unique=True, index=True, nullable=False)
+    email = Column(String(120), unique=True, index=True, nullable=False)
+    hashed_password = Column(String(255), nullable=False)
+    date_of_birth = Column(Date, nullable=True)
+    is_active = Column(Boolean, default=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
+
+    sessions = relationship("Session", back_populates="user", cascade="all, delete-orphan")
+    refresh_tokens = relationship("RefreshToken", back_populates="user", cascade="all, delete-orphan")
+    worlds = relationship("World", back_populates="owner")
+    assets = relationship("Asset", back_populates="owner")
+
+    @property
+    def is_adult(self) -> bool:
+        """Return True if the user is 18 or older based on date_of_birth."""
+        if self.date_of_birth is None:
+            return False
+        today = date.today()
+        age = today.year - self.date_of_birth.year
+        # Adjust if birthday hasn't occurred yet this year
+        if (today.month, today.day) < (self.date_of_birth.month, self.date_of_birth.day):
+            age -= 1
+        return age >= 18

backend/app/models/world.py

@@ -0,0 +1,36 @@
+from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey
+from sqlalchemy.dialects.postgresql import ENUM
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+import enum
+
+from app.database import Base
+
+
+class WorldVisibility(enum.Enum):
+    PUBLIC = "public"
+    PRIVATE = "private"
+    FRIENDS_ONLY = "friends_only"
+
+
+class World(Base):
+    __tablename__ = "worlds"
+
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    owner_id = Column(Integer, ForeignKey("users.id"), nullable=False)
+    visibility = Column(
+        ENUM(
+            WorldVisibility,
+            name="world_visibility",
+            create_type=False,
+            values_callable=lambda enum_cls: [e.value for e in enum_cls],
+        ),
+        default=WorldVisibility.PUBLIC,
+    )
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
+
+    owner = relationship("User", back_populates="worlds")
+    assets = relationship("Asset", back_populates="world", cascade="all, delete-orphan")

backend/app/routers/assets.py

@@ -0,0 +1,243 @@
+"""Asset management router."""
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Query
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import settings
+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()
+
+
+# --- Pydantic schemas ---
+
+class AssetCreate(BaseModel):
+    """Schema for creating an asset reference."""
+    name: str = Field(..., min_length=1, max_length=255)
+    description: Optional[str] = None
+    asset_type: AssetType
+    world_id: Optional[int] = None
+
+
+class AssetResponse(BaseModel):
+    """Schema for asset responses."""
+    id: int
+    name: str
+    description: Optional[str]
+    asset_type: AssetType
+    file_path: str
+    file_size: Optional[int]
+    mime_type: Optional[str]
+    world_id: Optional[int]
+    owner_id: int
+    is_public: bool
+    created_at: str
+    updated_at: str
+
+    model_config = {"from_attributes": True}
+
+
+class AssetUpdate(BaseModel):
+    """Schema for updating an asset."""
+    name: Optional[str] = None
+    description: Optional[str] = None
+    is_public: Optional[bool] = None
+
+
+# --- Helpers ---
+
+def _sanitize_filename(filename: str) -> str:
+    """Strip path components and unsafe characters from a filename."""
+    # Remove any directory components (path traversal protection).
+    base = os.path.basename(filename.replace("\\", "/"))
+    # Keep only safe characters.
+    safe = "".join(c for c in base if c.isalnum() or c in "._-")
+    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)
+async def create_asset(
+    payload: AssetCreate,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Create a new asset reference."""
+    # Verify world ownership if world_id is provided
+    if payload.world_id is not None:
+        world = await db.get(World, payload.world_id)
+        if world is None:
+            raise HTTPException(status_code=404, detail="World not found")
+        if world.owner_id != current_user.id:
+            raise HTTPException(status_code=403, detail="Not owner of this world")
+
+    asset = Asset(
+        name=payload.name,
+        description=payload.description,
+        asset_type=payload.asset_type,
+        file_path="",  # Will be set after upload
+        owner_id=current_user.id,
+        world_id=payload.world_id,
+        is_public=False,
+    )
+    db.add(asset)
+    await db.commit()
+    await db.refresh(asset)
+    return asset
+
+
+@router.get("/", response_model=list[AssetResponse])
+async def list_assets(
+    current_user: CurrentUser,
+    world_id: Optional[int] = Query(None, description="Filter by world"),
+    asset_type: Optional[AssetType] = Query(None),
+    limit: int = Query(50, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+    db: AsyncSession = Depends(get_db),
+):
+    """List assets with optional filters."""
+    stmt = select(Asset).where(Asset.owner_id == current_user.id)
+
+    if world_id is not None:
+        stmt = stmt.where(Asset.world_id == world_id)
+    if asset_type is not None:
+        stmt = stmt.where(Asset.asset_type == asset_type)
+
+    stmt = stmt.order_by(Asset.created_at.desc()).limit(limit).offset(offset)
+    result = await db.execute(stmt)
+    assets = result.scalars().all()
+    return assets
+
+
+@router.get("/{asset_id}", response_model=AssetResponse)
+async def get_asset(
+    asset_id: int,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Get a single asset by ID."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or asset.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="Asset not found")
+    return asset
+
+
+@router.patch("/{asset_id}", response_model=AssetResponse)
+async def update_asset(
+    asset_id: int,
+    payload: AssetUpdate,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Update an asset."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or asset.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="Asset not found")
+
+    update_data = payload.model_dump(exclude_unset=True)
+    for field, value in update_data.items():
+        setattr(asset, field, value)
+
+    await db.commit()
+    await db.refresh(asset)
+    return asset
+
+
+@router.delete("/{asset_id}", status_code=204)
+async def delete_asset(
+    asset_id: int,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete an asset."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or asset.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="Asset not found")
+
+    await db.delete(asset)
+    await db.commit()
+
+
+@router.post("/{asset_id}/upload", response_model=AssetResponse)
+async def upload_asset_file(
+    asset_id: int,
+    current_user: CurrentUser,
+    file: UploadFile = File(...),
+    db: AsyncSession = Depends(get_db),
+):
+    """Upload a file for an existing asset."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or asset.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="Asset not found")
+
+    # Sanitize filename to prevent path traversal.
+    safe_filename = _sanitize_filename(file.filename or f"asset_{asset_id}")
+
+    # Read the file content.
+    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,
+            detail=f"File size {file_size} exceeds maximum allowed size {max_bytes} bytes",
+        )
+
+    # Write the file to the upload directory.
+    upload_dir = Path(settings.UPLOAD_DIR)
+    upload_dir.mkdir(parents=True, exist_ok=True)
+    stored_name = f"{asset_id}_{safe_filename}"
+    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/routers/auth.py

@@ -0,0 +1,311 @@
+"""Authentication router - login, register, token refresh."""
+
+import uuid
+from datetime import date, datetime, timedelta, timezone
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordRequestForm
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+from pydantic import BaseModel, EmailStr
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import settings
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.session import RefreshToken
+from app.models.user import User
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+router = APIRouter()
+
+
+# --- Pydantic schemas ---
+
+class TokenResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+    access_token_expires_minutes: int
+
+
+class RefreshRequest(BaseModel):
+    refresh_token: str
+
+
+class RegisterRequest(BaseModel):
+    username: str
+    email: EmailStr
+    password: str
+    over_18: bool  # Simple boolean confirmation instead of date_of_birth
+
+
+class UserResponse(BaseModel):
+    id: int
+    username: str
+    email: str
+    date_of_birth: str | None = None
+    is_active: bool
+    created_at: datetime | None = None
+
+    model_config = {"from_attributes": True}
+
+
+# --- Helpers ---
+
+def _create_access_token(data: dict) -> str:
+    """Create a signed access token using RS256.
+
+    Includes a unique ``jti`` claim so that concurrent/same-second calls
+    (e.g. back-to-back /refresh requests) still produce distinct tokens —
+    without it, two tokens minted for the same user within the same
+    second are byte-identical since ``sub``/``exp`` are the only claims.
+    """
+    to_encode = data.copy()
+    to_encode["jti"] = str(uuid.uuid4())
+    expire = datetime.now(timezone.utc) + timedelta(
+        minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES
+    )
+    to_encode.update({"exp": expire})
+    return jwt.encode(
+        to_encode,
+        settings.private_pem,
+        algorithm=settings.ALGORITHM,
+    )
+
+
+def _create_refresh_token(data: dict) -> str:
+    """Create a signed refresh token using RS256.
+
+    Includes a unique ``jti`` claim so that concurrent calls produce
+    distinct tokens even when issued within the same second.
+    """
+    to_encode = data.copy()
+    to_encode["jti"] = str(uuid.uuid4())
+    expire = datetime.now(timezone.utc) + timedelta(
+        days=settings.REFRESH_TOKEN_EXPIRE_DAYS
+    )
+    to_encode.update({"exp": expire})
+    return jwt.encode(
+        to_encode,
+        settings.private_pem,
+        algorithm=settings.ALGORITHM,
+    )
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a plain password against a hash."""
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def hash_password(password: str) -> str:
+    """Hash a password."""
+    return pwd_context.hash(password)
+
+
+def calculate_age(birth_date: date, today: date | None = None) -> int:
+    """Calculate age in years from a birth date.
+
+    Not called by /register anymore (that endpoint now just trusts the
+    client's over_18 boolean, see RegisterRequest) -- kept as a real,
+    tested utility since date-of-birth storage/verification is coming
+    back in a future pass (real age math, not just a client-side claim,
+    the user explicitly wants to revisit this design). Removing it broke
+    backend/tests/test_auth_age_gate.py's collection entirely (ImportError
+    on `from app.routers.auth import calculate_age`) for zero benefit --
+    restoring it is the lower-risk path over rewriting or deleting 17
+    tests for logic this codebase will need again.
+
+    Args:
+        birth_date: The person's date of birth.
+        today: The reference date. Defaults to today's date (UTC).
+
+    Returns:
+        Age in whole years as of the reference date.
+    """
+    if today is None:
+        today = datetime.now(timezone.utc).date()
+
+    age = today.year - birth_date.year
+    # Adjust if birthday hasn't occurred yet this year
+    if (today.month, today.day) < (birth_date.month, birth_date.day):
+        age -= 1
+    return age
+
+
+def _issue_refresh_token(user_id: int, db: AsyncSession) -> str:
+    """Create and persist a refresh token for the given user."""
+    refresh_token_value = _create_refresh_token({"sub": str(user_id)})
+    refresh_token_record = RefreshToken(
+        id=str(uuid.uuid4()),
+        user_id=user_id,
+        token=refresh_token_value,
+        expires_at=datetime.now(timezone.utc)
+        + timedelta(days=settings.REFRESH_TOKEN_EXPIRE_DAYS),
+    )
+    db.add(refresh_token_record)
+    return refresh_token_value
+
+
+# --- Endpoints ---
+
+@router.post("/register", response_model=TokenResponse, status_code=status.HTTP_201_CREATED)
+async def register(req: RegisterRequest, db: AsyncSession = Depends(get_db)):
+    """Register a new user and return access + refresh tokens.
+
+    Requires over_18 boolean confirmation; rejects users who are not 18+.
+    """
+    if not req.over_18:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Must be 18 or older to register",
+        )
+
+    # Check if username already exists
+    result = await db.execute(select(User).where(User.username == req.username))
+    if result.scalar_one_or_none():
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Username already registered",
+        )
+
+    # Check if email already exists
+    result = await db.execute(select(User).where(User.email == req.email))
+    if result.scalar_one_or_none():
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Email already registered",
+        )
+
+    user = User(
+        username=req.username,
+        email=req.email,
+        hashed_password=hash_password(req.password),
+        date_of_birth=None,  # No longer collecting DOB
+    )
+    db.add(user)
+    await db.flush()  # flush to get user.id before creating refresh token
+    await db.refresh(user)
+
+    # Create access token
+    access_token = _create_access_token({"sub": str(user.id)})
+
+    # Create and persist refresh token
+    refresh_token_value = _issue_refresh_token(user.id, db)
+    await db.commit()
+
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=refresh_token_value,
+        access_token_expires_minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
+    )
+
+
+@router.post("/login", response_model=TokenResponse)
+async def login(form: OAuth2PasswordRequestForm = Depends(), db: AsyncSession = Depends(get_db)):
+    """Authenticate user and return access + refresh tokens.
+
+    Accepts form-encoded credentials (username/password) as expected by
+    OAuth2PasswordBearer, so the Swagger UI "Authorize" flow works correctly.
+    """
+    result = await db.execute(select(User).where(User.username == form.username))
+    user = result.scalar_one_or_none()
+
+    if not user or not verify_password(form.password, user.hashed_password):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password",
+        )
+
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User account is inactive",
+        )
+
+    # Create access token
+    access_token = _create_access_token({"sub": str(user.id)})
+
+    # Create and persist refresh token
+    refresh_token_value = _issue_refresh_token(user.id, db)
+    await db.commit()
+
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=refresh_token_value,
+        access_token_expires_minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
+    )
+
+
+@router.post("/refresh", response_model=TokenResponse)
+async def refresh(req: RefreshRequest, db: AsyncSession = Depends(get_db)):
+    """Exchange a valid refresh token for a new access token.
+
+    Validates the refresh token against the database:
+    - Must exist in the refresh_tokens table
+    - Must not be expired (expires_at > now)
+    - Must be active (is_active == true)
+
+    On success, returns a new access token. The refresh token itself is
+    NOT rotated (the client keeps using the same refresh token).
+    """
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Invalid or expired refresh token",
+    )
+
+    # Step 1: Decode and validate the JWT signature/claims
+    try:
+        payload = jwt.decode(
+            req.refresh_token,
+            settings.public_pem,
+            algorithms=[settings.ALGORITHM],
+        )
+    except JWTError:
+        raise credentials_exception
+
+    user_id_str: str | None = payload.get("sub")
+    if user_id_str is None:
+        raise credentials_exception
+
+    try:
+        user_id = int(user_id_str)
+    except (ValueError, TypeError):
+        raise credentials_exception
+
+    # Step 2: Look up the refresh token in the database
+    result = await db.execute(
+        select(RefreshToken).where(
+            RefreshToken.token == req.refresh_token,
+            RefreshToken.user_id == user_id,
+        )
+    )
+    stored_token = result.scalar_one_or_none()
+
+    if stored_token is None:
+        raise credentials_exception
+
+    # Step 3: Check if the token is expired
+    if datetime.now(timezone.utc) >= stored_token.expires_at:
+        raise credentials_exception
+
+    # Step 4: Check if the token is active
+    if not stored_token.is_active:
+        raise credentials_exception
+
+    # Step 5: Issue a new access token
+    access_token = _create_access_token({"sub": str(user_id)})
+
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=req.refresh_token,  # Return the same refresh token
+        access_token_expires_minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
+    )
+
+
+@router.get("/me", response_model=UserResponse)
+async def get_current_user(current_user: CurrentUser):
+    """Get current user profile from the JWT token."""
+    return current_user

backend/app/routers/users.py

@@ -0,0 +1,106 @@
+"""User management router."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, EmailStr
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.user import User
+
+router = APIRouter()
+
+
+# ─── Pydantic schemas ────────────────────────────────────────────────────────
+
+class UserResponse(BaseModel):
+    id: int
+    username: str
+    email: str
+    is_active: bool
+
+    model_config = {"from_attributes": True}
+
+
+class UserUpdate(BaseModel):
+    email: EmailStr | None = None
+    is_active: bool | None = None
+
+
+# ─── Endpoints ───────────────────────────────────────────────────────────────
+
+@router.get("/me", response_model=UserResponse)
+async def get_current_user_profile(
+    current_user: CurrentUser,
+):
+    """Get the currently authenticated user's profile."""
+    return current_user
+
+
+@router.get("/{user_id}", response_model=UserResponse)
+async def get_user(
+    user_id: int,
+    current_user: CurrentUser,
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    """Get a user by ID.  Only the owner can view their own profile."""
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    # Only the owner may view their own profile.
+    if user.id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not authorized to view this user")
+
+    return user
+
+
+@router.patch("/{user_id}", response_model=UserResponse)
+async def update_user(
+    user_id: int,
+    user_update: UserUpdate,
+    current_user: CurrentUser,
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    """Update a user.  Only the owner can update their own account."""
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    # Only the owner may update their own account.
+    if user.id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not authorized to update this user")
+
+    if user_update.email is not None:
+        user.email = user_update.email
+    if user_update.is_active is not None:
+        user.is_active = user_update.is_active
+
+    await db.commit()
+    await db.refresh(user)
+    return user
+
+
+@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user(
+    user_id: int,
+    current_user: CurrentUser,
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    """Delete a user.  Only the owner can delete their own account."""
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    # Only the owner may delete their own account.
+    if user.id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not authorized to delete this user")
+
+    await db.delete(user)
+    await db.commit()

backend/app/routers/worlds.py

@@ -0,0 +1,169 @@
+"""Worlds router - CRUD for game worlds."""
+
+from datetime import datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel, Field
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.world import World, WorldVisibility
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+
+# --- Pydantic schemas ---
+
+class WorldCreate(BaseModel):
+    """Schema for creating a world."""
+    name: str = Field(..., min_length=1, max_length=255)
+    description: str | None = None
+    visibility: WorldVisibility = WorldVisibility.PUBLIC
+
+
+class WorldUpdate(BaseModel):
+    """Schema for updating a world."""
+    name: str | None = Field(None, min_length=1, max_length=255)
+    description: str | None = None
+    visibility: WorldVisibility | None = None
+
+
+class WorldResponse(BaseModel):
+    """Schema for world responses."""
+    id: int
+    name: str
+    description: str | None
+    visibility: WorldVisibility
+    owner_id: int
+    created_at: datetime | None = None
+
+    model_config = {"from_attributes": True}
+
+
+# --- Endpoints ---
+
+@router.get("/", response_model=list[WorldResponse])
+async def list_worlds(
+    current_user: CurrentUser,
+    db: DbDep,
+    skip: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=100),
+    visibility: WorldVisibility | None = None,
+):
+    """List worlds visible to the current user.
+
+    PUBLIC worlds are visible to everyone.
+    PRIVATE/FRIENDS_ONLY worlds are visible to their owner.
+    """
+    query = select(World).options(selectinload(World.owner))
+
+    # Filter by visibility if specified
+    if visibility:
+        query = query.where(World.visibility == visibility)
+        if visibility != WorldVisibility.PUBLIC:
+            # Requesting a non-public visibility explicitly must not bypass
+            # ownership — otherwise any authenticated user could list every
+            # PRIVATE/FRIENDS_ONLY world in the system just by passing the
+            # filter, defeating the point of the check below.
+            query = query.where(World.owner_id == current_user.id)
+    else:
+        # Show PUBLIC worlds + owner's own worlds
+        query = query.where(
+            (World.visibility == WorldVisibility.PUBLIC)
+            | (World.owner_id == current_user.id)
+        )
+
+    query = query.offset(skip).limit(limit).order_by(World.created_at.desc())
+    result = await db.execute(query)
+    worlds = result.scalars().all()
+    return worlds
+
+
+@router.get("/{world_id}", response_model=WorldResponse)
+async def get_world(
+    world_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Get a single world by ID, respecting visibility."""
+    result = await db.execute(
+        select(World).where(World.id == world_id).options(selectinload(World.owner))
+    )
+    world = result.scalar_one_or_none()
+    if not world:
+        raise HTTPException(status_code=404, detail="World not found")
+
+    # Allow access if world is PUBLIC or owned by current user
+    if world.visibility != WorldVisibility.PUBLIC and world.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="World not found")
+
+    return world
+
+
+@router.post("/", response_model=WorldResponse, status_code=201)
+async def create_world(
+    world_data: WorldCreate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Create a new world."""
+    world = World(
+        name=world_data.name,
+        description=world_data.description,
+        owner_id=current_user.id,
+        visibility=world_data.visibility,
+    )
+    db.add(world)
+    await db.commit()
+    await db.refresh(world)
+    return world
+
+
+@router.put("/{world_id}", response_model=WorldResponse)
+async def update_world(
+    world_id: int,
+    world_data: WorldUpdate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Update an existing world."""
+    result = await db.execute(select(World).where(World.id == world_id))
+    world = result.scalar_one_or_none()
+    if not world:
+        raise HTTPException(status_code=404, detail="World not found")
+
+    if world.owner_id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not owner of this world")
+
+    update_data = world_data.model_dump(exclude_unset=True)
+    for field, value in update_data.items():
+        setattr(world, field, value)
+
+    await db.commit()
+    await db.refresh(world)
+    return world
+
+
+@router.delete("/{world_id}", status_code=204)
+async def delete_world(
+    world_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Delete a world."""
+    result = await db.execute(select(World).where(World.id == world_id))
+    world = result.scalar_one_or_none()
+    if not world:
+        raise HTTPException(status_code=404, detail="World not found")
+
+    if world.owner_id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not owner of this world")
+
+    await db.delete(world)
+    await db.commit()

backend/app/services/gltf.py

@@ -0,0 +1,197 @@
+"""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/docker-compose.yml

@@ -0,0 +1,34 @@
+version: "3.9"
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: agp_user
+      POSTGRES_PASSWORD: agp_password
+      POSTGRES_DB: agp_db
+    ports:
+      - "${POSTGRES_HOST_PORT:-5432}:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U agp_user -d agp_db"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "${REDIS_HOST_PORT:-6379}:6379"
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:
+  redis_data:

backend/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+asyncio_mode = auto
+testpaths = tests

backend/requirements.txt

@@ -0,0 +1,25 @@
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+sqlalchemy==2.0.36
+alembic==1.14.0
+psycopg2-binary==2.9.10
+asyncpg==0.31.0
+redis==5.2.1
+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
+pytest==8.3.4
+pytest-asyncio==0.25.0
+pytest-cov==6.0.0

backend/tests/conftest.py

@@ -0,0 +1,38 @@
+"""Shared pytest fixtures.
+
+The auth integration tests hit the *real* Postgres database (per
+``DATABASE_URL``), so they persist data between runs.  Without cleanup a
+second run of the suite fails with 409 conflicts because the users it
+registered on the first run already exist.  The session-scoped fixture below
+truncates all application tables once before the first test, making the suite
+re-runnable.
+
+Truncation order doesn't strictly matter because ``CASCADE`` follows foreign
+keys, but the tables are listed explicitly for clarity.
+"""
+
+import asyncio
+
+import pytest
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from app.config import settings
+
+TEST_TABLES = ("assets", "worlds", "sessions", "refresh_tokens", "users")
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _reset_database():
+    """Truncate all application tables once per test session."""
+
+    async def _truncate() -> None:
+        engine = create_async_engine(settings.DATABASE_URL)
+        async with engine.begin() as conn:
+            await conn.execute(
+                text(f"TRUNCATE TABLE {', '.join(TEST_TABLES)} CASCADE")
+            )
+        await engine.dispose()
+
+    asyncio.run(_truncate())
+    yield

backend/tests/test_auth_age_gate.py

@@ -0,0 +1,94 @@
+"""Tests for the 18+ age gate on user registration."""
+
+from datetime import date, timedelta
+
+import pytest
+
+from app.routers.auth import calculate_age
+
+
+class TestCalculateAge:
+    """Unit tests for the calculate_age helper."""
+
+    def test_exactly_18(self):
+        """A person born exactly 18 years ago today is 18."""
+        today = date(2025, 6, 15)
+        dob = today.replace(year=today.year - 18)
+        assert calculate_age(dob, today=today) == 18
+
+    def test_just_turned_18(self):
+        """A person who turned 18 yesterday is 18."""
+        today = date(2025, 6, 15)
+        dob = today.replace(year=today.year - 18) - timedelta(days=1)
+        assert calculate_age(dob, today=today) == 18
+
+    def test_one_day_short_of_18(self):
+        """A person born one day after their 18th birthday is 17."""
+        today = date(2025, 6, 15)
+        dob = today.replace(year=today.year - 18) + timedelta(days=1)
+        assert calculate_age(dob, today=today) == 17
+
+    def test_17_years_old(self):
+        """A person who is 17 years old today is 17."""
+        today = date(2025, 6, 15)
+        dob = date(2008, 6, 15)
+        assert calculate_age(dob, today=today) == 17
+
+    def test_65_years_old(self):
+        """A person who is 65 is correctly calculated."""
+        today = date(2025, 6, 15)
+        dob = today.replace(year=today.year - 65)
+        assert calculate_age(dob, today=today) == 65
+
+    def test_newborn(self):
+        """A newborn is 0."""
+        today = date(2025, 6, 15)
+        dob = today
+        assert calculate_age(dob, today=today) == 0
+
+    def test_birthday_not_yet_this_year(self):
+        """Person born Dec 31, 2000 — on Jan 1, 2025 they are still 24."""
+        dob = date(2000, 12, 31)
+        assert calculate_age(dob, today=date(2025, 1, 1)) == 24
+
+    def test_birthday_today(self):
+        """Person born Dec 31, 2000 — on Dec 31, 2024 they turn 24."""
+        dob = date(2000, 12, 31)
+        assert calculate_age(dob, today=date(2024, 12, 31)) == 24
+
+
+class TestRegisterRequestOver18Field:
+    """Tests for RegisterRequest's over_18 field.
+
+    Replaces TestRegisterRequestDateValidation -- date_of_birth and its
+    field_validator were removed from RegisterRequest 2026-08-20 (interim
+    simplification: a plain client-side over_18 confirmation instead of
+    collecting/validating an actual date of birth; see calculate_age's
+    own docstring in app/routers/auth.py for why that function is still
+    here even though this endpoint no longer calls it). There's no date
+    format left to validate, so the equivalent coverage is just: the
+    field exists, is a real bool, and is required."""
+
+    def test_over_18_true_accepted(self):
+        from app.routers.auth import RegisterRequest
+
+        req = RegisterRequest(username="u", email="u@example.com", password="p", over_18=True)
+        assert req.over_18 is True
+
+    def test_over_18_false_accepted(self):
+        """False is a valid value at the schema level -- the endpoint,
+        not the schema, is what rejects it (see
+        TestRegister::test_register_rejects_not_over_18 in
+        test_auth_endpoints.py)."""
+        from app.routers.auth import RegisterRequest
+
+        req = RegisterRequest(username="u", email="u@example.com", password="p", over_18=False)
+        assert req.over_18 is False
+
+    def test_over_18_missing_rejected(self):
+        """over_18 has no default -- omitting it entirely is a validation error."""
+        from app.routers.auth import RegisterRequest
+        from pydantic import ValidationError
+
+        with pytest.raises(ValidationError):
+            RegisterRequest(username="u", email="u@example.com", password="p")

backend/tests/test_auth_endpoints.py

@@ -0,0 +1,259 @@
+"""Integration tests for the auth endpoints (register + login).
+
+These tests hit the real FastAPI app against the real configured database
+(DATABASE_URL -- Postgres via Alembic migrations in CI/dev, not an isolated
+in-memory DB), so they exercise the full stack: Pydantic validation → DB →
+JWT → response. Requires migrations already applied (alembic upgrade head)
+before running.
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import settings
+from app.main import app
+from app.database import get_db
+from app.routers.auth import pwd_context
+
+
+# ---------------------------------------------------------------------------
+# Test fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def _override_db():
+    """Override get_db so the app uses a fresh session per test.
+
+    Deliberately does NOT reuse app.database's shared engine: FastAPI's
+    (sync) TestClient runs each request through anyio's blocking-portal
+    machinery, which can hand different requests different event loops.
+    asyncpg connections are bound to the loop they were created on, so
+    reusing one from the shared engine's connection pool across requests
+    raises "cannot perform operation: another operation is in progress" the
+    moment a test makes more than one request (register-then-login,
+    register-twice, etc.) -- confirmed this is the actual cause, not a bug
+    in the endpoints themselves. NullPool sidesteps it: every checkout is a
+    brand-new connection, never handed to a different loop than the one
+    that opened it.
+    """
+    test_engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+    test_session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
+
+    async def _get_db():
+        async_session = test_session_factory()
+        try:
+            yield async_session
+            await async_session.commit()
+        except Exception:
+            await async_session.rollback()
+            raise
+        finally:
+            await async_session.close()
+
+    app.dependency_overrides[get_db] = _get_db
+    yield
+    app.dependency_overrides.clear()
+
+
+# ---------------------------------------------------------------------------
+# Register endpoint
+# ---------------------------------------------------------------------------
+
+class TestRegister:
+    """Tests for POST /api/auth/register."""
+
+    def test_register_success(self):
+        """A valid registration returns 201 with a token."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "newuser",
+                "email": "new@example.com",
+                "password": "secret123",
+                "over_18": True,
+            },
+        )
+        assert resp.status_code == 201
+        data = resp.json()
+        assert "access_token" in data
+        assert data["token_type"] == "bearer"
+
+    def test_register_rejects_not_over_18(self):
+        """over_18=false gets a 400 with a detail message.
+
+        The interim design (2026-08-20) trusts a client-side boolean
+        confirmation instead of collecting/validating an actual date of
+        birth -- this only checks that the flag is respected, not real
+        age math (there's no date to verify against anymore). Real DOB
+        collection/verification may come back in a future pass."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "kid",
+                "email": "kid@example.com",
+                "password": "secret123",
+                "over_18": False,
+            },
+        )
+        assert resp.status_code == 400
+        assert "18 or older" in resp.json()["detail"]
+
+    def test_register_rejects_duplicate_username(self):
+        """Registering the same username twice returns 409."""
+        client = TestClient(app)
+        # First registration
+        client.post(
+            "/api/auth/register",
+            json={
+                "username": "duplicate",
+                "email": "dup1@example.com",
+                "password": "secret123",
+                "over_18": True,
+            },
+        )
+        # Second registration with same username, different email
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "duplicate",
+                "email": "dup2@example.com",
+                "password": "secret123",
+                "over_18": True,
+            },
+        )
+        assert resp.status_code == 409
+        assert "Username already registered" in resp.json()["detail"]
+
+    def test_register_rejects_duplicate_email(self):
+        """Registering the same email twice returns 409."""
+        client = TestClient(app)
+        client.post(
+            "/api/auth/register",
+            json={
+                "username": "user1",
+                "email": "same@example.com",
+                "password": "secret123",
+                "over_18": True,
+            },
+        )
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "user2",
+                "email": "same@example.com",
+                "password": "secret123",
+                "over_18": True,
+            },
+        )
+        assert resp.status_code == 409
+        assert "Email already registered" in resp.json()["detail"]
+
+    def test_register_missing_over_18(self):
+        """Missing the required over_18 field returns 422.
+
+        Replaces the old test_register_invalid_date_format -- there's no
+        date format to get wrong anymore (no date field at all), so the
+        closest equivalent "malformed request" case is the required
+        over_18 boolean being absent entirely."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "user",
+                "email": "user@example.com",
+                "password": "secret123",
+            },
+        )
+        assert resp.status_code == 422
+
+
+# ---------------------------------------------------------------------------
+# Login endpoint
+# ---------------------------------------------------------------------------
+
+class TestLogin:
+    """Tests for POST /api/auth/login."""
+
+    def _create_user(self, username: str, password: str, email: str = None):
+        """Helper to create a user via register."""
+        client = TestClient(app)
+        if email is None:
+            email = f"{username}@example.com"
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": username,
+                "email": email,
+                "password": password,
+                "over_18": True,
+            },
+        )
+        assert resp.status_code == 201
+        return resp.json()["access_token"]
+
+    def test_login_success(self):
+        """Correct credentials return a token."""
+        self._create_user("loginuser", "correctpass")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "loginuser", "password": "correctpass"},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "access_token" in data
+        assert data["token_type"] == "bearer"
+
+    def test_login_wrong_password(self):
+        """Wrong password returns 401."""
+        # Distinct username from test_login_success -- there's no per-test
+        # DB rollback/isolation here (real Postgres via the app's own
+        # dependency-overridden session), so reusing "loginuser" collided
+        # with the user that test already created (409 on register instead
+        # of the intended 401-on-login assertion this test is actually for).
+        self._create_user("loginuser_wrongpass", "correctpass")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "loginuser_wrongpass", "password": "wrongpass"},
+        )
+        assert resp.status_code == 401
+        assert "Incorrect username or password" in resp.json()["detail"]
+
+    def test_login_nonexistent_user(self):
+        """Non-existent user returns 401 (not 404)."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "nobody", "password": "any"},
+        )
+        assert resp.status_code == 401
+        assert "Incorrect username or password" in resp.json()["detail"]
+
+    def test_login_accepts_form_encoded(self):
+        """Login accepts application/x-www-form-urlencoded (OAuth2)."""
+        self._create_user("formuser", "formpass")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "formuser", "password": "formpass"},
+        )
+        assert resp.status_code == 200
+        assert "access_token" in resp.json()
+
+    def test_login_token_is_valid_jwt(self):
+        """The returned token is a valid JWT that can be decoded."""
+        self._create_user("jwttoken", "jwt123")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "jwttoken", "password": "jwt123"},
+        )
+        token = resp.json()["access_token"]
+        # Verify it's a 3-part JWT
+        parts = token.split(".")
+        assert len(parts) == 3

backend/tests/test_auth_expired_token.py

@@ -0,0 +1,171 @@
+"""Tests for expired-token rejection across auth endpoints.
+
+Covers two distinct expiry paths:
+
+1. An *access* JWT whose ``exp`` claim is in the past must be rejected
+   with 401 by ``GET /api/auth/me`` (jose's built-in ``exp`` validation).
+2. A *refresh* token whose persisted ``expires_at`` is in the past must be
+   rejected with 401 by ``POST /api/auth/refresh`` even though its JWT
+   signature is still valid.
+
+Requires migrations already applied (alembic upgrade head) before running.
+"""
+
+import asyncio
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from fastapi.testclient import TestClient
+from jose import jwt
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import settings
+from app.main import app
+from app.database import get_db
+from app.models.session import RefreshToken
+
+
+# ---------------------------------------------------------------------------
+# Test fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def _override_db():
+    """Override get_db so the app uses a fresh session per test."""
+    test_engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+    test_session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
+
+    async def _get_db():
+        async_session = test_session_factory()
+        try:
+            yield async_session
+            await async_session.commit()
+        except Exception:
+            await async_session.rollback()
+            raise
+        finally:
+            await async_session.close()
+
+    app.dependency_overrides[get_db] = _get_db
+    yield
+    app.dependency_overrides.clear()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _mint_access_token(exp: datetime) -> str:
+    """Mint an RS256 access token with an explicit ``exp`` claim."""
+    return jwt.encode(
+        {"sub": "1", "exp": exp},
+        settings.private_pem,
+        algorithm=settings.ALGORITHM,
+    )
+
+
+def _expire_refresh_token_in_db(token: str) -> None:
+    """Set the persisted refresh token's ``expires_at`` into the past."""
+
+    async def _do():
+        engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+        session_factory = async_sessionmaker(engine, expire_on_commit=False)
+        async with session_factory() as session:
+            from sqlalchemy import update
+
+            await session.execute(
+                update(RefreshToken)
+                .where(RefreshToken.token == token)
+                .values(expires_at=datetime.now(timezone.utc) - timedelta(hours=1))
+            )
+            await session.commit()
+        await engine.dispose()
+
+    asyncio.run(_do())
+
+
+def _register_user(client: TestClient, username: str) -> str:
+    """Register a user and return its refresh token."""
+    resp = client.post(
+        "/api/auth/register",
+        json={
+            "username": username,
+            "email": f"{username}@example.com",
+            "password": "secret123",
+            "over_18": True,
+        },
+    )
+    assert resp.status_code == 201
+    return resp.json()["refresh_token"]
+
+
+# ---------------------------------------------------------------------------
+# Expired access token (GET /api/auth/me)
+# ---------------------------------------------------------------------------
+
+class TestExpiredAccessToken:
+    def test_expired_access_token_is_rejected_by_me(self):
+        """An access JWT with a past exp claim returns 401 on /me."""
+        client = TestClient(app)
+        expired_token = _mint_access_token(
+            datetime.now(timezone.utc) - timedelta(minutes=5)
+        )
+        resp = client.get(
+            "/api/auth/me",
+            headers={"Authorization": f"Bearer {expired_token}"},
+        )
+        assert resp.status_code == 401
+        assert "Could not validate credentials" in resp.json()["detail"]
+
+    def test_garbage_access_token_is_rejected_by_me(self):
+        """A non-JWT bearer token returns 401 on /me."""
+        client = TestClient(app)
+        resp = client.get(
+            "/api/auth/me",
+            headers={"Authorization": "Bearer not-a-real-jwt"},
+        )
+        assert resp.status_code == 401
+
+    def test_missing_bearer_token_returns_401(self):
+        """No Authorization header at all returns 401 on /me."""
+        client = TestClient(app)
+        resp = client.get("/api/auth/me")
+        assert resp.status_code == 401
+
+
+# ---------------------------------------------------------------------------
+# Expired refresh token (POST /api/auth/refresh)
+# ---------------------------------------------------------------------------
+
+class TestExpiredRefreshToken:
+    def test_expired_refresh_token_is_rejected(self):
+        """A refresh token whose DB expires_at is in the past returns 401."""
+        client = TestClient(app)
+        refresh_token = _register_user(client, "expired_rt_user")
+
+        # Force the persisted record to be expired while its JWT signature
+        # is still valid.
+        _expire_refresh_token_in_db(refresh_token)
+
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp.status_code == 401
+        assert "Invalid or expired refresh token" in resp.json()["detail"]
+
+    def test_expired_refresh_token_jwt_is_rejected(self):
+        """A refresh JWT with a past exp claim is rejected before DB lookup."""
+        client = TestClient(app)
+        expired_jwt = jwt.encode(
+            {"sub": "1", "exp": datetime.now(timezone.utc) - timedelta(minutes=5)},
+            settings.private_pem,
+            algorithm=settings.ALGORITHM,
+        )
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": expired_jwt},
+        )
+        assert resp.status_code == 401
+        assert "Invalid or expired refresh token" in resp.json()["detail"]

backend/tests/test_gltf_metadata.py

@@ -0,0 +1,220 @@
+"""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]")

backend/tests/test_refresh_endpoint.py

@@ -0,0 +1,201 @@
+"""Tests for the POST /api/auth/refresh endpoint.
+
+These tests exercise the full stack: register → get refresh token →
+refresh → new access token.  Requires migrations already applied
+(alembic upgrade head) before running.
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import settings
+from app.main import app
+from app.database import get_db
+
+
+# ---------------------------------------------------------------------------
+# Test fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def _override_db():
+    """Override get_db so the app uses a fresh session per test."""
+    test_engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+    test_session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
+
+    async def _get_db():
+        async_session = test_session_factory()
+        try:
+            yield async_session
+            await async_session.commit()
+        except Exception:
+            await async_session.rollback()
+            raise
+        finally:
+            await async_session.close()
+
+    app.dependency_overrides[get_db] = _get_db
+    yield
+    app.dependency_overrides.clear()
+
+
+# ---------------------------------------------------------------------------
+# Refresh endpoint tests
+# ---------------------------------------------------------------------------
+
+class TestRefresh:
+    """Tests for POST /api/auth/refresh."""
+
+    def _register_user(self, username: str, password: str, email: str = None):
+        """Helper to register a user and return the refresh token."""
+        client = TestClient(app)
+        if email is None:
+            email = f"{username}@example.com"
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": username,
+                "email": email,
+                "password": password,
+                "over_18": True,
+            },
+        )
+        assert resp.status_code == 201
+        return resp.json()["refresh_token"]
+
+    def test_refresh_success(self):
+        """A valid refresh token returns a new access token."""
+        refresh_token = self._register_user("refep_refreshuser", "secret123")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "access_token" in data
+        assert data["token_type"] == "bearer"
+        # The refresh token in the response is the same one we sent
+        assert data["refresh_token"] == refresh_token
+
+    def test_refresh_returns_different_access_token(self):
+        """Refreshing produces a new access token (different from any previous)."""
+        refresh_token = self._register_user("refep_refreshtoken", "secret123")
+        client = TestClient(app)
+
+        # First refresh
+        resp1 = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp1.status_code == 200
+        access_token_1 = resp1.json()["access_token"]
+
+        # Second refresh
+        resp2 = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp2.status_code == 200
+        access_token_2 = resp2.json()["access_token"]
+
+        # Each refresh should produce a new access token
+        assert access_token_1 != access_token_2
+
+    def test_refresh_invalid_token(self):
+        """An invalid (garbage) refresh token returns 401."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": "not.a.jwt.token"},
+        )
+        assert resp.status_code == 401
+        assert "Invalid or expired refresh token" in resp.json()["detail"]
+
+    def test_refresh_empty_body(self):
+        """Missing refresh_token field returns 422 validation error."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/refresh",
+            json={},
+        )
+        assert resp.status_code == 422
+
+    def test_refresh_missing_field(self):
+        """No body at all returns 422."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/refresh",
+            content="{}",
+            headers={"Content-Type": "application/json"},
+        )
+        assert resp.status_code == 422
+
+    def test_refresh_with_login_token(self):
+        """A refresh token obtained from login also works for /refresh."""
+        client = TestClient(app)
+        # Register first
+        client.post(
+            "/api/auth/register",
+            json={
+                "username": "refep_loginrefuser",
+                "email": "loginref@example.com",
+                "password": "secret123",
+                "over_18": True,
+            },
+        )
+        # Login to get a refresh token
+        login_resp = client.post(
+            "/api/auth/login",
+            data={"username": "refep_loginrefuser", "password": "secret123"},
+        )
+        assert login_resp.status_code == 200
+        refresh_token = login_resp.json()["refresh_token"]
+
+        # Use it to refresh
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp.status_code == 200
+        assert "access_token" in resp.json()
+
+    def test_refresh_access_token_is_valid_jwt(self):
+        """The access token returned by /refresh is a valid JWT."""
+        from jose import jwt
+
+        refresh_token = self._register_user("refep_jwttoken", "secret123")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp.status_code == 200
+        access_token = resp.json()["access_token"]
+
+        # Verify it's a 3-part JWT
+        parts = access_token.split(".")
+        assert len(parts) == 3
+
+        # Verify it decodes with the public key
+        payload = jwt.decode(
+            access_token,
+            settings.public_pem,
+            algorithms=[settings.ALGORITHM],
+        )
+        assert "sub" in payload
+        assert "exp" in payload
+
+    def test_refresh_expires_minutes_in_response(self):
+        """The response includes access_token_expires_minutes."""
+        refresh_token = self._register_user("refep_expiretest", "secret123")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp.status_code == 200
+        assert "access_token_expires_minutes" in resp.json()
+        assert resp.json()["access_token_expires_minutes"] == settings.ACCESS_TOKEN_EXPIRE_MINUTES

backend/tests/test_refresh_token_jti.py

@@ -0,0 +1,79 @@
+"""Tests for refresh token uniqueness (jti claim) and model column length."""
+
+import uuid
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from jose import jwt
+
+from app.config import settings
+from app.routers.auth import _create_refresh_token
+from app.models.session import RefreshToken
+
+
+class TestRefreshTokenJtiUniqueness:
+    """Verify that _create_refresh_token produces unique tokens even when
+    called with identical data in rapid succession (issue #1 from review)."""
+
+    def test_two_calls_produce_different_tokens(self):
+        """Two calls with the same sub produce different JWTs because of jti."""
+        token_a = _create_refresh_token({"sub": "42"})
+        token_b = _create_refresh_token({"sub": "42"})
+        assert token_a != token_b
+
+    def test_jti_is_valid_uuid(self):
+        """The jti claim inside the refresh token is a valid UUID."""
+        token = _create_refresh_token({"sub": "1"})
+        payload = jwt.decode(
+            token,
+            settings.public_pem,
+            algorithms=[settings.ALGORITHM],
+        )
+        assert "jti" in payload
+        # Verify it parses as a UUID (raises ValueError if not)
+        uuid.UUID(payload["jti"])
+
+    def test_each_token_has_unique_jti(self):
+        """Generate 100 tokens for the same user — all jtis must differ."""
+        jtis = set()
+        for _ in range(100):
+            token = _create_refresh_token({"sub": "999"})
+            payload = jwt.decode(
+                token,
+                settings.public_pem,
+                algorithms=[settings.ALGORITHM],
+            )
+            jtis.add(payload["jti"])
+        assert len(jtis) == 100
+
+    def test_jti_survives_decode(self):
+        """The jti claim is present and correct after decode."""
+        token = _create_refresh_token({"sub": "7"})
+        payload = jwt.decode(
+            token,
+            settings.public_pem,
+            algorithms=[settings.ALGORITHM],
+        )
+        assert payload["sub"] == "7"
+        assert "jti" in payload
+        assert "exp" in payload
+
+
+class TestRefreshTokenModelColumnLength:
+    """Verify the model's token column length matches the migration (issue #2)."""
+
+    def test_token_column_has_length_512(self):
+        """RefreshToken.token column should be String(512), not unbounded."""
+        from sqlalchemy import inspect
+
+        # Get the column definition from the model's table
+        column = RefreshToken.__table__.columns["token"]
+        # The type should be String with length 512
+        assert column.type.length == 512
+
+    def test_token_column_type_is_string(self):
+        """The token column should be a String type."""
+        from sqlalchemy import String as SAString
+
+        column = RefreshToken.__table__.columns["token"]
+        assert isinstance(column.type, SAString)

docs/architecture/avatar.md

@@ -0,0 +1,462 @@
+# Avatar Component System & glTF Attachment Spec
+
+> **Status:** Proposed
+> **Owner:** Platform team
+> **Related:** Server authority + client prediction, world chunk data format
+
+## 1. Overview
+
+This document specifies the **avatar component system** for **agp-game**, a
+Godot-based multiplayer game. It defines:
+
+- How an avatar is decomposed into **body parts** and **attachment slots**.
+- How **cosmetic attachments** (clothing, accessories, gear) mount onto the
+  base body.
+- The **glTF/GLB format requirements** that all avatar assets must satisfy so
+  they can be loaded, skinned, and networked consistently.
+
+The goal is a **modular, data-driven avatar pipeline**: a single base body rig
+plus swappable attachments, all authored in glTF and consumed by a shared Godot
+runtime. This enables player customization, cosmetic monetization, and
+server-authoritative validation of what a player is wearing.
+
+### 1.1 Design Goals
+
+- **Modularity:** Body parts and attachments are independent assets that can be
+  combined at runtime without re-exporting.
+- **Consistency:** A single, well-defined skeleton and slot convention so any
+  attachment fits any base body.
+- **Networkability:** The avatar's composition is expressed as a compact,
+  serializable **loadout** that the server can validate and replicate.
+- **Performance:** Attachments are skinned to the same skeleton and share
+  materials where possible to minimize draw calls and skinning cost.
+- **Tooling-friendly:** Assets are authored in standard glTF 2.0 and validated
+  by a build-time checker.
+
+---
+
+## 2. Avatar Decomposition
+
+### 2.1 The Base Body
+
+Every avatar is built on a **base body** — a single glTF asset containing:
+
+- A **skeleton** (the canonical rig, see §3).
+- A **base mesh** for the skin/body (head, torso, arms, legs).
+- **Attachment points** (empty nodes) that define where accessories mount.
+
+The base body is the only asset that carries the skeleton. Attachments reference
+the skeleton by **bone name** and are skinned to it; they never carry their own
+rig.
+
+### 2.2 Body Parts vs. Attachments
+
+Two distinct concepts:
+
+| Concept        | Definition                                                              | Example                          |
+|----------------|-------------------------------------------------------------------------|----------------------------------|
+| **Body part**  | A mesh that replaces part of the base body's skin (e.g., a different head, a tail, wings). | Alternate head, cybernetic arm |
+| **Attachment** | A mesh that mounts *on top of* the body without replacing it (clothing, accessories). | Shirt, hat, glasses, backpack |
+
+The distinction matters for **slot exclusivity** and **layering**:
+
+- **Body parts** are *exclusive* per slot — only one head can be equipped.
+- **Attachments** are *layered* — a hat and glasses can coexist, and both sit
+  above the head mesh.
+
+---
+
+## 3. Skeleton & Slot Convention
+
+### 3.1 Canonical Skeleton
+
+All avatars share a **canonical skeleton** with a fixed set of bone names. This
+is the contract that lets any attachment fit any body. The skeleton follows a
+humanoid convention (Godot's `Humanoid` profile / glTF VRM-style naming).
+
+Required bones (subset of the full rig):
+
+```
+Root
+├── Hips
+│   ├── Spine
+│   │   ├── Chest
+│   │   │   ├── Neck
+│   │   │   │   └── Head
+│   │   │   │       ├── HeadTop          # hat / hair mount
+│   │   │   │       ├── Jaw              # face accessories
+│   │   │   │       └── LeftEye / RightEye
+│   │   │   ├── LeftShoulder
+│   │   │   │   └── LeftUpperArm
+│   │   │   │       └── LeftLowerArm
+│   │   │   │           └── LeftHand
+│   │   │   └── RightShoulder
+│   │   │       └── RightUpperArm
+│   │   │           └── RightLowerArm
+│   │   │               └── RightHand
+│   │   └── (Chest children for torso attachments)
+│   ├── LeftUpperLeg
+│   │   └── LeftLowerLeg
+│   │       └── LeftFoot
+│   └── RightUpperLeg
+│       └── RightLowerLeg
+│           └── RightFoot
+```
+
+**Rules:**
+
+- Bone names are **case-sensitive** and must match exactly.
+- The skeleton is **T-pose** at rest for consistent skinning.
+- Attachments must be skinned to **at least** the bones they deform; static
+  accessories may be parented to a single bone (e.g., a hat parented to `Head`).
+
+### 3.2 Attachment Slots
+
+Slots are the **logical mount points** for body parts and attachments. Each slot
+maps to one or more bones and defines what can be equipped there.
+
+| Slot ID        | Category     | Mount bone(s)      | Exclusivity | Example assets                |
+|----------------|--------------|--------------------|-------------|-------------------------------|
+| `head`         | body part    | `Head`             | exclusive   | alternate head, face          |
+| `hair`         | attachment   | `HeadTop`          | exclusive   | hairstyles, hats              |
+| `face`         | attachment   | `Jaw`              | exclusive   | glasses, masks, beards        |
+| `torso`        | body part    | `Chest`            | exclusive   | alternate torso               |
+| `chest`        | attachment   | `Chest`            | exclusive   | shirts, armor, chest gear     |
+| `back`         | attachment   | `Chest` (back)     | exclusive   | backpacks, wings, capes       |
+| `left_arm`     | body part    | `LeftUpperArm`     | exclusive   | alternate arm                 |
+| `right_arm`    | body part    | `RightUpperArm`    | exclusive   | alternate arm                 |
+| `left_hand`    | attachment   | `LeftHand`         | exclusive   | gloves, weapons (held)        |
+| `right_hand`   | attachment   | `RightHand`        | exclusive   | gloves, weapons (held)        |
+| `legs`         | body part    | `Hips`             | exclusive   | alternate legs                |
+| `pants`        | attachment   | `Hips`             | exclusive   | pants, skirts                 |
+| `left_foot`    | attachment   | `LeftFoot`         | exclusive   | shoes                         |
+| `right_foot`   | attachment   | `RightFoot`        | exclusive   | shoes                         |
+| `accessory`    | attachment   | `Root` (free)      | multiple    | belts, jewelry, floating items|
+
+**Slot semantics:**
+
+- **`exclusive`** slots allow at most one equipped item at a time.
+- The **`accessory`** slot is *multi-slot* — multiple accessories may be equipped
+  simultaneously (bounded by a configurable limit, e.g., 8).
+- **Body-part slots** (`head`, `torso`, `legs`, `left_arm`, `right_arm`) replace
+  the corresponding base mesh. When a body part is equipped, the base mesh for
+  that region is hidden.
+- **Attachment slots** layer on top of the base mesh and never hide it.
+
+### 3.3 Slot → Bone Mapping
+
+Each slot declares a **primary mount bone** and an optional **secondary bone
+list** for skinning. The runtime uses this to:
+
+1. Parent static accessories to the mount bone.
+2. Skin skinned attachments to the union of the slot's bones.
+
+---
+
+## 4. glTF/GLB Format Requirements
+
+All avatar assets (base bodies, body parts, attachments) are distributed as
+**glTF 2.0** (`.gltf` + external buffers/textures) or **GLB** (`.glb`, binary
+container). GLB is the preferred distribution format for runtime loading.
+
+### 4.1 Required Conventions
+
+| Concern            | Requirement                                                                 |
+|--------------------|------------------------------------------------------------------------------|
+| **Format**         | glTF 2.0 (`.gltf` or `.glb`). GLB preferred for runtime.                     |
+| **Coordinate system** | glTF standard: **+Y up, +Z forward, right-handed**. Godot converts to its own convention on import. |
+| **Units**          | Meters. Avatar height ~1.8 m at the `Root` bone.                              |
+| **Skeleton**       | Single skeleton per asset; bone names per §3.1.                              |
+| **Skinning**       | `skins` + `nodes` with `JOINTS_0` / `WEIGHTS_0` accessors.                    |
+| **Pose**           | T-pose at rest.                                                              |
+| **Materials**      | PBR metallic-roughness. Use `KHR_materials_unlit` for emissive/UI-only items. |
+| **Textures**       | Max 2048×2048; power-of-two preferred. Use `KHR_texture_basisu` (BasisU) for runtime. |
+| **Animation**      | Optional. If present, must not rename or remove canonical bones.             |
+
+### 4.2 Asset Metadata (extras)
+
+Each asset **must** declare its slot and identity in the glTF `asset.extras`
+object. This is the machine-readable contract consumed by the build pipeline and
+runtime.
+
+```json
+{
+  "asset": {
+    "version": "2.0",
+    "extras": {
+      "agp": {
+        "type": "attachment",          // "base_body" | "body_part" | "attachment"
+        "slot": "chest",               // slot ID from §3.2
+        "id": "shirt_bandit_01",       // globally unique asset id
+        "display_name": "Bandit Shirt",
+        "version": "1.0.0",
+        "mount_bone": "Chest",         // primary mount bone
+        "skin_bones": ["Chest", "Spine", "LeftUpperArm", "RightUpperArm"],
+        "exclusive": true,             // matches slot exclusivity
+        "tags": ["cloth", "common"],
+        "author": "platform-team"
+      }
+    }
+  }
+}
+```
+
+**Validation rules for `extras.agp`:**
+
+- `type` must be one of `base_body`, `body_part`, `attachment`.
+- `slot` must be a known slot ID (§3.2).
+- `mount_bone` must exist in the canonical skeleton.
+- `skin_bones` must all exist in the canonical skeleton.
+- `exclusive` must match the slot's declared exclusivity.
+- `id` must be unique across the asset catalog.
+
+### 4.3 Node Naming Convention
+
+To make assets self-describing and mergeable, nodes follow a convention:
+
+- **Base body:** the mesh node is named `Body`; the skeleton root is `Root`.
+- **Body part:** the mesh node is named `<SlotID>_Mesh` (e.g., `head_Mesh`).
+- **Attachment:** the mesh node is named `<SlotID>_<AssetID>` (e.g.,
+  `chest_shirt_bandit_01`).
+- **Attachment points** (empty nodes) on the base body are named
+  `attach_<slot>` (e.g., `attach_head`, `attach_left_hand`).
+
+### 4.4 Material & Texture Requirements
+
+- All materials use the **metallic-roughness** PBR model.
+- Textures are embedded in the GLB or referenced as external files; external
+  references must be relative paths within the asset package.
+- **Color customization** is supported via a `baseColorFactor` tint applied at
+  runtime (multiplied over the albedo). Assets should use a neutral albedo
+  (white/gray) where tinting is intended.
+- **Masked/transparent** materials must set the correct alpha mode
+  (`MASK` or `BLEND`) and `alphaCutoff`.
+
+### 4.5 Skeleton Merging at Runtime
+
+When an attachment is loaded, the runtime **merges** it onto the base body:
+
+1. Load the base body (skeleton + base meshes).
+2. Load each equipped attachment.
+3. For each attachment, **re-target its skin** to the base body's skeleton by
+   bone name (no re-export needed).
+4. Parent static accessories to their `mount_bone`.
+5. Hide base meshes for any equipped body-part slots.
+6. Apply material tints and merge into the render tree.
+
+The merge is **name-based** — bone names must match exactly (§3.1). This is the
+core reason for the strict naming contract.
+
+---
+
+## 5. Loadout Model (Network & Persistence)
+
+The avatar's composition is serialized as a **loadout** — a compact, ordered
+list of equipped asset IDs. This is what the server validates, persists, and
+replicates.
+
+### 5.1 Loadout JSON
+
+```json
+{
+  "base_body": "base_human_male_01",
+  "slots": {
+    "head":   "head_cyber_01",
+    "hair":   "hair_mohawk_01",
+    "face":   null,
+    "torso":  null,
+    "chest":  "chest_bandit_01",
+    "back":   "backpack_01",
+    "left_arm":  null,
+    "right_arm": null,
+    "left_hand": "glove_leather_01",
+    "right_hand": "glove_leather_01",
+    "legs":   null,
+    "pants":  "pants_cargo_01",
+    "left_foot":  "shoe_boot_01",
+    "right_foot": "shoe_boot_01",
+    "accessory": ["belt_01", "necklace_01"]
+  }
+}
+```
+
+**Rules:**
+
+- `base_body` is required and must reference a valid `base_body` asset.
+- Each exclusive slot holds **at most one** asset id (or `null`).
+- `accessory` is an array (0..N, bounded).
+- The server validates that every id exists in the catalog and that slot
+  exclusivity is respected.
+
+### 5.2 Network Replication
+
+The loadout is replicated as part of the player's spawn/state data:
+
+```
+spawn_entity:
+  entity_id: uint32
+  type: player
+  transform: { x, y, rot }
+  props:
+    loadout_hash: uint32      # hash of the loadout for change detection
+    loadout: { ... }          # full loadout on spawn / on change
+```
+
+- The **full loadout** is sent on spawn and whenever it changes (reliable).
+- A **`loadout_hash`** lets clients skip re-resolving assets if unchanged.
+- The server is the **authority** on the loadout; clients send *requests* to
+  change equipment, and the server validates and broadcasts the result.
+
+### 5.3 Server-Side Validation
+
+The server rejects a loadout if:
+
+- `base_body` is missing or unknown.
+- Any slot references an unknown asset id.
+- An exclusive slot has more than one item.
+- An asset's declared `slot` does not match the slot it is placed in.
+- The accessory list exceeds the configured limit.
+- The asset is not owned/unlocked by the player (for gated cosmetics).
+
+---
+
+## 6. Godot Runtime Architecture
+
+### 6.1 Node Structure
+
+```
+Avatar (Node3D)
+├── Skeleton3D            # canonical skeleton (from base body)
+├── BodyMeshes            # base body meshes (skinned to Skeleton3D)
+│   ├── head_Mesh
+│   ├── torso_Mesh
+│   └── ...
+├── Attachments           # equipped attachments
+│   ├── chest_shirt_bandit_01
+│   ├── hair_mohawk_01
+│   └── ...
+└── AttachmentPoints      # empty nodes for dynamic mounting
+    ├── attach_head
+    ├── attach_left_hand
+    └── ...
+```
+
+### 6.2 Core Classes
+
+| Class                    | Responsibility                                              |
+|--------------------------|-------------------------------------------------------------|
+| `AvatarSystem`           | Loads base body + attachments, resolves loadouts, owns the avatar node. |
+| `AvatarLoader`           | glTF/GLB import, skeleton merge, skin re-targeting.          |
+| `AvatarSlotRegistry`     | Static registry of slot definitions (id, bones, exclusivity).|
+| `AvatarLoadout`          | Serializable loadout model + validation.                    |
+| `AvatarCatalog`          | Asset catalog (id → asset metadata + resource path).         |
+| `AvatarVisualizer`       | Builds the render tree from a loadout.                      |
+
+### 6.3 Loading Pipeline
+
+```
+loadout JSON
+   │
+   ▼
+AvatarCatalog.resolve(loadout)   # id → asset metadata + GLB path
+   │
+   ▼
+AvatarLoader.load_base_body()    # import GLB, extract skeleton + base meshes
+   │
+   ▼
+for each equipped slot:
+   AvatarLoader.load_attachment()# import GLB, re-target skin to skeleton
+   │
+   ▼
+AvatarVisualizer.assemble()      # parent, hide replaced parts, apply tints
+   │
+   ▼
+Avatar node ready for render
+```
+
+### 6.4 Performance Considerations
+
+- **Shared skeleton:** All meshes skin to one `Skeleton3D`, so skinning is
+  computed once per frame.
+- **Material batching:** Attachments that share a material are merged into a
+  single mesh where possible (static accessories).
+- **LOD:** Optional LOD variants per asset; the runtime selects based on
+  distance.
+- **Caching:** Resolved loadouts and imported GLB resources are cached by
+  `AvatarCatalog` to avoid re-importing on respawn or re-join.
+
+---
+
+## 7. Asset Pipeline & Validation
+
+### 7.1 Build-Time Validation
+
+A build-time checker validates every asset before it enters the catalog:
+
+1. **Format check:** valid glTF 2.0 / GLB.
+2. **Metadata check:** `extras.agp` present and valid (§4.2).
+3. **Skeleton check:** all `skin_bones` exist in the canonical skeleton.
+4. **Slot check:** `slot` is known and `exclusive` matches.
+5. **Mesh check:** meshes are skinned (or static accessories parented to a bone).
+6. **Texture check:** sizes, formats, and alpha modes are valid.
+7. **Uniqueness check:** `id` is unique.
+
+### 7.2 Catalog Manifest
+
+The catalog is a JSON manifest mapping asset ids to metadata and resource paths:
+
+```json
+{
+  "assets": {
+    "base_human_male_01": {
+      "type": "base_body",
+      "path": "res://assets/avatars/base_human_male_01.glb",
+      "version": "1.0.0"
+    },
+    "chest_bandit_01": {
+      "type": "attachment",
+      "slot": "chest",
+      "path": "res://assets/avatars/chest_bandit_01.glb",
+      "version": "1.0.0"
+    }
+  }
+}
+```
+
+---
+
+## 8. Security & Anti-Cheat
+
+- **Server-authoritative loadouts:** Clients only *request* equipment changes;
+  the server validates against the catalog and the player's owned items.
+- **No client asset injection:** Clients cannot send arbitrary GLB data; they
+  reference catalog ids only.
+- **Rate limiting:** Equipment-change requests are rate-limited per peer.
+- **Hash verification:** The `loadout_hash` lets the server detect tampered or
+  stale loadout state.
+
+---
+
+## 9. Open Questions / Future Work
+
+- **Morph targets / blendshapes:** Support for facial expressions and body
+  morphs (e.g., height, muscle) via glTF morph targets.
+- **Physics attachments:** Cloth simulation for capes/skirts (Godot cloth).
+- **Dynamic tinting UI:** A color-picker that writes `baseColorFactor` tints.
+- **VRM compatibility:** Consider supporting VRM (a glTF extension for
+  humanoid avatars) as an import source.
+- **Attachment LOD streaming:** Streaming high-res attachments on demand.
+
+---
+
+## 10. Summary
+
+| Concern                | Decision                                              |
+|------------------------|-------------------------------------------------------|
+| Format                 | glTF 2.0 / GLB (GLB preferred for runtime)            |
+| Skeleton               | Single canonical humanoid skeleton, name-based merge  |
+| Slots                  | Fixed slot registry; exclusive body parts + layered attachments |
+| Loadout                | Compact JSON; server-authoritative and validated      |
+| Replication            | Full loadout on spawn/change + `loadout_hash`         |
+| Runtime                | Godot `Skeleton3D` + name-based skin re-targeting     |
+| Validation             | Build-time asset checker + runtime catalog validation |

docs/architecture/editor.md

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

docs/architecture/networking.md

@@ -0,0 +1,286 @@
+# Multiplayer Networking Architecture
+
+> **Status:** Proposed
+> **Owner:** Platform team
+> **Related:** Server authority + client prediction
+
+## 1. Overview
+
+This document specifies the multiplayer networking architecture for **agp-game**,
+a Godot-based game built by autonomous agents. The architecture follows a
+**server-authoritative model with client-side prediction and reconciliation**,
+which is the industry standard for fast-paced, competitive multiplayer games.
+
+The goals of this architecture are:
+
+- **Fairness & anti-cheat:** The server is the single source of truth for all
+  gameplay state. Clients never directly mutate world state.
+- **Responsiveness:** Client-side prediction hides network latency so local input
+  feels immediate.
+- **Determinism:** The server runs a fixed-timestep simulation so that state is
+  reproducible and testable.
+- **Scalability:** A clear separation between transport, simulation, and
+  replication layers allows the server to be tuned independently.
+
+---
+
+## 2. Transport Choice: ENet over WebSocket
+
+### 2.1 Decision
+
+We choose **ENet** as the primary transport for gameplay traffic.
+
+### 2.2 Justification
+
+| Criterion            | ENet                                   | WebSocket (TCP)                     |
+|----------------------|----------------------------------------|-------------------------------------|
+| **Reliability model**| Reliable + unreliable channels         | Reliable only (TCP)                 |
+| **Latency**          | Low; unreliable packets skip retransmit| Head-of-line blocking on loss       |
+| **Packet ordering**  | Per-channel ordering                   | Global strict ordering              |
+| **Congestion control**| Lightweight, game-oriented            | TCP-style (slow start, backoff)     |
+| **Godot support**    | First-class (`ENetConnection`, `MultiplayerPeerENet`) | Supported but TCP-based |
+| **Use case fit**     | Real-time action game                  | Chat, lobby, HTTP-style messaging   |
+
+**Rationale:**
+
+- **Movement & state replication** are latency-sensitive and tolerate occasional
+  packet loss. ENet's *unreliable* channel lets us send position snapshots at high
+  frequency without head-of-line blocking.
+- **RPCs that must be delivered** (e.g., interactions, spawns) use ENet's
+  *reliable* channel, giving us exactly the semantics we need without TCP's
+  retransmission stalls.
+- Godot's `MultiplayerPeerENet` is mature and integrates directly with the
+  high-level multiplayer API (`MultiplayerAPI`, `rpc()`).
+
+### 2.3 WebSocket as a Secondary Transport
+
+WebSocket remains available as a **secondary transport** for:
+
+- **Lobby / matchmaking** messaging (low-frequency, must-be-reliable).
+- **Browser builds** where raw UDP/ENet is unavailable.
+- **Admin / telemetry** channels.
+
+The transport layer is abstracted behind an interface so gameplay code does not
+depend on the underlying protocol.
+
+---
+
+## 3. Server-Side Game Loop
+
+### 3.1 Tick Rate
+
+- **Simulation tick rate:** **30 Hz** (33.33 ms per tick).
+- **Replication / snapshot rate:** **30 Hz**, aligned with the simulation tick.
+
+**Justification:**
+
+- 30 Hz is sufficient for smooth movement and interaction in a top-down / 2D
+  action game while keeping CPU and bandwidth costs predictable.
+- A fixed timestep (rather than delta-time) makes the simulation deterministic
+  and testable.
+- The tick rate is a **configuration constant** so it can be raised (e.g., to
+  60 Hz) for competitive modes without architectural changes.
+
+### 3.2 Authority Model
+
+- **Server is authoritative** for:
+  - Player position, velocity, and physics state.
+  - Health, damage, and death.
+  - Item pickups, inventory, and world-object state.
+  - Spawning and despawning of entities.
+  - Game rules, scoring, and win/lose conditions.
+- **Client is authoritative** for:
+  - Its own *input* (which keys/buttons are pressed).
+  - Local camera and UI.
+  - Cosmetic / non-gameplay presentation.
+
+### 3.3 Server Loop Pseudocode
+
+```
+while server_running:
+    process_network_inbound()      # read client inputs & RPCs
+    for _ in range(ticks_to_advance):
+        simulate_tick()            # fixed 30 Hz step
+    broadcast_snapshots()          # replicate authoritative state
+    process_network_outbound()     # flush reliable/unreliable channels
+```
+
+The server accumulates real elapsed time and advances the simulation in fixed
+`TICK_DURATION` increments, decoupling simulation from frame rate.
+
+---
+
+## 4. RPC Call Patterns
+
+RPCs are grouped by direction and reliability. All gameplay RPCs are routed
+through the high-level `MultiplayerAPI` with explicit `rpc_id` targeting.
+
+### 4.1 Client → Server (Input & Requests)
+
+| RPC                          | Channel   | Payload                                   | Notes |
+|------------------------------|-----------|-------------------------------------------|-------|
+| `request_move_input`         | unreliable| `{ seq, input_state, timestamp }`         | Batched per tick; drives prediction |
+| `request_interact`           | reliable  | `{ target_id }`                           | Open door, pick up item, use object |
+| `request_attack`             | reliable  | `{ target_id, aim_dir }`                  | Combat action |
+| `request_join`               | reliable  | `{ player_name, profile }`                | Session setup |
+| `request_respawn`            | reliable  | `{}`                                      | After death |
+
+**Design notes:**
+
+- **Input is batched** per client tick and sent with a monotonically increasing
+  `seq` so the server can detect gaps and the client can reconcile.
+- **Interactions are reliable** because they are discrete, must-happen events
+  (opening a door, picking up an item). Losing them would corrupt world state.
+
+### 4.2 Server → Client (State & Events)
+
+| RPC                          | Channel   | Payload                                   | Notes |
+|------------------------------|-----------|-------------------------------------------|-------|
+| `snapshot_state`             | unreliable| `{ tick, entities[], player_states[] }`   | Periodic authoritative state |
+| `spawn_entity`               | reliable  | `{ entity_id, type, transform, props }`   | New entity enters world |
+| `despawn_entity`             | reliable  | `{ entity_id, reason }`                   | Entity removed |
+| `interact_result`            | reliable  | `{ request_seq, success, result }`        | Acknowledges interaction |
+| `damage_event`               | reliable  | `{ target_id, amount, source_id }`        | Combat feedback |
+| `game_event`                 | reliable  | `{ type, payload }`                       | Score, win, round start/end |
+
+### 4.3 Broadcast vs. Targeted
+
+- **Broadcast (all clients):** `snapshot_state`, `spawn_entity`,
+  `despawn_entity`, `game_event`.
+- **Targeted (single client):** `interact_result`, `damage_event` (to affected
+  players), and any player-private data.
+
+---
+
+## 5. Client-Side Prediction & Reconciliation
+
+### 5.1 Prediction
+
+- The client runs a **local copy of the movement simulation** using the same
+  physics constants as the server.
+- When the player provides input, the client:
+  1. Applies the input to its local player immediately.
+  2. Renders the predicted position.
+  3. Sends the input to the server (batched, with `seq`).
+
+### 5.2 Reconciliation
+
+- The server sends authoritative `snapshot_state` at 30 Hz containing the
+  server's tick number and authoritative player positions.
+- The client keeps a **ring buffer of predicted states** keyed by input `seq`.
+- On receiving a snapshot:
+  1. Find the last predicted state that matches the server's tick.
+  2. Compute the **error** between predicted and authoritative position.
+  3. If error exceeds a threshold, **snap or smoothly interpolate** the local
+     player to the authoritative position (error correction).
+  4. Re-simulate any inputs that occurred after the server's tick (rollback).
+
+### 5.3 Interpolation of Remote Entities
+
+- **Local player:** predicted + reconciled (see above).
+- **Remote players / entities:** rendered with **interpolation delay** of
+  `2 × TICK_DURATION` (≈ 66 ms) to smooth out snapshot jitter.
+- The client buffers the last N snapshots and interpolates between them.
+
+### 5.4 Prediction Buffer Sizing
+
+- Buffer size is adaptive based on measured RTT.
+- Default: hold up to `ceil(RTT / TICK_DURATION) + 2` predicted states.
+
+---
+
+## 6. Entity & World State Replication
+
+### 6.1 Entity Model
+
+Every networked entity has:
+
+- A globally unique `entity_id` (server-assigned).
+- An `EntityType` (player, enemy, item, projectile, door, ...).
+- A `Transform` (position, rotation).
+- A typed `props` dictionary of gameplay state (health, state machine, etc.).
+
+### 6.2 Snapshot Format
+
+```
+snapshot_state:
+  tick: uint32
+  entities:
+    - entity_id: uint32
+      type: uint8
+      transform: { x, y, rot }
+      props: { ... }        # delta-encoded where possible
+  player_states:
+    - peer_id: int
+      entity_id: uint32
+      health: int
+      state: uint8
+```
+
+### 6.3 Delta Compression
+
+- Only **changed** entity fields are sent per snapshot (dirty-flag per entity).
+- Static or unchanged entities are omitted from the snapshot.
+- This keeps bandwidth proportional to *activity*, not world size.
+
+---
+
+## 7. Connection & Session Lifecycle
+
+1. **Connect:** Client opens an ENet connection to the server.
+2. **Authenticate / Join:** Client sends `request_join`; server validates and
+   assigns a `peer_id` and spawns the player entity.
+3. **Spawn:** Server broadcasts `spawn_entity` for the new player to all clients.
+4. **Play:** Input → prediction → server simulation → snapshot → reconciliation.
+5. **Disconnect:** Server removes the player entity, broadcasts `despawn_entity`,
+   and cleans up session state.
+
+---
+
+## 8. Security & Anti-Cheat
+
+- **No client-authoritative gameplay values.** Clients only send *inputs* and
+  *requests*; the server computes all outcomes.
+- **Input validation:** Server clamps movement speed, rejects out-of-bounds
+  positions, and validates interaction targets.
+- **Rate limiting:** Per-peer input and RPC rate limits prevent flooding.
+- **Sequence validation:** Gaps or replays in input `seq` are detected and
+  rejected.
+
+---
+
+## 9. Testing & Determinism
+
+- The simulation is a **pure function of (state, inputs, tick)** so it can be
+  unit-tested headlessly.
+- A **replay system** records inputs and can re-simulate to verify server and
+  client produce identical results.
+- Network code is tested with a **mock transport** that can inject latency,
+  jitter, and packet loss.
+
+---
+
+## 10. Open Questions / Future Work
+
+- **Interest management / spatial partitioning:** For large worlds, restrict
+  snapshots to entities near each client (AOI culling).
+- **Server-side physics:** Decide whether to use Godot's physics server on the
+  host or a custom deterministic physics step.
+- **Dedicated server vs. listen server:** The architecture supports both; a
+  dedicated headless server is the target for production.
+- **WebSocket fallback:** Implement the transport abstraction for browser builds.
+
+---
+
+## 11. Summary
+
+| Concern                | Decision                                        |
+|------------------------|-------------------------------------------------|
+| Transport              | ENet (primary), WebSocket (secondary)           |
+| Tick rate              | 30 Hz fixed timestep                            |
+| Authority              | Server-authoritative; client sends input only   |
+| Prediction             | Client-side prediction + reconciliation         |
+| Remote interpolation   | 2-tick interpolation delay                      |
+| Replication            | Delta-compressed snapshots at 30 Hz             |
+| Interaction RPCs       | Reliable channel                                |
+| Movement input         | Unreliable channel, batched with sequence       |

docs/architecture/pc2_test_level.md

@@ -0,0 +1,194 @@
+# PC2 Test Level & Player Spawn — Design Note
+
+> **Status:** Decided (PC2)
+> **Owner:** Architecture
+> **Consumers:** the two PC2 implementation tasks — (1) build the test level,
+> (2) build the player & spawn it. Both must be able to follow this note
+> without further design decisions.
+
+## 1. Decision: static scene, not chunk streaming
+
+**The PC2 playable test level is a single, hand-authored, static Godot 3D
+scene.** It is **not** built through the chunk streaming system
+(`scripts/chunk_stream_manager.gd`, `chunk_scene.gd`, `chunk.gd`,
+`chunk_data_decoder.gd`).
+
+This is a deliberate decision, not a default:
+
+- **The streaming system has never been exercised with real content.** It is a
+  faithful port of the `docs/architecture/world.md` format spec, but nothing in
+  the project produces or serves chunk payloads for it to consume. `scenes/main.tscn`
+  wires `chunk_stream_manager.gd` onto a bare `Node3D` with no `player` reference
+  and no `_server_rpc`, so at runtime it does nothing. There is no server-side
+  chunk authoring/streaming endpoint to integrate against.
+- **PC2 scope is single-player, local-only, no networking.** The value of chunk
+  streaming is server-authoritative streaming around a moving player across a
+  network boundary. None of those preconditions exist in PC2, so exercising the
+  pipeline here would mean building a chunk *authoring + serving* path first —
+  clearly out of checkpoint scope.
+- **A static scene is the lowest-risk way to get "spawn a player in a real 3D
+  level and walk around" working**, which is the actual PC2 outcome being tested.
+
+Chunk streaming is **not removed and not broken by this decision** — it stays as
+an optional, later milestone. The static level is the PC2 proof of the *player*
+and *camera/physics* half of the problem; chunk streaming remains the later proof
+of the *world data* half.
+
+## 2. Where things live
+
+| Artifact | Path | Owned by |
+|---|---|---|
+| Test level scene | `scenes/worlds/test_level.tscn` | level task |
+| Player scene | `scenes/player.tscn` | player task |
+| Player controller script | `scripts/player.gd` | player task |
+| Game composition scene | `scenes/game.tscn` | player task |
+
+- **`scenes/worlds/`** is the convention for all level scenes (it does not exist
+  yet; the level task creates it). Future levels follow `scenes/worlds/<name>.tscn`.
+- `scenes/player.tscn` is **reusable** across levels — it must not hard-code any
+  reference to `test_level`; it discovers the spawn point at runtime (see §3).
+
+## 3. Player spawn convention
+
+The level scene **must** contain a `Marker3D` named exactly **`PlayerSpawn`**.
+That node's world transform is the spawn point.
+
+- `Marker3D` is a plain `Node3D` that shows a cross gizmo in the editor and
+  carries no gameplay behavior — it is the established Godot idiom for "position
+  hint." (Confirmed present in Godot 4.6.2.)
+- The marker's **position** is authoritative; its rotation is ignored by the
+  player (spawn yaw is the player's concern, default forward is fine).
+- Coordinate system: **Y-up, units = meters, 1 unit = 1 m.** The marker must sit
+  at least **1.0 m above the ground's top surface** (recommended `y = 1.0` where
+  the ground top is `y = 0`) so the player capsule does not spawn intersecting
+  the floor and get popped out by the physics solver.
+- There is exactly **one** `PlayerSpawn` per level. (If a level ever needs
+  multiple spawns, that is a later convention — not PC2.)
+
+**Lookup rule (implemented by `player.gd`, not by the level):**
+
+```
+# in player.gd _ready()
+var spawn := get_tree().current_scene.find_child("PlayerSpawn", true, false)
+if spawn is Node3D:
+    global_position = spawn.global_position
+else:
+    push_warning("player.gd: no PlayerSpawn marker found; spawning at origin")
+    global_position = Vector3(0, 1.0, 0)   # fallback, do not crash
+```
+
+The lookup runs from the current scene root so it finds the marker whether it is
+a direct child of the level instance or nested under a `Level` wrapper. The
+fallback keeps the player runnable in a scene that forgot its marker, but a
+**missing `PlayerSpawn` is a level bug** and the level task's smoke test must fail
+on it (see §6).
+
+## 4. Composition (who puts level + player together)
+
+`scenes/game.tscn` is the PC2 playable entry point:
+
+```
+Game (Node3D)
+├── Level      (instance of res://scenes/worlds/test_level.tscn)
+└── Player     (instance of res://scenes/player.tscn)
+```
+
+- `Game` is a plain `Node3D` with **no script** — composition is done by scene
+  instantiation, not code, so there is nothing to keep in sync.
+- The **level scene is self-contained and has zero dependency on the player** —
+  it loads and is smoke-testable on its own. The level task does not instance or
+  reference `player.tscn`.
+- The **player scene is self-contained and has zero dependency on any specific
+  level** — it only requires that the *current scene* contains a `PlayerSpawn`.
+- Ownership of `game.tscn` goes to the **player task**, which depends on the
+  level task having landed `test_level.tscn` first (chain with `depends_on`).
+
+## 5. Level content requirements (level task)
+
+`scenes/worlds/test_level.tscn`, root node `TestLevel` (`Node3D`). Required
+children:
+
+| Node | Type | Notes |
+|---|---|---|
+| `Ground` | `StaticBody3D` | `BoxShape3D` (e.g. `40 × 1 × 40`) centered at `(0, -0.5, 0)` so the **top face is `y = 0`**; matching `MeshInstance3D` (`BoxMesh`) so it is visible and collidable. Use a `StaticBody3D` rather than a bare `PlaneMesh` so collision is explicit and reliable. |
+| `Props` | `Node3D` | 3–5 simple props as `StaticBody3D` + `MeshInstance3D` using built-in primitives only (`BoxMesh`, `CylinderMesh`, `SphereMesh`). `assets/` is empty and PC2 must not require imported content. Positioned on the ground surface; scale freely. |
+| `Sun` | `DirectionalLight3D` | Pitch it downward (~ -45°), enable shadows if the compatibility renderer allows; shadows are optional. |
+| `WorldEnvironment` | `WorldEnvironment` | Ambient light and/or a simple background color. Keep it plain — the project uses `gl_compatibility`. |
+| `PlayerSpawn` | `Marker3D` | Per §3. Recommended `(0, 1.0, 0)`. |
+
+Notes:
+
+- **Do not** add any `script` to the level. It is pure content. Any per-level
+  behavior belongs to the player (or a future game-mode script), not the level.
+- Keep the whole level on the XZ plane around the origin; nothing off at extreme
+  coordinates, no thin walls the capsule can tunnel through.
+
+## 6. Player contract (player task)
+
+`scenes/player.tscn`, root `Player` (`CharacterBody3D`) + `scripts/player.gd`.
+
+Minimum for PC2:
+
+- **Body:** `CharacterBody3D` with a `CollisionShape3D` using `CapsuleShape3D`
+  (~`radius 0.3`, ~`height 1.8`) and a matching `CapsuleMesh` for visibility.
+- **Camera:** a `Camera3D` child. First-person (camera at capsule head height) is
+  the lowest-risk choice; third-person is fine too but is more work.
+- **Spawn:** per §3 — read `PlayerSpawn` from the current scene, fall back
+  gracefully.
+- **Movement:** gravity + `move_and_slide()` so the player stands on `Ground`.
+  WASD/arrow locomotion is the hard requirement. Mouse-look is recommended but
+  may be split into its own task if the controller grows.
+- **No networking, no avatar UI, no chunk code** — PC2 is local-only. Do not add
+  `MultiplayerAPI`, `ChunkStreamManager`, or any avatar customization here.
+
+The player must work when instanced under `Game` alongside a level; it must not
+assume it is the only node in the scene.
+
+## 7. Entry point / how a human plays it
+
+- `scenes/game.tscn` is the PC2 playable scene. For playtesting, load it directly
+  (e.g. `godot --path . scenes/game.tscn`), or temporarily set
+  `application/run/main_scene` to it.
+- **Wiring "Play → Join a world" in the existing `world_list` UI is out of scope
+  for this note** and out of scope for the level/player tasks. The current menu
+  flow ends at browse-worlds (PC1). If a checkpoint wants a clickable path into
+  the test level, that navigation wiring is its own small task — do not fold it
+  into level or player.
+
+## 8. Validation (both tasks must run this before "done")
+
+```sh
+# one-time, first checkout only — builds the class/import cache
+godot --headless --path . --import
+
+# then, to catch parse/load errors:
+godot --headless --path . --quit
+```
+
+- **Level task:** additionally load `test_level.tscn` headlessly and assert it
+  (a) loads without error and (b) contains a `Marker3D` named `PlayerSpawn`
+  positioned ≥ 1.0 m above the ground top. A smoke script following the existing
+  `scripts/smoke_test_*.gd` pattern is the right vehicle.
+- **Player task:** a smoke test that instantiates `game.tscn`, waits a frame,
+  and asserts the player's global position equals the `PlayerSpawn` position
+  (within a small epsilon). This is the check that proves the spawn convention
+  actually wired through — not just "the scene loads."
+
+## 9. Explicitly out of scope for PC2
+
+- Networking / multiplayer / prediction (single-player, local-only).
+- Chunk streaming integration and server-side chunk authoring/serving.
+- Avatar customization UI and glTF avatar loading.
+- Join-a-world navigation from the world list.
+- Any content moderation / age-gating logic in the level.
+
+## 10. Summary
+
+| Concern | Decision |
+|---|---|
+| Level construction | Static hand-authored Godot 3D scene (chunk streaming deferred, not removed) |
+| Level location | `scenes/worlds/test_level.tscn` |
+| Spawn convention | `Marker3D` named `PlayerSpawn`, ≥ 1.0 m above ground, looked up by the player |
+| Player | `scenes/player.tscn` (`CharacterBody3D`) + `scripts/player.gd`, reusable across levels |
+| Composition | `scenes/game.tscn` instances `Level` + `Player`; no script |
+| Entry point | Load `scenes/game.tscn` directly; UI join-wiring deferred |

docs/architecture/scripting_sandbox.md

@@ -0,0 +1,159 @@
+# GDScript Sandboxing for User-Written Scripts
+
+> **Status:** Proposed
+> **Owner:** Platform team
+> **Related:** Content moderation & age verification (scripts are one of the
+> three moderated content types), avatar component system
+
+## 1. Overview
+
+This document evaluates how to safely run **user-written scripts** as part of
+UGC (user-generated content) in **agp-game**, and recommends an approach.
+
+**Bottom line: Godot 4 has no built-in security sandbox for GDScript, and
+none of the three options named in the original task hold up under testing.**
+A script running anywhere inside the Godot process — however it's loaded,
+parented, or wrapped — runs with full engine privileges: arbitrary process
+execution, full filesystem read/write, and raw network access. Sandboxing
+has to happen *outside* the scripting language, not through an in-engine
+restriction mechanism, because no such mechanism exists.
+
+This was verified directly against Godot 4.6.2 (`godot --headless`, evidence
+in `sandbox_probe/` on this branch) rather than assumed from documentation,
+some of which (see §2.1) describes APIs that don't actually exist in this
+version.
+
+## 2. Options Evaluated
+
+### 2.1 Godot's built-in "ScriptServer" restrictions — does not exist
+
+There is no `ScriptServer` class in Godot 4.6.2:
+
+```
+ClassDB.class_exists("ScriptServer")  →  false
+```
+
+There's also no project setting to disable engine subsystems for scripts —
+none of `application/run/disable_os`, `disable_file_access`, or
+`disable_network` exist as settings, and `ProjectSettings.get_property_list()`
+returns nothing matching "sandbox", "restrict", or "security". Any plan that
+assumes a flag like this exists needs to be dropped; it was likely conflated
+with sandboxing features from a different engine/scripting ecosystem, or
+with **export template stripping** (which controls what ships in a build,
+not what a script can call at runtime).
+
+Directly probed capabilities of an ordinary GDScript running as a normal
+node script, no special setup:
+
+| Capability | Available to any script? |
+|---|---|
+| `OS.execute(...)` — run arbitrary processes | ✅ Yes |
+| `FileAccess.open(...)` — read/write any path the OS user can reach | ✅ Yes (read `/etc/hostname`, write `/tmp/...` both succeeded) |
+| `TCPServer` / `HTTPClient` / `HTTPRequest` / `PacketPeerUDP` / `WebSocketPeer` | ✅ All instantiate and work |
+| `ClassDB.instantiate(...)` — construct any engine class by name | ✅ Yes |
+| Loading and running a second script from source text at runtime (`GDScript.new()` + `.reload()`) | ✅ Yes |
+
+**Verdict: rejected.** There is nothing to configure here — the restriction
+surface this option assumed doesn't exist in the engine.
+
+### 2.2 Isolated SubViewport with a limited API — doesn't isolate scripts
+
+`SubViewport` is a **rendering and input isolation** primitive (it gives a
+scene subtree its own render target and can gate input propagation) — it is
+not a security or scripting boundary. A script attached to any node inside a
+`SubViewport` still runs in the same process, on the same GDScript VM, with
+the exact same access to `OS`, `FileAccess`, networking classes, and
+`ClassDB` as a script anywhere else in the tree. Nothing about being
+"inside" a SubViewport changes what API calls are reachable from a script.
+
+**Verdict: rejected.** This solves a rendering/UI-composition problem, not
+the security problem the task is asking about. Worth keeping in mind for
+other purposes (e.g. isolated preview rendering of user avatars), but it
+provides zero script sandboxing.
+
+### 2.3 Custom GDScript interpreter with an allowlist — right idea, wrong layer for "custom interpreter"
+
+Two ways to read this option, tested separately:
+
+**(a) Write/embed a separate GDScript parser+interpreter.** Not
+practical — this means re-implementing (and then indefinitely maintaining,
+in lockstep with every Godot release) a full language interpreter outside
+the engine. Far more engineering than the problem justifies.
+
+**(b) Use Godot's built-in `Expression` class as a restricted subset.**
+`Expression` *looks* like a natural allowlist mechanism — it only evaluates
+a single expression, no control flow, no arbitrary statements. But it isn't
+safe by default: it can still reach through to unsafe engine methods if you
+aren't careful about what object you hand it as a base instance:
+
+```gdscript
+var expr = Expression.new()
+expr.parse("get_environment('HOME')", ["OS"])
+expr.execute([], OS)   # → "/home/daddy"  (successfully called OS.get_environment)
+```
+
+So `Expression` is a viable building block only if the host **never passes
+a base instance (or arguments) that exposes anything sensitive** — i.e. the
+allowlisting work still has to happen at the call site, `Expression` itself
+enforces none of it.
+
+**Static text pattern-matching (blocklisting dangerous substrings like
+`"OS.execute"` before parsing) was also probed and is not a real
+defense** — it's trivially defeated by string concatenation, `call()`,
+`Callable`, or any other indirection, and produces false confidence.
+
+**Verdict: partially viable, but only as a foundation, not a solution on
+its own.** A hand-built, narrow, data-driven DSL (not full GDScript, not
+raw `Expression`) with an explicit allowlist of safe operations and *no
+ability to reference engine singletons or arbitrary objects* is the only
+version of "custom interpreter" that's actually safe. This is real
+engineering effort, not a config flag.
+
+## 3. Recommendation
+
+**Don't run untrusted GDScript in-process at all.** Given none of the three
+in-engine options provide a real boundary, the two approaches actually worth
+building are, in order of recommended priority:
+
+1. **Primary: a narrow, non-Turing-complete content DSL**, not general
+   scripting. Most UGC scripting needs in a game like this (custom
+   interactions, simple triggers, item behaviors) don't need a general
+   programming language — they need a small set of declarative
+   verbs/conditions (e.g. `on_interact: give_item("torch")`,
+   `on_enter: play_sound("chime")`). Expressed as data (JSON/Resource, not
+   code) and interpreted by trusted, hand-written GDScript on the engine
+   side. This has *zero* attack surface by construction — there's no
+   interpreter to escape because there's no general execution, just a
+   fixed, reviewed set of verbs. This is almost certainly sufficient for
+   the actual UGC use cases in this game and should be scoped against real
+   feature requirements before assuming more is needed.
+
+2. **If genuinely general scripting becomes a hard requirement**, isolate it
+   at the OS level, not the engine level: run untrusted scripts in a
+   **separate process** (a stripped-down Godot instance or a dedicated
+   interpreter) under OS sandboxing (a restricted user account, a
+   container, or `firejail`/`bwrap`/seccomp), communicating with the main
+   game over a narrow IPC/RPC boundary that only exposes intentionally-safe
+   operations. This is the only approach that provides a real security
+   boundary for arbitrary code, because it doesn't depend on the scripting
+   language cooperating — the OS enforces it. Substantially more
+   infrastructure than option 1; only worth it if option 1's DSL genuinely
+   can't express what's needed.
+
+**Do not** attempt in-process GDScript sandboxing via SubViewport,
+ScriptServer, or ad hoc blocklisting — all three were directly tested and
+none provide a real boundary (§2).
+
+## 4. Open Questions
+
+- What do actual planned UGC scripts need to *do*? (Trigger conditions,
+  simple item/state effects, dialogue branching?) This determines whether
+  the DSL in §3.1 is sufficient or whether §3.2's process isolation is
+  needed. Needs a concrete feature list before implementation starts.
+- If §3.2 is needed later, does it run per-user-session or shared/pooled?
+  Affects resource cost and isolation guarantees.
+- Interaction with the content moderation pipeline (`content_moderation.md`):
+  scripts as a moderated content type still need a moderation flag path
+  regardless of which execution model is chosen — a DSL makes static
+  analysis of *what a script can possibly do* far easier than it would be
+  for general code, which is an additional point in its favor.

docs/architecture/world.md

@@ -0,0 +1,737 @@
+# 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.

docs/checkpoints/PC1.md

@@ -0,0 +1,72 @@
+# Package Checkpoint 1 (PC1)
+
+Validated 2026-08-20 against `main` commit `927f9bd`, from a genuinely fresh
+clone (not a reused agent workspace).
+
+## Automated validation
+
+Run with `scripts/run_checkpoint_tests.py` — see
+`docs/testing/test_inventory.md` for exactly what each suite covers.
+
+| Check | Result |
+|---|---|
+| Alembic migrations, fresh DB | PASS |
+| Backend pytest | 68/68 PASS |
+| Godot smoke tests (4 files) | ALL PASS |
+| Linux export (`agp-game.x86_64`) | Builds, verified as a real ELF64 binary |
+| Windows export (`agp-game.exe`) | Builds, verified as a real PE32+ binary |
+
+## Problems found during this checkpoint (fixed, tracked as tasks)
+
+- Roadmap showed the Godot Engine Scaffold feature amber despite 6/6 tasks
+  done — a historical data gap (a review-feedback follow-up task's
+  supersession link was never recorded, predating when that field started
+  being tracked). Backfilled in the PM database; confirmed green.
+- `docs/testing/test_inventory.md` was stale (said 38 backend tests,
+  actually 68; said no integration tests existed, 4 real ones had landed).
+  Fixed via task `398bf1a22a2d` / PR #40.
+
+## What's actually testable right now
+
+Login/register/browse-worlds only — there's no joinable gameplay yet. That's
+the real scope of PC1; don't expect more when playtesting.
+
+- Register a new account (18+ only, rejected otherwise)
+- Log out, log back in with the same credentials
+- Play → Browse Worlds — loads a (currently empty) world list with no errors
+
+## Manual playtest: backend on cloudbison, client on pinkbison
+
+As of 2026-08-20 this is dashboard-controlled — no terminal commands, no
+env vars, no editing files. Foolproof enough to hand to someone else.
+
+### 1. On cloudbison — the AGP dashboard
+
+Open the dashboard (`http://cloudbison:7070`, or its Tailscale address) and
+go to **PC1** in the nav bar (`/checkpoint/PC1`). Click **Start Backend** —
+it pulls the latest `main`, stands up Postgres, runs migrations, and starts
+the API server, all in one step. The page shows the LAN address it's
+reachable at once it's up (under a minute).
+
+When you're done playtesting, click **Stop & Clean Up** on the same page —
+it tears down everything that step started (API server, Postgres
+container, its volume and network). Nothing is left running or lying
+around afterward, even if the dashboard itself gets restarted in between.
+
+### 2. On pinkbison — download and run the .exe
+
+Same dashboard page: click **Build .exe** the first time (or **Rebuild** to
+pick up newer changes) — this pulls the latest `main` and exports a Windows
+binary with cloudbison's backend address already baked in. Click
+**Download agp-game.exe**, copy it to pinkbison, and just run it. No
+environment variable, no config file, no build step on pinkbison at all.
+
+### 3. Tear down when done
+
+**Stop & Clean Up** on the dashboard page. That's it.
+
+## Status
+
+`config/checkpoint_focus_feature_ids` in the AGP framework (`~/agp`) still
+restricts agent claiming to the 5 PC1-scope features. Agents will not move
+on to post-PC1 work until that's widened.

docs/planning/client-server-wiring.md

@@ -0,0 +1,41 @@
+# MVP Vertical Slice: Client-Server Wiring — Plan
+
+## Goal
+Prove the real Godot client and the real backend can talk: **a user can register/log in
+and see a list of worlds from the game client**. Nothing more. Gameplay, join-a-world,
+chat, avatar, Discovery search/tags/trending, Social/Economy/Trust & Safety are all
+explicitly out of scope.
+
+## Verified backend contract (as of this writing)
+- `POST /api/auth/register` — JSON body `{username, email, password, date_of_birth}`.
+  `date_of_birth` is a `YYYY-MM-DD` string. Returns `201 {access_token, token_type}`.
+  Rejects under-18 with `400`.
+- `POST /api/auth/login` — OAuth2 **form-encoded** (`application/x-www-form-urlencoded`)
+  `username` + `password` (this is NOT a JSON endpoint). Returns `{access_token, token_type}`.
+- `GET /api/worlds` — **requires auth** (`CurrentUser`), returns a JSON array of
+  `{id, name, description, visibility, owner_id, created_at}`. There is no unauthenticated
+  public-worlds path, so the worlds list screen can only be shown after login/register.
+- `GET /api/health` — unauthenticated, `{status, app}`.
+- Base URL: uvicorn default `http://127.0.0.1:8000` (must be configurable in the client).
+- CORS is irrelevant to the native Godot `HTTPRequest` client (no browser origin).
+
+## Task breakdown
+| # | 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 |
+
+## Design decisions captured (resolved in task 1)
+- Token storage: in-memory singleton property for the MVP; a `save_to_disk` seam is left
+  open but not required yet (no re-login on restart in this slice).
+- Error contract: every call returns a discriminated result (`ok`/`error`) so callers
+  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/economy.md

@@ -0,0 +1,295 @@
+# Economy — Currency, Marketplace & Creator Payouts — Plan
+
+> **Status:** Planned
+> **Owner:** Platform team
+> **Feature ID:** `economy`
+> **Godot version:** 4.6.2 stable
+> **Backend:** FastAPI + SQLAlchemy (async) + PostgreSQL + Redis
+
+## 1. Overview
+
+This document breaks the **Economy** feature into user stories and right-sized
+implementation tasks. The feature delivers:
+
+- **Virtual currency ("Credits")** — a single, server-authoritative currency
+  with an immutable, append-only transaction ledger.
+- **Premium purchase** — buying Credits with real money through a pluggable
+  payment-provider hook.
+- **Marketplace** — user-generated content (UGC) listings where creators sell
+  items (assets, avatar items, experience passes) to players for Credits.
+- **Creator payouts** — accumulating creator earnings and paying them out to
+  external accounts through a pluggable payout-provider hook.
+- **Godot client** — wallet/transaction history, marketplace browse/buy/sell,
+  and creator payout screens.
+
+The economy is the monetization backbone of the platform. Because it moves
+virtual value between real people, correctness (no double-spend, no lost funds,
+no balance drift) and safety (fraud prevention, moderation, audit) are treated
+as **blocking requirements**, not add-ons.
+
+## 2. Why correctness is the differentiator
+
+The platform is a creator economy (players buy UGC from other players). The
+economy is the highest-risk surface after chat: a single arithmetic or
+concurrency bug can mint or destroy value and irreversibly erode trust.
+Correctness is therefore designed in from the start:
+
+- **One currency, integer units.** Credits are whole-number integers. There are
+  no floats, no rounding, and no client-computed totals.
+- **Append-only ledger.** Every balance change is a row in a `transactions`
+  table with a signed amount, a `balance_after` snapshot, a reference to the
+  event that caused it, and an **idempotency key** so retries cannot double
+  credit or double debit.
+- **Atomic, locked mutations.** Balance changes run in a single database
+  transaction with row locking (`SELECT ... FOR UPDATE`) so concurrent
+  purchases/payouts cannot race.
+- **Escrow hold.** Marketplace proceeds are held in `pending_escrow` for a
+  configurable window before becoming available to the seller, so fraudulent
+  or moderated sales can be reversed without clawing back paid-out funds.
+- **Server-authoritative fees.** The platform commission is computed
+  server-side from a configured rate; the client never supplies the fee or the
+  seller's net.
+
+## 3. Existing constraints (do not re-build)
+
+- **Auth:** JWT bearer tokens; `get_current_user` / `CurrentUser` dependency in
+  `app/dependencies.py`. All economy endpoints reuse this.
+- **DB:** async SQLAlchemy + Alembic; migration `0001_initial` is the head.
+  Existing tables: `users`, `sessions`, `worlds`, `assets`.
+- **Redis:** configured (`REDIS_URL`) but unused so far; adopted here for
+  idempotency short-caching and rate limiting.
+- **Models:** `User` (owner_id), `Asset` (owner_id, is_public, asset_type).
+  Marketplace items reference existing `assets` rows and/or avatar items.
+- **Content moderation:** `docs/architecture/content_moderation.md` defines
+  flag vocabulary, age gate, and moderation actions. Marketplace items and
+  listings must inherit and enforce these rules (see §7).
+- **Client:** Godot 4.6.2, minimal `main_menu.gd`; no economy UI yet.
+
+## 4. Key design decisions
+
+| Concern | Decision |
+|---|---|
+| Currency model | Single virtual currency **"Credits" (CR)**, integer units. One wallet row per user; no fractional amounts. |
+| Ledger | Append-only `transactions` table: signed `amount`, `balance_after`, `reference_type`/`reference_id`, unique `idempotency_key`. |
+| Concurrency | `SELECT ... FOR UPDATE` on the wallet row inside the mutation transaction; never read-modify-write from stale data. |
+| Payments | Pluggable `PaymentProvider` interface with a **no-op default** that simulates a confirmed payment for dev/testing (clearly flagged). Stripe/PayPal later. |
+| Marketplace items | `catalog_items` (what is sold) + `marketplace_listings` (a seller's offer with a price/status). One item can have multiple listings over time. |
+| Purchase flow | Atomic transaction: debit buyer → hold funds in escrow (`pending_escrow`) → grant item. Platform fee computed server-side. |
+| Escrow | Configurable hold window (default 72h) before `pending_escrow` becomes available seller earnings. Refunds during the window reverse the sale. |
+| Fees | Single configurable `MARKETPLACE_FEE_RATE` (default `0.30`). `seller_net = floor(price * (1 - fee_rate))`. |
+| Creator balance | `creator_balances` table: `available` (earned, payable), `pending` (inside an open payout request), `lifetime_earned`. Updated in the same transaction as the sale completion. |
+| Payouts | Pluggable `PayoutProvider.pay()` with a no-op default (simulated external ref). Minimum payout threshold, admin review for large payouts. |
+| Idempotency | Every money-moving request carries a client-generated `Idempotency-Key`; duplicate keys return the original result. |
+| Rate limiting | Redis token-bucket dependency reused from the social feature for purchase/listing/payout endpoints. |
+| Moderation | Listings enforce content flags + age gate; moderators can `delist`/`remove`; fraud/chargeback reversal is an audited admin action. |
+
+## 5. User stories
+
+### US-1 Currency & wallet
+As a player, I can see my Credit balance and transaction history, and the system
+credits/debits my wallet only through server-authoritative events.
+
+**Acceptance criteria**
+- Exactly one wallet per user, created lazily on first use.
+- Balance is always a non-negative integer; no operation can make it negative.
+- Every mutation appends an immutable ledger row with amount, resulting balance,
+  reference, and idempotency key.
+- Retrying a request with the same idempotency key does not double-apply.
+- `GET` endpoints expose current balance and paged transaction history.
+
+### US-2 Premium purchase (buy Credits)
+As a player, I can purchase Credits with real money and have them credited only
+after the payment is confirmed.
+
+**Acceptance criteria**
+- A purchase session is created through the payment provider (or the no-op
+  default) and is idempotent.
+- Credits are granted exactly once, only after a verified provider confirmation
+  (webhook/confirm endpoint), never on client claim.
+- Purchase amounts are bounded and server-defined; clients cannot pick arbitrary
+  prices.
+- Confirmation is idempotent and audited (provider reference recorded).
+
+### US-3 Marketplace listing (sell)
+As a creator, I can list a catalog item for sale at a Credit price and
+manage/remove my listings.
+
+**Acceptance criteria**
+- A listing references a valid `catalog_item` owned by the seller (or an
+  authorized seller).
+- Price is bounded (min/max) and set server-side; status transitions are
+  explicit (`active`, `sold`, `delisted`, `removed_by_moderation`).
+- Only the seller (or a moderator) can update/remove a listing.
+- Listings are searchable/filterable (item type, price range, owner).
+
+### US-4 Marketplace purchase (buy)
+As a player, I can buy a listed item. The purchase is atomic, holds funds in
+escrow, grants the item, and splits the payment between platform and seller.
+
+**Acceptance criteria**
+- A single transaction debits the buyer, holds funds in escrow, and grants the
+  item — no partial states on failure.
+- Platform fee and seller net are computed server-side from the configured rate.
+- After the escrow hold window, funds move from escrow to the seller's
+  available balance.
+- Refunds during the hold window reverse the sale and return funds to the buyer.
+- Concurrent purchases of a one-of-a-kind listing cannot both succeed.
+
+### US-5 Creator payouts
+As a creator, I can view my earned balance, request a payout, and track its
+status; admins can review and approve/reject payouts.
+
+**Acceptance criteria**
+- Available balance is derived only from completed (escrow-released) sales and
+  completed payouts; it never goes negative.
+- Payout requests are bounded (min threshold, max per period) and rate-limited.
+- Large payouts require admin review; all payout requests carry an audit trail
+  (requested by, reviewed by, provider reference, status).
+- The payout provider is called exactly once; idempotent on retry.
+
+### US-6 Godot client
+As a player, I can manage Credits, browse/buy/sell marketplace items, and manage
+payouts from the game UI.
+
+**Acceptance criteria**
+- An API client handles JWT auth, HTTP, and idempotency keys for all economy
+  calls.
+- Dedicated screens: wallet + transaction history, marketplace browse/buy,
+  sell-listing, and creator payout.
+- The client never computes balances, fees, or seller nets — it only displays
+  server responses.
+
+## 6. Task breakdown
+
+Right-sized to 1–3 files / one coherent piece of functionality each. Task IDs
+are sequential for dependency chaining.
+
+| # | Task | Story | Depends on |
+|---|------|-------|-----------|
+| 1 | Wallet & ledger models + Alembic migration (`wallets`, `transactions`) | US-1 | — |
+| 2 | Wallet service (atomic credit/debit, idempotency, locking) + wallet/transactions API | US-1 | 1 |
+| 3 | Premium purchase: `PaymentProvider` interface + purchase/confirm endpoints | US-2 | 1 |
+| 4 | Catalog item & listing models + migration (`catalog_items`, `marketplace_listings`, `creator_balances`) | US-3 | 1 |
+| 5 | Marketplace listing API (create/list/search/update/remove) | US-3 | 4 |
+| 6 | Marketplace purchase service + API (atomic escrow, fee split, item grant) | US-4 | 2, 4, 5 |
+| 7 | Creator payout request models + API (`payout_requests`) | US-5 | 2, 6 |
+| 8 | Payout admin review + `PayoutProvider` + audit | US-5 | 7 |
+| 9 | Marketplace moderation + content-flag/age-gate enforcement | cross-cutting | 5, 6 |
+| 10 | Godot economy API client (auth + HTTP + idempotency) | US-6 | 2 |
+| 11 | Godot wallet & transaction history UI | US-6 | 10 |
+| 12 | Godot marketplace browse/buy UI | US-6 | 6, 10 |
+| 13 | Godot selling & payout UI | US-6 | 5, 7, 10 |
+
+## 7. Phasing
+
+- **Phase 1 (currency + payments):** tasks 1–3. The foundation — ledger and
+  money movement must be rock-solid before anything spends Credits.
+- **Phase 2 (marketplace):** tasks 4–6. Listing and atomic purchase with escrow.
+- **Phase 3 (payouts):** tasks 7–8. Turn released escrow into creator payouts.
+- **Phase 4 (moderation):** task 9. Lock down the marketplace against mature
+  content and abuse.
+- **Phase 5 (client):** tasks 10–13, each landing after its backend dependency.
+
+## 8. Data model sketch
+
+```text
+wallets
+  id                bigint PK
+  user_id           int UNIQUE FK -> users.id
+  balance           bigint NOT NULL DEFAULT 0  CHECK (balance >= 0)
+  created_at        timestamptz
+  updated_at        timestamptz
+
+transactions        (append-only ledger)
+  id                bigint PK
+  wallet_id         bigint FK -> wallets.id
+  type              enum(credit_purchase, marketplace_purchase,
+                        marketplace_sale, escrow_release, payout,
+                        refund, admin_adjustment)
+  amount            bigint NOT NULL            (signed)
+  balance_after     bigint NOT NULL
+  reference_type    text                        (e.g. "purchase", "sale", "payout_request")
+  reference_id      text
+  idempotency_key   text UNIQUE
+  metadata_json     jsonb
+  created_at        timestamptz
+
+catalog_items
+  id                bigint PK
+  owner_id          int FK -> users.id
+  asset_id          int FK -> assets.id (nullable; null for non-asset virtual items)
+  item_type         enum(asset, avatar_item, experience_pass)
+  name              text
+  description       text
+  metadata_json     jsonb
+  created_at        timestamptz
+
+marketplace_listings
+  id                bigint PK
+  catalog_item_id   bigint FK -> catalog_items.id
+  seller_id         int FK -> users.id
+  price             bigint NOT NULL CHECK (price > 0)
+  status            enum(active, sold, delisted, removed_by_moderation)
+  created_at        timestamptz
+  updated_at        timestamptz
+
+purchases
+  id                bigint PK
+  listing_id        bigint FK -> marketplace_listings.id
+  buyer_id          int FK -> users.id
+  seller_id         int FK -> users.id
+  price             bigint NOT NULL
+  platform_fee      bigint NOT NULL
+  seller_net        bigint NOT NULL
+  status            enum(pending_escrow, completed, refunded, reversed)
+  escrow_hold_until timestamptz
+  created_at        timestamptz
+
+creator_balances
+  id                bigint PK
+  user_id           int UNIQUE FK -> users.id
+  available         bigint NOT NULL DEFAULT 0
+  pending           bigint NOT NULL DEFAULT 0
+  lifetime_earned   bigint NOT NULL DEFAULT 0
+  updated_at        timestamptz
+
+payout_requests
+  id                bigint PK
+  creator_id        int FK -> users.id
+  amount            bigint NOT NULL CHECK (amount > 0)
+  status            enum(pending, approved, paid, rejected)
+  external_ref      text
+  provider_ref      text
+  requested_by      int FK -> users.id
+  reviewed_by       int FK -> users.id (nullable)
+  reviewed_at       timestamptz
+  created_at        timestamptz
+```
+
+## 9. Security, anti-fraud & audit
+
+- **Server-authoritative balances/fees:** clients never compute totals; amounts
+  are validated server-side against bounds and the current listing.
+- **Row locking:** wallet and creator-balance mutations use `SELECT ... FOR
+  UPDATE` within one transaction.
+- **Idempotency:** every money-moving endpoint requires an `Idempotency-Key`;
+  duplicate keys return the stored original outcome.
+- **Rate limiting:** purchase, listing, and payout endpoints are token-bucket
+  rate-limited per user.
+- **Escrow & reversibility:** funds are not payable until the hold window
+  elapses; chargebacks/refunds reverse before release.
+- **Moderation:** listings carry the item's effective content flags; mature
+  items require age verification (per `content_moderation.md`); moderators can
+  `delist`/`remove` and trigger audited reversals.
+- **Audit:** the ledger plus `payout_requests` review fields form an append-only
+  audit trail for every movement of value.
+
+## 10. Out of scope for this feature
+
+- Real Stripe/PayPal/KYC integrations (provider interfaces leave the hooks; the
+  defaults are deterministic no-ops).
+- Subscriptions, recurring billing, or premium memberships.
+- Gift cards, promotional codes, or user-to-user Credit transfers.
+- Partial refunds, chargeback disputes, and seller tax/VAT handling.
+- In-world vending machines / scripted economy triggers (future, built on this
+  ledger via the scripting sandbox).

docs/planning/social.md

@@ -0,0 +1,170 @@
+# Social — Friends, Chat & Groups — Plan
+
+> **Status:** Planned
+> **Owner:** Platform team
+> **Feature ID:** `social`
+> **Godot version:** 4.6.2 stable
+> **Backend:** FastAPI + SQLAlchemy (async) + PostgreSQL + Redis
+
+## 1. Overview
+
+This document breaks the **Social** feature into user stories and right-sized
+implementation tasks. The feature delivers:
+
+- **Friends & following** — a friend request/accept model plus a one-way follow
+  relationship, with block lists.
+- **Presence & status** — online/offline, custom status message, last-seen.
+- **Chat** — direct messages (DM) and in-experience (world/room) chat with
+  **first-class safety**: server-side text filtering, report-message, and rate
+  limiting.
+- **Groups** — named groups with roles (owner/admin/member) and a simple group
+  page.
+- **Public profiles** — avatar, bio, favorite experiences, and a friends list
+  that respects privacy settings.
+
+## 2. Why chat safety is the differentiator
+
+The platform is explicitly meant to pull adults away from a youth-oriented
+competitor. Chat is the highest-risk surface: it is real-time, user-generated,
+and where abuse happens fastest. Safety is therefore treated as a **blocking
+requirement**, not an add-on:
+
+- Every message passes a **server-side text filter** before it is stored or
+  delivered. The client filter is cosmetic only; the server is authoritative.
+- Every message can be **reported**; reports flow into a moderation queue with
+  actor + reason + audit trail (mirroring `content_moderation.md`).
+- Sending is **rate limited** per user (Redis token bucket) to stop flooding and
+  harassment-by-volume.
+- Report and block are always reachable from a message context in the UI.
+
+## 3. Existing constraints (do not re-build)
+
+- **Auth:** JWT bearer tokens; `get_current_user` / `CurrentUser` dependency in
+  `app/dependencies.py`. All social endpoints reuse this.
+- **DB:** async SQLAlchemy + Alembic; migration `0001_initial` is the head.
+- **Redis:** configured (`REDIS_URL`) but unused so far; adopted here for
+  presence and rate limiting.
+- **Models:** `User`, `World` (owner_id), `Asset` (owner_id, is_public). Avatars
+  and favorite-experience references point at existing rows.
+- **Client:** Godot 4.6.2, minimal `main_menu.gd`; no social UI yet.
+
+## 4. Key design decisions
+
+| Concern | Decision |
+|---|---|
+| Message transport | REST for send/history; **WebSocket** gateway for real-time delivery + presence (matches `networking.md`'s "WebSocket as secondary transport" for chat) |
+| Presence store | Redis (TTL heartbeat) + persisted `last_seen_at` on the user record |
+| Text filtering | Pluggable `TextFilter` interface with a deterministic default (profanity list + normalization) so it runs without external services; third-party hook later |
+| Rate limiting | Redis token-bucket dependency, reusable across all social endpoints |
+| Reports | `message_reports` table + moderation endpoints (list/review/resolve) with audit fields |
+| Friends vs. follow | Friends = mutual (request→accept). Follow = one-way (no approval). Block = hard deny that also hides content and prevents DMs |
+| Privacy | Per-user settings JSON (`profile_visibility`, `friends_list_visibility`, `favorites_visibility`) enforced server-side on every read |
+| Groups | `groups` + `group_members` (role: owner/admin/member) + group page aggregate endpoint |
+| Real-time | One WebSocket endpoint multiplexing presence, DM, and world-chat messages via Redis pub/sub |
+
+## 5. User stories
+
+### US-1 Friends & following
+As a player, I can send a friend request, accept/decline incoming requests,
+unfriend, follow/unfollow other players, and block users so they can't interact
+with me.
+
+**Acceptance criteria**
+- Friend requests are one-directional until accepted; accepted friendships are mutual.
+- Follow is one-way and requires no approval.
+- Block prevents DMs, hides the blocked user's profile/friends interactions, and
+  removes any existing friendship/follow between the two.
+- Duplicate/self requests are rejected idempotently.
+
+### US-2 Presence & status
+As a player, I can see whether my friends are online, their custom status, and
+when they were last seen.
+
+**Acceptance criteria**
+- Online/offline is derived from a server-side heartbeat (Redis TTL), not client claims.
+- `last_seen_at` persists and is visible (subject to privacy settings).
+- Custom status text is optional and length-limited.
+
+### US-3 Public profiles
+As a player, I can view a public profile page showing avatar, bio, favorite
+experiences, and a friends list that respects the owner's privacy settings.
+
+**Acceptance criteria**
+- Avatar and bio are editable by the owner only.
+- Favorite experiences reference existing `World` rows.
+- A viewer sees only the sections the owner's privacy settings allow; blocked
+  users see a restricted view.
+
+### US-4 Chat (DM + in-experience) with safety
+As a player, I can send direct messages and chat inside a world/room. Messages
+are filtered, rate limited, and reportable.
+
+**Acceptance criteria**
+- Server filters message text before storing/delivering; filtered content is either
+  rejected (blocking) or redacted (configurable per filter policy).
+- Send rate is limited per user (token bucket); excess sends get `429`.
+- Every message has a stable id, author, timestamp, and conversation/world scope.
+- Any message can be reported with a reason; reports are stored and reviewable.
+- Real-time delivery over WebSocket with REST fallback for history.
+
+### US-5 Groups
+As a player, I can create a group, join/leave groups, and (as owner/admin)
+manage roles and view a simple group page.
+
+**Acceptance criteria**
+- Each group has exactly one owner and any number of admins/members.
+- Role transitions are authorized (only owner can transfer ownership or promote/demote admins).
+- Group page lists name, description, member list with roles, and member count.
+
+### US-6 Godot client
+As a player, I can access friends, presence, chat, profiles, and groups from the
+game UI.
+
+**Acceptance criteria**
+- An API client handles JWT auth, HTTP, and WebSocket for all social calls.
+- Dedicated screens/panels: friends+presence, DM & world chat (with report),
+  profile page, group page.
+- Client-side filtering is cosmetic; server responses remain authoritative.
+
+## 6. Task breakdown
+
+Right-sized to 1–3 files / one coherent piece of functionality each. Task IDs
+are sequential for dependency chaining.
+
+| # | Task | Story | Depends on |
+|---|------|-------|-----------|
+| 1 | Friends/follow/block models + Alembic migration | US-1 | — |
+| 2 | Friends & follow API router | US-1 | 1 |
+| 3 | Presence & status model + endpoints (Redis heartbeat) | US-2 | — |
+| 4 | Profile model + migration + own-profile endpoints | US-3 | 1 |
+| 5 | Public profile view + favorites + privacy enforcement | US-3 | 2, 4 |
+| 6 | Chat data models + migration (conversations, messages, reports) | US-4 | — |
+| 7 | Text filtering service + profanity config | US-4 | — |
+| 8 | Redis rate-limiting dependency | US-4 | — |
+| 9 | DM chat send/list endpoints (filter + rate limit) | US-4 | 6, 7, 8 |
+| 10 | Report-message endpoint + moderation queue | US-4 | 6, 9 |
+| 11 | In-experience (world/room) chat endpoints | US-4 | 9 |
+| 12 | Real-time WebSocket gateway (presence + DM + world chat) | US-4 | 3, 9, 11 |
+| 13 | Group + membership models + migration | US-5 | — |
+| 14 | Groups API (CRUD, join/leave, roles, group page) | US-5 | 13 |
+| 15 | Godot API client (auth + HTTP + WebSocket) | US-6 | 2 |
+| 16 | Godot friends & presence UI | US-6 | 3, 15 |
+| 17 | Godot chat UI (DM + world chat + report) | US-6 | 12, 15 |
+| 18 | Godot profile page UI | US-6 | 5, 15 |
+| 19 | Godot groups UI + group page | US-6 | 14, 15 |
+
+## 7. Phasing
+
+- **Phase 1 (data + core APIs):** tasks 1–5 (friends, presence, profiles).
+- **Phase 2 (chat safety — the differentiator):** tasks 6–12 (chat + safety +
+  realtime). This is the critical path and highest priority.
+- **Phase 3 (groups):** tasks 13–14.
+- **Phase 4 (client):** tasks 15–19, each landing after its backend dependency.
+
+## 8. Out of scope for this feature
+
+- Age verification / maturity gating (covered by `content_moderation.md`).
+- Voice chat, media/image messages, message editing/deletion history.
+- Third-party profanity/toxicity vendors (the `TextFilter` interface leaves a
+  hook, but the default is deterministic and dependency-free).
+- Mobile push notifications.

docs/testing/README.md

@@ -0,0 +1,50 @@
+# 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

@@ -0,0 +1,106 @@
+# 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-20 — full PC1 checkpoint run,
+migrations + pytest + all 7 Godot smoke tests + both platform exports, all
+clean. Real bugs found and fixed via real playtesting this same day (not
+caught by the checkpoint suite as it stood before today): the main menu
+had no way to actually open the login/register form, the world list's
+cards rendered at ~1px wide once real data existed, and navigating Play →
+Back logged the user out despite a still-valid session. All three are now
+covered by the smoke tests below so they can't silently regress.
+
+## Backend — `backend/tests/` (pytest)
+
+Run: `cd backend && python -m pytest -v` (needs `DATABASE_URL` pointed at a
+reachable Postgres — see the runner script).
+
+**Current total: 61 tests, all passing on a clean `main` checkout.**
+
+| File | Tests | What it covers |
+|---|---|---|
+| `test_auth_age_gate.py` | 11 | `calculate_age()` date-math correctness (exact boundary, leap years, birthday-not-yet-this-year — kept as a tested utility for a future real-DOB pass even though `/register` no longer calls it) + `RegisterRequest.over_18` field tests (true accepted, false accepted, missing rejected). 2026-08-20: the register flow was simplified from collecting/validating a date of birth to a plain client-side "I am 18 or older" confirmation, so the old date-validation parametrized cases were replaced. Backs the 18+ registration gate (PR #23, revised PC1). |
+| `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). |
+| `test_auth_endpoints.py` | 10 | **Integration tests** for `POST /api/auth/register` and `POST /api/auth/login` against the real FastAPI app + real Postgres. Covers: successful register (201), duplicate username (409), duplicate email (409), `over_18=false` rejection (400), missing `over_18` field (422), successful login with correct credentials (200), wrong password (401), nonexistent user (401), form-encoded login (OAuth2), and JWT validity of returned tokens. |
+| `test_refresh_endpoint.py` | 8 | **Integration tests** for `POST /api/auth/refresh`. Covers: successful refresh (200, new access token, same refresh token returned), refresh produces different access tokens on repeated calls, invalid refresh token (401), empty body (422), missing field (422), refresh token from login also works, returned access token is valid JWT decodable with public key, `access_token_expires_minutes` in response. |
+| `test_refresh_token_jti.py` | 6 | Unit tests for refresh token uniqueness (jti claim) and model column length. Covers: two calls with same sub produce different tokens (jti uniqueness), jti is valid UUID, rapid repeated calls all produce unique jtis, jti survives decode, `RefreshToken.token` column is `String(512)`, column type is `String`. |
+| `test_auth_expired_token.py` | 5 | **Integration tests** for expired-token rejection across auth endpoints. Covers: expired access JWT rejected by `GET /api/auth/me` (401), garbage access token rejected by `/me` (401), missing bearer token returns 401, expired refresh token (DB `expires_at` in past) rejected by `/refresh` (401), expired refresh JWT (past `exp` claim) rejected before DB lookup (401). |
+
+**What these are, honestly:** a mix of pure unit tests (`test_auth_age_gate.py`,
+`test_gltf_metadata.py`, `test_refresh_token_jti.py`) and real integration tests
+(`test_auth_endpoints.py`, `test_refresh_endpoint.py`, `test_auth_expired_token.py`)
+that hit the FastAPI app against a real Postgres database via `TestClient`.
+The integration tests exercise the full stack: Pydantic validation → DB →
+JWT → response. The suite is also re-runnable without manual cleanup —
+`backend/tests/conftest.py` has a session-scoped autouse fixture that
+truncates all app tables once before the suite runs.
+
+**Known coverage gaps** (real gaps, not placeholders — nothing enforces filling
+these yet):
+- No endpoint tests for `GET /api/worlds`, `GET /api/assets/*`, or any
+  world/asset CRUD routes — only auth endpoints have integration coverage
+  (`GET /api/worlds` is covered indirectly via the Godot smoke tests below).
+- No tests for the moderation schema/migration beyond "the migration runs."
+- No tests for the `GET /api/auth/me` endpoint's response body (only its
+  auth-header validation is covered via expired-token tests).
+- No tests for session management (create/validate/revoke sessions).
+
+## Godot client — `scripts/smoke_test_*.gd`
+
+**7 smoke tests merged into `main`.** Each needs a live backend —
+`AGP_API_BASE_URL` env var, falling back to the
+`application/agp/api_base_url` project setting (default
+`http://127.0.0.1:8000`) if unset.
+
+| File | What it covers |
+|---|---|
+| `smoke_test_api.gd` | Exercises `ApiClient.health_check()` against a live backend. Verifies the real HTTP request path (`HTTPRequest` node lifecycle, JSON parse, result-dictionary contract). Exits 1 on failure. |
+| `smoke_test_auth.gd` | Tests the full auth flow via `ApiClient` autoload: register unique user (201), duplicate username (409), `over_18=false` registration (400), correct login (200), wrong password (401), nonexistent user (401). |
+| `smoke_test_e2e.gd` | End-to-end flow: health check → register → login → worlds list. Verifies the full request chain with a fresh user, including token storage and `get_worlds()` with auth header. |
+| `smoke_test_world_list.gd` | Registers a user, **seeds a real world via `POST /api/worlds/`** (without this, `run_checkpoint_tests.py`'s always-fresh DB means the populated-card render path never actually runs in CI, only the empty-list path would), instantiates `world_list.tscn` as a real scene, waits for `_refresh_worlds()` to complete, confirms it reached the populated (not empty) state, and asserts **each rendered card's real computed width is >= 200px**. That last check is the one that matters: 2026-08-20, a real bug shipped where every card existed in the tree with a non-zero child count and no crash, but rendered at 1.0px wide (`ScrollContainer`'s `size_flags_horizontal`/`vertical` used the raw integer `4` = `Control.SIZE_SHRINK_CENTER` instead of `3` = `SIZE_EXPAND_FILL`) — invisible on screen, and a child-count-only check would never have caught it. Confirmed by deliberately reintroducing the bug: card width check correctly fails at 25px. |
+| `smoke_test_main_menu_ui.gd` | Instantiates `main_menu.tscn`, confirms the auth panel starts hidden, and confirms a **real signal emission** on LoginButton/RegisterButton (not calling the handler method directly) actually opens it. This is the check that would have caught 2026-08-20's real bug: the auth panel and its logic were fully correct, but nothing in the scene was ever wired to open it, so Login/Register were completely unreachable from the UI. |
+| `smoke_test_main_menu_full_flow.gd` | Full click-through: open the register form, fill it exactly as a user would, submit, confirm Play actually becomes enabled, the welcome message shows, and the auth buttons hide themselves. Calls the submit handler directly (awaited) rather than via `auth_button.pressed.emit()` — see the note at the top of the file: a synthetic `.emit()` on an `await`-using handler doesn't get driven forward reliably in `--script`/SceneTree headless mode the way real GUI input event dispatch does, confirmed by comparing direct-call vs `.emit()` behavior. Not a bug in the actual click-driven flow, just a headless-test-harness quirk to route around when writing tests. |
+| `smoke_test_main_menu_back.gd` | Regression test for Play → Back logging the user out even with a valid token still held. Registers a user, loads `main_menu.tscn` (asserts it restores the authenticated state via a real `auth_state_ready` signal wait, not a frame-count guess), clicks Play → `world_list.tscn`, clicks Back → `main_menu.tscn`, and asserts the menu is still authenticated. Checks `WelcomeLabel.is_visible_in_tree()`, not just `.visible` — the label lives inside AuthPanel, so `.visible` alone is a false positive if the panel itself is hidden (a real bug briefly present: `_show_authenticated()` hid AuthPanel while claiming the welcome label was visible, which rendered nothing). |
+
+Run (once, to build the class cache): `godot --headless --path . --import`,
+then for each smoke test: `godot --headless --path . --script
+res://scripts/smoke_test_<name>.gd` — **no `--quit`**, it kills these before
+their awaited HTTP calls finish.
+
+**Known gaps:**
+- No smoke tests for chunk loading/streaming (`chunk.gd`, `chunk_scene.gd`).
+- No smoke tests for dynamic/static object nodes.
+- All smoke tests require a live backend; no offline/unit smoke tests exist.
+- `smoke_test_world_list.gd` and `smoke_test_main_menu_*.gd` are the only
+  ones that exercise a real `.tscn` scene instantiation — others only test
+  the `ApiClient` autoload directly.
+- `get_me()` (`GET /auth/me`) is implemented in `scripts/api_client.gd` but
+  has no smoke coverage yet.
+- The Login path (as opposed to Register) through `main_menu.gd` isn't
+  separately smoke-tested — it shares the same `_on_auth_button_pressed()`/
+  `_on_auth_complete()` code path already exercised for Register, but that's
+  inference, not a direct check.
+
+## Client export
+
+`scripts/build.sh` produces real Linux (`agp-game.x86_64`) and Windows
+(`agp-game.exe`) binaries via `--export-release`. Verified 2026-08-20: both
+exports complete clean from a fresh checkout and produce valid binaries
+(confirmed via `file` — real ELF64/PE32+, not empty or truncated). Neither
+export is exercised by an automated GUI test (headless Godot can't drive a
+window) — actually launching and clicking through the exported binary is a
+manual step, see `docs/checkpoints/PC1.md` for playtest instructions.
+
+## What "full coverage" should eventually mean here
+
+Not defined precisely yet — the honest target as of 2026-08-20 is
+"integration tests for every endpoint + smoke tests for every major scene."
+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

@@ -0,0 +1,74 @@
+[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=true
+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=true
+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

@@ -0,0 +1,27 @@
+; 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/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
+window/size/viewport_height=1080
+window/stretch/mode="canvas_items"
+
+[rendering]
+
+renderer/rendering_method="gl_compatibility"
+renderer/rendering_method.mobile="gl_compatibility"

sandbox_probe/.godot/.gdignore

@@ -0,0 +1 @@
+

sandbox_probe/probe6.gd

@@ -0,0 +1,174 @@
+extends Node
+
+func _ready():
+	print("=== SANDBOX PROBE 6: Corrected Evidence Gathering (Godot 4.6.2) ===")
+	probe_script_loading()
+	probe_os_apis()
+	probe_file_access()
+	probe_network()
+	probe_classdb()
+	probe_expression_engine()
+	probe_engine_singletons()
+	probe_worker_threads()
+	probe_project_settings()
+	probe_allowlist()
+	print("=== SANDBOX PROBE 6 END ===")
+	get_tree().quit()
+
+func probe_script_loading():
+	print("--- Script loading ---")
+	var gd = GDScript.new()
+	gd.source_code = "extends RefCounted\nfunc hello():\n\treturn 42\n"
+	var err = gd.reload()
+	print("GDScript.reload() from source_code err=", err)
+	if err == OK:
+		var inst = gd.new()
+		print("  instantiated, hello()=", inst.call("hello"))
+	var res = load("res://test_script.gd")
+	print("load('res://test_script.gd') = ", res)
+	if res:
+		print("  get_source_code() available: ", res.has_method("get_source_code"))
+	print("  GDScript instance has 'get_ast': ", gd.has_method("get_ast"))
+	print("  GDScript instance has 'get_parser': ", gd.has_method("get_parser"))
+	print("  GDScript instance has 'get_script_method_list': ", gd.has_method("get_script_method_list"))
+	print("  GDScript instance has 'get_script_property_list': ", gd.has_method("get_script_property_list"))
+
+func probe_os_apis():
+	print("--- OS APIs ---")
+	var out = []
+	var exit_code = OS.execute("echo", ["hello"], out)
+	print("OS.execute('echo') exit=", exit_code, " out=", out)
+	print("OS.get_environment('HOME') = ", OS.get_environment("HOME"))
+	print("OS has 'create_process': ", OS.has_method("create_process"))
+	print("OS.get_cmdline_args() = ", OS.get_cmdline_args())
+	print("OS.get_user_data_dir() = ", OS.get_user_data_dir())
+	print("OS.get_executable_path() = ", OS.get_executable_path())
+
+func probe_file_access():
+	print("--- File access ---")
+	var f = FileAccess.open("/etc/hostname", FileAccess.READ)
+	print("FileAccess.open('/etc/hostname') = ", f)
+	if f:
+		print("  content: ", f.get_as_text())
+		f.close()
+	var w = FileAccess.open("/tmp/godot_probe_write.txt", FileAccess.WRITE)
+	print("FileAccess.open('/tmp/...', WRITE) = ", w)
+	if w:
+		w.store_string("probe")
+		w.close()
+		print("  wrote to /tmp OK")
+	var dir = DirAccess.open("/")
+	print("DirAccess.open('/') = ", dir)
+	if dir:
+		var names = dir.get_files()
+		print("  root files count: ", names.size())
+	var res_dir = DirAccess.open("res://")
+	print("DirAccess.open('res://') = ", res_dir)
+	var user_dir = DirAccess.open("user://")
+	print("DirAccess.open('user://') = ", user_dir)
+
+func probe_network():
+	print("--- Network ---")
+	var tcp = TCPServer.new()
+	var bind_err = tcp.listen(0)
+	print("TCPServer.listen(0) err=", bind_err)
+	var http = HTTPClient.new()
+	print("HTTPClient instantiated: ", http != null)
+	var http_req = HTTPRequest.new()
+	print("HTTPRequest instantiated: ", http_req != null)
+	var udp = PacketPeerUDP.new()
+	print("PacketPeerUDP instantiated: ", udp != null)
+	var ws = WebSocketPeer.new()
+	print("WebSocketPeer instantiated: ", ws != null)
+
+func probe_classdb():
+	print("--- ClassDB ---")
+	print("ClassDB.class_exists('OS'): ", ClassDB.class_exists("OS"))
+	print("ClassDB.class_exists('FileAccess'): ", ClassDB.class_exists("FileAccess"))
+	print("ClassDB.class_exists('TCPServer'): ", ClassDB.class_exists("TCPServer"))
+	print("ClassDB.class_exists('HTTPClient'): ", ClassDB.class_exists("HTTPClient"))
+	var class_list = ClassDB.get_class_list()
+	print("ClassDB.get_class_list() count: ", class_list.size())
+	var os_methods = ClassDB.class_get_method_list("OS")
+	print("OS method count: ", os_methods.size())
+	var inst = ClassDB.instantiate("Node")
+	print("ClassDB.instantiate('Node') = ", inst)
+	print("ClassDB has 'class_get_singleton': ", ClassDB.has_method("class_get_singleton"))
+
+func probe_expression_engine():
+	print("--- Expression engine ---")
+	var expr = Expression.new()
+	var err = expr.parse("1 + 2")
+	print("Expression.parse('1 + 2') err=", err)
+	if err == OK:
+		var result = expr.execute()
+		print("  Expression.execute() = ", result)
+	var expr2 = Expression.new()
+	err = expr2.parse("OS.get_environment('HOME')")
+	print("Expression.parse('OS.get_environment') err=", err)
+	if err == OK:
+		var result2 = expr2.execute()
+		print("  Expression.execute() = ", result2)
+	var expr3 = Expression.new()
+	err = expr3.parse("get_environment('HOME')", ["OS"])
+	print("Expression.parse with base_instance err=", err)
+	if err == OK:
+		var result3 = expr3.execute([], OS)
+		print("  Expression.execute with OS base = ", result3)
+	var expr4 = Expression.new()
+	err = expr4.parse("FileAccess.open('/etc/hostname', 1)")
+	print("Expression.parse('FileAccess.open') err=", err)
+	if err == OK:
+		var result4 = expr4.execute()
+		print("  Expression.execute() = ", result4)
+	var expr5 = Expression.new()
+	err = expr5.parse("get_tree().quit()")
+	print("Expression.parse('get_tree().quit()') err=", err)
+	if err == OK:
+		var result5 = expr5.execute()
+		print("  Expression.execute() = ", result5)
+
+func probe_engine_singletons():
+	print("--- Engine singletons ---")
+	print("Engine has 'remove_singleton': ", Engine.has_method("remove_singleton"))
+	print("Engine has 'add_singleton': ", Engine.has_method("add_singleton"))
+	print("Engine.get_main_loop() = ", Engine.get_main_loop())
+
+func probe_worker_threads():
+	print("--- Worker threads ---")
+	var thread = Thread.new()
+	print("  Thread.new() = ", thread)
+	print("  WorkerThreadPool has 'add_task': ", WorkerThreadPool.has_method("add_task"))
+
+func probe_project_settings():
+	print("--- Project settings ---")
+	var settings = ProjectSettings.get_property_list()
+	var relevant = []
+	for s in settings:
+		var name = String(s.name)
+		if "sandbox" in name.to_lower() or "restrict" in name.to_lower() or "security" in name.to_lower():
+			relevant.append(name)
+	print("  Sandbox/security project settings: ", relevant)
+	print("  ProjectSettings has 'application/run/disable_os': ", ProjectSettings.has_setting("application/run/disable_os"))
+	print("  ProjectSettings has 'application/run/disable_file_access': ", ProjectSettings.has_setting("application/run/disable_file_access"))
+	print("  ProjectSettings has 'application/run/disable_network': ", ProjectSettings.has_setting("application/run/disable_network"))
+	print("  ProjectSettings has 'set_setting': ", ProjectSettings.has_method("set_setting"))
+	print("  ProjectSettings has 'save': ", ProjectSettings.has_method("save"))
+
+func probe_allowlist():
+	print("--- Allowlist / static analysis ---")
+	var dangerous_patterns = [
+		"OS.execute", "OS.create_process", "OS.get_environment",
+		"FileAccess.open", "DirAccess.open", "TCPServer", "HTTPClient",
+		"load(", "preload(", "ClassDB", "Engine.get_main_loop",
+		"get_tree().quit", "ProjectSettings"
+	]
+	var test_script = """extends Node
+func _ready():
+	var f = FileAccess.open("/etc/passwd", FileAccess.READ)
+	OS.execute("rm", ["-rf", "/"])
+"""
+	print("  Test script contains dangerous patterns:")
+	for p in dangerous_patterns:
+		if p in test_script:
+			print("    DETECTED: ", p)

sandbox_probe/probe6.tscn

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

sandbox_probe/project.godot

@@ -0,0 +1,8 @@
+; Engine configuration file.
+config_version=5
+
+[application]
+
+config/name="sandbox_probe"
+run/main_scene="res://probe6.tscn"
+config/features=PackedStringArray("4.6")

sandbox_probe/test_script.gd

@@ -0,0 +1,4 @@
+extends RefCounted
+
+func hello():
+	return "from test_script.gd"

scenes/main.tscn

@@ -0,0 +1,6 @@
+[gd_scene load_steps=2 format=3 uid="uid://main_scene"]
+
+[ext_resource type="Script" path="res://scripts/chunk_stream_manager.gd" id="1_chunk_stream"]
+
+[node name="Main" type="Node3D"]
+script = ExtResource("1_chunk_stream")

scenes/main_menu.tscn

@@ -0,0 +1,126 @@
+[gd_scene load_steps=2 format=3 uid="uid://main_menu_scene"]
+
+[ext_resource type="Script" path="res://scripts/main_menu.gd" id="1_main"]
+
+[node name="MainMenu" type="Control"]
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+grow_horizontal = 2
+grow_vertical = 2
+script = ExtResource("1_main")
+
+[node name="CenterContainer" type="CenterContainer" parent="."]
+layout_mode = 3
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+grow_horizontal = 2
+grow_vertical = 2
+
+[node name="VBoxContainer" type="VBoxContainer" parent="CenterContainer"]
+layout_mode = 1
+theme_override_constants/separation = 16
+size_flags_horizontal = 4
+
+[node name="TitleLabel" type="Label" parent="CenterContainer/VBoxContainer"]
+layout_mode = 1
+text = "AGP Game"
+horizontal_alignment = 1
+theme_override_font_sizes/font_size = 72
+
+[node name="AuthButtonsRow" type="HBoxContainer" parent="CenterContainer/VBoxContainer"]
+layout_mode = 1
+theme_override_constants/separation = 16
+alignment = 1
+
+[node name="LoginButton" type="Button" parent="CenterContainer/VBoxContainer/AuthButtonsRow"]
+layout_mode = 1
+text = "Login"
+size_flags_horizontal = 3
+
+[node name="RegisterButton" type="Button" parent="CenterContainer/VBoxContainer/AuthButtonsRow"]
+layout_mode = 1
+text = "Register"
+size_flags_horizontal = 3
+
+[node name="AuthPanel" type="PanelContainer" parent="CenterContainer/VBoxContainer"]
+layout_mode = 1
+visible = false
+
+[node name="MarginContainer" type="MarginContainer" parent="CenterContainer/VBoxContainer/AuthPanel"]
+layout_mode = 1
+theme_override_constants/margin_left = 24
+theme_override_constants/margin_top = 24
+theme_override_constants/margin_right = 24
+theme_override_constants/margin_bottom = 24
+
+[node name="AuthVBox" type="VBoxContainer" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer"]
+layout_mode = 1
+theme_override_constants/separation = 8
+size_flags_horizontal = 3
+
+[node name="AuthModeLabel" type="Label" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+text = "Login"
+horizontal_alignment = 1
+theme_override_font_sizes/font_size = 24
+
+[node name="UsernameEdit" type="LineEdit" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+placeholder_text = "Username"
+size_flags_horizontal = 3
+
+[node name="PasswordEdit" type="LineEdit" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+placeholder_text = "Password"
+size_flags_horizontal = 3
+echo_password = true
+
+[node name="EmailEdit" type="LineEdit" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+visible = false
+placeholder_text = "Email"
+size_flags_horizontal = 3
+
+[node name="Over18Check" type="CheckBox" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+visible = false
+text = "I am 18 or older"
+size_flags_horizontal = 3
+
+[node name="AuthButton" type="Button" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+text = "Login"
+size_flags_horizontal = 3
+
+[node name="AuthStatusLabel" type="Label" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+text = ""
+horizontal_alignment = 1
+autowrap_mode = 2
+visible = false
+
+[node name="WelcomeLabel" type="Label" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+visible = false
+text = ""
+horizontal_alignment = 1
+
+[node name="PlayButton" type="Button" parent="CenterContainer/VBoxContainer"]
+layout_mode = 1
+text = "Play"
+size_flags_horizontal = 4
+
+[node name="QuitButton" type="Button" parent="CenterContainer/VBoxContainer"]
+layout_mode = 1
+text = "Quit"
+size_flags_horizontal = 4
+
+[connection signal="pressed" from="CenterContainer/VBoxContainer/AuthButtonsRow/LoginButton" to="." method="_on_login_button_pressed"]
+[connection signal="pressed" from="CenterContainer/VBoxContainer/AuthButtonsRow/RegisterButton" to="." method="_on_register_button_pressed"]
+[connection signal="pressed" from="CenterContainer/VBoxContainer/PlayButton" to="." method="_on_play_button_pressed"]
+[connection signal="pressed" from="CenterContainer/VBoxContainer/QuitButton" to="." method="_on_quit_button_pressed"]
+[connection signal="pressed" from="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthButton" to="." method="_on_auth_button_pressed"]
+[connection signal="text_submitted" from="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/UsernameEdit" to="." method="_on_auth_button_pressed"]
+[connection signal="text_submitted" from="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/PasswordEdit" to="." method="_on_auth_button_pressed"]

scenes/world_list.tscn

@@ -0,0 +1,78 @@
+[gd_scene load_steps=2 format=3]
+
+[ext_resource type="Script" path="res://scripts/world_list.gd" id="1_wl"]
+
+[node name="WorldList" type="Control"]
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+grow_horizontal = 2
+grow_vertical = 2
+script = ExtResource("1_wl")
+
+[node name="VBoxContainer" type="VBoxContainer" parent="."]
+layout_mode = 1
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+grow_horizontal = 2
+grow_vertical = 2
+theme_override_constants/separation = 8
+
+[node name="HeaderHBox" type="HBoxContainer" parent="VBoxContainer"]
+layout_mode = 3
+size_flags_horizontal = 3
+theme_override_constants/separation = 16
+
+[node name="BackButton" type="Button" parent="VBoxContainer/HeaderHBox"]
+layout_mode = 3
+text = "< Back"
+size_flags_horizontal = 0
+
+[node name="TitleLabel" type="Label" parent="VBoxContainer/HeaderHBox"]
+layout_mode = 3
+text = "Browse Worlds"
+horizontal_alignment = 1
+size_flags_horizontal = 3
+theme_override_font_sizes/font_size = 28
+
+[node name="RefreshButton" type="Button" parent="VBoxContainer/HeaderHBox"]
+layout_mode = 3
+text = "Refresh"
+size_flags_horizontal = 0
+
+[node name="ScrollContainer" type="ScrollContainer" parent="VBoxContainer"]
+layout_mode = 3
+size_flags_horizontal = 3
+size_flags_vertical = 3
+horizontal_mode = 2
+vertical_mode = 2
+
+[node name="WorldList" type="VBoxContainer" parent="VBoxContainer/ScrollContainer"]
+layout_mode = 3
+size_flags_horizontal = 3
+theme_override_constants/separation = 8
+
+[node name="LoadingLabel" type="Label" parent="VBoxContainer"]
+layout_mode = 3
+text = "Loading worlds..."
+visible = false
+horizontal_alignment = 1
+theme_override_font_sizes/font_size = 18
+
+[node name="ErrorLabel" type="Label" parent="VBoxContainer"]
+layout_mode = 3
+text = ""
+visible = false
+horizontal_alignment = 1
+theme_override_font_sizes/font_size = 18
+
+[node name="EmptyLabel" type="Label" parent="VBoxContainer"]
+layout_mode = 3
+text = ""
+visible = false
+horizontal_alignment = 1
+theme_override_font_sizes/font_size = 18
+
+[connection signal="pressed" from="VBoxContainer/HeaderHBox/BackButton" to="." method="_on_back_button_pressed"]
+[connection signal="pressed" from="VBoxContainer/HeaderHBox/RefreshButton" to="." method="_on_refresh_button_pressed"]

scripts/api_client.gd

@@ -0,0 +1,292 @@
+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 over_18 Must be true; the backend rejects registration otherwise.
+func register(
+	username: String,
+	email: String,
+	password: String,
+	over_18: bool
+) -> Dictionary:
+	var payload := {
+		"username": username,
+		"email": email,
+		"password": password,
+		"over_18": over_18,
+	}
+	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

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

scripts/build.sh

@@ -0,0 +1,42 @@
+#!/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/chunk.gd

@@ -0,0 +1,105 @@
+class_name Chunk
+extends Node3D
+## A single world chunk. Holds the chunk coordinate, bounds, and the
+## visual/gameplay content for that region of the world.
+##
+## Chunks are the atomic unit of world geometry, gameplay objects, and
+## persistence (see docs/architecture/world.md). The server loads and saves
+## whole chunks; clients stream the chunks around them.
+
+## Default chunk dimensions in world units (tiles). Matches the constants in
+## docs/architecture/world.md section 2.2.
+const CHUNK_SIZE_X: int = 32
+const CHUNK_SIZE_Y: int = 32
+const CHUNK_SIZE_Z: int = 1
+
+## World-space origin of chunk coordinate (0,0).
+const CHUNK_ORIGIN := Vector3(0.0, 0.0, 0.0)
+
+## Chunk coordinate (cx, cy, cz) in chunk space.
+var coord := Vector3i.ZERO
+
+## The canonical chunk key: "{world_id}:{room_id}:{cx}:{cy}:{cz}".
+var key: String = ""
+
+## World and room identifiers this chunk belongs to.
+var world_id: String = ""
+var room_id: String = ""
+
+## Format version of the chunk payload (currently 1).
+var format_version: int = 1
+
+## Revision counter, incremented on every write. Used for optimistic
+## concurrency and change detection.
+var revision: int = 0
+
+## Whether this chunk has been modified in memory but not yet flushed.
+var dirty: bool = false
+
+## Container for static objects (props, geometry) in this chunk.
+var objects: Array[Node3D] = []
+
+## Container for dynamic object templates (spawnable entities).
+var dynamic_templates: Array[Node3D] = []
+
+## The world-space bounding box of this chunk.
+var bounds: AABB
+
+
+func _init(p_coord: Vector3i = Vector3i.ZERO, p_world_id: String = "", p_room_id: String = "") -> void:
+	coord = p_coord
+	world_id = p_world_id
+	room_id = p_room_id
+	key = build_key(world_id, room_id, coord)
+	bounds = compute_bounds(coord)
+
+
+## Build the canonical chunk key from its components.
+static func build_key(p_world_id: String, p_room_id: String, p_coord: Vector3i) -> String:
+	return "%s:%s:%d:%d:%d" % [p_world_id, p_room_id, p_coord.x, p_coord.y, p_coord.z]
+
+
+## Compute the world-space bounding box for a chunk coordinate.
+static func compute_bounds(p_coord: Vector3i) -> AABB:
+	var min_pos := Vector3(
+		CHUNK_ORIGIN.x + p_coord.x * CHUNK_SIZE_X,
+		CHUNK_ORIGIN.y + p_coord.y * CHUNK_SIZE_Y,
+		CHUNK_ORIGIN.z + p_coord.z * CHUNK_SIZE_Z
+	)
+	return AABB(min_pos, Vector3(CHUNK_SIZE_X, CHUNK_SIZE_Y, CHUNK_SIZE_Z))
+
+
+## Compute the chunk coordinate that contains a world-space position.
+static func coord_for_position(p_pos: Vector3) -> Vector3i:
+	return Vector3i(
+		int(floor((p_pos.x - CHUNK_ORIGIN.x) / CHUNK_SIZE_X)),
+		int(floor((p_pos.y - CHUNK_ORIGIN.y) / CHUNK_SIZE_Y)),
+		int(floor((p_pos.z - CHUNK_ORIGIN.z) / CHUNK_SIZE_Z))
+	)
+
+
+## Add a static object to this chunk.
+func add_object(p_object: Node3D) -> void:
+	objects.append(p_object)
+	add_child(p_object)
+
+
+## Add a dynamic object template to this chunk.
+func add_dynamic_template(p_template: Node3D) -> void:
+	dynamic_templates.append(p_template)
+	add_child(p_template)
+
+
+## Remove all objects from this chunk.
+func clear_objects() -> void:
+	for obj in objects:
+		if is_instance_valid(obj):
+			obj.queue_free()
+	objects.clear()
+	dynamic_templates.clear()
+
+
+## Mark this chunk as dirty (modified but not yet persisted).
+func mark_dirty() -> void:
+	dirty = true
+	revision += 1

scripts/chunk.gd.uid

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

scripts/chunk_data_decoder.gd

@@ -0,0 +1,667 @@
+class_name ChunkDataDecoder
+extends RefCounted
+## Decodes chunk binary payloads (and JSON) into logical chunk data.
+##
+## Implements the binary format spec from docs/architecture/world.md §3.6.
+## Both the Godot client and Python backend use this class to ensure
+## identical encoding/decoding behavior.
+##
+## ## Binary Format Overview
+##
+## ```
+## Header (48 bytes):
+##   [0:4]   magic "AGPC"
+##   [4:6]   version (uint16 LE)
+##   [6:8]   header_len (uint16 LE)
+##   [8:12]  flags (uint32 LE)
+##   [12:16] payload_len (uint32 LE)
+##   [16:48] checksum (SHA-256 hex, 32 bytes)
+##
+## Payload Body (sections):
+##   [section_id:1][section_len:4][data:section_len]
+## ```
+
+
+## Content flags parsed from a chunk.
+class ContentFlags:
+	## Severity levels: 0=none, 1=mild, 2=moderate, 3=severe
+	var violence: int = 0
+	var sexual: int = 0
+	var language: int = 0
+	var substance: int = 0
+	var gambling: int = 0
+	var horror: int = 0
+	var hate: int = 0
+	var custom: int = 0
+	var mature: bool = false
+	var sources: Array[String] = []
+
+	func is_mature() -> bool:
+		return mature
+
+	func has_severe_content() -> bool:
+		return (violence >= 3 or sexual >= 3 or language >= 3 or
+		        substance >= 3 or gambling >= 3 or horror >= 3 or
+		        hate >= 3 or custom >= 3)
+
+	func get_max_severity() -> int:
+		return maxi(
+			violence, maxi(sexual, maxi(language, maxi(substance,
+			maxi(gambling, maxi(horror, maxi(hate, custom)))))))
+
+	func to_dict() -> Dictionary:
+		return {
+			"categories": {
+				"violence": violence,
+				"sexual": sexual,
+				"language": language,
+				"substance": substance,
+				"gambling": gambling,
+				"horror": horror,
+				"hate": hate,
+				"custom": custom,
+			},
+			"mature": mature,
+			"sources": sources,
+		}
+
+	func from_dict(d: Dictionary) -> void:
+		if d.has("categories"):
+			violence = d["categories"].get("violence", 0)
+			sexual = d["categories"].get("sexual", 0)
+			language = d["categories"].get("language", 0)
+			substance = d["categories"].get("substance", 0)
+			gambling = d["categories"].get("gambling", 0)
+			horror = d["categories"].get("horror", 0)
+			hate = d["categories"].get("hate", 0)
+			custom = d["categories"].get("custom", 0)
+		mature = d.get("mature", false)
+		sources = d.get("sources", [])
+
+
+## A tile layer definition (palette + dense tile indices).
+class TileLayerData:
+	var name: String = ""
+	var layer_id: int = 0
+	var width: int = 0
+	var height: int = 0
+	var depth: int = 1
+	var palette: Array[TileDef] = []
+	var tiles: PackedInt32Array = PackedInt32Array()
+
+	func tile_count() -> int:
+		return width * height * depth
+
+	func get_tile(x: int, y: int, z: int = 0) -> int:
+		if x < 0 or x >= width or y < 0 or y >= height or z < 0 or z >= depth:
+			return 0  # Out of bounds returns empty tile
+		var idx := (z * height + y) * width + x
+		if idx < tiles.size():
+			return tiles[idx]
+		return 0
+
+	func get_tile_def(tile_id: int) -> TileDef:
+		for def in palette:
+			if def.id == tile_id:
+				return def
+		return null
+
+
+## A world object parsed from chunk data.
+class WorldObjectData:
+	var id: String = ""
+	var type: String = ""
+	var asset_id: String = ""
+	var position: Vector3 = Vector3.ZERO
+	var rotation: Vector4 = Vector4(0, 0, 0, 1)
+	var scale: Vector3 = Vector3.ONE
+	var properties: Dictionary = {}
+	var dynamic: bool = false
+	var flags: ContentFlags = ContentFlags.new()
+
+
+## The complete decoded chunk payload.
+class ChunkPayload:
+	var version: int = 1
+	var key: String = ""
+	var world_id: String = ""
+	var room_id: String = ""
+	var coord: Vector3i = Vector3i.ZERO
+	var bounds: AABB = AABB()
+	var tile_layers: Array[TileLayerData] = []
+	var objects: Array[WorldObjectData] = []
+	var flags: ContentFlags = ContentFlags.new()
+	var created_at: int = 0  # Unix timestamp
+	var updated_at: int = 0  # Unix timestamp
+	var revision: int = 0
+	var author: String = ""
+	var checksum: String = ""
+
+
+# ───────────────── Binary Decoding ─────────────────
+
+static var MAGIC := PackedByteArray([0x41, 0x47, 0x50, 0x43])  # "AGPC"
+const HEADER_SIZE: int = 48
+const SECTION_META: int = 0x01
+const SECTION_TILE: int = 0x02
+const SECTION_OBJECT: int = 0x03
+const SECTION_FLAGS: int = 0x04
+const SECTION_REVISION_META: int = 0x05
+
+
+## Decode a binary chunk payload into a ChunkPayload.
+## Returns null if the data is invalid or version is unsupported.
+static func decode_binary(data: PackedByteArray) -> ChunkPayload:
+	if data.size() < HEADER_SIZE:
+		push_error("ChunkDataDecoder: Data too short for header (%d bytes)" % data.size())
+		return null
+
+	# Verify magic
+	var magic := PackedByteArray(data.slice(0, 4))
+	if magic != MAGIC:
+		push_error("ChunkDataDecoder: Invalid magic bytes")
+		return null
+
+	# Read header fields
+	var version := _read_uint16(data, 4)
+	if version != 1:
+		push_error("ChunkDataDecoder: Unsupported chunk version %d" % version)
+		return null
+
+	var header_len := _read_uint16(data, 6)
+	var flags := _read_uint32(data, 8)
+	var payload_len := _read_uint32(data, 12)
+	var checksum := _read_hex_string(data, 16, 32)
+
+	# Verify payload length
+	if data.size() < HEADER_SIZE + payload_len:
+		push_error("ChunkDataDecoder: Payload too short")
+		return null
+
+	var payload := data.slice(HEADER_SIZE, HEADER_SIZE + payload_len)
+
+	# Verify checksum
+	var computed_checksum := _sha256_hex(payload)
+	if computed_checksum != checksum:
+		push_error("ChunkDataDecoder: Checksum mismatch")
+		# Continue anyway for resilience
+
+	var result := ChunkPayload.new()
+	result.version = version
+	result.checksum = checksum
+
+	# Parse sections
+	var offset := 0
+	while offset < payload.size():
+		if offset + 5 > payload.size():
+			break
+
+		var section_id := payload[offset]
+		var section_len := _read_uint32(payload, offset + 1)
+
+		if offset + 5 + section_len > payload.size():
+			break
+
+		var section_data := payload.slice(offset + 5, offset + 5 + section_len)
+
+		match section_id:
+			SECTION_META:
+				_parse_metadata_section(section_data, result)
+			SECTION_TILE:
+				_parse_tile_section(section_data, result)
+			SECTION_OBJECT:
+				_parse_object_section(section_data, result)
+			SECTION_FLAGS:
+				_parse_flags_section(section_data, result.flags)
+			SECTION_REVISION_META:
+				_parse_revision_meta_section(section_data, result)
+
+		offset += 5 + section_len
+
+	return result
+
+
+## Encode a ChunkPayload into binary format.
+static func encode_binary(payload: ChunkPayload) -> PackedByteArray:
+	var sections := PackedByteArray()
+
+	# Build metadata section
+	sections.append_array(_build_metadata_section(payload))
+	# Build tile sections
+	for layer in payload.tile_layers:
+		sections.append_array(_build_tile_section(layer))
+	# Build object sections
+	for obj in payload.objects:
+		sections.append_array(_build_object_section(obj))
+	# Build flags section
+	sections.append_array(_build_flags_section(payload.flags))
+	# Build revision meta section
+	sections.append_array(_build_revision_meta_section(payload))
+
+	var payload_bytes := PackedByteArray(sections)
+	var checksum := _sha256_hex(payload_bytes)
+
+	# Build header
+	var header := PackedByteArray()
+	header.append_array(MAGIC)
+	header.append_array(_write_uint16(1))  # version
+	header.append_array(_write_uint16(0))  # header_len (after this field)
+	header.append_array(_write_uint32(0))  # flags
+	header.append_array(_write_uint32(payload_bytes.size()))
+	header.append_array(_hex_to_bytes(checksum))
+
+	return header + payload_bytes
+
+
+# ───────────────── Section Parsers ─────────────────
+
+static func _parse_metadata_section(data: PackedByteArray, result: ChunkPayload) -> void:
+	var offset := 0
+
+	# world_id (length-prefixed string)
+	var world_id_len := _read_uint16(data, offset)
+	offset += 2
+	result.world_id = data.slice(offset, offset + world_id_len).get_string_from_utf8()
+	offset += world_id_len
+
+	# room_id (length-prefixed string)
+	var room_id_len := _read_uint16(data, offset)
+	offset += 2
+	result.room_id = data.slice(offset, offset + room_id_len).get_string_from_utf8()
+	offset += room_id_len
+
+	# coord (3 × int32)
+	result.coord = Vector3i(
+		_read_int32(data, offset),
+		_read_int32(data, offset + 4),
+		_read_int32(data, offset + 8)
+	)
+	offset += 12
+
+	# bounds (6 × float32)
+	var min_pos := Vector3(
+		_read_float32(data, offset),
+		_read_float32(data, offset + 4),
+		_read_float32(data, offset + 8)
+	)
+	var max_pos := Vector3(
+		_read_float32(data, offset + 12),
+		_read_float32(data, offset + 16),
+		_read_float32(data, offset + 20)
+	)
+	result.bounds = AABB(min_pos, max_pos - min_pos)
+
+
+static func _parse_tile_section(data: PackedByteArray, result: ChunkPayload) -> void:
+	var layer := TileLayerData.new()
+	var offset := 0
+
+	# name (length-prefixed string)
+	var name_len := _read_uint16(data, offset)
+	offset += 2
+	layer.name = data.slice(offset, offset + name_len).get_string_from_utf8()
+	offset += name_len
+
+	# layer_id (uint16)
+	layer.layer_id = _read_uint16(data, offset)
+	offset += 2
+
+	# dimensions (3 × uint16)
+	layer.width = _read_uint16(data, offset)
+	offset += 2
+	layer.height = _read_uint16(data, offset)
+	offset += 2
+	layer.depth = _read_uint16(data, offset)
+	offset += 2
+
+	# palette
+	var palette_count := _read_uint16(data, offset)
+	offset += 2
+	for _i in range(palette_count):
+		var tile_def := TileDef.new()
+		tile_def.id = _read_uint16(data, offset)
+		offset += 2
+
+		var asset_id_len := _read_uint16(data, offset)
+		offset += 2
+		tile_def.asset_id = data.slice(offset, offset + asset_id_len).get_string_from_utf8()
+		offset += asset_id_len
+
+		tile_def.solid = data[offset] != 0
+		offset += 1
+
+		tile_def.flags = _read_uint32(data, offset)
+		offset += 4
+
+		tile_def.variants = data[offset]
+		offset += 1
+
+		layer.palette.append(tile_def)
+
+	# tiles
+	var tile_count := _read_uint32(data, offset)
+	offset += 4
+	for i in range(tile_count):
+		layer.tiles.append(_read_uint16(data, offset))
+		offset += 2
+
+	result.tile_layers.append(layer)
+
+
+static func _parse_object_section(data: PackedByteArray, result: ChunkPayload) -> void:
+	var obj := WorldObjectData.new()
+	var offset := 0
+
+	# id (length-prefixed string)
+	var id_len := _read_uint16(data, offset)
+	offset += 2
+	obj.id = data.slice(offset, offset + id_len).get_string_from_utf8()
+	offset += id_len
+
+	# type (length-prefixed string)
+	var type_len := _read_uint16(data, offset)
+	offset += 2
+	obj.type = data.slice(offset, offset + type_len).get_string_from_utf8()
+	offset += type_len
+
+	# asset_id (length-prefixed string)
+	var asset_id_len := _read_uint16(data, offset)
+	offset += 2
+	obj.asset_id = data.slice(offset, offset + asset_id_len).get_string_from_utf8()
+	offset += asset_id_len
+
+	# position (3 × float32)
+	obj.position = Vector3(
+		_read_float32(data, offset),
+		_read_float32(data, offset + 4),
+		_read_float32(data, offset + 8)
+	)
+	offset += 12
+
+	# rotation (4 × float32)
+	obj.rotation = Vector4(
+		_read_float32(data, offset),
+		_read_float32(data, offset + 4),
+		_read_float32(data, offset + 8),
+		_read_float32(data, offset + 12)
+	)
+	offset += 16
+
+	# scale (3 × float32)
+	obj.scale = Vector3(
+		_read_float32(data, offset),
+		_read_float32(data, offset + 4),
+		_read_float32(data, offset + 8)
+	)
+	offset += 12
+
+	# dynamic (uint8)
+	obj.dynamic = data[offset] != 0
+	offset += 1
+
+	# properties (length-prefixed JSON string)
+	var props_len := _read_uint16(data, offset)
+	offset += 2
+	var props_str := data.slice(offset, offset + props_len).get_string_from_utf8()
+	offset += props_len
+	obj.properties = JSON.parse_string(props_str) or {}
+
+	# flags (ContentFlags)
+	obj.flags.violence = data[offset]
+	offset += 1
+	obj.flags.sexual = data[offset]
+	offset += 1
+	obj.flags.language = data[offset]
+	offset += 1
+	obj.flags.substance = data[offset]
+	offset += 1
+	obj.flags.gambling = data[offset]
+	offset += 1
+	obj.flags.horror = data[offset]
+	offset += 1
+	obj.flags.hate = data[offset]
+	offset += 1
+	obj.flags.custom = data[offset]
+	offset += 1
+	obj.flags.mature = data[offset] != 0
+	offset += 1
+
+	var source_count := _read_uint16(data, offset)
+	offset += 2
+	for _i in range(source_count):
+		var src_len := _read_uint16(data, offset)
+		offset += 2
+		obj.flags.sources.append(data.slice(offset, offset + src_len).get_string_from_utf8())
+		offset += src_len
+
+	result.objects.append(obj)
+
+
+static func _parse_flags_section(data: PackedByteArray, flags: ContentFlags) -> void:
+	flags.violence = data[0]
+	flags.sexual = data[1]
+	flags.language = data[2]
+	flags.substance = data[3]
+	flags.gambling = data[4]
+	flags.horror = data[5]
+	flags.hate = data[6]
+	flags.custom = data[7]
+	flags.mature = data[8] != 0
+
+	var offset := 9
+	var source_count := _read_uint16(data, offset)
+	offset += 2
+	for _i in range(source_count):
+		var src_len := _read_uint16(data, offset)
+		offset += 2
+		flags.sources.append(data.slice(offset, offset + src_len).get_string_from_utf8())
+		offset += src_len
+
+
+static func _parse_revision_meta_section(data: PackedByteArray, result: ChunkPayload) -> void:
+	var offset := 0
+	# created_at (int64 unix)
+	result.created_at = _read_int64(data, offset)
+	offset += 8
+	# updated_at (int64 unix)
+	result.updated_at = _read_int64(data, offset)
+	offset += 8
+	# revision (uint32)
+	result.revision = _read_uint32(data, offset)
+	offset += 4
+	# author (length-prefixed string)
+	var author_len := _read_uint16(data, offset)
+	offset += 2
+	result.author = data.slice(offset, offset + author_len).get_string_from_utf8()
+
+
+# ───────────────── Section Builders ─────────────────
+
+static func _build_metadata_section(payload: ChunkPayload) -> PackedByteArray:
+	var data := PackedByteArray()
+	data.append_array(_write_string(payload.world_id))
+	data.append_array(_write_string(payload.room_id))
+	data.append_array(_write_int32(payload.coord.x))
+	data.append_array(_write_int32(payload.coord.y))
+	data.append_array(_write_int32(payload.coord.z))
+	data.append_array(_write_float32(payload.bounds.position.x))
+	data.append_array(_write_float32(payload.bounds.position.y))
+	data.append_array(_write_float32(payload.bounds.position.z))
+	data.append_array(_write_float32(payload.bounds.size.x))
+	data.append_array(_write_float32(payload.bounds.size.y))
+	data.append_array(_write_float32(payload.bounds.size.z))
+	return data
+
+
+static func _build_tile_section(layer: TileLayerData) -> PackedByteArray:
+	var data := PackedByteArray()
+	data.append_array(_write_string(layer.name))
+	data.append_array(_write_uint16(layer.layer_id))
+	data.append_array(_write_uint16(layer.width))
+	data.append_array(_write_uint16(layer.height))
+	data.append_array(_write_uint16(layer.depth))
+	data.append_array(_write_uint16(layer.palette.size()))
+
+	for tile_def in layer.palette:
+		data.append_array(_write_uint16(tile_def.id))
+		data.append_array(_write_string(tile_def.asset_id))
+		data.append(tile_def.solid as int)
+		data.append_array(_write_uint32(tile_def.flags))
+		data.append(tile_def.variants)
+
+	data.append_array(_write_uint32(layer.tiles.size()))
+	for tile_id in layer.tiles:
+		data.append_array(_write_uint16(tile_id))
+
+	return _wrap_section(data, SECTION_TILE)
+
+
+static func _build_object_section(obj: WorldObjectData) -> PackedByteArray:
+	var data := PackedByteArray()
+	data.append_array(_write_string(obj.id))
+	data.append_array(_write_string(obj.type))
+	data.append_array(_write_string(obj.asset_id))
+	data.append_array(_write_float32(obj.position.x))
+	data.append_array(_write_float32(obj.position.y))
+	data.append_array(_write_float32(obj.position.z))
+	data.append_array(_write_float32(obj.rotation.x))
+	data.append_array(_write_float32(obj.rotation.y))
+	data.append_array(_write_float32(obj.rotation.z))
+	data.append_array(_write_float32(obj.rotation.w))
+	data.append_array(_write_float32(obj.scale.x))
+	data.append_array(_write_float32(obj.scale.y))
+	data.append_array(_write_float32(obj.scale.z))
+	data.append(obj.dynamic as int)
+
+	var props_json := JSON.stringify(obj.properties, "  ")
+	data.append_array(_write_string(props_json))
+
+	data.append(obj.flags.violence)
+	data.append(obj.flags.sexual)
+	data.append(obj.flags.language)
+	data.append(obj.flags.substance)
+	data.append(obj.flags.gambling)
+	data.append(obj.flags.horror)
+	data.append(obj.flags.hate)
+	data.append(obj.flags.custom)
+	data.append(obj.flags.mature as int)
+	data.append_array(_write_uint16(obj.flags.sources.size()))
+	for src in obj.flags.sources:
+		data.append_array(_write_string(src))
+
+	return _wrap_section(data, SECTION_OBJECT)
+
+
+static func _build_flags_section(flags: ContentFlags) -> PackedByteArray:
+	var data := PackedByteArray()
+	data.append(flags.violence)
+	data.append(flags.sexual)
+	data.append(flags.language)
+	data.append(flags.substance)
+	data.append(flags.gambling)
+	data.append(flags.horror)
+	data.append(flags.hate)
+	data.append(flags.custom)
+	data.append(flags.mature as int)
+	data.append_array(_write_uint16(flags.sources.size()))
+	for src in flags.sources:
+		data.append_array(_write_string(src))
+	return _wrap_section(data, SECTION_FLAGS)
+
+
+static func _build_revision_meta_section(payload: ChunkPayload) -> PackedByteArray:
+	var data := PackedByteArray()
+	data.append_array(_write_int64(payload.created_at))
+	data.append_array(_write_int64(payload.updated_at))
+	data.append_array(_write_uint32(payload.revision))
+	data.append_array(_write_string(payload.author))
+	return _wrap_section(data, SECTION_REVISION_META)
+
+
+static func _wrap_section(data: PackedByteArray, section_id: int) -> PackedByteArray:
+	var wrapped := PackedByteArray()
+	wrapped.append(section_id)
+	wrapped.append_array(_write_uint32(data.size()))
+	wrapped.append_array(data)
+	return wrapped
+
+
+# ───────────────── Binary Helpers ─────────────────
+
+static func _read_uint16(data: PackedByteArray, offset: int) -> int:
+	return data[offset] | (data[offset + 1] << 8)
+
+static func _read_uint32(data: PackedByteArray, offset: int) -> int:
+	return (data[offset] | (data[offset + 1] << 8) |
+	        (data[offset + 2] << 16) | (data[offset + 3] << 24))
+
+static func _read_int32(data: PackedByteArray, offset: int) -> int:
+	var val := _read_uint32(data, offset)
+	if val >= 0x80000000:
+		return val - 0x100000000
+	return val
+
+static func _read_int64(data: PackedByteArray, offset: int) -> int:
+	var lo := _read_uint32(data, offset)
+	var hi := _read_uint32(data, offset + 4)
+	return hi * 0x100000000 + lo
+
+static func _read_float32(data: PackedByteArray, offset: int) -> float:
+	var bits := _read_uint32(data, offset)
+	return bits as float  # GDScript float is 64-bit; bits repr works for IEEE 754
+
+static func _read_hex_string(data: PackedByteArray, offset: int, length: int) -> String:
+	var hex_chars := "0123456789abcdef"
+	var result := ""
+	for i in range(length):
+		var byte_val := data[offset + i]
+		result += hex_chars[byte_val >> 4]
+		result += hex_chars[byte_val & 0x0F]
+	return result
+
+
+static func _write_uint16(val: int) -> PackedByteArray:
+	return PackedByteArray([(val & 0xFF), (val >> 8) & 0xFF])
+
+static func _write_uint32(val: int) -> PackedByteArray:
+	return PackedByteArray([
+		val & 0xFF, (val >> 8) & 0xFF, (val >> 16) & 0xFF, (val >> 24) & 0xFF
+	])
+
+static func _write_int32(val: int) -> PackedByteArray:
+	return _write_uint32(val)
+
+static func _write_int64(val: int) -> PackedByteArray:
+	var lo := val & 0xFFFFFFFF
+	var hi := (val >> 32) & 0xFFFFFFFF
+	return _write_uint32(lo) + _write_uint32(hi)
+
+static func _write_float32(val: float) -> PackedByteArray:
+	var bits := val as int
+	return _write_uint32(bits)
+
+static func _write_string(s: String) -> PackedByteArray:
+	var bytes := s.to_utf8_buffer()
+	return _write_uint16(bytes.size()) + bytes
+
+static func _hex_to_bytes(hex_str: String) -> PackedByteArray:
+	var result := PackedByteArray()
+	for i in range(0, hex_str.length(), 2):
+		var byte_val := ("0x" + hex_str.substr(i, 2)).hex_to_int()
+		result.append(byte_val)
+	return result
+
+
+# ───────────────── SHA-256 ─────────────────
+
+static func _sha256_hex(data: PackedByteArray) -> String:
+	var ctx := HashingContext.new()
+	ctx.start(HashingContext.HASH_SHA256)
+	ctx.update(data)
+	var hash := ctx.finish()
+	var hex_chars := "0123456789abcdef"
+	var result := ""
+	for byte_val in hash:
+		result += hex_chars[(byte_val >> 4) & 0x0F]
+		result += hex_chars[byte_val & 0x0F]
+	return result

scripts/chunk_data_decoder.gd.uid

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

scripts/chunk_scene.gd

@@ -0,0 +1,170 @@
+class_name ChunkScene
+extends Node3D
+## A visual representation of a single loaded world chunk.
+##
+## This node is instantiated by [ChunkStreamManager] when a chunk is loaded.
+## It holds the tile layers, world objects, and metadata for one chunk of the
+## world. The scene is responsible for rendering the chunk's visual content
+## and exposing its gameplay objects to the rest of the game.
+##
+## ## Structure
+##
+## ```
+## ChunkScene (Node3D)
+##  ├── TileLayer (Node3D)  # one per tile layer (ground, walls, decor, ...)
+##  ├── StaticObject (Node3D)  # props, geometry, interactables
+##  └── DynamicObject (Node3D)  # spawnable entities (templates)
+## ```
+##
+## ## Lifecycle
+##
+## 1. [ChunkStreamManager] requests chunk data from the server.
+## 2. Server responds with binary payload.
+## 3. [ChunkStreamManager] decodes the payload and creates a [ChunkScene].
+## 4. [ChunkScene] populates itself with tile layers and objects.
+## 5. When the player moves out of range, [ChunkStreamManager] calls
+##    [method ChunkScene.queue_free] to unload it.
+
+## The chunk coordinate this scene represents.
+var coord: Vector3i = Vector3i.ZERO
+
+## The canonical chunk key.
+var key: String = ""
+
+## World-space bounding box of this chunk.
+var bounds: AABB = AABB()
+
+## Format version of the chunk data.
+var format_version: int = 1
+
+## Revision counter from the server.
+var revision: int = 0
+
+## List of tile layers in this chunk.
+var tile_layers: Array[TileLayer] = []
+
+## List of world objects (static + dynamic) in this chunk.
+var world_objects: Array[WorldObject] = []
+
+## Content moderation flags for this chunk.
+var content_flags: ChunkDataDecoder.ContentFlags = ChunkDataDecoder.ContentFlags.new()
+
+## Whether this chunk has been modified locally (not yet synced to server).
+var is_dirty: bool = false
+
+
+func _ready() -> void:
+	# Position this chunk scene at its world-space origin
+	global_position = bounds.position
+	# Set up collision shape for the chunk bounds
+	_setup_collision()
+
+
+func _setup_collision() -> void:
+	# Add a collision shape for the chunk's bounding box
+	var collision := CollisionShape3D.new()
+	var shape := BoxShape3D.new()
+	shape.size = bounds.size
+	collision.shape = shape
+	collision.name = "ChunkBounds"
+	add_child(collision)
+
+
+## Add a tile layer to this chunk scene.
+func add_tile_layer(layer: TileLayer) -> void:
+	tile_layers.append(layer)
+	var layer_node := TileLayerNode.new()
+	layer_node.tile_layer = layer
+	layer_node.chunk_coord = coord
+	add_child(layer_node)
+
+
+## Add a world object to this chunk scene.
+func add_object(obj: WorldObject) -> void:
+	world_objects.append(obj)
+	if obj.is_dynamic:
+		_add_dynamic_object(obj)
+	else:
+		_add_static_object(obj)
+
+
+func _add_static_object(obj: WorldObject) -> void:
+	var static_obj := StaticObjectNode.new()
+	static_obj.world_object = obj
+	static_obj.position = obj.position
+	static_obj.quaternion = Quaternion(obj.rotation.x, obj.rotation.y, obj.rotation.z, obj.rotation.w)
+	static_obj.scale = obj.scale
+	static_obj.name = "static_%s" % obj.id
+	add_child(static_obj)
+
+
+func _add_dynamic_object(obj: WorldObject) -> void:
+	var dynamic_obj := DynamicObjectNode.new()
+	dynamic_obj.world_object = obj
+	dynamic_obj.position = obj.position
+	dynamic_obj.quaternion = Quaternion(obj.rotation.x, obj.rotation.y, obj.rotation.z, obj.rotation.w)
+	dynamic_obj.scale = obj.scale
+	dynamic_obj.name = "dynamic_%s" % obj.id
+	add_child(dynamic_obj)
+
+
+## Get a world object by its ID.
+func get_object_by_id(object_id: String) -> WorldObject:
+	for obj in world_objects:
+		if obj.id == object_id:
+			return obj
+	return null
+
+
+## Get all static objects in this chunk.
+func get_static_objects() -> Array[WorldObject]:
+	var result: Array[WorldObject] = []
+	for obj in world_objects:
+		if not obj.is_dynamic:
+			result.append(obj)
+	return result
+
+
+## Get all dynamic object templates in this chunk.
+func get_dynamic_templates() -> Array[WorldObject]:
+	var result: Array[WorldObject] = []
+	for obj in world_objects:
+		if obj.is_dynamic:
+			result.append(obj)
+	return result
+
+
+## Mark this chunk as dirty (locally modified).
+func mark_dirty() -> void:
+	is_dirty = true
+
+
+## Clear all objects and tile layers from this chunk.
+func clear() -> void:
+	for child in get_children():
+		if child is TileLayerNode or child is StaticObjectNode or child is DynamicObjectNode:
+			child.queue_free()
+	tile_layers.clear()
+	world_objects.clear()
+
+
+## Get the world-space position of a tile within this chunk.
+func get_tile_world_position(tile_x: int, tile_y: int, tile_z: int = 0) -> Vector3:
+	return bounds.position + Vector3(
+		tile_x * 1.0,  # Tile size is 1 world unit
+		tile_y * 1.0,
+		tile_z * 1.0
+	)
+
+
+## Check if a world-space position is within this chunk's bounds.
+func contains_position(pos: Vector3) -> bool:
+	return bounds.has_point(pos)
+
+
+## Check if a chunk coordinate is adjacent to this chunk.
+func is_adjacent(other_coord: Vector3i) -> bool:
+	var dx: int = abs(coord.x - other_coord.x)
+	var dy: int = abs(coord.y - other_coord.y)
+	var dz: int = abs(coord.z - other_coord.z)
+	return dx <= 1 and dy <= 1 and dz <= 1 and (dx + dy + dz) > 0

scripts/chunk_scene.gd.uid

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

scripts/chunk_stream_manager.gd

@@ -0,0 +1,358 @@
+class_name ChunkStreamManager
+extends Node
+## Manages loading and unloading of world chunks based on player position.
+##
+## This is the central orchestrator for the chunk streaming system. It monitors
+## the player's position, determines which chunks should be loaded, requests
+## chunk data from the server, instantiates ChunkScene nodes, and unloads
+## chunks that fall outside the streaming radius.
+##
+## ## Design
+##
+## - **Streaming radius** defines how many chunks around the player are kept
+##   loaded. Chunks beyond this radius are unloaded to save memory and CPU.
+## - **Load priority** ensures chunks closer to the player are loaded first,
+##   preventing visual pop-in at the edge of the view.
+## - **Server communication** uses the RPCs defined in docs/architecture/world.md
+##   (§5.3): `request_chunk`, `chunk_data`, `chunk_invalidated`.
+##
+## ## Usage
+##
+## Add this node to your scene tree and set the `player` reference:
+## ```gdscript
+## var stream_manager: ChunkStreamManager = $ChunkStreamManager
+## stream_manager.player = $Player
+## stream_manager.streaming_radius = 4  # chunks
+## ```
+
+## Number of chunks (radius) to keep loaded around the player.
+## A radius of 2 means a 5x5 grid of chunks centered on the player.
+## Higher values increase memory usage but reduce streaming pop-in.
+@export var streaming_radius: int = 3
+
+## Maximum number of chunks to load per frame. Prevents frame spikes during
+## rapid movement or when entering a new area.
+@export var max_loads_per_frame: int = 4
+
+## Maximum number of chunks to unload per frame.
+@export var max_unloads_per_frame: int = 4
+
+## Distance (in chunks) from the streaming radius edge before a chunk is
+## considered for unloading. Prevents rapid load/unload cycling.
+@export var unload_margin: int = 1
+
+## Emitted when a chunk finishes loading.
+signal chunk_loaded(chunk_coord: Vector3i, chunk_scene: Node)
+
+## Emitted when a chunk is unloaded.
+signal chunk_unloaded(chunk_coord: Vector3i)
+
+## Emitted when a chunk fails to load (e.g., server error).
+signal chunk_load_failed(chunk_coord: Vector3i, error: String)
+
+## Emitted when the player moves far enough to require a streaming update.
+signal streaming_updated
+
+## Reference to the player node. Must be set before the manager starts.
+var player: Node3D = null
+
+## The current player chunk coordinate.
+var _player_chunk_coord: Vector3i = Vector3i.ZERO
+
+## Map of loaded chunk coordinates to their scene nodes.
+var _loaded_chunks: Dictionary = {}
+
+## Queue of chunk coordinates pending load, sorted by distance from player.
+var _load_queue: Array[Vector3i] = []
+
+## Queue of chunk coordinates pending unload.
+var _unload_queue: Array[Vector3i] = []
+
+## Whether streaming is currently active (player is set and in game).
+var is_active: bool = false
+
+## The server RPC interface for chunk data. Set by the networking layer.
+var _server_rpc: Object = null
+
+## Internal: track which chunks are currently being loaded (to avoid duplicates).
+var _loading_in_progress: Dictionary = {}
+
+## Internal: time accumulator for throttled streaming updates.
+var _update_accumulator: float = 0.0
+
+## Internal: interval between streaming updates (seconds).
+const UPDATE_INTERVAL: float = 0.1
+
+
+func _ready() -> void:
+	# Streaming is driven from _process (main thread) so we can safely
+	# manipulate the scene tree. No background thread is used.
+	set_process(true)
+
+
+func _process(delta: float) -> void:
+	if not is_active or player == null:
+		return
+
+	_update_accumulator += delta
+	if _update_accumulator < UPDATE_INTERVAL:
+		return
+	_update_accumulator = 0.0
+
+	_update_streaming()
+	_process_load_queue()
+	_process_unload_queue()
+	streaming_updated.emit()
+
+
+func _update_streaming() -> void:
+	if player == null or not is_inside_tree():
+		return
+
+	var current_coord: Vector3i = Chunk.coord_for_position(player.global_position)
+	if current_coord == _player_chunk_coord:
+		return
+
+	_player_chunk_coord = current_coord
+	_rebuild_queues()
+
+
+func _rebuild_queues() -> void:
+	var target_set: Dictionary = _compute_target_chunks()
+
+	# Determine which chunks need to be loaded
+	var to_load: Array[Vector3i] = []
+	for coord in target_set:
+		if not _loaded_chunks.has(coord) and not _loading_in_progress.has(coord):
+			to_load.append(coord)
+
+	# Sort by distance from player (closest first)
+	to_load.sort_custom(_compare_distance)
+	_load_queue = to_load
+
+	# Determine which chunks need to be unloaded
+	var to_unload: Array[Vector3i] = []
+	for coord in _loaded_chunks:
+		if not target_set.has(coord):
+			to_unload.append(coord)
+
+	to_unload.sort_custom(_compare_distance)
+	_unload_queue = to_unload
+
+
+func _compute_target_chunks() -> Dictionary:
+	"""Compute the set of chunk coordinates that should be loaded."""
+	var target: Dictionary = {}
+	var half: int = streaming_radius
+	for dx in range(-half, half + 1):
+		for dy in range(-half, half + 1):
+			for dz in range(-half, half + 1):
+				var coord: Vector3i = Vector3i(
+					_player_chunk_coord.x + dx,
+					_player_chunk_coord.y + dy,
+					_player_chunk_coord.z + dz
+				)
+				target[coord] = coord
+	return target
+
+
+func _compare_distance(a: Vector3i, b: Vector3i) -> bool:
+	"""Compare chunk coordinates by distance from player chunk."""
+	var dist_a: int = _chunk_distance_squared(_player_chunk_coord, a)
+	var dist_b: int = _chunk_distance_squared(_player_chunk_coord, b)
+	return dist_a < dist_b
+
+
+func _chunk_distance_squared(a: Vector3i, b: Vector3i) -> int:
+	var dx: int = a.x - b.x
+	var dy: int = a.y - b.y
+	var dz: int = a.z - b.z
+	return dx * dx + dy * dy + dz * dz
+
+
+func _process_load_queue() -> void:
+	var count: int = 0
+	while count < max_loads_per_frame and not _load_queue.is_empty():
+		var coord: Vector3i = _load_queue.pop_front()
+		_load_chunk(coord)
+		count += 1
+
+
+func _process_unload_queue() -> void:
+	var count: int = 0
+	while count < max_unloads_per_frame and not _unload_queue.is_empty():
+		var coord: Vector3i = _unload_queue.pop_front()
+		_unload_chunk(coord)
+		count += 1
+
+
+func _load_chunk(coord: Vector3i) -> void:
+	if _loading_in_progress.has(coord):
+		return
+
+	_loading_in_progress[coord] = true
+
+	# Request chunk data from server via RPC
+	if _server_rpc != null and _server_rpc.has_method("request_chunk"):
+		_server_rpc.request_chunk(Chunk.build_key(
+			"", "", coord
+		))
+	else:
+		# Fallback: try to load from local cache or create empty chunk
+		_instantiate_chunk_scene(coord)
+
+
+func _on_chunk_data_received(key: String, binary_data: PackedByteArray) -> void:
+	"""Called by the networking layer when chunk data arrives from server."""
+	var coord: Vector3i = _parse_coord_from_key(key)
+	if coord == null:
+		return
+
+	_loading_in_progress.erase(coord)
+
+	# Decode the binary chunk data
+	var chunk_data: ChunkDataDecoder.ChunkPayload = ChunkDataDecoder.decode_binary(binary_data)
+	if chunk_data == null:
+		chunk_load_failed.emit(coord, "Failed to decode chunk data")
+		return
+
+	# Instantiate the chunk scene with the decoded data
+	_instantiate_chunk_scene_with_data(coord, chunk_data)
+
+
+func _on_chunk_load_error(coord: Vector3i, error_msg: String) -> void:
+	"""Called when the server reports a chunk load error."""
+	_loading_in_progress.erase(coord)
+	chunk_load_failed.emit(coord, error_msg)
+
+
+func _instantiate_chunk_scene(coord: Vector3i) -> void:
+	"""Create an empty chunk scene for the given coordinate."""
+	var chunk_scene: ChunkScene = ChunkScene.new()
+	chunk_scene.coord = coord
+	chunk_scene.key = Chunk.build_key("", "", coord)
+	chunk_scene.bounds = Chunk.compute_bounds(coord)
+	_add_loaded_chunk(coord, chunk_scene)
+
+
+func _instantiate_chunk_scene_with_data(coord: Vector3i, data: ChunkDataDecoder.ChunkPayload) -> void:
+	"""Create a chunk scene populated with server data."""
+	var chunk_scene: ChunkScene = ChunkScene.new()
+	chunk_scene.coord = coord
+	chunk_scene.key = data.key
+	chunk_scene.bounds = data.bounds
+	chunk_scene.format_version = data.format_version
+	chunk_scene.revision = data.revision
+
+	# Add tiles
+	for layer in data.tile_layers:
+		var tile_layer: TileLayer = TileLayer.new()
+		tile_layer.name = layer.name
+		tile_layer.layer_id = layer.layer_id
+		tile_layer.width = layer.width
+		tile_layer.height = layer.height
+		tile_layer.depth = layer.depth
+		tile_layer.palette = layer.palette
+		tile_layer.tiles = layer.tiles
+		chunk_scene.add_tile_layer(tile_layer)
+
+	# Add objects
+	for obj_data in data.objects:
+		var world_obj: WorldObject = WorldObject.new()
+		world_obj.id = obj_data.id
+		world_obj.type = obj_data.type
+		world_obj.asset_id = obj_data.asset_id
+		world_obj.position = obj_data.position
+		world_obj.rotation = obj_data.rotation
+		world_obj.scale = obj_data.scale
+		world_obj.properties = obj_data.properties
+		world_obj.is_dynamic = obj_data.dynamic
+		world_obj.flags = obj_data.flags
+		chunk_scene.add_object(world_obj)
+
+	# Add content flags
+	chunk_scene.content_flags = data.flags
+
+	_add_loaded_chunk(coord, chunk_scene)
+
+
+func _add_loaded_chunk(coord: Vector3i, chunk_scene: Node) -> void:
+	_loaded_chunks[coord] = chunk_scene
+	add_child(chunk_scene)
+	_loading_in_progress.erase(coord)
+	chunk_loaded.emit(coord, chunk_scene)
+
+
+func _unload_chunk(coord: Vector3i) -> void:
+	if not _loaded_chunks.has(coord):
+		return
+
+	var chunk_scene: Node = _loaded_chunks[coord]
+	if is_instance_valid(chunk_scene):
+		chunk_scene.queue_free()
+
+	_loaded_chunks.erase(coord)
+	chunk_unloaded.emit(coord)
+
+
+func _on_player_position_changed() -> void:
+	"""Call this when the player position changes significantly."""
+	if player != null:
+		_update_streaming()
+
+
+func set_server_rpc(rpc_interface: Object) -> void:
+	"""Set the server RPC interface for chunk requests."""
+	_server_rpc = rpc_interface
+
+
+func get_loaded_chunk(coord: Vector3i) -> Node:
+	"""Get a loaded chunk scene by coordinate, or null if not loaded."""
+	return _loaded_chunks.get(coord, null)
+
+
+func is_chunk_loaded(coord: Vector3i) -> bool:
+	"""Check if a chunk is currently loaded."""
+	return _loaded_chunks.has(coord)
+
+
+func get_loaded_chunk_count() -> int:
+	"""Get the number of currently loaded chunks."""
+	return _loaded_chunks.size()
+
+
+func get_all_loaded_coords() -> Array[Vector3i]:
+	"""Get all currently loaded chunk coordinates."""
+	var coords: Array[Vector3i] = []
+	for key in _loaded_chunks:
+		coords.append(key)
+	return coords
+
+
+func force_reload_chunk(coord: Vector3i) -> void:
+	"""Force reload a specific chunk (e.g., after server update)."""
+	if _loaded_chunks.has(coord):
+		_unload_chunk(coord)
+	if not _loading_in_progress.has(coord):
+		_load_chunk(coord)
+
+
+func clear_all_chunks() -> void:
+	"""Unload all chunks immediately."""
+	var coords: Array[Vector3i] = get_all_loaded_coords()
+	for coord in coords:
+		_unload_chunk(coord)
+	_load_queue.clear()
+	_unload_queue.clear()
+
+
+func _parse_coord_from_key(key: String) -> Variant:
+	"""Parse chunk coordinate from a canonical chunk key."""
+	var parts: Array[String] = key.split(":")
+	if parts.size() < 5:
+		return null
+	return Vector3i(
+		int(parts[2]),
+		int(parts[3]),
+		int(parts[4])
+	)

scripts/chunk_stream_manager.gd.uid

@@ -0,0 +1 @@
+uid://8yokqwe23c23

scripts/dynamic_object_node.gd

@@ -0,0 +1,68 @@
+class_name DynamicObjectNode
+extends Node3D
+## A visual representation of a dynamic (spawnable) world object template.
+##
+## This node is instantiated by [ChunkScene] for each dynamic [WorldObject].
+## Dynamic objects are stored as *templates* in the chunk; their runtime state
+## (position, health, inventory) is managed by the entity system, not by this
+## node. This node renders the template's visual representation so the object
+## is visible in the world.
+##
+## ## Structure
+##
+## ```
+## DynamicObjectNode (Node3D)
+##  └── MeshInstance3D  # the object's visual mesh
+## ```
+
+## The world object data this node represents.
+var world_object: WorldObject = null
+
+## The loaded mesh instance (or placeholder).
+var _mesh_instance: MeshInstance3D = null
+
+
+func _ready() -> void:
+	if world_object == null:
+		return
+	_load_mesh()
+
+
+## Load and attach the object's mesh.
+func _load_mesh() -> void:
+	_mesh_instance = MeshInstance3D.new()
+	_mesh_instance.name = "mesh"
+
+	var mesh := _load_asset_mesh(world_object.asset_id)
+	if mesh == null:
+		mesh = _make_placeholder_mesh()
+
+	_mesh_instance.mesh = mesh
+	add_child(_mesh_instance)
+
+
+## Attempt to load a mesh from the asset path.
+func _load_asset_mesh(asset_id: String) -> Mesh:
+	if asset_id.is_empty():
+		return null
+	var path := "res://assets/%s" % asset_id
+	if ResourceLoader.exists(path):
+		var res := load(path)
+		if res is Mesh:
+			return res
+	return null
+
+
+## Create a simple placeholder sphere mesh when the real asset is unavailable.
+func _make_placeholder_mesh() -> Mesh:
+	var mesh := SphereMesh.new()
+	mesh.radius = 0.5
+	mesh.height = 1.0
+	return mesh
+
+
+## Get the world object's display name.
+func get_display_name() -> String:
+	if world_object == null:
+		return ""
+	return world_object.get_display_name()

scripts/dynamic_object_node.gd.uid

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

scripts/main_menu.gd

@@ -0,0 +1,262 @@
+extends Control
+## Main menu with login/register UI wired to the backend auth API.
+##
+## The AuthPanel is hidden by default. When the user clicks the LoginButton or
+## RegisterButton (AuthButtonsRow, above the panel), the auth panel slides in.
+## The Login and Register buttons on the AuthButtonsRow directly set the panel's
+## mode, so the user can switch between Login and Register at any time while
+## the panel is open.
+##
+## On successful auth the token is stored via ApiClient, AuthButtonsRow hides,
+## the welcome label shows the username, and the Play button becomes enabled.
+## The auth form fields are hidden, leaving only the welcome message visible.
+##
+## When returning from another scene (e.g. world_list), _ready() checks whether
+## ApiClient already holds a valid token. If so, it restores the authenticated
+## UI state (Play enabled, welcome message visible) instead of forcing the user
+## back to the login form.
+
+
+## Emitted once _ready()'s session check (has_token() + the awaited
+## get_me() call) has actually resolved, whichever way -- lets a test (or
+## anything else) know the UI state is trustworthy now, rather than
+## guessing from a frame count or from UI properties that are ambiguous
+## mid-await (e.g. AuthButtonsRow.visible is true both before the check
+## resolves AND in a genuine logged-out end state).
+signal auth_state_ready
+
+# ─── UI references ────────────────────────────────────────────────────────────
+
+var _auth_buttons_row: HBoxContainer
+var _login_button: Button
+var _register_button: Button
+var _auth_panel: PanelContainer
+var _auth_mode_label: Label
+var _username_edit: LineEdit
+var _password_edit: LineEdit
+var _email_edit: LineEdit
+var _over_18_check: CheckBox
+var _auth_button: Button
+var _status_label: Label
+var _welcome_label: Label
+var _play_button: Button
+var _quit_button: Button
+
+var _is_register_mode: bool = false
+var _is_authenticating: bool = false
+
+
+# ─── Lifecycle ────────────────────────────────────────────────────────────────
+
+func _ready() -> void:
+	# Cache node references.
+	_auth_buttons_row = $CenterContainer/VBoxContainer/AuthButtonsRow
+	_login_button = $CenterContainer/VBoxContainer/AuthButtonsRow/LoginButton
+	_register_button = $CenterContainer/VBoxContainer/AuthButtonsRow/RegisterButton
+	_auth_panel = $CenterContainer/VBoxContainer/AuthPanel
+	_auth_mode_label = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthModeLabel
+	_username_edit = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/UsernameEdit
+	_password_edit = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/PasswordEdit
+	_email_edit = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/EmailEdit
+	_over_18_check = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/Over18Check
+	_auth_button = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthButton
+	_status_label = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthStatusLabel
+	_welcome_label = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/WelcomeLabel
+	_play_button = $CenterContainer/VBoxContainer/PlayButton
+	_quit_button = $CenterContainer/VBoxContainer/QuitButton
+
+	# Default to Play being gated. When a token exists, the async session
+	# check below may take several frames (a real get_me() round-trip);
+	# keeping the button disabled until validation succeeds prevents a fast
+	# click from navigating to world_list with an expired/invalid token.
+	_play_button.disabled = true
+
+	# Check whether a valid session already exists (e.g. user logged in,
+	# navigated to world_list, then clicked Back). If so, restore the
+	# authenticated UI state instead of forcing the login form again.
+	if ApiClient.has_token():
+		var me_result: Dictionary = await ApiClient.get_me()
+		if me_result.ok and me_result.data is Dictionary:
+			var username: String = str((me_result.data as Dictionary).get("username", ""))
+			if username != "":
+				_show_authenticated(username)
+				auth_state_ready.emit()
+				return
+
+	# Token missing or invalid — fall through to logged-out state.
+	_reset_to_logged_out()
+	auth_state_ready.emit()
+
+
+## Restore the UI to the authenticated state (Play enabled, welcome message
+## visible, auth buttons hidden). AuthPanel itself stays visible -- the
+## welcome label lives inside it, so hiding the panel hides the label too
+## even when the label's own `visible` is true (real bug, 2026-08-20: a
+## review caught the panel being hidden here while the label claimed to be
+## visible, which is a no-op UI-wise since Control.visible doesn't override
+## an ancestor's hidden state).
+func _show_authenticated(username: String) -> void:
+	_auth_panel.visible = true
+	_status_label.visible = false
+	_welcome_label.text = "Welcome, %s!" % username
+	_welcome_label.visible = true
+	# Hide the same full set of form fields _on_auth_complete() hides right
+	# after a fresh login/register -- this path (session restore on scene
+	# reload, e.g. after Play -> Back) used to only hide EmailEdit/
+	# Over18Check, leaving UsernameEdit/PasswordEdit/AuthButton/
+	# AuthModeLabel visible on top of the welcome message. Real bug: Play
+	# was enabled and the welcome label was correct, so it wasn't caught by
+	# checks for those alone -- the login fields being back on screen is
+	# what a user actually sees as "it's making me log in again."
+	_username_edit.visible = false
+	_password_edit.visible = false
+	_email_edit.visible = false
+	_over_18_check.visible = false
+	_auth_button.visible = false
+	_auth_mode_label.visible = false
+	_play_button.disabled = false
+	_auth_buttons_row.visible = false
+	print("Restored authenticated session for: ", username)
+
+
+## Reset the UI to the logged-out state (Play disabled, auth panel hidden,
+## login/register buttons visible).
+func _reset_to_logged_out() -> void:
+	_auth_panel.visible = false
+	_status_label.visible = false
+	_welcome_label.visible = false
+	_email_edit.visible = false
+	_over_18_check.visible = false
+	_over_18_check.button_pressed = false
+	_play_button.disabled = true  # Gate play behind successful auth.
+	_update_auth_mode_ui()
+
+
+# ─── Play / Quit ──────────────────────────────────────────────────────────────
+
+func _on_play_button_pressed() -> void:
+	if _play_button.disabled:
+		return
+	# Browse worlds is the first real screen past login -- actual gameplay
+	# (joining a world) doesn't exist yet, browsing does.
+	get_tree().change_scene_to_file("res://scenes/world_list.tscn")
+
+
+func _on_quit_button_pressed() -> void:
+	get_tree().quit()
+
+
+# ─── Auth panel toggle ────────────────────────────────────────────────────────
+
+func _on_login_button_pressed() -> void:
+	"""Show the auth panel in login mode, called from AuthButtonsRow/LoginButton."""
+	_auth_panel.visible = true
+	_is_register_mode = false
+	_update_auth_mode_ui()
+	_clear_status()
+	_username_edit.grab_focus()
+
+
+func _on_register_button_pressed() -> void:
+	"""Show the auth panel in register mode, called from AuthButtonsRow/RegisterButton."""
+	_auth_panel.visible = true
+	_is_register_mode = true
+	_update_auth_mode_ui()
+	_clear_status()
+	_username_edit.grab_focus()
+
+
+func _update_auth_mode_ui() -> void:
+	"""Update labels and field visibility based on login vs register mode."""
+	if _is_register_mode:
+		_auth_mode_label.text = "Register"
+		_auth_button.text = "Register"
+		_email_edit.visible = true
+		_over_18_check.visible = true
+	else:
+		_auth_mode_label.text = "Login"
+		_auth_button.text = "Login"
+		_email_edit.visible = false
+		_over_18_check.visible = false
+
+
+# ─── Auth submission ──────────────────────────────────────────────────────────
+
+func _on_auth_button_pressed() -> void:
+	"""Handle login or register button press."""
+	if _is_authenticating:
+		return
+
+	# Validate inputs.
+	var username := _username_edit.text.strip_edges()
+	var password := _password_edit.text
+
+	if username == "":
+		_show_status("Username is required.")
+		return
+	if password == "":
+		_show_status("Password is required.")
+		return
+
+	if _is_register_mode:
+		var email := _email_edit.text.strip_edges()
+
+		if email == "":
+			_show_status("Email is required.")
+			return
+		if not _over_18_check.button_pressed:
+			_show_status("You must confirm you are 18 or older to register.")
+			return
+
+		_auth_button.disabled = true
+		_auth_button.text = "Registering..."
+		_is_authenticating = true
+		_clear_status()
+
+		var result := await ApiClient.register(username, email, password, true)
+		_on_auth_complete(result)
+	else:
+		_auth_button.disabled = true
+		_auth_button.text = "Logging in..."
+		_is_authenticating = true
+		_clear_status()
+
+		var result := await ApiClient.login(username, password)
+		_on_auth_complete(result)
+
+
+func _on_auth_complete(result: Dictionary) -> void:
+	"""Handle the result of a login or register call."""
+	_auth_button.disabled = false
+	_auth_button.text = "Register" if _is_register_mode else "Login"
+	_is_authenticating = false
+
+	if result.ok:
+		# Success — hide the auth form fields, show only the welcome label.
+		_username_edit.visible = false
+		_password_edit.visible = false
+		_email_edit.visible = false
+		_over_18_check.visible = false
+		_auth_button.visible = false
+		_auth_mode_label.visible = false
+		_status_label.visible = false
+		_welcome_label.text = "Welcome, %s!" % _username_edit.text.strip_edges()
+		_welcome_label.visible = true
+		_play_button.disabled = false
+		_auth_buttons_row.visible = false
+		print("Auth successful. Token stored.")
+	else:
+		# Failure — show backend error detail.
+		_show_status(result.detail)
+
+
+# ─── Status helpers ───────────────────────────────────────────────────────────
+
+func _show_status(message: String) -> void:
+	_status_label.text = message
+	_status_label.visible = true
+
+
+func _clear_status() -> void:
+	_status_label.text = ""
+	_status_label.visible = false

scripts/main_menu.gd.uid

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

scripts/run_checkpoint_tests.py

@@ -0,0 +1,170 @@
+#!/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

@@ -0,0 +1,46 @@
+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)

scripts/smoke_test_auth.gd

@@ -0,0 +1,132 @@
+extends SceneTree
+## Headless smoke test for the AuthPanel login/register flow.
+##
+## Run with:
+##     godot --headless --path . --script res://scripts/smoke_test_auth.gd
+##
+## Requires the backend to be running (default base URL
+## `application/agp/api_base_url` -> http://127.0.0.1:8000).
+##
+## Tests:
+##   1. Register a unique user → 201 + token stored.
+##   2. Register the same user again → 409 "Username already registered".
+##   3. Register with over_18=false → 400 "Must be 18 or older".
+##   4. Login with correct credentials → 200 + token stored.
+##   5. Login with wrong password → 401 "Incorrect username or password".
+##   6. Login with non-existent user → 401 "Incorrect username or password".
+##
+## Exits 0 on full pass, 1 on any failure.
+
+const API_BASE := "http://127.0.0.1:8000"
+const TEST_USERNAME := "smoke_test_user_%d"
+const TEST_EMAIL := "smoke_%d@test.example.com"
+const TEST_PASSWORD := "SmokeTest123!"
+
+
+func _initialize() -> void:
+	_run()
+
+
+func _run() -> void:
+	# Wait for autoloads to be ready.
+	await process_frame
+
+	var api := root.get_node("ApiClient") as ApiClient
+	assert(api != null, "ApiClient autoload not found")
+
+	var passed: int = 0
+	var failed: int = 0
+
+	# --- Test 1: Register a unique user ---
+	randomize()
+	var unique_id: int = int(Time.get_unix_time_from_system() * 1000) + randi() % 100000
+	var username := "smoke_%d" % unique_id
+	var email := "smoke_%d@test.example.com" % unique_id
+
+	print("\n=== Test 1: Register unique user ===")
+	var result := await api.register(username, email, TEST_PASSWORD, true)
+	if _check("register returns ok", result.ok) \
+			and _check("register status is 201", result.status == 201) \
+			and _check("register stores token", api.has_token()):
+		passed += 1
+	else:
+		failed += 1
+		print("  detail: ", result.detail)
+
+	# --- Test 2: Register same user again (duplicate) ---
+	print("\n=== Test 2: Duplicate username ===")
+	result = await api.register(username, email, TEST_PASSWORD, true)
+	if _check("duplicate register not ok", not result.ok) \
+			and _check("duplicate status is 409", result.status == 409) \
+			and _check("duplicate detail mentions username",
+					"username" in result.detail.to_lower()):
+		passed += 1
+	else:
+		failed += 1
+		print("  detail: ", result.detail)
+
+	# --- Test 3: Register with over_18=false ---
+	print("\n=== Test 3: over_18=false registration ===")
+	var child_username := "child_%d" % unique_id
+	var child_email := "child_%d@test.example.com" % unique_id
+	result = await api.register(child_username, child_email, TEST_PASSWORD, false)
+	if _check("over_18=false register not ok", not result.ok) \
+			and _check("over_18=false status is 400", result.status == 400) \
+			and _check("over_18=false detail mentions age",
+					"18" in result.detail):
+		passed += 1
+	else:
+		failed += 1
+		print("  detail: ", result.detail)
+
+	# --- Test 4: Login with correct credentials ---
+	print("\n=== Test 4: Correct login ===")
+	result = await api.login(username, TEST_PASSWORD)
+	if _check("login returns ok", result.ok) \
+			and _check("login status is 200", result.status == 200) \
+			and _check("login stores token", api.has_token()):
+		passed += 1
+	else:
+		failed += 1
+		print("  detail: ", result.detail)
+
+	# --- Test 5: Login with wrong password ---
+	print("\n=== Test 5: Wrong password ===")
+	result = await api.login(username, "WrongPassword!")
+	if _check("wrong pwd login not ok", not result.ok) \
+			and _check("wrong pwd status is 401", result.status == 401) \
+			and _check("wrong pwd detail",
+					"Incorrect" in result.detail or "incorrect" in result.detail):
+		passed += 1
+	else:
+		failed += 1
+		print("  detail: ", result.detail)
+
+	# --- Test 6: Login with non-existent user ---
+	print("\n=== Test 6: Non-existent user ===")
+	result = await api.login("nonexistent_user_xyz", TEST_PASSWORD)
+	if _check("missing user login not ok", not result.ok) \
+			and _check("missing user status is 401", result.status == 401) \
+			and _check("missing user detail",
+					"Incorrect" in result.detail or "incorrect" in result.detail):
+		passed += 1
+	else:
+		failed += 1
+		print("  detail: ", result.detail)
+
+	# --- Summary ---
+	print("\n=== SMOKE RESULT: %d/%d passed ===" % [passed, passed + failed])
+	if failed > 0:
+		quit(1)
+	else:
+		print("SMOKE RESULT: ALL PASS")
+		quit(0)
+
+
+func _check(description: String, condition: bool) -> bool:
+	if condition:
+		print("  PASS: ", description)
+		return true
+	else:
+		printerr("  FAIL: ", description)
+		return false

scripts/smoke_test_e2e.gd

@@ -0,0 +1,147 @@
+extends SceneTree
+## End-to-end headless smoke test: register -> login -> fetch worlds list.
+##
+## Run with:
+##     godot --headless --path . --script res://scripts/smoke_test_e2e.gd
+##
+## Requires the backend to be running (default base URL
+## `application/agp/api_base_url` -> http://127.0.0.1:8000, overridable via
+## the AGP_API_BASE_URL environment variable).
+##
+## Steps:
+##   1. Health check  GET  /api/health          -> 200, {"status": "ok"}
+##   2. Register      POST /api/auth/register   -> 201, access_token present
+##   3. Login         POST /api/auth/login      -> 200, access_token present
+##   4. Worlds list   GET  /api/worlds          -> 200, JSON array
+##
+## Exits 0 if all steps pass, 1 otherwise. If the backend is unreachable the
+## health check fails with a clear message and the script exits 1 immediately.
+
+# Fixed credentials from the task spec. The username gets a unique numeric
+# suffix so the test stays re-runnable (a second run would otherwise hit
+# "Username already registered" on step 2).
+const TEST_USERNAME_BASE := "smoke_test_user"
+const TEST_EMAIL := "smoke@test.com"
+const TEST_PASSWORD := "TestPass123"
+
+
+func _initialize() -> void:
+	_run()
+
+
+func _run() -> void:
+	# _initialize() fires before the first frame; wait one frame so freshly
+	# created HTTPRequest nodes are reliably inside the tree.
+	await process_frame
+
+	# In --script mode the autoload is reachable via get_node(), not as a
+	# bare identifier (bare identifiers fail to resolve at compile time here).
+	var api := root.get_node("ApiClient")
+	assert(api != null, "ApiClient autoload not found in the scene tree")
+
+	var unique_id := int(Time.get_unix_time_from_system() * 1000)
+	var username := "%s_%d" % [TEST_USERNAME_BASE, unique_id]
+	var email := "smoke_%d@test.com" % unique_id
+
+	var results := {}
+
+	# --- Step 1: Health check -------------------------------------------------
+	print("\n=== Step 1: Health check (GET /api/health) ===")
+	var health: Dictionary = await api.health_check()
+	var health_ok: bool = (
+		health.ok
+		and health.status == 200
+		and health.data is Dictionary
+		and str((health.data as Dictionary).get("status", "")) == "ok"
+	)
+	_record(results, "health", health_ok, "status=%d data=%s" % [
+		health.status, health.data
+	])
+
+	if not health.ok or health.status == 0:
+		printerr("\nERROR: Backend is not reachable at the configured base URL.")
+		printerr("       detail: %s" % health.detail)
+		printerr("       Start the backend first (see backend/README), then re-run:")
+		printerr("       godot --headless --path . --script res://scripts/smoke_test_e2e.gd")
+		_summarize(results)
+		quit(1)
+		return
+
+	# --- Step 2: Register -----------------------------------------------------
+	print("\n=== Step 2: Register (POST /api/auth/register) ===")
+	var reg: Dictionary = await api.register(username, email, TEST_PASSWORD, true)
+	var reg_token := _extract_token(reg)
+	var reg_ok: bool = (
+		reg.ok
+		and reg.status == 201
+		and reg_token != ""
+	)
+	_record(results, "register", reg_ok, "status=%d token=%s detail=%s" % [
+		reg.status, "yes" if reg_token != "" else "no", reg.detail
+	])
+
+	# --- Step 3: Login --------------------------------------------------------
+	print("\n=== Step 3: Login (POST /api/auth/login) ===")
+	var login: Dictionary = await api.login(username, TEST_PASSWORD)
+	var login_token := _extract_token(login)
+	var login_ok: bool = (
+		login.ok
+		and login.status == 200
+		and login_token != ""
+	)
+	_record(results, "login", login_ok, "status=%d token=%s detail=%s" % [
+		login.status, "yes" if login_token != "" else "no", login.detail
+	])
+
+	# --- Step 4: Worlds list ---------------------------------------------------
+	print("\n=== Step 4: Worlds list (GET /api/worlds) ===")
+	# login/register already stored the token; make the auth header explicit by
+	# re-applying the extracted token so step 4 is independent of storage order.
+	if login_token != "":
+		api.set_token(login_token)
+	var worlds: Dictionary = await api.get_worlds()
+	var worlds_ok: bool = (
+		worlds.ok
+		and worlds.status == 200
+		and worlds.data is Array
+	)
+	_record(results, "worlds", worlds_ok, "status=%d is_array=%s count=%d detail=%s" % [
+		worlds.status,
+		"yes" if (worlds.data is Array) else "no",
+		(worlds.data as Array).size() if (worlds.data is Array) else -1,
+		worlds.detail,
+	])
+
+	# --- Summary ---------------------------------------------------------------
+	_summarize(results)
+
+
+func _extract_token(result: Dictionary) -> String:
+	if result.ok and result.data is Dictionary:
+		return str((result.data as Dictionary).get("access_token", ""))
+	return ""
+
+
+func _record(results: Dictionary, name: String, ok: bool, detail: String) -> void:
+	results[name] = {"ok": ok, "detail": detail}
+	if ok:
+		print("  PASS: %s" % detail)
+	else:
+		printerr("  FAIL: %s" % detail)
+
+
+func _summarize(results: Dictionary) -> void:
+	var all_pass := true
+	print("\n=== Smoke test summary ===")
+	for step in ["health", "register", "login", "worlds"]:
+		var entry: Dictionary = results.get(step, {"ok": false, "detail": "not run"})
+		if not entry["ok"]:
+			all_pass = false
+		print("  %-8s : %s" % [step, "PASS" if entry["ok"] else "FAIL"])
+
+	if all_pass:
+		print("SMOKE RESULT: ALL PASS (4/4)")
+		quit(0)
+	else:
+		printerr("SMOKE RESULT: FAIL")
+		quit(1)

scripts/smoke_test_main_menu_back.gd

@@ -0,0 +1,170 @@
+extends SceneTree
+## Regression test for the Play -> Back navigation bug.
+##
+## The reported bug: after logging in and clicking Play, the user lands on
+## world_list.tscn; clicking Back returns to main_menu.tscn, but the menu
+## reset to a fully logged-out state (Play disabled, login form showing)
+## even though ApiClient still held a valid token. main_menu.gd's _ready()
+## used to unconditionally reset the UI on every scene load.
+##
+## This test drives the real navigation flow (change_scene_to_file) against
+## a live backend:
+##   1. Register a unique user so ApiClient holds a valid token.
+##   2. Load main_menu.tscn and assert it restores the authenticated state.
+##   3. Click Play -> world_list.tscn.
+##   4. Click Back -> main_menu.tscn.
+##   5. Assert the menu is STILL authenticated (Play enabled, welcome label
+##      actually visible in the tree, login/register buttons hidden).
+##
+## Run with:
+##     godot --headless --path . --script res://scripts/smoke_test_main_menu_back.gd
+##
+## Requires the backend to be running (default base URL
+## `application/agp/api_base_url` -> http://127.0.0.1:8000).
+
+const USERNAME := "backnav_%d"
+const EMAIL := "backnav_%d@test.example.com"
+const PASSWORD := "BackNav123!"
+
+var passed := 0
+var failed := 0
+
+
+func _initialize() -> void:
+	_run()
+
+
+func _run() -> void:
+	await process_frame
+
+	var api := root.get_node("ApiClient")
+	if api == null:
+		printerr("FAIL: ApiClient autoload not found")
+		quit(1)
+		return
+
+	# 1. Establish a real, valid session exactly the way a user would.
+	randomize()
+	var unique_id: int = int(Time.get_unix_time_from_system() * 1000) + randi() % 100000
+	var username := USERNAME % unique_id
+	var email := EMAIL % unique_id
+	print("\n=== Setup: register ", username, " ===")
+	var register_result: Dictionary = await api.register(username, email, PASSWORD, true)
+	if not _check("register succeeds", register_result.ok):
+		print("  detail: ", register_result.detail)
+		_finish()
+		return
+	_check("ApiClient stores token after register", api.has_token())
+
+	# 2. First visit to the main menu: should already show the authenticated
+	#    state (no login form, Play enabled).
+	change_scene_to_file("res://scenes/main_menu.tscn")
+	# change_scene_to_file defers the actual swap -- a couple frames is
+	# plenty for the scene object itself to exist (unlike the real
+	# get_me() network round-trip afterward, which is what auth_state_ready
+	# actually waits for below).
+	for i in 5:
+		await process_frame
+		if current_scene is Control:
+			break
+
+	var menu: Control = current_scene
+	if menu == null or not menu is Control:
+		printerr("FAIL: main_menu.tscn did not become current_scene")
+		_finish()
+		return
+	await menu.auth_state_ready
+	_check("first main menu visit restores authenticated state", _is_authenticated(menu))
+
+	# 3. Play -> world_list.tscn (real button press).
+	var play_button: Button = menu.get_node("CenterContainer/VBoxContainer/PlayButton")
+	play_button.pressed.emit()
+	await _wait_for_scene_change(menu)
+
+	var world_list_scene := current_scene
+	if world_list_scene == null or world_list_scene == menu:
+		printerr("FAIL: world_list.tscn did not become current_scene after Play")
+		_finish()
+		return
+
+	# 4. Back -> main_menu.tscn (real button press).
+	var back_button: Button = world_list_scene.get_node("VBoxContainer/HeaderHBox/BackButton")
+	back_button.pressed.emit()
+	await _wait_for_scene_change(world_list_scene)
+
+	menu = current_scene
+	if menu == null or not menu is Control:
+		printerr("FAIL: main_menu.tscn did not become current_scene after Back")
+		_finish()
+		return
+
+	# The new main_menu instance's own _ready() is *also* awaiting a real
+	# get_me() call -- _wait_for_scene_change only confirms the scene
+	# object exists, not that its authenticated-state fields have been
+	# set yet. Wait for the real signal, not a guess.
+	await menu.auth_state_ready
+
+	# 5. THE regression assertion: still logged in after returning.
+	_check("main menu stays authenticated after Play -> Back", _is_authenticated(menu))
+
+	_finish()
+
+
+func _is_authenticated(menu: Control) -> bool:
+	var play_button: Button = menu.get_node("CenterContainer/VBoxContainer/PlayButton")
+	var welcome_label: Label = menu.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/WelcomeLabel")
+	var auth_buttons_row: HBoxContainer = menu.get_node("CenterContainer/VBoxContainer/AuthButtonsRow")
+	var auth_panel: PanelContainer = menu.get_node("CenterContainer/VBoxContainer/AuthPanel")
+	var username_edit: LineEdit = menu.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/UsernameEdit")
+	var password_edit: LineEdit = menu.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/PasswordEdit")
+	var auth_button: Button = menu.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthButton")
+	var auth_mode_label: Label = menu.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthModeLabel")
+
+	_check("Play enabled", not play_button.disabled)
+	# WelcomeLabel lives inside AuthPanel, so `.visible` alone is a
+	# false-positive: the label can have visible=true while its parent is
+	# hidden and it renders as nothing. `is_visible_in_tree()` is the
+	# check that proves the user can actually see the welcome message.
+	_check("Welcome label visible in tree", welcome_label.is_visible_in_tree())
+	_check("Auth buttons row hidden", not auth_buttons_row.visible)
+	_check("Auth panel visible (it contains the welcome label)", auth_panel.visible)
+	# Real bug, 2026-08-20: the session-restore path (this one, after
+	# Play -> Back) hid EmailEdit/Over18Check but never the rest of the
+	# login form -- Play enabled + welcome label visible were both still
+	# true, so a check that stopped there passed while the user was
+	# looking at the login fields again on top of the welcome message.
+	_check("Username field hidden", not username_edit.visible)
+	_check("Password field hidden", not password_edit.visible)
+	_check("Auth button hidden", not auth_button.visible)
+	_check("Auth mode label hidden", not auth_mode_label.visible)
+
+	return (not play_button.disabled) \
+		and welcome_label.is_visible_in_tree() \
+		and not auth_buttons_row.visible \
+		and auth_panel.visible \
+		and not username_edit.visible \
+		and not password_edit.visible \
+		and not auth_button.visible \
+		and not auth_mode_label.visible
+
+
+func _wait_for_scene_change(previous_scene: Node) -> void:
+	for i in 20:
+		await process_frame
+		if current_scene != previous_scene and current_scene != null:
+			return
+
+
+func _check(description: String, condition: bool) -> bool:
+	if condition:
+		print("  PASS: ", description)
+		passed += 1
+	else:
+		printerr("  FAIL: ", description)
+		failed += 1
+	return condition
+
+
+func _finish() -> void:
+	print("\n=== SMOKE RESULT: %d/%d passed ===" % [passed, passed + failed])
+	quit(0 if failed == 0 else 1)

scripts/smoke_test_main_menu_full_flow.gd

@@ -0,0 +1,86 @@
+extends SceneTree
+## Full click-through simulation of the real user flow: press Register,
+## fill the form exactly as a human would, submit, confirm Play actually
+## becomes clickable. Also verifies that after successful auth the auth
+## form fields are hidden, leaving only the welcome message visible.
+
+var passed := 0
+var failed := 0
+
+
+func _initialize() -> void:
+	_run()
+
+
+func _run() -> void:
+	await process_frame
+
+	var packed: PackedScene = load("res://scenes/main_menu.tscn")
+	var instance: Control = packed.instantiate()
+	root.add_child(instance)
+	await process_frame
+
+	var register_button: Button = instance.get_node("CenterContainer/VBoxContainer/AuthButtonsRow/RegisterButton")
+	var auth_buttons_row: HBoxContainer = instance.get_node("CenterContainer/VBoxContainer/AuthButtonsRow")
+	var username_edit: LineEdit = instance.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/UsernameEdit")
+	var password_edit: LineEdit = instance.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/PasswordEdit")
+	var email_edit: LineEdit = instance.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/EmailEdit")
+	var over_18_check: CheckBox = instance.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/Over18Check")
+	var auth_button: Button = instance.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthButton")
+	var auth_mode_label: Label = instance.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthModeLabel")
+	var welcome_label: Label = instance.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/WelcomeLabel")
+	var play_button: Button = instance.get_node("CenterContainer/VBoxContainer/PlayButton")
+
+	_check("Play starts disabled", play_button.disabled)
+
+	# Click Register -- a real signal emission is fine here since
+	# _on_register_button_pressed() is synchronous (no await), same as a
+	# real click's GUI event dispatch would drive it.
+	register_button.pressed.emit()
+	await process_frame
+
+	_check("auth panel opened in register mode", instance.get_node("CenterContainer/VBoxContainer/AuthPanel").visible)
+
+	# Fill the form exactly as a user would type into it.
+	var unique_id := int(Time.get_unix_time_from_system() * 1000)
+	username_edit.text = "mainmenu_e2e_%d" % unique_id
+	password_edit.text = "TestPass123!"
+	email_edit.text = "mainmenu_e2e_%d@test.example.com" % unique_id
+	over_18_check.button_pressed = true
+
+	# Call the submit handler directly (awaited) rather than via
+	# auth_button.pressed.emit() -- a synthetic .emit() in --script/
+	# SceneTree headless mode doesn't drive an await-using handler's
+	# coroutine forward the same way real GUI input event dispatch does
+	# (confirmed via a direct-call vs emit() comparison: the direct call
+	# always resolves, the synthetic emit sometimes doesn't advance past
+	# its own await point even after 50 real process_frame waits). This
+	# is a headless-mode test-harness limitation, not a bug in the actual
+	# click-driven flow.
+	await instance._on_auth_button_pressed()
+
+	_check("Play became enabled after real register submission", not play_button.disabled)
+	_check("Welcome label visible in tree", welcome_label.is_visible_in_tree())
+	_check("Auth buttons row hid itself after success", not auth_buttons_row.visible)
+
+	# Verify the auth form fields are hidden after successful auth,
+	# leaving only the welcome message visible within the panel.
+	_check("Username edit hidden after auth", not username_edit.visible)
+	_check("Password edit hidden after auth", not password_edit.visible)
+	_check("Email edit hidden after auth", not email_edit.visible)
+	_check("Over18 checkbox hidden after auth", not over_18_check.visible)
+	_check("Auth button hidden after auth", not auth_button.visible)
+	_check("Auth mode label hidden after auth", not auth_mode_label.visible)
+	_check("Welcome label contains username", welcome_label.text.begins_with("Welcome, mainmenu_e2e_"))
+
+	print("\n=== SMOKE RESULT: %d/%d passed ===" % [passed, passed + failed])
+	quit(0 if failed == 0 else 1)
+
+
+func _check(description: String, condition: bool) -> void:
+	if condition:
+		print("  PASS: ", description)
+		passed += 1
+	else:
+		printerr("  FAIL: ", description)
+		failed += 1

scripts/smoke_test_main_menu_ui.gd

@@ -0,0 +1,126 @@
+extends SceneTree
+## Verifies the main menu's Login/Register buttons correctly open the auth
+## panel and toggle between Login and Register modes via signal emission.
+##
+## Key tests:
+##  - AuthPanel starts hidden.
+##  - LoginButton press opens the panel in Login mode.
+##  - RegisterButton press opens the panel in Register mode.
+##  - Clicking Login while in Register mode switches back to Login mode.
+##  - Clicking Register while in Login mode switches to Register mode.
+##  - The ModeToggle CheckButton no longer exists in the scene.
+
+
+func _initialize() -> void:
+	_run()
+
+
+func _run() -> void:
+	await process_frame
+
+	var passed := 0
+	var failed := 0
+
+	var packed: PackedScene = load("res://scenes/main_menu.tscn")
+	var instance: Control = packed.instantiate()
+	root.add_child(instance)
+	await process_frame
+
+	var login_button: Button = instance.get_node("CenterContainer/VBoxContainer/AuthButtonsRow/LoginButton")
+	var register_button: Button = instance.get_node("CenterContainer/VBoxContainer/AuthButtonsRow/RegisterButton")
+	var auth_panel: PanelContainer = instance.get_node("CenterContainer/VBoxContainer/AuthPanel")
+	var auth_mode_label: Label = instance.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthModeLabel")
+	var email_edit: LineEdit = instance.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/EmailEdit")
+	var over_18_check: CheckBox = instance.get_node("CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/Over18Check")
+
+	# --- Test 1: auth panel starts hidden ---
+	if _check("auth panel starts hidden", not auth_panel.visible):
+		passed += 1
+	else:
+		failed += 1
+
+	# --- Test 2: LoginButton press opens panel in Login mode ---
+	login_button.pressed.emit()
+	await process_frame
+
+	if _check("auth panel visible after LoginButton press", auth_panel.visible):
+		passed += 1
+	else:
+		failed += 1
+
+	if _check("Login mode label after LoginButton press", auth_mode_label.text == "Login"):
+		passed += 1
+	else:
+		failed += 1
+
+	if _check("Email field hidden in Login mode", not email_edit.visible):
+		passed += 1
+	else:
+		failed += 1
+
+	if _check("Over18 checkbox hidden in Login mode", not over_18_check.visible):
+		passed += 1
+	else:
+		failed += 1
+
+	# --- Test 3: RegisterButton press switches to Register mode ---
+	register_button.pressed.emit()
+	await process_frame
+
+	if _check("auth panel still visible after RegisterButton press", auth_panel.visible):
+		passed += 1
+	else:
+		failed += 1
+
+	if _check("Register mode label after RegisterButton press", auth_mode_label.text == "Register"):
+		passed += 1
+	else:
+		failed += 1
+
+	if _check("Email field visible in Register mode", email_edit.visible):
+		passed += 1
+	else:
+		failed += 1
+
+	if _check("Over18 checkbox visible in Register mode", over_18_check.visible):
+		passed += 1
+	else:
+		failed += 1
+
+	# --- Test 4: LoginButton press switches back to Login mode ---
+	login_button.pressed.emit()
+	await process_frame
+
+	if _check("Login mode label after second LoginButton press", auth_mode_label.text == "Login"):
+		passed += 1
+	else:
+		failed += 1
+
+	if _check("Email field hidden after switching back to Login", not email_edit.visible):
+		passed += 1
+	else:
+		failed += 1
+
+	if _check("Over18 checkbox hidden after switching back to Login", not over_18_check.visible):
+		passed += 1
+	else:
+		failed += 1
+
+	# --- Test 5: ModeToggle CheckButton no longer exists ---
+	var mode_toggle_path = "CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/ModeToggle"
+	var has_mode_toggle = instance.has_node(mode_toggle_path)
+	if _check("ModeToggle CheckButton removed from scene", not has_mode_toggle):
+		passed += 1
+	else:
+		failed += 1
+
+	print("\n=== SMOKE RESULT: %d/%d passed ===" % [passed, passed + failed])
+	quit(0 if failed == 0 else 1)
+
+
+func _check(description: String, condition: bool) -> bool:
+	if condition:
+		print("  PASS: ", description)
+	else:
+		printerr("  FAIL: ", description)
+	return condition

scripts/smoke_test_world_list.gd

@@ -0,0 +1,168 @@
+extends SceneTree
+## Headless smoke test for the world list screen.
+##
+## Run with:
+##     godot --headless --path . --script res://scripts/smoke_test_world_list.gd
+##
+## Requires the backend to be running (default base URL
+## `application/agp/api_base_url` -> http://127.0.0.1:8000, override with
+## AGP_API_BASE_URL).
+##
+## Unlike a pure API-level test, this actually instantiates scenes/
+## world_list.tscn as a real scene and adds it to the tree -- catches
+## @onready node-path bugs (a node reference pointing at the wrong path
+## errors right here, not just "looks right" from reading the script) that
+## an API-only test would miss entirely.
+##
+## Tests:
+##   1. Register + log in a fresh user (so get_worlds() has a valid token).
+##   2. POST a real world via the API so the populated-card path actually
+##      gets exercised -- run_checkpoint_tests.py always starts from a
+##      genuinely empty DB, so without this the card-rendering code below
+##      would never run in CI at all, only the empty-list path would.
+##   3. Instantiate world_list.tscn, add to tree -- @onready resolution
+##      must not error.
+##   4. Wait for _refresh_worlds()'s awaited request to complete.
+##   5. Confirm it actually reached the populated (not empty) state, and
+##      that the rendered card has a real width -- not just non-zero
+##      child_count. 2026-08-20: a real bug shipped where every card
+##      technically existed in the tree (child_count > 0, no error, no
+##      crash) but rendered at 1.0px wide because size_flags_horizontal/
+##      vertical used the raw integer 4 (Control.SIZE_SHRINK_CENTER)
+##      instead of 3 (Control.SIZE_EXPAND_FILL) on ScrollContainer -- a
+##      child-count check alone would never catch that, only a real size
+##      assertion does.
+##
+## Exits 0 on full pass, 1 on any failure.
+
+const WORLD_LIST_SCENE := "res://scenes/world_list.tscn"
+const MIN_SANE_CARD_WIDTH := 200.0  # a real screen is at minimum a few hundred px wide
+
+
+func _initialize() -> void:
+	_run()
+
+
+func _run() -> void:
+	await process_frame
+
+	var api := root.get_node("ApiClient")
+	assert(api != null, "ApiClient autoload not found")
+
+	var passed: int = 0
+	var failed: int = 0
+
+	# --- Setup: register + log in so the world list has a valid token ---
+	print("\n=== Setup: register + login ===")
+	randomize()
+	var unique_id: int = int(Time.get_unix_time_from_system() * 1000) + randi() % 100000
+	var username := "worldlist_smoke_%d" % unique_id
+	var email := "worldlist_smoke_%d@test.example.com" % unique_id
+	var reg_result: Dictionary = await api.register(username, email, "SmokeTest123!", true)
+	if not _check("setup: register succeeded", reg_result.ok):
+		print("  detail: ", reg_result.detail)
+		quit(1)
+		return
+
+	# --- Seed a real world so the populated-card path is actually exercised ---
+	print("\n=== Setup: seed a real world ===")
+	var world_body := JSON.stringify({
+		"name": "Smoke Test World %d" % unique_id,
+		"description": "Seeded by smoke_test_world_list.gd to exercise the populated-card render path.",
+		"visibility": "public",
+	})
+	var create_result: Dictionary = await api.request(HTTPClient.METHOD_POST, "/api/worlds/", world_body, "application/json", true)
+	if not _check("setup: world created", create_result.ok):
+		print("  detail: ", create_result.detail)
+		quit(1)
+		return
+
+	# --- Test 1: Instantiate the real scene ---
+	print("\n=== Test 1: Instantiate world_list.tscn ===")
+	var packed_scene: PackedScene = load(WORLD_LIST_SCENE)
+	if not _check("scene loads", packed_scene != null):
+		quit(1)
+		return
+
+	var instance: Control = packed_scene.instantiate()
+	if not _check("scene instantiates", instance != null):
+		quit(1)
+		return
+
+	root.add_child(instance)
+	# One frame for _ready() (and its @onready resolution) to run. A wrong
+	# node path in an @onready var errors during this, not silently.
+	await process_frame
+
+	if _check("scene added to tree without error", is_instance_valid(instance)):
+		passed += 1
+	else:
+		failed += 1
+
+	# --- Test 2: Wait for the world fetch to resolve, check a real end state ---
+	print("\n=== Test 2: World fetch reaches a real end state ===")
+	# _refresh_worlds() runs from _ready(); give its awaited HTTP call time
+	# to complete rather than a fixed sleep -- poll for either end state.
+	var world_list_node: VBoxContainer = instance.get_node("VBoxContainer/ScrollContainer/WorldList")
+	var empty_label: Label = instance.get_node("VBoxContainer/EmptyLabel")
+	var error_label: Label = instance.get_node("VBoxContainer/ErrorLabel")
+
+	var settled := false
+	for i in range(50):  # up to ~5s at 100ms/frame-ish via process_frame waits
+		await process_frame
+		if world_list_node.visible or empty_label.visible or error_label.visible:
+			settled = true
+			break
+
+	if _check("reached a real end state (cards, empty, or error) not stuck loading", settled):
+		passed += 1
+	else:
+		failed += 1
+		print("  world_list.visible=%s empty_label.visible=%s error_label.visible=%s" % [
+			world_list_node.visible, empty_label.visible, error_label.visible
+		])
+
+	if error_label.visible:
+		printerr("  Note: ended in error state: ", error_label.text)
+	elif empty_label.visible:
+		# We just seeded a world -- ending up empty means GET /api/worlds
+		# isn't actually seeing what POST /api/worlds/ just created.
+		_check("ended in populated state, not empty (a world was just seeded)", false)
+		failed += 1
+	elif world_list_node.visible:
+		var card_count := world_list_node.get_child_count()
+		print("  Note: rendered %d world card(s)" % card_count)
+
+		if _check("at least one card rendered", card_count > 0):
+			passed += 1
+		else:
+			failed += 1
+
+		# The actual bug this test exists to catch: a card can be present
+		# in the tree, not crash, and still be visually nothing because
+		# it rendered at ~1px wide. Check every card's real computed size,
+		# not just that it exists.
+		for i in range(card_count):
+			var card: Control = world_list_node.get_child(i)
+			var wide_enough := card.size.x >= MIN_SANE_CARD_WIDTH
+			if _check("card %d has a real width (%.0fpx >= %.0fpx)" % [i, card.size.x, MIN_SANE_CARD_WIDTH], wide_enough):
+				passed += 1
+			else:
+				failed += 1
+
+	# --- Summary ---
+	print("\n=== SMOKE RESULT: %d/%d passed ===" % [passed, passed + failed])
+	if failed > 0:
+		quit(1)
+	else:
+		print("SMOKE RESULT: ALL PASS")
+		quit(0)
+
+
+func _check(description: String, condition: bool) -> bool:
+	if condition:
+		print("  PASS: ", description)
+		return true
+	else:
+		printerr("  FAIL: ", description)
+		return false

scripts/static_object_node.gd

@@ -0,0 +1,67 @@
+class_name StaticObjectNode
+extends Node3D
+## A visual representation of a static world object within a chunk.
+##
+## This node is instantiated by [ChunkScene] for each static (non-dynamic)
+## [WorldObject]. It renders the object's mesh (referenced by `asset_id`) at
+## the object's transform. If the asset is not yet loaded, a placeholder mesh
+## is shown.
+##
+## ## Structure
+##
+## ```
+## StaticObjectNode (Node3D)
+##  └── MeshInstance3D  # the object's visual mesh
+## ```
+
+## The world object data this node represents.
+var world_object: WorldObject = null
+
+## The loaded mesh instance (or placeholder).
+var _mesh_instance: MeshInstance3D = null
+
+
+func _ready() -> void:
+	if world_object == null:
+		return
+	_load_mesh()
+
+
+## Load and attach the object's mesh.
+func _load_mesh() -> void:
+	_mesh_instance = MeshInstance3D.new()
+	_mesh_instance.name = "mesh"
+
+	# Try to load the asset by its id (path). Fall back to a placeholder.
+	var mesh := _load_asset_mesh(world_object.asset_id)
+	if mesh == null:
+		mesh = _make_placeholder_mesh()
+
+	_mesh_instance.mesh = mesh
+	add_child(_mesh_instance)
+
+
+## Attempt to load a mesh from the asset path.
+func _load_asset_mesh(asset_id: String) -> Mesh:
+	if asset_id.is_empty():
+		return null
+	var path := "res://assets/%s" % asset_id
+	if ResourceLoader.exists(path):
+		var res := load(path)
+		if res is Mesh:
+			return res
+	return null
+
+
+## Create a simple placeholder box mesh when the real asset is unavailable.
+func _make_placeholder_mesh() -> Mesh:
+	var mesh := BoxMesh.new()
+	mesh.size = Vector3(1.0, 1.0, 1.0)
+	return mesh
+
+
+## Get the world object's display name.
+func get_display_name() -> String:
+	if world_object == null:
+		return ""
+	return world_object.get_display_name()

scripts/static_object_node.gd.uid

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

scripts/tile_def.gd

@@ -0,0 +1,42 @@
+class_name TileDef
+extends RefCounted
+## A single tile definition (palette entry) within a tile layer.
+##
+## Maps a tile ID to its asset reference and gameplay flags. See
+## docs/architecture/world.md §3.2.
+
+## Tile ID (index into the layer palette). 0 is reserved for empty/air.
+var id: int = 0
+
+## Reference to the tile/terrain asset.
+var asset_id: String = ""
+
+## Whether this tile has collision.
+var solid: bool = false
+
+## Bitmask flags: bit 0 = walkable, bit 1 = climbable, bit 2 = liquid.
+var flags: int = 0
+
+## Number of visual variants for this tile.
+var variants: int = 1
+
+
+func _init(p_id: int = 0, p_asset_id: String = "", p_solid: bool = false,
+		p_flags: int = 0, p_variants: int = 1) -> void:
+	id = p_id
+	asset_id = p_asset_id
+	solid = p_solid
+	flags = p_flags
+	variants = p_variants
+
+
+func is_walkable() -> bool:
+	return (flags & 0x01) != 0
+
+
+func is_climbable() -> bool:
+	return (flags & 0x02) != 0
+
+
+func is_liquid() -> bool:
+	return (flags & 0x04) != 0

scripts/tile_def.gd.uid

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

scripts/tile_layer.gd

@@ -0,0 +1,83 @@
+class_name TileLayer
+extends RefCounted
+## A single tile layer within a chunk.
+##
+## Holds the dense grid of tile IDs, the palette mapping tile IDs to tile
+## definitions, and the layer metadata. This is the runtime representation of
+## the `TileLayer` from the chunk data format (see docs/architecture/world.md
+## §3.2).
+
+## Layer name (e.g. "ground", "walls", "decor").
+var name: String = ""
+
+## Numeric layer id, unique within the chunk.
+var layer_id: int = 0
+
+## Grid dimensions in tiles.
+var width: int = 0
+var height: int = 0
+var depth: int = 1
+
+## Palette mapping tile IDs to tile definitions (shared per layer).
+var palette: Array[TileDef] = []
+
+## Dense, row-major tile IDs. Length = width * height * depth.
+var tiles: PackedInt32Array = PackedInt32Array()
+
+
+func _init(
+	p_layer_name: String = "",
+	p_layer_id: int = 0,
+	p_width: int = 0,
+	p_height: int = 0,
+	p_depth: int = 1
+) -> void:
+	name = p_layer_name
+	layer_id = p_layer_id
+	width = p_width
+	height = p_height
+	depth = p_depth
+
+
+## Total number of tiles in this layer.
+func tile_count() -> int:
+	return width * height * depth
+
+
+## Get the tile ID at (x, y, z). Returns 0 (empty) for out-of-bounds.
+func get_tile(x: int, y: int, z: int = 0) -> int:
+	if x < 0 or x >= width or y < 0 or y >= height or z < 0 or z >= depth:
+		return 0
+	var idx := (z * height + y) * width + x
+	if idx < tiles.size():
+		return tiles[idx]
+	return 0
+
+
+## Set the tile ID at (x, y, z). No-op if out of bounds.
+func set_tile(x: int, y: int, z: int, tile_id: int) -> void:
+	if x < 0 or x >= width or y < 0 or y >= height or z < 0 or z >= depth:
+		return
+	var idx := (z * height + y) * width + x
+	if idx < tiles.size():
+		tiles[idx] = tile_id
+
+
+## Get the tile definition for a tile ID, or null if not in the palette.
+func get_tile_def(tile_id: int) -> TileDef:
+	for def in palette:
+		if def.id == tile_id:
+			return def
+	return null
+
+
+## Whether the tile at (x, y, z) is solid (collision).
+func is_solid(x: int, y: int, z: int = 0) -> bool:
+	var def := get_tile_def(get_tile(x, y, z))
+	return def != null and def.solid
+
+
+## Whether the tile at (x, y, z) is walkable.
+func is_walkable(x: int, y: int, z: int = 0) -> bool:
+	var def := get_tile_def(get_tile(x, y, z))
+	return def != null and def.is_walkable()

scripts/tile_layer.gd.uid

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

scripts/tile_layer_node.gd

@@ -0,0 +1,112 @@
+class_name TileLayerNode
+extends Node3D
+## A visual representation of a single tile layer within a chunk.
+##
+## This node is instantiated by [ChunkScene] for each tile layer in a chunk.
+## It renders the layer's tiles as instanced meshes (one per tile definition
+## in the palette) using [MultiMeshInstance3D] for efficiency.
+##
+## ## Structure
+##
+## ```
+## TileLayerNode (Node3D)
+##  └── MultiMeshInstance3D  # one per palette entry (tile definition)
+## ```
+
+## The tile layer data this node renders.
+var tile_layer: TileLayer = null
+
+## The chunk coordinate this layer belongs to (for world positioning).
+var chunk_coord: Vector3i = Vector3i.ZERO
+
+## Tile size in world units (each tile is 1x1x1).
+const TILE_SIZE: float = 1.0
+
+## Cache of MultiMeshInstance3D nodes, keyed by tile definition id.
+var _mesh_instances: Dictionary = {}
+
+
+func _ready() -> void:
+	if tile_layer == null:
+		return
+	_build_meshes()
+
+
+## Build the MultiMesh instances for each tile definition in the palette.
+func _build_meshes() -> void:
+	for tile_def in tile_layer.palette:
+		if tile_def.id == 0:
+			continue  # Tile 0 is "empty/air", no mesh needed
+		_create_mesh_for_tile(tile_def)
+
+
+func _create_mesh_for_tile(tile_def: TileDef) -> void:
+	# Count how many cells use this tile definition
+	var count := 0
+	for tile_id in tile_layer.tiles:
+		if tile_id == tile_def.id:
+			count += 1
+
+	if count == 0:
+		return
+
+	var multi_mesh := MultiMesh.new()
+	multi_mesh.transform_format = MultiMesh.TRANSFORM_3D
+	multi_mesh.mesh = _make_unit_cube_mesh()
+	multi_mesh.instance_count = count
+
+	var instance_idx := 0
+	for z in range(tile_layer.depth):
+		for y in range(tile_layer.height):
+			for x in range(tile_layer.width):
+				var tile_id := tile_layer.get_tile(x, y, z)
+				if tile_id != tile_def.id:
+					continue
+				var world_pos := _tile_to_world(x, y, z)
+				var xform := Transform3D(Basis(), world_pos)
+				multi_mesh.set_instance_transform(instance_idx, xform)
+				instance_idx += 1
+
+	var mesh_instance := MultiMeshInstance3D.new()
+	mesh_instance.multimesh = multi_mesh
+	mesh_instance.name = "tiles_%d" % tile_def.id
+	add_child(mesh_instance)
+	_mesh_instances[tile_def.id] = mesh_instance
+
+
+## Convert a tile grid coordinate to a world-space position (center of tile).
+func _tile_to_world(x: int, y: int, z: int) -> Vector3:
+	var origin := Vector3(
+		chunk_coord.x * tile_layer.width,
+		chunk_coord.y * tile_layer.height,
+		chunk_coord.z * tile_layer.depth
+	)
+	return origin + Vector3(
+		x * TILE_SIZE + TILE_SIZE * 0.5,
+		y * TILE_SIZE + TILE_SIZE * 0.5,
+		z * TILE_SIZE + TILE_SIZE * 0.5
+	)
+
+
+## Create a simple unit cube mesh for tile rendering.
+func _make_unit_cube_mesh() -> Mesh:
+	var mesh := BoxMesh.new()
+	mesh.size = Vector3(TILE_SIZE, TILE_SIZE, TILE_SIZE)
+	return mesh
+
+
+## Get the tile definition at a grid position, or null if empty.
+func get_tile_def_at(x: int, y: int, z: int = 0) -> TileDef:
+	if tile_layer == null:
+		return null
+	var tile_id := tile_layer.get_tile(x, y, z)
+	if tile_id == 0:
+		return null
+	return tile_layer.get_tile_def(tile_id)
+
+
+## Clear all rendered meshes.
+func clear() -> void:
+	for child in get_children():
+		child.queue_free()
+	_mesh_instances.clear()

scripts/tile_layer_node.gd.uid

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

scripts/world_list.gd

@@ -0,0 +1,142 @@
+extends Control
+## World list screen — browses public worlds via GET /api/worlds.
+##
+## Displays a scrollable list of world cards (name + description).
+## Handles loading, empty list, errors, and refresh.
+
+
+# UI references
+@onready var scroll_container: ScrollContainer = $VBoxContainer/ScrollContainer
+@onready var world_list: VBoxContainer = $VBoxContainer/ScrollContainer/WorldList
+@onready var loading_label: Label = $VBoxContainer/LoadingLabel
+@onready var error_label: Label = $VBoxContainer/ErrorLabel
+@onready var refresh_button: Button = $VBoxContainer/HeaderHBox/RefreshButton
+@onready var back_button: Button = $VBoxContainer/HeaderHBox/BackButton
+@onready var empty_label: Label = $VBoxContainer/EmptyLabel
+
+
+func _ready() -> void:
+	refresh_button.disabled = false
+	back_button.disabled = false
+	loading_label.visible = false
+	error_label.visible = false
+	empty_label.visible = false
+	world_list.visible = false
+	_refresh_worlds()
+
+
+func _on_refresh_button_pressed() -> void:
+	_refresh_worlds()
+
+
+func _on_back_button_pressed() -> void:
+	get_tree().change_scene_to_file("res://scenes/main_menu.tscn")
+
+
+## Fetch the world list from the backend and update the UI.
+func _refresh_worlds() -> void:
+	# Reset UI state
+	loading_label.visible = true
+	error_label.visible = false
+	empty_label.visible = false
+	world_list.visible = false
+	refresh_button.disabled = true
+
+	# Clear previous world cards
+	for child in world_list.get_children():
+		child.queue_free()
+
+	var result := await ApiClient.get_worlds()
+
+	loading_label.visible = false
+	refresh_button.disabled = false
+
+	if not result.ok:
+		# Show error message (401, network failure, etc.)
+		error_label.text = "Error: %s" % result.detail
+		error_label.visible = true
+		empty_label.visible = false
+		world_list.visible = false
+		return
+
+	var data = result.data
+	if not data is Array:
+		error_label.text = "Unexpected response format."
+		error_label.visible = true
+		empty_label.visible = false
+		world_list.visible = false
+		return
+
+	if data.is_empty():
+		empty_label.text = "No worlds yet. Check back later!"
+		empty_label.visible = true
+		error_label.visible = false
+		world_list.visible = false
+		return
+
+	# Render world cards
+	world_list.visible = true
+	empty_label.visible = false
+	error_label.visible = false
+
+	for world_dict in data:
+		if not world_dict is Dictionary:
+			continue
+		var card := _create_world_card(world_dict)
+		world_list.add_child(card)
+
+
+## Create a visual card for a single world entry.
+func _create_world_card(world_dict: Dictionary) -> Control:
+	# PanelContainer for the background, not a ColorRect moved to child index
+	# 0 of a VBoxContainer -- a VBoxContainer lays out ALL its children in a
+	# vertical sequence, it has no concept of "float this one child behind
+	# the others as an overlay". That version rendered as an empty dark bar
+	# sitting above the text, not a background behind it.
+	var panel := PanelContainer.new()
+	panel.size_flags_horizontal = Control.SIZE_EXPAND_FILL
+	panel.custom_minimum_size = Vector2(0, 80)
+	var style := StyleBoxFlat.new()
+	style.bg_color = Color(0.15, 0.15, 0.15, 1.0)
+	style.content_margin_left = 12
+	style.content_margin_right = 12
+	style.content_margin_top = 8
+	style.content_margin_bottom = 8
+	panel.add_theme_stylebox_override("panel", style)
+
+	var card := VBoxContainer.new()
+	card.size_flags_horizontal = Control.SIZE_EXPAND_FILL
+	card.add_theme_constant_override("separation", 4)
+	panel.add_child(card)
+
+	var name_label := Label.new()
+	name_label.text = world_dict.get("name", "Unnamed World")
+	name_label.autowrap_mode = TextServer.AUTOWRAP_WORD
+	name_label.size_flags_horizontal = Control.SIZE_FILL
+	name_label.size_flags_vertical = Control.SIZE_SHRINK_BEGIN
+	name_label.add_theme_font_size_override("font_size", 18)
+
+	var desc_label := Label.new()
+	var description: String = str(world_dict.get("description", ""))
+	desc_label.text = description if description != "" else "No description."
+	desc_label.autowrap_mode = TextServer.AUTOWRAP_WORD
+	desc_label.size_flags_horizontal = Control.SIZE_FILL
+	desc_label.size_flags_vertical = Control.SIZE_EXPAND_FILL
+	desc_label.add_theme_font_size_override("font_size", 14)
+	desc_label.add_theme_color_override("font_color", Color(0.7, 0.7, 0.7, 1.0))
+
+	var meta_label := Label.new()
+	var visibility: String = str(world_dict.get("visibility", "public"))
+	var created: String = str(world_dict.get("created_at", ""))
+	meta_label.text = "Visibility: %s%s" % [visibility, " | Created: " + created if created != "" else ""]
+	meta_label.autowrap_mode = TextServer.AUTOWRAP_WORD
+	meta_label.size_flags_horizontal = Control.SIZE_FILL
+	meta_label.size_flags_vertical = Control.SIZE_SHRINK_BEGIN
+	meta_label.add_theme_font_size_override("font_size", 12)
+	meta_label.add_theme_color_override("font_color", Color(0.5, 0.5, 0.5, 1.0))
+
+	card.add_child(name_label)
+	card.add_child(desc_label)
+	card.add_child(meta_label)
+
+	return panel

scripts/world_object.gd

@@ -0,0 +1,135 @@
+class_name WorldObject
+extends RefCounted
+## A world object (static or dynamic) within a chunk.
+##
+## This is the runtime representation of a WorldObject from the chunk data
+## format (see docs/architecture/world.md §3.3). It holds the object's
+## identity, transform, properties, and moderation flags.
+
+## Stable object ID, unique within the chunk.
+var id: String = ""
+
+## Object type (e.g. "prop", "interactable", "spawn_point", "door").
+var type: String = ""
+
+## Reference to the object's mesh/glTF asset.
+var asset_id: String = ""
+
+## World-space position.
+var position: Vector3 = Vector3.ZERO
+
+## World-space rotation as a quaternion (x, y, z, w).
+var rotation: Vector4 = Vector4(0, 0, 0, 1)
+
+## World-space scale.
+var scale: Vector3 = Vector3.ONE
+
+## Type-specific key/value properties.
+var properties: Dictionary = {}
+
+## Whether this is a spawnable dynamic entity (true) or static (false).
+var is_dynamic: bool = false
+
+## Per-object content moderation flags.
+var flags: ChunkDataDecoder.ContentFlags = ChunkDataDecoder.ContentFlags.new()
+
+## Whether this object has been modified locally.
+var is_dirty: bool = false
+
+
+func _init(
+	p_id: String = "",
+	p_type: String = "",
+	p_asset_id: String = "",
+	p_position: Vector3 = Vector3.ZERO,
+	p_rotation: Vector4 = Vector4(0, 0, 0, 1),
+	p_scale: Vector3 = Vector3.ONE,
+	p_properties: Dictionary = {},
+	p_dynamic: bool = false,
+	p_flags: ChunkDataDecoder.ContentFlags = null
+) -> void:
+	id = p_id
+	type = p_type
+	asset_id = p_asset_id
+	position = p_position
+	rotation = p_rotation
+	scale = p_scale
+	properties = p_properties
+	is_dynamic = p_dynamic
+	if p_flags != null:
+		flags = p_flags
+
+
+## Get a property value by key.
+func get_property(key: String) -> Variant:
+	return properties.get(key)
+
+
+## Set a property value.
+func set_property(key: String, value: Variant) -> void:
+	properties[key] = value
+	is_dirty = true
+
+
+## Check if this object is walkable (based on properties).
+func is_walkable() -> bool:
+	return properties.get("walkable", true)
+
+
+## Check if this object is climbable (based on properties).
+func is_climbable() -> bool:
+	return properties.get("climbable", false)
+
+
+## Check if this object is interactable.
+func is_interactable() -> bool:
+	return type == "interactable" or properties.get("interactable", false)
+
+
+## Get the object's display name.
+func get_display_name() -> String:
+	return properties.get("display_name", id)
+
+
+## Serialize this object to a dictionary (for networking).
+func to_dict() -> Dictionary:
+	return {
+		"id": id,
+		"type": type,
+		"asset_id": asset_id,
+		"position": [position.x, position.y, position.z],
+		"rotation": [rotation.x, rotation.y, rotation.z, rotation.w],
+		"scale": [scale.x, scale.y, scale.z],
+		"properties": properties,
+		"dynamic": is_dynamic,
+	}
+
+
+## Create a WorldObject from a dictionary (for networking).
+static func from_dict(d: Dictionary) -> WorldObject:
+	var pos := Vector3(
+		d.get("position", [0, 0, 0])[0],
+		d.get("position", [0, 0, 0])[1],
+		d.get("position", [0, 0, 0])[2]
+	)
+	var rot := Vector4(
+		d.get("rotation", [0, 0, 0, 1])[0],
+		d.get("rotation", [0, 0, 0, 1])[1],
+		d.get("rotation", [0, 0, 0, 1])[2],
+		d.get("rotation", [0, 0, 0, 1])[3]
+	)
+	var scl := Vector3(
+		d.get("scale", [1, 1, 1])[0],
+		d.get("scale", [1, 1, 1])[1],
+		d.get("scale", [1, 1, 1])[2]
+	)
+	return WorldObject.new(
+		d.get("id", ""),
+		d.get("type", ""),
+		d.get("asset_id", ""),
+		pos,
+		rot,
+		scl,
+		d.get("properties", {}),
+		d.get("dynamic", false),
+	)

scripts/world_object.gd.uid

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