# Documentation Index

This directory contains comprehensive analysis of the mp-xieyingeng (写英语) Cocos Creator game point/score system.

## 📚 Documentation Files

### 1. **GAME_ANALYSIS.md** (19 KB) - COMPREHENSIVE ANALYSIS
The complete technical analysis of the game's point and score system. **Start here for complete understanding.**

**Contents:**
- PART 1: Points/Asset System (Lives currency)
- PART 2: Level Completion & Rewards (+1 life per pass)
- PART 3: Hint/Clue System (Costs 1 life each)
- PART 4: Game Play Logic (Answer validation, timing)
- PART 5: Loading Page Logic (Initialization flow)
- PART 6: API & Network Requests (Backend endpoint)
- PART 7: User Data Storage (localStorage schema)
- PART 8: WeChat Mini-Game SDK Usage
- PART 9: Complete Game Flow Diagram
- PART 10: Complete Resource Flow
- PART 11: Key Observations & Implementation Gaps
- PART 12: Network Architecture
- Summary table of all features

### 2. **QUICK_REFERENCE.md** (8.6 KB) - QUICK LOOKUP GUIDE
Fast reference guide for developers. Use this for quick lookups.

**Contents:**
- Core Currency Overview (Lives system)
- Flow Charts (Life economics, answer submission, app startup)
- Data Structures (localStorage, API response)
- Key Functions & Methods
- Missing Features & Implementation Gaps
- Network Calls Summary
- Game Loop Per Level
- Data Integrity Notes
- WeChat Features Status
- Extension Ideas (Easy/Medium/Complex)

### 3. **ARCHITECTURE.md** (26 KB) - SYSTEM DESIGN
Detailed architecture diagrams and system design documentation.

**Contents:**
- System Architecture Diagram (layered view)
- Data Flow Diagram (complete user session)
- State Management Flow
- View Stack & Navigation
- Class Hierarchy
- Dependency Graph
- Performance Considerations
- Security Considerations & Vulnerabilities

## 🎯 Quick Navigation

### "I want to understand..."

**...how the point system works**
→ Read: QUICK_REFERENCE.md "THE COMPLETE PICTURE"

**...the complete game flow**
→ Read: GAME_ANALYSIS.md "PART 9: Complete Game Flow Diagram"

**...how lives are stored and managed**
→ Read: GAME_ANALYSIS.md "PART 1: Points/Asset System" + PART 7: User Data Storage"

**...what happens when a user completes a level**
→ Read: GAME_ANALYSIS.md "PART 2: Level Completion & Rewards"

**...how hints work**
→ Read: GAME_ANALYSIS.md "PART 3: Hint/Clue System"

**...the API integration**
→ Read: GAME_ANALYSIS.md "PART 6: API & Network Requests"

**...the code organization**
→ Read: ARCHITECTURE.md "System Architecture Diagram" + "Dependency Graph"

**...what's missing in the implementation**
→ Read: GAME_ANALYSIS.md "PART 11: Key Observations & Gaps"

**...where to add new features**
→ Read: QUICK_REFERENCE.md "EXTENSION IDEAS"

---

## 🔑 Key Findings Summary

### THE POINT SYSTEM
- **Currency**: Lives (生命值)
- **Default**: 10 lives
- **Earn**: +1 per level pass
- **Spend**: -1 per hint unlock (Hint 2 or 3 only)
- **Storage**: localStorage under key `game_lives`
- **No other currency**: No points, coins, or score counter

### LEVEL COMPLETION
- **Reward**: +1 life (only reward)
- **No time bonus**: Same reward regardless of speed
- **No partial credit**: Exact case-sensitive match required
- **Unlimited retries**: Can retry wrong answers indefinitely
- **Timeout incomplete**: 60s countdown exists but doesn't prevent submission

### HINT SYSTEM
- **Hint 1**: Free (always shown)
- **Hint 2**: Costs 1 life (unlock button)
- **Hint 3**: Costs 1 life (unlock button)
- **Max loss per level**: 2 lives (both hints)
- **Net per level**: -1 to +1 depending on hints used

### DATA STORAGE
- **Lives**: localStorage["game_lives"]
- **Progress**: localStorage["game_progress"] with currentLevelIndex & maxUnlockedLevelIndex
- **All local**: No server-side sync
- **No encryption**: Direct access via console
- **Immediate writes**: Each update written to storage immediately

### API INTEGRATION
- **Single endpoint**: GET https://ilookai.cn/api/v1/wechat-game/levels
- **Startup only**: Called once during initialization
- **Retry**: 2 attempts with 1s delay
- **Timeout**: 8 seconds
- **No other backend calls**: No score submission, no analytics, no leaderboard

### WECHAT FEATURES
- ✅ Sharing (with level parameter)
- ✅ Haptic feedback (vibration on errors)
- ❌ No authentication
- ❌ No cloud save
- ❌ No leaderboard

---

## 📁 Source Files Referenced

All 16 TypeScript files in the project are analyzed:

**Core Pages:**
- `PageLoading.ts` - Loading screen & initialization
- `PageHome.ts` - Home menu page
- `PageLevel.ts` - Main game level (where all game logic happens)
- `PassModal.ts` - Level completion modal

**Management Systems:**
- `ViewManager.ts` - Page navigation & lifecycle
- `StorageManager.ts` - Lives & progress persistence
- `LevelDataManager.ts` - API integration & asset loading

**Utilities:**
- `BaseView.ts` - Base class for pages
- `HttpUtil.ts` - HTTP request wrapper
- `WxSDK.ts` - WeChat SDK integration
- `ToastManager.ts` - Toast notifications
- `Toast.ts` - Toast component
- `LevelTypes.ts` - TypeScript interfaces
- `RoundedRectMask.ts` - UI utility
- `BackgroundScaler.ts` - UI utility
- `main.ts` - App entry point

---

## 🔬 Analysis Methodology

This documentation was created by:
1. Finding all 16 TypeScript files in the assets/ directory
2. Reading and analyzing each file for:
   - Score/points logic
   - Currency/asset management
   - Level completion mechanics
   - Hint/cost systems
   - API calls
   - Storage mechanisms
   - WeChat SDK usage
   - Data flows
3. Mapping dependencies between files
4. Creating flowcharts and diagrams
5. Documenting observations and gaps

---

## 🚀 Using This Documentation

### For Understanding the System
1. Start with QUICK_REFERENCE.md for overview
2. Read GAME_ANALYSIS.md for detailed understanding
3. Refer to ARCHITECTURE.md for system design

### For Making Changes
1. Check ARCHITECTURE.md "Dependency Graph"
2. Review relevant code sections in GAME_ANALYSIS.md
3. Use QUICK_REFERENCE.md to find specific methods

### For Adding Features
1. Review QUICK_REFERENCE.md "EXTENSION IDEAS"
2. Check ARCHITECTURE.md "Security Considerations"
3. Plan changes against current dependencies

### For Debugging
1. Review GAME_ANALYSIS.md "PART 9: Game Flow Diagram"
2. Check ARCHITECTURE.md "Data Flow Diagram"
3. Trace through StorageManager and LevelDataManager

---

## ⚠️ Important Notes

### Security Issues
- ⚠️ All data stored locally without encryption
- ⚠️ No server-side validation of progress
- ⚠️ Users can modify localStorage directly
- ⚠️ Can skip levels by editing progress

### Implementation Gaps
- ❌ No points/coins display
- ❌ No time-based bonuses
- ❌ Timeout doesn't prevent submission
- ❌ No server-side progress sync
- ❌ No analytics tracking

### To Improve
- Add server-side progress validation
- Implement user authentication
- Add score API endpoint
- Track time-to-completion
- Consider leaderboard system

---

## 📝 Document Versions

- Created: April 5, 2026
- Cocos Creator Version: 3.8.8
- Project: mp-xieyingeng (写英语)
- Platform: WeChat Mini-Game
- Analysis Coverage: 100% of TypeScript codebase (16 files)

---

## 📞 Questions Answered

This documentation answers:
- ✅ What is the points/score system?
- ✅ How do users earn points?
- ✅ How are points spent?
- ✅ What happens on level completion?
- ✅ How do hints work and cost lives?
- ✅ Where is data stored?
- ✅ What API calls are made?
- ✅ How does WeChat integration work?
- ✅ What's the complete game flow?
- ✅ What features are missing?
- ✅ What's the system architecture?
- ✅ Where are the security issues?

---

## 🔗 Cross-References

| Topic | Main Document | Quick Ref | Architecture |
|-------|---------------|-----------|--------------|
| Lives System | PART 1 | Overview | State Mgmt |
| Level Rewards | PART 2 | Economics | Data Flow |
| Hints & Costs | PART 3 | Game Loop | Dependencies |
| API | PART 6 | Network | External |
| Storage | PART 7 | Data Structures | State Mgmt |
| WeChat | PART 8 | Features | Dependencies |
| Game Flow | PART 9 | Game Loop | Data Flow |
| Features | PART 11 | Missing | Performance |

---

## 📊 Statistics

- **TypeScript Files Analyzed**: 16
- **Lines of Code Reviewed**: ~1,800
- **API Endpoints**: 1
- **Storage Keys**: 2
- **External SDKs**: 1 (WeChat)
- **Currency Types**: 1 (Lives)
- **Hint Levels**: 3
- **Levels Supported**: 100+ (from API)
- **Player Lives**: 10 (default)
- **Time Per Level**: 60 seconds
- **Max Hint Cost Per Level**: 2 lives
- **Max Life Gain Per Level**: 1 life

---

**For questions or clarifications, refer to the specific document sections listed above.**