# Asset & file commands

Commands for creating, importing, moving, copying, renaming, deleting and finding project assets, plus folder and text-file operations. Every agent-supplied path is funnelled through the authoring-root sandbox (it rejects `../` and out-of-project writes); destructive or overwriting operations require `confirm=true` and support `dry_run`. AssetDatabase create/move/copy/rename/delete are not part of Unity's Undo system.

### `create_asset`
Create a new ScriptableObject (or other UnityEngine.Object) asset of the given type at a path under the authoring root.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `path` | yes | – | Asset path relative to the authoring root, including extension (e.g. Data/Config.asset or Materials/Wall.mat). The Assets/ prefix is optional. |
| `type` | yes | – | Fully-qualified or short type name to instantiate (e.g. UnityEngine.Material, MyGame.GameConfig). Must derive from UnityEngine.Object and be creatable. |
| `shader` | no | `–` | Material-only (ignored otherwise): shader name to assign (e.g. Standard, "Universal Render Pipeline/Lit"). When omitted, defaults to "Universal Render Pipeline/Lit" if a Scriptable Render Pipeline is active, otherwise the built-in "Standard" shader (falling back to "Standard" if URP/Lit is unavailable). |
| `confirm` | no | `false` | Required (true) only when overwriting an existing asset at the path. Ignored when the path is empty. |
| `dry_run` | no | `false` | If true, validate inputs and report what would be created without writing anything. |

**Returns:** `AuthoringResult`
**Notes:** `confirm=true` required to overwrite an existing asset; supports `dry_run`.

### `import_asset`
Import an external file (e.g. a texture, model, audio clip) into the project by copying it to a path under the authoring root, then importing it.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `source` | yes | – | Absolute filesystem path to the external file to import. |
| `path` | yes | – | Destination asset path relative to the authoring root, including extension. The Assets/ prefix is optional. |
| `confirm` | no | `false` | Required (true) only when overwriting an existing asset at the destination path. |
| `dry_run` | no | `false` | If true, validate inputs and report what would be imported without writing anything. |

**Returns:** `AuthoringResult`
**Notes:** `confirm=true` required to overwrite an existing asset; supports `dry_run`.

### `move_asset`
Move (or rename via a new path) an asset to a new location under the authoring root. Preserves the asset's GUID.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `asset` | yes | – | Reference to the asset to move (path / guid / globalId). |
| `destination` | yes | – | Destination asset path relative to the authoring root, including extension. The Assets/ prefix is optional. |
| `dry_run` | no | `false` | If true, validate the move (via AssetDatabase.ValidateMoveAsset) without performing it. |

**Returns:** `AuthoringResult`
**Notes:** Supports `dry_run`.

### `copy_asset`
Copy an asset to a new path under the authoring root. The copy gets a fresh GUID.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `asset` | yes | – | Reference to the asset to copy (path / guid / globalId). |
| `destination` | yes | – | Destination asset path relative to the authoring root, including extension. The Assets/ prefix is optional. |
| `confirm` | no | `false` | Required (true) only when overwriting an existing asset at the destination path. |
| `dry_run` | no | `false` | If true, validate inputs and report what would be copied without writing anything. |

**Returns:** `AuthoringResult`
**Notes:** `confirm=true` required to overwrite an existing asset; supports `dry_run`.

### `rename_asset`
Rename an asset in place (keeps it in the same folder, keeps its GUID).

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `asset` | yes | – | Reference to the asset to rename (path / guid / globalId). |
| `new_name` | yes | – | New file name WITHOUT a folder path. The extension is preserved if omitted. |
| `dry_run` | no | `false` | If true, validate the rename without performing it. |

**Returns:** `AuthoringResult`
**Notes:** Supports `dry_run`.

### `delete_asset`
Delete an asset from the project. Destructive: requires confirm=true.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `asset` | yes | – | Reference to the asset to delete (path / guid / globalId). |
| `confirm` | no | `false` | Must be true to actually delete. Without it the command refuses (destructive guard). |
| `dry_run` | no | `false` | If true, report the asset that would be deleted without deleting it. |

**Returns:** `AuthoringResult`
**Notes:** Destructive — `confirm=true` required; supports `dry_run`. Not undoable via Unity's Undo.

### `find_assets`
Find assets by type and/or name and/or label, returning their path, GUID and type. At least one filter is required.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `type` | no | `–` | Type name to filter by (e.g. Material, GameObject, ScriptableObject, MyGame.GameConfig). Resolved to a System.Type and matched against each asset's actual main type. |
| `name` | no | `–` | Name substring to filter by (AssetDatabase name filter). |
| `label` | no | `–` | Asset label to filter by (AssetDatabase 'l:' filter). |
| `search_in` | no | `–` | Folder to scope the search to, relative to the authoring root (default: the authoring root). |
| `limit` | no | `200` | Maximum number of results to return (default 200). |

**Returns:** `FindAssetsResult`
**Notes:** At least one of `type`, `name`, or `label` is required.

### `set_import_settings`
Set import settings on an asset's AssetImporter (e.g. a texture's isReadable) and re-import it.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `asset` | yes | – | Reference to the asset whose importer to edit (path / guid / globalId). |
| `settings` | yes | – | JSON object of importer property/field names to values, e.g. {"isReadable": true, "textureType": "NormalMap"}. |
| `dry_run` | no | `false` | If true, validate which settings would apply (and which are unknown) without writing or re-importing. |

**Returns:** `SetImportSettingsResult`
**Notes:** Supports `dry_run`. Import settings live in the asset's .meta file and are not part of Unity's Undo system.

### `get_import_settings`
Read an asset's import settings, structured by importer type (texture/model/audio), including the default-platform fields and (for textures/audio) one platform override block.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `asset` | yes | – | Reference to the asset whose importer to read (path / guid / globalId). |
| `platform` | no | `Default` | Platform whose override to read: Default \| Standalone \| iOS \| Android \| WebGL \| tvOS. |

**Returns:** `GetImportSettingsResult`

### `create_folder`
Create a folder under the authoring root (creates intermediate folders).

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `path` | yes | – | Folder path relative to the authoring root (default Assets/); the Assets/ prefix is optional. e.g. Gameplay/Enemies or Assets/Gameplay/Enemies |

**Returns:** `AuthoringResult`

### `read_text_file`
Read a UTF-8 text file under the authoring root and return its contents.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `path` | yes | – | Text file path relative to the authoring root. The Assets/ prefix is optional. |
| `max_bytes` | no | `1048576` | Reject files larger than this many bytes (default 1048576 = 1 MiB) to avoid huge payloads. |

**Returns:** `ReadTextFileResult`
**Notes:** `MainThreadRequired = true`.

### `write_text_file`
Write UTF-8 text to a file under the authoring root, then import it. Overwriting an existing file requires confirm=true.

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `path` | yes | – | Text file path relative to the authoring root, including extension. The Assets/ prefix is optional. |
| `contents` | yes | – | The full text content to write (replaces the file). |
| `confirm` | no | `false` | Required (true) only when overwriting an existing file at the path. |
| `dry_run` | no | `false` | If true, validate inputs and report what would be written without writing anything. |

**Returns:** `AuthoringResult`
**Notes:** `confirm=true` required to overwrite an existing file; supports `dry_run`. Filesystem writes are not part of Unity's Undo system.

See [Creating commands](../creating-commands.md) and [Connectivity](../connectivity.md).