Create: Sequenced Mechanical Arm

# Create: Sequenced Mechanical Arm · 可编程动力臂

**Write a program on an operation table, insert it into the arm, and the arm performs the steps in
order** — take, deposit, stash, unload, deploy, attack, mine, use, filter, wait, send/receive a
redstone-link signal, call a sub-task, return, throw. An addon for **Create**.

The vanilla mechanical arm only does "A → B". This one hands you the **process**: a step table you
can edit, save and share — and since every coordinate is **relative to the arm that runs it**, the
same table works on any arm, anywhere, with no edits.

**在一张「操作表」上写下一串操作，插进臂里，它就按顺序一件一件地做** —— 取、放、存、卸、组装、
攻击、挖掘、使用、过滤、等待、收发信号、调用子任务、返回、抛错。**Create（机械动力）附属模组。**

原版动力臂只能"从 A 拿到 B"。这条臂把**流程**也交给你：一张可编辑、可保存、可分享的步骤表 ——
而所有坐标都是**相对执行它的那条臂**的，所以同一张表插到任何一条臂上都不需要改。

---

## The items · 物品

- **Sequenced Mechanical Arm** — the arm itself. Needs rotation speed, like the vanilla mechanical arm.
- **Operation Table** — the program card: holds the whole program (1 main task + sub-tasks) as text.
- **Operation Record Table** — a key: sneak-right-click an arm to **export** its program to a `.sma` file.
- **Program Import Table** — a table: pick a local `.sma` file and **import** it onto a blank operation table.

- **可编程动力臂** —— 臂本体，和原版动力臂一样需要转速。
- **操作表** —— 程序卡：一整份程序（1 个主任务 + 若干子任务）以文本形式存在卡上。
- **操作记录表** —— 一把钥匙：潜行右键一条臂，把它的程序**导出**成 `.sma` 文件。
- **操作导入桌** —— 一张桌子：从本机挑一个 `.sma` 文件，**导入**到一张空白操作表上。

---

## Quick start · 快速上手

1. Place a **sequenced arm**, give it rotation speed (adjacent cogwheel, like the vanilla arm).
2. Hold the **operation table** and **sneak-right-click** to switch mode (record ⇄ edit).
3. **Middle-click a block** while holding the table: that position becomes the **origin**.
4. In **record mode**, right-click blocks — each click appends a matching operation, with coordinates
   auto-filled as *block you look at − origin*.
5. Hold the table and **right-click the arm**: the program is loaded and starts running.

1. 放下「可编程动力臂」，给它**转速**（和原版动力臂一样，靠旁边的齿轮传动）。
2. 手持「操作表」**潜行右键**切换模式（录入 ⇄ 编辑）。
3. 手持操作表**中键对着方块**：把那一格设成**原点**。
4. **录入模式**下对着方块右键 —— 每次追加一条对应操作，坐标自动填成「看向的方块 − 原点」。
5. 手持操作表**右键动力臂**：程序导入这条臂，立刻开始跑。

---

## The operation table · 操作表

One card holds the whole program: **1 main task that loops forever** + sub-tasks.
Limits: **32 tasks**, **1024 entries**, notes ≤ 128 characters. The program is stored as **text**
(`.sma`), so saves are readable, diffable, hand-editable and shareable.

**Two modes.** *Record* appends one operation per right-click (an origin must be set first). *Edit*
opens the in-game editor, where every entry can be changed: target coordinates, facing, item count,
filter side, unload mode, signal frequency, plus per-entry **success exit**, **failure exit** and
**note**. `ALT + scroll` switches which task you are editing.

**Origin and relative coordinates.** An entry's coordinates are always relative: *target = arm
position + offset*. The origin only converts world positions while recording and draws the blue
box — it is not part of the program and is not read at runtime.

一张卡装着整份程序：**1 个主任务（无限循环）+ 若干子任务**。上限 **32 个任务**、**1024 条操作**、
单条备注 ≤ 128 字。程序以**文本**（`.sma`）形式存盘，所以可读、可 diff、可手改、可发给别人。

**两种模式。** *录入*：右键一次追加一条操作（必须先设原点）。*编辑*：打开游戏内编辑器，逐条改目标
坐标、朝向、个数、过滤位置、卸货模式、信号频率，以及每条自己的**成功后**、**失败后**和**备注**。
`ALT + 滚轮`换正在编辑的那条任务。

**原点与相对坐标。** 条目坐标永远是相对的：*目标 = 臂的位置 + 偏移*。原点只在录制时把世界坐标换算
成相对坐标、并画那个蓝框 —— 它不属于程序，运行时不读它。

---

## The 14 operations · 14 种操作

| Operation | Coords | Operands | Does |
|---|---|---|---|
| `take` | yes | `count=`, `countmode=` | take items from the target into the arm |
| `deposit` | yes | `count=`, `countmode=` | put the held items into the target |
| `stash` | no | `count=`, `countmode=` | move the held stack into the arm's own overflow storage |
| `unload` | yes | `mode=as_much` / `mode=all` | unload the overflow storage into the target |
| `deploy` | yes | — | apply the held applicator to items on a depot / belt |
| `attack` | yes | `face=` | swing once at that cell (hits an entity) |
| `mine` | yes | `face=` | break the block there (never entities) |
| `use` | yes | `face=`, `sneak=true` | right-click once; `sneak=true` = sneak-use |
| `filter` | container mode only | `source=held\|container`, `item=` | compare one item against a filter, then branch |
| `wait` | no | a time | wait in place |
| `signal` | no | `recv on\|off`, `send_on`, `send_off`, `freq=`, `range=`, `place=` | redstone-link frequency: receive / send / cut |
| `call` | no | task name, `repeat=`, `shift=` | run another task, then come back |
| `break` | no | — | end the current task (return to the caller, or stop the arm) |
| `throw` | no | one quoted message | fail immediately |

- `count=` is 1–64; `countmode=exact` requires exactly N, `atmost` (default) takes/gives as much as it can.
- `unload` `mode=all` is **atomic**: if the target cannot hold everything at once, nothing is unloaded
  **and the arm does not even reach over**.
- `signal` `range=` (0–256) constrains *receiving* only; `place=` is the hold time of `send_on`
  (`0t` = forever). `send_off` takes neither.
- **`take` / `deposit` / `unload` / `deploy`** require the target to be a **Create interaction
  point**; **`attack` / `mine` / `use`** work on any block.

| 操作 | 坐标 | 参数 | 做什么 |
|---|---|---|---|
| `take` | 要 | `count=`、`countmode=` | 从目标取出物品进臂内 |
| `deposit` | 要 | `count=`、`countmode=` | 把手上的物品放进目标 |
| `stash` | 不要 | `count=`、`countmode=` | 把手上的那一摞收进臂自己的溢出库存 |
| `unload` | 要 | `mode=as_much` / `mode=all` | 把溢出库存卸给目标 |
| `deploy` | 要 | —— | 用臂手上的应用物加工置物台 / 传送带上的物品 |
| `attack` | 要 | `face=` | 对那一格挥一击（打实体） |
| `mine` | 要 | `face=` | 挖那一格的方块（永远不碰实体） |
| `use` | 要 | `face=`、`sneak=true` | 右键一次；`sneak=true` = 潜行右键 |
| `filter` | 仅容器模式 | `source=held\|container`、`item=` | 拿一份物品比过滤器，按结果分流 |
| `wait` | 不要 | 时间 | 原地等待 |
| `signal` | 不要 | `recv on\|off`、`send_on`、`send_off`、`freq=`、`range=`、`place=` | 红石链接频率：接收 / 发送 / 中断 |
| `call` | 不要 | 任务名、`repeat=`、`shift=` | 跑一趟别的任务再回来 |
| `break` | 不要 | —— | 立刻结束当前任务（返回调用方，或收工停机） |
| `throw` | 不要 | 一句带引号的文案 | 立刻失败结束 |

- `count=` 取 1–64；`countmode=exact` 要求**恰好** N 个，`atmost`（默认）能取/放多少算多少。
- `unload` 的 `mode=all` 是**原子**的：目标一次盛不下全部，就一件都不卸，**臂也不伸过去**。
- `signal` 的 `range=`（0–256）只约束**接收**；`place=` 只有 `send_on` 有（`0t` = 一直保持），
  `send_off` 既没有持续时间也没有距离。
- **`take` / `deposit` / `unload` / `deploy`** 要求目标是 **Create 交互点**；
  **`attack` / `mine` / `use`** 对任意方块都能试。

---

## Program flow · 走向与分支

- Every entry has two exits — **on success** and **on failure**: *skip* (continue) or *jump to N*
  (entry number inside that task, 1-based; `entries + 1` = this round is over).
- **`timeout=`** is the retry window: the entry retries **in place** until it elapses, then the
  failure exit applies. **No `timeout=` means retry forever** — that is the default.
- **`call`** runs another task and comes back (`repeat=0` = forever, `shift=` offsets everything that
  sub-task does). Jumping to a *task name* instead **switches** to it — use `call` for a round trip.
- **`break`** ends the current task; **`throw`** ends it as a failure. The main task itself loops
  forever, so "keep doing this" needs no loop.
- Signals are **persistent levels**: they stay until something cuts them (`send_off`, a card swap,
  or a stop).

- 每条操作都有两个出口 —— **成功后**、**失败后**：*跳过*（继续下一条）或 *跳转 N*
  （本任务内的条目序号，从 1 数；`条数 + 1` = 这一轮到此为止）。
- **`timeout=`** 是重试窗口：这段时间内**原地重试**，超时才走失败后。**不写就是一直重试** ——
  这是默认值。
- **`call`** 跑一趟别的任务再回来（`repeat=0` = 无限，`shift=` 给整个子任务加坐标偏移）。
  写**任务名**的跳转则是**换到那个任务**去 —— 要"有去有回"请用 `call`。
- **`break`** 结束当前任务，**`throw`** 以失败结束。主任务本身无限循环，所以"一直干这个"不用写循环。
- 信号是**持久电平**：一直保持，直到有东西清掉它（`send_off`、换卡、停机）。

---

## The arm itself · 动力臂本身

- Right-click with an **operation table** = load that program (the card is not consumed).
- **Bare hand right-click** = take back the item in the arm's hand.
- **Bare hand + sneak right-click** = take one stack out of the overflow storage (LIFO).
- Inventory: **1 held slot + 10 overflow slots**. Full storage never blocks an action; items that
  cannot be caught simply drop on the ground.
- Funnels and pipes can only insert into the **held slot**; overflow slots are extract-only.
- **Create's engineer's goggles** on an arm show its task, step, state, failure reason, held item,
  overflow contents and speed.

- **手持操作表右键** = 装载那份程序（卡不会被消耗）。
- **空手右键** = 取走臂手上的那一件。
- **空手潜行右键** = 从溢出库存取走一组（后进的先出）。
- 库存：**1 格手持 + 10 格溢出**。满仓不阻塞动作，捡不下的掉落物正常掉在地上。
- 漏斗 / 管道只能往**手持格**输入；溢出格只出不进。
- 戴 **Create 工程师护目镜**看臂：任务、第几步、状态、失败原因、手持物、溢出内容与转速。

---

## Import & export · 导入导出

Programs are text, and text can live as files: back them up, share them, hand-edit them, keep them in
version control. Files are **client-side**: `sequenced_arm/scripts/<name>.sma` in the game directory
(same treatment as Create's `schematics/` — the server never touches them). Max 60 KB per file.

- **Export:** the **Operation Record Table** — sneak-right-click an arm, type a file name, done.
  Or `/sma code export [name]` for the operation table in your hand.
- **Import:** the **Program Import Table** — a blank operation table in the input slot, pick a script,
  confirm; the table is only consumed if compiling succeeds. Or `/sma code import <name>`.
- `/sma code check` compiles the table in your hand and lists every error **with its line number**.
- A full bilingual writer's manual ships with the mod: `sequenced_arm/docs/sma_zh_cn.md` and
  `sma_en_us.md` are written on first launch if missing (**files you edited yourself are never
  overwritten** — delete one to get the factory version back).

程序是文本，文本可以落成文件：备份、分享、手改、进版本管理都行。文件在**客户端**的游戏目录
`sequenced_arm/scripts/<名字>.sma`（和 Create 的 `schematics/` 一个待遇 —— 服务端不碰）。单份上限 60 KB。

- **导出**：**操作记录表** —— 潜行右键一条臂，输入文件名即可。或 `/sma code export [名字]`
  导出主手那张操作表。
- **导入**：**操作导入桌** —— 输入槽放一张空白操作表，选脚本、确认；编译通过才消耗那张表。
  或 `/sma code import <名字>`。
- `/sma code check` 编译主手那张表，把每一处错误**带行号**列出来。
- 模组自带一份**中英双语编写手册**：首次启动时放到 `sequenced_arm/docs/sma_zh_cn.md` 与
  `sma_en_us.md`（**你改过的文件不会被覆盖**；想要出厂版本就删掉它，下次启动重新生成）。

---

## Requirements · 环境要求

| | |
|---|---|
| Minecraft | **1.21.1** |
| NeoForge | **21.1.251** |
| Create | **6.0.10** or newer (**required**) |
| Java | **21** |

---

## Good to know · 注意

- **Set the origin before recording** — without one, recording refuses (there is no base for the
  relative coordinates).
- The default failure exit is **"retry forever"**. If you want "no items → skip", set the failure
  exit explicitly.
- The arm's reach is Create's `mechanicalArmRange` (default 5 blocks); targets beyond it report an
  error instead of acting.
- Unloading never dumps items on the ground; `mode=all` is atomic, `mode=as_much` may unload partially.
- Programs saved before 0.1.0 were compiled NBT and **will not load** in current versions —
  re-record them or import the `.sma`.

- **录制前先设原点** —— 没有原点时录制会被拒绝（相对坐标没有基准）。
- 「失败后」的默认去向是**一直重试**。如果想让"没货就跳过"，必须**显式**设失败后。
- 臂够得着的范围 = Create 的 `mechanicalArmRange`（默认 5 格），超出会直接报错而不是动手。
- 卸货**不会**把东西卸在地上；`mode=all` 是原子的，`mode=as_much` 才可能只卸进去一部分。
- 0.1.0 之前存的是编译后的 NBT，**旧存档里的程序读不出来** —— 重录一遍，或把 `.sma` 导回去。

---

## License · 许可

MIT. Built on top of **[Create](https://github.com/Creators-of-Create/Create)** (MIT, © simibubi and
contributors): the arm's two-segment IK angles follow Create's `ArmAngleTarget`, and the UI pieces
(ghost slots, action bar, redstone-link frequencies) reuse the mod itself rather than re-implementing
a second set of rules.

MIT 许可。建立在 **[Create（机械动力）](https://github.com/Creators-of-Create/Create)**（MIT，© simibubi
及其贡献者）之上：两节臂的 IK 角度解算与 Create 的 `ArmAngleTarget` 一致，幽灵槽、行为条、
红石链接频率这些机制都直接复用本体，而不是再写一套规则。