# ruddle/oxidator architecture

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

- Interactive diagram: https://gitdiagram.com/ruddle/oxidator
- Repository: https://github.com/ruddle/oxidator

## Overview

1. **Overall shape**
   - This is a single Rust application that combines an RTS game engine, map editor, unit editor, local multiplayer networking, and rendering.
   - The executable seems to select a client “mode” at runtime: play, map editing, or unit editing, rather than splitting into separate programs.

2. **Core runtime / entrypoint**
   - `src/main.rs` is the top-level entrypoint.
   - `src/frame.rs` and `src/frame_server/` suggest a frame-ticked runtime layer that coordinates simulation and rendering work, likely helping decouple update cadence from presentation.

3. **Client-side application layer**
   - `src/client/` is the main front-end subsystem.
   - It contains mode-specific flows like `play.rs`, `map_editor.rs`-equivalent functionality via `heightmap_editor.rs`, and `unit_editor.rs`, plus shared UI/input/camera code.
   - `client/game_state.rs` is the likely central state model used by the current mode and rendering.

4. **Input, camera, and UI boundaries**
   - `client/input_state.rs` owns raw input state and is the boundary between OS/window events and game/editor actions.
   - `client/camera.rs` handles view control.
   - `client/uitool.rs` and `client/misc.rs` appear to provide common interaction utilities for editor overlays and in-game UI.

5. **Simulation / world logic**
   - `src/unit.rs`, `src/mobile.rs`, `src/heightmap_phy.rs`, `src/manager.rs`, and likely `src/model.rs` hold the gameplay simulation and entity/terrain logic.
   - The README confirms early support for collision, flocking, health/damage, construction/repair, selection, move/build orders, and terrain interaction.
   - This is the non-rendering side of the engine: the authoritative world state that rendering and networking consume.

6. **Map and terrain subsystem**
   - `src/asset/map/` contains example map data, and `src/client/heightmap_editor.rs` indicates terrain editing is a first-class workflow.
   - `src/gpu_obj/heightmap_gpu.rs` and `src/gpu_obj/heightmap_helper.rs` show terrain is also a specialized GPU-rendered object, not just a simulation data structure.
   - `src/heightmap_phy.rs` likely provides terrain-aware physics or movement constraints.

7. **Units, definitions, and mod data**
   - `src/botdef.rs` and `src/moddef.rs` define data-driven unit/mod metadata.
   - Example JSON assets in `src/asset/botdef/` show units/buildings are represented as external definitions rather than hardcoded types.
   - This is an important content boundary: gameplay content is intended to be editable without changing engine code.

8. **Rendering architecture**
   - `src/client/render.rs` is the high-level render coordinator.
   - `src/gpu_obj/` is the rendering backend abstraction layer, with dedicated GPU objects for models, terrain, water, lines, health bars, explosions, unit icons, arrows, post-processing, and texture blits.
   - The renderer is built around WebGPU via `wgpu`, with specialized pipelines for each visual subsystem rather than one monolithic shader path.

9. **Shader and asset pipeline**
   - Source shaders live in `src/shader/`, and precompiled SPIR-V is checked into `src/shader/compiled/`.
   - The README notes hot reload and alternate shader compilation paths (`shaderc` or `glsl_to_spirv`), so the build/runtime pipeline includes shader compilation as a first-class concern.
   - 3D geometry is stored as OBJ assets under `src/asset/3d/`, including tank parts and debug meshes.

10. **Networking**
   - `src/net_client.rs` and `src/net_server.rs` implement a local TCP client/server proof of concept for multiplayer.
   - The README frames networking as high-latency and host-driven, so the current design is not a low-latency lockstep system.
   - Networking is expected to exchange player inputs/state for an RTS session, with future lobby/host-swapping functionality not yet present.

11. **Editor-specific subsystems**
   - `src/client/unit_editor.rs` handles node hierarchy editing, joint selection, mesh selection, and parameter editing for unit definitions.
   - `src/client/heightmap_editor.rs` handles terrain editing operations like raise/lower/flatten/blur/noise.
   - These editors are embedded tools inside the game engine, sharing rendering, camera, and UI infrastructure with play mode.

12. **Supporting GPU utilities**
   - `src/gpu_obj/` also contains lower-level helpers like GLSL compilation, texture copy, image/UI integration, and generic GPU traits.
   - This layer separates reusable graphics infrastructure from the higher-level game/editor logic.

13. **Data flow to picture an architecture diagram**
   - OS/window/input events enter the client layer.
   - Client mode code updates game/editor state.
   - Simulation/world state evolves through unit, terrain, and manager subsystems.
   - Render code reads that state and sends draw data through specialized GPU objects into WebGPU.
   - Network code sits beside simulation, feeding remote state/input into the same game loop.

14. **What to treat as external boundaries**
   - WebGPU/wgpu and winit are the primary platform/runtime dependencies.
   - ImGui-style tooling is present through `gpu_obj/imgui_wgpu.rs` and shader support, which matters because much of the editor UX is immediate-mode UI layered on top of the game renderer.
   - Assets and definitions are file-based and versionable, which is central to the project’s mod/editor goals.

Main entry points: [`src/gpu_obj/mod.rs`](https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/mod.rs) (GPU layer), [`src/client/unit_editor.rs`](https://github.com/ruddle/oxidator/blob/master/src/client/unit_editor.rs) (Unit editor), [`src/manager.rs`](https://github.com/ruddle/oxidator/blob/master/src/manager.rs) (Manager), [`src/client/play.rs`](https://github.com/ruddle/oxidator/blob/master/src/client/play.rs) (Play mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("Main<br/>entrypoint<br/>[main.rs]"))
  node_frame["Frame<br/>tick runtime<br/>[frame.rs]"]
  node_frame_server["Frame server<br/>server loop<br/>[mod.rs]"]
end

subgraph group_client["Client"]
  node_client_mod["Client core<br/>app shell<br/>[mod.rs]"]
  node_play["Play mode<br/>game mode<br/>[play.rs]"]
  node_heightmap_editor["Terrain editor<br/>editor mode"]
  node_unit_editor["Unit editor<br/>editor mode<br/>[unit_editor.rs]"]
  node_input_state["Input state<br/>input boundary<br/>[input_state.rs]"]
  node_camera["Camera<br/>view control<br/>[camera.rs]"]
  node_game_state["Game state<br/>shared state<br/>[game_state.rs]"]
  node_uitool["UI tools<br/>interaction helpers<br/>[uitool.rs]"]
end

subgraph group_sim["Simulation"]
  node_unit["Units<br/>simulation<br/>[unit.rs]"]
  node_mobile["Movement<br/>simulation<br/>[mobile.rs]"]
  node_manager["Manager<br/>simulation<br/>[manager.rs]"]
  node_heightmap_phy["Terrain physics<br/>simulation<br/>[heightmap_phy.rs]"]
  node_model["Model<br/>simulation data<br/>[model.rs]"]
end

subgraph group_render["Rendering"]
  node_render["Render<br/>[render.rs]"]
  node_gpu_mod["GPU layer<br/>gpu backend<br/>[mod.rs]"]
  node_heightmap_gpu["Terrain GPU<br/>gpu object<br/>[heightmap_gpu.rs]"]
  node_model_gpu["Model GPU<br/>gpu object<br/>[model_gpu.rs]"]
  node_post_fx["Post FX<br/>gpu object<br/>[post_fx.rs]"]
  node_imgui_wgpu["UI GPU<br/>gpu object<br/>[imgui_wgpu.rs]"]
  node_unit_icon["Unit icons<br/>gpu object<br/>[unit_icon.rs]"]
  node_health_bar["Health bars<br/>gpu object<br/>[health_bar.rs]"]
  node_water["Water<br/>gpu object<br/>[water.rs]"]
  node_line["Lines<br/>gpu object<br/>[line.rs]"]
end

subgraph group_content["Content"]
  node_botdef["Bot defs<br/>content schema<br/>[botdef.rs]"]
  node_moddef["Mod defs<br/>content schema<br/>[moddef.rs]"]
end

subgraph group_net["Networking"]
  node_net_client["Net client<br/>tcp client<br/>[net_client.rs]"]
  node_net_server["Net server<br/>tcp server<br/>[net_server.rs]"]
end

node_main -->|"drives"| node_frame
node_main -->|"starts"| node_client_mod
node_frame -->|"syncs"| node_frame_server
node_client_mod -->|"selects"| node_play
node_client_mod -->|"selects"| node_heightmap_editor
node_client_mod -->|"selects"| node_unit_editor
node_play -->|"uses"| node_game_state
node_heightmap_editor -->|"uses"| node_game_state
node_unit_editor -->|"uses"| node_game_state
node_input_state -->|"feeds"| node_play
node_input_state -->|"feeds"| node_heightmap_editor
node_input_state -->|"feeds"| node_unit_editor
node_camera -->|"views"| node_render
node_play -->|"updates"| node_render
node_heightmap_editor -->|"updates"| node_render
node_unit_editor -->|"updates"| node_render
node_render -->|"builds on"| node_gpu_mod
node_gpu_mod -->|"includes"| node_heightmap_gpu
node_gpu_mod -->|"includes"| node_model_gpu
node_gpu_mod -->|"includes"| node_post_fx
node_gpu_mod -->|"includes"| node_imgui_wgpu
node_gpu_mod -->|"includes"| node_unit_icon
node_gpu_mod -->|"includes"| node_health_bar
node_gpu_mod -->|"includes"| node_water
node_gpu_mod -->|"includes"| node_line
node_manager -->|"orchestrates"| node_unit
node_unit -->|"uses"| node_mobile
node_manager -->|"consults"| node_heightmap_phy
node_manager -->|"owns"| node_model
node_botdef -->|"edited by"| node_unit_editor
node_moddef -->|"edited by"| node_unit_editor
node_net_client -->|"feeds"| node_manager
node_net_server -->|"feeds"| node_manager
node_net_client -->|"supports"| node_play
node_net_server -->|"supports"| node_frame_server

click node_main "https://github.com/ruddle/oxidator/blob/master/src/main.rs"
click node_frame "https://github.com/ruddle/oxidator/blob/master/src/frame.rs"
click node_frame_server "https://github.com/ruddle/oxidator/blob/master/src/frame_server/mod.rs"
click node_client_mod "https://github.com/ruddle/oxidator/blob/master/src/client/mod.rs"
click node_play "https://github.com/ruddle/oxidator/blob/master/src/client/play.rs"
click node_heightmap_editor "https://github.com/ruddle/oxidator/blob/master/src/client/heightmap_editor.rs"
click node_unit_editor "https://github.com/ruddle/oxidator/blob/master/src/client/unit_editor.rs"
click node_input_state "https://github.com/ruddle/oxidator/blob/master/src/client/input_state.rs"
click node_camera "https://github.com/ruddle/oxidator/blob/master/src/client/camera.rs"
click node_game_state "https://github.com/ruddle/oxidator/blob/master/src/client/game_state.rs"
click node_uitool "https://github.com/ruddle/oxidator/blob/master/src/client/uitool.rs"
click node_render "https://github.com/ruddle/oxidator/blob/master/src/client/render.rs"
click node_gpu_mod "https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/mod.rs"
click node_heightmap_gpu "https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/heightmap_gpu.rs"
click node_model_gpu "https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/model_gpu.rs"
click node_post_fx "https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/post_fx.rs"
click node_imgui_wgpu "https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/imgui_wgpu.rs"
click node_unit_icon "https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/unit_icon.rs"
click node_health_bar "https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/health_bar.rs"
click node_water "https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/water.rs"
click node_line "https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/line.rs"
click node_unit "https://github.com/ruddle/oxidator/blob/master/src/unit.rs"
click node_mobile "https://github.com/ruddle/oxidator/blob/master/src/mobile.rs"
click node_manager "https://github.com/ruddle/oxidator/blob/master/src/manager.rs"
click node_heightmap_phy "https://github.com/ruddle/oxidator/blob/master/src/heightmap_phy.rs"
click node_model "https://github.com/ruddle/oxidator/blob/master/src/model.rs"
click node_botdef "https://github.com/ruddle/oxidator/blob/master/src/botdef.rs"
click node_moddef "https://github.com/ruddle/oxidator/blob/master/src/moddef.rs"
click node_net_client "https://github.com/ruddle/oxidator/blob/master/src/net_client.rs"
click node_net_server "https://github.com/ruddle/oxidator/blob/master/src/net_server.rs"

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_main,node_frame,node_frame_server toneBlue
class node_client_mod,node_play,node_heightmap_editor,node_unit_editor,node_input_state,node_camera,node_game_state,node_uitool toneAmber
class node_unit,node_mobile,node_manager,node_heightmap_phy,node_model toneMint
class node_render,node_gpu_mod,node_heightmap_gpu,node_model_gpu,node_post_fx,node_imgui_wgpu,node_unit_icon,node_health_bar,node_water,node_line toneRose
class node_botdef,node_moddef toneIndigo
class node_net_client,node_net_server toneTeal
```

## Components

### Runtime

Top-level executable and frame scheduling

- [Main](https://github.com/ruddle/oxidator/blob/master/src/main.rs): entrypoint · Application entrypoint and mode bootstrap · `src/main.rs`
- [Frame](https://github.com/ruddle/oxidator/blob/master/src/frame.rs): tick runtime · Frame-ticked coordination layer · `src/frame.rs`
- [Frame server](https://github.com/ruddle/oxidator/blob/master/src/frame_server/mod.rs): server loop · Server-side frame coordination · `src/frame_server/mod.rs`

### Client

Mode selection, input, camera, and UI

- [Client core](https://github.com/ruddle/oxidator/blob/master/src/client/mod.rs): app shell · Top-level client module and mode dispatch · `src/client/mod.rs`
- [Play mode](https://github.com/ruddle/oxidator/blob/master/src/client/play.rs): game mode · In-game RTS interaction flow · `src/client/play.rs`
- [Terrain editor](https://github.com/ruddle/oxidator/blob/master/src/client/heightmap_editor.rs): editor mode · Heightmap editing workflow · `src/client/heightmap_editor.rs`
- [Unit editor](https://github.com/ruddle/oxidator/blob/master/src/client/unit_editor.rs): editor mode · Unit definition and part editing workflow · `src/client/unit_editor.rs`
- [Input state](https://github.com/ruddle/oxidator/blob/master/src/client/input_state.rs): input boundary · Raw input handling and state capture · `src/client/input_state.rs`
- [Camera](https://github.com/ruddle/oxidator/blob/master/src/client/camera.rs): view control · World-to-view navigation and framing · `src/client/camera.rs`
- [Game state](https://github.com/ruddle/oxidator/blob/master/src/client/game_state.rs): shared state · Mode-scoped application state model · `src/client/game_state.rs`
- [UI tools](https://github.com/ruddle/oxidator/blob/master/src/client/uitool.rs): interaction helpers · Editor and HUD interaction utilities · `src/client/uitool.rs`

### Simulation

World state, units, terrain, and gameplay logic

- [Units](https://github.com/ruddle/oxidator/blob/master/src/unit.rs): simulation · Unit behavior and interaction logic · `src/unit.rs`
- [Movement](https://github.com/ruddle/oxidator/blob/master/src/mobile.rs): simulation · Mobility and movement behavior · `src/mobile.rs`
- [Manager](https://github.com/ruddle/oxidator/blob/master/src/manager.rs): simulation · World orchestration and coordination · `src/manager.rs`
- [Terrain physics](https://github.com/ruddle/oxidator/blob/master/src/heightmap_phy.rs): simulation · Terrain-aware movement and collision rules · `src/heightmap_phy.rs`
- [Model](https://github.com/ruddle/oxidator/blob/master/src/model.rs): simulation data · Core world and entity model structures · `src/model.rs`

### Rendering

Renderer and GPU object layer

- [Render](https://github.com/ruddle/oxidator/blob/master/src/client/render.rs): renderer · High-level render orchestration · `src/client/render.rs`
- [GPU layer](https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/mod.rs): gpu backend · Reusable GPU object and pipeline layer · `src/gpu_obj/mod.rs`
- [Terrain GPU](https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/heightmap_gpu.rs): gpu object · Specialized terrain rendering · `src/gpu_obj/heightmap_gpu.rs`
- [Model GPU](https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/model_gpu.rs): gpu object · 3D model rendering pipeline · `src/gpu_obj/model_gpu.rs`
- [Post FX](https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/post_fx.rs): gpu object · Fullscreen post-processing passes · `src/gpu_obj/post_fx.rs`
- [UI GPU](https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/imgui_wgpu.rs): gpu object · Immediate-mode UI rendering integration · `src/gpu_obj/imgui_wgpu.rs`
- [Unit icons](https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/unit_icon.rs): gpu object · 2D unit marker rendering · `src/gpu_obj/unit_icon.rs`
- [Health bars](https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/health_bar.rs): gpu object · Damage and status overlays · `src/gpu_obj/health_bar.rs`
- [Water](https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/water.rs): gpu object · Water surface rendering · `src/gpu_obj/water.rs`
- [Lines](https://github.com/ruddle/oxidator/blob/master/src/gpu_obj/line.rs): gpu object · Debug and overlay line rendering · `src/gpu_obj/line.rs`

### Content

Data-driven unit and mod definitions

- [Bot defs](https://github.com/ruddle/oxidator/blob/master/src/botdef.rs): content schema · Data-driven unit and building definitions · `src/botdef.rs`
- [Mod defs](https://github.com/ruddle/oxidator/blob/master/src/moddef.rs): content schema · Mod and content metadata definitions · `src/moddef.rs`

### Networking

Local client/server multiplayer path

- [Net client](https://github.com/ruddle/oxidator/blob/master/src/net_client.rs): tcp client · Local multiplayer client transport · `src/net_client.rs`
- [Net server](https://github.com/ruddle/oxidator/blob/master/src/net_server.rs): tcp server · Local multiplayer host transport · `src/net_server.rs`

## Connections

- Main → Frame: drives · Main sets up and runs the frame loop
- Main → Client core: starts · Bootstraps the runtime client shell
- Frame → Frame server: syncs · Frame timing and server-side coordination
- Client core → Play mode: selects · Runtime mode dispatch for gameplay
- Client core → Terrain editor: selects · Runtime mode dispatch for terrain editing
- Client core → Unit editor: selects · Runtime mode dispatch for unit editing
- Play mode → Game state: uses · Gameplay reads and updates shared state
- Terrain editor → Game state: uses · Terrain editor operates on shared state
- Unit editor → Game state: uses · Unit editor operates on definition state
- Input state → Play mode: feeds · OS input becomes gameplay actions
- Input state → Terrain editor: feeds · OS input becomes terrain editing actions
- Input state → Unit editor: feeds · OS input becomes unit editing actions
- Camera → Render: views · Camera state shapes the visible world
- Play mode → Render: updates · Gameplay state is rendered each frame
- Terrain editor → Render: updates · Terrain edits are previewed visually
- Unit editor → Render: updates · Unit edits are previewed visually
- Render → GPU layer: builds on · Renderer delegates to specialized GPU objects
- GPU layer → Terrain GPU: includes · Terrain rendering specialization
- GPU layer → Model GPU: includes · 3D model rendering specialization
- GPU layer → Post FX: includes · Post-processing pipeline
- GPU layer → UI GPU: includes · Immediate-mode UI rendering
- GPU layer → Unit icons: includes · Unit marker overlays
- GPU layer → Health bars: includes · Status bar overlays
- GPU layer → Water: includes · Water surface pipeline
- GPU layer → Lines: includes · Line and debug overlay pipeline
- Manager → Units: orchestrates · World manager coordinates units
- Units → Movement: uses · Unit behavior depends on movement logic
- Manager → Terrain physics: consults · Movement and interaction use terrain rules
- Manager → Model: owns · Central world/entity state model
- Bot defs → Unit editor: edited by · Unit editor manipulates definition data
- Mod defs → Unit editor: edited by · Unit editor works with mod metadata
- Net client → Manager: feeds · Remote actions enter the simulation layer
- Net server → Manager: feeds · Host-side actions enter the simulation layer
- Net client → Play mode: supports · Networking supports multiplayer gameplay
- Net server → Frame server: supports · Server transport sits alongside frame coordination
