1  # GUNRPG - Text-Based Tactical Combat Simulator
  2  
  3  A deterministic, time-based combat simulation system inspired by Call of Duty weapon mechanics, implementing a discrete event simulation model with real-time physics and tactical decision-making.
  4  
  5  ## Overview
  6  
  7  GUNRPG is a **text-based tactical combat simulator** that features:
  8  
  9  * **Real-time simulation** with millisecond precision
 10  * **Raw weapon stats** used 1:1 (fire rate, recoil, damage falloff, etc.)
 11  * **Discrete event simulation** with priority queue event execution
 12  * **Turn-based player interaction** with continuous-time simulation
 13  * **Commitment-based reaction windows** (every N bullets fired / meters moved)
 14  * **Deterministic gameplay** with optional seed-based randomization
 15  * **Virtual pet mechanics** for operator management (planned)
 16  
 17  ## Architecture
 18  
 19  ### Core Systems
 20  
 21  The project is built on a modular architecture with clear separation of concerns:
 22  
 23  ```
 24  GUNRPG.Core/
 25  ├── Time/              # Global simulation clock
 26  ├── Events/            # Event queue and event types
 27  ├── Operators/         # Operator state and behavior
 28  ├── Weapons/           # Weapon configurations and stats
 29  ├── Intents/           # Player/AI action declarations
 30  ├── Combat/            # Combat orchestration
 31  └── AI/                # AI decision making
 32  ```
 33  
 34  ### Key Concepts
 35  
 36  #### Time Model
 37  
 38  - All time measured in **milliseconds** (`long`)
 39  - Monotonic global clock (`SimulationTime`)
 40  - Events execute at exact timestamps
 41  
 42  #### Event System
 43  
 44  - Priority queue sorted by: timestamp → operator ID → sequence number
 45  - Events are **atomic** and **irreversible**
 46  - Deterministic ordering ensures reproducibility
 47  
 48  #### Actor/Operator Model
 49  
 50  Each operator maintains:
 51  - **Movement State**: Idle, Walking, Sprinting, Sliding
 52  - **Aim State**: Hip, ADS, Transitioning
 53  - **Weapon State**: Ready, Reloading, Jammed
 54  - **Physical State**: Health, Stamina, Fatigue
 55  
 56  #### Intent System
 57  
 58  Intents are **declarative action plans** that schedule future events:
 59  - `FireWeapon` - Fire equipped weapon
 60  - `Reload` - Reload weapon magazine
 61  - `EnterADS` / `ExitADS` - Aim down sights
 62  - `Walk/Sprint/Slide` - Movement intents (toward/away)
 63  - `Stop` - Cease all actions
 64  
 65  Intents are validated before execution and can be cancelled during planning phases.
 66  
 67  #### Commitment Units & Reaction Windows
 68  
 69  Combat flows through **Planning** and **Execution** phases:
 70  
 71  1. **Planning Phase**: Both sides submit intents (time paused)
 72  2. **Execution Phase**: Events execute in order (time runs)
 73  3. **Reaction Window**: Triggered after commitment units complete
 74     - Weapons: Every N bullets fired (default: 3)
 75     - Movement: Every N meters moved (default: 2)
 76  
 77  This creates tactical decision points without traditional "turns".
 78  
 79  #### Hit Resolution
 80  
 81  - Weapon spread depends on aim state (Hip vs ADS)
 82  - Recoil accumulates and recovers over time
 83  - Distance affects both accuracy and damage
 84  - Damage falloff based on weapon-specific ranges
 85  - Headshot multipliers (10% chance)
 86  
 87  ## Weapon System
 88  
 89  Weapons use **real stats** from Call of Duty and other tactical shooters:
 90  
 91  - Fire rate (RPM) → exact time between shots
 92  - Magazine size and reload time
 93  - Base damage and headshot multipliers
 94  - Distance-based damage falloff curves
 95  - Hipfire and ADS spread angles
 96  - Vertical and horizontal recoil
 97  - ADS transition time
 98  - Sprint-to-fire delays
 99  
100  ### Included Weapons
101  
102  - **SOKOL 545**: Light machine gun (583 RPM, 32 damage, 102-round magazine)
103  - **STURMWOLF 45**: Submachine gun (667 RPM, 30 damage)
104  - **M15 MOD 0**: Assault rifle (769 RPM, 21 damage)
105  
106  ## Health & Regeneration
107  
108  Implements Call of Duty-style health regeneration:
109  - Health regenerates after delay following damage
110  - Configurable regen delay and rate
111  - Stamina regenerates when not sprinting
112  - Stamina drains during sprint/slide
113  
114  ## AI System
115  
116  Simple but effective AI decision-making:
117  - Prioritizes survival when low health
118  - Reloads tactically (when safe or out of ammo)
119  - Engages at optimal range
120  - Makes use of reaction windows
121  
122  ## Running the Demo
123  
124  ### Build
125  
126  ```bash
127  dotnet build
128  ```
129  
130  ### Run
131  
132  ```bash
133  # Start the headless Web API (http://localhost:5209 by default)
134  dotnet run --project GUNRPG.Api
135  
136  # In another terminal, launch the console client (uses the same API)
137  GUNRPG_API_BASE=http://localhost:5209 dotnet run --project GUNRPG.ConsoleClient
138  ```
139  
140  ### Test
141  
142  ```bash
143  dotnet test
144  ```
145  
146  Core tests exercise the domain and application layers; see `GUNRPG.Tests` for coverage details.
147  
148  ## Headless Architecture
149  
150  - **Domain (`GUNRPG.Core`)**: Combat engine, operators, weapons, intents, virtual pet rules (no UI or HTTP dependencies).
151  - **Application (`GUNRPG.Application`)**: `CombatSessionService`, DTOs, in-memory session store, pet care helpers. Converts domain state into transport-ready shapes.
152  - **Web API (`GUNRPG.Api`)**: Stateless controllers exposing the service. Key endpoints:
153    - `POST /sessions` – create a combat session (`SessionCreateRequest`).
154    - `GET /sessions/{id}/state` – fetch current session state (`CombatSessionDto`).
155    - `POST /sessions/{id}/intent` – submit player intents (`SubmitIntentsRequest`/`IntentDto`).
156    - `POST /sessions/{id}/advance` – resolve execution to the next reaction window or combat end.
157    - `POST /sessions/{id}/pet` – apply rest/eat/drink/mission inputs (`PetActionRequest` → `PetStateDto`).
158  - **Responsibilities**: Controllers only translate HTTP ⇄ DTOs; `CombatSessionService` owns session lifecycle and deterministic transitions; domain types stay UI-agnostic.
159  - **Console client (`GUNRPG.ConsoleClient`)**: Thin CLI that calls the API for session creation, intent submission, advancement, and pet care. Configurable via `GUNRPG_API_BASE`.
160  
161  ## Usage Example
162  
163  ```csharp
164  // Create operators
165  var player = new Operator("Player")
166  {
167      EquippedWeapon = WeaponFactory.CreateSokol545(),
168      CurrentAmmo = 102,
169      DistanceToOpponent = 15f
170  };
171  
172  var enemy = new Operator("Enemy")
173  {
174      EquippedWeapon = WeaponFactory.CreateSturmwolf45(),
175      CurrentAmmo = 32,
176      DistanceToOpponent = 15f
177  };
178  
179  // Initialize combat
180  var combat = new CombatSystem(player, enemy, seed: 42);
181  
182  // Submit intents (Planning Phase)
183  combat.SubmitIntent(player, new FireWeaponIntent(player.Id));
184  combat.SubmitIntent(enemy, new FireWeaponIntent(enemy.Id));
185  
186  // Execute (Execution Phase)
187  combat.BeginExecution();
188  bool hasReactionWindow = combat.ExecuteUntilReactionWindow();
189  
190  // Repeat until combat ends
191  ```
192  
193  ## Design Philosophy
194  
195  ### Core Principles
196  
197  1. **No derived combat stats** - Use raw weapon data directly
198  2. **Time is absolute** - Milliseconds are the single source of truth
199  3. **Deterministic simulation** - Same seed = same outcome
200  4. **Emergent gameplay** - Complex behavior from simple rules
201  5. **Player agency** - React to observable events, not hidden timers
202  
203  ### Non-Goals (v1)
204  
205  Explicitly out of scope:
206  - Multiplayer networking
207  - 3D graphics or animation
208  - Complex ballistics simulation
209  - Persistent injuries or equipment degradation
210  - Cover system (planned for later)
211  
212  ## Project Status
213  
214  **Current Status**: ✅ Foundation Complete (Draft 1)
215  
216  ### Implemented
217  
218  - [x] Core time model
219  - [x] Event queue system
220  - [x] Operator state machines
221  - [x] Weapon system with real stats
222  - [x] Intent system
223  - [x] Combat orchestration
224  - [x] Commitment units & reaction windows
225  - [x] Hit resolution with spread/recoil
226  - [x] Movement system (distance-based)
227  - [x] Health/stamina regeneration
228  - [x] Basic AI
229  - [x] Unit tests for all core systems (38 tests)
230  - [x] Interactive demo
231  - [x] Virtual pet/rest system
232  - [x] Fatigue mechanics
233  
234  ### Planned
235  
236  - [ ] Cover system
237  - [ ] Multiple opponents
238  - [ ] Campaign mode
239  - [ ] Enhanced TUI with better visualization
240  - [ ] More weapons
241  - [ ] Advanced AI behaviors
242  
243  ## Technical Details
244  
245  - **Language**: C# (.NET 10.0)
246  - **Testing**: xUnit
247  - **Platform**: Cross-platform (Windows, Linux, macOS)
248  
249  ## License
250  
251  See LICENSE file for details.
252  
253  ## Credits
254  
255  Design inspired by:
256  - Call of Duty weapon mechanics
257  - X-COM tactical gameplay
258  - Virtual pet management games
259  - Discrete event simulation theory