# Glock Fnatic's Wargame — Design & Technical Specification (v1.1)
## 🎮 1. Game Fundamentals
* **Core Concept:**
A browser-based, turn-based tactical strategy game featuring a 64×64 tile grid with a retro Medival aesthetic.
* **Three-Phase Turn System:**
Each turn progresses through three distinct operational phases:
1. **Military / Movement:** Execute troop maneuvers, pathfinding, unit merging, and combat engagements.
2. **Construction:** Place infrastructure, defensive structures, and economic buildings on valid grid locations.
3. **Recruitment:** Train new units using acquired resources and deploy them to active grid tiles.
* **Match Setup & AI Tiers:**
Supports up to 6 players per match. Empty player slots can be configured with autonomous AI opponents across three difficulty levels:
* **Easy:** Basic positioning, passive aggression.
* **Medium:** Tactical pathfinding, balanced resource distribution.
* **Hard:** Aggressive expansion, optimal unit merging, target prioritization.
* **Free Movement & Unit Merging:**
Units move freely across available grid paths. Identical unit types occupying the same tile merge into a single, higher-tier stack.
* **Road Connection Logic:**
All constructed buildings must maintain an active road connection back to the player's Starting Castle to remain operational.
* **Linear Unit Scaling:**
* Merging units stacks base statistics linearly: `HP_total = sum(HP)`, `ATK_total = sum(ATK)`, `DEF_total = sum(DEF)`.
* Movement range scaling thresholds:
* **Level 100:** +1 Movement Range
* **Level 200:** +2 Movement Range
* **Damage Caps per Unit Type:**
* **Soldiers:** 1,000 max damage per attack.
* **Cavalry:** 1,200 max damage per attack.
* **Archers:** 900 max damage per attack.
* **Catapults:** 1,500 max damage vs units / 500 max damage vs structures.
* **Defensive Fortress Buff:**
All direct attacks targeting a player's **Starting Castle** suffer an automatic **50% damage reduction penalty**.
---
## 🌐 2. Multiplayer & Server Backend
* **Server-Side Lobbies:**
Multiplayer lobbies powered by a WebSocket/HTTP backend with shareable room codes for hosting and joining matches.
* **Real-Time Synchronization:**
Live updates reflect connected players in the lobby in real time. The host retains authoritative control to launch the match.
* **Automated AI Backfilling:**
Unfilled player slots are automatically backfilled with AI bots upon match start to ensure full 6-player matches.
---
## 🏆 3. Leaderboard & Ranking System
* **Server-Backed Leaderboard:**
Top 20 global leaderboard dynamically fetched from the server. Automatically re-loads upon client startup and re-syncs every 3 minutes.
* **Persistent Top Billing & Bot Fillers:**
Features top-tier entry *"TheRealGlock"* alongside realistic, uniquely generated bot entries to maintain continuous competition.
* **VIP Name Formatting:**
Victor's name renders with an animated rainbow color gradient for authenticated VIP players.
* **Deduplication Logic:**
Strict database deduplication based on unique `player_id` — preventing duplicate user entries on the leaderboard.
---
## 💎 4. Donations & VIP System
* **Stripe Integration:**
Direct Stripe payment link embedded within the main menu interface.
* **Post-Donation Flow:**
Dedicated confirmation page displaying a custom thank-you message upon completed transaction.
* **VIP Perks:**
Unlocks the glowing rainbow name style on the global leaderboard and explicitly displays the user's custom Player ID.
---
## ⚙️ 5. Progression & Upgrade Framework
* **In-Game Currency:**
Credits (🪙C) continuously tracked and rendered in the top-right corner of the main menu.
* **Persistent Upgrade Tree:**
Individual stat upgrades available for unit types, functional structures, and the Starting Castle:
* **Stat Scaling:** +0.2 stat gain per upgrade level (+1 HP for Starting Castle).
* **Cost Scaling:** Upgrade costs double exponentially per tier.
* **Level Cap:** Maximum upgrade level capped at Level 200.
* **Challenge Mode:**
A high-difficulty survival mode placing the player against 5 Hard AI bots programmed to target the player.
* Destroying enemy troops/structures yields Credits (🪙C).
* Victories guarantee an automatic entry onto the global leaderboard.
---
## 🔊 6. Audio & Intro Sequence
* **Procedural Web Audio Engine:**
Generates audio dynamically via Web Audio API, shifting from initial 8-bit chiptunes to a dark, menacing minor-key war-drum ambient soundtrack.
* **Intro Sequence:**
3.5-second silent opening intro displaying a shaking, intense red *"Glock Fnatic's Wargame"* title header, followed by immediate seamless transition to the main menu background music (BGM).
---
## 🌍 7. Localization & User Interface
* **Bilingual Support (DE/EN):**
Language toggle feature using clear flag icon assets (Germany & USA flags rendered at 44×44px).
* **Commander Identity:**
Dedicated, centered text input field for setting the Commander Name, decoupled from language toggles.
* **Typography & Styling:**
* **Body & UI Text:** Retro arcade font `VT323`.
* **Headers & Titles:** Pixel font `Press Start 2P`.
* **Main Menu:** Full-screen background art with a dark semi-transparent gradient overlay.
* **Watermark:** *"Studio - Lohmar Project"* anchored in the bottom-right corner.
---
## 📖 8. Onboarding & Tutorial Scenario
* **Guided Main Menu Tutorial:**
Interactive step-by-step onboarding mode explaining grid mechanics, road connections, and phase management.
* **Deterministic Scenario:**
Fixed tactical scenario with a 15-tile separation distance between opposing bases, smoothly transitioning into Free Play mode upon completion.
---
## 🧩 9. Engine Architecture & Code Standards
* **Centralized Combat Engine:**
Deterministic combat calculator ensuring identical damage calculations across single-player and multiplayer matches.
* **State Serialization:**
Full state import/export capabilities supporting game saves, loads, and real-time multiplayer delta transfers.
* **Procedural Canvas Renderer:**
HTML5 Canvas rendering pipeline handling layered terrain drawing, structural models, troop units, visual animations, and particle combat effects.