01 // Current system
Current runtime overview
Claude of Tanks is a browser-based armored combat game built directly on Three.js. Production exposes 111 first-party procedural vehicles; a keyed local-development build exposes 148 playable models from 150 saved roster records. The game contains 16 authored battlefields, runs combat at a fixed 60 Hz, and supports local bots, persistent private and LAN rooms, and dedicated ranked authority.
Authoritative simulation
Clients request actions. The authority resolves movement, reloads, hits, damage, visibility, destruction, and match results.
Measured presentation
Three.js renders simulation state and adjusts visual cost without changing combat rate, map dimensions, ballistics, or armor.
Verified assets
Geometry fingerprints, generated diagrams, deterministic screenshots, browser checks, and release tests verify the current assets.
02 // Graphics + drivers
Three.js rendering architecture
The engine owns the Three.js renderer, color output, camera, lighting, sky, fog, post-processing, shadows, GPU timing, quality policy, warmup, and context recovery. The renderer combines output conversion and color grading, supports stable high-refresh presentation, preserves image clarity during battle loading, and anchors cascaded shadows to prevent flashing during camera movement.
| Driver responsibility | Current mechanism | Failure behavior |
|---|---|---|
| Image clarity | Device-capped pixel ratio, adaptive internal scale, subpixel AA, fused output/grade. | Optional resolution and post cost adapt before gameplay. |
| Shadows | Stable cascades, texel anchoring, bounded contrast, articulated tank shadow proxies. | Quality tiers reduce cascade cost without altering visibility rules. |
| Shader readiness | Boot and transition warmup of battle-critical material/pass variants. | Countdown waits for required visual work instead of compiling on first fire. |
| GPU safety | Capability probes, framebuffer validation, context-loss recovery, black-frame rescue ladder. | Optional shadows, environment, fog, and post can be stepped down. |
Primary implementation files: src/engine/renderer.js, post.js, lighting.js, deviceDiag.js, renderScalePolicy.js, and the shadow stability and refresh self-tests.
03 // Tank design
Shared vehicle specifications
The canonical roster reports 111 production-visible vehicles, 148 keyed local-development models, and 150 saved records, with two reference-only placeholders kept outside the playable path. Every playable remains first-party procedural with zero GLB-sourced playable geometry. A shared vehicle specification supplies data to garage cards, combat authority, bots, icons, anatomy diagrams, Tank Gallery, and Scene Studio.
specificationcanonical dataDimensions, mass, engine, movement, weapon, armor, modules, crew, labels, markings, nation, class, and tier.
procedural rigcurrent geometryHull, turret, gun, recoil group, fittings, suspension, road wheels, flexible track path, shadow proxies, and LOD.
combat anatomysimulation dataAuthored plates, internal volumes, crew stations, muzzle and articulation anchors, hit logic, and damage state.
release checksverificationCurrent hero, side, and top assets; geometry fingerprints; anatomy diagrams; focused profile tests; and release results.
Vehicle systems include class-specific IFV statistics and audio behavior, visible recoil, magazine autoloaders, missiles and special actions, Swedish siege suspension, vehicle-specific fidelity profiles, and component-level geometry reports.
04 // Combat + killcam
Projectile and damage resolution
- The center reticle requests a finite world-space point.
- Authority bounds turret yaw, gun pitch, traverse rate, and dispersion.
- The articulated muzzle transform spawns AP, APCR, APFSDS, HEAT, or HE.
- Projectile travel and gravity determine the first eligible world or vehicle contact.
- Armor evaluates the struck plate, impact angle, slope, normalization, ricochet, overmatch, spaced layers, ERA, and ammunition behavior.
- Damage updates hit points, modules, crew, fire, repair, tracks, and destruction state.
- The HUD and X-ray killcam present the completed result.
05 // Worlds + physics
Battlefield construction and physics
Verdant Fields, Sirocco Wadi, Frosthollow, Steinburg, Saltmere Bay, Amberford, Tarkhan Steppe, Cinder Junction, Frontier Basin, Nordhavn Fjord, Jade River Delta, Redrock Divide, Monsoon Ridge, Glacier Pass, Obsidian Caldera, and Ironworks share the current world systems.
Each map combines designed routes and role-specific positions with smoothed terrain, matte surface materials, atmosphere, textured structures, precise collision, modern wreck families, detached remnants, movable props, crushable objects, toppling, linked utility wires, vegetation, craters, and persistent networked destruction. The original eight maps use the same current world systems as the expansion maps.
06 // HUD + UI
Interface design across game states
The current interface includes the vehicle dossier and component workshop, map and camouflage previews, autoloader shell rack, stabilized aiming readouts, room chat, local lifetime statistics, responsive nation filters, debrief and rematch flow, settings, graphics and audio controls, and compact FPS and ping telemetry. Debug and shadow-tuning controls require dedicated URL parameters and remain hidden during normal play.
07 // Multiplayer
Multiplayer authority and session persistence
Client responsibilities
Input requests and presentation.
- Normalized movement and aim input
- Fire, ammunition, and equipment input
- Local movement prediction
- Snapshot interpolation
- HUD, audio, effects, and reports
Private and LAN rooms use browser-hosted WebRTC authority. Ranked matches use a renderer-free Node service. Rooms retain the host-selected map, player camouflage, authenticated chat, invitation metadata, rejoin state, garage presence, team and ready state, and round-to-round continuity. Separate browser tests verify four-player and 7v7 moving-and-firing matches, including synchronization, reconciliation, rubber-banding, event delivery, and rendering behavior.
08 // Performance + GPU
Performance budgets and runtime ownership
The garage does not build a battlefield until it is required. Battle entry completes required warmup before the countdown, performance-sensitive loops reuse scratch state, and repeated world and vehicle resources are cached or pooled. Effect budgets limit transient work. Public presentation pages do not start the playable renderer.
| Budget | Mechanism | Invariant |
|---|---|---|
| Simulation | Bounded fixed-step accumulator at 60 Hz. | Graphics quality cannot change combat. |
| Rendering | High-refresh frame scheduler, adaptive scale, quality tiers, fused post output. | Certified test runs reached the native 120 FPS refresh rate on measured hardware. |
| Draw/GPU | Instancing/merging, LOD cadence, shadow proxies, cached worlds, resource disposal. | Cosmetic work is reduced before simulation work. |
| Loading | Garage-first boot, lazy battle graph, shader/material warmup, staged world activation. | Required battle work finishes before countdown. |
| Network | 20 Hz viewer-filtered snapshots, deltas, keyframes, event channel, bounded prediction. | Hidden transforms never reach unauthorized viewers. |
npm run perf:dev
npm run perf:loading
npm run test:net:render
node src/engine/renderScalePolicy.selftest.mjs
node src/engine/shadowStability.selftest.mjs09 // Mobile compatibility
Mobile rendering and input
Phones and tablets receive dual-stick movement, swipe aim, pinch-to-scope, held/dynamic fire, accessible ammunition and equipment placement, safe-area-aware layout, compact settings, and automatic device tiers. Boot-time GPU probes, pixel-ratio caps, memory-conscious detail, shadow rescue, PMREM validation, and a black-scene watchdog let presentation recover without changing gameplay.
10 // Scene Studio
Scene production with the game renderer
Open /studio or press F8 in the garage. Studio places any roster vehicle on any map, conforms actors to terrain, applies camouflage and damage states, schedules the game's firing and destruction effects, scrubs a deterministic 20-second timeline, builds camera, actor, and effect tracks, records video, captures high-resolution PNGs, and imports or exports scene JSON. The Field Frames drawer provides the current 88-frame archive beside the authoring controls.
Contact-sheet review
Each campaign begins with deterministic scene data. Low-resolution captures are then reviewed in groups of ten. The contact sheets reveal weak silhouettes, obstructed cameras, unreadable vehicles, repetitive staging, and effects that hide the action. Approved frames proceed to 4K export, automated image analysis, owner approval, and publication.
Open any sheet at full resolution. The filenames are the stable scene IDs used by the capture and quality receipts.
11 // Tank Gallery
Interactive vehicle inspection
The Tank Gallery searches the current fleet registry and constructs the selected procedural vehicle. Camera presets, hull, turret, and gun articulation, armor, module, and crew overlays, normalized ratings, ammunition tables, and triangle or coplanar-patch markup all use canonical game data. Exported JSON and PNG review packets preserve pose, camera, rig path, mesh identity, bounds, centroid, triangle, and requested operation.
12 // Verification
Automated verification
npm testbehaviorSimulation, networking, UI, rendering policy, vehicles, maps, collision, destruction, assets, and tools.
tank:native:checkprovenanceReports 121 first-party procedural playables, zero GLB-sourced playables, and isolated comparison inputs.
tank:release:checkvehicle checksTargeted anatomy, geometry, generated assets, profiles, and current release results.
marketing-shotsimage reviewDeterministic scenes, six review sheets, 4K image analysis, and owner approval produce the 88-frame archive.
npm install
npx vite
npm test
npm run tank:native:check
npm run test:net:seven:live
npm run buildContinue with architecture, performance, multiplayer, Studio, Gallery, and the dated development evolution.