HikeMap/README.md

HikeMap - Location-Based RPG

A location-based RPG web application where you walk in the real world to explore trails, battle monsters, and level up your character. Also includes GPS track editing tools for trail mapping.

Features

RPG System

Character Creation

• Choose from 4 races: Human, Elf, Dwarf, Halfling
• Select your class (Trail Runner with running-themed skills)
• Set your home base for respawning and skill management

Combat

• Turn-based battles against MOOP (Matter Out Of Place) monsters
• Skill-based combat with damage, healing, buffs, and multi-hit attacks
• Hit/miss mechanics based on accuracy and dodge stats
• Animated combat with synchronized damage timing
• XP rewards and leveling system

Skills & Progression

• Unlock new skills at levels 2, 3, 4, 5, 6, and 7
• Choose between two skills at each milestone (both unlock, one activates)
• Swap your active skill loadout at your home base
• Class-specific skill names (e.g., "Gel Pack" instead of "Heal")

Home Base

• Set anywhere on the map as your respawn point
• 3x HP regeneration when within 20 meters
• Required destination when defeated
• Skill loadout management location

Fog of War

• Unexplored areas hidden by dark overlay
• Reveal zones around your home base and current position
• Geocaches only visible in revealed areas
• Utility skills can expand your reveal radius

Track Editing

• Draw new GPS tracks directly on the map
• Reshape existing tracks with rope physics simulation
• Smooth tracks with a brush tool
• Smart track snapping at endpoints with auto-splitting
• Multi-track selection and merge operations
• 20-step undo/redo history
• Import/export KML files

Navigation Mode

• Graph-based pathfinding using Dijkstra's algorithm
• Automatic trail intersection detection
• Real-time route recalculation when deviating from path
• Map rotation to face direction of travel
• Auto-center on GPS position

Quick Start

Docker (Recommended)

docker-compose up -d

Access at http://localhost:880

Local Development

npm install
node server.js

Access at http://localhost:8080

Game Mechanics

Stats

Stat	Description
HP	Health - reach 0 and you're defeated
MP	Mana - used for skills, regenerates while walking
ATK	Attack power
DEF	Reduces damage taken
Accuracy	Affects hit chance
Dodge	Chance to evade attacks

Trail Runner Skills

Level	Skill Choice A	Skill Choice B
1	Kick-ems! (basic)	-
2	Brand New Hokas (2x hit)	Gel Pack (heal)
3	Downhill Sprint (power)	Pace Yourself (defense)
4	Trail Blaze (AoE)	Quick Feet (accurate)
5	Second Wind (MP buff)	Trail Mix (quick heal)
6	Finish Line Sprint (3x hit)	Zone In (accuracy buff)
7	Ultra Marathon (full heal)	The Bonk (devastating)

See SKILLS.md for complete skill details.

Monsters

Monster	Level Range	Description
Sub Par Moop	1	Tutorial enemy
Moop	1-5	Standard enemy
Fancy Moop	1-5	Higher attack
Fanciest Moop	3-5	Stronger variant

MOOP = Matter Out Of Place (litter-themed enemies encouraging trail cleanup)

Technical Details

Architecture

• Frontend: Single-page app in index.html
• Backend: Node.js/Express server in server.js
• Database: SQLite via better-sqlite3 in database.js
• Animations: Combat animation definitions in animations.js
• Real-time: WebSocket for live updates

Developer Features

• Virtual movement mode for testing without real GPS
• Winch tethering system prevents unlimited virtual exploration
• Admin panel for monster/skill management and icon uploads
• Customizable spawn settings and game balance

Dependencies

• MapLibre GL JS 4.1.0 (WebGL vector maps)
• Turf.js (geospatial calculations)
• Express (API server)
• better-sqlite3 (database)
• jsonwebtoken (authentication)
• ws (WebSocket)

Data Storage

• User accounts with JWT authentication
• Server-authoritative game state
• LocalStorage as offline backup only

Browser Requirements

• Modern browser with ES6 support
• HTTPS or localhost for GPS features
• Location services permission

Documentation

• SKILLS.md - Complete skill reference
• CLAUDE.md - Development guide

License

[Add your license information here]