echoes-of-the-ash/docs/GAME_IMPROVEMENTS_2025.md

Game Improvements - 2025

Summary

This document outlines the major gameplay and UI improvements implemented in this update.

Changes Overview

1. ✅ Distance Tracking in Meters

• Changed: Statistics now track actual distance walked in meters instead of stamina cost
• Implementation:
  • Modified move_player() in api/game_logic.py to return distance as 5th value
  • Distance calculated as: int(coord_distance * 100) for integer meters
  • Updated move endpoint to track distance_walked in meters
• Files Modified:
  • api/game_logic.py (lines 11-66)
  • api/main.py (lines 738-780)

2. ✅ Integer Distance Display

• Changed: All distances rounded to integers (no decimals/centimeters)
• Implementation: Changed all round(distance, 1) to int(distance)
• Files Modified:
  • api/game_logic.py
  • api/main.py (direction details endpoint)

3. ✅ Game Title Update

• Changed: Game name updated to "Echoes of the Ash"
• Files Modified:
  • pwa/src/components/GameHeader.tsx (line 18)
  • pwa/src/components/Login.tsx (line 37)
  • pwa/index.html (title tag)
  • api/main.py (line 85 - API title)

4. ✅ Movement Cooldown System

• Added: 5-second cooldown between movements to prevent rapid zone hopping
• Backend Implementation:
  • Database: Added last_movement_time FLOAT column to players table
  • Migration: migrate_add_movement_cooldown.py (successfully executed)
  • API validates cooldown in move endpoint (returns 400 if < 5 seconds)
  • Game state endpoint returns movement_cooldown (seconds remaining)
• Frontend Implementation:
  • State management: movementCooldown state variable
  • Countdown timer: useEffect hook decrements every second
  • Compass buttons: Disabled during cooldown
  • Visual feedback: Shows ⏳ 3s countdown instead of stamina cost
  • Tooltip: Displays "Wait Xs before moving" when on cooldown
• Duration: Initially 30 seconds, reduced to 5 seconds based on feedback
• Files Modified:
  • api/database.py (line 58 - schema)
  • api/main.py (lines 423-433, 738-765 - cooldown logic)
  • pwa/src/components/Game.tsx (lines 74-75, 93-99, 125-128, 474-498)
  • migrate_add_movement_cooldown.py (new file)
  • Dockerfile.api (line 22 - copy migrations)

5. ✅ Enhanced Danger Level Display

• Changed: Danger level badges enlarged and improved visibility
• Improvements:
  • Font size: Increased to 1rem (from smaller)
  • Padding: Increased to 0.5rem 1.2rem
  • Border radius: Increased to 24px
  • Borders: All levels have 2px solid borders
  • Safe zones: New green badge styling for danger_level 0
• Safe Zone Badge:
  • Background: rgba(76, 175, 80, 0.2)
  • Color: #4caf50 (green)
  • Border: 2px solid #4caf50
• Files Modified:
  • pwa/src/components/Game.css (lines 267-320)
  • pwa/src/components/Game.tsx (location display logic)

6. ✅ Enemy Turn Delay (Combat Animation)

• Added: 2-second dramatic pause for enemy turns in combat
• Implementation:
  • Shows "🗡️ Enemy's turn..." message with orange pulsing animation
  • Waits 2 seconds before displaying enemy attack results
  • Player actions shown immediately
  • Enemy actions shown after delay
• Visual Style:
  • Orange background: rgba(255, 152, 0, 0.2)
  • Border: 2px solid rgba(255, 152, 0, 0.5)
  • Animation: Pulse effect (scale and opacity)
• Files Modified:
  • pwa/src/components/Game.tsx (lines 371-451 - handleCombatAction)
  • pwa/src/components/Game.css (lines 2646-2675 - enemy-turn-message style)

7. ✅ Encounter Rate System

• Added: Random enemy encounters when arriving in dangerous zones
• Mechanics:
  • Triggers only when moving to locations with danger_level > 1
  • Uses encounter_rate from danger_config in locations.json
  • Rolls random chance: if random() < encounter_rate, spawn enemy
  • Selects random enemy from location's spawn table
  • Automatically initiates combat upon arrival
  • Does not trigger if already in combat
• Backend Implementation:
  • Check in move endpoint after successful movement
  • Uses existing LOCATION_DANGER and get_random_npc_for_location()
  • Creates combat directly (not from wandering enemy table)
  • Returns encounter data in move response
• Frontend Implementation:
  • Detects encounter.triggered in move response
  • Sets combat state immediately
  • Shows ambush message in combat log
  • Stores enemy info (name, image)
  • Clears previous combat log
• Example Rates:
  • Safe zones (danger 0): 0% encounter rate
  • Low danger (danger 1): 10% encounter rate
  • Medium danger (danger 2): 15-22% encounter rate
  • High danger (danger 3): 25-30% encounter rate
• Files Modified:
  • api/main.py (lines 780-835 - encounter check in move endpoint)
  • pwa/src/components/Game.tsx (lines 165-218 - handleMove with encounter handling)

Technical Details

Database Changes

• New Column: players.last_movement_time (FLOAT, default 0)
• Migration: Successfully executed via migrate_add_movement_cooldown.py

API Changes

• Move Endpoint (POST /api/game/move):
  • Now validates 5-second cooldown
  • Returns encounter object if triggered
  • Updates last_movement_time timestamp
  • Tracks distance in meters (not stamina)
• Game State Endpoint (GET /api/game/state):
  • Now includes movement_cooldown (seconds remaining)

Frontend Changes

• New State Variables:
  • movementCooldown (number) - seconds remaining
  • enemyTurnMessage (string) - shown during enemy turn delay
• New Effects:
  • Countdown timer for movement cooldown
• Updated Functions:
  • handleMove() - handles encounter responses
  • handleCombatAction() - adds 2-second delay for enemy turns
  • renderCompassButton() - shows cooldown countdown

Configuration

• Movement Cooldown: 5 seconds (reduced from initial 30 seconds)
• Enemy Turn Delay: 2 seconds
• Encounter Rates: Configured per location in gamedata/locations.json

Testing Notes

• ✅ All containers rebuilt successfully
• ✅ Migration executed without errors
• ✅ Movement cooldown functional (backend + frontend)
• ✅ Danger badges properly styled
• ✅ Combat turn delay working with animation
• ✅ Encounter system integrated with move endpoint

Known Issues

• TypeScript lint errors (pre-existing configuration issues, do not affect functionality)
• No issues with core game mechanics

Future Improvements

• Consider adding sound effects for enemy turns
• Add visual shake/impact effect during enemy attacks
• Consider different cooldown times based on distance traveled
• Add encounter notification sound/vibration

---

Deployment Date: 2025
Status: ✅ Successfully Deployed
Game Version: Updated to "Echoes of the Ash"