# mshumer/claude-of-duty architecture

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

- Interactive diagram: https://gitdiagram.com/mshumer/claude-of-duty
- Repository: https://github.com/mshumer/claude-of-duty

## Overview

#### Purpose and runtime

Claude of Duty is a browser-first first-person shooter built with Three.js r180 and WebGL2. It procedurally generates all gameplay content—geometry, materials, animation, and audio—at load time; `three` is the sole runtime dependency. Vite serves the app. The main entry point is `src/main.js`, with the engine lifecycle centered in `src/core/engine.js`.

#### Boot, orchestration, and shared state

`src/main.js` composes the major subsystems into a running game. Core services provide configuration, deterministic random generation, input, shared object registration, and shader warm-up:
- `src/core/engine.js`
- `src/core/input.js`
- `src/core/registry.js`
- `src/core/prewarm.js`

Prewarming is architecturally material: it compiles required WebGL programs before gameplay to avoid runtime shader-compilation hitches while preserving deterministic visual output.

#### World construction and collision boundary

The world subsystem procedurally builds the market-street level from layouts, a modular building kit, interiors, ground, props, and dressing. It produces scene geometry and physical surfaces consumed by rendering, player movement, projectiles, and AI:
- `src/world/builder.js`
- `src/world/layout.js`
- `src/world/buildings.js`
- `src/world/index.js`

Physics owns collision representation and simulation rather than relying on a physics library. Its BVH supports world queries; character movement, rigid bodies, ragdolls, and penetration are separate consumers of that spatial foundation:
- `src/physics/bvh.js`
- `src/physics/character.js`
- `src/physics/penetration.js`
- `src/physics/index.js`

#### Player, weapons, and combat flow

Input drives the player movement state machine and camera. The player controls sprinting, crouching, jumping, slide/mantle/lean, health, and camera feel:
- `src/player/index.js`
- `src/player/movement.js`
- `src/player/camera.js`

Weapons construct procedural first-person models and viewmodels, manage firing/reload state, and emit ballistic results. Ballistics then queries physics, applies travel/drop and penetration, and fans combat outcomes to targets, effects, audio, and UI:
- `src/weapons/index.js`
- `src/weapons/ballistics.js`
- `src/weapons/viewmodel.js`
- `src/weapons/defs.js`

#### AI actors

AI creates procedural skinned soldiers and squads, governs navigation, perception, targeting, animation, and death/ragdoll transitions. It is a gameplay consumer of world navigation and physics, and a producer of combat actions:
- `src/ai/index.js`
- `src/ai/agent.js`
- `src/ai/nav.js`
- `src/ai/soldier.js`

#### Visual content and render pipeline

Materials are generated on the GPU from procedural masks/noise and GLSL surface definitions, avoiding external texture assets:
- `src/materials/generator.js`
- `src/materials/library.js`
- `src/materials/shader.js`

Rendering owns the HDR frame pipeline: shadows, MRT prepass, ambient occlusion, reflections, temporal accumulation, motion blur, bloom, exposure, grading, and final composite:
- `src/render/index.js`
- `src/render/prepass.js`
- `src/render/csm.js`
- `src/render/composite.js`

Sky/environment generation provides atmospheric lighting, PMREM environment data, clouds, and volumetric effects to the world/render boundary:
- `src/sky/index.js`
- `src/sky/atmosphere.js`
- `src/sky/volumetrics.js`

Combat and environmental visuals are event-driven overlays on the scene—particles, impacts, decals, tracers, muzzle flashes, shells, and explosions:
- `src/fx/index.js`
- `src/fx/particles.js`
- `src/fx/impacts.js`
- `src/fx/explosions.js`

#### Audio, HUD, and verification infrastructure

Audio uses Web Audio synthesis, mixing, convolution/reverb, HRTF spatialization, and occlusion; weapon and world events feed it rather than file-backed assets:
- `src/audio/index.js`
- `src/audio/mixer.js`
- `src/audio/spatial.js`
- `src/audio/weapons.js`

UI is DOM/CSS HUD state driven by player and combat events:
- `src/ui/index.js`
- `src/ui/health.js`
- `src/ui/hitmarkers.js`
- `src/ui/minimap.js`

Headless Chromium tooling captures scripted frames, isolates deterministic baselines, pixel-diffs output, profiles real gameplay, and runs smoke tests:
- `tools/baseline.mjs`
- `tools/imagediff.mjs`
- `tools/profile.mjs`
- `tools/playtest.mjs`

Main entry points: [`src/weapons/ballistics.js`](https://github.com/mshumer/claude-of-duty/blob/main/src/weapons/ballistics.js) (Ballistics), [`src/render/index.js`](https://github.com/mshumer/claude-of-duty/blob/main/src/render/index.js) (HDR Renderer), [`src/world/builder.js`](https://github.com/mshumer/claude-of-duty/blob/main/src/world/builder.js) (World Builder), [`src/main.js`](https://github.com/mshumer/claude-of-duty/blob/main/src/main.js) (Application Boot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Game Runtime"]
  node_main["Application Boot<br/>entrypoint<br/>[main.js]"]
  node_engine["Engine Lifecycle<br/>orchestrator<br/>[engine.js]"]
  node_input["Input Service<br/>[input.js]"]
  node_registry["Object Registry<br/>shared-state<br/>[registry.js]"]
  node_prewarm["Shader Prewarm<br/>gpu-setup<br/>[prewarm.js]"]
  node_physics["Physics Simulation<br/>[index.js]"]
  node_bvh["Collision BVH<br/>spatial-index<br/>[bvh.js]"]
  node_player["Player Controller<br/>gameplay<br/>[index.js]"]
  node_weapons["Weapons<br/>combat<br/>[index.js]"]
  node_ballistics["Ballistics<br/>combat-simulation<br/>[ballistics.js]"]
  node_ai["AI Actors<br/>gameplay-ai<br/>[index.js]"]
end

subgraph group_content["Procedural Content"]
  node_world["World Builder<br/>procedural-world<br/>[builder.js]"]
  node_materials["Material Generator<br/>procedural-materials<br/>[generator.js]"]
  node_sky["Sky &amp; Environment<br/>[index.js]"]
end

subgraph group_presentation["Presentation"]
  node_render["HDR Renderer<br/>render-pipeline<br/>[index.js]"]
  node_fx["Combat FX<br/>visual-effects<br/>[index.js]"]
  node_audio["Spatial Audio<br/>[index.js]"]
  node_ui["HUD<br/>dom-ui<br/>[index.js]"]
end

subgraph group_verification["Verification"]
  node_baseline["Deterministic Baselines<br/>visual-test<br/>[baseline.mjs]"]
  node_imagediff["Pixel Diff<br/>visual-test<br/>[imagediff.mjs]"]
  node_profile["Gameplay Profiler<br/>performance-tool<br/>[profile.mjs]"]
  node_playtest["Smoke Playtest<br/>test-tool<br/>[playtest.mjs]"]
end

node_main -->|"boots"| node_engine
node_main -->|"initializes"| node_input
node_main -->|"initializes"| node_registry
node_engine -->|"warms up"| node_prewarm
node_engine -->|"builds"| node_world
node_world -->|"uses"| node_materials
node_world -->|"provides surfaces"| node_physics
node_physics -->|"builds queries"| node_bvh
node_input -->|"drives"| node_player
node_player -->|"character movement"| node_physics
node_player -->|"controls"| node_weapons
node_weapons -->|"fires"| node_ballistics
node_ballistics -->|"queries hits"| node_physics
node_ai -->|"uses navigation"| node_world
node_ai -->|"uses collision"| node_physics
node_ai -->|"combat actions"| node_ballistics
node_ballistics -->|"impact events"| node_fx
node_ballistics -->|"combat events"| node_audio
node_ballistics -->|"hit events"| node_ui
node_world -->|"scene geometry"| node_render
node_materials -->|"surface materials"| node_render
node_sky -->|"lighting and volumetrics"| node_render
node_player -->|"camera"| node_render
node_fx -->|"scene overlays"| node_render
node_render -.->|"programs to compile"| node_prewarm
node_baseline -->|"baseline frames"| node_imagediff
node_profile -.->|"profiles runtime"| node_main
node_playtest -.->|"drives smoke tests"| node_main

click node_main "https://github.com/mshumer/claude-of-duty/blob/main/src/main.js"
click node_engine "https://github.com/mshumer/claude-of-duty/blob/main/src/core/engine.js"
click node_input "https://github.com/mshumer/claude-of-duty/blob/main/src/core/input.js"
click node_registry "https://github.com/mshumer/claude-of-duty/blob/main/src/core/registry.js"
click node_prewarm "https://github.com/mshumer/claude-of-duty/blob/main/src/core/prewarm.js"
click node_world "https://github.com/mshumer/claude-of-duty/blob/main/src/world/builder.js"
click node_materials "https://github.com/mshumer/claude-of-duty/blob/main/src/materials/generator.js"
click node_sky "https://github.com/mshumer/claude-of-duty/blob/main/src/sky/index.js"
click node_physics "https://github.com/mshumer/claude-of-duty/blob/main/src/physics/index.js"
click node_bvh "https://github.com/mshumer/claude-of-duty/blob/main/src/physics/bvh.js"
click node_player "https://github.com/mshumer/claude-of-duty/blob/main/src/player/index.js"
click node_weapons "https://github.com/mshumer/claude-of-duty/blob/main/src/weapons/index.js"
click node_ballistics "https://github.com/mshumer/claude-of-duty/blob/main/src/weapons/ballistics.js"
click node_ai "https://github.com/mshumer/claude-of-duty/blob/main/src/ai/index.js"
click node_render "https://github.com/mshumer/claude-of-duty/blob/main/src/render/index.js"
click node_fx "https://github.com/mshumer/claude-of-duty/blob/main/src/fx/index.js"
click node_audio "https://github.com/mshumer/claude-of-duty/blob/main/src/audio/index.js"
click node_ui "https://github.com/mshumer/claude-of-duty/blob/main/src/ui/index.js"
click node_baseline "https://github.com/mshumer/claude-of-duty/blob/main/tools/baseline.mjs"
click node_imagediff "https://github.com/mshumer/claude-of-duty/blob/main/tools/imagediff.mjs"
click node_profile "https://github.com/mshumer/claude-of-duty/blob/main/tools/profile.mjs"
click node_playtest "https://github.com/mshumer/claude-of-duty/blob/main/tools/playtest.mjs"

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_engine,node_input,node_registry,node_prewarm,node_physics,node_bvh,node_player,node_weapons,node_ballistics,node_ai toneBlue
class node_world,node_materials,node_sky toneAmber
class node_render,node_fx,node_audio,node_ui toneMint
class node_baseline,node_imagediff,node_profile,node_playtest toneRose
```

## Components

### Game Runtime

Browser game boot and simulation.

- [Application Boot](https://github.com/mshumer/claude-of-duty/blob/main/src/main.js): entrypoint · Composes subsystems into the running game. · `src/main.js`
- [Engine Lifecycle](https://github.com/mshumer/claude-of-duty/blob/main/src/core/engine.js): orchestrator · Owns the frame lifecycle and subsystem updates. · `src/core/engine.js`
- [Input Service](https://github.com/mshumer/claude-of-duty/blob/main/src/core/input.js): input · `src/core/input.js`
- [Object Registry](https://github.com/mshumer/claude-of-duty/blob/main/src/core/registry.js): shared-state · Registers shared game objects. · `src/core/registry.js`
- [Shader Prewarm](https://github.com/mshumer/claude-of-duty/blob/main/src/core/prewarm.js): gpu-setup · Compiles required WebGL programs before gameplay. · `src/core/prewarm.js`
- [Physics Simulation](https://github.com/mshumer/claude-of-duty/blob/main/src/physics/index.js): physics · Owns collision simulation, character bodies, ragdolls, and penetration. · `src/physics/index.js`
- [Collision BVH](https://github.com/mshumer/claude-of-duty/blob/main/src/physics/bvh.js): spatial-index · World-query foundation for movement and ballistic hits. · `src/physics/bvh.js`
- [Player Controller](https://github.com/mshumer/claude-of-duty/blob/main/src/player/index.js): gameplay · Controls movement state, health, and camera feel. · `src/player/index.js`
- [Weapons](https://github.com/mshumer/claude-of-duty/blob/main/src/weapons/index.js): combat · Manages procedural weapons, viewmodels, firing, and reloads. · `src/weapons/index.js`
- [Ballistics](https://github.com/mshumer/claude-of-duty/blob/main/src/weapons/ballistics.js): combat-simulation · Resolves travel, drop, collision, and penetration outcomes. · `src/weapons/ballistics.js`
- [AI Actors](https://github.com/mshumer/claude-of-duty/blob/main/src/ai/index.js): gameplay-ai · Runs squads, navigation, perception, animation, and ragdoll transitions. · `src/ai/index.js`

### Procedural Content

Generated world, materials, and environment.

- [World Builder](https://github.com/mshumer/claude-of-duty/blob/main/src/world/builder.js): procedural-world · Builds the market-street scene, layouts, buildings, and physical surfaces. · `src/world/builder.js`
- [Material Generator](https://github.com/mshumer/claude-of-duty/blob/main/src/materials/generator.js): procedural-materials · Generates GPU masks, noise, and GLSL surface materials. · `src/materials/generator.js`
- [Sky & Environment](https://github.com/mshumer/claude-of-duty/blob/main/src/sky/index.js): environment · Provides atmosphere, PMREM lighting, clouds, and volumetrics. · `src/sky/index.js`

### Presentation

GPU rendering and event-driven feedback.

- [HDR Renderer](https://github.com/mshumer/claude-of-duty/blob/main/src/render/index.js): render-pipeline · Runs shadows, MRT prepass, temporal effects, post-processing, and composite. · `src/render/index.js`
- [Combat FX](https://github.com/mshumer/claude-of-duty/blob/main/src/fx/index.js): visual-effects · Renders particles, impacts, decals, tracers, and explosions. · `src/fx/index.js`
- [Spatial Audio](https://github.com/mshumer/claude-of-duty/blob/main/src/audio/index.js): audio · Synthesizes, mixes, spatializes, and occludes event-driven sound. · `src/audio/index.js`
- [HUD](https://github.com/mshumer/claude-of-duty/blob/main/src/ui/index.js): dom-ui · Displays player and combat state. · `src/ui/index.js`

### Verification

Headless Chromium validation tooling.

- [Deterministic Baselines](https://github.com/mshumer/claude-of-duty/blob/main/tools/baseline.mjs): visual-test · Captures scripted headless Chromium frames. · `tools/baseline.mjs`
- [Pixel Diff](https://github.com/mshumer/claude-of-duty/blob/main/tools/imagediff.mjs): visual-test · Compares rendered output with deterministic baselines. · `tools/imagediff.mjs`
- [Gameplay Profiler](https://github.com/mshumer/claude-of-duty/blob/main/tools/profile.mjs): performance-tool · Profiles real gameplay in Chromium. · `tools/profile.mjs`
- [Smoke Playtest](https://github.com/mshumer/claude-of-duty/blob/main/tools/playtest.mjs): test-tool · Runs scripted gameplay smoke tests. · `tools/playtest.mjs`

## Connections

- Application Boot → Engine Lifecycle: boots
- Application Boot → Input Service: initializes
- Application Boot → Object Registry: initializes
- Engine Lifecycle → Shader Prewarm: warms up
- Engine Lifecycle → World Builder: builds
- World Builder → Material Generator: uses
- World Builder → Physics Simulation: provides surfaces
- Physics Simulation → Collision BVH: builds queries
- Input Service → Player Controller: drives
- Player Controller → Physics Simulation: character movement
- Player Controller → Weapons: controls
- Weapons → Ballistics: fires
- Ballistics → Physics Simulation: queries hits
- AI Actors → World Builder: uses navigation
- AI Actors → Physics Simulation: uses collision
- AI Actors → Ballistics: combat actions
- Ballistics → Combat FX: impact events
- Ballistics → Spatial Audio: combat events
- Ballistics → HUD: hit events
- World Builder → HDR Renderer: scene geometry
- Material Generator → HDR Renderer: surface materials
- Sky & Environment → HDR Renderer: lighting and volumetrics
- Player Controller → HDR Renderer: camera
- Combat FX → HDR Renderer: scene overlays
- HDR Renderer → Shader Prewarm: programs to compile
- Deterministic Baselines → Pixel Diff: baseline frames
- Gameplay Profiler → Application Boot: profiles runtime
- Smoke Playtest → Application Boot: drives smoke tests