How shanekanterman04/zeus-engine works
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: ZeusApp.ts Zeus app · src/index.ts Zeus tools · main.cpp Zeus editor · src/index.ts Pixi renderer
Components 29
Runtime packages
Core engine and runtime-adjacent packages
- Zeus app · Top-level runtime lifecycle and integration point
packages/zeus-core/src/ZeusApp.ts - Simulation · Frame timing, system execution, and simulation metrics
packages/zeus-core/src/simulation/FixedStepLoop.ts - ECS · Component storage and ECS primitives
packages/zeus-core/src/ecs/ComponentStore.ts - World · World state, layers, chunks, and streaming boundaries
packages/zeus-core/src/world.ts - Scenes · Scene orchestration and transitions
packages/zeus-core/src/scenes/SceneManager.ts - Spatial · Spatial hashing for proximity and lookup
packages/zeus-core/src/spatial/SpatialHashGrid.ts - Pixi renderer · Rendering boundary between engine state and visual output
packages/zeus-renderer-pixi/src/index.ts - Atlas · Atlas manifest and sprite resource mapping
packages/zeus-renderer-pixi/src/atlas/AtlasManifest.ts - Lighting · Pixi lighting integration
packages/zeus-renderer-pixi/src/lighting/PixiLighting.ts - Waterways · Specialized creek and water rendering
packages/zeus-renderer-pixi/src/waterways/CreekPainter.ts - Input · Engine input abstraction and context
packages/zeus-input/src/InputContext.ts - Audio · Runtime audio service consumed by the engine
packages/zeus-audio/src/AudioService.ts - Debug · Console tools and FPS overlay
packages/zeus-debug/src/ZeusDebug.ts - AI helpers · Signals, roaming, threat, and steering helpers
packages/zeus-ai/src/index.ts - Assets · Runtime asset manifest and metadata boundary
packages/zeus-assets/src/AssetManifest.ts - Networking · Transport and room abstractions for local and websocket paths
packages/zeus-net/src/index.ts - In-memory · In-memory transport and room host/client path
packages/zeus-net/src/inMemoryTransport.ts - WebSocket · WebSocket room client/server implementation
packages/zeus-net/src/webSocketProtocol.ts - Colyseus · Optional adapter for the Colyseus ecosystem
packages/zeus-net-colyseus/src/index.ts
Tooling
Offline content and validation tools
- Zeus tools · Offline sprite, schema, validation, and world tooling
packages/zeus-tools/src/index.ts - Sprites · Sprite generation, packing, and sheet import
packages/zeus-tools/src/sprites/PixelSpriteGenerator.ts - Schemas · Content schema validation and shared rules
packages/zeus-tools/src/schema/ContentSchema.ts - World validate · Chunk, layer, and review validation for authored world data
packages/zeus-tools/src/world/WorldLayerValidation.ts - Hot reload · File hot reloader and last-valid content retention
packages/zeus-tools/src/hot-reload/FileHotReloader.ts
Desktop app
C++ editor application
- Zeus editor · Standalone desktop authoring and operations tool
apps/zeus-editor/src/main.cpp - Asset browser · Asset browsing and studio views
apps/zeus-editor/src/AssetBrowserWidget.cpp - Remote ops · Remote exploration, SSH running, and terminal bridge
apps/zeus-editor/src/RemoteExplorerWidget.cpp
Docs
Architecture and pipeline planning docs
- Engine plan · Engine architecture and intended runtime boundaries
docs/zeus/engine-plan.md - Content plan · Content pipeline and tooling direction
docs/zeus/content-pipeline.md
Connections 30
- 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