mp-xieyingeng/QUICK_REFERENCE.md

# QUICK REFERENCE - Game Points/Score System

## 🎮 What is the "Currency"?
**LIVES** - Not traditional points/coins, but a renewable "health" resource.

## 📊 Lives Management
```
Storage Key:        "game_lives" (localStorage)
Default:            10
Min Value:          0
Max Value:          ∞ (no limit)

Methods:
├─ getLives()           → Returns current lives
├─ setLives(n)          → Set specific value
├─ consumeLife()        → Deduct 1 life
├─ addLife()            → Add 1 life
├─ hasLives()           → Check if > 0
└─ resetLives()         → Reset to 10
```

## 🎯 How Lives Are Spent
| Action | Cost | Where |
|--------|------|-------|
| Unlock Clue 2 | 1 Life | PageLevel → onUnlockClue(2) |
| Unlock Clue 3 | 1 Life | PageLevel → onUnlockClue(3) |
| **TOTAL PER LEVEL** | **0-2 Lives** | Depends on player choice |

## 🏆 How Lives Are Earned
| Action | Reward | Where |
|--------|--------|-------|
| Complete a Level | +1 Life | PageLevel → showSuccess() |
| Wrong Answer | 0 | No penalty |
| Time Up | 0 | No penalty |

## 📈 Level Progression
```
Storage Key:     "game_progress" (localStorage)
Structure:
{
  currentLevelIndex: number,      // 0-based, current level
  maxUnlockedLevelIndex: number   // 0-based, highest reached
}

Default:         { currentLevelIndex: 0, maxUnlockedLevelIndex: 0 }
```

### Progression Rules:
1. **Level 1 always unlocked** - Start here
2. **Beat Level N** → currentLevel becomes N+1
3. **Beat Level N** → maxUnlocked becomes max(maxUnlocked, N)
4. **Can replay earlier levels** - But always progress forward

### Methods:
```
getCurrentLevelIndex()          → Get current (0-based)
setCurrentLevelIndex(n)         → Jump to level
getMaxUnlockedLevelIndex()      → Get highest reached
isLevelUnlocked(n)              → Check if playable
onLevelCompleted(n)             → Save win + progress
resetProgress()                 → Reset to level 1
```

## 🎨 Level Data (from API)
**Endpoint:** `https://ilookai.cn/api/v1/wechat-game/levels`

```typescript
ApiLevelData {
    id: string,          // UUID
    level: number,       // Level number (1-based display)
    imageUrl: string,    // Main puzzle image
    hint1: string,       // Free clue
    hint2: string,       // Costs 1 life
    hint3: string,       // Costs 1 life
    answer: string,      // The answer (case-sensitive, trimmed)
    sortOrder: number    // Sort order
}
```

## ⏱️ Gameplay Mechanics

### Time Limit
- **Duration:** 60 seconds per level
- **On Timeout:** Play fail sound, game doesn't end
- **After Timeout:** Can still submit answers

### Input System
- **Type:** Single text box (not per-character)
- **Processing:** Trimmed, case-sensitive comparison
- **Max Length:** Based on answer length

### Win Condition
```
input.trim() === answer
↓
Play success sound → Stop timer → Award +1 life 
→ Show PassModal → Save progress
```

### Lose Condition
```
input.trim() !== answer
↓
Play fail sound → Vibrate → Show toast
→ Lives unchanged → Can retry
```

## 🎁 Rewards & Penalties
| Event | Lives Change | Other Effects |
|-------|--------------|---------------|
| Correct Answer | +1 | Play success sound, show modal |
| Wrong Answer | 0 | Play fail sound, vibrate, toast |
| Unlock Clue | -1 | Show clue content |
| Time Up | 0 | Play fail sound, countdown stops |
| Level Complete | Already +1ed | Save progress, move to next |

## 🔄 Economy Balance
```
Starting Inventory:    10 lives

Without Hints:         +1 life/level   → Infinite
With 1 Hint/Level:     0 lives/level   → Stable
With 2 Hints/Level:    -1 life/level   → Finite (10-20 levels)

Net Formula:           newLives = oldLives - hintsUsed + 1 (on win)
```

## 📡 API Integration
```
LevelDataManager {
    API_URL: "https://ilookai.cn/api/v1/wechat-game/levels"
    TIMEOUT: 8000ms
    RETRY_COUNT: 2
    
    Calls:
    ├─ initialize()          → Load all level metadata + image for level 1
    ├─ ensureLevelReady(n)   → Load specific level image
    ├─ preloadNextLevel(n)   → Silently preload level n+1
    └─ getLevelConfig(n)     → Get cached level data
}
```

## 📁 Storage Schema
```
localStorage: {
    "game_lives": "10",
    "game_progress": "{\"currentLevelIndex\":0,\"maxUnlockedLevelIndex\":0}"
}
```

## 🌐 WeChat Integration
```
Features Used:
├─ WxSDK.initShare()       → Enable sharing
├─ WxSDK.shareAppMessage() → Share to friend with level query param
├─ WxSDK.vibrateLong()     → 400ms vibration on error
└─ WxSDK.vibrateShort()    → 15ms vibration on click
```

## 🔑 Key Files
```
StorageManager.ts         → Lives & progress persistence
LevelDataManager.ts       → API & image loading
PageLevel.ts              → Main game logic
PageLoading.ts            → App initialization
PassModal.ts              → Victory screen
ViewManager.ts            → Page navigation
WxSDK.ts                  → WeChat APIs
```

## ⚙️ Constants
```
DEFAULT_LIVES               10
MIN_LIVES                   0
LEVEL_TIME_LIMIT            60 seconds
LIFE_PER_HINT               1
LIFE_PER_WIN                1
API_TIMEOUT                 8000ms
API_RETRY_COUNT             2

Game Title                  "写英语" (Write English)
Share Query Format          "level=<levelIndex>"
```

## 🚨 No Implementation For:
- User Authentication (wx.login)
- Backend Progress Save
- Ads/Monetization
- Leaderboards
- Analytics
- Premium Life Refills
- Difficulty Levels

---

**In Summary:** Players earn/spend LIVES by unlocking clues (-1 each) or winning levels (+1 each). Progress is saved locally with streak tracking. The economy encourages players to solve without hints to maximize lives.