How anentrypoint/spoint works
1. Overall shape
- This repo is an authoritative multiplayer game SDK with a Node.js server, a Three.js browser client, a Jolt-based physics layer, and an app/plugin system for game-specific behavior.
- The main runtime boundary is server authority vs. client presentation/prediction.
2. Entry points and packaging
- server.js is the main runtime entry on the server side.
- client/app.js is the browser client bootstrap.
- src/sdk/server.js assembles the server subsystems; src/index.client.js and client/app.js define the client startup path.
- apps/ contains game/app modules, while apps/world/ holds the world configuration that selects the current map, physics, camera, spawn point, and entities.
3. World configuration and app composition
- The world config in apps/world/tps-game.js / apps/world/tps-game.hf and the README example show how the world is composed from:
- static environment entities,
- interactive “app” entities,
- player model and movement settings,
- camera and scene parameters.
- src/apps/AppLoader.js, AppRuntime.js, AppContext.js, and Lifecycle.js provide the runtime that loads app modules from apps/*/index.js, keeps persistent app state, and runs lifecycle hooks.
4. Server simulation loop
- The server tick pipeline is centered in src/apps/TickHandler.js and related runtime code.
- The simulation order is described in the README and supported by modules like src/netcode/TickSystem.js, src/netcode/PhysicsIntegration.js, and src/physics/World.js:
- input/state update,
- movement,
- physics stepping,
- collision handling,
- app callbacks,
- snapshot generation and broadcast.
- This is the core “authoritative state” boundary for the diagram.
5. Physics and collision subsystem
- src/physics/World.js wraps the Jolt physics world.
- src/physics/CharacterManager.js, ShapeBuilder.js, GLBLoader.js, and decompressor helpers support player capsules and mesh-derived colliders.
- src/netcode/CollisionSystem.js, src/netcode/LagCompensator.js, and src/spatial/Octree.js support gameplay collision queries, hit detection, and spatial filtering.
- Terrain-specific physics lives under src/terrain/ for grass, rocks, vegetation, and terrain interaction.
6. Netcode and authoritative state replication
- src/netcode/NetworkState.js, SnapshotEncoder.js, EventLog.js, and PlayerManager.js represent server state and produce network snapshots.
- src/netcode/LagCompensator.js supports rewind-style hit validation, which matters for FPS-style interactions.
- src/netcode/PhysicsIntegration.js connects each player to a physics character proxy, keeping server simulation and network state aligned.
7. Client networking and prediction
- The client-side network stack is in src/client/:
- BaseClient.js, PhysicsNetworkClient.js, MessageHandler.js, and InputHandler.js manage transport and message flow.
- PredictionEngine.js, ReconciliationEngine.js, SnapshotProcessor.js, and interpolation utilities handle client prediction, correction, and smoothing.
- JitterBuffer.js and SmoothInterpolation.js absorb network variance.
- The data flow is: local input → predicted movement → server snapshots → reconciliation/interpolation.
8. Browser rendering and game presentation
- client/app.js and client/core/ own the rendering and scene presentation path.
- client/core/SceneSetup.js, SceneGraph.js, TerrainBackdrop.js, Vegetation.js, Grass.js, Rocks.js, and camera helpers construct the visible world in Three.js.
- client/PlayerManager.js, PlayerAnimator.js, AnimationLibrary.js, and facial-animation.js handle player avatars, animations, and model-driven presentation.
9. Editor and hot-reload tooling
- The repo has a strong in-browser editor system under client/editor/ and supporting server SDK modules under src/sdk/.
- src/sdk/ReloadManager.js, HotReloadQueue.js, ReloadHandlers.js, and EditorHandlers.js support live app reloads without restarting the whole server.
- client/editor/EditorShell.js, SceneHierarchy.js, EditorInspector.js, and HookFlowViewer.js are the main UI surfaces for editing scene entities and app behavior.
10. Singleplayer and local-client mode
- The README’s ?singleplayer mode uses client/singleplayer-world.json and bypasses the networked server path.
- The client still runs the same rendering and simulation-facing APIs, but client/LocalClient.js/local client logic becomes the network stand-in.
- This is an important architecture boundary: same game app and scene code, different transport/backend.
11. Transports and runtime connectivity
- The repo supports multiple transport layers under src/transport/:
- WebSocket,
- WebTransport,
- worker-based transport,
- and a Wireweave transport/client path.
- src/connection/ConnectionManager.js and SessionStore.js handle session lifecycle on the server.
- This makes transport an interchangeable layer beneath the authoritative simulation and above the client prediction stack.
12. Assets, maps, and build pipeline
- Game content is heavily asset-driven: apps/maps/*.glb, client/anim-lib.glb, VRM/GLB player models, and data/placed-models.json.
- scripts/ contains asset-processing and bake steps for heightfields, GLB optimization, terrain fixes, vegetation placement, and model transforms.
- src/static/ and client/basis/ indicate runtime support for compressed/static assets and progressive baking.
13. External surface and deployment
- .github/workflows/ includes publishing and GitHub Pages deployment, and the README demo points to a hosted build.
- nixpacks.toml and package.json suggest the project is built and run as a Node-based app with browser output, but the architecture itself is dominated by the server simulation + browser client split rather than a traditional web backend/frontend app.
Main entry points: server.js Server SDK · TickSystem.js Tick System · tps-game.js World Config · index.client.js Client Bootstrap
Components 24
Server Runtime
Authoritative simulation, connection handling, and app execution.
- server.js · Node server entrypoint.
server.js - Server SDK · Assembles server subsystems and handlers.
src/sdk/server.js - Connections · Session lifecycle and connection routing.
src/connection/ConnectionManager.js - Tick Handler · Drives the authoritative server tick pipeline.
src/sdk/TickHandler.js - Tick System · Coordinates update order inside the simulation tick.
src/netcode/TickSystem.js - Physics Sync · Synchronizes players between net state and physics proxies.
src/netcode/PhysicsIntegration.js - Net State · Server-side state model for snapshots and events.
src/netcode/NetworkState.js - Snapshot Encoder · Serializes authoritative state for clients.
src/netcode/SnapshotEncoder.js - Physics World · Jolt-backed world wrapper and stepping boundary.
src/physics/World.js
Client Runtime
Browser bootstrap, transport client, prediction, and rendering.
- client/app.js · Browser bootstrap for the client runtime.
client/app.js - Client Bootstrap · Client-side startup and runtime wiring.
src/index.client.js - Base Client · Client transport, messaging, and connection core.
src/client/BaseClient.js - Prediction · Local prediction and reconciliation loop.
src/client/PredictionEngine.js - Scene Setup · Builds the visible world and presentation layers.
client/core/SceneSetup.js - Player View · Client-side player avatars and animation state.
client/PlayerManager.js
Content and Apps
World config, gameplay apps, and asset-backed content.
- App Loader · Loads game apps and their persistent runtime state.
src/apps/AppLoader.js - App Runtime · Runs lifecycle hooks and app-local execution.
src/apps/AppRuntime.js - World Config · Selects map, camera, spawn, physics, and entities.
apps/world/tps-game.js - TPS Game · Main gameplay app module and behavior.
apps/tps-game/index.js - Environment · Environment and smart-object content composition.
apps/environment/index.js
Tooling and SDK
Hot reload, editor surfaces, and build/bake support.
- Editor Shell · Primary in-browser editor surface.
client/editor/EditorShell.js - Reload Manager · Live reload and editor-driven server updates.
src/sdk/ReloadManager.js - Worker Entry · Worker-side SDK entry for background execution.
src/sdk/WorkerEntry.js - GLB Tools · Asset processing and bake-time model transforms.
scripts/glb-processor.js
Connections 24
- server.js → Server SDK: starts · Main Node entry initializes the server SDK.
- Server SDK → Connections: sessions · Creates and manages client sessions.
- Server SDK → Tick Handler: ticks · Wires the authoritative tick loop.
- Server SDK → Reload Manager: hot reload · Enables live app and editor updates.
- Server SDK → App Loader: loads apps · Bootstraps gameplay modules from apps/*.
- Tick Handler → Tick System: drives · Advances simulation in ordered stages.
- Tick System → Physics Sync: updates · Keeps player physics aligned with net state.
- Physics Sync → Physics World: steps · Runs authoritative physics simulation.
- Tick System → Net State: mutates · Applies input and state changes to server state.
- Net State → Snapshot Encoder: encodes · Produces network snapshots for clients.
- Tick System → App Runtime: callbacks · Invokes app lifecycle and gameplay hooks.
- App Loader → App Runtime: builds · Creates runtime instances for each app.
- App Loader → World Config: reads · Uses world composition and spawn configuration.
- World Config → TPS Game: selects · World config references the main gameplay app.
- World Config → Environment: includes · World config composes environment content.
- client/app.js → Client Bootstrap: boots · Browser entry hands off to client startup.
- Client Bootstrap → Base Client: connects · Creates the client transport and messaging core.
- Base Client → Prediction: predicts · Feeds local input into prediction and reconciliation.
- Prediction → Scene Setup: updates view · Reconciled state drives scene presentation.
- Scene Setup → Player View: renders · Builds avatar and animation presentation.
- Client Bootstrap → Editor Shell: can open · Editor mode overlays the client runtime.
- Reload Manager → Editor Shell: serves edits · Hot reload supports editor-driven iteration.
- Worker Entry → Reload Manager: background tasks · Worker runtime can participate in reload workflows.
- GLB Tools → World Config: bakes assets · Asset tooling feeds the world/content pipeline.