/component

name: unity-component
description: Manage GameObject components

Unity Component Skills

Add, remove, copy, toggle and edit components. 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

• Attaching or removing components
• Copying components between objects
• Toggling components
• Reading/writing serialized fields

Rules

• **Targets**: single-object skills and batch items take `entityId`, `name`, `instanceId` or `path`, matched like GameObjects: an id that names nothing is `TARGET_NOT_FOUND`, never a fallback; an ambiguous fuzzy name returns `TARGET_NOT_FOUND` with `candidates`; non-exact matches are listed in `resolutionNotes`. `component_copy*` use `source*` / `target*` identifiers (`sourceEntityId`, `targetEntityId`, ...).
• **`componentType`** (required): the class name — `Rigidbody`, `BoxCollider`, `Namespace.ClassName` for custom scripts. Unity, UI, TextMeshPro, Cinemachine and Input System namespaces are searched first, then a case-insensitive scan that takes the first matching type; the response's `component` / `fullTypeName` show what was resolved.
• **Two naming schemes**: `component_set_property` / `component_get_properties` use C# member names (`mass`, `isKinematic`; matched case-insensitively, private fields writable too). `component_get_serialized_properties` / `component_set_serialized_property` use SerializedProperty paths (`m_Mass`, `items.Array.data[0]`; a bare `mass` is retried as `m_Mass`). To convert, drop `m_` and lowercase the first letter; an `m_` name sent to `component_set_property` fails with "Property/field not found" and lists the writable members.
• **Value source** (`component_set_property`, its batch, `batch_preview_set_property`): exactly one of `assetPath` (project asset) > `referencePath` (scene object by path) / `referenceName` (by name, first match) > `value`, checked in that order; a lower one sent alongside is silently ignored. Sending none writes the type's default (0 / false / null).
• **`value` encoding**: numbers and bools (`true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off`; others rejected) as JSON or strings; enums by member name, case-insensitive; vectors, Quaternion (3 values = euler, 4 = xyzw), Rect (`x,y,w,h`) and Bounds (`cx,cy,cz,sx,sy,sz`) as comma strings (`"1,2,3"`); colours as `"r,g,b[,a]"` (0–1), `#RRGGBB[AA]` or a name (red, green, blue, white, black, yellow, cyan, magenta, gray/grey, clear); LayerMask as a layer name or an integer mask. The JSON object form (`{"x":1,"y":2,"z":3}`, `{"r":1,"g":0,"b":0}`) works only for Vector2/3/4 and Color/Color32, with every component required (colour `a` defaults to 1; an explicit `null` counts as missing); partial objects, unknown keys and non-numbers are rejected naming the expected keys.
• **Read-back**: `component_set_property` returns `valueSet` read from the component after the write, plus `valueRequested` only when the setter clamped or normalised it; `component_set_serialized_property` re-reads after applying. No follow-up read needed.
• **Property/add/remove batches**: all-or-nothing — one failed item reverts the whole call (`rolledBack:true`, other items `reverted:true`); unknown item keys are named in `warnings`.

Skills Overview

Invocation batches are non-atomic async jobs; details: [method calls](reference/component_invoke_method.md).

| Single | Batch | |---|---| | `component_add` | `component_add_batch` | | `component_get_methods` | `component_get_methods_batch` | | `component_invoke_method` | `component_invoke_method_batch` | | `component_remove` | `component_remove_batch` | | `component_set_property` | `component_set_property_batch` | | `component_set_serialized_property` | `component_set_serialized_property_batch` |

No batch: `component_list` (types and enabled state), `component_get_properties` (C# members and values), `component_get_serialized_properties` (Inspector paths), `component_copy`, `component_copy_exact` (verifies every serialized field), `component_set_enabled` (Behaviour/Renderer/Collider on or off — not `component_set_property`).

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

**DO NOT** (common hallucinations):

• `component_create` / `component_get` do not exist → use `component_add` (add) and `component_get_properties` (read)
• `component_find` does not exist → use `component_list` to list components on an object

Common Errors

| Error | Trigger → fix | |---|---| | `TARGET_NOT_FOUND` | Object, component type, component on the object, member or asset missing → `component_list`, `component_get_properties`, `asset_find`, `gameobject_find`. | | `MISSING_PARAM` | e.g. `componentType`, `propertyName`, `propertyPath` → supply it; the error (or a dryRun) lists all parameters. | | `SEMANTIC_INVALID` | A `value` the target type rejects, `componentIndex` out of range, a component another one still requires (`requiredBy`: remove those first), or a failed batch item → fix per the message / `results`. | | `SKILL_ERROR` | Read-only property → pick a writable member. |

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