# shanekanterman04/zeus-engine architecture

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

- Interactive diagram: https://gitdiagram.com/shanekanterman04/zeus-engine
- Repository: https://github.com/shanekanterman04/zeus-engine

## Overview

1. **Repository shape**
   - This is a **TypeScript monorepo** for a browser-game engine plus tooling, with one separate **C++ desktop editor** in `apps/zeus-editor`.
   - The TypeScript side is split into focused packages under `packages/`, each intended to be imported independently as `@zeus/*`.

2. **Core runtime boundary**
   - `@zeus/core` is the center of the runtime: it contains app lifecycle, ECS primitives, scene management, world/chunk abstractions, simulation loops, spatial indexing, and shared engine types.
   - Most other runtime packages plug into `@zeus/core` rather than replacing it, so the main architecture is “core loop + optional subsystems.”

3. **Game loop and simulation flow**
   - The core simulation path is organized around fixed-step/update utilities (`FixedStepLoop`, `SystemRunner`, frame metrics) and world/chunk primitives.
   - Data typically flows from the app loop into systems, then into ECS/world state, then out to rendering, input handling, and networking adapters.

4. **Rendering subsystem**
   - `@zeus/renderer-pixi` is the rendering bridge and is explicitly tied to **PixiJS 8**.
   - It sits on the boundary between engine state and draw output, with specialized rendering helpers for atlas handling, lighting, and waterways.
   - In architecture terms, this package consumes core/game state and produces visual output; it does not appear to own simulation logic.

5. **Input, audio, and debug as runtime services**
   - `@zeus/input` provides an input abstraction layer centered on an input context and engine integration.
   - `@zeus/audio` exposes audio services that are likely consumed by the game/runtime layer rather than running standalone.
   - `@zeus/debug` adds non-production runtime instrumentation: console tools and overlays such as FPS display.

6. **Assets and content layer**
   - `@zeus/assets` handles asset/runtime metadata, manifest data, and runtime asset file references.
   - This is the content boundary between authored game assets and the runtime that loads them.
   - The package layout suggests a metadata-driven asset pipeline rather than ad hoc asset paths.

7. **AI helpers**
   - `@zeus/ai` is a lightweight helper package for gameplay behavior: signals, threat classification/metering, roaming, and steering-style utilities.
   - It is not a full agent framework; it looks like reusable gameplay primitives that feed into the core simulation.

8. **Networking architecture**
   - `@zeus/net` provides transport and room abstractions, with both **in-memory** and **WebSocket** implementations.
   - This package defines the transport boundary for local testing and browser/server multiplayer paths.
   - `@zeus/net-colyseus` is an adapter layer for the **Colyseus** ecosystem, kept separate so the core networking package stays framework-neutral.

9. **Tooling and content validation**
   - `@zeus/tools` is the offline/content-authoring side of the repo: sprite generation, atlas packing, sprite-sheet import, foliage placement, hot reload helpers, schema validation, and world review/validation.
   - Its outputs feed the asset/content layer and world data used by the runtime.
   - The presence of world/chunk validation modules indicates a strong “validate before runtime” boundary for authored content.

10. **Editor application**
   - `apps/zeus-editor` is a separate **C++/CMake desktop app**, not part of the TypeScript runtime.
   - Its modules indicate a functional editor shell with asset browsing/studio views, remote exploration, terminal integration, SSH running, and profile/theme/icon support.
   - This app likely acts as an external authoring/operations tool for managing Zeus content and remote environments.

11. **Docs and planning**
   - `docs/zeus/` contains architecture and pipeline planning docs, suggesting the repo is still evolving and the docs are part of the design source of truth.
   - The docs are not just end-user docs; they likely encode the intended engine/content pipeline boundaries.

12. **Build, validation, and test boundaries**
   - Root scripts and GitHub Actions focus on **package builds**, **export checks**, and **type-checking**, which reinforces the package-boundary design.
   - Tests cover critical seams: chunk streaming, networking room behavior, browser/runtime boundary checks, runtime primitives, and world-layer validation.
   - That test mix shows the repo’s highest-risk architecture seams are world streaming, networking, and package interoperability.

13. **How to draw the architecture**
   - A good diagram should place `@zeus/core` in the center, with arrows out to renderer, input, audio, debug, AI, assets, and networking.
   - Put `@zeus/tools` and the C++ editor outside the runtime path as authoring/validation tooling.
   - Show `@zeus/net` as the transport layer with separate in-memory and WebSocket branches, and `@zeus/net-colyseus` as an optional adapter on top.

Main entry points: [`packages/zeus-core/src/ZeusApp.ts`](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/ZeusApp.ts) (Zeus app), [`packages/zeus-tools/src/index.ts`](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-tools/src/index.ts) (Zeus tools), [`apps/zeus-editor/src/main.cpp`](https://github.com/shanekanterman04/zeus-engine/blob/main/apps/zeus-editor/src/main.cpp) (Zeus editor), [`packages/zeus-renderer-pixi/src/index.ts`](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-renderer-pixi/src/index.ts) (Pixi renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime packages"]
  node_core_app["Zeus app<br/>engine app shell<br/>[ZeusApp.ts]"]
  node_core_sim(("Simulation<br/>fixed-step loop<br/>[FixedStepLoop.ts]"))
  node_core_ecs[("ECS<br/>entity state<br/>[ComponentStore.ts]")]
  node_core_world[("World<br/>[world.ts]")]
  node_core_scene["Scenes<br/>scene manager<br/>[SceneManager.ts]"]
  node_core_spatial{{"Spatial<br/>[SpatialHashGrid.ts]"}}
  node_renderer["Pixi renderer<br/>PixiJS bridge<br/>[index.ts]"]
  node_render_atlas["Atlas<br/>[AtlasManifest.ts]"]
  node_render_light["Lighting<br/>[PixiLighting.ts]"]
  node_render_water["Waterways<br/>render effects<br/>[CreekPainter.ts]"]
  node_input["Input<br/>[InputContext.ts]"]
  node_audio["Audio<br/>[AudioService.ts]"]
  node_debug["Debug<br/>runtime instrumentation<br/>[ZeusDebug.ts]"]
  node_ai["AI helpers<br/>gameplay AI<br/>[index.ts]"]
  node_assets["Assets<br/>asset metadata<br/>[AssetManifest.ts]"]
  node_net["Networking<br/>transport layer<br/>[index.ts]"]
  node_net_mem(("In-memory<br/>local transport"))
  node_net_ws(("WebSocket<br/>network transport"))
  node_net_colyseus["Colyseus<br/>network adapter<br/>[index.ts]"]
end

subgraph group_tooling["Tooling"]
  node_tools["Zeus tools<br/>content tooling<br/>[index.ts]"]
  node_tools_sprites["Sprites<br/>sprite pipeline"]
  node_tools_schema["Schemas<br/>content schema<br/>[ContentSchema.ts]"]
  node_tools_world["World validate<br/>world validation"]
  node_tools_reload["Hot reload<br/>content reload<br/>[FileHotReloader.ts]"]
end

subgraph group_desktop["Desktop app"]
  node_editor["Zeus editor<br/>C++ desktop app<br/>[main.cpp]"]
  node_editor_asset["Asset browser<br/>editor module"]
  node_editor_remote["Remote ops<br/>editor module"]
end

subgraph group_docs["Docs"]
  node_docs_engine["Engine plan<br/>design doc<br/>[engine-plan.md]"]
  node_docs_content["Content plan<br/>design doc"]
end

node_core_app -->|"drives"| node_core_sim
node_core_sim -->|"updates"| node_core_ecs
node_core_sim -->|"steps"| node_core_world
node_core_world -->|"indexes"| node_core_spatial
node_core_app -->|"hosts"| node_core_scene
node_core_app -->|"consumes"| node_input
node_core_app -->|"uses"| node_audio
node_core_app -->|"instruments"| node_debug
node_core_app -->|"renders via"| node_renderer
node_renderer -->|"uses"| node_render_atlas
node_renderer -->|"uses"| node_render_light
node_renderer -->|"uses"| node_render_water
node_core_app -->|"extends with"| node_ai
node_core_app -->|"loads"| node_assets
node_core_app -->|"syncs with"| node_net
node_net -->|"implements"| node_net_mem
node_net -->|"implements"| node_net_ws
node_net_colyseus -.->|"adapts"| node_net
node_tools -->|"includes"| node_tools_sprites
node_tools -->|"validates"| node_tools_schema
node_tools -->|"checks"| node_tools_world
node_tools -->|"supports"| node_tools_reload
node_tools -->|"produces"| node_assets
node_tools -->|"authoring boundary"| node_core_world
node_editor -->|"contains"| node_editor_asset
node_editor -->|"contains"| node_editor_remote
node_editor -->|"supports"| node_tools
node_editor -->|"manages"| node_assets
node_docs_engine -.->|"describes"| node_core_app
node_docs_content -.->|"describes"| node_tools

click node_core_app "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/ZeusApp.ts"
click node_core_sim "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/simulation/FixedStepLoop.ts"
click node_core_ecs "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/ecs/ComponentStore.ts"
click node_core_world "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/world.ts"
click node_core_scene "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/scenes/SceneManager.ts"
click node_core_spatial "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/spatial/SpatialHashGrid.ts"
click node_renderer "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-renderer-pixi/src/index.ts"
click node_render_atlas "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-renderer-pixi/src/atlas/AtlasManifest.ts"
click node_render_light "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-renderer-pixi/src/lighting/PixiLighting.ts"
click node_render_water "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-renderer-pixi/src/waterways/CreekPainter.ts"
click node_input "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-input/src/InputContext.ts"
click node_audio "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-audio/src/AudioService.ts"
click node_debug "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-debug/src/ZeusDebug.ts"
click node_ai "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-ai/src/index.ts"
click node_assets "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-assets/src/AssetManifest.ts"
click node_net "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-net/src/index.ts"
click node_net_mem "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-net/src/inMemoryTransport.ts"
click node_net_ws "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-net/src/webSocketProtocol.ts"
click node_net_colyseus "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-net-colyseus/src/index.ts"
click node_tools "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-tools/src/index.ts"
click node_tools_sprites "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-tools/src/sprites/PixelSpriteGenerator.ts"
click node_tools_schema "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-tools/src/schema/ContentSchema.ts"
click node_tools_world "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-tools/src/world/WorldLayerValidation.ts"
click node_tools_reload "https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-tools/src/hot-reload/FileHotReloader.ts"
click node_editor "https://github.com/shanekanterman04/zeus-engine/blob/main/apps/zeus-editor/src/main.cpp"
click node_editor_asset "https://github.com/shanekanterman04/zeus-engine/blob/main/apps/zeus-editor/src/AssetBrowserWidget.cpp"
click node_editor_remote "https://github.com/shanekanterman04/zeus-engine/blob/main/apps/zeus-editor/src/RemoteExplorerWidget.cpp"
click node_docs_engine "https://github.com/shanekanterman04/zeus-engine/blob/main/docs/zeus/engine-plan.md"
click node_docs_content "https://github.com/shanekanterman04/zeus-engine/blob/main/docs/zeus/content-pipeline.md"

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_core_app,node_core_sim,node_core_ecs,node_core_world,node_core_scene,node_core_spatial,node_renderer,node_render_atlas,node_render_light,node_render_water,node_input,node_audio,node_debug,node_ai,node_assets,node_net,node_net_mem,node_net_ws,node_net_colyseus toneBlue
class node_tools,node_tools_sprites,node_tools_schema,node_tools_world,node_tools_reload toneAmber
class node_editor,node_editor_asset,node_editor_remote toneMint
class node_docs_engine,node_docs_content toneRose
```

## Components

### Runtime packages

Core engine and runtime-adjacent packages

- [Zeus app](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/ZeusApp.ts): engine app shell · Top-level runtime lifecycle and integration point · `packages/zeus-core/src/ZeusApp.ts`
- [Simulation](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/simulation/FixedStepLoop.ts): fixed-step loop · Frame timing, system execution, and simulation metrics · `packages/zeus-core/src/simulation/FixedStepLoop.ts`
- [ECS](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/ecs/ComponentStore.ts): entity state · Component storage and ECS primitives · `packages/zeus-core/src/ecs/ComponentStore.ts`
- [World](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/world.ts): world/chunks · World state, layers, chunks, and streaming boundaries · `packages/zeus-core/src/world.ts`
- [Scenes](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/scenes/SceneManager.ts): scene manager · Scene orchestration and transitions · `packages/zeus-core/src/scenes/SceneManager.ts`
- [Spatial](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-core/src/spatial/SpatialHashGrid.ts): spatial index · Spatial hashing for proximity and lookup · `packages/zeus-core/src/spatial/SpatialHashGrid.ts`
- [Pixi renderer](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-renderer-pixi/src/index.ts): PixiJS bridge · Rendering boundary between engine state and visual output · `packages/zeus-renderer-pixi/src/index.ts`
- [Atlas](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-renderer-pixi/src/atlas/AtlasManifest.ts): texture atlas · Atlas manifest and sprite resource mapping · `packages/zeus-renderer-pixi/src/atlas/AtlasManifest.ts`
- [Lighting](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-renderer-pixi/src/lighting/PixiLighting.ts): render lighting · Pixi lighting integration · `packages/zeus-renderer-pixi/src/lighting/PixiLighting.ts`
- [Waterways](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-renderer-pixi/src/waterways/CreekPainter.ts): render effects · Specialized creek and water rendering · `packages/zeus-renderer-pixi/src/waterways/CreekPainter.ts`
- [Input](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-input/src/InputContext.ts): input context · Engine input abstraction and context · `packages/zeus-input/src/InputContext.ts`
- [Audio](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-audio/src/AudioService.ts): audio service · Runtime audio service consumed by the engine · `packages/zeus-audio/src/AudioService.ts`
- [Debug](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-debug/src/ZeusDebug.ts): runtime instrumentation · Console tools and FPS overlay · `packages/zeus-debug/src/ZeusDebug.ts`
- [AI helpers](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-ai/src/index.ts): gameplay AI · Signals, roaming, threat, and steering helpers · `packages/zeus-ai/src/index.ts`
- [Assets](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-assets/src/AssetManifest.ts): asset metadata · Runtime asset manifest and metadata boundary · `packages/zeus-assets/src/AssetManifest.ts`
- [Networking](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-net/src/index.ts): transport layer · Transport and room abstractions for local and websocket paths · `packages/zeus-net/src/index.ts`
- [In-memory](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-net/src/inMemoryTransport.ts): local transport · In-memory transport and room host/client path · `packages/zeus-net/src/inMemoryTransport.ts`
- [WebSocket](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-net/src/webSocketProtocol.ts): network transport · WebSocket room client/server implementation · `packages/zeus-net/src/webSocketProtocol.ts`
- [Colyseus](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-net-colyseus/src/index.ts): network adapter · Optional adapter for the Colyseus ecosystem · `packages/zeus-net-colyseus/src/index.ts`

### Tooling

Offline content and validation tools

- [Zeus tools](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-tools/src/index.ts): content tooling · Offline sprite, schema, validation, and world tooling · `packages/zeus-tools/src/index.ts`
- [Sprites](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-tools/src/sprites/PixelSpriteGenerator.ts): sprite pipeline · Sprite generation, packing, and sheet import · `packages/zeus-tools/src/sprites/PixelSpriteGenerator.ts`
- [Schemas](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-tools/src/schema/ContentSchema.ts): content schema · Content schema validation and shared rules · `packages/zeus-tools/src/schema/ContentSchema.ts`
- [World validate](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-tools/src/world/WorldLayerValidation.ts): world validation · Chunk, layer, and review validation for authored world data · `packages/zeus-tools/src/world/WorldLayerValidation.ts`
- [Hot reload](https://github.com/shanekanterman04/zeus-engine/blob/main/packages/zeus-tools/src/hot-reload/FileHotReloader.ts): content reload · File hot reloader and last-valid content retention · `packages/zeus-tools/src/hot-reload/FileHotReloader.ts`

### Desktop app

C++ editor application

- [Zeus editor](https://github.com/shanekanterman04/zeus-engine/blob/main/apps/zeus-editor/src/main.cpp): C++ desktop app · Standalone desktop authoring and operations tool · `apps/zeus-editor/src/main.cpp`
- [Asset browser](https://github.com/shanekanterman04/zeus-engine/blob/main/apps/zeus-editor/src/AssetBrowserWidget.cpp): editor module · Asset browsing and studio views · `apps/zeus-editor/src/AssetBrowserWidget.cpp`
- [Remote ops](https://github.com/shanekanterman04/zeus-engine/blob/main/apps/zeus-editor/src/RemoteExplorerWidget.cpp): editor module · Remote exploration, SSH running, and terminal bridge · `apps/zeus-editor/src/RemoteExplorerWidget.cpp`

### Docs

Architecture and pipeline planning docs

- [Engine plan](https://github.com/shanekanterman04/zeus-engine/blob/main/docs/zeus/engine-plan.md): design doc · Engine architecture and intended runtime boundaries · `docs/zeus/engine-plan.md`
- [Content plan](https://github.com/shanekanterman04/zeus-engine/blob/main/docs/zeus/content-pipeline.md): design doc · Content pipeline and tooling direction · `docs/zeus/content-pipeline.md`

## Connections

- Zeus app → Simulation: drives · App lifecycle advances the simulation loop
- Simulation → ECS: updates · Fixed-step systems mutate ECS state
- Simulation → World: steps · Simulation advances world and chunk state
- World → Spatial: indexes · World state uses spatial lookup structures
- Zeus app → Scenes: hosts · Top-level app coordinates scenes
- Zeus app → Input: consumes · Engine app reads input context
- Zeus app → Audio: uses · Runtime integrates audio service
- Zeus app → Debug: instruments · Debug tools attach to the running app
- Zeus app → Pixi renderer: renders via · App hands engine state to the renderer bridge
- Pixi renderer → Atlas: uses · Renderer consumes atlas metadata
- Pixi renderer → Lighting: uses · Renderer applies lighting helpers
- Pixi renderer → Waterways: uses · Renderer applies water rendering helpers
- Zeus app → AI helpers: extends with · Gameplay helpers plug into core simulation
- Zeus app → Assets: loads · Runtime consumes asset manifests and metadata
- Zeus app → Networking: syncs with · Runtime connects to transport and room abstractions
- Networking → In-memory: implements · In-memory branch for local testing
- Networking → WebSocket: implements · WebSocket branch for browser/server multiplayer
- Colyseus → Networking: adapts · Optional Colyseus integration wraps the neutral network layer
- Zeus tools → Sprites: includes · Tooling covers sprite generation and packing
- Zeus tools → Schemas: validates · Tooling enforces content schemas
- Zeus tools → World validate: checks · Tooling validates world and chunk data
- Zeus tools → Hot reload: supports · Tooling supports hot reload workflows
- Zeus tools → Assets: produces · Offline tooling feeds runtime asset metadata
- Zeus tools → World: authoring boundary · Validated content targets world data used by runtime
- Zeus editor → Asset browser: contains · Editor shell hosts asset browsing and studio views
- Zeus editor → Remote ops: contains · Editor shell hosts remote exploration and terminal tools
- Zeus editor → Zeus tools: supports · Desktop editor complements offline content workflows
- Zeus editor → Assets: manages · Editor interacts with asset content and browsing
- Engine plan → Zeus app: describes · Planning docs define engine boundaries
- Content plan → Zeus tools: describes · Planning docs define content pipeline tooling
