Imported from Kevin-Liu-01/CoTFly (src/sim/SKILL.md). Install upstream with npx skills add Kevin-Liu-01/CoTFly --skill sim. Copyright stays with the author.

claude-of-tanks / src/sim

Purpose

Own authoritative armored-combat math at a fixed 60 Hz step.

Mental model & key files

movement.ts owns tank state and terrain contact through named fixed-step phases for debuffs, drivetrain, gun lay, collision, attitude, support sampling, and ride contact; armor.ts owns hit geometry; ballistics.ts owns typed shells, gravity, guidance, penetration falloff, gun lay, and dispersion; damage.ts owns penetration/modules/crew/fire; spotting.ts owns strict renderer-free visibility and team-intel contracts; authoritativeMatch.ts composes those rules with match-local world collision for every network authority; specialActionPolicy.ts and specialActions.ts own the strict shared state machine for guided missiles, suspension aim, and manual magazine reloads; terrainMobility.ts owns the allocation-free drivetrain/grip capability math shared by movement and bot navigation; botRoutePlanner.ts builds one typed seeded traversability grid per match and feeds renderer-free openings into the game AI controller.

Patterns to follow / invariants

Use meters/seconds/radians, injected seeded RNG, and reusable scratch math. Never trust client hit/damage data. Visual track/hull geometry and combat hitboxes must derive from the same authored profile where specified. Movement's module-scoped scratch records make each module instance allocation-free but non-reentrant: advance tanks sequentially inside a fixed-step owner.

Common tasks → first action

Read the matching selftest and architecture contract, add a failing invariant, then edit. Run movement, combat, and spotting tests after shared-state changes.

Gotchas

Render attitude has locked sign/order conventions. Do not introduce wall-clock time, frame-rate-dependent integration, or Three.js renderer dependencies. Run node src/sim/authoritativeMatch.selftest.mjs after changing match composition, snapshot visibility, or multiplayer identity seams. Bot route changes must also pass node server/authoritativeBots.selftest.mjs on all maps.