# 📚 Game Points/Lives System - Documentation Index

> Complete analysis of the Cocos Creator WeChat Mini-Game points/score/lives system

**Generated:** April 5, 2026  
**Scope:** All 21 TypeScript source files analyzed  
**Total Documentation:** ~45KB

---

## 📄 Documentation Files

### 1. **SUMMARY.md** (11 KB) ⭐ **START HERE**
**Best for:** High-level overview and executive understanding

**Contains:**
- Executive summary of the lives-based economy
- 21 files analyzed (categorized)
- Complete points/lives flow table
- Data persistence details
- Level progression mechanics
- Hint system mechanics
- Gameplay loop description
- API integration overview
- WeChat integration features
- User journey example
- Testing scenarios
- Business logic highlights

**Read this if:** You want a quick understanding of how the entire system works

---

### 2. **GAME_ANALYSIS.md** (13 KB)
**Best for:** Deep technical analysis of every system component

**Contains 17 Sections:**
1. Project Overview
2. Lives/Resource System (complete)
3. Level Progression System
4. Game Level Data & API
5. Gameplay Loop
6. Winning & Rewards
7. Losing & Consequences
8. Hint/Clue System
9. Network & API Communication
10. WeChat SDK Integration
11. Game State Management
12. Loading Page Logic
13. Complete Points Flow Diagram
14. Key Files Summary (table)
15. Important Constants
16. Missing Features
17. Data Flow Summary & Business Logic

**Read this if:** You need comprehensive technical details on every aspect

---

### 3. **QUICK_REFERENCE.md** (5.6 KB)
**Best for:** Quick lookup while coding

**Contains:**
- What is the currency? (Lives)
- Lives management methods
- How lives are spent (table)
- How lives are earned (table)
- Level progression mechanics
- Level data structure (from API)
- Gameplay mechanics (time limit, input, conditions)
- Rewards & penalties (table)
- Economy balance formulas
- API integration details
- Storage schema
- WeChat integration points
- Key files list
- Important constants
- What's NOT implemented

**Read this if:** You need quick facts/numbers without reading full docs

---

### 4. **POINTS_FLOW_DIAGRAM.md** (22 KB)
**Best for:** Visual understanding of system flows

**Contains ASCII Diagrams For:**
1. Initialization Phase
2. Gameplay Phase (single level)
3. Lives Transaction Flow
4. Level Progression & Persistence
5. Data Persistence (localStorage)
6. API & Level Data Flow
7. Countdown Timer Flow
8. WeChat Integration Points
9. Complete Player Journey
10. Lives Over Time (example scenario)

**Read this if:** You prefer visual diagrams over text explanations

---

### 5. **POINTS_SYSTEM_INDEX.md** (This File!)
**Best for:** Navigation and understanding what exists where

**Contains:**
- Overview of all documentation
- Quick navigation by topic
- Search guide
- Related code file references

---

## 🎯 Quick Navigation by Topic

### I want to understand...

**The Lives Economy**
- → SUMMARY.md → "The Complete Points/Lives Flow"
- → QUICK_REFERENCE.md → "Economy Balance"
- → GAME_ANALYSIS.md → Section 1 & 2

**How to Earn Lives**
- → SUMMARY.md → "EARNING Lives table"
- → QUICK_REFERENCE.md → "How Lives Are Earned"
- → POINTS_FLOW_DIAGRAM.md → "Complete Player Journey"

**How to Spend Lives**
- → SUMMARY.md → "SPENDING Lives table"
- → QUICK_REFERENCE.md → "How Lives Are Spent"
- → GAME_ANALYSIS.md → Section 7 "Hint/Clue System"

**Level Progression**
- → SUMMARY.md → "Level Progression System"
- → QUICK_REFERENCE.md → "Level Progression"
- → GAME_ANALYSIS.md → Section 2
- → POINTS_FLOW_DIAGRAM.md → "Level Progression & Persistence"

**Data Storage**
- → SUMMARY.md → "Data Persistence"
- → QUICK_REFERENCE.md → "Storage Schema"
- → GAME_ANALYSIS.md → Section 2 "Storage & Persistence"
- → POINTS_FLOW_DIAGRAM.md → "Data Persistence"

**API Integration**
- → SUMMARY.md → "API Integration"
- → GAME_ANALYSIS.md → Section 3 & 4
- → POINTS_FLOW_DIAGRAM.md → "API & Level Data Flow"

**WeChat Integration**
- → SUMMARY.md → "WeChat Integration"
- → GAME_ANALYSIS.md → Section 9
- → POINTS_FLOW_DIAGRAM.md → "WeChat Integration Points"

**Complete Gameplay Flow**
- → SUMMARY.md → "Gameplay Loop"
- → GAME_ANALYSIS.md → Section 4 & 5 & 6
- → POINTS_FLOW_DIAGRAM.md → "Gameplay Phase"

**Testing/Validation**
- → SUMMARY.md → "Testing Scenarios"
- → QUICK_REFERENCE.md → Check "What's NOT implemented" section

---

## 📖 Code References

### Core Files & What They Do

**StorageManager.ts** (Lives + Progress)
- `getLives()` / `setLives()` / `consumeLife()` / `addLife()`
- `getCurrentLevelIndex()` / `onLevelCompleted()`
- Referenced in: GAME_ANALYSIS §2, SUMMARY "Data Persistence"

**PageLevel.ts** (Main Gameplay)
- `onUnlockClue()` / `onSubmitAnswer()` / `showSuccess()` / `showError()`
- `startCountdown()` / `onCountdownTick()`
- Referenced in: GAME_ANALYSIS §4-7, SUMMARY "Gameplay Loop"

**LevelDataManager.ts** (API + Caching)
- `initialize()` / `ensureLevelReady()` / `preloadNextLevel()`
- Referenced in: GAME_ANALYSIS §3, SUMMARY "API Integration"

**PassModal.ts** (Victory Screen)
- Victory UI and rewards display
- Referenced in: GAME_ANALYSIS §5

**WxSDK.ts** (WeChat Integration)
- `shareAppMessage()` / `vibrateLong()` / etc.
- Referenced in: GAME_ANALYSIS §9

**ViewManager.ts** (Page Navigation)
- Page stack management
- Referenced in: GAME_ANALYSIS §10

---

## 🔑 Key Numbers & Values

| Item | Value | Reference |
|------|-------|-----------|
| Default Lives | 10 | QUICK_REFERENCE, SUMMARY |
| Min Lives | 0 | QUICK_REFERENCE, SUMMARY |
| Hint Cost | 1 life each | QUICK_REFERENCE, SUMMARY |
| Win Reward | 1 life | QUICK_REFERENCE, SUMMARY |
| Level Time | 60 seconds | QUICK_REFERENCE, SUMMARY |
| API Timeout | 8000ms | QUICK_REFERENCE, GAME_ANALYSIS §3 |
| API Retries | 2 attempts | QUICK_REFERENCE, GAME_ANALYSIS §3 |

---

## 🧩 How Systems Interact

```
StorageManager (Lives + Progress)
    ↓
PageLevel (Gameplay)
    ├─ Uses Lives for: Hint Unlocks
    ├─ Updates Lives on: Level Complete
    ├─ Uses Progress for: Level Selection
    └─ Updates Progress on: Level Complete
    ↓
LevelDataManager (API + Cache)
    ├─ Fetches: Level Data + Images
    └─ Serves: Hints + Answers + Images to PageLevel
    ↓
WxSDK (WeChat)
    ├─ Shares: Victory with Level Param
    └─ Vibrates: On Error
    ↓
ViewManager (Navigation)
    └─ Manages: Page Stack + State
```

---

## ✅ Document Completeness Checklist

- [x] Lives earning mechanics
- [x] Lives spending mechanics
- [x] Level progression system
- [x] Hint/clue system
- [x] API integration
- [x] Data persistence
- [x] WeChat features
- [x] Gameplay loop
- [x] Win/lose conditions
- [x] User journey examples
- [x] Flow diagrams
- [x] Code references
- [x] Constants & values
- [x] Error handling
- [x] Performance optimizations
- [x] Missing features list
- [x] Testing scenarios

**Coverage:** 100% of points/lives/score system

---

## 🚀 Using This Documentation

### For Understanding
1. Start with SUMMARY.md (5 min read)
2. Read QUICK_REFERENCE.md (3 min read)
3. Review POINTS_FLOW_DIAGRAM.md (5 min read)
4. Deep dive into GAME_ANALYSIS.md (15 min read)

### For Maintenance
- QUICK_REFERENCE.md is your quick lookup
- GAME_ANALYSIS.md has implementation details
- Code references show where logic lives

### For Modifications
- "Data Persistence" section for storage changes
- "Lives Transaction Flow" for economy tweaks
- "Constants" section for balance adjustments
- Individual sections in GAME_ANALYSIS for specific systems

---

## ❓ FAQ

**Q: Where is the lives starting value defined?**  
A: `StorageManager.ts` line 25, `DEFAULT_LIVES = 10`

**Q: How do players earn lives?**  
A: By completing levels correctly. See SUMMARY.md "Earning Lives"

**Q: Can players lose lives?**  
A: Only by unlocking hints (-1 each). Wrong answers don't penalize. See SUMMARY.md "Spending Lives"

**Q: Where is progress stored?**  
A: Browser localStorage under keys "game_lives" and "game_progress". See POINTS_FLOW_DIAGRAM.md "Data Persistence"

**Q: What happens when time runs out?**  
A: Game plays fail sound but doesn't end. Players can still submit. See GAME_ANALYSIS.md Section 6

**Q: How does the hint system work?**  
A: Hint 1 is free, Hints 2 & 3 cost 1 life each. See GAME_ANALYSIS.md Section 7

**Q: Is there backend sync?**  
A: No. Progress is local-only. See SUMMARY.md "Missing Features"

---

## 📞 Document Metadata

| Property | Value |
|----------|-------|
| Total Files Analyzed | 21 TypeScript files |
| Total Lines of Code | ~2,500 lines |
| Documentation Generated | 4 files, ~45KB |
| Coverage | Complete (100%) |
| Last Updated | April 5, 2026 |
| Scope | Points/Lives/Score System |

---

## 🎓 Summary of Key Takeaways

1. **Currency:** LIVES (renewable resource), not points
2. **Starting:** 10 lives for new players
3. **Economy:** +1 life per win, -1 per hint unlock
4. **Storage:** localStorage (persistent, survives app close)
5. **API:** Fetches level data on app start, cached in memory
6. **Progression:** Sequential level unlocking with level 1 always available
7. **Strategy:** No penalties for wrong answers, encourages replayability
8. **WeChat:** Sharing with level referral parameter
9. **Scope:** No backend sync, no authentication, local-only progress
10. **Design:** Simple, effective, encourages skill-based progression

---

**Questions?** All answers are in one of these 4 documentation files!