# 機器人模擬器 API(課程作者文件)

給撰寫 `type => 'robot'` 單元的課程作者。規格背景見 `docs/robot-sim-spec.md`。學員程式是 Python 子集(`resources/js/robot-lang.js`),在瀏覽器內執行,不連接真實硬體。
驗證:`php tools/validate-chapter.php 章節檔` 檢查格式,`node tools/validate-robot.mjs 章節檔` 在模擬器實際跑 `solution`(一開始沒有任務成立、跑完全部完成、解答沒有程式錯誤)。

## 1. 座標、單位與時間
- 單位:長度 **公分**、角度 **度**、時間 **模擬秒**(固定時間步 20 ms,結果決定性;同一份程式每次跑結果完全相同)。
- 場地座標:原點在左下角,**x 向右、y 向上**。
- 航向 `heading`:**0° = 朝 +x(畫面右方),逆時針為正**(左轉角度增加,90° = 朝上)。`robot.heading()` 回傳 0 ≤ h < 360。
- `robot.position()` 是里程計,**座標系與場地相同**(起點就是場地起點),有約 0.3% 的比例誤差。
- 程式要靠 `sleep()` 讓出時間;`while True:` 裡一定要有 `sleep(0.02)` 之類的等待。每次執行都從場地起點重新開始。
- 程式結束後,馬達停止並再多模擬 1 秒(讓 `stop_in` 等檢查有時間成立)。超過 `time_limit` 會被中止。全部任務完成時模擬立刻結束。

## 2. diffdrive(差速小車)API
機器人半徑 8 cm,輪距 14 cm,最高輪速 40 cm/s(speed=100)。馬達有加速延遲(時間常數 0.1 s),輪速有約 0.5% 的雜訊;撞牆會停住。

### 動作(只設定馬達,持續運轉直到下一次設定)
| 簽名 | 說明 |
|---|---|
| `robot.forward(speed=60)` | 前進,speed 0~100 |
| `robot.backward(speed=60)` | 後退 |
| `robot.turn_left(speed=60)` / `robot.turn_right(speed=60)` | 原地左轉 / 右轉(speed=60 約 190°/s) |
| `robot.set_motors(left, right)` | 左右輪各自 -100~100(負數倒轉) |
| `robot.stop()` | 馬達停止(因慣性還會滑一小段) |

### 阻塞型輔助(執行到完成才往下)
| 簽名 | 說明 |
|---|---|
| `robot.move(distance_cm, speed=60)` | 前進(負數為後退)指定距離,用里程計量距離、陀螺儀維持直線,精度約 ±2 cm。撞到東西或超時會提前結束 |
| `robot.rotate(angle_deg, speed=60)` | 原地旋轉,**正數左轉(逆時針)、負數右轉**,精度約 ±1°。結束時硬煞車 |

### 感測器
| 簽名 | 回傳 |
|---|---|
| `robot.distance()` | 前方超音波距離(cm,float),從車頭量起,最大 200,雜訊 ±1。實際量 -7.5°/0°/+7.5° 三條射線取最小值 |
| `robot.line()` | `[左, 中, 右]` 三個反射感測器,1 = 黑線、0 = 亮。感測器在車頭前 7 cm、左右間距 3.5 cm,黑線寬 3 cm |
| `robot.color()` | 腳下顏色字串:`'black'`(黑線上)、`'red' 'green' 'blue' 'yellow'`(色塊)、`'white'`(其他) |
| `robot.heading()` | IMU 航向 0~360(float),雜訊 ±0.3° |
| `robot.position()` | `(x, y)` tuple(float) |
| `robot.bumped()` | 碰撞開關:碰撞後 0.15 秒內為 True |
| `robot.battery()` | 電量百分比(float),隨時間與行駛距離下降 |
| `robot.camera.find(color)` | `(found, cx, size)`:cx 為水平位置 -1(左)~1(右),size 為佔視野比例 0~1;沒看到回傳 `(False, 0.0, 0.0)`。視野 60°,距離 300 cm,被障礙物擋住看不到,已收集的球看不到 |
| `robot.camera.detect()` | 清單 `[{'label': 'ball', 'color': 'red', 'cx': ..., 'size': ...}, ...]`,依 size 由大到小 |

### 其他
| 簽名 | 說明 |
|---|---|
| `led.on()` / `led.off()` | LED 開關(預設白色) |
| `led.color(name)` | 設定顏色並點亮:`red green blue yellow white orange purple cyan`,其他名稱會報錯 |
| `buzzer.beep(ms=200)` | 蜂鳴(1~5000 毫秒),不阻塞 |
| `print(...)` | 輸出到畫面下方主控台(`printed` 檢查會比對這些輸出) |

球的收集:車身碰到球就算收集(球消失)。
所有函式都支援具名參數,例如 `robot.move(100, speed=40)`、`robot.set_motors(right=0, left=50)`。參數錯誤(型別、範圍)會以中文錯誤訊息並標示行號。

## 3. arm(3 自由度手臂 + 夾爪)API
肩關節離桌面 12 cm,上臂與前臂各 20 cm,最遠伸到離肩膀 40 cm。桌面 y = 0。**座標是側視圖平面:`x` = 離底座軸心的水平距離(可為負,表示在後方),`y` = 離桌面的高度**;底座旋轉(關節 0)決定手臂朝向哪個方位角(俯視、逆時針為正),物件與區域除了 `r`、高度,還有方位角 `yaw`。
關節範圍:0 底座 -90°~90°;1 肩 0°~180°(90° = 上臂直立);2 肘 0°~150°(0° = 前臂與上臂成一直線,正值向下彎)。關節角速度 90°/s,夾爪開合 0.4 秒。**初始姿勢**:關節 `[0, 90, 90]`,末端 (20, 32),夾爪張開。

| 簽名 | 說明 |
|---|---|
| `arm.set_joint(index, angle)` | 轉動單一關節到指定角度(阻塞)。index 只能 0/1/2,角度超出範圍報錯 |
| `arm.move_to(x, y)` | 逆運動學(肘朝上解),肩與肘同時轉(阻塞)。y < 0、超出可及範圍、太靠近底座都會報錯並說明原因 |
| `arm.gripper_open()` / `arm.gripper_close()` | 開/合夾爪(阻塞)。閉合完成時,若末端 3.5 cm 內有物件(且方位角相符)就夾住;張開時夾住的物件落到桌面 |
| `arm.position()` | `(x, y)` 末端位置(float) |
| `arm.holding()` | 是否夾著物體 |
| `arm.joint(index)` | 目前關節角度 |
| `arm.camera.find(color)` | `(found, x, y)`:該顏色物件中心的水平距離與高度(桌上的方塊 y = 2);沒有回傳 `(False, 0.0, 0.0)` |
| `arm.camera.bearing(color)` | (規格外的補充)該物件的方位角(度);沒有回傳 `None` |

## 4. 場地預設
`config.world` 取下列之一;`diffdrive` 搭配除 `pick-place` 以外的場地,`arm` 只能搭配 `pick-place`。每個預設有固定起點與命名區域(可用在 `reach`、`stop_in`、`pick_place` 的 `zone`)。

`config.params` 可微調:`start => [x, y, heading]`(diffdrive 起點)、`noise => 0`(關掉雜訊,預設 1)、`obstacles => [...]`(追加障礙物:`['x'=>,'y'=>,'w'=>,'h'=>]` 矩形或 `['x'=>,'y'=>,'r'=>]` 圓)、`zones => [...]`(新增或覆寫同名區域)、`balls => [...]`(取代球:`['name','color','x','y']`)、`objects => [...]`(取代手臂物件)。

## 5. 任務檢查(`check` / `checks`)
`checks` 是陣列,**全部同時成立**才算完成;任務一旦完成就不取消(跨多次執行也保留,按「重設」不會清掉)。**任務一開始不能已經成立**——只有 `no_collision`、`time_under` 的任務會在一開始就成立,必須搭配別的 check。`uses` 比對的是學員按下執行時的程式碼(不是起始程式碼是否已含有關鍵字:驗證工具會用 `starter` 檢查)。

| type | 欄位 | 成立條件 |
|---|---|---|
| `distance` | `min`,可選 `max` | 累計行駛距離(路徑長,cm;arm 為末端移動距離) |
| `reach` | `zone` | 機器人中心(arm 為末端)進入區域 |
| `stop_in` | `zone` | 在區域內停住(速度 < 1 cm/s、轉速 < 5°/s;arm 為動作完成)連續至少 0.5 秒 |
| `heading` | `target`,`tol`(預設 10) | 航向與 target 相差不超過 tol(度) |
| `no_collision` | — | 到目前為止沒有碰撞(撞牆、撞障礙物都算;持續頂著算一次) |
| `on_line_ratio` | `min` | 移動中中間感測器在黑線上的時間比例 ≥ min;累計移動時間不足 2 秒時不成立 |
| `collect` | `count`(預設 1) | 收集的球數(arm:夾起過的不同物件數) |
| `pick_place` | `object`(物件名或顏色)、`zone` | 物件已放開、停在桌面,且位置在區域內(arm 區域看 r 與方位角) |
| `time_under` | `seconds` | 目前模擬時間 ≤ seconds(搭配其他 check) |
| `printed` | `pattern` | 所有 print 輸出以換行串起後,符合 JS 正規表示式 |
| `uses` | `pattern` | 原始碼符合正規表示式(例如 `'\\bdef\\b'`) |
| `led` | `color` | LED 曾以該顏色亮過 |
| `sensor_read` | `name`,`min`/`max` 或 `value` | 曾讀到範圍內的值。name:`distance heading battery x y line`(三個感測器總和)`line_center color`(用 `value`)`camera_cx camera_size arm_x arm_y` |

## 6. 學員可用的 Python 子集與限制(`robot-lang.js`)
- 支援:賦值與 `+= -= *= /=`、`if/elif/else`、`while`、`for ... in range()/list`、`break/continue/pass`、`def`(參數、預設值、`return`)、`global`、f-string、list/tuple/dict、`print len range abs min max round int float str sum sorted`、`math`(**要先 `import math`** 或 `from math import ...`)、`time`(**要先 `import time`**:`time.sleep()`、`time.time()`),`sleep(s)` 不需 import。
- 不支援(會給中文錯誤):`class`、其他模組、`try/except`、`with`、`lambda`、生成式、`yield`、`async`、`eval/exec/open`。
- 另外**不支援**:閉包(內層函式讀外層函式的區域變數)、`sorted/min/max` 的 `key=`、切片賦值、`del`、`assert`、`raise`、`nonlocal`、`*args/**kwargs`、屬性賦值(`robot.x = 1`)、把學員函式當 callback 傳給內建函式。
- 回傳值型別:整數值是 int,其餘是 float;感測器的 float 即使剛好是整數也會顯示成 `90.0`;`position()`、`camera.find()` 等回傳 tuple。
- 無窮迴圈沒有 `sleep` 會被中止,提示「請在 while 迴圈裡加上 sleep(0.05) 之類的等待」。

## 7. 完整的 robot 單元範例(PHP)
```php
['title' => '互動模擬:開到目標點', 'type' => 'robot', 'xp' => 30,
 'content' => '倉庫裡的送貨小車要從左側的充電站出發,筆直開到場地右側的綠色卸貨點。這一課你會用程式控制馬達,學習「距離」「航向」與「停止」這三件事:先讓小車前進一段指定的距離,再練習原地轉向,最後讓它準確停在目標圈內並保持不動。模擬器會用里程計與航向感測器回報小車的狀態,右邊的任務清單會在你達成條件時自動打勾。前提:你已經學過變數與函式呼叫,不需要先會迴圈。',
 'config' => [
    'robot'  => 'diffdrive',
    'world'  => 'open-field',
    'starter'=> "# 讓小車前進\nrobot.forward(60)\nsleep(1)\nrobot.stop()\n",
    'tasks'  => [
        ['title' => '讓小車前進 50 公分以上', 'hint' => 'robot.move(60) 會前進 60 公分', 'check' => ['type' => 'distance', 'min' => 50]],
        ['title' => '原地左轉到航向約 90 度', 'hint' => 'rotate 的正數是左轉', 'check' => ['type' => 'heading', 'target' => 90, 'tol' => 8]],
        ['title' => '開到綠色目標點並停穩', 'hint' => '目標點叫 goal,離起點約 220 公分', 'checks' => [['type' => 'reach', 'zone' => 'goal'], ['type' => 'stop_in', 'zone' => 'goal']]],
    ],
    'solution'   => "robot.move(100)\nrobot.rotate(90)\nrobot.rotate(-90)\nrobot.move(120)\nrobot.stop()\nsleep(1)\n",
    'time_limit' => 60,
    'params'     => [],
 ],
],
```
注意:`solution` 是**字串**(多行用 `\n`),不會送到瀏覽器;`content` 至少 150 字、`tasks` 至少 3 個,每個要有 `title`、`hint` 與 `check`/`checks`。

## 8. 各場地範例與解答
以下每個範例都已由 `tools/test-robot-sim.mjs` 在模擬器實際跑過並完成全部任務(原始資料在 `tools/robot-examples.mjs`)。

### `open-field`(diffdrive)

空場地,四周是牆。畫面上有綠色 `goal`、藍色 `center`、橘色 `corner-ne` 三個目標標記。

- 場地大小:300 × 200 cm;起點與航向:(30, 100),0°
- 命名區域:
  - `start`:x 10~50,y 80~120
  - `goal`:圓心 (250, 100),半徑 15
  - `center`:圓心 (150, 100),半徑 20
  - `corner-ne`:x 260~300,y 160~200

範例任務與可通過的解答(`time_limit` 60):

1. 讓小車前進 50 公分以上 — `{"type":"distance","min":50}`
2. 原地左轉到航向約 90 度 — `{"type":"heading","target":90,"tol":8}`
3. 開到綠色目標點並停穩 — `[{"type":"reach","zone":"goal"},{"type":"stop_in","zone":"goal"}]`
4. 用 print 印出「前進完成」 — `{"type":"printed","pattern":"前進完成"}`

```python
robot.move(100)
print("前進完成", robot.position())
robot.rotate(90)
robot.rotate(-90)
robot.move(120)
robot.stop()
sleep(1)
```

### `line-track`(diffdrive)

黑線軌道:起點在左下,先向右直行,左彎向上,直行,再左彎轉向西,終點在左上。黑線寬 3 cm。
```
  y260 +------------------------------+
       |  [finish]<=====(弧)          |
       |               ||(直線)      |
       |        [checkpoint]          |
       |               ||             |
       | [start]==========(弧)        |
  y0   +------------------------------+ x300
```

- 場地大小:300 × 260 cm;起點與航向:(30, 50),0°
- 命名區域:
  - `start`:x 15~45,y 35~65
  - `checkpoint`:x 235~265,y 120~150
  - `finish`:x 60~95,y 205~235

範例任務與可通過的解答(`time_limit` 90):

1. 開到檢查點 — `{"type":"reach","zone":"checkpoint"}`
2. 沿黑線跑到終點,而且大部分時間都在線上 — `[{"type":"reach","zone":"finish"},{"type":"on_line_ratio","min":0.6}]`
3. 45 秒內跑完且沒有碰撞 — `[{"type":"reach","zone":"finish"},{"type":"no_collision"},{"type":"time_under","seconds":45}]`

```python
while True:
    left, center, right = robot.line()
    if center == 1:
        robot.set_motors(45, 45)
    elif left == 1:
        robot.set_motors(15, 45)
    elif right == 1:
        robot.set_motors(45, 15)
    else:
        robot.set_motors(30, 30)
    sleep(0.02)
```

### `obstacle-course`(diffdrive)

起點在左側中央,正前方有一面牆(`wall`:x 110~125,y 85~165),另有兩根圓柱(圓心 (240,60) r18、(300,150) r15)。終點 `goal` 在右側。繞牆走上方(y≈205)最順。

- 場地大小:400 × 250 cm;起點與航向:(30, 125),0°
- 命名區域:
  - `start`:x 10~50,y 105~145
  - `before-wall`:x 60~95,y 100~150
  - `checkpoint`:x 180~230,y 185~225
  - `goal`:圓心 (365, 125),半徑 18
- 障礙物:矩形 x 110~125,y 85~165;圓 (240, 60) r18;圓 (300, 150) r15

範例任務與可通過的解答(`time_limit` 60):

1. 前進超過 50 公分 — `{"type":"distance","min":50}`
2. 在牆前方的橘色區域停穩,不可撞牆 — `[{"type":"stop_in","zone":"before-wall"},{"type":"no_collision"}]`
3. 繞過牆,經過藍色檢查點 — `{"type":"reach","zone":"checkpoint"}`
4. 抵達終點且完全沒有碰撞 — `[{"type":"reach","zone":"goal"},{"type":"no_collision"}]`

```python
while robot.distance() > 30:
    robot.forward(40)
    sleep(0.02)
robot.stop()
sleep(1)
robot.rotate(90)
robot.move(80)
robot.rotate(-90)
robot.move(255)
robot.rotate(-90)
robot.move(80)
robot.rotate(90)
robot.move(35)
robot.stop()
```

### `maze`(diffdrive)

5×5 格迷宮,每格 50 cm,牆厚 4 cm,決定性產生(固定種子,每次都一樣,且任兩格皆可到達)。起點格在左下 (0~50, 0~50),出口 `goal` 在右上格。起始航向 0°(朝東)。

- 場地大小:250 × 250 cm;起點與航向:(25, 25),0°
- 命名區域:
  - `start`:x 0~50,y 0~50
  - `goal`:x 200~250,y 200~250

範例任務與可通過的解答(`time_limit` 300):

1. 走出起點格(累計行駛 50 公分以上) — `{"type":"distance","min":50}`
2. 抵達迷宮出口 — `{"type":"reach","zone":"goal"}`
3. 抵達出口且沒有撞牆 — `[{"type":"reach","zone":"goal"},{"type":"no_collision"}]`

```python
# 右手法則:每到一格,依 右 → 前 → 左 → 後 的順序找得過去的方向
while True:
    robot.rotate(-90)
    if robot.distance() > 40:
        robot.move(50)
    else:
        robot.rotate(90)
        if robot.distance() > 40:
            robot.move(50)
        else:
            robot.rotate(90)
            if robot.distance() > 40:
                robot.move(50)
            else:
                robot.rotate(90)
                robot.move(50)
```

### `color-zones`(diffdrive)

四個 50×50 色塊:紅(左上)、綠(左下)、藍(右上)、黃(右下);`robot.color()` 在色塊上回傳色名,其他地方回傳 `white`。

- 場地大小:300 × 200 cm;起點與航向:(30, 100),0°
- 命名區域:
  - `start`:x 10~50,y 80~120
  - `zone-red`:x 85~135,y 125~175
  - `zone-green`:x 85~135,y 25~75
  - `zone-blue`:x 205~255,y 125~175
  - `zone-yellow`:x 205~255,y 25~75

範例任務與可通過的解答(`time_limit` 90):

1. 開到紅色區域並印出腳下的顏色 — `[{"type":"reach","zone":"zone-red"},{"type":"printed","pattern":"red"}]`
2. 開到藍色區域 — `{"type":"reach","zone":"zone-blue"}`
3. 讓 LED 亮綠燈 — `{"type":"led","color":"green"}`
4. 依序抵達黃色與綠色區域,並讀到 green — `[{"type":"reach","zone":"zone-green"},{"type":"sensor_read","name":"color","value":"green"}]`

```python
robot.move(80)
robot.rotate(90)
robot.move(50)
print(robot.color())
led.color("green")
robot.rotate(-90)
robot.move(120)
robot.rotate(-90)
robot.move(100)
robot.rotate(-90)
robot.move(120)
print(robot.color())
```

### `ball-hunt`(diffdrive)

空場地中散落 4 顆球(紅、綠、藍、黃,半徑 4 cm)。相機視野 60°、距離 300 cm。碰到球就收集(球消失)。`home` 是起點附近的藍色區域。

- 場地大小:300 × 200 cm;起點與航向:(30, 100),0°
- 命名區域:
  - `start`:x 10~50,y 80~120
  - `home`:x 0~60,y 70~130
- 球:red (140, 120);green (200, 60);blue (250, 140);yellow (270, 40)

範例任務與可通過的解答(`time_limit` 90):

1. 收集 1 顆球 — `{"type":"collect","count":1}`
2. 收集 3 顆球 — `{"type":"collect","count":3}`
3. 收集完成後印出「收集完成」 — `{"type":"printed","pattern":"收集完成"}`
4. 程式要用到 def 自訂函式 — `{"type":"uses","pattern":"\\bdef\\b"}`

```python
def hunt(color):
    seen = False
    while True:
        found, cx, size = robot.camera.find(color)
        if found:
            seen = True
            robot.set_motors(40 + 25 * cx, 40 - 25 * cx)
        elif seen:
            break
        else:
            robot.turn_left(25)
        sleep(0.05)
    robot.stop()

for color in ["red", "green", "blue"]:
    hunt(color)
print("收集完成")
```

### `pick-place`(arm)

手臂側視圖。底座在 r=0,肩關節高 12 cm,上臂與前臂各 20 cm(最遠伸到離肩膀 40 cm)。桌面高度 y=0。桌上有 `red-cube`(r=28、方位 0°)與 `blue-cube`(r=18、方位 0°),邊長 4 cm。

- 命名區域:
  - `home`:r -8~8 cm,高度 44~70 cm,底座角度 -90°~90°
  - `bin`:r 18~32 cm,高度 -1~8 cm,底座角度 50°~80°
  - `tray`:r 14~30 cm,高度 -1~8 cm,底座角度 -80°~-50°
  - `table-red`:r 24~32 cm,高度 -1~8 cm,底座角度 -10°~10°
- 物件:`red-cube` r=28, 方位 0°;`blue-cube` r=18, 方位 0°

範例任務與可通過的解答(`time_limit` 120):

1. 把手臂舉到 home 區域 — `{"type":"reach","zone":"home"}`
2. 夾起一個方塊 — `{"type":"collect","count":1}`
3. 把紅色方塊放進 bin — `{"type":"pick_place","object":"red-cube","zone":"bin"}`
4. 把藍色方塊放進 tray — `{"type":"pick_place","object":"blue-cube","zone":"tray"}`

```python
def pick_and_drop(color, yaw):
    found, x, y = arm.camera.find(color)
    arm.gripper_open()
    arm.set_joint(0, arm.camera.bearing(color))
    arm.move_to(x, y + 8)
    arm.move_to(x, y)
    arm.gripper_close()
    arm.move_to(x, y + 12)
    arm.set_joint(0, yaw)
    arm.move_to(x, y)
    arm.gripper_open()
    arm.move_to(x, y + 12)
    arm.set_joint(0, 0)

arm.move_to(0, 50)
pick_and_drop("red", 65)
pick_and_drop("blue", -65)
print("done")
```

