skills.md

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)。

  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