Add visual progress bars and refactor handler modules
- Implement visual HP/Stamina/XP bars using Unicode characters (██░) - Refactor handlers.py (1308 → 377 lines) into specialized modules: * action_handlers.py - World interaction and status display * inventory_handlers.py - Inventory management * combat_handlers.py - Combat actions * profile_handlers.py - Character stats with visual bars * corpse_handlers.py - Looting system * pickup_handlers.py - Item collection - Add utility functions: create_progress_bar(), format_stat_bar() - Organize all documentation into docs/ structure - Create comprehensive documentation index with navigation - Add UI examples showing before/after visual improvements
This commit is contained in:
Joan
221
docs/game/MECHANICS.md
Normal file
221
docs/game/MECHANICS.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# Game Mechanics Overview
|
||||
|
||||
## Core Systems
|
||||
|
||||
### 1. Health & Stamina System
|
||||
|
||||
#### Health Points (HP)
|
||||
- **Purpose:** Measure of character's life force
|
||||
- **Starting Value:** 100 HP
|
||||
- **Range:** 0 to max_hp
|
||||
- **Death:** Occurs when HP reaches 0
|
||||
- **Regeneration:** Does not auto-regenerate (requires items or rest)
|
||||
- **Display:** Visual bar with percentage
|
||||
```
|
||||
❤️ HP: ███████░░░ 70% (70/100)
|
||||
```
|
||||
|
||||
#### Stamina
|
||||
- **Purpose:** Resource for actions and movement
|
||||
- **Starting Value:** 100 Stamina
|
||||
- **Range:** 0 to max_stamina
|
||||
- **Usage:**
|
||||
- Movement between locations (varies by distance and inventory weight)
|
||||
- Actions on interactables (searching, opening, etc.)
|
||||
- **Regeneration:** Passive over time (1 + endurance/10 per cycle)
|
||||
- **Display:** Visual bar with percentage
|
||||
```
|
||||
⚡ Stamina: █████░░░░░ 50% (50/100)
|
||||
```
|
||||
|
||||
### 2. Character Progression
|
||||
|
||||
#### Experience (XP)
|
||||
- **Gained From:**
|
||||
- Defeating enemies
|
||||
- Completing actions
|
||||
- Exploring new locations
|
||||
- **Display:** Progress bar showing advancement to next level
|
||||
```
|
||||
⭐ XP: ████░░░░░░ 40% (240/600)
|
||||
```
|
||||
|
||||
#### Leveling
|
||||
- **Formula:** XP required = 100 * (level ^ 1.5)
|
||||
- **Benefits:**
|
||||
- Stat point to allocate
|
||||
- Increased base damage
|
||||
- Access to new areas
|
||||
|
||||
#### Stats
|
||||
- **Strength (💪)**
|
||||
- Increases melee damage
|
||||
- Formula: Base Damage = 5 + (strength / 2) + level
|
||||
|
||||
- **Agility (🏃)**
|
||||
- Increases flee chance in combat
|
||||
- Formula: Flee Chance = 50% + (agility / 100)
|
||||
|
||||
- **Endurance (💚)**
|
||||
- Increases max HP when leveled
|
||||
- Increases stamina regeneration
|
||||
- Formula: Stamina Regen = 1 + (endurance / 10)
|
||||
|
||||
- **Intellect (🧠)**
|
||||
- Reserved for future mechanics
|
||||
- May affect crafting, dialogue, etc.
|
||||
|
||||
#### Stat Points
|
||||
- **Earned:** 1 point per level
|
||||
- **Allocation Options:**
|
||||
- +10 Max HP
|
||||
- +5 Max Stamina
|
||||
- +1 Strength
|
||||
- +1 Agility
|
||||
- +1 Endurance
|
||||
- +1 Intellect
|
||||
|
||||
### 3. Inventory System
|
||||
|
||||
#### Capacity
|
||||
- **Weight Limit:** 50 kg (base) + equipped backpack bonus
|
||||
- **Volume Limit:** 100 vol (base) + equipped backpack bonus
|
||||
- **Overencumbered:** Cannot pick up items when at capacity
|
||||
- **Movement Penalty:** Higher inventory weight increases stamina cost for travel
|
||||
|
||||
#### Item Types
|
||||
- **Weapons:** Equippable, adds damage
|
||||
- **Armor:** Equippable, adds protection
|
||||
- **Consumables:** Single-use, restores HP/Stamina
|
||||
- **Tools:** Required for certain actions
|
||||
- **Materials:** Crafting components (future)
|
||||
- **Quest Items:** Special items for progression
|
||||
|
||||
#### Equipment Slots
|
||||
- **Weapon:** Primary attack tool
|
||||
- **Backpack:** Increases carrying capacity
|
||||
- **Armor:** Protection (future implementation)
|
||||
|
||||
### 4. Combat System
|
||||
|
||||
#### Turn-Based Combat
|
||||
- Player turn → NPC turn → Repeat until victory or defeat
|
||||
|
||||
#### Actions
|
||||
- **Attack:** Deal damage to enemy
|
||||
- **Flee:** Attempt to escape (chance-based)
|
||||
- **Use Item:** Consume healing/buff items
|
||||
|
||||
#### Damage Calculation
|
||||
```python
|
||||
Base Damage = 5 + (strength / 2) + level
|
||||
Weapon Damage = random(weapon_min, weapon_max)
|
||||
Total Damage = Base Damage + Weapon Damage
|
||||
```
|
||||
|
||||
#### Enemy Spawning
|
||||
- **Static Spawns:** Fixed enemies at locations
|
||||
- **Random Encounters:** Chance-based when moving
|
||||
- **Wandering Enemies:** NPCs that patrol locations
|
||||
|
||||
#### Death & Respawn
|
||||
- **Player Death:** Lose all inventory, respawn at start location
|
||||
- **Corpses:** Player corpses can be looted by others (multiplayer aspect)
|
||||
- **Enemy Death:** Drop loot, award XP
|
||||
|
||||
### 5. World Interaction
|
||||
|
||||
#### Locations
|
||||
- **Types:** Safe zones, dangerous areas, dungeons
|
||||
- **Connections:** Graph-based navigation
|
||||
- **Images:** Visual representation of each location
|
||||
- **Interactables:** Objects to search/interact with
|
||||
|
||||
#### Actions
|
||||
- **Inspect Area:** View location details and items
|
||||
- **Move:** Travel to connected locations
|
||||
- **Search Objects:** Loot interactables for items
|
||||
- **Attack Enemies:** Engage wandering NPCs
|
||||
|
||||
#### Cooldowns
|
||||
- **Purpose:** Prevent infinite resource farming
|
||||
- **Duration:** Varies by action (typically 5-30 minutes)
|
||||
- **Per-Object:** Each interactable has independent cooldown
|
||||
|
||||
### 6. Item Collection
|
||||
|
||||
#### Dropped Items
|
||||
- **Sources:**
|
||||
- Enemy loot
|
||||
- Interactable rewards
|
||||
- Player-dropped items
|
||||
- **Pickup:** Choose quantity to take
|
||||
- **Capacity Check:** Must have room in inventory
|
||||
|
||||
#### Looting
|
||||
- **NPC Corpses:**
|
||||
- Requires tools for certain materials
|
||||
- Random quantities
|
||||
- Disappears when fully looted
|
||||
|
||||
- **Player Corpses:**
|
||||
- Contains all inventory from death
|
||||
- Can be looted by any player
|
||||
- Encourages retrieval runs
|
||||
|
||||
## Game Loop
|
||||
|
||||
### Basic Cycle
|
||||
1. **Explore** → Move to new location
|
||||
2. **Inspect** → Find interactables and enemies
|
||||
3. **Action** → Search, fight, or collect
|
||||
4. **Manage** → Organize inventory, use items
|
||||
5. **Progress** → Gain XP, level up, allocate stats
|
||||
6. **Repeat**
|
||||
|
||||
### Resource Management
|
||||
- Monitor HP and Stamina
|
||||
- Use consumables strategically
|
||||
- Rest when needed
|
||||
- Manage inventory weight
|
||||
|
||||
### Risk vs. Reward
|
||||
- Dangerous areas have better loot
|
||||
- Higher-level enemies give more XP
|
||||
- Overextending can lead to death
|
||||
- Strategic retreats preserve progress
|
||||
|
||||
## Progression Path
|
||||
|
||||
### Early Game (Levels 1-5)
|
||||
- Learn basic mechanics
|
||||
- Gather starting equipment
|
||||
- Explore safe zones
|
||||
- Build initial stats
|
||||
|
||||
### Mid Game (Levels 6-15)
|
||||
- Venture into dangerous areas
|
||||
- Face tougher enemies
|
||||
- Collect better equipment
|
||||
- Specialize character build
|
||||
|
||||
### Late Game (Levels 16+)
|
||||
- Challenge end-game content
|
||||
- Optimize builds
|
||||
- Collect rare items
|
||||
- Explore all areas
|
||||
|
||||
## Future Mechanics
|
||||
|
||||
### Planned Features
|
||||
- **Crafting System:** Combine materials into items
|
||||
- **Quests:** Story-driven objectives
|
||||
- **Factions:** Reputation and alliances
|
||||
- **Trading:** Player-to-player economy
|
||||
- **Skills:** Special abilities beyond stats
|
||||
- **Housing:** Personal storage and rest areas
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** October 19, 2025
|
||||
**Status:** Living document - Updated as mechanics evolve
|
||||
Reference in New Issue
Block a user