cocos-standalone-test

# 🪷 Cocos Creator Standalone HTML 快速測試 ## 背景 佛心項目嘅遊戲用 Cocos Creator 3.x 開發，需要 Cocos Creator IDE 先可以 compile TypeScript。但好多時候我哋唔方便開 IDE，或者想快速驗證邏輯先再做正式 build。 呢個 workflow 提供一個快速測試方法。 ## 步驟 ### 1. 確認需求 師兄想測試某個遊戲功能。如果只係邏輯層面（劇情引擎、選擇系統、功德系統等），可以用 standalone HTML 做快速驗證。 ### 2. 建立測試 HTML 喺 `BuddhaHeart_Game/build/web-mobile/` 建立 `test-story.html`（或 `test-xxx.html`），做以下轉換： **TypeScript → JavaScript 轉換規則：** | TypeScript（Cocos） | JavaScript（Standalone） | |---------------------|------------------------| | `import { ... } from 'cc'` | 移除，改用純 JS | | `@_decorator.ccclass('X')` | 移除，用 class / object | | `@_decorator.property(...)` | 移除，直接初始化 | | `Component, Node, Label, Button, tween` | 用 DOM API + CSS 動畫代替 | | `this.node.emit(...)` | 用自訂 EventTarget / callback | | TypeScript type annotation | 移除 | ### 3. 核心 UI 元素對應 | Cocos 元素 | HTML 對應 | |-----------|-----------| | Scene node | `<div id="app">` | | Label | `<div>` or `<p>` with CSS font styling | | Button | `<button>` with CSS | | Sprite / color | CSS `background`, `color` | | tween | CSS `transition` + `animation` | | Button.EventType.CLICK | `element.addEventListener('click', ...)` | ### 4. 啟動測試 ```bash cd BuddhaHeart_Game/build/web-mobile && python3 -m http.server 8080 ``` 然後用 browser 打開 `http://localhost:8080/test-story.html` ### 5. 測試方法 - 用 browser tool 操作 UI（click 按鈕、睇文字變化） - 用 browser_snapshot 睇 DOM 狀態（睇到文字、按鈕等內容） - 用 browser_vision 截圖確認視覺效果（可 Send 俾師兄睇） - 檢查邏輯是否正確（功德值計算、劇情分支、結局條件） - 行晒所有可能路線，確保每個分支同結局都正常 ### 6. 完成後 - Kill server：`process(action='kill', session_id='...')` - 知會師兄測試結果 - 如果測試 pass，將邏輯保留返喺正式 `.ts` 檔案中 - 測試用嘅 `test-story.html` 可以保留或刪除 ## No Compile, No Commit — TypeScript 強制編譯規則 Cocos Creator 項目改 code 後，commit 前必須做 TypeScript compile check： 1. 確保 `node_modules/typescript` 已安裝：`npm install typescript` 2. 確保 `types/cc.d.ts` 存在（mock Cocos 3.x 類型宣告，因 cocos-creator-3d 不在 npm registry） 3. 確保 `tsconfig.phase6.json` 存在（獨立 config，用 typeRoots 指向 types/，只 include 新 code 排除舊 code） 4. Run: `npx tsc --noEmit -p tsconfig.phase6.json` 5. **零 error 先可以 commit**。自行修復所有報錯。 常見 TS error 同修復： | Error | 原因 | 修復 | |-------|------|------| | `cc.Vec3` not found | 用咗舊 Cocos 2.x `cc.xxx` 語法 | 改用 ES6 import + `Vec3` | | `'scale' not in Partial<Node>` | Tween type 唔夠闊 | 在 cc.d.ts 加 `TweenProps` interface | | `property X not exist` | spread 咗唔喺 interface 嘅 field | `as any` cast | | `?? unreachable` | `?.` operator 順序問題 | 改用明確變量 + if-else | ## 注意事項 - Standalone HTML 用純 JS，**唔可以**直接用 Cocos API（`cc` namespace） - 動畫效果會比 Cocos 版本簡陋，呢個係正常嘅 - 只適合測試邏輯，UI 精緻度要用 Cocos IDE 先做到 - 如果師兄想見到正式畫面，需要 Cocos Creator 打開 project build ## 輸出長度限制處理（關鍵技巧） 大嘅 standalone 測試頁（SocialUI + 控制邏輯，>30KB）好容易超出模型 output 上限。**解決方法：分步寫入法** ### 步驟 A：先寫 HTML 骨架 + CSS（write_file） 一次性寫 HTML head、body 結構、style block、DOM element 骨架。呢 part 約 8-15KB。 ### 步驟 B：分開 patch JS adapter 部分 JS block（inline adapter、managers、控制邏輯）佔最大篇幅。用多個 `patch` 命令分段加入： 1. **第一次 patch**：SocialUI inline renderer（UI 生成函數 + CSS getter） 2. **第二次 patch**：SocialIntegration bridge（createSocialIntegration, helper functions, event binding） 3. **第三次 patch**：初始化代碼 + 快速操作按鈕 + 測試頁尾部 咁樣每個 patch 約 8-12KB，遠低於 output 上限，唔會爆長度。 ### 通用規則 - 任何超過 15KB 嘅檔案，考慮分拆為「骨架 + N次 patch」 - TypeScript adapter（繞過 Cocos decorator 嘅 JS class）係最大舊嘅，要放最後 patch - 多個 managers 各自 patch 會更穩定