/gameobject

name: unity-gameobject
description: Create and manipulate GameObjects

Unity GameObject Skills

Create, find, parent and transform scene objects. Parameters come from the schema (recommend `includeSchema=true` or `/skills/schema?names=`), which notes the non-obvious ones — never from a skill's name. Execution, dryRun and verification rules: root [SKILL.md](../../SKILL.md).

When to use

• Building or restructuring scene hierarchy
• Spawning or removing objects
• Adjusting transforms

Rules

• **Identifiers**: `entityId` (string, any Unity; the only id on 6000.4+, where `instanceId` reads `0`), `instanceId` (int, older Unity), `path` (`"Parent/Child"`, case-insensitive, optional scene-name prefix), `name`. Give at least one; precedence `entityId > instanceId > path > name`. An id that names nothing is `TARGET_NOT_FOUND` (it may be stale), never a fallback; a missed path falls back to `name`.
• **Name matching**: an exact name wins (the top-most in the Hierarchy when several share it, inactive too; Prefab Mode only by id); otherwise a single whole-word or substring match is used. Several fuzzy matches return `TARGET_NOT_FOUND` with `candidates` (`path` + `entityId` each) instead of guessing. Non-exact resolutions are listed in top-level `resolutionNotes`.
• **Spaces**: `gameobject_create` `x/y/z` and `rotX/Y/Z` are local to the parent unless `space:"world"` (applied after parenting). `gameobject_set_transform` `posX/Y/Z` and `rotX/Y/Z` are world, `localPosX/Y/Z` local; it applies world position, then local position, then rotation, then scale, so local wins on a shared axis and omitted axes keep their value. `scaleX/Y/Z` is always `localScale`. RectTransform fields (`anchor*`, `pivot*`, `sizeDelta*`, `width`/`height`) are UI-only.
• **Read-back**: create, set_transform and their batches return the Transform read back — `position` (world), `localPosition`, `rotation` (world euler, 0–360), `scale` (local), as `gameobject_get_info` reports them; no follow-up read needed.
• **Batches** (`items` = JSON array): all-or-nothing. One failed item reverts the whole call (`rolledBack:true`, the other items `reverted:true`, error `SEMANTIC_INVALID`); fix the failed items and resend all. Unknown item keys are ignored and named in `warnings`. Items take the single skill's identifiers and fields; `gameobject_create_batch` items may parent to an item created earlier in the same call.

Skills Overview

Use `*_batch` for 2+ objects (one call instead of N).

| Single | Batch | |---|---| | `gameobject_create` | `gameobject_create_batch` | | `gameobject_delete` | `gameobject_delete_batch` | | `gameobject_duplicate` (sibling `<name>_Copy`) | `gameobject_duplicate_batch` | | `gameobject_rename` | `gameobject_rename_batch` | | `gameobject_set_transform` | `gameobject_set_transform_batch` | | `gameobject_set_active` | `gameobject_set_active_batch` | | `gameobject_set_parent` (no parent id = unparent) | `gameobject_set_parent_batch` | | - | `gameobject_set_layer_batch` | | - | `gameobject_set_tag_batch` | | `gameobject_set_sibling_index` (index clamped) | - |

Query (no batch): `gameobject_find` (name substring or regex, tag, layer, component; at most `limit` (50) objects, `truncated:true` + `totalMatched` report a cut), `gameobject_get_info` (transform, parent, children, components).

Per-skill tables, item fields and return shapes: `reference/<skill_name>.md` — rarely needed, the schema notes the parameters.

**DO NOT** (common hallucinations):

• `gameobject_move` / `gameobject_rotate` / `gameobject_set_scale` / `gameobject_set_position` do not exist → use `gameobject_set_transform`
• `gameobject_add_component` does not exist → use `component_add`
• `gameobject_get_transform` does not exist → use `gameobject_get_info`

**Elsewhere**: components → `component_*` skills; material or colour → `material_*` skills; `scene_find_objects` (SemiAuto) also searches objects.

Common Errors

| Error | Fix | |---|---| | `TARGET_NOT_FOUND` (object, parent, child, layer) | Retry with a `candidates` entry's `path` / `entityId`, or locate it via `gameobject_find` / `scene_get_hierarchy`. | | `MISSING_PARAM` | Supply it (e.g. `newName`, `items`); the error (or a dryRun) lists all parameters. | | `SEMANTIC_INVALID` | Use an allowed value from the message (`primitiveType`, `space` local/world, a registered tag) or fix the failed `results` items. |

Transport codes (`COMPILING`, `RATE_LIMIT`, ...) → [error codes](../../references/protocol-error-codes.md).