From d908e2bc3f8f3dca471b6491e11fdd08116865da Mon Sep 17 00:00:00 2001
From: Joseph Ferano <joseph@ferano.io>
Date: Tue, 24 Jun 2025 12:23:50 +0700
Subject: [PATCH] README

---
 README.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 152 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..38d34a5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,152 @@
+# DegenzGame
+
+A multiplayer Discord gaming platform built with F# and the Giraffe web framework, featuring interactive games with player progression and an in-game economy.
+
+## Architecture
+
+### Core Technologies
+
+- **F# (.NET 6.0)**: Primary programming language for all game logic and bot functionality
+- **Giraffe**: F# web framework used for the Currency API microservice
+- **DSharpPlus**: Discord API library for bot interactions and slash commands
+- **PostgreSQL**: Database with Npgsql.FSharp for type-safe operations
+- **Docker**: Containerized deployment
+
+### Project Structure
+
+The solution consists of two main projects:
+
+- **Bot** (`Bot.fsproj`): Main Discord bot application containing all game implementations
+- **CurrencyAPI** (`CurrencyAPI.fsproj`): HTTP API microservice for currency balance management
+
+## Game System
+
+### Available Games
+
+#### HackerBattle
+Cyberpunk-themed combat game where players:
+- Use hack items (VIRUS, REMOTE, WORM) to attack other players and steal GBT currency
+- Deploy shields (FIREWALL, ENCRYPTION, CYPHER) for defense
+- Items have cooldown periods and class-based effectiveness
+- Combat resolution based on item power vs resistance stats
+- Includes comprehensive validation (can't attack yourself, cooldown checks, etc.)
+
+#### SlotMachine
+Casino-style slot machine featuring:
+- Custom symbols: BigBrother, Eye, Obey, AnonMask, Rat, Ramen, Sushi, Pizza
+- Configurable reel probabilities per symbol
+- Prize table with money rewards and jackpot system
+- Integration with GBT currency system
+
+#### Thief Game
+Player-vs-player stealing mechanics:
+- 1-minute cooldown for thieves, 1-hour recovery for victims
+- Success chance calculation based on player stats
+- Payout formula: `defenderBank * 0.1 * (1.0 - chance)` with random bonus
+- Two outcomes: Success (steal GBT) or WentToPrison (imprisoned status)
+
+#### Rock Paper Scissors
+Classic game with Discord UI integration and animated GIF results
+
+#### Store System
+In-game marketplace with:
+- Fixed-price item purchasing with GBT currency
+- Stock management (limited/unlimited items)
+- Role-based access control and invite requirements
+- Timed sales with Unix timestamp endpoints
+- Stack limits for certain items
+
+#### Trainer System
+Tutorial/onboarding system:
+- Grants "Trainee" role to new players
+- Multi-step tutorial teaching shield and hack mechanics
+- Provides starting items (REMOTE hack, FIREWALL shield)
+- Simulated combat against "Sensei" bot
+
+### Player Progression
+
+#### Stats System (`GameTypes.fs:41-55`)
+Four core attributes with time-based decay:
+- **Strength**: Combat effectiveness
+- **Focus**: Precision and accuracy
+- **Charisma**: Social interactions
+- **Luck**: Random event outcomes
+
+Each stat features:
+- Base range 0-100 with item-based modifications
+- Decay rate of 2.09 (100 to 0 in ~48 hours)
+- Item effects: Min/Max bounds, Add bonuses, RateMultiplier
+
+## Discord Integration
+
+### Multi-Bot Architecture (`Bot.fs:53-59`)
+The system uses multiple specialized Discord bot clients:
+- **hackerBattleBot**: HackerBattle game interactions
+- **storeBot**: Store transactions and interactions
+- **inviterBot**: Member recruitment and invite tracking
+- **slotsBot**: Slot machine operations
+- **adminBot**: Administrative functions
+
+### Event Handling
+- Component interactions (buttons, dropdowns)
+- Slash command registration per guild
+- Message creation events
+- Guild member join/update tracking
+- Real-time game state management
+
+## Database Design
+
+### PostgreSQL Integration (`DbService.fs`)
+Type-safe database operations using Npgsql.FSharp:
+
+- **User table**: Discord IDs, display names, GBT balances, wallet addresses
+- **Item system**: Database-driven item definitions with custom composite types
+- **Event tracking**: Player actions, cooldowns, game history with proper typing
+- **Custom types**: `StatMod` composite type for database item modifiers
+
+## Currency API (Giraffe)
+
+### Endpoints (`Currency.fs`)
+- **GET `/user/{id}/balance`**: Retrieve player's GBT balance
+- **PATCH `/user/{id}/balance/withdraw`**: Deduct GBT (with insufficient funds validation)
+- **PATCH `/user/{id}/balance/deposit`**: Add GBT to player account
+- **API Key Authentication**: `X-API-Key` header validation
+- **Error Handling**: Comprehensive error responses and logging
+
+## Player Economy
+
+The game features a balanced virtual economy:
+- **GBT Currency**: Primary medium of exchange earned through gameplay
+- **Fixed Pricing**: Items have set buy/sell prices (no dynamic market)
+- **Cooldown Systems**: Rate limiting prevents exploitation
+- **Risk/Reward Balance**: Thief game risk vs potential reward
+- **Player Progression**: Long-term engagement through stat decay requiring active play
+
+## Development Setup
+
+### Prerequisites
+- .NET 6.0 SDK
+- PostgreSQL database
+- Discord application with multiple bot tokens
+- Paket for F# package management
+
+### Configuration
+Environment variables required:
+- `DATABASE_URL`: PostgreSQL connection string
+- `API_KEY`: Currency API authentication key
+- Multiple Discord bot tokens for specialized bots
+
+### Running the Application
+```bash
+# Restore packages
+dotnet paket restore
+
+# Build the solution
+dotnet build
+
+# Run the Discord bot
+dotnet run --project Bot
+
+# Run the Currency API
+dotnet run --project CurrencyAPI
+```