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

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.