| name | unity-batch |
| description | Batch query, preview-confirm-execute, async job orchestration, and bulk scene cleanup for UnitySkills. Use when users want a unified batch query (gameobjects/components/assets), preview before mutation (rename/set property/replace material/missing scripts/standardize naming/render layer/cleanup temp), execute with confirmToken, manage async jobs (status/progress/wait/logs/list/cancel), inspect or list reports, retry failed items, or validate scene objects. Triggers: batch, preview, dry-run, confirmToken, execute batch, batch report, batch retry, job, jobId, async job, job status, job progress, job wait, job logs, job cancel, query gameobjects, query components, query assets, batch rename, batch set property, batch replace material, batch fix missing scripts, batch standardize naming, batch set render layer, batch cleanup temp, batch validate scene, 批处理, 批量, 预览执行, 确认令牌, 异步作业, 作业状态, 作业进度, 作业等待, 作业日志, 作业取消, 批量查询, 批量重命名, 批量改属性, 批量换材质, 修复缺失脚本, 规范命名, 清理临时对象, 场景校验. |
Unity Batch Skills
Batch workflow orchestration for query, preview, execution, reports, and async jobs.
Operating Mode
本模块共 22 个 skill，按 Operation 区分为两类：
- 18 个 SemiAuto（query / preview / report / job 查询类）：
batch_query_gameobjects / batch_query_components / batch_query_assets / batch_preview_rename / batch_preview_set_property / batch_preview_replace_material / batch_report_get / batch_report_list / job_status / job_progress / job_logs / job_list / batch_fix_missing_scripts / batch_standardize_naming / batch_set_render_layer / batch_replace_material / batch_validate_scene_objects / batch_cleanup_temp_objects。Approval 模式下可直接执行。
- 4 个 FullAuto（Execute 类，C# 未标
Mode 走默认 SkillMode.FullAuto）：batch_execute / job_wait / job_cancel / batch_retry_failed。Approval 模式下首次调用返 MODE_RESTRICTED，走 grant 协议。
- Auto / Bypass：两类都直接执行。不含 NeverInSemi 高危 skill（无 Delete/MayEnterPlayMode/MayTriggerReload 标记）。
注意：batch_execute(confirmToken) 本身放行，但它执行的 preview 内容可能包括对场景对象的删除/改属性等高影响动作 —— 请确保 batch_preview_* 返回的 sample/risk 字段已审阅。confirmToken 一次性消费、过期需重新 preview。
DO NOT (common hallucinations):
- Always call a
batch_preview_* skill first — batch_execute requires a confirmToken from a preview, it cannot be called directly
batch_run does not exist → use batch_execute(confirmToken)job_poll / job_result do not exist → use job_status to check and retrieve async job resultsbatch_delete / batch_move do not exist → use asset module for asset-level operations
Routing:
- For asset-level bulk operations (move, copy, delete) →
asset module
- For workflow session/task undo tracking →
workflow module
- For scene object validation →
batch_validate_scene_objects (this module)
- For async job polling →
job_status / job_wait (this module)
Skills
batch_query_gameobjects
Query GameObjects with unified batch filters. queryJson supports name/path/instanceId/tag/layer/active/componentType/sceneName/parentPath/prefabSource/includeInactive/limit.
| Parameter | Type | Required | Default | Description |
|---|
queryJson | string | No | null | JSON query filter envelope |
sampleLimit | int | No | 20 | Max sample objects returned |
batch_query_components
Query components with unified batch filters. Optional componentType narrows the result.
| Parameter | Type | Required | Default | Description |
|---|
queryJson | string | No | null | JSON query filter envelope |
componentType | string | No | null | Optional component type constraint |
sampleLimit | int | No | 20 | Max sample objects returned |
batch_query_assets
Query project assets by type, path pattern, and labels. Read-only.
| Parameter | Type | Required | Default | Description |
|---|
searchFilter | string | No | null | Raw Unity AssetDatabase filter string |
folder | string | No | "Assets" | Search root folder |
typeFilter | string | No | null | Asset type (prefix t: optional, e.g. Texture2D) |
namePattern | string | No | null | Case-insensitive regex for filename |
labelFilter | string | No | null | Asset label (prefix l: optional) |
maxResults | int | No | 200 | Max results returned |
batch_preview_rename
Preview batch renaming. mode supports prefix / suffix / replace / regex_replace.
| Parameter | Type | Required | Default | Description |
|---|
queryJson | string | No | null | JSON query filter envelope |
mode | string | No | "prefix" | Rename mode |
prefix | string | No | null | Prefix to add |
suffix | string | No | null | Suffix to add |
search | string | No | null | Plain text search term |
replacement | string | No | null | Plain text replacement |
regexPattern | string | No | null | Regex search pattern |
regexReplacement | string | No | null | Regex replacement text |
sampleLimit | int | No | DefaultSampleLimit | Max preview items |
batch_preview_set_property
Preview setting a component property or field across queried targets.
| Parameter | Type | Required | Default | Description |
|---|
queryJson | string | No | null | JSON query filter envelope |
componentType | string | No | null | Target component type |
propertyName | string | No | null | Property or field name |
value | string | No | null | Literal value |
referencePath | string | No | null | Scene reference path |
referenceName | string | No | null | Scene reference object name |
assetPath | string | No | null | Asset reference path |
sampleLimit | int | No | DefaultSampleLimit | Max preview items |
batch_preview_replace_material
Preview replacing Renderer materials across queried targets.
| Parameter | Type | Required | Default | Description |
|---|
queryJson | string | No | null | JSON query filter envelope |
materialPath | string | No | null | Replacement material asset path |
sampleLimit | int | No | DefaultSampleLimit | Max preview items |
batch_execute
Execute a previously previewed batch operation by confirmToken. Large operations return a jobId.
| Parameter | Type | Required | Default | Description |
|---|
confirmToken | string | Yes | - | Preview confirmation token |
runAsync | bool | No | true | Run as async job |
chunkSize | int | No | 100 | Batch execution chunk size |
progressGranularity | int | No | 10 | Emit a progressEvent every N items processed |
batch_report_get
Get a batch execution report by reportId.
| Parameter | Type | Required | Default | Description |
|---|
reportId | string | Yes | - | Batch report identifier |
batch_report_list
List recent batch reports.
| Parameter | Type | Required | Default | Description |
|---|
limit | int | No | 20 | Max reports returned |
job_status
Get status for an asynchronous UnitySkills job. Supports recentCount query param (1–200, default 10) to include the last N progressEvents in the response as recentProgress.
| Parameter | Type | Required | Default | Description |
|---|
jobId | string | Yes | - | Job identifier |
recentCount | int | No | 10 | Number of recent progress events to include in recentProgress |
job_progress
Get fine-grained progress events for a job via incremental polling. Use offset to fetch only new events since the last call (pass previous totalCount as next offset).
Note: Also exposed as HTTP GET /jobs/{id}/progress and Python client.get_job_progress(job_id, offset) — all three paths share the same response shape.
| Parameter | Type | Required | Default | Description |
|---|
jobId | string | Yes | - | Job identifier |
offset | int | No | 0 | Skip first N events (use previous totalCount for incremental polling) |
Response fields: jobId, status, totalCount, offset, events[] (timestamp ms, progress, stage, description), terminal.
job_logs
Get structured logs for a UnitySkills job.
| Parameter | Type | Required | Default | Description |
|---|
jobId | string | Yes | - | Job identifier |
limit | int | No | 100 | Max log entries returned |
job_list
List recent UnitySkills jobs.
| Parameter | Type | Required | Default | Description |
|---|
limit | int | No | 20 | Max jobs returned |
job_wait
Wait for a UnitySkills job to finish or until timeoutMs elapses.
| Parameter | Type | Required | Default | Description |
|---|
jobId | string | Yes | - | Job identifier |
timeoutMs | int | No | 10000 | Wait timeout in milliseconds |
job_cancel
Cancel a UnitySkills job if the job supports cancellation.
| Parameter | Type | Required | Default | Description |
|---|
jobId | string | Yes | - | Job identifier |
batch_fix_missing_scripts
Preview batch removal of missing scripts. Execute with batch_execute(confirmToken).
| Parameter | Type | Required | Default | Description |
|---|
queryJson | string | No | null | JSON query filter envelope |
sampleLimit | int | No | DefaultSampleLimit | Max preview items |
batch_standardize_naming
Preview standardizing names by trimming whitespace and normalizing separators. Execute with batch_execute(confirmToken).
| Parameter | Type | Required | Default | Description |
|---|
queryJson | string | No | null | JSON query filter envelope |
separator | string | No | "_" | Replacement separator |
sampleLimit | int | No | DefaultSampleLimit | Max preview items |
batch_set_render_layer
Preview setting GameObject layers in batch. Execute with batch_execute(confirmToken).
| Parameter | Type | Required | Default | Description |
|---|
queryJson | string | No | null | JSON query filter envelope |
layer | string | No | null | Target layer name |
recursive | bool | No | false | Apply recursively to children |
sampleLimit | int | No | DefaultSampleLimit | Max preview items |
batch_replace_material
Preview replacing materials in batch. Execute with batch_execute(confirmToken).
| Parameter | Type | Required | Default | Description |
|---|
queryJson | string | No | null | JSON query filter envelope |
materialPath | string | No | null | Replacement material asset path |
sampleLimit | int | No | DefaultSampleLimit | Max preview items |
batch_validate_scene_objects
Analyze scene objects for missing scripts, missing references, duplicate names, and empty objects.
| Parameter | Type | Required | Default | Description |
|---|
issueLimit | int | No | 100 | Max issues returned |
batch_cleanup_temp_objects
Preview deleting temporary helper objects by common temp-name patterns. Execute with batch_execute(confirmToken).
| Parameter | Type | Required | Default | Description |
|---|
queryJson | string | No | null | JSON query filter envelope |
patternsCsv | string | No | null | Comma-separated temp-name patterns |
sampleLimit | int | No | DefaultSampleLimit | Max preview items |
batch_retry_failed
Re-run only the failed items from a previous batch execution report. Returns a new jobId and originalReportId.
| Parameter | Type | Required | Default | Description |
|---|
reportId | string | Yes | — | Prior batch report ID to resume from |
runAsync | bool | No | true | Whether to run asynchronously (returns jobId) |
chunkSize | int | No | 100 | Chunk size per retry batch |
Exact Signatures
Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file.
