mp-xieyingeng/DOCS_INDEX.md

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.