System overview
Thirdwurld is a persistent, real-time 3D environment in which human clients and autonomous residents use the same world protocol. The server owns world state, identity, authorization, persistence, and accepted mutations. Browser and headless clients render or act on the state they receive.
Runtime topology
| Runtime | Responsibilities | Primary implementation |
|---|---|---|
| Browser | Render the world, collect input, present 2D and in-world UI, interpolate remote motion | src/client |
| Server | Own canonical entities, permissions, events, assets, account state, and durable writes | src/server |
| Headless resident | Run navigation, activities, memory context, conversation, and approved world actions | src/server/residents.js |
| Shared engine | Entity graph, systems, packets, physics integration, nodes, and scripting interfaces | src/core |
| Asset pipeline | Generate, bake, optimize, and validate GLB, VRM, texture, and collision assets | scripts, art/blender |
JavaScript and ESM are shared across the browser, server, and headless resident runtimes. PhysX is compiled to WebAssembly so collision behavior does not depend on a separate physics implementation for each participant type.
Authoritative action flow
- IntentA human or resident selects an allowed action and submits typed context.
- TransportThe client sends a binary packet over the shared WebSocket protocol.
- ValidationThe server checks identity, scope, current state, target, and idempotency.
- MutationAn authorized service changes canonical state inside the server boundary.
- ReceiptThe result is recorded as state, an event, or a bounded failure result.
- ProjectionEach audience receives only the fields and visibility level it is allowed to read.
Design invariant
Client rendering or UI state never substitutes for server authorization or a durable receipt.
Persistence
Knex provides one data-access layer across local SQLite and production Postgres. Boot-time migrations create additive schemas. World state, accounts, events, resident memory, relationship state, intent facts, and approved Host changes use distinct stores and visibility rules.
| Data class | Storage | Continuity |
|---|---|---|
| World and account state | SQL through Knex | Persists across server restart |
| World events | Typed event records | Idempotent, visibility-aware history |
| Resident memory | Structured SQL records with optional vector recall | Keyword fallback remains available |
| Assets | Local disk or object storage | Backend selected through configuration |
| Transient simulation | Process memory | Reconstructed from durable state after restart |
Build and delivery
A single esbuild pipeline produces browser, server, and headless-client bundles. The Docker build
uses separate builder and runtime stages. Railway health checks use /status, which
reports build time and the best available commit provenance.
- CompileBundle the three JavaScript runtimes and copy versioned static assets.
- PackageCreate a reduced runtime image containing the build, dependencies, scripts, and source assets required at run time.
- Health checkRequire the HTTP status route before a deployment becomes active.
- Acceptance checkVerify exact product routes and browser behavior after deployment.
Current boundaries
- A successful deploy and HTTP 200 establish availability, not complete gameplay correctness.
- Resident behavior is constrained by allowlisted actions, finite routines, and server checks.
- Model providers are optional; deterministic fallback behavior keeps core world state available.
- Python is used for asset production and validation, not the request-time application runtime.
- The public documentation describes implementation evidence, not user adoption or commercial scale.