# 機器人模擬器規格(lesson type = `robot`)

系列課程《從無到有打造你的 AI 機器人》(四個版本)用這個瀏覽器內模擬器,讓沒有實體機器人的學員也能寫程式、看虛擬機器人動起來,系統自動判定任務完成。
所有程式都在瀏覽器內執行,不會執行真實硬體指令,也不送到伺服器。

## 1. 單元格式(課程章節檔)

```php
['title' => '互動模擬:循線小車', 'type' => 'robot', 'xp' => 30,
 'content' => '情境說明(至少 150 字:要解決什麼問題、目標、前提,不貼完整答案)',
 'config' => [
    'robot'  => 'diffdrive',            // 機器人模型:diffdrive | arm(見 §3)
    'world'  => 'line-track',           // 場地預設:見 §4
    'starter'=> "# 在這裡寫你的程式\n...",   // 起始程式碼(Python 子集)
    'tasks'  => [                        // 至少 3 個,由易到難,每個要有 title、hint、check 或 checks
        ['title' => '讓小車前進 50 公分', 'hint' => '...', 'check' => ['type' => 'distance', 'min' => 50]],
        ['title' => '沿著黑線跑完一圈', 'hint' => '...', 'checks' => [['type' => 'reach', 'zone' => 'finish'], ['type' => 'no_collision']]],
    ],
    'solution'   => "標準解答的程式碼(Python 子集)",   // 必填;驗證工具會在模擬器跑它,必須完成所有任務
    'time_limit' => 60,                  // 模擬秒數上限(預設 60)
    'params'     => [],                  // 選填:覆寫場地/機器人參數(如 'start' => [x, y, heading])
 ],
],
```
- 任務一開始不能已經成立(沒寫程式就達成的不算)。任務一旦完成就不取消。
- 全部任務完成 → 單元完成(與 terminal 單元相同,前端呼叫 `learn.complete`)。
- `solution` 不會送到瀏覽器(與 terminal 相同,後端 `except('solution')`)。

## 2. 程式語言:Python 子集(`resources/js/robot-lang.js`)

目的是讓學員寫出「看起來就是 Python」的機器人程式,對應樹莓派/ROS 2 版;Arduino 版也用同一個子集練「邏輯」(課程文字會說明和 C++ 語法的對應)。

支援:
- 語句:賦值(含 `+= -= *= /=`)、`if / elif / else`、`while`、`for x in range(...)` 與 `for x in list`、`break`、`continue`、`pass`、`def` 函式(含參數、預設值、`return`)、`global`;註解 `#`;縮排(4 空格或 tab,不可混用)。
- 運算:`+ - * / // % **`、比較、`and or not`、`in`、`is None`、三元式 `a if c else b`。
- 資料型別:int、float、str、bool、None、list(含索引、切片、`append`、`len`)、tuple、簡單 dict(讀、寫、`get`、`keys`、`in`)。f-string(`f"x={x}"`)。
- 內建:`print`、`len`、`range`、`abs`、`min`、`max`、`round`、`int`、`float`、`str`、`sum`、`sorted`;`math` 模組(`sqrt sin cos atan2 pi radians degrees`)(用 `import math` 或 `from math import ...`);`time.sleep(s)` 與 `sleep(s)`(模擬時間);`time.time()`(模擬時間)。
- **不支援**(遇到要給清楚的中文錯誤訊息含行號,例如「第 5 行:練習環境不支援 class」):`class`、`import` 其他模組、`try/except`、`with`、`lambda`、生成式(comprehension)、`yield`、`async`、檔案與網路存取、`eval/exec/open/__import__`、屬性存取 `__xxx__`。
- 安全:不用 `eval` / `new Function` 執行學員程式。自己寫 tokenizer + parser + 直譯器。有指令數上限與模擬時間上限,無窮迴圈(沒有 sleep)會在固定指令數後被中止並提示「程式沒有讓出時間,請在迴圈裡加 sleep」。
- 執行模型:**協作式逐步執行**。直譯器以 generator 實作,遇到 `sleep()` 或每執行 N 個運算就讓出;模擬器每個時間步(例如 20 ms)呼叫一次 `step`,所以 `while True:` 迴圈搭配 `sleep(0.05)` 是正常寫法。
- 介面:
  ```js
  const prog = createProgram(source, builtins, { maxOpsPerStep: 2000, maxTotalOps: 5_000_000 });
  // prog.error  → 語法錯誤時 { line, message }(中文),否則 null
  prog.step(dtSim) → { done: boolean, error: null | { line, message }, waiting: boolean }  // 每次推進一個時間步
  prog.output     → print 輸出的行陣列
  ```
  `builtins` 是模擬器提供的物件(`robot`、`arm`、`led` 等,方法可呼叫、屬性可讀),直譯器要能呼叫 JS 函式物件的方法並傳入/取回 Python 值。

## 3. 機器人模型與 API

### 3.1 `diffdrive`(差速輪式小車,俯視 2D,單位:公分、度、秒)
物件 `robot`:
- 動作:`robot.forward(speed=60)`、`robot.backward(speed=60)`、`robot.turn_left(speed=60)`(原地左轉)、`robot.turn_right(speed=60)`、`robot.set_motors(left, right)`(-100~100)、`robot.stop()`。這些只設定馬達輸出,馬達持續運轉直到下一次設定(與真實機器人相同);走一段距離要自己 `sleep`。
- 輔助:`robot.move(distance_cm, speed=60)`、`robot.rotate(angle_deg, speed=60)`(阻塞直到完成,內部用里程計/航向)。
- 感測器:`robot.distance()`(前方超音波,公分,最大 200,有輕微雜訊 ±1)、`robot.line()` → `[左, 中, 右]` 三個反射感測器(0=亮,1=黑線)、`robot.color()`(腳下顏色字串)、`robot.heading()`(IMU 偏航角 0~360)、`robot.position()` → `(x, y)`(里程計,公分,有極小漂移)、`robot.bumped()`(碰撞開關)、`robot.battery()`(百分比,隨時間下降)。
- 相機(AI 視覺入門):`robot.camera.find(color)` → `(found, cx, size)`,cx 為畫面水平位置 -1~1,size 為佔畫面比例 0~1;`robot.camera.detect()` → 物件清單 `[{'label': 'ball', 'cx': ..., 'size': ...}, ...]`(模擬的辨識結果)。
- 其他:`led.on()`、`led.off()`、`led.color(name)`;`buzzer.beep(ms)`;`print()` 輸出顯示在畫面下方的主控台。
- 物理:簡化的差速運動學 + 馬達加速延遲 + 輪速雜訊;撞牆會停住並觸發 `bumped()`。固定時間步 20 ms,結果完全**決定性**(用固定種子的偽隨機,方便驗證)。

### 3.2 `arm`(桌上型 3 自由度手臂 + 夾爪,側視 2D 平面,單位:公分、度)
物件 `arm`:`arm.set_joint(index, angle)`(index 0 底座旋轉、1 肩、2 肘;角度有範圍限制,超出要報錯)、`arm.move_to(x, y)`(逆運動學,平面;超出可及範圍時報錯並說明)、`arm.gripper_open()`、`arm.gripper_close()`、`arm.position()`(末端 x,y)、`arm.holding()`(是否夾著物體)、`arm.joint(index)`。動作需要時間(依角速度),`arm` 的動作呼叫會阻塞到完成(內部讓出時間)。`arm.camera.find(color)` 回傳物體在桌面上的 `(found, x, y)`。

## 4. 場地預設(`world`)
`open-field`(空場地,可畫目標點)、`line-track`(黑線軌道:直線/曲線/迴圈)、`obstacle-course`(障礙物)、`maze`(迷宮)、`color-zones`(顏色區域)、`ball-hunt`(找球,相機)、`pick-place`(手臂抓取放置)。每個預設有固定的起點與命名區域(`start`、`goal`、`finish`、`zone-red` 等)供 check 使用。`params` 可微調。模擬器須有固定的畫布繪製(Canvas 2D),深色背景、清楚的格線/比例尺,機器人與感測器範圍(如超音波錐、線感測點)可視。

## 5. 任務檢查類型(`check` / `checks`)
| type | 欄位 | 說明 |
|---|---|---|
| `distance` | `min`(可選 `max`) | 累計行駛距離(公分) |
| `reach` | `zone` | 機器人(手臂為末端)進入命名區域 |
| `stop_in` | `zone` | 停在區域內(速度≈0)至少 0.5 秒 |
| `heading` | `target`、`tol` | 航向接近某角度 |
| `no_collision` | — | 到目前為止沒有碰撞 |
| `on_line_ratio` | `min` | 感測到黑線的時間比例(循線品質) |
| `collect` | `count` | 收集/碰到的目標物數量 |
| `pick_place` | `object`、`zone` | 物體被放到區域 |
| `time_under` | `seconds` | 在指定模擬秒數內達成(搭配其他 check) |
| `printed` | `pattern` | print 輸出符合正規表示式 |
| `uses` | `pattern` | 原始碼符合(例如要求用到 `while`、`def`、`if`),教學用 |
| `led` | `color` | LED 曾亮過某顏色 |
| `sensor_read` | `name`、`min`/`max` | 曾讀到某感測器數值範圍 |
`checks` 為全部成立才算。

## 6. 前端與整合需求
- 檔案:`resources/js/robot-lang.js`(直譯器)、`resources/js/robot-sim-core.js`(世界、物理、機器人、感測器、任務檢查;純 JS 不依賴 DOM,可在 Node 跑)、`resources/js/robot.js`(Alpine 元件:程式編輯區、畫布、執行/暫停/重設/速度、主控台、任務清單)、`resources/views/learn/robot.blade.php`(單元畫面,仿 `learn/terminal.blade.php`)。
- 編輯器:不引入新套件。用 `<textarea>` + 行號 + 簡單語法高亮(可用疊層 `<pre>`),支援 Tab 縮排、Ctrl/Cmd+Enter 執行。錯誤顯示行號與中文訊息並標示該行。
- UI 文字全部用 `__()`(Blade)與 `t()`(JS,見 resources/js/i18n.js 與 lang/_work/README.md)。新增的鍵與四語言翻譯寫進 `lang/_work/robot.json`,JS 用到的鍵也要加入 `resources/js/i18n-keys.json`。
- 整合:`Lesson::TYPES`/`typeLabel()` 加入 `robot`('互動模擬')、`learn/body.blade.php` 分派、`tools/validate-chapter.php` 接受 `robot` 單元並檢查格式、`LearnController` 完成流程沿用 terminal 的方式、`Services/Tutor.php` 對 robot 單元的上下文說明(任務清單與起始程式碼,不含解答)、`resources/css` 若需要樣式。
- 驗證工具:`tools/validate-robot.mjs <章節檔...>`(仿 validate-terminal.mjs):對每個 robot 單元「一開始沒有任務完成」且「執行 solution 後全部完成」,輸出 OK/FAIL。
- 測試:`tools/test-robot-lang.mjs`、`tools/test-robot-sim.mjs`(Node 直接執行,風格仿 tools/test-terminal-core.mjs);PHP 端測試加入 tests/Feature。

## 7. 圖片與示意圖(所有機器人課程的教材都要有圖)
- 語法:在 text / lab 單元內容裡,**單獨一行**寫 `[圖:/images/courses/<課程slug>/<檔名>.svg|圖說文字]`。圖說同時是替代文字(給螢幕閱讀器與 AI 朗讀),要寫出「這張圖在表達什麼」,至少 6 個字。圖檔放在 `public/images/courses/<課程slug>/`,只接受 /images/ 底下的 svg/png/jpg/webp/gif。
- 驗證:`php tools/validate-chapter.php` 會檢查圖檔存在、SVG 是合法 XML、有 viewBox 與 `<title>`、沒有 script/事件屬性。
- **每章至少 2 張圖**(純理論章也要有):系統方塊圖、接線示意圖、流程圖/狀態機圖、感測器視野(如超音波錐、循線感測器位置)、座標系與角度定義、控制迴路方塊圖、PID 響應曲線示意、運動學幾何圖、ROS 2 節點與話題關係圖、組裝步驟示意等。
- SVG 規範:手寫 SVG(不要引用外部檔案/字型/圖片);`viewBox` 寬約 640~800、高依內容;**自帶白色或極淺色背景矩形**(圖會放在深色與淺色主題的頁面上);文字用 `font-family="sans-serif"`、字級 ≥ 14、繁體中文標示;配色對比足夠(深色字 on 淺底),用色彩+線型+文字三重區分,不只靠顏色;箭頭用 `<marker>`;每個檔案 < 40 KB;檔名 `chNN-主題.svg`(英文小寫與連字號)。
- 接線圖與零件圖是**示意**:不要宣稱和某個特定套件的腳位一致。圖上要標示「示意圖:腳位以你的零件與程式碼為準」,課程程式碼裡用到的腳位與圖一致。
- 不要放照片或有版權的圖;只用自己畫的 SVG。
