Unity Batch

Triggers

• Operating on many objects at once
• Running or polling long async jobs
• Preview-then-commit bulk edits
• 一次性操作大量对象、运行或轮询长时异步任务、先预览后提交的批量编辑

Unity Batch Skills

The POST /skills/batch endpoint, query → preview → execute bulk edits, execution reports and async jobs. Parameters come from the schema, never from a skill's name; execution and dryRun rules: root 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": {"instanceId": {"$ref": "$0.instanceId"}, "componentType": "Rigidbody"}}
  ],
  "continueOnError": false
}

• $ref: an args object whose only key is $ref, {"$ref":"$N.path"}, is replaced by the value at path (e.g. instanceId, 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 (instanceId, or entityId on Unity 6000.4+) rather than 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 an earlier step would create (a warning notes the 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 an unknown skill, a step that may trigger a domain reload, or continueOnError:true. ?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).