first commit

2025-11-24 23:10:55 -06:00
commit 8315fa51c9
279 changed files with 74600 additions and 0 deletions
--- a/api/docs/GAME_SYSTEMS.md
+++ b/api/docs/GAME_SYSTEMS.md
@@ -0,0 +1,587 @@
+# Game Systems
+
+## Combat System
+
+### Core Concepts
+
+**Turn-Based Combat:**
+- Initiative rolls determine turn order (d20 + speed stat)
+- Each combatant takes one action per turn
+- Effects (buffs/debuffs/DoT) process at start of turn
+- Combat continues until one side is defeated
+
+### Damage Calculations
+
+| Attack Type | Formula | Min Damage |
+|-------------|---------|------------|
+| **Physical** | weapon.damage + (strength / 2) - target.defense | 1 |
+| **Magical** | spell.damage + (magic_power / 2) - target.resistance | 1 |
+| **Critical Hit** | base_damage × weapon.crit_multiplier | - |
+
+**Critical Hit System:**
+- **Design Choice:** Critical hits only, no damage variance (JRPG-style)
+- Base damage is **deterministic** (always same result for same stats)
+- Random element is **only** whether attack crits
+- Default crit_chance: **5%** (0.05)
+- Default crit_multiplier: **2.0×** (double damage)
+- Weapons can have different crit_chance and crit_multiplier values
+
+**Why This Design:**
+- Predictable damage for tactical planning
+- Exciting moments when crits occur
+- Easier to balance than full damage ranges
+- Simpler AI prompting (no damage variance to explain)
+
+### Combat Flow
+
+| Phase | Actions |
+|-------|---------|
+| **1. Initialize Combat** | Roll initiative for all combatants<br>Sort by initiative (highest first)<br>Set turn order |
+| **2. Turn Start** | Process all active effects on current combatant<br>Check for stun (skip turn if stunned)<br>Reduce spell cooldowns |
+| **3. Action Phase** | Player/AI selects action (attack, cast spell, use item, defend)<br>Execute action<br>Apply damage/effects<br>Check for death |
+| **4. Turn End** | Advance to next combatant<br>If back to first combatant, increment round number<br>Check for combat end condition |
+| **5. Combat Resolution** | **Victory:** Distribute XP and loot<br>**Defeat:** Handle character death/respawn |
+
+### Action Types
+
+| Action | Description | Examples |
+|--------|-------------|----------|
+| **Attack** | Physical weapon attack | Sword strike, bow shot |
+| **Cast Spell** | Use magical ability | Fireball, heal, curse |
+| **Use Item** | Consume item from inventory | Health potion, scroll |
+| **Defend** | Defensive stance | +defense for 1 turn |
+| **Special Ability** | Class-specific skill | Shield bash, stealth strike |
+
+### Effect Mechanics
+
+**Effect Processing:**
+- Effects have **duration** (turns remaining)
+- Effects can **stack** (multiple applications increase power)
+- Effects are processed at **start of turn**
+- Effects expire automatically when duration reaches 0
+
+**Stacking Mechanics:**
+- Effects stack up to **max_stacks** (default 5, configurable per effect)
+- Re-applying same effect increases stacks (up to max)
+- Duration **refreshes** on re-application (does not stack cumulatively)
+- Power scales linearly with stacks: 3 stacks × 5 damage = 15 damage per turn
+- Once at max stacks, re-application only refreshes duration
+
+**Stacking Examples:**
+- Poison (power=5, max_stacks=5): 3 stacks = 15 damage per turn
+- Defense buff (power=3, max_stacks=5): 2 stacks = +6 defense
+- Applying poison 6 times = 5 stacks (capped), duration refreshed each time
+
+**Shield Effect Mechanics:**
+- Shield absorbs damage **before HP loss**
+- Shield strength = power × stacks
+- Partial absorption: If damage > shield, shield breaks and remaining damage goes to HP
+- Full absorption: If damage <= shield, all damage absorbed, shield reduced
+- Shield depletes when power reaches 0 or duration expires
+
+**Effect Interaction with Stats:**
+- BUFF/DEBUFF effects modify stats via `get_effective_stats()`
+- Stat modifications are temporary (only while effect is active)
+- Debuffs **cannot reduce stats below 1** (minimum clamping)
+- Buffs stack with equipment and skill bonuses
+
+### AI-Generated Combat Narrative
+
+**Narrative Generation:**
+- After each combat action executes, generate narrative description
+- Code calculates mechanics ("Aragorn attacks Goblin for 15 damage (critical hit!)")
+- AI generates flavor ("Aragorn's blade finds a gap in the goblin's armor, striking a devastating blow!")
+
+**Model Selection:**
+
+| Encounter Type | Model Tier |
+|----------------|------------|
+| Standard encounters | STANDARD (Haiku) |
+| Boss fights | PREMIUM (Sonnet) |
+| Free tier users | FREE (Replicate) |
+
+---
+
+## Ability System
+
+### Overview
+
+Abilities are actions that can be used in combat (attacks, spells, skills). The system is **data-driven** using YAML configuration files.
+
+### Ability Components
+
+| Component | Description |
+|-----------|-------------|
+| **Base Power** | Starting damage or healing value |
+| **Scaling Stat** | Which stat enhances the ability (STR, INT, etc.) |
+| **Scaling Factor** | Multiplier for scaling (default 0.5) |
+| **Mana Cost** | MP required to use |
+| **Cooldown** | Turns before ability can be used again |
+| **Effects** | Status effects applied on hit |
+
+### Power Calculation
+
+```
+Final Power = base_power + (scaling_stat × scaling_factor)
+Minimum power is always 1
+```
+
+**Examples:**
+- **Cleave** (physical skill): base_power=15, scaling_stat=STRENGTH, scaling_factor=0.5
+  - With 20 STR: 15 + (20 × 0.5) = 25 power
+- **Fireball** (spell): base_power=30, scaling_stat=INTELLIGENCE, scaling_factor=0.5
+  - With 16 INT: 30 + (16 × 0.5) = 38 power
+
+### Mana & Cooldown Mechanics
+
+**Mana System:**
+- Each ability has a mana_cost (0 for basic attacks)
+- Combatant must have current_mp >= mana_cost
+- Mana is consumed when ability is used
+- Mana regeneration happens between combat encounters
+
+**Cooldown System:**
+- Abilities can have cooldowns (turns before re-use)
+- Cooldown starts when ability is used
+- Cooldowns tick down at start of each turn
+- 0 cooldown = can use every turn
+
+**Example:**
+- Power Strike: mana_cost=10, cooldown=3
+- Use on turn 1 → Can't use again until turn 5
+
+### Effect Application
+
+Abilities can apply effects to targets:
+
+```yaml
+effects_applied:
+  - effect_id: "burn"
+    name: "Burning"
+    effect_type: "dot"
+    duration: 3
+    power: 5
+    max_stacks: 3
+```
+
+When ability hits, all `effects_applied` are added to the target's `active_effects`.
+
+### Data-Driven Design
+
+**Benefits:**
+- Game designers can add/modify abilities without code changes
+- Easy balancing through config file edits
+- Version control friendly (text files)
+- Hot-reloading capable (reload without restart)
+
+**Workflow:**
+1. Create YAML file in `/app/data/abilities/`
+2. Define ability properties
+3. AbilityLoader automatically loads on request
+4. Abilities available for use immediately
+
+**Example YAML Structure:**
+```yaml
+ability_id: "shield_bash"
+name: "Shield Bash"
+description: "Bash enemy with shield, dealing damage and stunning"
+ability_type: "skill"
+base_power: 10
+damage_type: "physical"
+scaling_stat: "strength"
+scaling_factor: 0.5
+mana_cost: 5
+cooldown: 2
+effects_applied:
+  - effect_id: "stun_1"
+    name: "Stunned"
+    effect_type: "stun"
+    duration: 1
+    power: 0
+```
+
+### Ability Types
+
+| Type | Description | Typical Use |
+|------|-------------|-------------|
+| **ATTACK** | Basic physical attack | Default melee/ranged attacks |
+| **SPELL** | Magical ability | Fireballs, heals, buffs |
+| **SKILL** | Class-specific ability | Shield bash, backstab, power strike |
+| **ITEM_USE** | Using consumable | Health potion, scroll |
+| **DEFEND** | Defensive action | Defensive stance, dodge |
+
+---
+
+## Multiplayer Party System
+
+### Session Formation
+
+| Step | Action | Details |
+|------|--------|---------|
+| 1 | Create Session | Leader creates session with configuration |
+| 2 | Generate Code | System generates invite code |
+| 3 | Join Session | Other players join via invite code |
+| 4 | Start Game | Session begins when min_players met |
+
+**Max Party Size by Tier:**
+
+| Subscription Tier | Max Party Size |
+|-------------------|----------------|
+| FREE | Solo only (1) |
+| BASIC | 2 players |
+| PREMIUM | 6 players |
+| ELITE | 10 players |
+
+### Turn Flow
+
+1. Turn order determined by initiative
+2. Active player takes action
+3. Action queued to RQ for AI processing
+4. AI response generated
+5. Game state updated in Appwrite
+6. All party members notified via Appwrite Realtime
+7. Next player's turn
+
+### Session End Conditions
+
+| Condition | Result |
+|-----------|--------|
+| Manual end by leader | Session completed |
+| Below min_players for timeout duration | Session timeout |
+| All players leave | Session completed |
+| Total party wipeout in combat | Session completed (defeat) |
+
+### Post-Session
+
+- Players keep all loot/gold earned
+- Session logs saved:
+  - **Free tier:** 7 days
+  - **Basic:** 14 days
+  - **Premium:** 30 days
+  - **Elite:** 90 days
+- Exportable as Markdown
+
+### Realtime Synchronization
+
+**Appwrite Realtime Features:**
+- WebSocket connections for multiplayer
+- Automatic updates when game state changes
+- No polling required
+- Built-in connection management
+- Automatic reconnection
+
+**Update Flow:**
+1. Player takes action
+2. Backend updates Appwrite document
+3. Appwrite triggers realtime event
+4. All subscribed clients receive update
+5. UI updates automatically
+
+---
+
+## Marketplace System
+
+### Overview
+
+| Aspect | Details |
+|--------|---------|
+| **Access Level** | Premium+ subscription tiers only |
+| **Currency** | In-game gold only (no real money trading) |
+| **Listing Types** | Fixed price or auction |
+| **Transaction Fee** | None (may implement later for economy balance) |
+
+### Auction System
+
+**eBay-Style Bidding:**
+
+| Feature | Description |
+|---------|-------------|
+| **Starting Bid** | Minimum bid set by seller |
+| **Buyout Price** | Optional instant-win price |
+| **Duration** | 24, 48, or 72 hours |
+| **Bidding** | Must exceed current bid |
+| **Auto-Win** | Buyout price triggers instant sale |
+| **Winner** | Highest bidder when auction ends |
+| **Notifications** | Outbid alerts via Appwrite Realtime |
+
+**Auction Processing:**
+- RQ periodic task checks for ended auctions every 5 minutes
+- Winner receives item, seller receives gold
+- If no bids, item returned to seller
+
+### Fixed Price Listings
+
+| Feature | Description |
+|---------|-------------|
+| **Price** | Set by seller |
+| **Purchase** | Immediate transaction |
+| **Availability** | First come, first served |
+
+### Item Restrictions
+
+**Non-Tradeable Items:**
+- Quest items
+- Character-bound items
+- Items marked `is_tradeable: false`
+
+### Marketplace Features by Tier
+
+| Tier | Access | Max Active Listings | Priority |
+|------|--------|---------------------|----------|
+| FREE | ✗ | - | - |
+| BASIC | ✗ | - | - |
+| PREMIUM | ✓ | 10 | Normal |
+| ELITE | ✓ | 25 | Priority (shown first) |
+
+---
+
+## NPC Shop System
+
+### Overview
+
+**Game-Run Shop:**
+- Sells basic items at fixed prices
+- Always available (not affected by marketplace access)
+- Provides gold sink to prevent inflation
+
+### Shop Categories
+
+| Category | Items | Tier Range |
+|----------|-------|------------|
+| **Consumables** | Health potions, mana potions, antidotes | All |
+| **Basic Weapons** | Swords, bows, staves | 1-2 |
+| **Basic Armor** | Helmets, chest plates, boots | 1-2 |
+| **Crafting Materials** | (Future feature) | - |
+
+### Pricing Strategy
+
+- Basic items priced reasonably for new players
+- Prices higher than marketplace average (encourages player economy)
+- No selling back to shop (or at 50% value to prevent abuse)
+
+---
+
+## Progression Systems
+
+### Experience & Leveling
+
+| Source | XP Gain |
+|--------|---------|
+| Combat victory | Based on enemy difficulty |
+| Quest completion | Fixed quest reward |
+| Story milestones | Major plot points |
+| Exploration | Discovering new locations |
+
+**Level Progression:**
+- XP required increases per level (exponential curve)
+- Each level grants +1 skill point
+- Stats may increase based on class
+
+### Loot System
+
+**Loot Sources:**
+- Defeated enemies
+- Treasure chests
+- Quest rewards
+- Boss encounters
+
+**Loot Quality Tiers:**
+
+| Tier | Color | Drop Rate | Example |
+|------|-------|-----------|---------|
+| Common | Gray | 60% | Basic health potion |
+| Uncommon | Green | 25% | Enhanced sword |
+| Rare | Blue | 10% | Fire-enchanted blade |
+| Epic | Purple | 4% | Legendary armor |
+| Legendary | Orange | 1% | Artifact weapon |
+
+**Boss Loot:**
+- Bosses always drop rare+ items
+- Guaranteed unique item per boss
+- Chance for legendary items
+
+---
+
+## Quest System (Future)
+
+### Quest Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Main Story** | Plot progression | "Defeat the Dark Lord" |
+| **Side Quest** | Optional content | "Help the blacksmith" |
+| **Daily Quest** | Repeatable daily | "Slay 10 goblins" |
+| **World Event** | Server-wide | "Defend the city" |
+
+### Quest Rewards
+
+- Gold
+- Experience
+- Items (equipment, consumables)
+- Unlock locations/features
+- Reputation with factions
+
+---
+
+## Economy & Balance
+
+### Gold Sources (Inflow)
+
+| Source | Amount |
+|--------|--------|
+| Combat loot | 10-100 per encounter |
+| Quest rewards | 100-1000 per quest |
+| Marketplace sales | Player-driven |
+
+### Gold Sinks (Outflow)
+
+| Sink | Cost |
+|------|------|
+| NPC shop purchases | Varies |
+| Skill respec | Level × 100 gold |
+| Fast travel | 50-500 per location |
+| Equipment repairs | (Future feature) |
+
+### Economy Monitoring
+
+**Metrics to Track:**
+- Average gold per player
+- Marketplace price trends
+- Item availability
+- Transaction volume
+
+**Balancing Actions:**
+- Adjust NPC shop prices
+- Introduce new gold sinks
+- Modify loot drop rates
+- Implement transaction fees if needed
+
+---
+
+## PvP Arena (Future Feature)
+
+### Planned Features
+
+| Feature | Description |
+|---------|-------------|
+| **Arena Mode** | Optional combat mode |
+| **Matchmaking** | Ranked and casual |
+| **Rewards** | Exclusive PvP items |
+| **Leaderboard** | Season-based rankings |
+| **Restrictions** | Balanced gear/levels |
+
+**Note:** PvP is entirely optional and separate from main game.
+
+---
+
+## Guild System (Future Feature)
+
+### Planned Features
+
+| Feature | Description |
+|---------|-------------|
+| **Guild Creation** | Player-run organizations |
+| **Guild Bank** | Shared resources |
+| **Guild Quests** | Cooperative challenges |
+| **Guild Halls** | Customizable spaces |
+| **Guild Wars** | PvP guild vs guild |
+
+---
+
+## World Events (Future Feature)
+
+### Planned Features
+
+| Feature | Description |
+|---------|-------------|
+| **Server-Wide Events** | All players can participate |
+| **Timed Events** | Limited duration |
+| **Cooperative Goals** | Community objectives |
+| **Exclusive Rewards** | Event-only items |
+| **Story Impact** | Events affect world state |
+
+---
+
+## Achievements (Future Feature)
+
+### Planned Categories
+
+| Category | Examples |
+|----------|----------|
+| **Combat** | "Defeat 100 enemies", "Win without taking damage" |
+| **Exploration** | "Discover all locations", "Travel 1000 miles" |
+| **Collection** | "Collect all legendary items", "Complete skill tree" |
+| **Social** | "Join a guild", "Complete 10 multiplayer sessions" |
+| **Story** | "Complete main story", "Complete all side quests" |
+
+**Rewards:**
+- Titles
+- Cosmetic items
+- Special abilities
+- Achievement points
+
+---
+
+## Crafting System (Future Feature)
+
+### Planned Features
+
+| Feature | Description |
+|---------|-------------|
+| **Recipes** | Learn from quests, loot, NPCs |
+| **Materials** | Gather from enemies, exploration |
+| **Crafting Stations** | Special locations required |
+| **Item Enhancement** | Upgrade existing items |
+| **Unique Items** | Crafted-only items |
+
+---
+
+## Common Patterns
+
+### AI Cost Tracking
+
+**Log every AI call:**
+- User ID
+- Model used
+- Cost tier
+- Tokens used
+- Timestamp
+
+**Daily Limits:**
+- Track usage per user per day
+- Block calls if limit exceeded
+- Graceful degradation message
+
+### Error Handling
+
+**Consistent error format:**
+```json
+{
+  "error": "Error message",
+  "code": "ERROR_CODE",
+  "details": {}
+}
+```
+
+### Logging
+
+**Structured logging with context:**
+- Session ID
+- Character ID
+- Action type
+- Results
+- Timestamp
+
+---
+
+## Glossary
+
+| Term | Definition |
+|------|------------|
+| **DM** | Dungeon Master (AI in this case) |
+| **NPC** | Non-Player Character |
+| **DoT** | Damage over Time |
+| **HoT** | Heal over Time |
+| **AoE** | Area of Effect |
+| **XP** | Experience Points |
+| **PWA** | Progressive Web App |