playbooks

home / skills / besty0728 / unity-skills / component

component skill

/unity-skills/skills/component

This skill helps you manage Unity GameObject components efficiently by adding, removing, and tuning properties, including batch operations for multiple objects.

npx playbooks add skill besty0728/unity-skills --skill component

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
6.0 KB
---
name: unity-component
description: "Add, remove, and configure components on GameObjects. Use *_batch skills for 2+ objects."
---

# Unity Component Skills

> **BATCH-FIRST**: Use `*_batch` skills when operating on 2+ objects to reduce API calls from N to 1.

## Skills Overview

| Single Object | Batch Version | Use Batch When |
|---------------|---------------|----------------|
| `component_add` | `component_add_batch` | Adding to 2+ objects |
| `component_remove` | `component_remove_batch` | Removing from 2+ objects |
| `component_set_property` | `component_set_property_batch` | Setting on 2+ objects |

**Query Skills** (no batch needed):
- `component_list` - List all components on an object
- `component_get_properties` - Get component property values

---

## Single-Object Skills

### component_add
Add a component to a GameObject.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No* | GameObject name |
| `instanceId` | int | No* | Instance ID (preferred) |
| `path` | string | No* | Hierarchy path |
| `componentType` | string | Yes | Component type name |

*At least one identifier required

**Returns**: `{success, gameObject, componentType, added}`

### component_remove
Remove a component from a GameObject.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No* | GameObject name |
| `instanceId` | int | No* | Instance ID |
| `componentType` | string | Yes | Component type to remove |

**Returns**: `{success, gameObject, componentType, removed}`

### component_list
List all components on a GameObject.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No* | GameObject name |
| `instanceId` | int | No* | Instance ID |

**Returns**: `{success, gameObject, instanceId, components: [string]}`

### component_set_property
Set a component property value.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No* | GameObject name |
| `instanceId` | int | No* | Instance ID |
| `componentType` | string | Yes | Component type |
| `propertyName` | string | Yes | Property to set |
| `value` | any | Yes | New value |

**Returns**: `{success, gameObject, componentType, property, oldValue, newValue}`

### component_get_properties
Get all properties of a component.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No* | GameObject name |
| `instanceId` | int | No* | Instance ID |
| `componentType` | string | Yes | Component type |

**Returns**: `{success, gameObject, componentType, properties: {name: value}}`

---

## Batch Skills

### component_add_batch
Add components to multiple objects.

```python
unity_skills.call_skill("component_add_batch", items=[
    {"name": "Enemy1", "componentType": "Rigidbody"},
    {"name": "Enemy2", "componentType": "Rigidbody"},
    {"name": "Enemy3", "componentType": "Rigidbody"}
])
```

### component_remove_batch
Remove components from multiple objects.

```python
unity_skills.call_skill("component_remove_batch", items=[
    {"instanceId": 12345, "componentType": "BoxCollider"},
    {"instanceId": 12346, "componentType": "BoxCollider"}
])
```

### component_set_property_batch
Set properties on multiple objects.

```python
unity_skills.call_skill("component_set_property_batch", items=[
    {"name": "Enemy1", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0},
    {"name": "Enemy2", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0}
])
```

---

## Common Component Types

### Physics
| Type | Description |
|------|-------------|
| `Rigidbody` | Physics simulation |
| `BoxCollider` | Box collision |
| `SphereCollider` | Sphere collision |
| `CapsuleCollider` | Capsule collision |
| `MeshCollider` | Mesh-based collision |
| `CharacterController` | Character movement |

### Rendering
| Type | Description |
|------|-------------|
| `MeshRenderer` | Render meshes |
| `SkinnedMeshRenderer` | Animated meshes |
| `SpriteRenderer` | 2D sprites |
| `LineRenderer` | Draw lines |
| `TrailRenderer` | Motion trails |

### Audio
| Type | Description |
|------|-------------|
| `AudioSource` | Play sounds |
| `AudioListener` | Receive audio |

### UI
| Type | Description |
|------|-------------|
| `Canvas` | UI container |
| `Image` | UI images |
| `Text` | UI text (legacy) |
| `Button` | Clickable button |

---

## Example: Efficient Physics Setup

```python
import unity_skills

# BAD: 6 API calls
unity_skills.call_skill("component_add", name="Box1", componentType="Rigidbody")
unity_skills.call_skill("component_add", name="Box2", componentType="Rigidbody")
unity_skills.call_skill("component_add", name="Box3", componentType="Rigidbody")
unity_skills.call_skill("component_set_property", name="Box1", componentType="Rigidbody", propertyName="mass", value=2.0)
unity_skills.call_skill("component_set_property", name="Box2", componentType="Rigidbody", propertyName="mass", value=2.0)
unity_skills.call_skill("component_set_property", name="Box3", componentType="Rigidbody", propertyName="mass", value=2.0)

# GOOD: 2 API calls
unity_skills.call_skill("component_add_batch", items=[
    {"name": "Box1", "componentType": "Rigidbody"},
    {"name": "Box2", "componentType": "Rigidbody"},
    {"name": "Box3", "componentType": "Rigidbody"}
])
unity_skills.call_skill("component_set_property_batch", items=[
    {"name": "Box1", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0},
    {"name": "Box2", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0},
    {"name": "Box3", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0}
])
```

## Best Practices

1. Add colliders before Rigidbody for physics
2. Use `component_list` to verify additions
3. Check property names with `component_get_properties` first
4. Some properties are read-only (will fail to set)
5. Use full type names for custom scripts (e.g., "MyNamespace.MyScript")

Overview

This skill lets you add, remove, and configure Unity components on GameObjects from an automation context. It supports single-object operations and batch variants for performing the same change across many objects in one call. Use query helpers to list components and read component properties before changing them.

How this skill works

Provide a GameObject identifier (instanceId, name, or hierarchy path) and the component type to add, remove, or modify. Batch variants accept an items array so multiple objects are updated with a single API call, drastically reducing round trips. Query skills return current components or full property dictionaries so you can validate or discover property names before setting values.

When to use it

  • Add components to a single GameObject during scene setup or runtime tweaks
  • Remove unwanted or duplicate components from objects
  • Change component properties across many GameObjects in a single operation
  • Inspect a GameObject to see what components and properties it currently has
  • Apply the same configuration (e.g., mass) to a group of physics objects

Best practices

  • Use batch skills (component_add_batch, component_remove_batch, component_set_property_batch) whenever you operate on 2+ objects to reduce API calls
  • Call component_list or component_get_properties first to confirm target components and valid property names
  • Add colliders before adding a Rigidbody to ensure physics behave correctly
  • Use full type names (including namespace) for custom MonoBehaviour scripts
  • Be aware some properties are read-only and will fail to set; handle returned success flags

Example use cases

  • Add Rigidbody to every enemy in a wave using component_add_batch, then set mass via component_set_property_batch
  • Remove legacy BoxCollider from multiple prefabs with component_remove_batch
  • Query a selected GameObject with component_list to enumerate attached components before refactoring
  • Inspect and dump all properties of a custom script with component_get_properties for debugging
  • Set UI component fields (e.g., Image, Button) across a menu using batch property updates

FAQ

What identifiers can I use to target a GameObject?

You can identify a GameObject by instanceId, name, or hierarchy path; at least one identifier is required.

When should I use batch vs single skills?

Use batch skills anytime you need to change 2 or more objects to minimize API calls and improve performance.

How do I know valid property names before setting them?

Call component_get_properties to retrieve the component’s current properties and names before using component_set_property or its batch variant.