text-adventure-game/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a text-based idle adventure game (文字冒险游戏) built with uni-app, Vue 3, and Pinia. The game features skill-driven progression, idle mechanics, combat, crafting, and a dark post-apocalyptic theme.

**Tech Stack:**
- Framework: uni-app (Vue 3 with Composition API)
- State Management: Pinia
- Testing: Jest + Vitest + Playwright
- Style: SCSS with global variables

## Build and Run Commands

### Development
- Use HBuilderX IDE to run the project (uni-app standard)
- Run to different platforms: mp-weixin (WeChat Mini Program), h5, app

### Testing
```bash
npm test              # Run Jest tests in watch mode
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Generate coverage report
```

## Architecture

### Directory Structure
```
├── components/
│   ├── common/       # Reusable UI components (ProgressBar, StatItem, etc.)
│   ├── layout/       # Layout components (TabBar, Drawer)
│   ├── panels/       # Main game panels (StatusPanel, MapPanel, LogPanel)
│   └── drawers/      # Slide-out drawers (Inventory, Event, Shop, Crafting)
├── config/           # Game configuration (skills, items, enemies, locations, etc.)
├── store/            # Pinia stores (player.js, game.js)
├── utils/            # Game systems (combat, skill, item, task, event, etc.)
├── pages/            # Uni-app pages
└── tests/            # Unit tests with fixtures and helpers
```

### Core Systems (utils/)
- **skillSystem.js**: Skill unlocking, XP, leveling, milestone rewards, parent skills
- **combatSystem.js**: AP/EP hit calculation, three-layer defense (evade/shield/armor), damage
- **itemSystem.js**: Item usage, equipment, quality calculation, inventory management
- **taskSystem.js**: Idle task management, mutual exclusion checks
- **eventSystem.js**: Event triggering, NPC dialogue handling
- **environmentSystem.js**: Environment penalties, passive skill XP
- **gameLoop.js**: Main game tick (1-second interval), time progression, auto-save
- **storage.js**: Save/load using uni.setStorageSync, offline earnings
- **craftingSystem.js**: Recipe-based crafting with quality calculation
- **levelingSystem.js**: Player level progression and stat scaling
- **mapLayout.js**: Visual map representation

### State Management (Pinia Stores)
- **player.js**: Base stats, current stats (HP/stamina/sanity), level, skills, equipment, inventory, currency, location, flags
- **game.js**: Current tab, drawer states, logs, game time, combat state, active tasks, market prices, current event

### Configuration (config/)
- **constants.js**: Game constants (quality levels, stat scaling, time scale, etc.)
- **skills.js**: All skill definitions with milestones and unlock conditions
- **items.js**: All item definitions (weapons, consumables, materials, books)
- **enemies.js**: Enemy stats, drops, spawn conditions
- **locations.js**: Area definitions, connections, activities, unlock conditions
- **npcs.js**: NPC dialogue trees and interactions
- **events.js**: Event definitions and triggers
- **recipes.js**: Crafting recipes
- **shop.js**: Shop inventory and pricing
- **formulas.js**: Mathematical formulas for stat calculations

## Key Game Concepts

### Quality System (品质系统)
Items have quality (0-250) that affects their power:
- 0-49: 垃圾 (Trash)
- 50-99: 普通 (Common)
- 100-139: 优秀 (Good)
- 140-169: 稀有 (Rare)
- 170-199: 史诗 (Epic)
- 200-250: 传说 (Legendary)

Each tier has a multiplier that increases item stats.

### AP/EP Combat System
- AP (Attack Points) = 灵巧 + 智力×0.2 + skills + equipment + stance - enemyCountPenalty
- EP (Evasion Points) = 敏捷 + 智力×0.2 + skills + equipment + stance - environmentPenalty
- Hit rate is non-linear: AP=5×EP → ~98%, AP=EP → ~50%, AP=0.5×EP → ~24%

### Three-Layer Defense
1. Evasion (complete dodge)
2. Shield absorption
3. Defense reduction (min 10% damage)

### Skill Milestones
Skills provide permanent global bonuses at specific levels (e.g., all weapons +crit rate at level 5). Parent skills auto-level to match highest child skill level.

### Time System
- 1 real second = 5 game minutes
- Day/night cycle affects gameplay
- Markets refresh daily
- Offline earnings available (0.5h base, 2.5h with ad)

### Idle Tasks
Active tasks (reading, training, working) and passive tasks (environment adaptation). Combat is mutually exclusive with most tasks.

## Important Patterns

### Adding New Skills
1. Add config to `config/skills.js`
2. Set unlockCondition (item, location, or skill level)
3. Add milestones with permanent bonuses
4. Link to parentSkill if applicable

### Adding New Items
1. Add config to `config/items.js`
2. Set baseValue, baseDamage/defense, type
3. Add to shop or enemy drop tables
4. For equipment, quality affects final stats

### Adding New Locations
1. Add to `config/locations.js`
2. Set connections, enemies, activities
3. Add unlockCondition if needed
4. Update `utils/mapLayout.js` for visual representation

### Store Usage
```javascript
import { usePlayerStore } from '@/store/player.js'
import { useGameStore } from '@/store/game.js'

const player = usePlayerStore()
const game = useGameStore()

// Access state
player.baseStats.strength
game.logs

// Call actions
game.addLog('message', 'info')
```

### Color Variables (uni.scss)
- $bg-primary: #0a0a0f (main background)
- $accent: #4ecdc4 (primary accent)
- $danger: #ff6b6b (combat/HP low)
- Quality colors: $quality-trash through $quality-legend

## Development Workflow

### Game Loop Timing
- Main loop runs every 1 second via `gameLoop.js`
- Time advances by TIME_SCALE (5) minutes per tick
- Auto-save triggers every 30 game minutes

### Saving
- `App.vue` handles onLaunch/onShow/onHide
- Auto-saves on app hide
- Manual save via `window.manualSave()`
- Logs are NOT persisted (cleared on load)

### Testing
- Tests in `tests/unit/` use Vitest
- Fixtures in `tests/fixtures/` provide mock data
- Helpers in `tests/helpers/` mock timers, stores, random
- See `tests/README.md` for testing guidelines

## Known Gotchas

1. **uni API availability**: Some uni APIs only work in specific platforms (H5 vs mini-program)
2. **Store timing**: Always use `setActivePinia(createPinia())` in tests
3. **Logs array**: Limited to 200 entries, shifts old entries
4. **Skill level cap**: Cannot exceed player level × 2
5. **Equipment quality**: Calculated as base × quality% × tierMultiplier
6. **Combat stance**: Switching stance resets attack progress
7. **Market saturation**: Selling same item reduces price (encourages exploration)