Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 architect-bot
|
0b973b73ab |
@@ -1,14 +0,0 @@
|
||||
# Database
|
||||
DATABASE_URL=postgresql://agp_user:agp_password@localhost:5432/agp_db
|
||||
|
||||
# Redis
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
|
||||
# JWT
|
||||
SECRET_KEY=change-me-to-a-secure-random-string
|
||||
ALGORITHM=HS256
|
||||
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
||||
|
||||
# App
|
||||
DEBUG=true
|
||||
CORS_ORIGINS=http://localhost:8080,http://localhost:3000
|
||||
@@ -1,4 +0,0 @@
|
||||
.env
|
||||
__pycache__/
|
||||
*.pyc
|
||||
.venv/
|
||||
@@ -1,42 +0,0 @@
|
||||
# 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
|
||||
@@ -1,65 +0,0 @@
|
||||
"""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()
|
||||
@@ -1,48 +0,0 @@
|
||||
"""Application configuration via pydantic-settings."""
|
||||
|
||||
from pydantic_settings import BaseSettings
|
||||
from functools import lru_cache
|
||||
|
||||
|
||||
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
|
||||
SECRET_KEY: str = "change-me-to-a-secure-random-string"
|
||||
ALGORITHM: str = "HS256"
|
||||
ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
|
||||
|
||||
# CORS
|
||||
CORS_ORIGINS: str = "http://localhost:8080,http://localhost:3000"
|
||||
|
||||
# File uploads
|
||||
UPLOAD_DIR: str = "uploads"
|
||||
MAX_UPLOAD_SIZE_MB: int = 100
|
||||
|
||||
@property
|
||||
def cors_origins_list(self) -> list[str]:
|
||||
return [origin.strip() for origin in self.CORS_ORIGINS.split(",")]
|
||||
|
||||
class Config:
|
||||
env_file = ".env"
|
||||
env_file_encoding = "utf-8"
|
||||
case_sensitive = True
|
||||
|
||||
|
||||
@lru_cache()
|
||||
def get_settings() -> Settings:
|
||||
"""Return cached settings instance."""
|
||||
return Settings()
|
||||
|
||||
|
||||
# Convenience singleton
|
||||
settings = get_settings()
|
||||
@@ -1,38 +0,0 @@
|
||||
"""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."""
|
||||
async with async_session_factory() as session:
|
||||
try:
|
||||
yield session
|
||||
await session.commit()
|
||||
except Exception:
|
||||
await session.rollback()
|
||||
raise
|
||||
@@ -1,36 +0,0 @@
|
||||
"""FastAPI application entry point."""
|
||||
|
||||
from contextlib import asynccontextmanager
|
||||
|
||||
from fastapi import FastAPI
|
||||
|
||||
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,
|
||||
)
|
||||
|
||||
# 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}
|
||||
@@ -1,6 +0,0 @@
|
||||
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"]
|
||||
@@ -1,36 +0,0 @@
|
||||
from sqlalchemy import Column, Integer, String, ForeignKey, Text, DateTime, Enum as SAEnum
|
||||
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(SAEnum(AssetType), 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(Integer, default=0, 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")
|
||||
@@ -1,18 +0,0 @@
|
||||
from sqlalchemy import Column, 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, primary_key=True)
|
||||
user_id = Column(String, 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")
|
||||
@@ -1,21 +0,0 @@
|
||||
from sqlalchemy import Column, Integer, String, Boolean, DateTime
|
||||
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)
|
||||
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")
|
||||
worlds = relationship("World", back_populates="owner")
|
||||
assets = relationship("Asset", back_populates="owner")
|
||||
@@ -1,27 +0,0 @@
|
||||
from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey, 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), 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")
|
||||
@@ -1,181 +0,0 @@
|
||||
"""Asset management router."""
|
||||
|
||||
from typing import Optional
|
||||
|
||||
from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Query
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from sqlalchemy.orm import selectinload
|
||||
|
||||
from app.database import get_db
|
||||
from app.models.asset import Asset, AssetType
|
||||
from app.models.user import User
|
||||
from app.models.world import World
|
||||
from app.routers.worlds import get_current_user
|
||||
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
|
||||
|
||||
class 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
|
||||
|
||||
|
||||
# --- Endpoints ---
|
||||
|
||||
@router.post("/", response_model=AssetResponse, status_code=201)
|
||||
async def create_asset(
|
||||
payload: AssetCreate,
|
||||
db: AsyncSession = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user),
|
||||
):
|
||||
"""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(
|
||||
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),
|
||||
current_user: User = Depends(get_current_user),
|
||||
):
|
||||
"""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,
|
||||
db: AsyncSession = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user),
|
||||
):
|
||||
"""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,
|
||||
db: AsyncSession = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user),
|
||||
):
|
||||
"""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,
|
||||
db: AsyncSession = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user),
|
||||
):
|
||||
"""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")
|
||||
async def upload_asset_file(
|
||||
asset_id: int,
|
||||
file: UploadFile = File(...),
|
||||
db: AsyncSession = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user),
|
||||
):
|
||||
"""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")
|
||||
|
||||
# TODO: Implement actual file upload logic (S3, local filesystem, etc.)
|
||||
file_path = f"uploads/{asset_id}_{file.filename}"
|
||||
asset.file_path = file_path
|
||||
asset.mime_type = file.content_type
|
||||
asset.file_size = 0 # Will be updated after actual write
|
||||
|
||||
await db.commit()
|
||||
await db.refresh(asset)
|
||||
|
||||
return {"message": "File upload endpoint", "asset_id": asset_id, "file_path": file_path}
|
||||
@@ -1,133 +0,0 @@
|
||||
"""Authentication router - login, register, token refresh."""
|
||||
|
||||
from datetime import datetime, timedelta, timezone
|
||||
|
||||
from fastapi import APIRouter, Depends, HTTPException, status
|
||||
from pydantic import BaseModel, EmailStr
|
||||
|
||||
from jose import JWTError, jwt
|
||||
from passlib.context import CryptContext
|
||||
|
||||
from app.config import settings
|
||||
from app.database import get_db
|
||||
from app.models.user import User
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from sqlalchemy import select
|
||||
|
||||
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
|
||||
# --- Pydantic schemas ---
|
||||
|
||||
class TokenResponse(BaseModel):
|
||||
access_token: str
|
||||
token_type: str = "bearer"
|
||||
|
||||
|
||||
class RegisterRequest(BaseModel):
|
||||
username: str
|
||||
email: EmailStr
|
||||
password: str
|
||||
|
||||
|
||||
class LoginRequest(BaseModel):
|
||||
username: str
|
||||
password: str
|
||||
|
||||
|
||||
# --- Helpers ---
|
||||
|
||||
def _create_access_token(data: dict) -> str:
|
||||
to_encode = data.copy()
|
||||
expire = datetime.now(timezone.utc) + timedelta(
|
||||
minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES
|
||||
)
|
||||
to_encode.update({"exp": expire})
|
||||
return jwt.encode(to_encode, settings.SECRET_KEY, 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)
|
||||
|
||||
|
||||
# --- 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 an access token."""
|
||||
# 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),
|
||||
)
|
||||
db.add(user)
|
||||
await db.commit()
|
||||
await db.refresh(user)
|
||||
|
||||
access_token = _create_access_token({"sub": str(user.id)})
|
||||
return TokenResponse(access_token=access_token)
|
||||
|
||||
|
||||
@router.post("/login", response_model=TokenResponse)
|
||||
async def login(req: LoginRequest, db: AsyncSession = Depends(get_db)):
|
||||
"""Authenticate user and return an access token."""
|
||||
result = await db.execute(select(User).where(User.username == req.username))
|
||||
user = result.scalar_one_or_none()
|
||||
|
||||
if not user or not verify_password(req.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",
|
||||
)
|
||||
|
||||
access_token = _create_access_token({"sub": str(user.id)})
|
||||
return TokenResponse(access_token=access_token)
|
||||
|
||||
|
||||
@router.get("/me")
|
||||
async def get_current_user(
|
||||
user_id: int,
|
||||
db: AsyncSession = Depends(get_db),
|
||||
):
|
||||
"""Get current user 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")
|
||||
return {
|
||||
"id": user.id,
|
||||
"username": user.username,
|
||||
"email": user.email,
|
||||
"is_active": user.is_active,
|
||||
"created_at": user.created_at,
|
||||
}
|
||||
@@ -1,130 +0,0 @@
|
||||
"""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.models.user import User
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
|
||||
# ── Pydantic schemas ──────────────────────────────────────────────────────
|
||||
|
||||
class UserCreate(BaseModel):
|
||||
username: str
|
||||
email: EmailStr
|
||||
password: str
|
||||
|
||||
|
||||
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.post(
|
||||
"/",
|
||||
response_model=UserResponse,
|
||||
status_code=status.HTTP_201_CREATED,
|
||||
)
|
||||
async def create_user(
|
||||
user_in: UserCreate,
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
):
|
||||
"""Register a new user."""
|
||||
# Check uniqueness of username
|
||||
existing = await db.execute(select(User).where(User.username == user_in.username))
|
||||
if existing.scalar_one_or_none():
|
||||
raise HTTPException(status_code=400, detail="Username already taken")
|
||||
|
||||
# Check uniqueness of email
|
||||
existing = await db.execute(select(User).where(User.email == user_in.email))
|
||||
if existing.scalar_one_or_none():
|
||||
raise HTTPException(status_code=400, detail="Email already registered")
|
||||
|
||||
from app.routers.auth import hash_password
|
||||
|
||||
hashed = hash_password(user_in.password)
|
||||
|
||||
user = User(
|
||||
username=user_in.username,
|
||||
email=user_in.email,
|
||||
hashed_password=hashed,
|
||||
)
|
||||
db.add(user)
|
||||
await db.commit()
|
||||
await db.refresh(user)
|
||||
return user
|
||||
|
||||
|
||||
@router.get("/me", response_model=UserResponse)
|
||||
async def get_current_user(
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
# current_user would come from JWT dependency in real usage
|
||||
):
|
||||
"""Get the currently authenticated user (placeholder)."""
|
||||
raise HTTPException(status_code=501, detail="Not implemented")
|
||||
|
||||
|
||||
@router.get("/{user_id}", response_model=UserResponse)
|
||||
async def get_user(
|
||||
user_id: int,
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
):
|
||||
"""Get a user by ID."""
|
||||
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")
|
||||
return user
|
||||
|
||||
|
||||
@router.patch("/{user_id}", response_model=UserResponse)
|
||||
async def update_user(
|
||||
user_id: int,
|
||||
user_update: UserUpdate,
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
):
|
||||
"""Update a user."""
|
||||
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")
|
||||
|
||||
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,
|
||||
db: Annotated[AsyncSession, Depends(get_db)],
|
||||
):
|
||||
"""Delete a user."""
|
||||
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")
|
||||
await db.delete(user)
|
||||
await db.commit()
|
||||
@@ -1,151 +0,0 @@
|
||||
"""Worlds router - CRUD for game worlds."""
|
||||
|
||||
from typing import Annotated
|
||||
|
||||
from fastapi import APIRouter, Depends, HTTPException, Query
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from sqlalchemy.orm import selectinload
|
||||
|
||||
from app.database import get_db
|
||||
from app.models.world import World, WorldVisibility
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
|
||||
async def get_current_user():
|
||||
"""Placeholder dependency for current user auth."""
|
||||
# TODO: Implement JWT auth dependency
|
||||
return {"id": 1, "username": "testuser", "email": "test@example.com"}
|
||||
|
||||
|
||||
@router.get("/")
|
||||
async def list_worlds(
|
||||
skip: int = Query(0, ge=0),
|
||||
limit: int = Query(50, ge=1, le=100),
|
||||
visibility: WorldVisibility | None = None,
|
||||
db: Annotated[AsyncSession, Depends(get_db)] = Depends(),
|
||||
):
|
||||
"""List worlds with optional visibility filter."""
|
||||
query = select(World).options(selectinload(World.owner))
|
||||
if visibility:
|
||||
query = query.where(World.visibility == visibility)
|
||||
query = query.offset(skip).limit(limit).order_by(World.created_at.desc())
|
||||
result = await db.execute(query)
|
||||
worlds = result.scalars().all()
|
||||
return [
|
||||
{
|
||||
"id": w.id,
|
||||
"name": w.name,
|
||||
"description": w.description,
|
||||
"visibility": w.visibility.value if w.visibility else None,
|
||||
"owner_id": w.owner_id,
|
||||
"created_at": w.created_at.isoformat() if w.created_at else None,
|
||||
}
|
||||
for w in worlds
|
||||
]
|
||||
|
||||
|
||||
@router.get("/{world_id}")
|
||||
async def get_world(
|
||||
world_id: int,
|
||||
db: Annotated[AsyncSession, Depends(get_db)] = Depends(),
|
||||
):
|
||||
"""Get a single world by ID."""
|
||||
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")
|
||||
return {
|
||||
"id": world.id,
|
||||
"name": world.name,
|
||||
"description": world.description,
|
||||
"visibility": world.visibility.value if world.visibility else None,
|
||||
"owner_id": world.owner_id,
|
||||
"created_at": world.created_at.isoformat() if world.created_at else None,
|
||||
}
|
||||
|
||||
|
||||
@router.post("/")
|
||||
async def create_world(
|
||||
world_data: dict,
|
||||
current_user=Depends(get_current_user),
|
||||
db: Annotated[AsyncSession, Depends(get_db)] = Depends(),
|
||||
):
|
||||
"""Create a new world."""
|
||||
name = world_data.get("name")
|
||||
if not name:
|
||||
raise HTTPException(status_code=400, detail="World name is required")
|
||||
|
||||
world = World(
|
||||
name=name,
|
||||
description=world_data.get("description"),
|
||||
owner_id=current_user["id"],
|
||||
visibility=WorldVisibility(
|
||||
world_data.get("visibility", "public")
|
||||
),
|
||||
)
|
||||
db.add(world)
|
||||
await db.commit()
|
||||
await db.refresh(world)
|
||||
|
||||
return {
|
||||
"id": world.id,
|
||||
"name": world.name,
|
||||
"description": world.description,
|
||||
"visibility": world.visibility.value,
|
||||
"owner_id": world.owner_id,
|
||||
"created_at": world.created_at.isoformat() if world.created_at else None,
|
||||
}
|
||||
|
||||
|
||||
@router.put("/{world_id}")
|
||||
async def update_world(
|
||||
world_id: int,
|
||||
world_data: dict,
|
||||
current_user=Depends(get_current_user),
|
||||
db: Annotated[AsyncSession, Depends(get_db)] = Depends(),
|
||||
):
|
||||
"""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_data.get("name"):
|
||||
world.name = world_data["name"]
|
||||
if world_data.get("description") is not None:
|
||||
world.description = world_data["description"]
|
||||
if world_data.get("visibility"):
|
||||
world.visibility = WorldVisibility(world_data["visibility"])
|
||||
|
||||
await db.commit()
|
||||
await db.refresh(world)
|
||||
|
||||
return {
|
||||
"id": world.id,
|
||||
"name": world.name,
|
||||
"description": world.description,
|
||||
"visibility": world.visibility.value if world.visibility else None,
|
||||
"owner_id": world.owner_id,
|
||||
"created_at": world.created_at.isoformat() if world.created_at else None,
|
||||
}
|
||||
|
||||
|
||||
@router.delete("/{world_id}")
|
||||
async def delete_world(
|
||||
world_id: int,
|
||||
current_user=Depends(get_current_user),
|
||||
db: Annotated[AsyncSession, Depends(get_db)] = Depends(),
|
||||
):
|
||||
"""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")
|
||||
|
||||
await db.delete(world)
|
||||
await db.commit()
|
||||
return {"detail": "World deleted"}
|
||||
@@ -1,16 +0,0 @@
|
||||
fastapi==0.115.6
|
||||
uvicorn[standard]==0.34.0
|
||||
sqlalchemy==2.0.36
|
||||
alembic==1.14.0
|
||||
psycopg2-binary==2.9.10
|
||||
redis==5.2.1
|
||||
pydantic==2.10.3
|
||||
pydantic-settings==2.7.0
|
||||
python-jose[cryptography]==3.3.0
|
||||
passlib[bcrypt]==1.7.4
|
||||
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
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user