/batch

name: unity-batch
description: Unified batch and async-job orchestration

Unity Batch Skills

When to use

• Operating on many objects at once
• Running or polling long async jobs
• Preview-then-commit bulk edits

The `POST /skills/batch` endpoint, query → preview → execute bulk edits, execution reports and async jobs. Parameters come from the schema (`GET /skills/schema?category=Workflow&wire=v2`, or `?category=Validation` for the fixers), never from a skill's name; execution and dryRun rules: root [SKILL.md](../../SKILL.md).

POST /skills/batch — several skills, one HTTP call

An **HTTP endpoint, not a skill**: never send `skills_batch` to `POST /skill/<name>`. It runs up to 50 ordinary skill calls in order inside one main-thread job, each through the full single-skill pipeline (validation, permission gate, its own Undo group, audit): one round trip and one main-thread wake-up instead of N, the biggest saving once there are 3+ writes.

POST /skills/batch
{
  "steps": [
    {"skill": "gameobject_create", "args": {"name": "Cube", "primitiveType": "Cube"}},
    {"skill": "component_add", "args": {"entityId": {"$ref": "$0.entityId"}, "componentType": "Rigidbody"}}
  ],
  "continueOnError": false
}

| Body field | Default | Meaning | |---|---|---| | `steps` | required | `{skill, args}` objects, in order. More than 50 → `400 SEMANTIC_INVALID`; split the call. | | `continueOnError` | `false` | `false` = stop at the first failure; `true` = record it and keep going. | | `params` | none | Values for `{"$param":"name"}` or `{"$param":"name","default":X}` nodes in args; static, resolved before `$ref`; a missing slot without default fails that step. |

• **`$ref`**: an args object whose only key is `$ref`, `{"$ref":"$N.path"}`, is replaced by the value at `path` (e.g. `entityId`, `results[0].path`; bare `$N` = the whole result) in the result of earlier successful step `N` (0-based). Only structured args are scanned, never strings. A ref that cannot resolve (forward, failed step, no match) fails its step with `SEMANTIC_INVALID`. Refer to created objects through `$ref` (`entityId`, any version; the instanceId before 6000.4), not by name: a same-named existing object may win a name lookup.
• **Query**: `?mode=dryRun` (the batch dryRun gate) validates every step, executes nothing and never halts; a step may name an object or component an earlier step adds (a warning notes skipped live checks) and `$ref` args get a structural check only (`refsValidated`). `?mode=transactional` is all-or-nothing with Undo rollback, rejected up front (`400`) for `continueOnError:true` or a step it cannot undo (unknown skill, may reload, invoke/scenario, particle playback). `?diff=1` adds a net `sceneDiff`; `?wire=v2` slims dryRun step payloads; `expectInstance` / `expectProject` work as on `/skill`. `?mode=plan` is not supported. `mode` / `dryRun` may sit in the body instead: each key resolves query-first and a blank value counts as absent. Any key outside these (body: `steps`, `params`, `continueOnError`, `mode`, `dryRun`) is `400 UNKNOWN_PARAM`.

**Reading the response.** HTTP `200` whenever the batch ran; only a rejected request (bad body, >50 steps, unknown mode or key) is `4xx`.

{"status":"partial","mode":"execute","dryRun":false,"executed":2,"failed":1,
 "results":[{"index":0,"skill":"...","status":"success","result":{...}},
            {"index":1,"skill":"...","status":"error","error":{"errorCode":"...","error":"..."}},
            {"index":2,"skill":"...","status":"skipped"}]}

• `status`: `completed` (nothing failed), `partial`, or `rolled_back` (transactional: executed steps become `rolled_back`, asset-writing ones flagged `rollbackReliability:"partial"`). `mode` / `dryRun` echo what actually ran; every entry carries `index` and `skill`.
• **Partial failure**: `success` steps are applied; the failed step's Undo-recorded changes are reverted; `skipped` steps never ran. Resend only the fixed failed step and the skipped ones, never the successful ones.
• **Authorization always interrupts**, `continueOnError` notwithstanding: a `MODE_RESTRICTED` / `CONFIRMATION_REQUIRED` step halts the batch and returns its full payload (grant token included); complete the grant, then resubmit the remaining steps.

> **Not the same as `batch_execute`.** `batch_execute(confirmToken)` commits *one* previewed bulk operation (one verb over N objects). `POST /skills/batch` composes *N different skills* over any targets and takes no token; it never skips the preview/confirm gate — a `batch_execute` step still needs its own `confirmToken`.

**Jobs.** When a skill or step returns a `jobId` (async execution, tests, compiles), wait with `GET /jobs/{id}?wait=<s>` (up to 120 s; answers once the job is terminal, with `resultData`; `waitTimedOut:true` = GET it again; a `503` during a domain reload = repeat the same URL) or poll `GET /jobs/{id}`. Both stay out of the main-thread skill queue and are far smaller than `job_status`; `job_wait` blocks the main thread (max 2 s).

Preview → execute

1. Select with `queryJson` (filters ANDed: `name` substring and `namePattern` .NET regex, case-insensitive unless `caseSensitive:true` or `(?-i)`; `path` / `parentPath` exact, `underPath` any depth; `entityId`, `instanceId`, `tag`, `layer`, `componentType`, `sceneName`, `active`, `isStatic`, `prefabSource`, `includeInactive` (false), `limit` (500)); `batch_query_*` shows what matches. A `limit` cut shows as `truncated:true` with the full `totalMatched` (`count` stops at `limit`); previews return both and cover only `limit` matches. 2. Preview with `batch_preview_*` or a fixer (`batch_fix_missing_scripts`, `batch_standardize_naming`, `batch_set_render_layer`, `batch_replace_material`, `batch_cleanup_temp_objects`). Previews are read-only and return `{confirmToken, kind, summary, riskLevel, targetCount, executableCount, skipCount, totalMatched, truncated, sampleChanges: [{targetPath, action, before, after}], skipReason