--- name: learning-mechanics description: Choose and implement a game mechanic that makes a learning interaction genuinely playable without teaching anything wrong. Use when a teaching site's demo or quiz feels monotonous (很單調, 只是拖滑桿, 沒有挑戰感), when adding goals, challenge, feedback, progress, or rewards to a learning interaction, or when judging whether a candidate mechanic (timed challenge, matching, ordering, boss level, estimation betting) is safe for a given learning objective. --- # Learning Mechanics(教學遊戲化機制層) Read [Codex runtime guidance](../../CODEX.md) before using this skill. Resolve bundled skills and resources relative to this installed package. ## Overview 這一層只做一件事:**把「概念視覺化 demo」升級成「有目標、有回饋、有進度的遊玩循環」,而且不教錯任何東西。** 它是課程層與引擎層之間的一層: | 需求 | 用誰 | |---|---| | 章節依賴圖、demo 直覺化、小測 schema、事實審查、PWA | `progressive-learning-site` | | **機制選擇、挑戰與回饋設計、獎勵與進度、可玩性驗收** | 本 skill | | 3D / WebGL / Phaser / 大量粒子與相機捲動 | `game-studio`(只在真的需要時) | ## 三條鐵則 1. **機制必須為學習目標服務。** 先寫下「玩完懂了什麼」一句話;答不出來就不要做這個機制。 2. **機制不得獎勵錯誤行為。** 每個機制都在訓練某種行為(快、猜、記位置、找規律)。若它獎勵的行為 ≠ 學習目標要的行為,這個機制就是在教反的東西。 3. **教學正確性零容忍,遊戲化不例外。** 隨機生成的局面必須先證明**有解**;題目若有多條等價路徑(例如解一元一次方程式可先移項也可先去括號),不得只承認單一解法。機制通過 ≠ 上線,事實審查照樣要做。 ## Procedure ### 1. 定位學習目標型態 先判斷這一章要的是哪一型,這決定候選機制: | 型態 | 目標 | 典型章節 | |---|---|---| | 表徵轉換 | 同一概念在不同表徵間轉換 | 公式 ↔ 圖形、單位 ↔ 量 | | 概念邊界 | 分辨是 / 不是、屬於 / 不屬於 | 是函數嗎、是物理量嗎 | | 程序性 | 步驟有序、可重複 | 解方程式、配平、實驗流程 | | 量感 | 數量級、估算、合理性 | 面積量級、單位換算 | | 整合應用 | 多知識點合起來解一個情境 | 章末綜合題 | ### 2. 選機制 讀 `references/mechanic-catalog.md`,挑 1–2 個候選,逐項過排除清單。候選超過 2 個時,選「實作成本最低、且答得出『玩完懂了什麼』」的那個 —— 不要一次上多個機制。 **加嚴門檻不是遊戲化。** 如果學生「做的事」沒變(還是答 4 選 1),只是變難(全對才過、加限時、答錯重來),那是門檻不是機制 —— 門檻只讓同一件事變累,不會讓它變好玩。要解決單調,就得換學生實際動手做的事。 ### 3. 副作用檢查(最容易漏的一步) 對選定機制明寫兩行: - **它獎勵什麼行為**:__(例:快速反應 / 精確估算 / 願意重試 / 找出反例) - **這是不是本章要的行為**:是 / 否 若答「否」但有教學價值 → 標明它是**暖身或流暢度訓練**,且不得放在理解階段。 ### 4. 最小 juice(回饋層) 不是「加動畫」,是「讓因果關係看得見」。最低標準: - 操作後 **100ms 內**有可見回饋;數值 / 圖形變化與操作同步 - 正確與錯誤的回饋**必須不同且可辨識**(顏色 + 形狀 + 文字,不要只靠顏色) - 獎勵動畫 **≤600ms** 且不阻斷下一步操作(學校裝置多為中低階手機) - 提供 `prefers-reduced-motion` 降級路徑 - 音效預設可關(教室環境);不靠音效傳達必要資訊 - 回饋要指向「為什麼」,不是只有「對 / 錯」—— 接上既有的分層提示,不要用回饋取代提示 ### 5. 進度與獎勵 - **獎勵反映掌握度**,不是純過關給分(答對率 / 難度 / 重試次數影響 XP) - **可檢查的最低標準**:重試次數必須反映在 XP,或至少被記錄下來。「重試 5 次過關」與「一次過關」拿同樣 XP 且不留痕跡 = 違反掌握度對齊;即使專案打算之後才做,也要先記錄 `retryCount` 讓將來算得出來 - 難度曲線前期簡單、後期遞增;同一機制的難度要有可調參數,不要寫死 - 獎勵節奏:**可預期為主 + 偶發驚喜為輔**。純賭博式掉落(與表現無關的隨機)不採用 - 進度儲存必帶 schema version(沿用專案既有原則) ### 6. 實作 兩種底盤,選專案既有者,不要混: - **A. 純靜態**(`progressive-learning-site` 產出:無框架、CDN only、SVG / Canvas + localStorage) - **B. Vue 3 SPA**(ArcanaArk:Pinia + reducer 狀態機 + DOM / CSS) 共同硬規約: - 能 DOM / CSS 做就不要開 canvas;動畫優先用 `transform` / `opacity` - 遊戲狀態要進既有狀態機或進度物件,**不要藏在 DOM 裡**(否則無法測試、無法存檔、無法驗收) - 手機優先:不得產生水平捲動;觸控目標 ≥ 44px ### 7. 驗收(四個訊號) 1. **首次通過率 70–80%**(沿用課程層標準)。全對=太易,全錯=太難或講解沒講清 2. **「玩完懂了什麼」一句話答得出來**,且答的是概念不是操作 3. **拔掉機制測試**:把機制移除後學習目標還在嗎?若「沒有機制就學不到」→ 機制掩蓋目標,重設計 4. **教學正確性複查**:有解性、等價路徑、簡化標註,逐一**實算**,不靠肉眼 **量不到就不能聲稱通過**:若「首次通過率」目前沒有事件記錄可算(無後端 / 無 instrumentation 的 demo),先加最小記錄 —— 每題 attempt / retry / 花費時間 / 是否超時(存 localStorage 即可)。這是前置工作,不是「之後再說」。 最後跑一次新手走查(從頭到尾走一遍):卡關處就是設計缺陷,不要推給使用者程度。 ## 排除清單(硬性禁止) - ❌ **理解階段使用限時挑戰** —— 訓練焦慮與猜測,直接違反學習目標。限時只允許在已學會之後的流暢度訓練,且必須標明 - ❌ 隨機生成卻未驗證有解的關卡(配對、配平、排序、迷宮都算) - ❌ **固定題目 + 無限重試 + 答錯顯示正解** 三件同時出現 —— 「全對才過關」會被背答案繞過(第二、三輪照著上一輪的正解選就會過)。要搭題庫池抽題或數值變體,且每個變體都要驗算有解 - ❌ 用「加嚴門檻」冒充機制(加限時、加全對要求、加重試,但學生做的事沒變) - ❌ 只承認單一解法、把等價路徑判錯的評分 - ❌ 純賭博式獎勵(與表現無關的隨機掉落) - ❌ 一次上手多個機制,或機制複雜度超過學習目標本身 - ❌ 用遊戲性蓋掉事實審查,或「先上線再修教學內容」 ## Output contract 交付時要附: - 學習目標型態 + 選定機制 + 「玩完懂了什麼」一句話 - 副作用檢查兩行(獎勵什麼行為 / 是否本章要的行為) - 難度參數與獎勵規則(含 XP 如何反映掌握度) - 驗收四訊號的實測結果(含首次通過率) - 教學正確性複查紀錄(有解性怎麼驗的、等價路徑怎麼處理) ## Routing - 只有課程骨架 / demo 直覺化 / 事實審查 → `progressive-learning-site` - 需要 3D、大量粒子、相機捲動的 tile 世界、或要換渲染引擎 → `game-studio`(先確認真的需要;本 skill 涵蓋範圍內不要動引擎) - 專案既有決策優先:以該 repo 的 `CONTEXT.md` / `ROADMAP.md` 為準,本 skill 不覆蓋專案已對齊的決策