PokerRogue/PokerRogue_Specification.md

# PokerRogue – Arcade Poker Roguelike RPG  
**Technical & Game Design Specification**

## 1. High Concept
PokerRogue is a **single‑player arcade roguelike RPG** where all combat is resolved through a **fast, simplified Texas Hold’em system**.  
Poker decisions are reimagined as **combat actions** (attack, block, dodge), enhanced by **skills, relics, and RPG progression**.

Core fantasy: *You don’t just play poker — you fight with it.*

Target platform: **PC (Desktop)**  
Engine: **MonoGame (DesktopGL)**  
Runtime: **.NET 10**

---

## 2. Design Pillars
1. **Arcade Speed** – short hands (20–40s), minimal betting loops  
2. **Readable Decisions** – clear risk/reward previews (Pot & Damage)  
3. **Build Identity** – skills + relics define playstyle  
4. **Controlled RNG** – randomness is bendable, not dominant  
5. **“One More Node” Loop** – roguelike pacing and rewards  

---

## 3. Core Game Loop
1. Start a **Run**
2. Navigate a **procedural map** (fight / event / shop / elite / boss)
3. Resolve **Poker Combat Fights**
4. Gain **rewards** (skills, relics, upgrades)
5. Defeat the **Boss**
6. Die → earn **Meta Currency** → unlock content
7. Start next run

Average run length: **25–35 minutes**

---

## 4. Poker Combat System (Arcade Version)

### 4.1 Hand Structure
Each fight consists of **3–7 Hands**.  
Each Hand has 3 phases:

1. **Deal**
   - Player hole cards
   - Flop revealed immediately
2. **Clash**
   - Player chooses an action
   - Enemy chooses an intent
3. **Resolve**
   - Turn/River reveal
   - Damage, status effects, cleanup

---

### 4.2 Player Actions
| Action | Poker Meaning | Combat Meaning |
|------|--------------|----------------|
| STRIKE | Raise | Increase Pot, aggressive attack |
| GUARD | Call / Check | Gain Shield, reduce damage |
| DODGE | Fold | Avoid heavy damage, lose tempo |
| SKILL | Cheat / Ability | Special effect (limited) |

---

### 4.3 Core Combat Values
- **HP** – player/enemy health
- **Pot** – base damage value
- **Edge (0–100)** – advantage meter (hand strength + synergies)
- **Focus** – control resource (defensive/utility)
- **Grit** – aggression resource (risk/reward)

#### Damage Formula
- **If Player Wins**
```
EnemyHP -= Pot * (1 + Edge / 100)
```

- **If Player Loses**
```
PlayerHP -= Pot * (1 + EnemyEdge / 100) - Shield
```

---

## 5. Skills System
Skills behave like **ability cards** with costs and cooldowns.

### Skill Costs
- Focus (precision, control)
- Grit (risk, aggression)

### Examples
- **Reroll** – replace one hole card
- **Power Raise** – +50% Pot, increased self-risk
- **Clean Fold** – dodge without tempo penalty
- **Time Stop** – delay resolve, take extra action
- **All‑In Slam** – massive Pot multiplier (once per fight)

Limit: **1 skill per hand** (unless modified)

---

## 6. Status Effects
Status effects last **1–3 hands**.

Examples:
- Pressure – boosts next STRIKE
- Shield – reduces incoming damage
- Bleed – damage over time
- Stun – enemy can’t STRIKE
- Lucky – free reroll
- Cursed – penalties until removed

---

## 7. Enemies
Enemies use **intent‑based AI**, not solver logic.

Each enemy has:
- Aggression (STRIKE chance)
- Trickery (skill usage)
- Cowardice (DODGE chance)

### Archetypes
- Goblin Maniac – high aggression
- Vampire Caller – sustain & bleed
- Witch – card manipulation
- Knight Nit – defensive, low risk

---

## 8. Boss Design
Bosses modify core rules.

Examples:
- **The Tax Collector** – blinds increase every hand
- **The Oracle** – knows future cards
- **The Mirror Dealer** – copies player skills

---

## 9. Roguelike Progression

### Map Nodes
- Fight
- Event
- Shop
- Elite
- Boss

### Rewards
- Skills
- Relics (passive modifiers)
- Upgrades
- Healing / Currency

---

## 10. Meta Progression
Between runs, players unlock:
- New skills
- New relics
- New enemies
- New starting loadouts

---

## 11. UI Layout – Fight Screen
**Top**
- Player HP, Focus, Grit
- Enemy HP, archetype, intent
- Hand counter & tempo

**Center**
- Board cards
- Edge meter
- Pot & damage preview

**Bottom**
- STRIKE / GUARD / DODGE buttons
- Skill bar (hotkeys)
- Status icons

Design goal: **one‑screen readability, no menus during combat**

---

## 12. Technical Architecture

### Solution Structure
```
PokerRogue.sln
 ├─ PokerRogue.Game   (MonoGame DesktopGL)
 ├─ PokerRogue.Core   (Game logic, no rendering)
 └─ PokerRogue.Tests  (optional)
```

### PokerRogue.Core
- Combat state machine
- Card & deck logic
- Enemy AI
- Run & reward generation
- Save/meta systems

### PokerRogue.Game
- Screens (Fight, Map, Shop)
- Input handling
- Rendering & animations
- Audio & effects

---

## 13. Technology Stack
- **Language:** C#
- **Runtime:** .NET 10
- **Engine:** MonoGame 3.8+ (DesktopGL)
- **UI:** SpriteBatch‑based custom UI
- **Content Pipeline:** MGCB (local dotnet tool)

---

## 14. Development Milestones
1. **Playable Fight Prototype**
2. **Basic Run & Map**
3. **Skills, Relics, Build Variety**
4. **Bosses & Meta Progression**
5. **Polish & Balance**

---

## 15. Design Goal Summary
PokerRogue aims to feel:
- Strategic, not random
- Fast, not slow or solver‑heavy
- Skill‑expressive
- Highly replayable

**Poker as combat. Risk as power. Builds as identity.**