# Project: Tactical Shooter (CS-Clone) — Build Plan

## 1. Vision

A competitive, round-based tactical FPS (Counter-Strike-style: buy phase, bomb/objective rounds, economy) built in **Godot 4**, targeting:
- Good visual fidelity on low/mid-end hardware (Valorant-tier art direction, not AAA realism)
- 128-tick authoritative dedicated servers, community-hostable
- Official map-making tools/SDK so the community can build and distribute maps
- Server browser + map distribution pipeline (Steam-Workshop-like, but self-hosted)

## 2. Core Tech Decisions (locked)

| Area | Decision |
|---|---|
| Engine | Godot 4, Forward+ renderer |
| Server model | Authoritative dedicated server, headless Godot (`--headless`) export |
| Netcode | GDExtension (C++) simulation core from day one; ENet or GodotSteam transport (evaluate both in Phase 0) |
| Tick rate | **128 tick, firm target.** Simulation hot path built in GDExtension (C++) from day one — not GDScript — to make this realistic. See Section 3a. |
| Lighting | Baked lightmaps (LightmapGI) + reflection probes, no SDFGI/real-time GI |
| Map tooling | Built-in CSG nodes (Hammer-like blockout) + custom map template project |
| Hit detection | Server-side hitscan with lag compensation (rewind) |
| Distribution | Self-hosted CDN/GitHub releases for `.pck` map bundles, custom server browser API |

## 3a. Notes on Hitting 128 Tick

128 tick is achievable in Godot but requires committing to the harder architecture from the start, not retrofitting it later:

- **Simulation core in GDExtension (C++), not GDScript.** Movement, hit detection, and state serialization for the authoritative server should live in a compiled GDExtension module. GDScript can drive high-level game logic (round state, economy, UI) but should not be in the 128Hz hot loop.
- **Delta-compressed snapshots, not full state per tick.** At 128Hz, sending full world state every tick is a bandwidth non-starter. Serialize only changed fields per entity per tick.
- **Decouple simulation tick from network send rate.** The server can simulate at 128Hz while only sending snapshots to clients at a lower rate (e.g. 64Hz) with interpolation — this is standard practice (Source engine itself decouples these). Confirm with the team whether "128 tick" means simulation rate, network send rate, or both — this materially changes the engineering plan.
- **Benchmark in Phase 0, not Phase 1.** Stand up a synthetic load test (bots or dummy clients) hitting 128Hz simulation with realistic player counts (10v10) before building gameplay on top of it. If GDExtension can't sustain it on target hardware, that needs to be known before Phase 1 starts, not discovered mid-project.
- **Physics FPS setting**: Godot's `_physics_process` must be set to 128 (Project Settings → Physics → Common → Physics Ticks Per Second) and profiled for headroom, since this affects both simulation and physics engine cost.

## 3b. Libraries & Plugins

| Plugin/Library | Purpose | Notes | Owning Agent |
|---|---|---|---|
| **[FuncGodot](https://github.com/func-godot/func_godot_plugin)** | Import TrenchBroom `.map`/`.vmf`-style files into Godot as scenes | Successor to Qodot; gives community a Hammer/TrenchBroom-equivalent mapping workflow — evaluate as primary mapping tool over raw CSG | Mapping SDK Agent |
| **[godot-tbloader](https://github.com/codecat/godot-tbloader)** | Alternative TrenchBroom loader | Lighter-weight C++ port; benchmark against FuncGodot in Phase 0/5, pick one | Mapping SDK Agent |
| **[GodotSteam](https://godotsteam.com) (GDExtension)** | Low-level networking transport (wraps GameNetworkingSockets) | Works over plain IP, not just Steam lobbies; strong candidate to replace/augment ENet for reliability and lane prioritization | Netcode Agent |
| **GodotSteam Server (GDExtension)** | Server-side counterpart to GodotSteam | Useful if considering optional Steam-based server discovery later | Server Infra Agent |
| **[steam-multiplayer-peer](https://github.com/expressobits/steam-multiplayer-peer)** | MultiplayerPeer implementation over Steam Sockets | Only relevant if adopting Godot's high-level multiplayer API on top of Steam transport | Netcode Agent |
| ENet (built-in) | Baseline transport | Keep as Phase 0 fallback/reference implementation while evaluating GodotSteam | Netcode Agent |
| Custom GDExtension (C++) | Simulation hot path | Not a plugin — build in-house. See Section 3a. | Netcode Agent |

**Deliberately not using:**
- **GD-Sync** — relay-based hosted multiplayer service; conflicts with the self-hosted community dedicated server model.
- **godot-rollback-netcode** (Snopek Games) — built for rollback-style netcode (fighting games), not authoritative-server shooters. Wrong model for this project.

## 4. Phases & Milestones

### Phase 0 — Foundations (spike/prototype)
- Stand up empty Godot project, Forward+ renderer configured
- Headless dedicated server export pipeline working (`--headless`, build + run on Linux VPS)
- Basic client-server connection via ENet or GodotSteam transport, player join/leave, position replication
- GDExtension simulation core scaffolded; synthetic load test at 128Hz with realistic player counts (see Section 3a)
- **Exit criteria:** two clients can connect to a dedicated server and see each other move, and the 128Hz load test hits target headroom on reference hardware

### Phase 1 — Core Gameplay Loop
- First-person character controller (movement, jump, crouch, walk toggle)
- Client-side prediction + server reconciliation for movement
- Hitscan weapon (one gun), server-authoritative damage, lag compensation
- Round system: round start/end, win condition (elimination), respawn/spectate
- One grey-box test map
- **Exit criteria:** two players can shoot each other and complete a round on the dedicated server

### Phase 2 — Tactical Shooter Systems
- Buy menu + economy (money per round, win/loss bonuses)
- Bomb-defuse or objective mode (plant/defuse or equivalent)
- Weapon set (rifle, pistol, sniper, utility — smoke/flash/grenade)
- Team system, spawn zones, buy zones
- **Exit criteria:** full round loop (buy → play → win/loss → economy carries over) playable end-to-end

### Phase 3 — Visuals & Performance Pass
- Baked lighting pass on test map (LightmapGI), reflection probes
- Art pass: modular wall/floor kit, PBR materials at 1K, agreed art style guide
- Performance budget defined (target frame time on reference low-end GPU) and profiled
- LOD + occlusion culling setup
- **Exit criteria:** test map hits performance budget on reference low-end hardware while looking presentable

### Phase 4 — Dedicated Server Hardening
- RCON-style remote admin console
- Server config files (tick rate, map rotation, cvars)
- Master server / server browser API (heartbeat + query)
- Anti-cheat basics (server-authoritative validation, sanity checks on inputs)
- **Exit criteria:** community member can download server binary, configure, and have it appear in a public server browser

### Phase 5 — Mapmaking SDK
- Map template Godot project (CSG-based prefabs, spawn/buy-zone/bombsite node types documented)
- Lightmap baking + validation script (poly count, texture size, light count linting)
- Map packaging as `.pck` addon + auto-download on client connect
- Mapping documentation for community
- **Exit criteria:** a team member unfamiliar with the codebase can build and ship a working custom map using only the SDK + docs

### Phase 6 — Polish & Ecosystem
- Plugin/scripting hook API for server admins (SourceMod-style, stretch goal)
- Workshop-style map browser in-client
- Bug bash, netcode edge cases (packet loss, high ping simulation testing)
- **Exit criteria:** ready for closed community playtest

## 5. Repository Structure (proposed)

```
/client                 Godot client project
/server                 Headless server export config/scripts
/shared                 Code shared between client & server (game logic, data structs)
/maps
  /template              Base map project agents/community start from
  /test_maps
/tools
  /map-validator          Lint script for poly count, texture size, lighting
  /server-browser-api      Master server service
/docs
  /architecture.md
  /netcode.md
  /mapping-sdk.md
  /server-hosting.md
```

## 6. Workstream Ownership (for agent team assignment)

| Workstream | Scope |
|---|---|
| **Netcode Agent** | GDExtension simulation core, client prediction, server reconciliation, lag compensation, 128Hz tick loop, snapshot delta compression, transport layer (ENet/GodotSteam) |
| **Gameplay Agent** | Movement controller, weapons, round/economy logic, buy system |
| **Rendering/Art Pipeline Agent** | Forward+ renderer config, LightmapGI baked lighting setup, material/texture standards, performance profiling |
| **Server Infra Agent** | Headless export pipeline, RCON, config system, master server/server browser |
| **Mapping SDK Agent** | Map template project, CSG prefab kit, validation/lint tooling, `.pck` packaging pipeline |
| **Docs/Integration Agent** | Keeps `/docs` in sync, defines interfaces between workstreams, integration testing |

## 7. Key Risks to Flag Early

- **128 tick is the firm target — treat it as a Phase 0 gate, not a later optimization.** If the load test in Phase 0 doesn't hit target headroom, stop and resolve it before Phase 1 gameplay work begins; don't build gameplay on an unproven simulation core.
- **GDScript must stay out of the 128Hz hot loop.** All performance-critical simulation code goes in the GDExtension core from day one (see Section 3a) — this is not optional at this tick rate.
- **Clarify what "128 tick" covers** with the team up front: simulation rate, network send rate, or both. This changes the bandwidth budget and delta-compression design significantly.
- **Scope**: a full CS clone (weapon balance, anti-cheat, matchmaking, many maps) is large. Phases above are ordered so there's a playable end-to-end loop as early as Phase 2 — resist adding features before that loop is solid.
- **Lag compensation correctness** is the single most likely source of "feels bad" gameplay bugs — budget real testing time here, not just implementation time.

## 8. Definition of Done for Each Phase

Each phase is done when its exit criteria (above) is met, testable by two or more clients connecting to an actual dedicated server build (not just in-editor play mode), with no P0/P1 bugs open in that phase's scope.
