# anentrypoint/spoint architecture

> Architecture diagram of the GitHub repository anentrypoint/spoint, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anentrypoint/spoint
- Repository: https://github.com/anentrypoint/spoint

## Overview

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: [`src/sdk/server.js`](https://github.com/anentrypoint/spoint/blob/main/src/sdk/server.js) (Server SDK), [`src/netcode/TickSystem.js`](https://github.com/anentrypoint/spoint/blob/main/src/netcode/TickSystem.js) (Tick System), [`apps/world/tps-game.js`](https://github.com/anentrypoint/spoint/blob/main/apps/world/tps-game.js) (World Config), [`src/index.client.js`](https://github.com/anentrypoint/spoint/blob/main/src/index.client.js) (Client Bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server_runtime["Server Runtime"]
  node_server_js["server.js<br/>entrypoint<br/>[server.js]"]
  node_sdk_server["Server SDK<br/>runtime assembly<br/>[server.js]"]
  node_connection_manager["Connections<br/>session management"]
  node_tick_handler["Tick Handler<br/>server loop<br/>[TickHandler.js]"]
  node_tick_system["Tick System<br/>simulation pipeline<br/>[TickSystem.js]"]
  node_physics_integration["Physics Sync<br/>netcode bridge"]
  node_network_state["Net State<br/>replication state<br/>[NetworkState.js]"]
  node_snapshot_encoder["Snapshot Encoder<br/>replication encoder<br/>[SnapshotEncoder.js]"]
  node_physics_world["Physics World<br/>physics runtime<br/>[World.js]"]
end

subgraph group_client_runtime["Client Runtime"]
  node_client_app["client/app.js<br/>browser entrypoint<br/>[app.js]"]
  node_client_bootstrap["Client Bootstrap<br/>client startup<br/>[index.client.js]"]
  node_base_client["Base Client<br/>transport client<br/>[BaseClient.js]"]
  node_prediction_engine["Prediction"]
  node_scene_setup["Scene Setup<br/>three.js scene<br/>[SceneSetup.js]"]
  node_player_manager_client["Player View<br/>avatar presentation<br/>[PlayerManager.js]"]
end

subgraph group_content_apps["Content and Apps"]
  node_app_loader["App Loader<br/>app runtime<br/>[AppLoader.js]"]
  node_app_runtime["App Runtime<br/>app lifecycle<br/>[AppRuntime.js]"]
  node_world_config["World Config<br/>world definition<br/>[tps-game.js]"]
  node_tps_game_app["TPS Game<br/>game app<br/>[index.js]"]
  node_environment_app["Environment<br/>content app<br/>[index.js]"]
end

subgraph group_tooling_sdk["Tooling and SDK"]
  node_editor_shell["Editor Shell<br/>editor ui<br/>[EditorShell.js]"]
  node_reload_manager["Reload Manager<br/>hot reload<br/>[ReloadManager.js]"]
  node_worker_entry["Worker Entry<br/>worker runtime<br/>[WorkerEntry.js]"]
  node_glb_processor["GLB Tools<br/>asset pipeline<br/>[glb-processor.js]"]
end

node_server_js -->|"starts"| node_sdk_server
node_sdk_server -->|"sessions"| node_connection_manager
node_sdk_server -->|"ticks"| node_tick_handler
node_sdk_server -->|"hot reload"| node_reload_manager
node_sdk_server -->|"loads apps"| node_app_loader
node_tick_handler -->|"drives"| node_tick_system
node_tick_system -->|"updates"| node_physics_integration
node_physics_integration -->|"steps"| node_physics_world
node_tick_system -->|"mutates"| node_network_state
node_network_state -->|"encodes"| node_snapshot_encoder
node_tick_system -->|"callbacks"| node_app_runtime
node_app_loader -->|"builds"| node_app_runtime
node_app_loader -->|"reads"| node_world_config
node_world_config -->|"selects"| node_tps_game_app
node_world_config -->|"includes"| node_environment_app
node_client_app -->|"boots"| node_client_bootstrap
node_client_bootstrap -->|"connects"| node_base_client
node_base_client -->|"predicts"| node_prediction_engine
node_prediction_engine -->|"updates view"| node_scene_setup
node_scene_setup -->|"renders"| node_player_manager_client
node_client_bootstrap -.->|"can open"| node_editor_shell
node_reload_manager -->|"serves edits"| node_editor_shell
node_worker_entry -.->|"background tasks"| node_reload_manager
node_glb_processor -.->|"bakes assets"| node_world_config

click node_server_js "https://github.com/anentrypoint/spoint/blob/main/server.js"
click node_sdk_server "https://github.com/anentrypoint/spoint/blob/main/src/sdk/server.js"
click node_connection_manager "https://github.com/anentrypoint/spoint/blob/main/src/connection/ConnectionManager.js"
click node_tick_handler "https://github.com/anentrypoint/spoint/blob/main/src/sdk/TickHandler.js"
click node_tick_system "https://github.com/anentrypoint/spoint/blob/main/src/netcode/TickSystem.js"
click node_physics_integration "https://github.com/anentrypoint/spoint/blob/main/src/netcode/PhysicsIntegration.js"
click node_network_state "https://github.com/anentrypoint/spoint/blob/main/src/netcode/NetworkState.js"
click node_snapshot_encoder "https://github.com/anentrypoint/spoint/blob/main/src/netcode/SnapshotEncoder.js"
click node_physics_world "https://github.com/anentrypoint/spoint/blob/main/src/physics/World.js"
click node_app_loader "https://github.com/anentrypoint/spoint/blob/main/src/apps/AppLoader.js"
click node_app_runtime "https://github.com/anentrypoint/spoint/blob/main/src/apps/AppRuntime.js"
click node_world_config "https://github.com/anentrypoint/spoint/blob/main/apps/world/tps-game.js"
click node_tps_game_app "https://github.com/anentrypoint/spoint/blob/main/apps/tps-game/index.js"
click node_environment_app "https://github.com/anentrypoint/spoint/blob/main/apps/environment/index.js"
click node_client_app "https://github.com/anentrypoint/spoint/blob/main/client/app.js"
click node_client_bootstrap "https://github.com/anentrypoint/spoint/blob/main/src/index.client.js"
click node_base_client "https://github.com/anentrypoint/spoint/blob/main/src/client/BaseClient.js"
click node_prediction_engine "https://github.com/anentrypoint/spoint/blob/main/src/client/PredictionEngine.js"
click node_scene_setup "https://github.com/anentrypoint/spoint/blob/main/client/core/SceneSetup.js"
click node_player_manager_client "https://github.com/anentrypoint/spoint/blob/main/client/PlayerManager.js"
click node_editor_shell "https://github.com/anentrypoint/spoint/blob/main/client/editor/EditorShell.js"
click node_reload_manager "https://github.com/anentrypoint/spoint/blob/main/src/sdk/ReloadManager.js"
click node_worker_entry "https://github.com/anentrypoint/spoint/blob/main/src/sdk/WorkerEntry.js"
click node_glb_processor "https://github.com/anentrypoint/spoint/blob/main/scripts/glb-processor.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_js,node_sdk_server,node_connection_manager,node_tick_handler,node_tick_system,node_physics_integration,node_network_state,node_snapshot_encoder,node_physics_world toneBlue
class node_client_app,node_client_bootstrap,node_base_client,node_prediction_engine,node_scene_setup,node_player_manager_client toneAmber
class node_app_loader,node_app_runtime,node_world_config,node_tps_game_app,node_environment_app toneMint
class node_editor_shell,node_reload_manager,node_worker_entry,node_glb_processor toneRose
```

## Components

### Server Runtime

Authoritative simulation, connection handling, and app execution.

- [server.js](https://github.com/anentrypoint/spoint/blob/main/server.js): entrypoint · Node server entrypoint. · `server.js`
- [Server SDK](https://github.com/anentrypoint/spoint/blob/main/src/sdk/server.js): runtime assembly · Assembles server subsystems and handlers. · `src/sdk/server.js`
- [Connections](https://github.com/anentrypoint/spoint/blob/main/src/connection/ConnectionManager.js): session management · Session lifecycle and connection routing. · `src/connection/ConnectionManager.js`
- [Tick Handler](https://github.com/anentrypoint/spoint/blob/main/src/sdk/TickHandler.js): server loop · Drives the authoritative server tick pipeline. · `src/sdk/TickHandler.js`
- [Tick System](https://github.com/anentrypoint/spoint/blob/main/src/netcode/TickSystem.js): simulation pipeline · Coordinates update order inside the simulation tick. · `src/netcode/TickSystem.js`
- [Physics Sync](https://github.com/anentrypoint/spoint/blob/main/src/netcode/PhysicsIntegration.js): netcode bridge · Synchronizes players between net state and physics proxies. · `src/netcode/PhysicsIntegration.js`
- [Net State](https://github.com/anentrypoint/spoint/blob/main/src/netcode/NetworkState.js): replication state · Server-side state model for snapshots and events. · `src/netcode/NetworkState.js`
- [Snapshot Encoder](https://github.com/anentrypoint/spoint/blob/main/src/netcode/SnapshotEncoder.js): replication encoder · Serializes authoritative state for clients. · `src/netcode/SnapshotEncoder.js`
- [Physics World](https://github.com/anentrypoint/spoint/blob/main/src/physics/World.js): physics runtime · Jolt-backed world wrapper and stepping boundary. · `src/physics/World.js`

### Client Runtime

Browser bootstrap, transport client, prediction, and rendering.

- [client/app.js](https://github.com/anentrypoint/spoint/blob/main/client/app.js): browser entrypoint · Browser bootstrap for the client runtime. · `client/app.js`
- [Client Bootstrap](https://github.com/anentrypoint/spoint/blob/main/src/index.client.js): client startup · Client-side startup and runtime wiring. · `src/index.client.js`
- [Base Client](https://github.com/anentrypoint/spoint/blob/main/src/client/BaseClient.js): transport client · Client transport, messaging, and connection core. · `src/client/BaseClient.js`
- [Prediction](https://github.com/anentrypoint/spoint/blob/main/src/client/PredictionEngine.js): client prediction · Local prediction and reconciliation loop. · `src/client/PredictionEngine.js`
- [Scene Setup](https://github.com/anentrypoint/spoint/blob/main/client/core/SceneSetup.js): three.js scene · Builds the visible world and presentation layers. · `client/core/SceneSetup.js`
- [Player View](https://github.com/anentrypoint/spoint/blob/main/client/PlayerManager.js): avatar presentation · Client-side player avatars and animation state. · `client/PlayerManager.js`

### Content and Apps

World config, gameplay apps, and asset-backed content.

- [App Loader](https://github.com/anentrypoint/spoint/blob/main/src/apps/AppLoader.js): app runtime · Loads game apps and their persistent runtime state. · `src/apps/AppLoader.js`
- [App Runtime](https://github.com/anentrypoint/spoint/blob/main/src/apps/AppRuntime.js): app lifecycle · Runs lifecycle hooks and app-local execution. · `src/apps/AppRuntime.js`
- [World Config](https://github.com/anentrypoint/spoint/blob/main/apps/world/tps-game.js): world definition · Selects map, camera, spawn, physics, and entities. · `apps/world/tps-game.js`
- [TPS Game](https://github.com/anentrypoint/spoint/blob/main/apps/tps-game/index.js): game app · Main gameplay app module and behavior. · `apps/tps-game/index.js`
- [Environment](https://github.com/anentrypoint/spoint/blob/main/apps/environment/index.js): content app · Environment and smart-object content composition. · `apps/environment/index.js`

### Tooling and SDK

Hot reload, editor surfaces, and build/bake support.

- [Editor Shell](https://github.com/anentrypoint/spoint/blob/main/client/editor/EditorShell.js): editor ui · Primary in-browser editor surface. · `client/editor/EditorShell.js`
- [Reload Manager](https://github.com/anentrypoint/spoint/blob/main/src/sdk/ReloadManager.js): hot reload · Live reload and editor-driven server updates. · `src/sdk/ReloadManager.js`
- [Worker Entry](https://github.com/anentrypoint/spoint/blob/main/src/sdk/WorkerEntry.js): worker runtime · Worker-side SDK entry for background execution. · `src/sdk/WorkerEntry.js`
- [GLB Tools](https://github.com/anentrypoint/spoint/blob/main/scripts/glb-processor.js): asset pipeline · Asset processing and bake-time model transforms. · `scripts/glb-processor.js`

## Connections

- 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.