Spaces:
Running
Running
| # Skills & Best Practices - Math City Project | |
| 此文件記錄本專案開發過程中的技術規範、設計模式、教學設計哲學與除錯經驗，供後續開發參考。 | |
| ## 1. 技術架構與規範 (Tech Stack & Guidelines) | |
| ### 核心技術 | |
| * **核心**: HTML5 Canvas + Vanilla JS (ES6+)。 | |
| * **樣式**: Tailwind CSS (CDN read-only 模式) + Custom CSS (for animations/glassmorphism)。 | |
| * **字體**: 'Orbitron' (數字符號/標題), 'Noto Sans TC' (中文內文)。 | |
| * **建置**: 無須 Build Tool (No Webpack/Vite)，保持單檔可執行 (`.html`)，方便老師分享與部署。 | |
| ### 程式碼規範 | |
| * **語言**: 註解與文件說明嚴格使用**繁體中文**，變數與函數名稱使用**英文**。 | |
| * **檔案結構**: 保持扁平，html 檔包含 CSS/JS 為主 (方便單檔攜帶)，通用素材放 `Assets/`。 | |
| * **狀態管理**: 使用整數常數定義狀態機 (`const STATE = { INIT: 0, PLAYING: 1 ... }`)，避免字串混淆。 | |
| ## 2. 視覺與互動設計 (UI/UX Patterns) | |
| ### 視覺風格：Glassmorphism (玻璃擬態) | |
| * 背景使用 `backdrop-filter: blur(12px)` 搭配半透明深色背景 (`bg-slate-900/90`)。 | |
| * 邊框使用亮色且低透明度 (`border-cyan-500/30`) 營造科技質感。 | |
| * 善用 `box-shadow` 與 `drop-shadow` 營造霓虹發光效果。 | |
| ### Canvas 渲染優化 | |
| * **High-DPI 支援**: | |
| * 在 Retina 螢幕上，務必處理 `devicePixelRatio`。 | |
| * Canvas 屬性寬高 = CSS 寬高 * dpr。 | |
| * Context 縮放: `ctx.scale(dpr, dpr)`。 | |
| ```javascript | |
| const dpr = window.devicePixelRatio || 1; | |
| canvas.width = width * dpr; | |
| canvas.height = height * dpr; | |
| canvas.style.width = width + 'px'; | |
| canvas.style.height = height + 'px'; | |
| ctx.scale(dpr, dpr); | |
| ``` | |
| ### 行動裝置適配 (Mobile Adaptation) | |
| * **禁止捲動/縮放**: | |
| * CSS: `touch-action: none; user-select: none; -webkit-user-select: none;` | |
| * JS: 監聽 `touchstart` / `touchmove` 並執行 `e.preventDefault()` (需加 `{ passive: false }`)。 | |
| * **虛擬鍵盤 (Virtual Keypad)**: | |
| * iOS/Android 預設軟鍵盤會推擠版面，破壞全螢幕體驗。 | |
| * **解決方案**: 自製 DOM 虛擬鍵盤，支援拖曳 (Draggable) 與自動定位。 | |
| * **點擊穿透處理**: 鍵盤點擊事件需 `e.stopPropagation()`。 | |
| ## 3. 遊戲邏輯與物理 (Game Mechanics) | |
| ### 物理引擎 (Physics) | |
| * **Coyote Time (土狼時間)**: | |
| * 在玩家離開平台的一小段時間內 (例如 0.13秒) 仍允許跳躍，增加操作手感容錯率。 | |
| * 實作: 設置 `coyoteTimer`，只要在地上就重置，離地後遞減，大於 0 時仍視為可跳躍。 | |
| * **時間步長 (Time Step)**: | |
| * 目前使用簡易的 `requestAnimationFrame` 迴圈。若需更精準物理，考慮導入 Delta Time (`dt`)。 | |
| ### 遊戲反饋 (Juice & Feedback) | |
| * **動畫選擇**: | |
| * 錯誤提示避免使用滑稽的 `bounce`，改用嚴肅且有質感的 `pulse` (呼吸燈) + 紅色邊框。 | |
| * **音效合成 (Web Audio API)**: | |
| * 不依賴外部 mp3 檔案，使用 `OscillatorNode` 即時合成音效 (Sine, Square, Sawtooth)。 | |
| * 優點：無載入時間、檔案極小、可動態改變頻率 (Pitch Bend)。 | |
| * **注意**: 必須使用者互動 (Click/Touch) 後才能 `resume()` AudioContext。 | |
| ## 4. 數學教學設計 (Pedagogy Design) | |
| ### 鷹架理論 (Scaffolding) | |
| * **不僅僅是給答案**: 錯誤訊息應轉化為引導問題。 | |
| * *Bad*: "答錯了！" | |
| * *Good*: "如果 x=2, y=11, 但公式是 y=2x+b, 所以 b 是多少？" | |
| * **變數分離**: | |
| * 在解 $y=ax+b$ 時，先令 $x=0$ 解 $b$，再令 $x=1$ 解 $a$，避免同時處理雙變數的認知負荷。 | |
| ### 視覺化連結 (Visual-Algebra Connection) | |
| * **多重表徵連結**: 當計算出代數答案 (例如 y=35) 時，程式應同步強調圖表上的對應幾何點 (10, 35)，強化「數形合一」的概念。 | |
| ### 正向回饋 (Positive Feedback) | |
| * 避免挫折感，將艱澀的計算任務後的獎勵極大化 (例如：華麗的煙火、Phase 6 的節奏遊戲)，讓大腦獲得多巴胺釋放。 | |
| ## 5. Agent 開發工作流 (Agent Workflow) | |
| ### 任務邊界 (Task Boundary) | |
| * 使用 `task_boundary` 明確區分 **PLANNING** (規劃)、**EXECUTION** (執行) 與 **VERIFICATION** (驗證) 階段。 | |
| * **Context Management**: 保持對話專注，一個 Task 解決一個具體問題。 | |
| ### Artifacts 使用 | |
| * **Implementation Plan**: 修改複雜邏輯前，先撰寫 `implementation_plan.md` 讓使用者確認設計思路。 | |
| * **Walkthrough**: 完成功能後，建立 `walkthrough.md` 展示成果與測試截圖。 | |
| ## 6. 已知問題與解決 (Troubleshooting Log) | |
| * **問題**: 平台消失後的透明牆導致玩家卡住。 | |
| * **解法**: 物理碰撞檢測時，需過濾掉 `active: false` 的平台物件。 | |
| * **問題**: Home 鍵在全螢幕模式下難以點擊。 | |
| * **解法**: 確保 UI 層級 (`z-index`) 正確，並添加 `pointer-events-auto` 到按鈕本身，而容器保持 `pointer-events-none`。 | |
| * **問題**: 數列峽谷中，只有前兩項有提示，後續太難。 | |
| * **解法**: 設計意圖就是強制計算。但為了公平，統一了所有平台的視覺 (碎石紋理)，避免玩家嘗試「辨色」而非「計算」。 | |
| --- | |
| *Created by Antigravity Team for Project 11402* | |