Update README.md

README.md

@@ -1,130 +1,140 @@
-# Math City: Cyber Chronicles (數學特區：未來都市)
-
-## 1. 專案願景 (Project Vision)
-本專案為八年級下學期數學課程的遊戲化教學平台。透過「未來都市」的沉浸式包裝，讓學生以「特務/維護者」的身分，在解決城市危機的過程中學習數學概念。
-
-**核心體驗**：
-*   **平台**：iPad 橫向全螢幕體驗 (Mobile Web App)。
-*   **風格**：Cyberpunk / Neon Noir (賽博龐克/霓虹暗黑)。
-*   **技術**：HTML5 Canvas + Tailwind CSS + Vanilla JS (無須建置工具)。
-
-## 2. 檔案結構 (File Structure)
-```
-/
-├── index.html          # [入口] 城市全息地圖 (Math City Map)
-├── sequence.html       # [數列] 數列峽谷 (The Glitch Canyon)
-├── function.html       # [函數] 能源核心 (The Energy Core)
-├── congruence.html     # [全等] 全等重案組 (Congruence District) - {待開發}
-├── parallel.html       # [平行] 平行建構區 (Parallel Skyline) - {待開發}
-└── assets/             # (建議) 存放圖片與音效資源
-```
-
-## 3. 視覺設計系統 (Design System)
-
-### 色彩計畫 (Neon Palette)
-這座城市由四個區域組成，每個區域有其代表的主色調：
-*   **🟦 能源核心 (Cyan)**: `#06b6d4` (Cyan-500) - 代表科技、冷靜、函數邏輯。
-*   **🟨 數列峽谷 (Amber)**: `#f59e0b` (Amber-500) - 代表古老遺跡、警示、規律。
-*   **🟪 全等重案組 (Magenta)**: `#d946ef` (Fuchsia-500) - 代表神秘、霓虹街頭、偵探氛圍。
-*   **🟩 平行建構區 (Green)**: `#22c55e` (Green-500) - 代表建設、雷射光束、結構。
-*   **🌑 背景基調**: `#050510` (Very Dark Blue) - 極致黑，襯托霓虹光。
-
-### UI 規範
-*   **字體**: 'Orbitron' (數字/英文標題), 'Noto Sans TC' (中文內文)。
-*   **介面**: 玻璃擬態 (Glassmorphism)，半透明深色背景 + 亮色邊框。
-*   **互動**: 針對觸控優化的大按鈕，避免依賴 Hover 效果。
-
-## 4. 遊戲模組詳解 (Game Modules)
-
-### A. 數列峽谷 (The Glitch Canyon) - `sequence.html` [已完成/需微調]
-*   **數學單元**：等差數列與級數。
-*   **劇情**：城市邊緣的古老程式碼層出現 Glitch，階梯消失。
-*   **玩法**：動作跳躍遊戲。
-    *   **Phase 1 (觀念檢測)**：進入關卡前，先通過數列填空測驗，確認對首項與公差的理解。
-    *   **Phase 2 (數列跑酷)**：動作遊戲階段。
-        *   **視覺風格**：全區統一碎石 (Gravel) 紋理，數位荒野主題。
-        *   **規則**：僅有數列的「前兩項」會有琥珀色外框提示，後續特定平台外觀一致，玩家需自行計算並跳上正確數字平台。
-        *   **裝飾**：仙人掌與骨骸等裝飾物僅生成於無數字的安全平台上，不干擾作答。
-    *   **Phase 3 (召喚儀式)**：終點的互動教學。利用「倒轉複製」概念，將階梯補成長方形，引導學生推導出等差級數求和公式 $S_n = \frac{(a_1+a_n) \times n}{2}$。
-    *   **Phase 4 (核心回顧)**：(Gold Standard) 遊戲結束後顯示重點摘要，包含「等差數列定義」、「公差公式」、「級數和公式」，對應學習單內容。
-
-### B. 能源核心 (The Energy Core) - `function.html` [已完成]
-*   **數學單元**：線型函數 ($y = ax + b$)。
-*   **劇情**：中央發電廠核心不穩，需要輸入正確的晶石量以維持能量平衡。
-*   **玩法**：數據分析與邏輯推導。
-    *   **Phase 1 (蒐集數據)**：輸入 $x$ (晶石)，觀察 $y$ (電力)，利用描點法找出函數關係。
-    *   **Phase 2 (規律分析)**：觀察圖表上的點，辨識出「直線」規律，並利用規律預測未來。
-    *   **Phase 3 (過載危機)**：系統給出目標電力 $y=203$，玩家需根據 $y=2x+3$ 反求投入量 $x$。
-    *   **Phase 4 (進階推導)**：(Advanced Deduction) 核心重置，公式改變 ($y=ax+b$)。
-        *   **Step 1 (找截距 b)**：投入 $x=0$，觀察 $y$ 值，解出 $b$。
-        *   **Step 2 (找斜率 a)**：投入 $x=1$，觀察變化量，解出 $a$。
-        *   **Step 3 (驗算)**：利用新公式 $y=3x+5$ 驗算 $x=10$ 的結果。
-    *   **Phase 5 (核心解鎖)**：輸入正確的 $a$ 與 $b$ 值，完成任務。
-
-### C. 全等重案組 (Congruence District) - `congruence.html` [規劃中]
-*   **數學單元**：全等三角形判別 (SAS, ASA, SSS, RHS)。
-*   **劇情**：追捕偽裝大師「三角魔人」。
-*   **玩法**：偵探解謎。
-    *   **Phase 1 (蒐證)**：在案發現場使用放大鏡蒐集「邊長」與「角度」線索。
-    *   **Phase 2 (指認)**：在警局指認牆上，利用蒐集的條件篩選嫌疑犯。
-    *   **Phase 3 (審判/回顧)**：整理案情，總結全等性質（SAS, ASA...），並解釋為何 SSA (搖擺分身) 無法全等。
-
-### D. 平行建構區 (Parallel Skyline) - `parallel.html` [規劃中]
-*   **數學單元**：平行線截角性質、特殊四邊形。
-*   **劇情**：建設通往雲端的摩天大樓。
-*   **玩法**：建築工程。
-    *   **平行光束**：調整雷射發射器角度，利用「內錯角相等」或「同側內角互補」原理接通橋樑。
-    *   **四邊形物流**：輸送帶上出現各種四邊形建材，需根據對角線性質 (是否等長/垂直/平分) 快速分類。
-    *   **Phase 3 (完工驗收)**：展示建築藍圖，總結平行線截角性質與特殊四邊形的判別家族樹。
-
-## 5. 開發路徑 (Roadmap)
-- [x] **Phase 1: 基礎建設**
-    - [x] 建立 `index.html` 城市地圖。
-    - [x] 生成 iPad 專用背景圖。
-    - [x] 統一導航系統 (Back to Map 按鈕)。
-- [ ] **Phase 2: 現有程式優化**
-    - [ ] `function.html`: 增加音效回饋、優化引導流程、修正手機版面。
-    - [ ] `sequence.html`: 統一視覺風格，調整難度曲線。
-- [ ] **Phase 3: 新關卡開發**
-    - [ ] 開發 `congruence.html` (全等重案組) 原型。
-    - [ ] 開發 `parallel.html` (平行建構區) 原型。
-
----
-
-## 6. 修正經驗與開發筆記 (Dev Log)
-此區塊記錄開發過程中的重要迭代與修正經驗，供日後參考。
-
-### [Sequence Canyon] 視覺與機制修正 (Visual & Mechanics Polish)
-*   **視覺一致性的陷阱 (Visual Consistency)**：
-    *   在設計「尋找規律」類型的遊戲時，**所有平台的視覺材質必須嚴格統一**（例如全部使用碎石 Gravel）。
-    *   若正確與錯誤的平台有顏色差異，玩家會傾向使用「顏色判斷」而非「數學計算」，導致教學目標失效。
-*   **提示機制 (Scaffolding)**：
-    *   **限制提示範圍**：為了兼顧新手引導與挑戰性，提示（如光暈、外框）應僅限於首幾項（前兩項），後續必須完全移除提示。
-    *   **嚴格判定**：程式邏輯需確保 `p.hint` 是唯一決定外觀差異的參數，避免其他狀態（如 `target` 類型預設值）意外洩漏答案。
-*   **裝飾物與碰撞 (Decorations & Collision)**：
-    *   **空白平台 Bug**：直接在遊戲主路徑生成「無功能裝飾平台」容易讓玩家混淆（跳上去沒反應）。
-    *   **解決方案**：採用「區塊化 (Chunking)」策略，將起點與終點的長型安全區切割成多個小區塊，將裝飾物僅生成於這些絕對安全的區域，確保遊戲核心路徑的純粹性。
-*   **音效與視覺同步 (Audio-Visual Sync)**：
-    *   過關音效（如 Victory Fanfare）應在視覺高潮（如煙火發射）的**第一瞬間**觸發。
-    *   避免在動畫結束 callback 才播放音效，會造成「乾乾的」等待感。
-
-### [Function Core] 介面優化與教學引導 (UI/UX & Pedagogy Refinement)
-*   **介面佈局 (Layout & Alignment)**：
-    *   **分割視窗 (Split-Screen)**：在 Desktop 模式下，應將操作區（左）與圖表區（右）明確分開，避免彈出式視窗遮擋數據。
-    *   **視覺對齊 (Pixel-Perfect Alignment)**：上下排列的元件（如「核心法則Banner」與「指令對話框」）寬度必須一致（例如都設為 `w-[480px]`），視覺安定感會大幅提升。
-*   **教學引導與錯誤回饋 (Pedagogy & Feedback)**：
-    *   **不只是報錯**：當學生回答錯誤時，不能只顯示 Error，必須提供**具體且有數學邏輯的引導**。（例如：錯誤提示不只寫 "Wrong"，而是顯示 "$203 = 2x + 3 \rightarrow 200 = 2x$"，引導下一步思考）。
-    *   **即時回饋 (Instant Gratification)**：當學生發現數學規律（如「是一條直線」）時，圖表應**立刻**畫出對應的直線，讓數學發現與視覺獎勵同步。
-*   **視覺層級 (Visual Hierarchy)**：
-    *   **關鍵變數特大化**：數學應用題中的關鍵變數 ($x, y$) 字體應設定為極大 (e.g., `text-6xl`) 並嚴格遵守色碼（$x$=琥珀, $y$=青），降低閱讀一段長文字的認知負荷。
-    *   **去除干擾**：輸入框周圍不應有重複的標籤文字（如重複的「投入晶石」），會造成視覺混亂。
-*   **開發注意事項 (Dev Ops)**：
-    *   **檔案覆寫確認**：進行大幅度重構時，若 `replace_file_content` 失敗頻率高，應果斷使用 `write_to_file` 進行全檔覆寫 (`Overwrite=true`)，確保版本一致性。
-
----
----
-## 7. 專案製作群 (Credits)
-*   **遊戲設計**: 新竹縣精華國中 藍星宇老師
-*   **社群**: [萬物皆數](https://www.facebook.com/groups/1554372228718393)
-
-*Created by Antigravity for 11402 Semester Project*
+---
+title: MathCity
+emoji: 🌖
+colorFrom: gray
+colorTo: pink
+sdk: static
+pinned: false
+---
+
+
+# Math City: Cyber Chronicles (數學特區：未來都市)
+
+## 1. 專案願景 (Project Vision)
+本專案為八年級下學期數學課程的遊戲化教學平台。透過「未來都市」的沉浸式包裝，讓學生以「特務/維護者」的身分，在解決城���危機的過程中學習數學概念。
+
+**核心體驗**：
+*   **平台**：iPad 橫向全螢幕體驗 (Mobile Web App)。
+*   **風格**：Cyberpunk / Neon Noir (賽博龐克/霓虹暗黑)。
+*   **技術**：HTML5 Canvas + Tailwind CSS + Vanilla JS (無須建置工具)。
+
+## 2. 檔案結構 (File Structure)
+```
+/
+├── index.html          # [入口] 城市全息地圖 (Math City Map)
+├── sequence.html       # [數列] 數列峽谷 (The Glitch Canyon)
+├── function.html       # [函數] 能源核心 (The Energy Core)
+├── congruence.html     # [全等] 全等重案組 (Congruence District) - {待開發}
+├── parallel.html       # [平行] 平行建構區 (Parallel Skyline) - {待開發}
+└── assets/             # (建議) 存放圖片與音效資源
+```
+
+## 3. 視覺設計系統 (Design System)
+
+### 色彩計畫 (Neon Palette)
+這座城市由四個區域組成，每個區域有其代表的主色調：
+*   **🟦 能源核心 (Cyan)**: `#06b6d4` (Cyan-500) - 代表科技、冷靜、函數邏輯。
+*   **🟨 數列峽谷 (Amber)**: `#f59e0b` (Amber-500) - 代表古老遺跡、警示、規律。
+*   **🟪 全等重案組 (Magenta)**: `#d946ef` (Fuchsia-500) - 代表神秘、霓虹街頭、偵探氛圍。
+*   **🟩 平行建構區 (Green)**: `#22c55e` (Green-500) - 代表建設、雷射光束、結構。
+*   **🌑 背景基調**: `#050510` (Very Dark Blue) - 極致黑，襯托霓虹光。
+
+### UI 規範
+*   **字體**: 'Orbitron' (數字/英文標題), 'Noto Sans TC' (中文內文)。
+*   **介面**: 玻璃擬態 (Glassmorphism)，半透明深色背景 + 亮色邊框。
+*   **互動**: 針對觸控優化的大按鈕，避免依賴 Hover 效果。
+
+## 4. 遊戲模組詳解 (Game Modules)
+
+### A. 數列峽谷 (The Glitch Canyon) - `sequence.html` [已完成/需微調]
+*   **數學單元**：等差數列與級數。
+*   **劇情**：城市邊緣的古老程式碼層出現 Glitch，階梯消失。
+*   **玩法**：動作跳躍遊戲。
+    *   **Phase 1 (觀念檢測)**：進入關卡前，先通過數列填空測驗，確認對首項與公差的理解。
+    *   **Phase 2 (數列跑酷)**：動作遊戲階段。
+        *   **視覺風格**：全區統一碎石 (Gravel) 紋理，數位荒野主題。
+        *   **規則**：僅有數列的「前兩項」會有琥珀色外框提示，後續特定平台外觀一致，玩家需自行計算並跳上正確數字平台。
+        *   **裝飾**：仙人掌與骨骸等裝飾物僅生成於無數字的安全平台上，不干擾作答。
+    *   **Phase 3 (召喚儀式)**：終點的互動教學。利用「倒轉複製」概念，將階梯補成長方形，引導學生推導出等差級數求和公式 $S_n = \frac{(a_1+a_n) \times n}{2}$。
+    *   **Phase 4 (核心回顧)**：(Gold Standard) 遊戲結束後顯示重點摘要，包含「等差數列定義」、「公差公式」、「級數和公式」，對應學習單內容。
+
+### B. 能源核心 (The Energy Core) - `function.html` [已完成]
+*   **數學單元**：線型函數 ($y = ax + b$)。
+*   **劇情**：中央發電廠核心不穩，需要輸入正確的晶石量以維持能量平衡。
+*   **玩法**：數據分析與邏輯推導。
+    *   **Phase 1 (蒐集數據)**：輸入 $x$ (晶石)，觀察 $y$ (電力)，利用描點法找出函數關係。
+    *   **Phase 2 (規律分析)**：觀察圖表上的點，辨識出「直線」規律，並利用規律預測未來。
+    *   **Phase 3 (過載危機)**：系統給出目標電力 $y=203$，玩家需根據 $y=2x+3$ 反求投入量 $x$。
+    *   **Phase 4 (進階推導)**：(Advanced Deduction) 核心重置，公式改變 ($y=ax+b$)。
+        *   **Step 1 (找截距 b)**：投入 $x=0$，觀察 $y$ 值，解出 $b$。
+        *   **Step 2 (找斜率 a)**：投入 $x=1$，觀察變化量，解出 $a$。
+        *   **Step 3 (驗算)**：利用新公式 $y=3x+5$ 驗算 $x=10$ 的結果。
+    *   **Phase 5 (核心解鎖)**：輸入正確的 $a$ 與 $b$ 值，完成任務。
+
+### C. 全等重案組 (Congruence District) - `congruence.html` [規劃中]
+*   **數學單元**：全等三角形判別 (SAS, ASA, SSS, RHS)。
+*   **劇情**：追捕偽裝大師「三角魔人」。
+*   **玩法**：偵探解謎。
+    *   **Phase 1 (蒐證)**：在案發現場使用放大鏡蒐集「邊長」與「角度」線索。
+    *   **Phase 2 (指認)**：在警局指認牆上，利用蒐集的條件篩選嫌疑犯。
+    *   **Phase 3 (審判/回顧)**：整理案情，總結全等性質（SAS, ASA...），並解釋為何 SSA (搖擺分身) 無法全等。
+
+### D. 平行建構區 (Parallel Skyline) - `parallel.html` [規劃中]
+*   **數學單元**：平行線截角性質、特殊四邊形。
+*   **劇情**：建設通往雲端的摩天大樓。
+*   **玩法**：建築工程。
+    *   **平行光束**：調整雷射發射器角度，利用「內錯角相等」或「同側內角互補」原理接通橋樑。
+    *   **四邊形物流**：輸送帶上出現各種四邊形建材，需根據對角線性質 (是否等長/垂直/平分) 快速分類。
+    *   **Phase 3 (完工驗收)**：展示建築藍圖，總結平行線截角性質與特殊四邊形的判別家族樹。
+
+## 5. 開發路徑 (Roadmap)
+- [x] **Phase 1: 基礎建設**
+    - [x] 建立 `index.html` 城市地圖。
+    - [x] 生成 iPad 專用背景圖。
+    - [x] 統一導航系統 (Back to Map 按鈕)。
+- [ ] **Phase 2: 現有程式優化**
+    - [ ] `function.html`: 增加音效回饋、優化引導流程、修正手機版面。
+    - [ ] `sequence.html`: 統一視覺風格，調整難度曲線。
+- [ ] **Phase 3: 新關卡開發**
+    - [ ] 開發 `congruence.html` (全等重案組) 原型。
+    - [ ] 開發 `parallel.html` (平行建構區) 原型。
+
+---
+
+## 6. 修正經驗與開發筆記 (Dev Log)
+此區塊記錄開發過程中的重要迭代與修正經驗，供日後參考。
+
+### [Sequence Canyon] 視覺與機制修正 (Visual & Mechanics Polish)
+*   **視覺一致性的陷阱 (Visual Consistency)**：
+    *   在設計「尋找規律」類型的遊戲時，**所有平台的視覺材質必須嚴格統一**（例如全部使用碎石 Gravel）。
+    *   若正確與錯誤的平台有顏色差異，玩家會傾向使用「顏色判斷」而非「數學計算」，導致教學目標失效。
+*   **提示機制 (Scaffolding)**：
+    *   **限制提示範圍**：為了兼顧新手引導與挑戰性，提示（如光暈、外框）應僅限於首幾項（前兩項），後續必須完全移除提示。
+    *   **嚴格判定**：程式邏輯需確保 `p.hint` 是唯一決定外觀差異的參數，避免其他狀態（如 `target` 類型預設值）意外洩漏答案。
+*   **裝飾物與碰撞 (Decorations & Collision)**：
+    *   **空白平台 Bug**：直接在遊戲主路徑生成「無功能裝飾平台」容易讓玩家混淆（跳上去沒反應）。
+    *   **解決方案**：採用「區塊化 (Chunking)」策略，將起點與終點的長型安全區切割成多個小區塊，將裝飾物僅生成於這些絕對安全的區域，確保遊戲核心路徑的純粹性。
+*   **音效與視覺同步 (Audio-Visual Sync)**：
+    *   過關音效（如 Victory Fanfare）應在視覺高潮（如煙火發射）的**第一瞬間**觸發。
+    *   避免在動畫結束 callback 才播放音效，會造成「乾乾的」等待感。
+
+### [Function Core] 介面優化與教學引導 (UI/UX & Pedagogy Refinement)
+*   **介面佈局 (Layout & Alignment)**：
+    *   **分割視窗 (Split-Screen)**：在 Desktop 模式下，應將操作區（左）與圖表區（右）明確分開，避免彈出式視窗遮擋數據。
+    *   **視覺對齊 (Pixel-Perfect Alignment)**：上下排列的元件（如「核心法則Banner」與「指令對話框」）寬度必須一致（例如都設為 `w-[480px]`），視覺安定感會大幅提升。
+*   **教學引導與錯誤回饋 (Pedagogy & Feedback)**：
+    *   **不只是報錯**：當學生回答錯誤時，不能只顯示 Error，必須提供**具體且有數學邏輯的引導**。（例如：錯誤提示不只寫 "Wrong"，而是顯示 "$203 = 2x + 3 \rightarrow 200 = 2x$"，引導下一步思考）。
+    *   **即時回饋 (Instant Gratification)**：當學生發現數學規律（如「是一條直線」）時，圖表應**立刻**畫出對應的直線，讓數學發現與視覺獎勵同步。
+*   **視覺層級 (Visual Hierarchy)**：
+    *   **關鍵變數特大化**：數學應用題中的關鍵變數 ($x, y$) 字體應設定為極大 (e.g., `text-6xl`) 並嚴格遵守色碼（$x$=琥珀, $y$=青），降低閱讀一段長文字的認知負荷。
+    *   **去除干擾**：輸入框周圍不應有重複的標籤文字（如重複的「投入晶石」），會造成視覺混亂。
+*   **開發注意事項 (Dev Ops)**：
+    *   **檔案覆寫確認**：進行大幅度重構時，若 `replace_file_content` 失敗頻率高，應果斷使用 `write_to_file` 進行全檔覆寫 (`Overwrite=true`)，確保版本一致性。
+
+---
+---
+## 7. 專案製作群 (Credits)
+*   **遊戲設計**: 新竹縣精華國中 藍星宇老師
+*   **社群**: [萬物皆數](https://www.facebook.com/groups/1554372228718393)
+
+*Created by Antigravity for 11402 Semester Project*