home / skills / besty0728 / unity-skills / prefab

prefab skill

safe

/unity-skills/skills/prefab

This skill helps you create, instantiate, and manage Unity prefabs efficiently, using batch instantiation for multiple objects.

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

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

Files (1)

SKILL.md

3.5 KB

---
name: unity-prefab
description: "Create, instantiate, and manage prefabs. Use prefab_instantiate_batch for spawning 2+ instances."
---

# Unity Prefab Skills

> **BATCH-FIRST**: Use `prefab_instantiate_batch` when spawning 2+ prefab instances.

## Skills Overview

| Single Object | Batch Version | Use Batch When |
|---------------|---------------|----------------|
| `prefab_instantiate` | `prefab_instantiate_batch` | Spawning 2+ instances |

**No batch needed**:
- `prefab_create` - Create prefab from scene object
- `prefab_apply` - Apply instance changes to prefab
- `prefab_unpack` - Unpack prefab instance

---

## Skills

### prefab_create
Create a prefab from a scene GameObject.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `gameObjectName` | string | No* | Source object name |
| `instanceId` | int | No* | Instance ID |
| `savePath` | string | Yes | Prefab save path |

**Returns**: `{success, prefabPath, sourceObject}`

### prefab_instantiate
Instantiate a prefab into the scene.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prefabPath` | string | Yes | - | Prefab asset path |
| `name` | string | No | prefab name | Instance name |
| `x`, `y`, `z` | float | No | 0 | Position |
| `parentName` | string | No | null | Parent object |

**Returns**: `{success, name, instanceId, prefabPath, position}`

### prefab_instantiate_batch
Instantiate multiple prefabs in one call.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `items` | array | Yes | Array of instantiation configs |

**Item properties**: `prefabPath`, `name`, `x`, `y`, `z`, `rotX`, `rotY`, `rotZ`, `scaleX`, `scaleY`, `scaleZ`, `parentName`

```python
unity_skills.call_skill("prefab_instantiate_batch", items=[
    {"prefabPath": "Assets/Prefabs/Enemy.prefab", "x": 0, "z": 0, "name": "Enemy_01"},
    {"prefabPath": "Assets/Prefabs/Enemy.prefab", "x": 2, "z": 0, "name": "Enemy_02"},
    {"prefabPath": "Assets/Prefabs/Enemy.prefab", "x": 4, "z": 0, "name": "Enemy_03"}
])
```

### prefab_apply
Apply instance changes back to the prefab asset.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `gameObjectName` | string | No* | Prefab instance name |
| `instanceId` | int | No* | Instance ID |

**Returns**: `{success, gameObject, prefabPath}`

### prefab_unpack
Unpack a prefab instance (break prefab connection).

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `gameObjectName` | string | No* | - | Prefab instance name |
| `instanceId` | int | No* | - | Instance ID |
| `completely` | bool | No | false | Unpack all nested prefabs |

**Returns**: `{success, gameObject, mode}`

---

## Example: Efficient Enemy Spawning

```python
import unity_skills

# BAD: 10 API calls for 10 enemies
for i in range(10):
    unity_skills.call_skill("prefab_instantiate",
        prefabPath="Assets/Prefabs/Enemy.prefab",
        name=f"Enemy_{i}",
        x=i * 2
    )

# GOOD: 1 API call for 10 enemies
unity_skills.call_skill("prefab_instantiate_batch", items=[
    {"prefabPath": "Assets/Prefabs/Enemy.prefab", "name": f"Enemy_{i}", "x": i * 2}
    for i in range(10)
])
```

## Best Practices

1. Organize prefabs in dedicated folders
2. Use prefabs for repeated objects
3. Apply changes to update all instances
4. Unpack only when unique modifications needed
5. Use batch instantiation for level generation

Overview

This skill provides a compact set of prefab management actions for Unity: create, instantiate (single and batch), apply changes, and unpack. It focuses on efficient runtime and editor workflows and highlights a batch-first pattern when spawning two or more instances. Use these actions to manage prefab assets and scene instances from automation or tooling code.

How this skill works

The skill exposes discrete operations that act on prefab assets and scene GameObjects: prefab_create saves a scene object as a prefab asset; prefab_instantiate spawns a single instance; prefab_instantiate_batch spawns many instances in one call for performance; prefab_apply writes instance changes back to the prefab asset; prefab_unpack severs prefab links for unique edits. Each call returns a small result object with success and identifying fields.

When to use it

Create a reusable asset from a configured scene object (prefab_create).
Spawn a single object for occasional or manual placement (prefab_instantiate).
Spawn two or more objects or large groups — always use prefab_instantiate_batch for performance.
Persist iterative edits back to the prefab asset after testing (prefab_apply).
Break prefab connections when instances require unique structural changes (prefab_unpack).

Best practices

Prefer prefab_instantiate_batch whenever instantiating multiple instances to reduce API overhead and improve performance.
Organize prefabs in dedicated folders and use clear prefabPath strings to avoid path mistakes.
Make iterative changes on instances, then call prefab_apply to propagate stable updates to the asset.
Only use prefab_unpack when you need permanent, instance-specific modifications; avoid unpacking by default to retain updateability.
Include parentName and transform fields in batch items to place many objects with a single call and avoid extra scene edits.

Example use cases

Level generation: use prefab_instantiate_batch to populate terrain with many props or enemies in one API call.
Procedural waves: spawn dozens of enemies with varied positions and rotations via a single batch request.
Editor tooling: convert a placed object into a reusable prefab with prefab_create, then apply later updates with prefab_apply.
One-off customization: unpack a complex instance, perform unique edits, and keep it independent with prefab_unpack.
Automated tests: spawn controlled test scenes by instantiating prefabs programmatically, using batch calls for speed.

FAQ

When should I choose prefab_instantiate vs prefab_instantiate_batch?

Use prefab_instantiate for single or rare spawns. Use prefab_instantiate_batch whenever creating two or more instances to reduce calls and improve performance.

What does prefab_apply do and when is it safe to call?

prefab_apply writes the current instance state back to the prefab asset. Call it when you want instance changes to become the new default for all future instances; avoid calling it for temporary or test-only modifications.