feat: 进入关卡时 toast 提示体力消耗，修复 StorageManager 接口位置和 WxSDK 访问级别
- 进入关卡成功后显示 toast 提示消耗体力及剩余体力 - 将 StorageManager 中 UserInfo 接口移至模块顶层，修复嵌套接口语法问题 - WxSDK.getWx() 改为 static 公开方法，便于外部调用
This commit is contained in:
richarjiang
665
ARCHITECTURE_DIAGRAM.md
Normal file
665
ARCHITECTURE_DIAGRAM.md
Normal file
@@ -0,0 +1,665 @@
|
|||||||
|
# Architecture & Flow Diagrams
|
||||||
|
|
||||||
|
## System Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Cocos Creator Runtime │
|
||||||
|
├─────────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ UI Layer (This Analysis) │ │
|
||||||
|
│ ├──────────────────────────────────────────────────────────┤ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ ┌────────────────┐ ┌──────────────┐ │ │
|
||||||
|
│ │ │ main.ts │────────▶│ ViewManager │ │ │
|
||||||
|
│ │ │ (Bootstrap) │ │ (Singleton) │ │ │
|
||||||
|
│ │ └────────────────┘ └──────────────┘ │ │
|
||||||
|
│ │ │ │ │
|
||||||
|
│ │ Pages (All extend BaseView): │ │ │
|
||||||
|
│ │ ┌─────────────────────────────────┼──────────────┐ │ │
|
||||||
|
│ │ │ • PageLoading (init data) │ │ │ │
|
||||||
|
│ │ │ • PageHome (hub) │ │ │ │
|
||||||
|
│ │ │ • PageLevel (game - complex) ◀┘ │ │ │
|
||||||
|
│ │ │ • PagePreviewLevels (list) │ │ │
|
||||||
|
│ │ │ • PassModal (modal) │ │ │
|
||||||
|
│ │ └────────────────────────────────────────────────┘ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ ┌────────────────┐ ┌──────────────┐ │ │
|
||||||
|
│ │ │ ToastManager │────────▶│ Toast │ │ │
|
||||||
|
│ │ │ (Singleton) │ │ (Component) │ │ │
|
||||||
|
│ │ └────────────────┘ └──────────────┘ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ └──────────────────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ Data Layer (External - Not Analyzed) │ │
|
||||||
|
│ ├──────────────────────────────────────────────────────────┤ │
|
||||||
|
│ │ • AuthManager • LevelDataManager │ │
|
||||||
|
│ │ • StorageManager • UserAssetsManager │ │
|
||||||
|
│ │ • ShareManager • WxSDK │ │
|
||||||
|
│ └──────────────────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Page State Machine
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────┐
|
||||||
|
│ Application Starts │
|
||||||
|
└──────────────┬──────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌──────────────────────┐
|
||||||
|
│ main.onLoad() │
|
||||||
|
│ Registers all pages │
|
||||||
|
└──────────┬───────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌──────────────────────────────┐
|
||||||
|
│ PageLoading displayed │
|
||||||
|
│ - Load auth + levels │
|
||||||
|
│ - Sync progress │
|
||||||
|
│ - Check share code │
|
||||||
|
└──────────────┬───────────────┘
|
||||||
|
│
|
||||||
|
┌──────────────┴──────────────┐
|
||||||
|
│ Normal Mode │ Share Mode │
|
||||||
|
▼ ▼ │
|
||||||
|
┌──────────────────┐ ┌───────────────┐ │
|
||||||
|
│ PageHome │ │ PageLevel │ │
|
||||||
|
│ [Start] [PK] │ │ (in share) │ │
|
||||||
|
└────┬─────┬───────┘ └───────┬───────┘ │
|
||||||
|
│ │ │ │
|
||||||
|
┌────────▼─┐ └────────────┬──────┴────────┘
|
||||||
|
│ │ │
|
||||||
|
▼ ▼ ▼
|
||||||
|
PageLevel PageWrite (Repeat levels)
|
||||||
|
(game) Levels │
|
||||||
|
│ (create) ▼
|
||||||
|
│ │ PassModal
|
||||||
|
│ ▼ [Share]
|
||||||
|
│ PagePreview │
|
||||||
|
│ Levels ▼
|
||||||
|
│ (verify) Back to Home
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ PassModal
|
||||||
|
│ [Next/Share]
|
||||||
|
│ │
|
||||||
|
└──────────┼─────────┐
|
||||||
|
│ │
|
||||||
|
┌────▼──┐ ┌───▼────┐
|
||||||
|
│ Next │ │ Share │
|
||||||
|
│ Loop │ │ to WX │
|
||||||
|
└───────┘ └────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Page Stack Visualization
|
||||||
|
|
||||||
|
### Session Trace
|
||||||
|
|
||||||
|
```
|
||||||
|
INITIALIZATION:
|
||||||
|
┌────────────────────────────────────────────┐
|
||||||
|
│ Stack: [] │
|
||||||
|
│ (Nothing loaded yet) │
|
||||||
|
└────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼ main.onLoad()
|
||||||
|
┌────────────────────────────────────────────┐
|
||||||
|
│ Stack: [] │
|
||||||
|
│ ViewManager + pages registered in registry │
|
||||||
|
└────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼ PageLoading.start() → ViewManager.open('PageHome')
|
||||||
|
┌────────────────────────────────────────────┐
|
||||||
|
│ Stack: [PageHome] │
|
||||||
|
│ PageHome._doShow() called │
|
||||||
|
└────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
USER CLICKS "START GAME":
|
||||||
|
▼ PageHome._onStartGameClick() → ViewManager.open('PageLevel')
|
||||||
|
┌────────────────────────────────────────────┐
|
||||||
|
│ Stack: [PageHome, PageLevel] │
|
||||||
|
│ PageHome._doHide() called │
|
||||||
|
│ PageLevel._doShow() called │
|
||||||
|
└────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
COMPLETES LEVEL:
|
||||||
|
▼ PageLevel shows PassModal (not in stack, drawn on top)
|
||||||
|
┌────────────────────────────────────────────┐
|
||||||
|
│ Stack: [PageHome, PageLevel] │
|
||||||
|
│ UI Layer: [PageLevel, PassModal@z999] │
|
||||||
|
│ PassModal shown with instantiate() │
|
||||||
|
└────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
CLICKS "NEXT LEVEL":
|
||||||
|
▼ PassModal closed, PageLevel.nextLevel()
|
||||||
|
┌────────────────────────────────────────────┐
|
||||||
|
│ Stack: [PageHome, PageLevel] │
|
||||||
|
│ PageLevel loads next level config │
|
||||||
|
│ PassModal destroyed │
|
||||||
|
└────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
CLICKS BACK FROM PageLevel:
|
||||||
|
▼ PageLevel.onIconSettingClick() → ViewManager.back()
|
||||||
|
┌────────────────────────────────────────────┐
|
||||||
|
│ Stack: [PageHome] │
|
||||||
|
│ PageLevel._doHide() called │
|
||||||
|
│ PageLevel destroyed (cache=true, not kept) │
|
||||||
|
│ PageHome._doShow() called │
|
||||||
|
└────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Component Communication Diagram
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────┐
|
||||||
|
│ ViewManager │
|
||||||
|
│ (Singleton) │
|
||||||
|
└──────────┬──────────┘
|
||||||
|
│
|
||||||
|
┌──────────────┼──────────────┐
|
||||||
|
│ │ │
|
||||||
|
▼ ▼ ▼
|
||||||
|
open() back() replace()
|
||||||
|
│ │ │
|
||||||
|
│ │ │
|
||||||
|
┌───────────┴────┐ ┌───┴────┐ ┌──┴───────┐
|
||||||
|
│ │ │ │ │ │
|
||||||
|
▼ ▼ ▼ ▼ ▼ ▼
|
||||||
|
PageHome PageLevel PassModal (back) (new page)
|
||||||
|
│ │ │
|
||||||
|
│ ├─ Timer ────┐
|
||||||
|
│ │ │
|
||||||
|
│ ├─ Points │
|
||||||
|
│ │ ↑ │
|
||||||
|
│ │ │ │
|
||||||
|
▼ ▼ │ ▼
|
||||||
|
ToastMgr Hints │ PassModal
|
||||||
|
│ │ │
|
||||||
|
├──────┤ └──▶ Share to WX
|
||||||
|
│ │
|
||||||
|
Unlock Earn Points
|
||||||
|
Consume (UserAssets)
|
||||||
|
(check hasPoints)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data Flow: Level Completion
|
||||||
|
|
||||||
|
```
|
||||||
|
USER ENTERS ANSWER:
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ PageLevel.onSubmitAnswer() │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
├─ getAnswer() ──▶ [Retrieve from EditBox]
|
||||||
|
│
|
||||||
|
├─ Compare with _currentConfig.answer
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌────────────────────────────────────────┐
|
||||||
|
│ CORRECT ANSWER │
|
||||||
|
└────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
├─ _isTransitioning = true [Prevent double-submit]
|
||||||
|
│
|
||||||
|
├─ stopCountdown()
|
||||||
|
│
|
||||||
|
├─ playSuccessSound()
|
||||||
|
│
|
||||||
|
├─ Calculate: timeSpent = 60 - _countdown
|
||||||
|
│
|
||||||
|
├─┐ Normal Mode:
|
||||||
|
│ │
|
||||||
|
│ └─▶ UserAssetsManager.earnPoint(levelId, timeSpent)
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ └─ UPDATE SERVER + LOCAL
|
||||||
|
│ └─ Get points amount
|
||||||
|
│ └─ PageLevel.updatePointsLabel()
|
||||||
|
│
|
||||||
|
├─┐ Share Mode:
|
||||||
|
│ │
|
||||||
|
│ └─▶ ShareManager.reportLevelProgress(...)
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ └─ SEND TO SERVER (fire-and-forget)
|
||||||
|
│
|
||||||
|
├─ _showPassModal()
|
||||||
|
│ │
|
||||||
|
│ ├─ instantiate(passModalPrefab)
|
||||||
|
│ │
|
||||||
|
│ ├─ Set z-index = 999 (topmost)
|
||||||
|
│ │
|
||||||
|
│ ├─ Add to Canvas
|
||||||
|
│ │
|
||||||
|
│ └─ Call passModal.onViewLoad() + onViewShow()
|
||||||
|
│
|
||||||
|
└─ WAIT FOR USER:
|
||||||
|
│
|
||||||
|
├─ [Next Level] ──▶ PassModal closed
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ nextLevel()
|
||||||
|
│ │
|
||||||
|
│ ┌────────┴────────┐
|
||||||
|
│ │ No More Levels │ Next Level
|
||||||
|
│ ▼ ▼
|
||||||
|
│ BACK HOME Load & Display
|
||||||
|
│ Restart Timer
|
||||||
|
│
|
||||||
|
└─ [Share] ──▶ WxSDK.shareAppMessage()
|
||||||
|
│
|
||||||
|
└─ Modal stays open
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Hint Unlocking Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
USER CLICKS UNLOCK BUTTON:
|
||||||
|
┌──────────────────────────────────────────────┐
|
||||||
|
│ PageLevel.onUnlockClue(index: 2 or 3) │
|
||||||
|
└──────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
├─ Check: _isUnlocking == true?
|
||||||
|
│ └─ YES: Return immediately (prevent double-click)
|
||||||
|
│ └─ NO: Continue
|
||||||
|
│
|
||||||
|
├─ Check: StorageManager.hasPoints()?
|
||||||
|
│ └─ NO: Show toast "积分不足！"
|
||||||
|
│ └─ YES: Continue
|
||||||
|
│
|
||||||
|
├─ Set: _isUnlocking = true
|
||||||
|
│
|
||||||
|
├─ await UserAssetsManager.consumePoint(levelId, index)
|
||||||
|
│ │
|
||||||
|
│ ├─ ASYNC: Contact server/storage
|
||||||
|
│ │
|
||||||
|
│ └─ Returns: success boolean
|
||||||
|
│
|
||||||
|
├─ If success:
|
||||||
|
│ │
|
||||||
|
│ ├─ updatePointsLabel()
|
||||||
|
│ │
|
||||||
|
│ ├─ playClickSound()
|
||||||
|
│ │
|
||||||
|
│ ├─ hideUnlockButton(index)
|
||||||
|
│ │
|
||||||
|
│ ├─ showClue(index)
|
||||||
|
│ │
|
||||||
|
│ └─ setClue(index, config.clueN)
|
||||||
|
│
|
||||||
|
├─ If failed:
|
||||||
|
│ │
|
||||||
|
│ └─ Show toast "积分不足！"
|
||||||
|
│
|
||||||
|
└─ Finally: _isUnlocking = false
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Timer Sequence Diagram
|
||||||
|
|
||||||
|
```
|
||||||
|
Timeline: 1s 2s 3s ... 59s 60s 61s
|
||||||
|
│ │ │ │ │ │
|
||||||
|
▼ ▼ ▼ ▼ ▼ ▼
|
||||||
|
countdown: 60 59 58 1 0 (ended)
|
||||||
|
│ │ │ │ │
|
||||||
|
display: "60s" "59s" "58s" ......... "1s" "0s"
|
||||||
|
│ │ │ │ │
|
||||||
|
▼ ▼ ▼ ▼ ▼
|
||||||
|
|
||||||
|
LEVEL LOAD:
|
||||||
|
│
|
||||||
|
└─ startCountdown()
|
||||||
|
│
|
||||||
|
├─ _countdown = 60
|
||||||
|
├─ _isTimeUp = false
|
||||||
|
└─ schedule(onCountdownTick, 1.0) [Repeat every 1 sec]
|
||||||
|
│
|
||||||
|
▼ (Every 1 second)
|
||||||
|
onCountdownTick()
|
||||||
|
│
|
||||||
|
├─ if (_isTimeUp) return
|
||||||
|
│
|
||||||
|
├─ _countdown-- (60→59→58...→0)
|
||||||
|
│
|
||||||
|
├─ updateClockLabel() [Display: "59s"]
|
||||||
|
│
|
||||||
|
└─ if (_countdown <= 0):
|
||||||
|
│
|
||||||
|
├─ _isTimeUp = true
|
||||||
|
│
|
||||||
|
├─ stopCountdown()
|
||||||
|
│ └─ unschedule(onCountdownTick)
|
||||||
|
│
|
||||||
|
└─ onTimeUp()
|
||||||
|
│
|
||||||
|
└─ playFailSound()
|
||||||
|
|
||||||
|
ANSWER SUBMITTED (Correct):
|
||||||
|
│
|
||||||
|
└─ showSuccess()
|
||||||
|
│
|
||||||
|
├─ stopCountdown()
|
||||||
|
│ └─ Timer stops, no more ticks
|
||||||
|
│
|
||||||
|
└─ _showPassModal()
|
||||||
|
|
||||||
|
OR:
|
||||||
|
|
||||||
|
ANSWER SUBMITTED (Wrong):
|
||||||
|
│
|
||||||
|
└─ Timer continues running...
|
||||||
|
│
|
||||||
|
└─ User keeps playing
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Input Box Creation & Management
|
||||||
|
|
||||||
|
```
|
||||||
|
LEVEL LOADS:
|
||||||
|
│
|
||||||
|
└─ _applyLevelConfig(config)
|
||||||
|
│
|
||||||
|
└─ createSingleInput(config.answer.length)
|
||||||
|
│
|
||||||
|
├─ clearInputNodes()
|
||||||
|
│ │
|
||||||
|
│ └─ Destroy old input nodes
|
||||||
|
│ (If level changed)
|
||||||
|
│
|
||||||
|
├─ Hide inputTemplate
|
||||||
|
│
|
||||||
|
├─ instantiate(inputTemplate)
|
||||||
|
│
|
||||||
|
├─ Set properties:
|
||||||
|
│ │
|
||||||
|
│ ├─ active = true
|
||||||
|
│ ├─ name = 'singleInput'
|
||||||
|
│ ├─ position = (0, 0, 0)
|
||||||
|
│ │
|
||||||
|
│ └─ Get EditBox component
|
||||||
|
│ │
|
||||||
|
│ ├─ placeholder = "(Xlength个字)"
|
||||||
|
│ ├─ maxLength = answerLength
|
||||||
|
│ ├─ string = ""
|
||||||
|
│ │
|
||||||
|
│ └─ Listen events:
|
||||||
|
│ ├─ TEXT_CHANGED → onInputTextChanged()
|
||||||
|
│ └─ EDITING_DID_ENDED → onInputEditingEnded()
|
||||||
|
│
|
||||||
|
├─ Calculate width:
|
||||||
|
│ └─ Math.min(600, Math.max(200, length*60+40))
|
||||||
|
│
|
||||||
|
├─ Set UITransform contentSize to width x 100
|
||||||
|
│
|
||||||
|
├─ Adjust underline width to match
|
||||||
|
│
|
||||||
|
├─ Add to inputLayout
|
||||||
|
│
|
||||||
|
└─ Store in _inputNodes[0]
|
||||||
|
|
||||||
|
USER ENTERS TEXT:
|
||||||
|
│
|
||||||
|
├─ EditBox updates string property
|
||||||
|
└─ TEXT_CHANGED event fires
|
||||||
|
|
||||||
|
USER SUBMITS:
|
||||||
|
│
|
||||||
|
├─ getAnswer()
|
||||||
|
│ │
|
||||||
|
│ └─ _inputNodes[0].getComponent(EditBox).string.trim()
|
||||||
|
│
|
||||||
|
└─ Compare with config.answer
|
||||||
|
|
||||||
|
USER NAVIGATES AWAY:
|
||||||
|
│
|
||||||
|
└─ onViewDestroy() → clearInputNodes()
|
||||||
|
│
|
||||||
|
└─ Destroy all input nodes
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Share Challenge Mode Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
LAUNCH FROM WeChat LINK:
|
||||||
|
│
|
||||||
|
└─ PageLoading.start()
|
||||||
|
│
|
||||||
|
└─ _startPreload()
|
||||||
|
│
|
||||||
|
├─ Initialize auth + levels (parallel)
|
||||||
|
│
|
||||||
|
├─ WxSDK.getShareCodeFromLaunch()
|
||||||
|
│ │
|
||||||
|
│ └─ Extract from wx.getLaunchOptionsSync().query
|
||||||
|
│
|
||||||
|
├─ if shareCode exists AND loginSuccess:
|
||||||
|
│ │
|
||||||
|
│ └─ ShareManager.instance.joinShare(shareCode)
|
||||||
|
│ │
|
||||||
|
│ ├─ ASYNC: Fetch share session from server
|
||||||
|
│ │
|
||||||
|
│ ├─ Get shared level set
|
||||||
|
│ │
|
||||||
|
│ └─ Return: success boolean
|
||||||
|
│
|
||||||
|
├─ if (joinSuccess):
|
||||||
|
│ │
|
||||||
|
│ ├─ Set progress = 1
|
||||||
|
│ │
|
||||||
|
│ ├─ ViewManager.open('PageLevel', {
|
||||||
|
│ │ params: { shareMode: true }
|
||||||
|
│ │ })
|
||||||
|
│ │
|
||||||
|
│ └─ Destroy self (PageLoading)
|
||||||
|
│
|
||||||
|
└─ else (normal flow)
|
||||||
|
│
|
||||||
|
└─ Preload PageHome → Open PageHome
|
||||||
|
|
||||||
|
IN SHARE MODE (PageLevel):
|
||||||
|
│
|
||||||
|
├─ onViewLoad():
|
||||||
|
│ │
|
||||||
|
│ ├─ params = getParams()
|
||||||
|
│ ├─ _isShareMode = params?.shareMode === true
|
||||||
|
│ │
|
||||||
|
│ ├─ if shareMode:
|
||||||
|
│ │ └─ currentLevelIndex = 0 (start at first)
|
||||||
|
│ │
|
||||||
|
│ └─ initLevel() loads from ShareManager, not LevelDataManager
|
||||||
|
│
|
||||||
|
├─ showSuccess():
|
||||||
|
│ │
|
||||||
|
│ ├─ if normal mode:
|
||||||
|
│ │ └─ earn points
|
||||||
|
│ │
|
||||||
|
│ └─ if share mode:
|
||||||
|
│ │
|
||||||
|
│ └─ ShareManager.reportLevelProgress(levelId, true, timeSpent)
|
||||||
|
│ │
|
||||||
|
│ └─ FIRE-AND-FORGET (no await)
|
||||||
|
│
|
||||||
|
├─ nextLevel():
|
||||||
|
│ │
|
||||||
|
│ ├─ if NOT shareMode:
|
||||||
|
│ │ └─ StorageManager.onLevelCompleted() [Save progress]
|
||||||
|
│ │
|
||||||
|
│ ├─ Check level count:
|
||||||
|
│ │ │
|
||||||
|
│ │ ├─ Share: ShareManager.getShareLevelCount()
|
||||||
|
│ │ └─ Normal: LevelDataManager.getLevelCount()
|
||||||
|
│ │
|
||||||
|
│ ├─ if (allLevelsComplete):
|
||||||
|
│ │ │
|
||||||
|
│ │ ├─ if shareMode:
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ ├─ ShareManager.clearShareMode()
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ └─ ViewManager.replace('PageHome')
|
||||||
|
│ │ │
|
||||||
|
│ │ └─ if normal:
|
||||||
|
│ │ └─ ViewManager.back()
|
||||||
|
│ │
|
||||||
|
│ └─ else (more levels):
|
||||||
|
│ └─ Load next level
|
||||||
|
│
|
||||||
|
└─ Back to PageHome (replaces, clears share state)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ViewManager Caching Mechanism
|
||||||
|
|
||||||
|
```
|
||||||
|
OPEN 'PageHome' (first time):
|
||||||
|
│
|
||||||
|
└─ ViewManager.open('PageHome')
|
||||||
|
│
|
||||||
|
├─ Check cache: _viewCache.get('PageHome')
|
||||||
|
│ └─ Cache miss (undefined)
|
||||||
|
│
|
||||||
|
├─ _instantiateView('PageHome', prefab)
|
||||||
|
│ │
|
||||||
|
│ ├─ instantiate(prefab)
|
||||||
|
│ │
|
||||||
|
│ ├─ Get BaseView component
|
||||||
|
│ │
|
||||||
|
│ ├─ Set viewId, config, params
|
||||||
|
│ │
|
||||||
|
│ ├─ Add to container
|
||||||
|
│ │
|
||||||
|
│ ├─ Call view.onViewLoad() ◄─── Called once
|
||||||
|
│ │
|
||||||
|
│ ├─ if (config.cache === true): ◄─── PageHome has cache:true
|
||||||
|
│ │ └─ _viewCache.set('PageHome', view)
|
||||||
|
│ │
|
||||||
|
│ └─ _showView(view)
|
||||||
|
│ │
|
||||||
|
│ └─ view._doShow()
|
||||||
|
│ └─ view.onViewShow() ◄─── Called now
|
||||||
|
│
|
||||||
|
└─ Stack: [PageHome]
|
||||||
|
|
||||||
|
OPEN 'PageLevel':
|
||||||
|
│
|
||||||
|
└─ ViewManager.open('PageLevel')
|
||||||
|
│
|
||||||
|
├─ PageHome._doHide()
|
||||||
|
│ └─ view.onViewHide() ◄─── First hide
|
||||||
|
│
|
||||||
|
└─ (Same as above for PageLevel)
|
||||||
|
│
|
||||||
|
└─ Stack: [PageHome, PageLevel]
|
||||||
|
|
||||||
|
BACK FROM 'PageLevel':
|
||||||
|
│
|
||||||
|
└─ ViewManager.back()
|
||||||
|
│
|
||||||
|
├─ Pop stack: PageLevel
|
||||||
|
│
|
||||||
|
├─ PageLevel._doHide()
|
||||||
|
│ └─ view.onViewHide()
|
||||||
|
│
|
||||||
|
├─ Decide: shouldDestroy?
|
||||||
|
│ │
|
||||||
|
│ └─ PageLevel has cache:true
|
||||||
|
│ └─ shouldDestroy = false (keep cached)
|
||||||
|
│
|
||||||
|
├─ Get current: PageHome
|
||||||
|
│
|
||||||
|
├─ PageHome._doShow()
|
||||||
|
│ └─ view.onViewShow() ◄─── Called again
|
||||||
|
│
|
||||||
|
└─ Stack: [PageHome]
|
||||||
|
Caches: {PageHome, PageLevel}
|
||||||
|
|
||||||
|
OPEN 'PageLevel' AGAIN (from cache):
|
||||||
|
│
|
||||||
|
└─ ViewManager.open('PageLevel')
|
||||||
|
│
|
||||||
|
├─ Check cache: _viewCache.get('PageLevel')
|
||||||
|
│ └─ Cache hit! (PageLevel instance)
|
||||||
|
│
|
||||||
|
├─ _showView(cachedView)
|
||||||
|
│ │
|
||||||
|
│ ├─ PageHome._doHide()
|
||||||
|
│ │
|
||||||
|
│ └─ cachedView._doShow()
|
||||||
|
│ └─ view.onViewShow() ◄─── Called again (2nd time)
|
||||||
|
│ onViewLoad() NOT called again ◄─── Important!
|
||||||
|
│
|
||||||
|
└─ Stack: [PageHome, PageLevel]
|
||||||
|
Same instance reused
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling Paths
|
||||||
|
|
||||||
|
```
|
||||||
|
LEVEL LOADING ERROR:
|
||||||
|
│
|
||||||
|
├─ initLevel()
|
||||||
|
│ │
|
||||||
|
│ └─ await LevelDataManager.ensureLevelReady(index)
|
||||||
|
│ │
|
||||||
|
│ └─ Returns null (error)
|
||||||
|
│
|
||||||
|
└─ Log warning, return early
|
||||||
|
│
|
||||||
|
└─ UI stays as-is (might be blank)
|
||||||
|
|
||||||
|
INSUFFICIENT POINTS:
|
||||||
|
│
|
||||||
|
└─ onUnlockClue()
|
||||||
|
│
|
||||||
|
├─ StorageManager.hasPoints() → false
|
||||||
|
│
|
||||||
|
└─ ToastManager.show("积分不足！")
|
||||||
|
│
|
||||||
|
└─ User sees notification, unlock blocked
|
||||||
|
|
||||||
|
DOUBLE-SUBMIT PREVENTION:
|
||||||
|
│
|
||||||
|
├─ onSubmitAnswer()
|
||||||
|
│ │
|
||||||
|
│ └─ if (_isTransitioning) return ◄─── Blocks multiple calls
|
||||||
|
│
|
||||||
|
└─ showSuccess()
|
||||||
|
│
|
||||||
|
└─ _isTransitioning = true ◄─── Set to block
|
||||||
|
│
|
||||||
|
└─ After modal shown/closed
|
||||||
|
└─ (Would be reset on nextLevel)
|
||||||
|
|
||||||
|
DOUBLE-CLICK UNLOCK:
|
||||||
|
│
|
||||||
|
└─ onUnlockClue()
|
||||||
|
│
|
||||||
|
└─ if (_isUnlocking) return ◄─── Blocks rapid clicks
|
||||||
|
│
|
||||||
|
└─ _isUnlocking = true at start
|
||||||
|
└─ Finally: _isUnlocking = false ◄─── Reset after async
|
||||||
|
```
|
||||||
|
|
||||||
@@ -1,196 +1,348 @@
|
|||||||
# QUICK REFERENCE - Game Points/Score System
|
# UI Components - Quick Reference Guide
|
||||||
|
|
||||||
## 🎮 What is the "Currency"?
|
## Component Overview
|
||||||
**LIVES** - Not traditional points/coins, but a renewable "health" resource.
|
|
||||||
|
|
||||||
## 📊 Lives Management
|
| Component | Purpose | Extends | Key Responsibilities |
|
||||||
```
|
|-----------|---------|---------|----------------------|
|
||||||
Storage Key: "game_lives" (localStorage)
|
| **main.ts** | App bootstrap | Component | Register pages, init ViewManager & ToastManager |
|
||||||
Default: 10
|
| **PageLoading.ts** | Splash screen | Component | Load data, sync progress, detect share code |
|
||||||
Min Value: 0
|
| **PageHome.ts** | Landing page | BaseView | Navigation hub (game/PK buttons) |
|
||||||
Max Value: ∞ (no limit)
|
| **PageLevel.ts** | Game level | BaseView | Core gameplay (timer, hints, scoring, input) |
|
||||||
|
| **PagePreviewLevels.ts** | Level preview | BaseView | Scrollable list of selected levels |
|
||||||
Methods:
|
| **PassModal.ts** | Completion modal | BaseView | Next level & share buttons, success sound |
|
||||||
├─ getLives() → Returns current lives
|
| **Toast.ts** | Notification | Component | Display message with fade animation |
|
||||||
├─ setLives(n) → Set specific value
|
| **ToastManager.ts** | Toast system | Singleton | Centralized toast creation & display |
|
||||||
├─ consumeLife() → Deduct 1 life
|
| **BaseView.ts** | Page base class | Component | Lifecycle interface for all pages |
|
||||||
├─ addLife() → Add 1 life
|
| **ViewManager.ts** | Page manager | Singleton | Navigation, stacking, caching, lifecycle |
|
||||||
├─ 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`
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
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.
|
## Lifecycle Stages
|
||||||
|
|
||||||
|
### Page Lifecycle (BaseView)
|
||||||
|
```
|
||||||
|
onViewLoad() → onViewShow() → onViewHide() → onViewDestroy()
|
||||||
|
(once) (each show) (each hide) (on destroy)
|
||||||
|
```
|
||||||
|
|
||||||
|
### App Startup Flow
|
||||||
|
```
|
||||||
|
main.onLoad()
|
||||||
|
↓ (Initialize ViewManager + register pages)
|
||||||
|
PageLoading.start()
|
||||||
|
↓ (Load auth + levels in parallel, check share code)
|
||||||
|
PageHome (normal) OR PageLevel (share mode)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Data Flows
|
||||||
|
|
||||||
|
### Level Progression
|
||||||
|
```
|
||||||
|
PageLevel loads config → Displays image + clue1 → User enters answer
|
||||||
|
↓ (correct) → Earn points → Show PassModal → Next level
|
||||||
|
↓ (wrong) → Show toast → Continue playing
|
||||||
|
↓ (timeout) → Play fail sound
|
||||||
|
```
|
||||||
|
|
||||||
|
### Hint Unlocking
|
||||||
|
```
|
||||||
|
User clicks unlock button → Check points available
|
||||||
|
↓ (yes) → Consume point from UserAssetsManager
|
||||||
|
↓ → Hide unlock button, show clue
|
||||||
|
↓ (no) → Show "insufficient points" toast
|
||||||
|
```
|
||||||
|
|
||||||
|
### Share Challenge Mode
|
||||||
|
```
|
||||||
|
WeChat link → PageLoading detects share code
|
||||||
|
↓ → ShareManager.joinShare(code)
|
||||||
|
↓ → Play through shared levels (doesn't save local progress)
|
||||||
|
↓ → Report progress to server
|
||||||
|
↓ → Return to PageHome
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Component Properties Summary
|
||||||
|
|
||||||
|
### PageLevel (Most Complex)
|
||||||
|
**UI Elements:**
|
||||||
|
- inputLayout, submitButton, inputTemplate, actionNode
|
||||||
|
- iconSetting (back button)
|
||||||
|
- tipsLayout, tipsItem1/2/3 (clues)
|
||||||
|
- unLockItem2/3 (unlock buttons)
|
||||||
|
- clockLabel (timer), liveLabel (points)
|
||||||
|
- mainImage (level image)
|
||||||
|
|
||||||
|
**Audio:**
|
||||||
|
- clickAudio, successAudio, failAudio
|
||||||
|
|
||||||
|
**Internal State:**
|
||||||
|
- _countdown (60 sec timer)
|
||||||
|
- _isTimeUp (timer expired flag)
|
||||||
|
- _currentConfig (level data)
|
||||||
|
- _isTransitioning (prevent double-submit)
|
||||||
|
- _isUnlocking (prevent double-click unlock)
|
||||||
|
- _passModalNode (modal reference)
|
||||||
|
- _isShareMode (shared vs normal)
|
||||||
|
|
||||||
|
**Key Methods:**
|
||||||
|
- onViewLoad/Show/Hide/Destroy (lifecycle)
|
||||||
|
- initLevel() (async load config)
|
||||||
|
- createSingleInput(length) (input box)
|
||||||
|
- onUnlockClue(index) (consume points for hints)
|
||||||
|
- onSubmitAnswer() (check answer)
|
||||||
|
- showSuccess() (correct: earn points, show modal)
|
||||||
|
- showError() (wrong: toast + vibration)
|
||||||
|
- nextLevel() (progress to next)
|
||||||
|
- startCountdown() / onCountdownTick() (60s timer)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Points & Scoring System
|
||||||
|
|
||||||
|
**Earning Points:**
|
||||||
|
- `UserAssetsManager.earnPoint(levelId, timeSpent)`
|
||||||
|
- Called in PageLevel.showSuccess()
|
||||||
|
- Time spent = 60 - countdown
|
||||||
|
|
||||||
|
**Consuming Points:**
|
||||||
|
- `UserAssetsManager.consumePoint(levelId, hintIndex)`
|
||||||
|
- Called in PageLevel.onUnlockClue()
|
||||||
|
- Check `StorageManager.hasPoints()` before consuming
|
||||||
|
|
||||||
|
**Displaying Points:**
|
||||||
|
- `StorageManager.getPoints()` → Display as "x {points}"
|
||||||
|
- Called in PageLevel.updatePointsLabel()
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Timer System
|
||||||
|
|
||||||
|
**60-Second Countdown:**
|
||||||
|
- Starts when level loads: `startCountdown()`
|
||||||
|
- Ticks every 1 second: `onCountdownTick()`
|
||||||
|
- Displayed as: "60s", "59s", ..., "0s"
|
||||||
|
- On timeout: plays fail sound, doesn't end game
|
||||||
|
|
||||||
|
**Stop Timer:**
|
||||||
|
- `stopCountdown()` called when:
|
||||||
|
- Answer submitted (correct)
|
||||||
|
- Page destroyed
|
||||||
|
- All levels completed
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Hint/Clue System
|
||||||
|
|
||||||
|
**3 Clues Per Level:**
|
||||||
|
1. **Clue 1** - Always visible (free)
|
||||||
|
2. **Clue 2** - Unlock button, costs points
|
||||||
|
3. **Clue 3** - Unlock button, costs points
|
||||||
|
|
||||||
|
**Display:**
|
||||||
|
- Text in tipsItem1/2/3 nodes
|
||||||
|
- Hidden if locked (tipsItem.active = false)
|
||||||
|
- Unlock button visible if locked
|
||||||
|
|
||||||
|
**Unlock Flow:**
|
||||||
|
1. User clicks unLockItem2 or unLockItem3
|
||||||
|
2. Check points: `StorageManager.hasPoints()`
|
||||||
|
3. Consume: `UserAssetsManager.consumePoint(levelId, index)`
|
||||||
|
4. Hide button, show clue, update UI
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Navigation Stack
|
||||||
|
|
||||||
|
**Structure:**
|
||||||
|
- LIFO stack managed by ViewManager
|
||||||
|
- Each open() adds to stack
|
||||||
|
- back() pops from stack
|
||||||
|
- replace() swaps top
|
||||||
|
|
||||||
|
**Example Session:**
|
||||||
|
```
|
||||||
|
[PageHome]
|
||||||
|
↓ open PageLevel
|
||||||
|
[PageHome, PageLevel]
|
||||||
|
↓ open PassModal (or inline)
|
||||||
|
[PageHome, PageLevel, PassModal?]
|
||||||
|
↓ close/back
|
||||||
|
[PageHome]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Methods:**
|
||||||
|
- `ViewManager.open(viewId, options?)` - Push to stack
|
||||||
|
- `ViewManager.back()` - Pop from stack, show previous
|
||||||
|
- `ViewManager.replace(viewId, options?)` - Pop current, push new
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Caching Strategy
|
||||||
|
|
||||||
|
**Cached Views (default):**
|
||||||
|
- Instance reused on re-open
|
||||||
|
- onViewLoad() called once
|
||||||
|
- onViewShow() called each time
|
||||||
|
- Memory persists
|
||||||
|
|
||||||
|
**Non-Cached Views:**
|
||||||
|
- New instance each time
|
||||||
|
- onViewLoad() called each time
|
||||||
|
- Memory released on close
|
||||||
|
|
||||||
|
**Configuration:**
|
||||||
|
```typescript
|
||||||
|
// In main.ts registration
|
||||||
|
ViewManager.instance.register('PageHome', {
|
||||||
|
prefab: pageHomePrefab,
|
||||||
|
cache: true, // ← Reuse instance
|
||||||
|
zIndex: 0 // ← Layer depth
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Toast System
|
||||||
|
|
||||||
|
**Show Toast:**
|
||||||
|
```typescript
|
||||||
|
ToastManager.show("消息内容", 2000); // duration in ms
|
||||||
|
```
|
||||||
|
|
||||||
|
**Initialization (main.ts):**
|
||||||
|
```typescript
|
||||||
|
ToastManager.instance.init(toastPrefab, canvasNode);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Toast Behavior:**
|
||||||
|
- Creates Toast instance from prefab
|
||||||
|
- Displays for duration (default 2000ms)
|
||||||
|
- Fades out over 300ms
|
||||||
|
- Auto-destroys
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## WeChat Integration
|
||||||
|
|
||||||
|
**Share Initialization (PageHome):**
|
||||||
|
```typescript
|
||||||
|
WxSDK.initShare({
|
||||||
|
title: '写英语',
|
||||||
|
imageUrl: '',
|
||||||
|
query: ''
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
**Share in Challenge (PassModal):**
|
||||||
|
```typescript
|
||||||
|
WxSDK.shareAppMessage({
|
||||||
|
title: '快来一起玩这款游戏吧',
|
||||||
|
query: `level={levelIndex}`
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
**Share Code Detection (PageLoading):**
|
||||||
|
```typescript
|
||||||
|
const shareCode = WxSDK.getShareCodeFromLaunch();
|
||||||
|
if (shareCode) {
|
||||||
|
const joined = await ShareManager.instance.joinShare(shareCode);
|
||||||
|
// Launch PageLevel in share mode
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Other WeChat Features:**
|
||||||
|
- `WxSDK.vibrateLong()` - Haptic feedback on wrong answer
|
||||||
|
- `WxSDK.isWechat()` - Check if running in WeChat
|
||||||
|
- `checkPrivacySetting()` - Check privacy authorization
|
||||||
|
- `requirePrivacyAuthorize()` - Prompt for privacy consent
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling & Edge Cases
|
||||||
|
|
||||||
|
**Level Loading:**
|
||||||
|
- Try cache first, then async load
|
||||||
|
- Preload next level without blocking
|
||||||
|
- Handle missing config gracefully
|
||||||
|
|
||||||
|
**Point Consumption:**
|
||||||
|
- Check availability before consuming
|
||||||
|
- Show toast if insufficient
|
||||||
|
- Prevent double-click with flag
|
||||||
|
|
||||||
|
**Answer Submission:**
|
||||||
|
- Prevent multiple submissions with transition flag
|
||||||
|
- Trim whitespace from answer
|
||||||
|
- Case-sensitive comparison
|
||||||
|
|
||||||
|
**Page Navigation:**
|
||||||
|
- Share mode: clears share state before returning home
|
||||||
|
- Normal mode: simple back() navigation
|
||||||
|
- Modal: stays on top (z-index 999)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common Tasks
|
||||||
|
|
||||||
|
### Add Toast
|
||||||
|
```typescript
|
||||||
|
ToastManager.show('提示信息');
|
||||||
|
```
|
||||||
|
|
||||||
|
### Navigate to Page
|
||||||
|
```typescript
|
||||||
|
ViewManager.instance.open('PageLevel'); // Push
|
||||||
|
ViewManager.instance.back(); // Pop
|
||||||
|
ViewManager.instance.replace('PageHome');// Swap
|
||||||
|
```
|
||||||
|
|
||||||
|
### Get Current Level
|
||||||
|
```typescript
|
||||||
|
const index = StorageManager.getCurrentLevelIndex();
|
||||||
|
```
|
||||||
|
|
||||||
|
### Check/Consume Points
|
||||||
|
```typescript
|
||||||
|
if (StorageManager.hasPoints()) {
|
||||||
|
await UserAssetsManager.consumePoint(levelId, hintIndex);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Start Game
|
||||||
|
```typescript
|
||||||
|
// From PageHome
|
||||||
|
ViewManager.instance.open('PageLevel');
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create & Share Challenge
|
||||||
|
```typescript
|
||||||
|
// User flow:
|
||||||
|
PageHome → [PK Button] → PageWriteLevels [Select 6]
|
||||||
|
→ PagePreviewLevels [Verify]
|
||||||
|
→ PassModal [Share Button]
|
||||||
|
→ WxSDK.shareAppMessage()
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## File Size & Complexity
|
||||||
|
|
||||||
|
| File | Lines | Complexity |
|
||||||
|
|------|-------|-----------|
|
||||||
|
| main.ts | 92 | Simple (init only) |
|
||||||
|
| PageLoading.ts | 141 | Medium (parallel loading, sync) |
|
||||||
|
| PageHome.ts | 119 | Simple (two buttons) |
|
||||||
|
| PageLevel.ts | 823 | **Very High** (core game logic) |
|
||||||
|
| PagePreviewLevels.ts | 247 | Medium (scroll list) |
|
||||||
|
| PassModal.ts | 155 | Simple (two buttons) |
|
||||||
|
| Toast.ts | 50 | Simple (fade animation) |
|
||||||
|
| ToastManager.ts | 59 | Simple (factory pattern) |
|
||||||
|
| BaseView.ts | 132 | Medium (lifecycle) |
|
||||||
|
| ViewManager.ts | 320 | High (stack navigation) |
|
||||||
|
|
||||||
|
**Total: ~2,138 lines** | **Focal Point: PageLevel.ts (38% of code)**
|
||||||
|
|
||||||
|
|||||||
489
UI_COMPONENTS_INDEX.md
Normal file
489
UI_COMPONENTS_INDEX.md
Normal file
@@ -0,0 +1,489 @@
|
|||||||
|
# UI Components Complete Analysis - Index
|
||||||
|
|
||||||
|
## 📚 Documentation Files Created
|
||||||
|
|
||||||
|
This analysis consists of three comprehensive documents:
|
||||||
|
|
||||||
|
### 1. **UI_COMPONENT_ANALYSIS.md** (Main Reference)
|
||||||
|
**1,424 lines | 45 KB**
|
||||||
|
- Detailed breakdown of all 10 files
|
||||||
|
- Complete method signatures and implementations
|
||||||
|
- Lifecycle method documentation
|
||||||
|
- Data manager interactions
|
||||||
|
- Game flow explanations
|
||||||
|
- Key concepts and patterns
|
||||||
|
|
||||||
|
**Best for:** Deep dives into specific components, understanding implementation details
|
||||||
|
|
||||||
|
### 2. **QUICK_REFERENCE.md** (Developer Cheat Sheet)
|
||||||
|
**~400 lines | 8.6 KB**
|
||||||
|
- Component overview table
|
||||||
|
- Lifecycle stages summary
|
||||||
|
- Key data flows (visual)
|
||||||
|
- Component properties summary
|
||||||
|
- Points & scoring system quick look
|
||||||
|
- Timer system overview
|
||||||
|
- Hint/clue system
|
||||||
|
- Navigation stack examples
|
||||||
|
- Toast system usage
|
||||||
|
- WeChat integration quick reference
|
||||||
|
- Common tasks & code snippets
|
||||||
|
- File complexity metrics
|
||||||
|
|
||||||
|
**Best for:** Quick lookups, copy-paste code patterns, understanding overall architecture
|
||||||
|
|
||||||
|
### 3. **ARCHITECTURE_DIAGRAM.md** (Visual Reference)
|
||||||
|
**~1,000 lines | 26 KB**
|
||||||
|
- System architecture diagram
|
||||||
|
- Page state machine
|
||||||
|
- Page stack visualization with session traces
|
||||||
|
- Component communication diagrams
|
||||||
|
- Data flow diagrams (level completion, hint unlocking)
|
||||||
|
- Timer sequence diagrams
|
||||||
|
- Input box creation flow
|
||||||
|
- Share challenge mode flow
|
||||||
|
- ViewManager caching mechanism
|
||||||
|
- Error handling paths
|
||||||
|
|
||||||
|
**Best for:** Understanding flow, tracing execution, visual learners
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Component Summary
|
||||||
|
|
||||||
|
### Core Infrastructure
|
||||||
|
- **main.ts** (92 lines) - App bootstrap, register pages and managers
|
||||||
|
- **BaseView.ts** (132 lines) - Abstract page lifecycle interface
|
||||||
|
- **ViewManager.ts** (320 lines) - Stack-based page navigation system
|
||||||
|
|
||||||
|
### UI Pages (All extend BaseView)
|
||||||
|
- **PageLoading.ts** (141 lines) - Splash screen, load data, detect share code
|
||||||
|
- **PageHome.ts** (119 lines) - Landing page hub with game/PK buttons
|
||||||
|
- **PageLevel.ts** (823 lines) ⭐ **Most Complex** - Main game with timer, hints, scoring
|
||||||
|
- **PagePreviewLevels.ts** (247 lines) - Scrollable list of selected levels
|
||||||
|
- **PassModal.ts** (155 lines) - Completion modal with next/share buttons
|
||||||
|
|
||||||
|
### Notification System
|
||||||
|
- **Toast.ts** (50 lines) - Individual toast notification with fade animation
|
||||||
|
- **ToastManager.ts** (59 lines) - Singleton manager for toast creation
|
||||||
|
|
||||||
|
**Total: ~2,138 lines across 10 files**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔑 Key Topics Quick Index
|
||||||
|
|
||||||
|
### Game Mechanics
|
||||||
|
| Topic | Location | Key Method |
|
||||||
|
|-------|----------|-----------|
|
||||||
|
| 60-second countdown | PageLevel | startCountdown() / onCountdownTick() |
|
||||||
|
| Hint/clue system (3 levels) | PageLevel | onUnlockClue(index) |
|
||||||
|
| Answer verification | PageLevel | onSubmitAnswer() / getAnswer() |
|
||||||
|
| Level progression | PageLevel | nextLevel() |
|
||||||
|
| Points earning | PageLevel | showSuccess() + UserAssetsManager.earnPoint() |
|
||||||
|
| Points spending | PageLevel | onUnlockClue() + UserAssetsManager.consumePoint() |
|
||||||
|
|
||||||
|
### UI Management
|
||||||
|
| Topic | Location | Key Method |
|
||||||
|
|-------|----------|-----------|
|
||||||
|
| Page navigation | ViewManager | open() / back() / replace() |
|
||||||
|
| Page lifecycle | BaseView | onViewLoad/Show/Hide/Destroy |
|
||||||
|
| Page caching | ViewManager | _viewCache Map |
|
||||||
|
| Page stacking | ViewManager | _viewStack array (LIFO) |
|
||||||
|
| Toast notifications | ToastManager | show(content, duration) |
|
||||||
|
|
||||||
|
### Special Features
|
||||||
|
| Topic | Location | Key Method |
|
||||||
|
|-------|----------|-----------|
|
||||||
|
| Share challenge mode | PageLevel + ShareManager | _isShareMode flag |
|
||||||
|
| WeChat integration | PageHome, PassModal, WxSDK | initShare() / shareAppMessage() |
|
||||||
|
| Server progress sync | PageLoading | _syncProgressFromServer() |
|
||||||
|
| Level preloading | PageLevel | preloadNextLevel() |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Complexity Breakdown
|
||||||
|
|
||||||
|
```
|
||||||
|
PageLevel.ts (823 lines - 38% of total code)
|
||||||
|
├─ Input management
|
||||||
|
├─ Timer system
|
||||||
|
├─ Hint unlocking
|
||||||
|
├─ Answer validation
|
||||||
|
├─ Point interactions
|
||||||
|
├─ Audio effects
|
||||||
|
├─ Modal handling
|
||||||
|
└─ Share mode support
|
||||||
|
|
||||||
|
ViewManager.ts (320 lines - 15% of total code)
|
||||||
|
├─ Page registration
|
||||||
|
├─ Stack management
|
||||||
|
├─ Instance caching
|
||||||
|
├─ Lifecycle coordination
|
||||||
|
└─ Error handling
|
||||||
|
|
||||||
|
All Other Components (995 lines - 47% of total code)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎮 Game Flow Overview
|
||||||
|
|
||||||
|
```
|
||||||
|
User Launches App
|
||||||
|
↓
|
||||||
|
main.ts registers pages & managers
|
||||||
|
↓
|
||||||
|
PageLoading loads auth + levels (parallel)
|
||||||
|
↓
|
||||||
|
┌─ Detect Share Code ──→ Enter Share Mode (PageLevel)
|
||||||
|
│ ↓
|
||||||
|
│ Play Levels
|
||||||
|
│ ↓
|
||||||
|
│ Return Home
|
||||||
|
│
|
||||||
|
└─ Normal Path ──→ Open PageHome
|
||||||
|
↓
|
||||||
|
┌──────┴──────┐
|
||||||
|
↓ ↓
|
||||||
|
Play Game Create Challenge
|
||||||
|
(PageLevel) (PageWriteLevels)
|
||||||
|
↓ ↓
|
||||||
|
Win Level PagePreviewLevels
|
||||||
|
↓ ↓
|
||||||
|
PassModal PassModal/Share
|
||||||
|
↓ ↓
|
||||||
|
Next/Back Share to WeChat
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💾 Data Manager Interactions
|
||||||
|
|
||||||
|
### By Page
|
||||||
|
|
||||||
|
**PageLoading**
|
||||||
|
- AuthManager.initialize()
|
||||||
|
- LevelDataManager.initialize()
|
||||||
|
- StorageManager.getMaxUnlockedLevelIndex()
|
||||||
|
- StorageManager.onLevelCompleted()
|
||||||
|
- ShareManager.joinShare()
|
||||||
|
- WxSDK.getShareCodeFromLaunch()
|
||||||
|
|
||||||
|
**PageHome**
|
||||||
|
- WxSDK.initShare()
|
||||||
|
- checkPrivacySetting()
|
||||||
|
- requirePrivacyAuthorize()
|
||||||
|
|
||||||
|
**PageLevel** (Most interactions)
|
||||||
|
- LevelDataManager (load, preload, get count)
|
||||||
|
- StorageManager (get/set progress, get points)
|
||||||
|
- UserAssetsManager (earn/consume points)
|
||||||
|
- ShareManager (share mode, report progress)
|
||||||
|
- WxSDK (vibration, sharing)
|
||||||
|
- ToastManager (notifications)
|
||||||
|
- ViewManager (navigation)
|
||||||
|
|
||||||
|
**PagePreviewLevels**
|
||||||
|
- LevelDataManager.ensureLevelReady()
|
||||||
|
|
||||||
|
**PassModal**
|
||||||
|
- WxSDK.shareAppMessage()
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚠️ Important Flags & Preventing Issues
|
||||||
|
|
||||||
|
### Double-Submission Prevention
|
||||||
|
```typescript
|
||||||
|
// In PageLevel.onSubmitAnswer()
|
||||||
|
if (this._isTransitioning) return; // Blocks rapid re-submission
|
||||||
|
```
|
||||||
|
|
||||||
|
### Double-Click Unlock Prevention
|
||||||
|
```typescript
|
||||||
|
// In PageLevel.onUnlockClue()
|
||||||
|
if (this._isUnlocking) return; // Blocks rapid hint unlocking
|
||||||
|
```
|
||||||
|
|
||||||
|
### Share Mode Detection
|
||||||
|
```typescript
|
||||||
|
// In PageLevel.onViewLoad()
|
||||||
|
this._isShareMode = params?.shareMode === true;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Timer Running Flag
|
||||||
|
```typescript
|
||||||
|
// In PageLevel.onCountdownTick()
|
||||||
|
if (this._isTimeUp) return; // Prevents countdown after timeout
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Page Lifecycle Details
|
||||||
|
|
||||||
|
### First-Time Open
|
||||||
|
1. ViewManager.open() called
|
||||||
|
2. Prefab instantiated
|
||||||
|
3. onViewLoad() called (do heavy init here)
|
||||||
|
4. Page added to stack
|
||||||
|
5. onViewShow() called
|
||||||
|
|
||||||
|
### Re-open (if cached)
|
||||||
|
1. ViewManager.open() called
|
||||||
|
2. Cache hit found
|
||||||
|
3. Previous page onViewHide() called
|
||||||
|
4. This page onViewShow() called (not onViewLoad!)
|
||||||
|
5. Page already in stack (or re-added)
|
||||||
|
|
||||||
|
### Close/Back
|
||||||
|
1. ViewManager.back() called
|
||||||
|
2. Current page onViewHide() called
|
||||||
|
3. Current page destroyed (if not cached)
|
||||||
|
4. Previous page onViewShow() called
|
||||||
|
|
||||||
|
### Destroy
|
||||||
|
1. onViewDestroy() called
|
||||||
|
2. All listeners removed
|
||||||
|
3. Resources cleaned up
|
||||||
|
4. Node destroyed
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Common Code Patterns
|
||||||
|
|
||||||
|
### Open Page with Parameters
|
||||||
|
```typescript
|
||||||
|
ViewManager.instance.open('PageLevel', {
|
||||||
|
params: { shareMode: true },
|
||||||
|
onComplete: (view) => {
|
||||||
|
console.log('PageLevel opened');
|
||||||
|
},
|
||||||
|
onError: (err) => {
|
||||||
|
console.error('Failed to open:', err);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Get Page Parameters
|
||||||
|
```typescript
|
||||||
|
onViewLoad(): void {
|
||||||
|
const params = this.getParams();
|
||||||
|
if (params?.shareMode) {
|
||||||
|
// Handle share mode
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Show Toast Notification
|
||||||
|
```typescript
|
||||||
|
ToastManager.show('提示信息', 2000); // 2 second display
|
||||||
|
```
|
||||||
|
|
||||||
|
### Check & Consume Points
|
||||||
|
```typescript
|
||||||
|
if (StorageManager.hasPoints()) {
|
||||||
|
const success = await UserAssetsManager.consumePoint(levelId, hintIndex);
|
||||||
|
if (success) {
|
||||||
|
this.updatePointsLabel();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Schedule & Unschedule
|
||||||
|
```typescript
|
||||||
|
startCountdown(): void {
|
||||||
|
this.schedule(this.onCountdownTick, 1); // Every 1 second
|
||||||
|
}
|
||||||
|
|
||||||
|
stopCountdown(): void {
|
||||||
|
this.unschedule(this.onCountdownTick); // Stop callback
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🐛 Known Patterns to Watch
|
||||||
|
|
||||||
|
### Caching Implications
|
||||||
|
- Pages with cache:true keep their onViewLoad() state
|
||||||
|
- onViewShow() is called each time, even if cached
|
||||||
|
- If you modify state in onViewLoad(), it persists!
|
||||||
|
- Solution: Reset state in onViewShow() if needed
|
||||||
|
|
||||||
|
### Share Mode Edge Cases
|
||||||
|
- Share mode doesn't save local progress
|
||||||
|
- Share mode uses ShareManager instead of LevelDataManager
|
||||||
|
- Share mode clears state on return to home
|
||||||
|
- Must check _isShareMode before saving
|
||||||
|
|
||||||
|
### Modal Positioning
|
||||||
|
- PassModal instantiated with z-index 999 (topmost)
|
||||||
|
- Added to Canvas root node (not PageLevel child)
|
||||||
|
- This allows full-screen coverage with proper Widget alignment
|
||||||
|
|
||||||
|
### Timer Edge Cases
|
||||||
|
- Timer continues even if page is hidden
|
||||||
|
- Must stop timer on destroy or completion
|
||||||
|
- onTimeUp() plays sound but doesn't end game automatically
|
||||||
|
- Wrong answer doesn't stop timer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Tips for Modifications
|
||||||
|
|
||||||
|
### Adding New Hint Types
|
||||||
|
1. Add hint4 config to RuntimeLevelConfig
|
||||||
|
2. Add unLockItem4 property to PageLevel
|
||||||
|
3. Add tipsItem4 property to PageLevel
|
||||||
|
4. Call showUnlockButton(4) in _applyLevelConfig()
|
||||||
|
5. Handle in onUnlockClue() switch/case
|
||||||
|
|
||||||
|
### Adding Page Analytics
|
||||||
|
1. Add tracking in onViewLoad() (first visit)
|
||||||
|
2. Add tracking in onViewShow() (each visit)
|
||||||
|
3. Use page viewId for identification
|
||||||
|
4. Track user actions in event handlers
|
||||||
|
|
||||||
|
### Changing Point System
|
||||||
|
1. Modify UserAssetsManager (not shown)
|
||||||
|
2. Update updatePointsLabel() display format
|
||||||
|
3. Adjust hasPoints() check if needed
|
||||||
|
4. Test unlock flow with new values
|
||||||
|
|
||||||
|
### Adjusting Timer
|
||||||
|
1. Change `_countdown = 60` to desired seconds
|
||||||
|
2. Update display frequency if needed
|
||||||
|
3. Adjust point calculation if time-based
|
||||||
|
4. Test timeout behavior
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📖 How to Use This Documentation
|
||||||
|
|
||||||
|
**For a new developer:**
|
||||||
|
1. Start with QUICK_REFERENCE.md for overview
|
||||||
|
2. Read UI_COMPONENT_ANALYSIS.md sections for specific pages
|
||||||
|
3. Reference ARCHITECTURE_DIAGRAM.md for flow understanding
|
||||||
|
|
||||||
|
**For debugging:**
|
||||||
|
1. Find error in component name
|
||||||
|
2. Look up methods in UI_COMPONENT_ANALYSIS.md
|
||||||
|
3. Check flow in ARCHITECTURE_DIAGRAM.md
|
||||||
|
4. Use QUICK_REFERENCE.md for code patterns
|
||||||
|
|
||||||
|
**For adding features:**
|
||||||
|
1. Understand game flow in QUICK_REFERENCE.md
|
||||||
|
2. Find where to hook in UI_COMPONENT_ANALYSIS.md
|
||||||
|
3. Check data flows in ARCHITECTURE_DIAGRAM.md
|
||||||
|
4. Copy patterns from QUICK_REFERENCE.md
|
||||||
|
|
||||||
|
**For optimization:**
|
||||||
|
1. Note complexity metrics in QUICK_REFERENCE.md
|
||||||
|
2. Identify bottlenecks in PageLevel.ts
|
||||||
|
3. Check async operations in PageLoading.ts
|
||||||
|
4. Review caching in ViewManager.ts
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔗 Cross-References
|
||||||
|
|
||||||
|
### Frequently Referenced Files
|
||||||
|
- **PageLevel.ts** - Most complex, used from PageHome and PageLoading
|
||||||
|
- **ViewManager.ts** - Used by all pages for navigation
|
||||||
|
- **StorageManager** - Used by PageLoading and PageLevel
|
||||||
|
- **UserAssetsManager** - Used by PageLevel for points
|
||||||
|
- **LevelDataManager** - Used by PageLoading and PageLevel
|
||||||
|
|
||||||
|
### Integration Points
|
||||||
|
```
|
||||||
|
main.ts (startup)
|
||||||
|
↓
|
||||||
|
PageLoading (data loading)
|
||||||
|
├─ AuthManager
|
||||||
|
├─ LevelDataManager
|
||||||
|
└─ ShareManager
|
||||||
|
↓
|
||||||
|
PageHome (navigation hub)
|
||||||
|
├─ PageLevel (game)
|
||||||
|
│ ├─ StorageManager
|
||||||
|
│ ├─ UserAssetsManager
|
||||||
|
│ ├─ WxSDK
|
||||||
|
│ └─ PassModal (modal)
|
||||||
|
│ └─ WxSDK
|
||||||
|
│
|
||||||
|
└─ PageWriteLevels (not analyzed)
|
||||||
|
└─ PagePreviewLevels
|
||||||
|
└─ LevelDataManager
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 File Statistics
|
||||||
|
|
||||||
|
| Metric | Value |
|
||||||
|
|--------|-------|
|
||||||
|
| Total Lines | 2,138 |
|
||||||
|
| Total Files Analyzed | 10 |
|
||||||
|
| Most Complex File | PageLevel.ts (823 lines, 38%) |
|
||||||
|
| Most Reused Manager | ViewManager |
|
||||||
|
| Total Data Managers Used | 7+ |
|
||||||
|
| UI Components | 5 pages + 2 utilities |
|
||||||
|
| Lifecycle Methods | 4 per BaseView |
|
||||||
|
| Key Patterns | Stack navigation, caching, events |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Next Steps for Development
|
||||||
|
|
||||||
|
1. **Run the game** and trace through the flows documented here
|
||||||
|
2. **Add logging** to key methods to understand real execution order
|
||||||
|
3. **Modify a page** to get familiar with lifecycle
|
||||||
|
4. **Create new page** following BaseView pattern
|
||||||
|
5. **Add new feature** using documented patterns
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📞 Quick Troubleshooting
|
||||||
|
|
||||||
|
**Page not showing?**
|
||||||
|
- Check ViewManager.open() called
|
||||||
|
- Verify prefab has BaseView component
|
||||||
|
- Check registration in main.ts
|
||||||
|
|
||||||
|
**Points not updating?**
|
||||||
|
- Verify UserAssetsManager call succeeds
|
||||||
|
- Check updatePointsLabel() is called
|
||||||
|
- Test StorageManager.getPoints() returns value
|
||||||
|
|
||||||
|
**Timer not stopping?**
|
||||||
|
- Check stopCountdown() called on completion
|
||||||
|
- Verify unschedule() works in Cocos
|
||||||
|
- Test onDestroy calls stopCountdown()
|
||||||
|
|
||||||
|
**Modal not appearing?**
|
||||||
|
- Check z-index set to 999
|
||||||
|
- Verify added to Canvas root
|
||||||
|
- Test instantiate() succeeds
|
||||||
|
- Check onViewLoad/Show called manually
|
||||||
|
|
||||||
|
**Share mode broken?**
|
||||||
|
- Verify share code detected in PageLoading
|
||||||
|
- Check _isShareMode set properly
|
||||||
|
- Test ShareManager.joinShare() succeeds
|
||||||
|
- Verify clearShareMode() called on exit
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ Analysis Complete
|
||||||
|
|
||||||
|
All 10 UI component files have been thoroughly analyzed and documented.
|
||||||
|
|
||||||
|
**Total Documentation: 3 comprehensive guides**
|
||||||
|
- **UI_COMPONENT_ANALYSIS.md** - Deep technical reference (1,424 lines)
|
||||||
|
- **QUICK_REFERENCE.md** - Developer cheat sheet (~400 lines)
|
||||||
|
- **ARCHITECTURE_DIAGRAM.md** - Visual flow diagrams (~1,000 lines)
|
||||||
|
- **This file** - Navigation & index (this document)
|
||||||
|
|
||||||
|
**Ready for:** Development, debugging, feature implementation, onboarding
|
||||||
|
|
||||||
1424
UI_COMPONENT_ANALYSIS.md
Normal file
1424
UI_COMPONENT_ANALYSIS.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -2,13 +2,14 @@ import { _decorator, Node, EditBox, instantiate, Vec3, Button, Label, Sprite, Sp
|
|||||||
import { BaseView } from 'db://assets/scripts/core/BaseView';
|
import { BaseView } from 'db://assets/scripts/core/BaseView';
|
||||||
import { ViewManager } from 'db://assets/scripts/core/ViewManager';
|
import { ViewManager } from 'db://assets/scripts/core/ViewManager';
|
||||||
import { StorageManager } from 'db://assets/scripts/utils/StorageManager';
|
import { StorageManager } from 'db://assets/scripts/utils/StorageManager';
|
||||||
import { UserAssetsManager } from 'db://assets/scripts/utils/UserAssetsManager';
|
import { StaminaManager } from 'db://assets/scripts/utils/StaminaManager';
|
||||||
import { WxSDK } from 'db://assets/scripts/utils/WxSDK';
|
import { WxSDK } from 'db://assets/scripts/utils/WxSDK';
|
||||||
import { LevelDataManager } from 'db://assets/scripts/utils/LevelDataManager';
|
import { LevelDataManager } from 'db://assets/scripts/utils/LevelDataManager';
|
||||||
import { RuntimeLevelConfig } from 'db://assets/scripts/types/LevelTypes';
|
import { RuntimeLevelConfig } from 'db://assets/scripts/types/LevelTypes';
|
||||||
import { ToastManager } from 'db://assets/scripts/utils/ToastManager';
|
import { ToastManager } from 'db://assets/scripts/utils/ToastManager';
|
||||||
import { ShareManager } from 'db://assets/scripts/utils/ShareManager';
|
import { ShareManager } from 'db://assets/scripts/utils/ShareManager';
|
||||||
import { PassModal } from 'db://assets/prefabs/PassModal';
|
import { PassModal } from 'db://assets/prefabs/PassModal';
|
||||||
|
import { StaminaInfo } from 'db://assets/scripts/types/ApiTypes';
|
||||||
const { ccclass, property } = _decorator;
|
const { ccclass, property } = _decorator;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -60,7 +61,7 @@ export class PageLevel extends BaseView {
|
|||||||
@property(Label)
|
@property(Label)
|
||||||
clockLabel: Label | null = null;
|
clockLabel: Label | null = null;
|
||||||
|
|
||||||
/** 积分显示标签（prefab 中序列化名为 liveLabel，保持兼容） */
|
/** 体力值显示标签（prefab 中序列化名为 liveLabel，保持兼容） */
|
||||||
@property(Label)
|
@property(Label)
|
||||||
liveLabel: Label | null = null;
|
liveLabel: Label | null = null;
|
||||||
|
|
||||||
@@ -99,7 +100,7 @@ export class PageLevel extends BaseView {
|
|||||||
/** 是否正在切换关卡（防止重复提交） */
|
/** 是否正在切换关卡（防止重复提交） */
|
||||||
private _isTransitioning: boolean = false;
|
private _isTransitioning: boolean = false;
|
||||||
|
|
||||||
/** 是否正在解锁提示（防止双击重复消耗积分） */
|
/** 是否正在解锁提示（防止双击重复触发） */
|
||||||
private _isUnlocking: boolean = false;
|
private _isUnlocking: boolean = false;
|
||||||
|
|
||||||
/** 通关弹窗实例 */
|
/** 通关弹窗实例 */
|
||||||
@@ -108,6 +109,9 @@ export class PageLevel extends BaseView {
|
|||||||
/** 是否处于分享挑战模式 */
|
/** 是否处于分享挑战模式 */
|
||||||
private _isShareMode: boolean = false;
|
private _isShareMode: boolean = false;
|
||||||
|
|
||||||
|
/** 体力恢复倒计时定时器 */
|
||||||
|
private _staminaTimerId: ReturnType<typeof setInterval> | null = null;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 页面首次加载时调用
|
* 页面首次加载时调用
|
||||||
*/
|
*/
|
||||||
@@ -125,16 +129,14 @@ export class PageLevel extends BaseView {
|
|||||||
this.currentLevelIndex = StorageManager.getCurrentLevelIndex();
|
this.currentLevelIndex = StorageManager.getCurrentLevelIndex();
|
||||||
console.log(`[PageLevel] 恢复关卡进度: 第 ${this.currentLevelIndex + 1} 关`);
|
console.log(`[PageLevel] 恢复关卡进度: 第 ${this.currentLevelIndex + 1} 关`);
|
||||||
}
|
}
|
||||||
this.updatePointsLabel();
|
this.updateStaminaLabel();
|
||||||
this.initIconSetting();
|
this.initIconSetting();
|
||||||
this.initUnlockButtons();
|
this.initUnlockButtons();
|
||||||
this.initSubmitButton();
|
this.initSubmitButton();
|
||||||
|
|
||||||
// 异步加载关卡资源，完成后启动倒计时
|
// 异步加载关卡资源并调用进入关卡接口，完成后启动倒计时
|
||||||
this.initLevel().then(() => {
|
this._enterAndInitLevel().catch(err => {
|
||||||
this.startCountdown();
|
console.error('[PageLevel] 进入关卡失败:', err);
|
||||||
}).catch(err => {
|
|
||||||
console.error('[PageLevel] 加载关卡失败:', err);
|
|
||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -143,7 +145,8 @@ export class PageLevel extends BaseView {
|
|||||||
*/
|
*/
|
||||||
onViewShow(): void {
|
onViewShow(): void {
|
||||||
console.log('[PageLevel] onViewShow');
|
console.log('[PageLevel] onViewShow');
|
||||||
this.updatePointsLabel();
|
this.updateStaminaLabel();
|
||||||
|
this._startStaminaRecoverTimer();
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -151,6 +154,7 @@ export class PageLevel extends BaseView {
|
|||||||
*/
|
*/
|
||||||
onViewHide(): void {
|
onViewHide(): void {
|
||||||
console.log('[PageLevel] onViewHide');
|
console.log('[PageLevel] onViewHide');
|
||||||
|
this._stopStaminaRecoverTimer();
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -161,6 +165,7 @@ export class PageLevel extends BaseView {
|
|||||||
this.clearInputNodes();
|
this.clearInputNodes();
|
||||||
this.stopCountdown();
|
this.stopCountdown();
|
||||||
this._closePassModal();
|
this._closePassModal();
|
||||||
|
this._stopStaminaRecoverTimer();
|
||||||
|
|
||||||
// 清理事件监听
|
// 清理事件监听
|
||||||
this.iconSetting?.off(Node.EventType.TOUCH_END, this.onIconSettingClick, this);
|
this.iconSetting?.off(Node.EventType.TOUCH_END, this.onIconSettingClick, this);
|
||||||
@@ -170,16 +175,18 @@ export class PageLevel extends BaseView {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 初始化关卡（从 API 数据加载，异步确保资源就绪）
|
* 进入关卡并初始化
|
||||||
|
* 1. 加载关卡图片资源
|
||||||
|
* 2. 调用进入关卡接口（消耗体力，获取答案和线索）
|
||||||
|
* 3. 启动倒计时
|
||||||
*/
|
*/
|
||||||
private async initLevel(): Promise<void> {
|
private async _enterAndInitLevel(): Promise<void> {
|
||||||
|
// 先加载关卡图片资源
|
||||||
let config: RuntimeLevelConfig | null = null;
|
let config: RuntimeLevelConfig | null = null;
|
||||||
|
|
||||||
if (this._isShareMode) {
|
if (this._isShareMode) {
|
||||||
// 分享模式：从 ShareManager 获取关卡
|
|
||||||
config = await ShareManager.instance.ensureShareLevelReady(this.currentLevelIndex);
|
config = await ShareManager.instance.ensureShareLevelReady(this.currentLevelIndex);
|
||||||
} else {
|
} else {
|
||||||
// 正常模式：先尝试缓存，再异步加载
|
|
||||||
config = LevelDataManager.instance.getLevelConfig(this.currentLevelIndex);
|
config = LevelDataManager.instance.getLevelConfig(this.currentLevelIndex);
|
||||||
if (!config) {
|
if (!config) {
|
||||||
console.log(`[PageLevel] 关卡 ${this.currentLevelIndex + 1} 资源未缓存，开始加载...`);
|
console.log(`[PageLevel] 关卡 ${this.currentLevelIndex + 1} 资源未缓存，开始加载...`);
|
||||||
@@ -192,8 +199,53 @@ export class PageLevel extends BaseView {
|
|||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// 非分享模式下，调用进入关卡接口获取答案和线索
|
||||||
|
if (!this._isShareMode) {
|
||||||
|
const levelId = LevelDataManager.instance.getLevelId(this.currentLevelIndex);
|
||||||
|
if (levelId) {
|
||||||
|
const enterData = await StaminaManager.instance.enterLevel(levelId);
|
||||||
|
if (!enterData) {
|
||||||
|
// 进入关卡失败（可能是体力不足）
|
||||||
|
const stamina = StaminaManager.instance.getStamina();
|
||||||
|
if (stamina.current <= 0) {
|
||||||
|
ToastManager.show('体力不足，请等待恢复');
|
||||||
|
this._startStaminaRecoverTimer();
|
||||||
|
} else {
|
||||||
|
ToastManager.show('进入关卡失败，请重试');
|
||||||
|
}
|
||||||
|
this.updateStaminaLabel();
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
// 提示用户消耗体力
|
||||||
|
ToastManager.show(`消耗1点体力，剩余 ${enterData.stamina.current}/${enterData.stamina.max}`);
|
||||||
|
|
||||||
|
// 用 enter 接口返回的数据更新关卡配置（填充答案和线索）
|
||||||
|
LevelDataManager.instance.updateLevelDetails(
|
||||||
|
this.currentLevelIndex,
|
||||||
|
{
|
||||||
|
answer: enterData.answer,
|
||||||
|
hint1: enterData.hint1,
|
||||||
|
hint2: enterData.hint2,
|
||||||
|
hint3: enterData.hint3,
|
||||||
|
}
|
||||||
|
);
|
||||||
|
|
||||||
|
// 重新获取更新后的配置
|
||||||
|
config = LevelDataManager.instance.getLevelConfig(this.currentLevelIndex);
|
||||||
|
if (!config) {
|
||||||
|
console.error('[PageLevel] 更新关卡详情后获取配置失败');
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
// 更新体力显示
|
||||||
|
this.updateStaminaLabel();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
console.log(`[PageLevel] 初始化关卡 ${this.currentLevelIndex + 1}: ${config.name}`);
|
console.log(`[PageLevel] 初始化关卡 ${this.currentLevelIndex + 1}: ${config.name}`);
|
||||||
this._applyLevelConfig(config);
|
this._applyLevelConfig(config);
|
||||||
|
this.startCountdown();
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -212,8 +264,10 @@ export class PageLevel extends BaseView {
|
|||||||
// 设置主图
|
// 设置主图
|
||||||
this.setMainImage(config.spriteFrame);
|
this.setMainImage(config.spriteFrame);
|
||||||
|
|
||||||
// 设置线索1（默认解锁）
|
// 设置线索1（默认解锁，如果有的话）
|
||||||
|
if (config.clue1) {
|
||||||
this.setClue(1, config.clue1);
|
this.setClue(1, config.clue1);
|
||||||
|
}
|
||||||
|
|
||||||
// 隐藏线索2、3
|
// 隐藏线索2、3
|
||||||
this.hideClue(2);
|
this.hideClue(2);
|
||||||
@@ -224,7 +278,9 @@ export class PageLevel extends BaseView {
|
|||||||
this.showUnlockButton(3);
|
this.showUnlockButton(3);
|
||||||
|
|
||||||
// 根据答案长度创建单个输入框
|
// 根据答案长度创建单个输入框
|
||||||
|
if (config.answer) {
|
||||||
this.createSingleInput(config.answer.length);
|
this.createSingleInput(config.answer.length);
|
||||||
|
}
|
||||||
|
|
||||||
// 更新倒计时显示
|
// 更新倒计时显示
|
||||||
this.updateClockLabel();
|
this.updateClockLabel();
|
||||||
@@ -239,7 +295,7 @@ export class PageLevel extends BaseView {
|
|||||||
LevelDataManager.instance.preloadNextLevel(this.currentLevelIndex);
|
LevelDataManager.instance.preloadNextLevel(this.currentLevelIndex);
|
||||||
}
|
}
|
||||||
|
|
||||||
console.log(`[PageLevel] 初始化关卡 ${this.currentLevelIndex + 1}, 答案长度: ${config.answer.length}`);
|
console.log(`[PageLevel] 初始化关卡 ${this.currentLevelIndex + 1}, 答案长度: ${config.answer?.length ?? 0}`);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -313,6 +369,11 @@ export class PageLevel extends BaseView {
|
|||||||
private clearInputNodes(): void {
|
private clearInputNodes(): void {
|
||||||
for (const node of this._inputNodes) {
|
for (const node of this._inputNodes) {
|
||||||
if (node.isValid) {
|
if (node.isValid) {
|
||||||
|
const editBox = node.getComponent(EditBox);
|
||||||
|
if (editBox) {
|
||||||
|
editBox.node.off(EditBox.EventType.TEXT_CHANGED, this.onInputTextChanged, this);
|
||||||
|
editBox.node.off(EditBox.EventType.EDITING_DID_ENDED, this.onInputEditingEnded, this);
|
||||||
|
}
|
||||||
node.destroy();
|
node.destroy();
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -501,38 +562,38 @@ export class PageLevel extends BaseView {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 点击解锁线索
|
* 点击解锁线索（观看激励视频广告后解锁）
|
||||||
*/
|
*/
|
||||||
private async onUnlockClue(index: number): Promise<void> {
|
private async onUnlockClue(index: number): Promise<void> {
|
||||||
// 防止双击重复消耗
|
// 防止双击重复触发
|
||||||
if (this._isUnlocking) return;
|
if (this._isUnlocking) return;
|
||||||
|
|
||||||
if (!this.hasPoints()) {
|
|
||||||
ToastManager.show('积分不足，无法解锁提示！');
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
this._isUnlocking = true;
|
this._isUnlocking = true;
|
||||||
|
|
||||||
try {
|
try {
|
||||||
const levelId = this._currentConfig?.id;
|
// 检查线索是否存在
|
||||||
const success = await UserAssetsManager.instance.consumePoint(levelId, index);
|
if (!this._currentConfig) return;
|
||||||
if (!success) {
|
|
||||||
ToastManager.show('积分不足，无法解锁提示！');
|
const clueContent = index === 2 ? this._currentConfig.clue2 : this._currentConfig.clue3;
|
||||||
|
if (!clueContent) {
|
||||||
|
ToastManager.show('该提示暂未配置');
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
// 调用微信激励视频广告
|
||||||
|
ToastManager.show('观看视频即可解锁提示');
|
||||||
|
const adWatched = await WxSDK.showRewardedVideoAd();
|
||||||
|
if (!adWatched) {
|
||||||
|
ToastManager.show('需要看完视频才能解锁提示哦');
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
this.updatePointsLabel();
|
|
||||||
this.playClickSound();
|
this.playClickSound();
|
||||||
this.hideUnlockButton(index);
|
this.hideUnlockButton(index);
|
||||||
this.showClue(index);
|
this.showClue(index);
|
||||||
|
|
||||||
if (this._currentConfig) {
|
|
||||||
const clueContent = index === 2 ? this._currentConfig.clue2 : this._currentConfig.clue3;
|
|
||||||
this.setClue(index, clueContent);
|
this.setClue(index, clueContent);
|
||||||
}
|
|
||||||
|
|
||||||
console.log(`[PageLevel] 解锁线索${index}`);
|
console.log(`[PageLevel] 通过观看广告解锁线索${index}`);
|
||||||
} finally {
|
} finally {
|
||||||
this._isUnlocking = false;
|
this._isUnlocking = false;
|
||||||
}
|
}
|
||||||
@@ -639,17 +700,70 @@ export class PageLevel extends BaseView {
|
|||||||
// 可以在这里添加游戏结束逻辑
|
// 可以在这里添加游戏结束逻辑
|
||||||
}
|
}
|
||||||
|
|
||||||
// ========== 积分相关方法 ==========
|
// ========== 体力值相关方法 ==========
|
||||||
|
|
||||||
private updatePointsLabel(): void {
|
/** 上次显示的体力值，用于变更检测 */
|
||||||
|
private _lastDisplayedStamina: number = -1;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 更新体力值显示（仅值变化时更新 UI）
|
||||||
|
*/
|
||||||
|
private updateStaminaLabel(): void {
|
||||||
if (this.liveLabel) {
|
if (this.liveLabel) {
|
||||||
const points = StorageManager.getPoints();
|
const stamina = StaminaManager.instance.getStamina();
|
||||||
this.liveLabel.string = `x ${points}`;
|
if (stamina.current !== this._lastDisplayedStamina) {
|
||||||
|
this.liveLabel.string = `x ${stamina.current}`;
|
||||||
|
this._lastDisplayedStamina = stamina.current;
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
private hasPoints(): boolean {
|
/**
|
||||||
return StorageManager.hasPoints();
|
* 启动体力恢复倒计时 UI
|
||||||
|
*/
|
||||||
|
private _startStaminaRecoverTimer(): void {
|
||||||
|
this._stopStaminaRecoverTimer();
|
||||||
|
|
||||||
|
const stamina = StaminaManager.instance.getStamina();
|
||||||
|
if (!stamina.nextRecoverAt || stamina.current >= stamina.max) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
const targetTime = new Date(stamina.nextRecoverAt).getTime();
|
||||||
|
if (isNaN(targetTime)) return;
|
||||||
|
|
||||||
|
this._staminaTimerId = setInterval(() => {
|
||||||
|
if (targetTime - Date.now() > 0) return;
|
||||||
|
|
||||||
|
// 恢复一点体力
|
||||||
|
const currentStamina = StaminaManager.instance.getStamina();
|
||||||
|
const newCurrent = Math.min(currentStamina.current + 1, currentStamina.max);
|
||||||
|
const newStamina: StaminaInfo = {
|
||||||
|
...currentStamina,
|
||||||
|
current: newCurrent,
|
||||||
|
nextRecoverAt: newCurrent < currentStamina.max
|
||||||
|
? new Date(Date.now() + 10 * 60 * 1000).toISOString()
|
||||||
|
: null,
|
||||||
|
};
|
||||||
|
StaminaManager.instance.updateStamina(newStamina);
|
||||||
|
this.updateStaminaLabel();
|
||||||
|
|
||||||
|
this._stopStaminaRecoverTimer();
|
||||||
|
|
||||||
|
if (newCurrent < currentStamina.max) {
|
||||||
|
this._startStaminaRecoverTimer();
|
||||||
|
}
|
||||||
|
}, 1000);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 停止体力恢复倒计时
|
||||||
|
*/
|
||||||
|
private _stopStaminaRecoverTimer(): void {
|
||||||
|
if (this._staminaTimerId !== null) {
|
||||||
|
clearInterval(this._staminaTimerId);
|
||||||
|
this._staminaTimerId = null;
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
// ========== 答案提交与关卡切换 ==========
|
// ========== 答案提交与关卡切换 ==========
|
||||||
@@ -674,7 +788,7 @@ export class PageLevel extends BaseView {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 显示成功提示
|
* 显示成功提示并上报通关
|
||||||
*/
|
*/
|
||||||
private async showSuccess(): Promise<void> {
|
private async showSuccess(): Promise<void> {
|
||||||
console.log('[PageLevel] 答案正确！');
|
console.log('[PageLevel] 答案正确！');
|
||||||
@@ -692,8 +806,13 @@ export class PageLevel extends BaseView {
|
|||||||
const timeSpent = 60 - this._countdown;
|
const timeSpent = 60 - this._countdown;
|
||||||
|
|
||||||
if (!this._isShareMode) {
|
if (!this._isShareMode) {
|
||||||
await UserAssetsManager.instance.earnPoint(levelId, timeSpent);
|
// 上报通关耗时
|
||||||
this.updatePointsLabel();
|
const result = await StaminaManager.instance.completeLevel(levelId, timeSpent);
|
||||||
|
if (result) {
|
||||||
|
console.log(`[PageLevel] 通关上报成功，首次通关: ${result.firstClear}`);
|
||||||
|
}
|
||||||
|
// 标记关卡为已通关（本地缓存）
|
||||||
|
LevelDataManager.instance.markLevelCompleted(this.currentLevelIndex);
|
||||||
} else {
|
} else {
|
||||||
// fire-and-forget: errors are logged inside reportLevelProgress
|
// fire-and-forget: errors are logged inside reportLevelProgress
|
||||||
void ShareManager.instance.reportLevelProgress(levelId, true, timeSpent);
|
void ShareManager.instance.reportLevelProgress(levelId, true, timeSpent);
|
||||||
@@ -812,11 +931,8 @@ export class PageLevel extends BaseView {
|
|||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
// 重置并加载下一关，重新开始倒计时
|
// 重置并加载下一关（包含进入关卡接口调用）
|
||||||
await this.initLevel();
|
await this._enterAndInitLevel();
|
||||||
this.startCountdown();
|
|
||||||
console.log(`[PageLevel] 进入关卡 ${this.currentLevelIndex + 1}`);
|
console.log(`[PageLevel] 进入关卡 ${this.currentLevelIndex + 1}`);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@@ -30,7 +30,7 @@ export class PassModal extends BaseView {
|
|||||||
@property(Node)
|
@property(Node)
|
||||||
shareButton: Node | null = null;
|
shareButton: Node | null = null;
|
||||||
|
|
||||||
/** 提示Label（如 +1 生命） */
|
/** 提示Label（如 恭喜通关） */
|
||||||
@property(Label)
|
@property(Label)
|
||||||
tipLabel: Label | null = null;
|
tipLabel: Label | null = null;
|
||||||
|
|
||||||
|
|||||||
@@ -8,27 +8,38 @@ export const API_BASE = 'https://ilookai.cn/api/v1';
|
|||||||
|
|
||||||
/** API 端点 */
|
/** API 端点 */
|
||||||
export const API_ENDPOINTS = {
|
export const API_ENDPOINTS = {
|
||||||
|
/** 微信登录 */
|
||||||
WX_LOGIN: `${API_BASE}/auth/wx-login`,
|
WX_LOGIN: `${API_BASE}/auth/wx-login`,
|
||||||
USER_ASSETS: `${API_BASE}/user/assets`,
|
/** 用户资料（含实时体力） */
|
||||||
USER_ASSETS_CONSUME: `${API_BASE}/user/assets/consume`,
|
USER_PROFILE: `${API_BASE}/user/profile`,
|
||||||
USER_ASSETS_EARN: `${API_BASE}/user/assets/earn`,
|
/** 游戏数据（体力 + 通关进度） */
|
||||||
USER_GAME_DATA: `${API_BASE}/user/game-data`,
|
USER_GAME_DATA: `${API_BASE}/user/game-data`,
|
||||||
LEVELS: `${API_BASE}/wechat-game/levels`,
|
/** 关卡列表 */
|
||||||
|
LEVELS: `${API_BASE}/levels`,
|
||||||
|
/** 游戏配置 */
|
||||||
|
GAME_CONFIGS: `${API_BASE}/game-configs`,
|
||||||
|
/** 分享相关 */
|
||||||
SHARE_CREATE: `${API_BASE}/share`,
|
SHARE_CREATE: `${API_BASE}/share`,
|
||||||
SHARE_PROGRESS: `${API_BASE}/share/progress`,
|
SHARE_PROGRESS: `${API_BASE}/share/progress`,
|
||||||
|
/** 用户信息 */
|
||||||
USER_INFO: `${API_BASE}/user/info`,
|
USER_INFO: `${API_BASE}/user/info`,
|
||||||
} as const;
|
} as const;
|
||||||
|
|
||||||
/** 构建加入分享的 URL */
|
export function getLevelEnterUrl(levelId: string): string {
|
||||||
|
return `${API_BASE}/levels/${levelId}/enter`;
|
||||||
|
}
|
||||||
|
|
||||||
|
export function getLevelCompleteUrl(levelId: string): string {
|
||||||
|
return `${API_BASE}/levels/${levelId}/complete`;
|
||||||
|
}
|
||||||
|
|
||||||
export function getShareJoinUrl(code: string): string {
|
export function getShareJoinUrl(code: string): string {
|
||||||
return `${API_BASE}/share/${code}/join`;
|
return `${API_BASE}/share/${code}/join`;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** 积分操作原因 */
|
export function getGameConfigUrl(key: string): string {
|
||||||
export const POINT_REASONS = {
|
return `${API_BASE}/game-configs/${key}`;
|
||||||
HINT_UNLOCK: 'hint_unlock',
|
}
|
||||||
LEVEL_COMPLETE: 'level_complete',
|
|
||||||
} as const;
|
|
||||||
|
|
||||||
/** 请求超时时间（毫秒） */
|
/** 请求超时时间（毫秒） */
|
||||||
export const API_TIMEOUT = {
|
export const API_TIMEOUT = {
|
||||||
|
|||||||
@@ -7,6 +7,17 @@ export interface ApiEnvelope<T> {
|
|||||||
success: boolean;
|
success: boolean;
|
||||||
data: T | null;
|
data: T | null;
|
||||||
message: string | null;
|
message: string | null;
|
||||||
|
timestamp: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** 体力值信息 */
|
||||||
|
export interface StaminaInfo {
|
||||||
|
/** 当前体力值（已计算恢复） */
|
||||||
|
current: number;
|
||||||
|
/** 体力上限，固定为 5 */
|
||||||
|
max: number;
|
||||||
|
/** 下一点体力恢复的时间（ISO 8601），满体力时为 null */
|
||||||
|
nextRecoverAt: string | null;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** 登录响应数据 */
|
/** 登录响应数据 */
|
||||||
@@ -15,21 +26,64 @@ export interface WxLoginData {
|
|||||||
user: {
|
user: {
|
||||||
id: string;
|
id: string;
|
||||||
nickname: string | null;
|
nickname: string | null;
|
||||||
points: number;
|
stamina: number;
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
/** 积分响应数据 */
|
/** 用户资料响应数据 */
|
||||||
export interface UserAssetsData {
|
export interface UserProfileData {
|
||||||
points: number;
|
id: string;
|
||||||
|
nickname: string | null;
|
||||||
|
stamina: StaminaInfo;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** 游戏数据响应（Loading 页面） */
|
/** 游戏数据响应（Loading 页面） */
|
||||||
export interface GameData {
|
export interface GameData {
|
||||||
user: { id: string; points: number };
|
user: {
|
||||||
|
id: string;
|
||||||
|
stamina: StaminaInfo;
|
||||||
|
};
|
||||||
completedLevelIds: string[];
|
completedLevelIds: string[];
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** 关卡列表项 */
|
||||||
|
export interface LevelListItem {
|
||||||
|
id: string;
|
||||||
|
level: number;
|
||||||
|
imageUrl: string;
|
||||||
|
answer: string | null;
|
||||||
|
hint1: string | null;
|
||||||
|
hint2: string | null;
|
||||||
|
hint3: string | null;
|
||||||
|
completed: boolean;
|
||||||
|
timeSpent: number | null;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** 关卡列表响应 */
|
||||||
|
export interface LevelListData {
|
||||||
|
levels: LevelListItem[];
|
||||||
|
total: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** 进入关卡响应 */
|
||||||
|
export interface EnterLevelData {
|
||||||
|
id: string;
|
||||||
|
level: number;
|
||||||
|
imageUrl: string;
|
||||||
|
answer: string;
|
||||||
|
hint1: string | null;
|
||||||
|
hint2: string | null;
|
||||||
|
hint3: string | null;
|
||||||
|
stamina: StaminaInfo;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** 通关上报响应 */
|
||||||
|
export interface CompleteLevelData {
|
||||||
|
firstClear: boolean;
|
||||||
|
levelId: string;
|
||||||
|
timeSpent: number;
|
||||||
|
}
|
||||||
|
|
||||||
/** 创建分享响应 */
|
/** 创建分享响应 */
|
||||||
export interface CreateShareData {
|
export interface CreateShareData {
|
||||||
shareCode: string;
|
shareCode: string;
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
import { SpriteFrame } from 'cc';
|
import { SpriteFrame } from 'cc';
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* API 返回的单个关卡数据结构
|
* API 返回的单个关卡数据结构（关卡列表）
|
||||||
*/
|
*/
|
||||||
export interface ApiLevelData {
|
export interface ApiLevelData {
|
||||||
/** 关卡 ID (UUID) */
|
/** 关卡 ID (UUID) */
|
||||||
@@ -10,20 +10,22 @@ export interface ApiLevelData {
|
|||||||
level: number;
|
level: number;
|
||||||
/** 主图 URL */
|
/** 主图 URL */
|
||||||
imageUrl: string;
|
imageUrl: string;
|
||||||
/** 线索1 */
|
/** 线索1（未通关时为 null） */
|
||||||
hint1: string;
|
hint1: string | null;
|
||||||
/** 线索2 */
|
/** 线索2（未通关时为 null） */
|
||||||
hint2: string;
|
hint2: string | null;
|
||||||
/** 线索3 */
|
/** 线索3（未通关时为 null） */
|
||||||
hint3: string;
|
hint3: string | null;
|
||||||
/** 答案 */
|
/** 答案（未通关时为 null） */
|
||||||
answer: string;
|
answer: string | null;
|
||||||
/** 排序 */
|
/** 是否已通关 */
|
||||||
sortOrder: number;
|
completed: boolean;
|
||||||
|
/** 通关时长（秒），未通关时为 null */
|
||||||
|
timeSpent: number | null;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* API 响应结构
|
* API 响应结构（关卡列表）
|
||||||
*/
|
*/
|
||||||
export interface ApiResponse {
|
export interface ApiResponse {
|
||||||
/** 是否成功 */
|
/** 是否成功 */
|
||||||
@@ -47,12 +49,14 @@ export interface RuntimeLevelConfig {
|
|||||||
name: string;
|
name: string;
|
||||||
/** 主图 SpriteFrame（可能为 null 如果加载失败） */
|
/** 主图 SpriteFrame（可能为 null 如果加载失败） */
|
||||||
spriteFrame: SpriteFrame | null;
|
spriteFrame: SpriteFrame | null;
|
||||||
/** 线索1 */
|
/** 线索1（未通关时为 null，进入关卡后由 enter 接口获取） */
|
||||||
clue1: string;
|
clue1: string | null;
|
||||||
/** 线索2 */
|
/** 线索2（未通关时为 null） */
|
||||||
clue2: string;
|
clue2: string | null;
|
||||||
/** 线索3 */
|
/** 线索3（未通关时为 null） */
|
||||||
clue3: string;
|
clue3: string | null;
|
||||||
/** 答案 */
|
/** 答案（未通关时为 null，进入关卡后由 enter 接口获取） */
|
||||||
answer: string;
|
answer: string | null;
|
||||||
|
/** 是否已通关 */
|
||||||
|
completed: boolean;
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -15,8 +15,6 @@ export class AuthManager {
|
|||||||
private _isLoggedIn: boolean = false;
|
private _isLoggedIn: boolean = false;
|
||||||
/** 服务端返回的已完成关卡 ID（登录后暂存，等 LevelDataManager 就绪后同步） */
|
/** 服务端返回的已完成关卡 ID（登录后暂存，等 LevelDataManager 就绪后同步） */
|
||||||
private _completedLevelIds: string[] = [];
|
private _completedLevelIds: string[] = [];
|
||||||
/** 服务端返回的已完成关卡 ID（登录后暂存，等 LevelDataManager 就绪后同步） */
|
|
||||||
private _completedLevelIds: string[] = [];
|
|
||||||
|
|
||||||
static get instance(): AuthManager {
|
static get instance(): AuthManager {
|
||||||
if (!this._instance) {
|
if (!this._instance) {
|
||||||
@@ -88,12 +86,14 @@ export class AuthManager {
|
|||||||
|
|
||||||
this._userId = user.id;
|
this._userId = user.id;
|
||||||
this._isLoggedIn = true;
|
this._isLoggedIn = true;
|
||||||
StorageManager.setPoints(user.points);
|
|
||||||
|
|
||||||
// 获取通关进度
|
// 登录响应中 stamina 是原始数值（不含实时恢复），先存储默认体力
|
||||||
await this.fetchCompletedLevels();
|
// 后续通过 game-data 接口获取完整 StaminaInfo
|
||||||
|
console.log(`[AuthManager] 登录成功，用户: ${user.id}，体力: ${user.stamina}`);
|
||||||
|
|
||||||
|
// 获取通关进度和完整体力信息
|
||||||
|
await this.fetchGameData();
|
||||||
|
|
||||||
console.log(`[AuthManager] 登录成功，用户: ${user.id}，积分: ${user.points}`);
|
|
||||||
return true;
|
return true;
|
||||||
} catch (err) {
|
} catch (err) {
|
||||||
console.error('[AuthManager] 登录异常:', err);
|
console.error('[AuthManager] 登录异常:', err);
|
||||||
@@ -102,45 +102,42 @@ export class AuthManager {
|
|||||||
}
|
}
|
||||||
|
|
||||||
private async validateToken(): Promise<boolean> {
|
private async validateToken(): Promise<boolean> {
|
||||||
try {
|
const gameData = await this._fetchGameData();
|
||||||
const response = await HttpUtil.get<ApiEnvelope<GameData>>(
|
if (!gameData) return false;
|
||||||
API_ENDPOINTS.USER_GAME_DATA,
|
|
||||||
API_TIMEOUT.SHORT
|
|
||||||
);
|
|
||||||
|
|
||||||
if (!response.success || !response.data) {
|
this._userId = gameData.user.id;
|
||||||
return false;
|
this._isLoggedIn = true;
|
||||||
|
StorageManager.setStamina(gameData.user.stamina);
|
||||||
|
this._completedLevelIds = gameData.completedLevelIds;
|
||||||
|
|
||||||
|
console.log(`[AuthManager] Token 验证成功，体力: ${gameData.user.stamina.current}/${gameData.user.stamina.max}，已完成: ${this._completedLevelIds.length} 关`);
|
||||||
|
return true;
|
||||||
}
|
}
|
||||||
|
|
||||||
this._userId = response.data.user.id;
|
/**
|
||||||
this._isLoggedIn = true;
|
* 登录成功后获取游戏数据（体力 + 通关进度）
|
||||||
StorageManager.setPoints(response.data.user.points);
|
*/
|
||||||
this._completedLevelIds = response.data.completedLevelIds;
|
private async fetchGameData(): Promise<void> {
|
||||||
|
const gameData = await this._fetchGameData();
|
||||||
console.log(`[AuthManager] Token 验证成功，积分: ${response.data.user.points}，已完成: ${this._completedLevelIds.length} 关`);
|
if (gameData) {
|
||||||
return true;
|
this._completedLevelIds = gameData.completedLevelIds;
|
||||||
} catch {
|
StorageManager.setStamina(gameData.user.stamina);
|
||||||
return false;
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 登录成功后获取通关进度
|
* 从服务端获取游戏数据（共用方法）
|
||||||
*/
|
*/
|
||||||
private async fetchCompletedLevels(): Promise<void> {
|
private async _fetchGameData(): Promise<GameData | null> {
|
||||||
try {
|
try {
|
||||||
const response = await HttpUtil.get<ApiEnvelope<GameData>>(
|
const response = await HttpUtil.get<ApiEnvelope<GameData>>(
|
||||||
API_ENDPOINTS.USER_GAME_DATA,
|
API_ENDPOINTS.USER_GAME_DATA,
|
||||||
API_TIMEOUT.SHORT
|
API_TIMEOUT.SHORT
|
||||||
);
|
);
|
||||||
|
return (response.success && response.data) ? response.data : null;
|
||||||
if (response.success && response.data) {
|
|
||||||
this._completedLevelIds = response.data.completedLevelIds;
|
|
||||||
// 同步最新积分
|
|
||||||
StorageManager.setPoints(response.data.user.points);
|
|
||||||
}
|
|
||||||
} catch {
|
} catch {
|
||||||
console.warn('[AuthManager] 获取通关进度失败');
|
console.warn('[AuthManager] 获取游戏数据失败');
|
||||||
|
return null;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -109,6 +109,45 @@ export class LevelDataManager {
|
|||||||
return this._apiData.length;
|
return this._apiData.length;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 获取指定索引的关卡 ID
|
||||||
|
* @param index 关卡索引
|
||||||
|
*/
|
||||||
|
getLevelId(index: number): string | null {
|
||||||
|
if (index < 0 || index >= this._apiData.length) {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
return this._apiData[index].id;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 检查指定索引的关卡是否已通关
|
||||||
|
* @param index 关卡索引
|
||||||
|
*/
|
||||||
|
isLevelCompleted(index: number): boolean {
|
||||||
|
if (index < 0 || index >= this._apiData.length) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
return this._apiData[index].completed;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 标记指定关卡为已通关（本地缓存更新）
|
||||||
|
* @param index 关卡索引
|
||||||
|
*/
|
||||||
|
markLevelCompleted(index: number): void {
|
||||||
|
if (index < 0 || index >= this._apiData.length) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
this._apiData[index].completed = true;
|
||||||
|
|
||||||
|
// 同时更新运行时配置的 completed 状态
|
||||||
|
const config = this._levelConfigs.get(index);
|
||||||
|
if (config) {
|
||||||
|
this._levelConfigs.set(index, { ...config, completed: true });
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 根据已完成的关卡 ID 列表，计算最高已完成关卡索引
|
* 根据已完成的关卡 ID 列表，计算最高已完成关卡索引
|
||||||
* @param completedLevelIds 服务端返回的已完成关卡 ID
|
* @param completedLevelIds 服务端返回的已完成关卡 ID
|
||||||
@@ -191,6 +230,27 @@ export class LevelDataManager {
|
|||||||
return config;
|
return config;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 用 enter 接口返回的数据更新运行时关卡配置（填充答案和线索）
|
||||||
|
*/
|
||||||
|
updateLevelDetails(index: number, details: { answer: string; hint1: string | null; hint2: string | null; hint3: string | null }): void {
|
||||||
|
const config = this._levelConfigs.get(index);
|
||||||
|
if (!config) {
|
||||||
|
console.warn(`[LevelDataManager] 关卡 ${index} 配置不存在，无法更新详情`);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
this._levelConfigs.set(index, {
|
||||||
|
...config,
|
||||||
|
answer: details.answer,
|
||||||
|
clue1: details.hint1 ?? null,
|
||||||
|
clue2: details.hint2 ?? null,
|
||||||
|
clue3: details.hint3 ?? null,
|
||||||
|
});
|
||||||
|
|
||||||
|
console.log(`[LevelDataManager] 关卡 ${index} 详情已更新`);
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 预加载下一关图片（静默加载，不阻塞）
|
* 预加载下一关图片（静默加载，不阻塞）
|
||||||
* 在进入当前关卡后调用，提前加载下一关资源
|
* 在进入当前关卡后调用，提前加载下一关资源
|
||||||
@@ -278,7 +338,8 @@ export class LevelDataManager {
|
|||||||
clue1: data.hint1,
|
clue1: data.hint1,
|
||||||
clue2: data.hint2,
|
clue2: data.hint2,
|
||||||
clue3: data.hint3,
|
clue3: data.hint3,
|
||||||
answer: data.answer
|
answer: data.answer,
|
||||||
|
completed: data.completed,
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
110
assets/scripts/utils/StaminaManager.ts
Normal file
110
assets/scripts/utils/StaminaManager.ts
Normal file
@@ -0,0 +1,110 @@
|
|||||||
|
import { HttpUtil } from './HttpUtil';
|
||||||
|
import { StorageManager } from './StorageManager';
|
||||||
|
import { AuthManager } from './AuthManager';
|
||||||
|
import { API_TIMEOUT, getLevelEnterUrl, getLevelCompleteUrl } from '../config/ApiConfig';
|
||||||
|
import { ApiEnvelope, StaminaInfo, EnterLevelData, CompleteLevelData } from '../types/ApiTypes';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 体力值管理器
|
||||||
|
* 单例模式，负责体力值的服务端同步、进入关卡和通关上报
|
||||||
|
* 以服务端为准，本地 StorageManager 作为缓存
|
||||||
|
*/
|
||||||
|
export class StaminaManager {
|
||||||
|
private static _instance: StaminaManager | null = null;
|
||||||
|
|
||||||
|
static get instance(): StaminaManager {
|
||||||
|
if (!this._instance) {
|
||||||
|
this._instance = new StaminaManager();
|
||||||
|
}
|
||||||
|
return this._instance;
|
||||||
|
}
|
||||||
|
|
||||||
|
private constructor() {}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 获取当前体力信息（从本地缓存）
|
||||||
|
*/
|
||||||
|
getStamina(): StaminaInfo {
|
||||||
|
return StorageManager.getStamina();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 更新本地缓存的体力信息
|
||||||
|
* @param stamina 服务端返回的体力信息
|
||||||
|
*/
|
||||||
|
updateStamina(stamina: StaminaInfo): void {
|
||||||
|
StorageManager.setStamina(stamina);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 检查当前是否有足够的体力
|
||||||
|
*/
|
||||||
|
hasStamina(): boolean {
|
||||||
|
return StorageManager.hasStamina();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 进入关卡
|
||||||
|
* 消耗 1 点体力（未通关关卡），获取完整关卡详情（含答案和线索）
|
||||||
|
* @param levelId 关卡 ID
|
||||||
|
* @returns 关卡详情，失败时返回 null
|
||||||
|
*/
|
||||||
|
async enterLevel(levelId: string): Promise<EnterLevelData | null> {
|
||||||
|
if (!AuthManager.instance.isLoggedIn) {
|
||||||
|
console.warn('[StaminaManager] 未登录，无法进入关卡');
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
try {
|
||||||
|
const response = await HttpUtil.post<ApiEnvelope<EnterLevelData>>(
|
||||||
|
getLevelEnterUrl(levelId),
|
||||||
|
{},
|
||||||
|
API_TIMEOUT.DEFAULT
|
||||||
|
);
|
||||||
|
|
||||||
|
if (response.success && response.data) {
|
||||||
|
StorageManager.setStamina(response.data.stamina);
|
||||||
|
console.log(`[StaminaManager] 进入关卡 ${levelId}，体力: ${response.data.stamina.current}/${response.data.stamina.max}`);
|
||||||
|
return response.data;
|
||||||
|
}
|
||||||
|
|
||||||
|
console.warn('[StaminaManager] 进入关卡失败:', response.message);
|
||||||
|
return null;
|
||||||
|
} catch (err) {
|
||||||
|
console.error('[StaminaManager] 进入关卡请求失败:', err);
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 通关上报
|
||||||
|
* @param levelId 关卡 ID
|
||||||
|
* @param timeSpent 通关耗时（秒）
|
||||||
|
* @returns 通关响应，失败时返回 null
|
||||||
|
*/
|
||||||
|
async completeLevel(levelId: string, timeSpent: number): Promise<CompleteLevelData | null> {
|
||||||
|
if (!AuthManager.instance.isLoggedIn) {
|
||||||
|
console.warn('[StaminaManager] 未登录，无法上报通关');
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
try {
|
||||||
|
const response = await HttpUtil.post<ApiEnvelope<CompleteLevelData>>(
|
||||||
|
getLevelCompleteUrl(levelId),
|
||||||
|
{ timeSpent },
|
||||||
|
API_TIMEOUT.DEFAULT
|
||||||
|
);
|
||||||
|
|
||||||
|
if (response.success && response.data) {
|
||||||
|
console.log(`[StaminaManager] 通关上报成功: ${levelId}, 首次: ${response.data.firstClear}, 耗时: ${response.data.timeSpent}s`);
|
||||||
|
return response.data;
|
||||||
|
}
|
||||||
|
|
||||||
|
console.warn('[StaminaManager] 通关上报失败:', response.message);
|
||||||
|
return null;
|
||||||
|
} catch (err) {
|
||||||
|
console.error('[StaminaManager] 通关上报请求失败:', err);
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -2,7 +2,7 @@
|
|||||||
"ver": "4.0.24",
|
"ver": "4.0.24",
|
||||||
"importer": "typescript",
|
"importer": "typescript",
|
||||||
"imported": true,
|
"imported": true,
|
||||||
"uuid": "ddba71db-75ed-468d-ac99-b4632c0b2ae4",
|
"uuid": "7fb84423-af68-468c-a17b-7bdd195eb815",
|
||||||
"files": [],
|
"files": [],
|
||||||
"subMetas": {},
|
"subMetas": {},
|
||||||
"userData": {}
|
"userData": {}
|
||||||
@@ -1,4 +1,5 @@
|
|||||||
import { sys } from 'cc';
|
import { sys } from 'cc';
|
||||||
|
import { StaminaInfo } from '../types/ApiTypes';
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 用户进度数据结构
|
* 用户进度数据结构
|
||||||
@@ -10,13 +11,21 @@ interface UserProgress {
|
|||||||
maxUnlockedLevelIndex: number;
|
maxUnlockedLevelIndex: number;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 用户信息结构
|
||||||
|
*/
|
||||||
|
interface UserInfo {
|
||||||
|
avatarUrl: string;
|
||||||
|
nickName: string;
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 本地存储管理器
|
* 本地存储管理器
|
||||||
* 统一管理用户数据的本地持久化存储
|
* 统一管理用户数据的本地持久化存储
|
||||||
*/
|
*/
|
||||||
export class StorageManager {
|
export class StorageManager {
|
||||||
/** 积分存储键 */
|
/** 体力值存储键 */
|
||||||
private static readonly KEY_POINTS = 'game_points';
|
private static readonly KEY_STAMINA = 'game_stamina';
|
||||||
|
|
||||||
/** 用户进度存储键 */
|
/** 用户进度存储键 */
|
||||||
private static readonly KEY_PROGRESS = 'game_progress';
|
private static readonly KEY_PROGRESS = 'game_progress';
|
||||||
@@ -27,11 +36,12 @@ export class StorageManager {
|
|||||||
/** 用户信息存储键 */
|
/** 用户信息存储键 */
|
||||||
private static readonly KEY_USER_INFO = 'user_info';
|
private static readonly KEY_USER_INFO = 'user_info';
|
||||||
|
|
||||||
/** 默认积分 */
|
/** 默认体力值 */
|
||||||
private static readonly DEFAULT_POINTS = 10;
|
private static readonly DEFAULT_STAMINA: StaminaInfo = {
|
||||||
|
current: 5,
|
||||||
/** 最小积分 */
|
max: 5,
|
||||||
private static readonly MIN_POINTS = 0;
|
nextRecoverAt: null,
|
||||||
|
};
|
||||||
|
|
||||||
/** 默认进度 */
|
/** 默认进度 */
|
||||||
private static readonly DEFAULT_PROGRESS: UserProgress = {
|
private static readonly DEFAULT_PROGRESS: UserProgress = {
|
||||||
@@ -42,75 +52,52 @@ export class StorageManager {
|
|||||||
/** 进度缓存（避免重复读取 localStorage） */
|
/** 进度缓存（避免重复读取 localStorage） */
|
||||||
private static _progressCache: UserProgress | null = null;
|
private static _progressCache: UserProgress | null = null;
|
||||||
|
|
||||||
// ==================== 积分管理 ====================
|
/** 体力缓存（避免重复 JSON 解析） */
|
||||||
|
private static _staminaCache: StaminaInfo | null = null;
|
||||||
|
|
||||||
|
// ==================== 体力值管理 ====================
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 获取当前积分
|
* 获取当前体力信息（带内存缓存，避免重复 JSON 解析）
|
||||||
* @returns 当前积分，新用户返回默认值 10
|
|
||||||
*/
|
*/
|
||||||
static getPoints(): number {
|
static getStamina(): StaminaInfo {
|
||||||
const stored = sys.localStorage.getItem(StorageManager.KEY_POINTS);
|
if (StorageManager._staminaCache) {
|
||||||
|
return { ...StorageManager._staminaCache };
|
||||||
|
}
|
||||||
|
|
||||||
|
const stored = sys.localStorage.getItem(StorageManager.KEY_STAMINA);
|
||||||
if (stored === null || stored === '') {
|
if (stored === null || stored === '') {
|
||||||
// 新用户，设置默认值
|
StorageManager.setStamina(StorageManager.DEFAULT_STAMINA);
|
||||||
StorageManager.setPoints(StorageManager.DEFAULT_POINTS);
|
return { ...StorageManager.DEFAULT_STAMINA };
|
||||||
return StorageManager.DEFAULT_POINTS;
|
|
||||||
}
|
}
|
||||||
const points = parseInt(stored, 10);
|
try {
|
||||||
// 防止异常数据
|
const stamina = JSON.parse(stored) as StaminaInfo;
|
||||||
if (isNaN(points) || points < 0) {
|
if (typeof stamina.current !== 'number' || typeof stamina.max !== 'number') {
|
||||||
StorageManager.setPoints(StorageManager.DEFAULT_POINTS);
|
StorageManager.setStamina(StorageManager.DEFAULT_STAMINA);
|
||||||
return StorageManager.DEFAULT_POINTS;
|
return { ...StorageManager.DEFAULT_STAMINA };
|
||||||
|
}
|
||||||
|
StorageManager._staminaCache = stamina;
|
||||||
|
return { ...stamina };
|
||||||
|
} catch {
|
||||||
|
StorageManager.setStamina(StorageManager.DEFAULT_STAMINA);
|
||||||
|
return { ...StorageManager.DEFAULT_STAMINA };
|
||||||
}
|
}
|
||||||
return points;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 设置积分
|
* 设置体力信息（同时更新缓存）
|
||||||
* @param points 积分
|
|
||||||
*/
|
*/
|
||||||
static setPoints(points: number): void {
|
static setStamina(stamina: StaminaInfo): void {
|
||||||
const validPoints = Math.max(StorageManager.MIN_POINTS, points);
|
StorageManager._staminaCache = stamina;
|
||||||
sys.localStorage.setItem(StorageManager.KEY_POINTS, validPoints.toString());
|
sys.localStorage.setItem(StorageManager.KEY_STAMINA, JSON.stringify(stamina));
|
||||||
console.log(`[StorageManager] 积分已更新: ${validPoints}`);
|
console.log(`[StorageManager] 体力已更新: ${stamina.current}/${stamina.max}`);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 消耗一个积分
|
* 检查是否有足够的体力
|
||||||
* @returns 是否消耗成功（积分不足时返回 false）
|
|
||||||
*/
|
*/
|
||||||
static consumePoint(): boolean {
|
static hasStamina(): boolean {
|
||||||
const currentPoints = StorageManager.getPoints();
|
return StorageManager.getStamina().current > 0;
|
||||||
if (currentPoints <= 0) {
|
|
||||||
console.warn('[StorageManager] 积分不足，无法消耗');
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
StorageManager.setPoints(currentPoints - 1);
|
|
||||||
return true;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* 增加一个积分
|
|
||||||
*/
|
|
||||||
static addPoint(): void {
|
|
||||||
const currentPoints = StorageManager.getPoints();
|
|
||||||
StorageManager.setPoints(currentPoints + 1);
|
|
||||||
console.log(`[StorageManager] 获得一个积分，当前积分: ${currentPoints + 1}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* 检查是否有足够的积分
|
|
||||||
* @returns 是否有积分
|
|
||||||
*/
|
|
||||||
static hasPoints(): boolean {
|
|
||||||
return StorageManager.getPoints() > 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* 重置积分为默认值
|
|
||||||
*/
|
|
||||||
static resetPoints(): void {
|
|
||||||
StorageManager.setPoints(StorageManager.DEFAULT_POINTS);
|
|
||||||
console.log('[StorageManager] 积分已重置为默认值');
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// ==================== 认证 Token 管理 ====================
|
// ==================== 认证 Token 管理 ====================
|
||||||
@@ -261,10 +248,10 @@ export class StorageManager {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 重置所有数据（积分 + 进度）
|
* 重置所有数据（体力 + 进度）
|
||||||
*/
|
*/
|
||||||
static resetAll(): void {
|
static resetAll(): void {
|
||||||
StorageManager.resetPoints();
|
StorageManager.setStamina(StorageManager.DEFAULT_STAMINA);
|
||||||
StorageManager.resetProgress();
|
StorageManager.resetProgress();
|
||||||
StorageManager.clearToken();
|
StorageManager.clearToken();
|
||||||
StorageManager.clearUserInfo();
|
StorageManager.clearUserInfo();
|
||||||
@@ -273,14 +260,6 @@ export class StorageManager {
|
|||||||
|
|
||||||
// ==================== 用户信息管理 ====================
|
// ==================== 用户信息管理 ====================
|
||||||
|
|
||||||
/**
|
|
||||||
* 用户信息结构
|
|
||||||
*/
|
|
||||||
interface UserInfo {
|
|
||||||
avatarUrl: string;
|
|
||||||
nickName: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 保存用户信息（头像、昵称）
|
* 保存用户信息（头像、昵称）
|
||||||
* @param userInfo 用户信息对象
|
* @param userInfo 用户信息对象
|
||||||
|
|||||||
@@ -1,120 +0,0 @@
|
|||||||
import { HttpUtil } from './HttpUtil';
|
|
||||||
import { StorageManager } from './StorageManager';
|
|
||||||
import { AuthManager } from './AuthManager';
|
|
||||||
import { API_ENDPOINTS, API_TIMEOUT, POINT_REASONS } from '../config/ApiConfig';
|
|
||||||
import { ApiEnvelope, UserAssetsData } from '../types/ApiTypes';
|
|
||||||
|
|
||||||
/**
|
|
||||||
* 用户资产管理器
|
|
||||||
* 单例模式，负责积分的服务端同步
|
|
||||||
* 以服务端为准，本地 StorageManager 作为缓存
|
|
||||||
*/
|
|
||||||
export class UserAssetsManager {
|
|
||||||
private static _instance: UserAssetsManager | null = null;
|
|
||||||
|
|
||||||
static get instance(): UserAssetsManager {
|
|
||||||
if (!this._instance) {
|
|
||||||
this._instance = new UserAssetsManager();
|
|
||||||
}
|
|
||||||
return this._instance;
|
|
||||||
}
|
|
||||||
|
|
||||||
private constructor() {}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* 从服务端获取最新积分
|
|
||||||
*/
|
|
||||||
async fetchPoints(): Promise<number> {
|
|
||||||
if (!AuthManager.instance.isLoggedIn) {
|
|
||||||
return StorageManager.getPoints();
|
|
||||||
}
|
|
||||||
|
|
||||||
try {
|
|
||||||
const response = await HttpUtil.get<ApiEnvelope<UserAssetsData>>(
|
|
||||||
API_ENDPOINTS.USER_ASSETS,
|
|
||||||
API_TIMEOUT.SHORT
|
|
||||||
);
|
|
||||||
|
|
||||||
if (response.success && response.data) {
|
|
||||||
StorageManager.setPoints(response.data.points);
|
|
||||||
return response.data.points;
|
|
||||||
}
|
|
||||||
} catch (err) {
|
|
||||||
console.error('[UserAssetsManager] 获取积分失败:', err);
|
|
||||||
}
|
|
||||||
|
|
||||||
return StorageManager.getPoints();
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* 消耗积分（解锁提示）
|
|
||||||
* @returns 是否消耗成功
|
|
||||||
*/
|
|
||||||
async consumePoint(levelId?: string, hintIndex?: number): Promise<boolean> {
|
|
||||||
if (!StorageManager.hasPoints()) {
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (!AuthManager.instance.isLoggedIn) {
|
|
||||||
return StorageManager.consumePoint();
|
|
||||||
}
|
|
||||||
|
|
||||||
try {
|
|
||||||
const response = await HttpUtil.post<ApiEnvelope<UserAssetsData>>(
|
|
||||||
API_ENDPOINTS.USER_ASSETS_CONSUME,
|
|
||||||
{
|
|
||||||
reason: POINT_REASONS.HINT_UNLOCK,
|
|
||||||
levelId,
|
|
||||||
hintIndex,
|
|
||||||
},
|
|
||||||
API_TIMEOUT.SHORT
|
|
||||||
);
|
|
||||||
|
|
||||||
if (response.success && response.data) {
|
|
||||||
StorageManager.setPoints(response.data.points);
|
|
||||||
return true;
|
|
||||||
} else {
|
|
||||||
console.warn('[UserAssetsManager] 消耗积分失败:', response.message);
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
} catch (err) {
|
|
||||||
console.error('[UserAssetsManager] 消耗积分请求失败，降级本地处理:', err);
|
|
||||||
return StorageManager.consumePoint();
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* 获得积分（通关奖励）
|
|
||||||
* @param levelId 关卡ID
|
|
||||||
* @param timeSpent 通关耗时（秒）
|
|
||||||
* @returns 获得后的积分数
|
|
||||||
*/
|
|
||||||
async earnPoint(levelId: string, timeSpent: number): Promise<number> {
|
|
||||||
if (!AuthManager.instance.isLoggedIn) {
|
|
||||||
StorageManager.addPoint();
|
|
||||||
return StorageManager.getPoints();
|
|
||||||
}
|
|
||||||
|
|
||||||
try {
|
|
||||||
const response = await HttpUtil.post<ApiEnvelope<UserAssetsData>>(
|
|
||||||
API_ENDPOINTS.USER_ASSETS_EARN,
|
|
||||||
{
|
|
||||||
reason: POINT_REASONS.LEVEL_COMPLETE,
|
|
||||||
levelId,
|
|
||||||
timeSpent,
|
|
||||||
},
|
|
||||||
API_TIMEOUT.SHORT
|
|
||||||
);
|
|
||||||
|
|
||||||
if (response.success && response.data) {
|
|
||||||
StorageManager.setPoints(response.data.points);
|
|
||||||
return response.data.points;
|
|
||||||
}
|
|
||||||
} catch (err) {
|
|
||||||
console.error('[UserAssetsManager] 获得积分请求失败，降级本地处理:', err);
|
|
||||||
}
|
|
||||||
|
|
||||||
StorageManager.addPoint();
|
|
||||||
return StorageManager.getPoints();
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@@ -39,7 +39,7 @@ export class WxSDK {
|
|||||||
/**
|
/**
|
||||||
* 获取 wx 全局对象（仅微信环境下可用）
|
* 获取 wx 全局对象（仅微信环境下可用）
|
||||||
*/
|
*/
|
||||||
private static getWx(): any {
|
static getWx(): any {
|
||||||
if (!WxSDK.isWechat()) return null;
|
if (!WxSDK.isWechat()) return null;
|
||||||
return typeof wx !== 'undefined' ? wx : null;
|
return typeof wx !== 'undefined' ? wx : null;
|
||||||
}
|
}
|
||||||
@@ -217,6 +217,84 @@ export class WxSDK {
|
|||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// ==================== 激励视频广告 ====================
|
||||||
|
|
||||||
|
/** 激励视频广告实例（复用） */
|
||||||
|
private static _rewardedVideoAd: any = null;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 展示激励视频广告
|
||||||
|
* 用户看完广告后返回 true，中途退出或失败返回 false
|
||||||
|
* 非微信环境直接返回 true（开发模式直接通过）
|
||||||
|
* @param adUnitId 广告单元 ID（默认使用项目配置的 ID）
|
||||||
|
* @returns Promise<boolean> 是否看完广告
|
||||||
|
*/
|
||||||
|
static showRewardedVideoAd(adUnitId: string = ''): Promise<boolean> {
|
||||||
|
return new Promise((resolve) => {
|
||||||
|
const wxApi = WxSDK.getWx();
|
||||||
|
if (!wxApi) {
|
||||||
|
console.log('[WxSDK] 非微信环境，跳过激励视频广告');
|
||||||
|
resolve(true);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (typeof wxApi.createRewardedVideoAd !== 'function') {
|
||||||
|
console.warn('[WxSDK] 当前微信版本不支持激励视频广告');
|
||||||
|
resolve(true);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
try {
|
||||||
|
// 复用或创建广告实例
|
||||||
|
if (!WxSDK._rewardedVideoAd) {
|
||||||
|
WxSDK._rewardedVideoAd = wxApi.createRewardedVideoAd({
|
||||||
|
adUnitId: adUnitId,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
const ad = WxSDK._rewardedVideoAd;
|
||||||
|
|
||||||
|
// 定义关闭回调（一次性）
|
||||||
|
const onClose = (res: any) => {
|
||||||
|
ad.offClose(onClose);
|
||||||
|
if (res && res.isEnded) {
|
||||||
|
console.log('[WxSDK] 激励视频广告观看完成');
|
||||||
|
resolve(true);
|
||||||
|
} else {
|
||||||
|
console.log('[WxSDK] 激励视频广告中途退出');
|
||||||
|
resolve(false);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// 定义错误回调（一次性）
|
||||||
|
const onError = (err: any) => {
|
||||||
|
ad.offError(onError);
|
||||||
|
ad.offClose(onClose);
|
||||||
|
console.error('[WxSDK] 激励视频广告错误:', err);
|
||||||
|
resolve(false);
|
||||||
|
};
|
||||||
|
|
||||||
|
ad.onClose(onClose);
|
||||||
|
ad.onError(onError);
|
||||||
|
|
||||||
|
// 先尝试 show，如果广告未加载则先 load
|
||||||
|
ad.show().catch(() => {
|
||||||
|
ad.load().then(() => ad.show()).catch((loadErr: any) => {
|
||||||
|
ad.offClose(onClose);
|
||||||
|
ad.offError(onError);
|
||||||
|
console.error('[WxSDK] 激励视频广告加载失败:', loadErr);
|
||||||
|
resolve(false);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
} catch (err) {
|
||||||
|
console.error('[WxSDK] 激励视频广告异常:', err);
|
||||||
|
resolve(false);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
// ==================== 启动参数 ====================
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* 从启动参数中获取分享码
|
* 从启动参数中获取分享码
|
||||||
* @returns 分享码，不存在则返回 null
|
* @returns 分享码，不存在则返回 null
|
||||||
|
|||||||
Reference in New Issue
Block a user