From 48099e9de7bb4510742f1fa6add64af4577357ca Mon Sep 17 00:00:00 2001 From: Michal Vrba Date: Mon, 9 Feb 2026 13:59:15 +0100 Subject: [PATCH] Add project docs, .gitignore, and solution items Added README, design spec, roadmap, and contributing guide for PokerRogue. Updated .gitignore with Visual Studio template. Introduced .slnx solution file to organize documentation under Solution Items. --- .gitignore | 363 ++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 88 +++++++++ PokerRogue_Specification.md | 239 ++++++++++++++++++++++++ README.md | 80 ++++++++ ROADMAP.md | 85 +++++++++ src/PokerRogue.slnx | 8 + 6 files changed, 863 insertions(+) create mode 100644 .gitignore create mode 100644 CONTRIBUTING.md create mode 100644 PokerRogue_Specification.md create mode 100644 README.md create mode 100644 ROADMAP.md create mode 100644 src/PokerRogue.slnx diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9491a2f --- /dev/null +++ b/.gitignore @@ -0,0 +1,363 @@ +## Ignore Visual Studio temporary files, build results, and +## files generated by popular Visual Studio add-ons. +## +## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore + +# User-specific files +*.rsuser +*.suo +*.user +*.userosscache +*.sln.docstates + +# User-specific files (MonoDevelop/Xamarin Studio) +*.userprefs + +# Mono auto generated files +mono_crash.* + +# Build results +[Dd]ebug/ +[Dd]ebugPublic/ +[Rr]elease/ +[Rr]eleases/ +x64/ +x86/ +[Ww][Ii][Nn]32/ +[Aa][Rr][Mm]/ +[Aa][Rr][Mm]64/ +bld/ +[Bb]in/ +[Oo]bj/ +[Oo]ut/ +[Ll]og/ +[Ll]ogs/ + +# Visual Studio 2015/2017 cache/options directory +.vs/ +# Uncomment if you have tasks that create the project's static files in wwwroot +#wwwroot/ + +# Visual Studio 2017 auto generated files +Generated\ Files/ + +# MSTest test Results +[Tt]est[Rr]esult*/ +[Bb]uild[Ll]og.* + +# NUnit +*.VisualState.xml +TestResult.xml +nunit-*.xml + +# Build Results of an ATL Project +[Dd]ebugPS/ +[Rr]eleasePS/ +dlldata.c + +# Benchmark Results +BenchmarkDotNet.Artifacts/ + +# .NET Core +project.lock.json +project.fragment.lock.json +artifacts/ + +# ASP.NET Scaffolding +ScaffoldingReadMe.txt + +# StyleCop +StyleCopReport.xml + +# Files built by Visual Studio +*_i.c +*_p.c +*_h.h +*.ilk +*.meta +*.obj +*.iobj +*.pch +*.pdb +*.ipdb +*.pgc +*.pgd +*.rsp +*.sbr +*.tlb +*.tli +*.tlh +*.tmp +*.tmp_proj +*_wpftmp.csproj +*.log +*.vspscc +*.vssscc +.builds +*.pidb +*.svclog +*.scc + +# Chutzpah Test files +_Chutzpah* + +# Visual C++ cache files +ipch/ +*.aps +*.ncb +*.opendb +*.opensdf +*.sdf +*.cachefile +*.VC.db +*.VC.VC.opendb + +# Visual Studio profiler +*.psess +*.vsp +*.vspx +*.sap + +# Visual Studio Trace Files +*.e2e + +# TFS 2012 Local Workspace +$tf/ + +# Guidance Automation Toolkit +*.gpState + +# ReSharper is a .NET coding add-in +_ReSharper*/ +*.[Rr]e[Ss]harper +*.DotSettings.user + +# TeamCity is a build add-in +_TeamCity* + +# DotCover is a Code Coverage Tool +*.dotCover + +# AxoCover is a Code Coverage Tool +.axoCover/* +!.axoCover/settings.json + +# Coverlet is a free, cross platform Code Coverage Tool +coverage*.json +coverage*.xml +coverage*.info + +# Visual Studio code coverage results +*.coverage +*.coveragexml + +# NCrunch +_NCrunch_* +.*crunch*.local.xml +nCrunchTemp_* + +# MightyMoose +*.mm.* +AutoTest.Net/ + +# Web workbench (sass) +.sass-cache/ + +# Installshield output folder +[Ee]xpress/ + +# DocProject is a documentation generator add-in +DocProject/buildhelp/ +DocProject/Help/*.HxT +DocProject/Help/*.HxC +DocProject/Help/*.hhc +DocProject/Help/*.hhk +DocProject/Help/*.hhp +DocProject/Help/Html2 +DocProject/Help/html + +# Click-Once directory +publish/ + +# Publish Web Output +*.[Pp]ublish.xml +*.azurePubxml +# Note: Comment the next line if you want to checkin your web deploy settings, +# but database connection strings (with potential passwords) will be unencrypted +*.pubxml +*.publishproj + +# Microsoft Azure Web App publish settings. Comment the next line if you want to +# checkin your Azure Web App publish settings, but sensitive information contained +# in these scripts will be unencrypted +PublishScripts/ + +# NuGet Packages +*.nupkg +# NuGet Symbol Packages +*.snupkg +# The packages folder can be ignored because of Package Restore +**/[Pp]ackages/* +# except build/, which is used as an MSBuild target. +!**/[Pp]ackages/build/ +# Uncomment if necessary however generally it will be regenerated when needed +#!**/[Pp]ackages/repositories.config +# NuGet v3's project.json files produces more ignorable files +*.nuget.props +*.nuget.targets + +# Microsoft Azure Build Output +csx/ +*.build.csdef + +# Microsoft Azure Emulator +ecf/ +rcf/ + +# Windows Store app package directories and files +AppPackages/ +BundleArtifacts/ +Package.StoreAssociation.xml +_pkginfo.txt +*.appx +*.appxbundle +*.appxupload + +# Visual Studio cache files +# files ending in .cache can be ignored +*.[Cc]ache +# but keep track of directories ending in .cache +!?*.[Cc]ache/ + +# Others +ClientBin/ +~$* +*~ +*.dbmdl +*.dbproj.schemaview +*.jfm +*.pfx +*.publishsettings +orleans.codegen.cs + +# Including strong name files can present a security risk +# (https://github.com/github/gitignore/pull/2483#issue-259490424) +#*.snk + +# Since there are multiple workflows, uncomment next line to ignore bower_components +# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622) +#bower_components/ + +# RIA/Silverlight projects +Generated_Code/ + +# Backup & report files from converting an old project file +# to a newer Visual Studio version. Backup files are not needed, +# because we have git ;-) +_UpgradeReport_Files/ +Backup*/ +UpgradeLog*.XML +UpgradeLog*.htm +ServiceFabricBackup/ +*.rptproj.bak + +# SQL Server files +*.mdf +*.ldf +*.ndf + +# Business Intelligence projects +*.rdl.data +*.bim.layout +*.bim_*.settings +*.rptproj.rsuser +*- [Bb]ackup.rdl +*- [Bb]ackup ([0-9]).rdl +*- [Bb]ackup ([0-9][0-9]).rdl + +# Microsoft Fakes +FakesAssemblies/ + +# GhostDoc plugin setting file +*.GhostDoc.xml + +# Node.js Tools for Visual Studio +.ntvs_analysis.dat +node_modules/ + +# Visual Studio 6 build log +*.plg + +# Visual Studio 6 workspace options file +*.opt + +# Visual Studio 6 auto-generated workspace file (contains which files were open etc.) +*.vbw + +# Visual Studio LightSwitch build output +**/*.HTMLClient/GeneratedArtifacts +**/*.DesktopClient/GeneratedArtifacts +**/*.DesktopClient/ModelManifest.xml +**/*.Server/GeneratedArtifacts +**/*.Server/ModelManifest.xml +_Pvt_Extensions + +# Paket dependency manager +.paket/paket.exe +paket-files/ + +# FAKE - F# Make +.fake/ + +# CodeRush personal settings +.cr/personal + +# Python Tools for Visual Studio (PTVS) +__pycache__/ +*.pyc + +# Cake - Uncomment if you are using it +# tools/** +# !tools/packages.config + +# Tabs Studio +*.tss + +# Telerik's JustMock configuration file +*.jmconfig + +# BizTalk build output +*.btp.cs +*.btm.cs +*.odx.cs +*.xsd.cs + +# OpenCover UI analysis results +OpenCover/ + +# Azure Stream Analytics local run output +ASALocalRun/ + +# MSBuild Binary and Structured Log +*.binlog + +# NVidia Nsight GPU debugger configuration file +*.nvuser + +# MFractors (Xamarin productivity tool) working folder +.mfractor/ + +# Local History for Visual Studio +.localhistory/ + +# BeatPulse healthcheck temp database +healthchecksdb + +# Backup folder for Package Reference Convert tool in Visual Studio 2017 +MigrationBackup/ + +# Ionide (cross platform F# VS Code tools) working folder +.ionide/ + +# Fody - auto-generated XML schema +FodyWeavers.xsd \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e1ff4ef --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,88 @@ +# Contributing to PokerRogue + +Thanks for your interest in contributing to **PokerRogue**! +This project is in early development, so flexibility and communication are key. + +--- + +## 🧭 Philosophy +PokerRogue values: +- Clean, readable code +- Deterministic game logic +- Fast iteration +- Fun > realism + +Avoid overengineering and solver-heavy logic. + +--- + +## 🛠️ Tech Requirements +- .NET SDK 10 +- MonoGame 3.8+ +- Windows (primary dev platform) + +Optional: +- Rider or Visual Studio +- Git + +--- + +## 📁 Code Structure Guidelines +### PokerRogue.Core +- No rendering code +- No MonoGame dependencies (unless unavoidable) +- Deterministic logic preferred +- Unit-testable systems + +### PokerRogue.Game +- Rendering +- Input +- UI +- Screen/state management + +--- + +## 🧪 Testing +- Core logic should be unit-testable +- Focus on: + - Damage calculations + - Status stacking + - Skill interactions + +--- + +## 🧾 Coding Style +- C# conventions +- Explicit over clever +- Small, composable systems +- Prefer data-driven design + +--- + +## 🔀 Git Workflow +- Feature branches preferred +- Small, focused commits +- Descriptive commit messages + +Example: +``` +feat: add bleed status effect +fix: shield calculation overflow +``` + +--- + +## 🧠 Design Contributions +If proposing gameplay changes: +- Explain the problem +- Explain why it improves player decision-making +- Avoid pure randomness buffs + +--- + +## 📬 Communication +Open an issue or discussion before large changes. + +--- + +Happy hacking 🃏 diff --git a/PokerRogue_Specification.md b/PokerRogue_Specification.md new file mode 100644 index 0000000..a1ea33c --- /dev/null +++ b/PokerRogue_Specification.md @@ -0,0 +1,239 @@ +# 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.** diff --git a/README.md b/README.md new file mode 100644 index 0000000..55fdf41 --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +# PokerRogue + +**PokerRogue** is a single-player **arcade poker roguelike RPG** where combat is resolved through a fast, simplified Texas Hold’em system. + +Poker is not a minigame — **poker *is* the combat system**. + +--- + +## 🎮 High Concept +- **Genre:** Roguelike / RPG / Arcade Strategy +- **Core Mechanic:** Texas Hold’em reimagined as combat +- **Platform:** PC (Desktop) +- **Engine:** MonoGame (DesktopGL) +- **Runtime:** .NET 10 + +You fight enemies by raising, guarding, folding, and using skills that bend probability. +Builds, relics, and enemies radically change how poker is played. + +--- + +## 🧠 Core Pillars +- **Fast arcade hands** (20–40 seconds) +- **Clear risk vs reward** (Pot = Damage) +- **Build-driven gameplay** +- **Readable enemies, not solver AI** +- **High replayability** + +--- + +## 🕹️ Gameplay Loop +1. Start a run +2. Navigate a procedural map +3. Fight enemies via poker combat +4. Gain skills, relics, upgrades +5. Defeat a boss +6. Die → unlock meta progression +7. Repeat + +Average run: **25–35 minutes** + +--- + +## 🧩 Project Structure +``` +PokerRogue.sln + ├─ PokerRogue.Game (MonoGame DesktopGL) + ├─ PokerRogue.Core (Game logic, engine-agnostic) + └─ PokerRogue.Tests (optional) +``` + +--- + +## 🛠️ Tech Stack +- C# +- .NET 10 +- MonoGame 3.8+ +- MGCB Content Pipeline +- Custom SpriteBatch UI + +--- + +## 🚀 Project Status +**Early development / pre-alpha** + +Currently focusing on: +- Core combat prototype +- Arcade poker rules +- UI & game feel + +--- + +## 📄 Documentation +- `PokerRogue_Specification.md` – full design & technical spec +- `ROADMAP.md` – planned milestones +- `CONTRIBUTING.md` – contribution guidelines + +--- + +## 📜 License +TBD (likely MIT or custom indie license) diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..59fb1f7 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,85 @@ +# PokerRogue Roadmap + +This roadmap outlines the planned development phases for PokerRogue. +Dates are intentionally flexible. + +--- + +## 🧪 Phase 1 – Core Combat Prototype +**Goal:** A single playable poker fight + +- [ ] Poker hand state machine +- [ ] STRIKE / GUARD / DODGE actions +- [ ] Pot & Edge system +- [ ] Basic enemy AI (1 archetype) +- [ ] Minimal fight UI + +Deliverable: *One enemy, one fight, fully playable* + +--- + +## 🗺️ Phase 2 – Run Skeleton +**Goal:** A full run from start to boss + +- [ ] Procedural map (10–15 nodes) +- [ ] Fight / Event / Shop nodes +- [ ] Rewards (skills & relics) +- [ ] 3 enemy archetypes +- [ ] 1 boss with rule modifier + +Deliverable: *Complete run loop* + +--- + +## 🧠 Phase 3 – Builds & Depth +**Goal:** Meaningful player builds + +- [ ] 20+ skills +- [ ] 20+ relics +- [ ] Status effects system +- [ ] Build synergies +- [ ] Balance pass + +Deliverable: *Distinct playstyles* + +--- + +## 👑 Phase 4 – Meta Progression +**Goal:** Long-term replayability + +- [ ] Meta currency +- [ ] Unlockable content pools +- [ ] Save / Load +- [ ] Starting loadouts + +Deliverable: *Persistent progression* + +--- + +## ✨ Phase 5 – Polish & Content +**Goal:** Production-ready feel + +- [ ] UI polish & animations +- [ ] Sound & juice +- [ ] More enemies & bosses +- [ ] Accessibility & settings + +Deliverable: *Public demo / early access* + +--- + +## 🚧 Out of Scope (for now) +- Multiplayer +- Real-money poker simulation +- Solver-level AI + +--- + +## 🏁 Vision +PokerRogue should feel: +- Fast +- Tactical +- Dangerous +- Addictive + +**Poker as combat. Risk as power.** diff --git a/src/PokerRogue.slnx b/src/PokerRogue.slnx new file mode 100644 index 0000000..de8701b --- /dev/null +++ b/src/PokerRogue.slnx @@ -0,0 +1,8 @@ + + + + + + + +