# Game System Summary - Points/Score/Lives Analysis

**Project:** Cocos Creator WeChat Mini-Game ("写英语" - Write English)  
**Date Analyzed:** April 5, 2026  
**Analysis Scope:** Complete TypeScript codebase (21 source files)

---

## Executive Summary

This game uses a **LIVES-based economy** rather than traditional points/coins:

- **Currency:** Lives (renewable resource)
- **Starting Value:** 10 lives per new player
- **Earning Mechanic:** +1 life per completed level
- **Spending Mechanic:** -1 life per hint unlock (optional, 2 hints available)
- **Net Effect:** Players naturally gain lives if they solve without hints, stay stable with 1 hint/level, or lose lives if using both hints

The system is **fully persistent** (saved to localStorage) and **progression-aware** (can replay earlier levels while advancing).

---

## Files Analyzed (21 total)

### Core Game Logic (4 files)
1. **PageLevel.ts** (786 lines) - Main gameplay, hint system, answer validation
2. **LevelDataManager.ts** (312 lines) - API calls, level caching, image loading
3. **StorageManager.ts** (240 lines) - Lives & progress persistence
4. **PageLoading.ts** (88 lines) - App initialization, preloading

### UI/Navigation (3 files)
5. **ViewManager.ts** (320 lines) - Page stack management
6. **BaseView.ts** (132 lines) - View lifecycle
7. **PassModal.ts** (155 lines) - Victory screen with rewards

### Utilities (5 files)
8. **ToastManager.ts** (59 lines) - Toast notifications
9. **WxSDK.ts** (188 lines) - WeChat API wrapper
10. **HttpUtil.ts** (76 lines) - HTTP requests
11. **Toast.ts** (50 lines) - Toast display component
12. **LevelTypes.ts** (59 lines) - TypeScript interfaces

### Prefabs & Entry Points (3 files)
13. **PageHome.ts** (78 lines) - Home page
14. **main.ts** (59 lines) - App entry point
15. Plus UI utilities (BackgroundScaler, RoundedRectMask)

---

## The Complete Points/Lives Flow

### 🟢 EARNING Lives
| Event | Amount | Condition |
|-------|--------|-----------|
| Correct Answer | +1 | Submitted answer matches API answer exactly (case-sensitive, trimmed) |
| New Game | +10 | First time players only (default) |
| **Cannot Earn** | 0 | Wrong answers, timeouts, hint unlocks, returning players don't reset |

### 🔴 SPENDING Lives
| Event | Amount | Condition |
|--------|--------|-----------|
| Unlock Hint 2 | -1 | Player clicks unlock, must have lives > 0 |
| Unlock Hint 3 | -1 | Player clicks unlock, must have lives > 0 |
| No Other Costs | - | No penalties for wrong answers or timeouts |

### 📊 Net Economy Per Level
```
Best Case (No Hints):     +1 life/level   → Infinite scaling
Average Case (1 Hint):     0 lives/level  → Stable indefinitely
Hard Case (2 Hints):      -1 life/level  → Runs out after 10-20 levels
```

---

## Data Persistence

### localStorage Keys
```javascript
{
  "game_lives": "10",                          // Current lives count
  "game_progress": "{                          // Player progression
    \"currentLevelIndex\": 0,
    \"maxUnlockedLevelIndex\": 0
  }"
}
```

### Lifespan
- **Initial:** Set when first loading game
- **Updates:** Every level completion or hint unlock
- **Persistence:** Survives app close/reopen (native browser storage)
- **Manual Reset:** Available via `StorageManager.resetAll()`

---

## Level Progression System

### Mechanics
1. **Level 1 Always Unlocked** - New players start here
2. **Sequential Unlocking** - Beat level N to unlock level N+1
3. **Non-Linear Progress** - Can replay earlier levels anytime
4. **Max Tracking** - Tracks highest level reached for achievements

### Data Structure
```typescript
{
  currentLevelIndex: number,      // Which level to play next (0-based)
  maxUnlockedLevelIndex: number   // Highest level player has beaten
}
```

### Example Progression
```
User beats Level 3 (index 2)
↓
currentLevelIndex → 2+1 = 3 (level 4)
maxUnlockedLevelIndex → max(2, previous) = 2
↓
Can now play levels 0-3
Must complete level 3 to unlock level 4
```

---

## Hint System

### Mechanics
- **Hint 1:** Always visible, completely free
- **Hint 2:** Hidden by default, costs 1 life to unlock
- **Hint 3:** Hidden by default, costs 1 life to unlock

### Implementation
```typescript
onUnlockClue(index: 2|3) {
    if (!hasLives()) return;           // Must have >= 1 life
    consumeLife();                     // Deduct 1 life
    showClue(index);                   // Reveal the clue content
}
```

### Strategic Element
Players must decide if they want to spend lives for hints or solve blindly to accumulate more lives for future levels.

---

## Gameplay Loop

### Per-Level Sequence
1. Load level image from API cache
2. Display Hint 1 (free) + two "Unlock" buttons
3. Start 60-second countdown
4. Player can:
   - Unlock hints by spending lives (optional, repeatable)
   - Type their answer in single text box
   - Submit answer
5. Outcome:
   - **Correct:** Reward +1 life, show victory modal
   - **Wrong:** No penalty, show error toast, can retry
   - **Timeout:** Play fail sound, can still submit

### Victory Rewards
```
onSubmitAnswer(userAnswer) {
    if (userAnswer.trim() === correctAnswer) {
        playSuccessSound();
        addLife();                    // +1 life
        StorageManager.onLevelCompleted(currentLevel);
        showPassModal();              // Next/Share buttons
    }
}
```

---

## API Integration

### Endpoint
```
GET https://ilookai.cn/api/v1/wechat-game/levels
```

### Response Format
```typescript
{
  success: boolean,
  message: string | null,
  data: {
    levels: [
      {
        id: "uuid",
        level: 1,
        imageUrl: "https://...",
        hint1: "Free clue",
        hint2: "Paid clue",
        hint3: "Paid clue",
        answer: "CORRECT_ANSWER",
        sortOrder: 1
      },
      // ... more levels
    ],
    total: number
  }
}
```

### Reliability Features
- **Retry Logic:** 2 attempts on failure
- **Timeout:** 8 seconds per request
- **Fallback:** Shows error message if all retries fail
- **Caching:** All levels cached in memory after first load

---

## WeChat Integration

### Features Implemented
1. **Sharing** - Share game to friends with level parameter
2. **Vibration** - Haptic feedback on errors
3. **Platform Detection** - Gracefully degrade on non-WeChat platforms

### Share Implementation
```typescript
// On victory, user can click "Share"
WxSDK.shareAppMessage({
    title: "快来一起玩这款游戏吧",
    query: `level=${victoryLevelIndex}`
});
// Opens WeChat share dialog with referral link
```

### Not Implemented
- ❌ User authentication (wx.login)
- ❌ Backend progress sync
- ❌ Analytics
- ❌ Ads/Monetization
- ❌ Leaderboards

---

## User Journey Example

```
New User Opens Game
  ↓
[Initialize: 10 lives, Level 1]
  ↓
Attempt Level 1
  ├─ Unlocks Hint 2 (-1 life)           → 9 lives
  ├─ Unlocks Hint 3 (-1 life)           → 8 lives
  ├─ Submits Answer
  │
  ├─ CORRECT
  │  ├─ Awards +1 life                  → 9 lives
  │  ├─ Saves progress (level → 2)
  │  └─ Shows PassModal
  │     ├─ Can click "Next Level"       → Level 2
  │     └─ Can click "Share"            → wx.share
  │
  └─ WRONG
     ├─ No penalty                      → 9 lives unchanged
     ├─ Shows error toast
     └─ Can retry immediately
```

---

## Loading & Initialization

### On App Start
1. **Detect New vs. Returning User**
   - Check localStorage "game_lives" key
   - New: Initialize to 10
   - Returning: Restore value

2. **Load Level Metadata**
   - API call to fetch all levels
   - Retry up to 2 times on failure
   - Cache all level data in memory

3. **Preload First Level**
   - Download image for level 1
   - Cache in memory for instant display

4. **Show Home Screen**
   - Display "Start Game" button
   - Initialize WeChat sharing

### On Subsequent Game Sessions
1. Restore lives from localStorage
2. Restore progress from localStorage
3. Resume at saved level
4. API already cached (no refetch unless app restarted)

---

## Key Constants

| Constant | Value | Usage |
|----------|-------|-------|
| DEFAULT_LIVES | 10 | New player starting amount |
| MIN_LIVES | 0 | Cannot go negative |
| LEVEL_TIME_LIMIT | 60 seconds | Countdown timer |
| API_TIMEOUT | 8000ms | HTTP request timeout |
| API_RETRY_COUNT | 2 | Attempts on failure |
| HINT_COST | 1 life each | Unlock clue 2 or 3 |
| WIN_REWARD | 1 life | Completion bonus |
| MODAL_Z_INDEX | 999 | Victory modal layer |

---

## Business Logic Highlights

### Win Condition
```typescript
userAnswer.trim() === correctAnswer
```
- Case-sensitive
- Whitespace trimmed
- Must match exactly

### No Lose Condition
- Wrong answers: No penalty
- Time up: No penalty
- Can retry infinitely on same level

### Safety Checks
- Can't unlock hints if lives ≤ 0
- Can't go below 0 lives
- Can't exceed total levels
- Invalid data resets to defaults

---

## Performance Optimizations

1. **Image Caching** - Downloaded images cached in memory
2. **Level Metadata Caching** - API data cached to avoid re-fetching
3. **Progress Caching** - localStorage data cached to reduce reads
4. **Async Preloading** - Next level preloaded silently
5. **Efficient UI** - Single EditBox (not per-character)
6. **Lazy Loading** - Pages cached after first load

---

## Missing Features / Gaps

| Feature | Status | Impact |
|---------|--------|--------|
| User Authentication | ❌ | No way to sync across devices |
| Backend Progress Save | ❌ | Progress lost if localStorage clears |
| Monetization | ❌ | No revenue stream |
| Ads | ❌ | No ad integration |
| Analytics | ❌ | Can't track player behavior |
| Leaderboards | ❌ | No competition mechanics |
| Sound Toggle | ❌ | Always plays sounds |
| Difficulty Levels | ❌ | All players see same levels |

---

## Testing Scenarios

### Test Case 1: Lives Economy
```
1. New game → 10 lives
2. Beat level without hints → 11 lives
3. Beat level with 1 hint → 11 lives (net 0)
4. Beat level with 2 hints → 10 lives (net -1)
→ Verify localStorage updated after each
```

### Test Case 2: Progression
```
1. Complete level 1
2. Verify currentLevel → 2
3. Verify maxUnlocked → 1
4. Restart app
5. Verify levels still saved
6. Replay level 1
7. Verify no duplicate progress
```

### Test Case 3: Hint Cost
```
1. Start with 10 lives
2. Unlock hint 2 → 9 lives displayed
3. Unlock hint 3 → 8 lives displayed
4. Can't unlock again (button inactive)
5. Wrong answer → 8 lives still
6. Correct answer → 9 lives (net -1)
```

---

## Conclusion

This is a **well-architected mini-game** with:
- ✅ Clear lives-based economy
- ✅ Persistent progress tracking
- ✅ Strategic hint system
- ✅ Reliable API integration
- ✅ Good error handling
- ✅ WeChat platform integration

The point system is **intentionally forgiving** - players who solve puzzles smartly gain lives indefinitely, while those using hints maintain stability. This encourages skill development without hard progress walls.

---

## Documentation Files Generated

1. **GAME_ANALYSIS.md** - Comprehensive 17-section analysis (13KB)
2. **QUICK_REFERENCE.md** - Quick lookup guide (5.6KB)
3. **POINTS_FLOW_DIAGRAM.md** - Visual flow diagrams (15KB)
4. **SUMMARY.md** - This executive summary (8KB)

**Total:** 42KB of detailed documentation covering every aspect of the points/score/lives system.