README.md

---
title: 802MathCity
emoji: 👁
colorFrom: blue
colorTo: purple
sdk: static
pinned: false
app_file: index.html
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference


# Math City: Cyber Chronicles (數學特區：未來都市)
## ⚠️ AI 行為準則 (System Instructions)
1. **語言要求：** 所有的對話、思考過程、Implementation Plan (實作計畫) 以及程式碼註解，請**嚴格使用「繁體中文 (Traditional Chinese)」**。
2. **例外：** 只有程式碼本身的變數名稱、函數名稱、專有名詞保留英文。
## 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)

### 分區色彩計畫 (Zone Color Coding)
為了區分不同的數學主題區域，每個子頁面都擁有**獨立的背景色調**與**霓虹主色**，強化玩家的空間感：
| 區域 (Zone) | 數學主題 (Theme) | 霓虹主色 (Neon) | 背景基調 (Background) | 狀態 |
| :--- | :--- | :--- | :--- | :--- |
| **首頁 (Hub)** | 城市全息圖 | 🔵 `#06b6d4` (Cyan) | ⚫ `#050510` (Void) | `index.html` |
| **摩天大樓** | 平行/幾何 | 🟢 `#22c55e` (Green) | 🌑 `#020804` (Deep Jungle) | `skyscraper.html` |
| **數列峽谷** | 數列/規律 | 🟠 `#f59e0b` (Amber) | 🟤 `#1a1005` (Dark Amber) | `sequence.html` |
| **能源核心** | 函數/邏輯 | 🔵 `#06b6d4` (Cyan) | 🔵 `#051015` (Deep Azure) | `function.html` |
| **全等重案組** | 全等判別 | 🟣 `#d946ef` (Fuchsia) | 🟣 `#100515` (Dark Void) | `congruence.html` |

### 色彩計畫 (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$ 的結果，並用圖表上的點 ($10,35$) 進行再確認。
    *   **Phase 5 (核心解鎖)**：輸入正確的 $a$ 與 $b$ 值，完成任務。
    *   **Phase 6 (脈衝同步)**：節奏遊戲，在音樂節拍下進行點擊，穩定核心能量，強化回饋感。

### 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 按鈕)。
- [x] **Phase 2: 現有程式優化**
    - [x] `function.html`: 音量核心遊戲完整化、Phase 4 進階邏輯完備、節奏遊戲計分平衡。
    - [x] `sequence.html`: 統一視覺風格，調整難度曲線。
- [ ] **Phase 3: 新關卡開發**
    - [ ] 開發 `congruence.html` (全等重案組) 原型。
    - [ ] 開發 `parallel.html` (平行建構區) 原型。

---

## 6. 修正經驗與開發筆記 (Dev Log)
此區塊記錄開發過程中的重要迭代與修正經驗，供日後參考。

### [Sequence Canyon] 視覺與機制修正 (Visual & Mechanics Polish)
*   **視覺一致性的陷阱**: 修正了平台顏色提示過於明顯的問題，統一為碎石紋理，強制學生進行計算而非辨色。
*   **提示機制**: 僅由數列前兩項提供視覺提示，後續完全依賴計算。
*   **裝飾物配置**: 將裝飾物移至非遊戲路徑的安全平台，避免干擾判斷。

### [Function Core] 進階教學設計 (Advanced Pedagogy Design)
*   **鷹架理論 (Scaffolding) 的應用**:
    *   **變數分離**: 在推導 $y=ax+b$ 時，不要同時讓學生解兩個未知數。我們設計為：
        1.  先令 $x=0$，讓 $a$ 項消失，專注解 $b$ (截距)。
        2.  知道 $b$ 後，再令 $x=1$，專注解 $a$ (斜率)。
    *   這樣能讓學生理解每個係數的幾何意義，而非單純背誦解聯立方程式。
*   **視覺與代數的連結 (Visual-Algebra Connection)**:
    *   **圖表驗證**: 在 Phase 4 Step 3，驗算出 $y=35$ 後，不僅僅是數字正確，程式還引導視線看向圖表上的 $(10, 35)$ 點。這強化了「代數解」與「幾何圖形上的點」是同一回事的概念。
*   **正向回饋系統 (Positive Feedback Loop)**:
    *   **避免挫折感**: 將傳統的 `alert()` 錯誤彈窗，改為「介面上的脈衝紅框」與「引導式錯誤訊息」。
    *   **具體化錯誤**: 錯誤訊息不是只說「錯」，而是說「如果 x=2, y=11, 因 11 = 2a+5, 所以 a=?」。這將**錯誤轉化為另一個數學題目**，而非單純的懲罰。
    *   **節奏遊戲獎勵**: 在完成艱澀的運算後，Phase 6 的節奏遊戲提供純粹的感官刺激與高分回饋 (5000分)，平衡大腦疲勞。
*   **情境化總結 (Contextual Summary)**:
    *   任務完成頁面不僅列出分數，更點出核心數學素養：「預測」與「建模」。讓學生知道他們剛剛做的計算，本質上就是科學家預測未來的過程。

### [Function Core] 介面優化與除錯經驗
*   **按鈕鎖定邏輯**: 驗證成功後鎖定按鈕 (`disabled`) 非常重要，可防止重複觸發事件或重複計分。需確保 CSS Selector 選中正確的按鈕。
*   **樣式與動畫**:
    *   **跳動 vs 呼吸**: `animate-bounce` 用於錯誤訊息有時過於滑稽且難以閱讀，改為 `animate-pulse` (呼吸燈/閃耀) 配合紅色邊框，既有警示效果又保持質感。
    *   **Canvas 文字清晰度**: 在 High-DPI 螢幕 (Retina) 上，Canvas 必須正確縮放 (Scale by DevicePixelRatio)，否則文字會模糊。

---

## 7. 專案製作群 (Credits)
*   **遊戲設計**: 新竹縣精華國中 藍星宇老師
*   **社群**: [萬物皆數](https://www.facebook.com/groups/1554372228718393)

*Created by Antigravity for 11402 Semester Project*