How ruddle/oxidator works
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: mod.rs GPU layer · unit_editor.rs Unit editor · manager.rs Manager · play.rs Play mode
Components 30
Runtime
Top-level executable and frame scheduling
- Main · Application entrypoint and mode bootstrap
src/main.rs - Frame · Frame-ticked coordination layer
src/frame.rs - Frame server · Server-side frame coordination
src/frame_server/mod.rs
Client
Mode selection, input, camera, and UI
- Client core · Top-level client module and mode dispatch
src/client/mod.rs - Play mode · In-game RTS interaction flow
src/client/play.rs - Terrain editor · Heightmap editing workflow
src/client/heightmap_editor.rs - Unit editor · Unit definition and part editing workflow
src/client/unit_editor.rs - Input state · Raw input handling and state capture
src/client/input_state.rs - Camera · World-to-view navigation and framing
src/client/camera.rs - Game state · Mode-scoped application state model
src/client/game_state.rs - UI tools · Editor and HUD interaction utilities
src/client/uitool.rs
Simulation
World state, units, terrain, and gameplay logic
- Units · Unit behavior and interaction logic
src/unit.rs - Movement · Mobility and movement behavior
src/mobile.rs - Manager · World orchestration and coordination
src/manager.rs - Terrain physics · Terrain-aware movement and collision rules
src/heightmap_phy.rs - Model · Core world and entity model structures
src/model.rs
Rendering
Renderer and GPU object layer
- Render · High-level render orchestration
src/client/render.rs - GPU layer · Reusable GPU object and pipeline layer
src/gpu_obj/mod.rs - Terrain GPU · Specialized terrain rendering
src/gpu_obj/heightmap_gpu.rs - Model GPU · 3D model rendering pipeline
src/gpu_obj/model_gpu.rs - Post FX · Fullscreen post-processing passes
src/gpu_obj/post_fx.rs - UI GPU · Immediate-mode UI rendering integration
src/gpu_obj/imgui_wgpu.rs - Unit icons · 2D unit marker rendering
src/gpu_obj/unit_icon.rs - Health bars · Damage and status overlays
src/gpu_obj/health_bar.rs - Water · Water surface rendering
src/gpu_obj/water.rs - Lines · Debug and overlay line rendering
src/gpu_obj/line.rs
Content
Data-driven unit and mod definitions
Networking
Local client/server multiplayer path
- Net client · Local multiplayer client transport
src/net_client.rs - Net server · Local multiplayer host transport
src/net_server.rs
Connections 35
- 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