ucp-assets ยท diff
v0.6.3 to v0.6.3
154 added, 27 removed. Audit A to A.
---
name: ucp-assets
description: >-
- Manage project assets with `ucp asset`
- (search/move/bulk-move/import-settings/reimport/info/inspect),
- bridge-mediated file I/O via `ucp files` (read/write/patch), and shader
- diagnostics via `ucp shader errors`. Use when the user wants to find/move
- assets, edit importer settings, reimport, or read/write project files. For
- broad multi-surface Unity automation, use the unity-control-protocol skill
- instead.
- homepage: https://github.com/mflRevan/unity-control-protocol
- compatibility: Requires the `ucp` CLI and the UCP Bridge package in the target Unity project. Unity 2021.3+.
+ Work with a Unity project's assets and files through the editor with `ucp asset`, `ucp files`,
+ `ucp material`, `ucp references`, `ucp shader`, and `ucp script`: search and inspect assets,
+ read and write ScriptableObject and material fields, move or rename assets without breaking
+ GUID references, edit importer settings instead of .meta files, find every reference to an
+ asset, and check shader and project-file health. Use when the task touches files under Assets/
+ or Packages/. For scene objects use ucp-scene-authoring; for UXML/USS use ucp-ui-toolkit.
+ compatibility: Requires the `ucp` CLI (npm `@mflrevan/ucp`) and the UCP bridge package in the target Unity project. Unity 2021.3 or newer. `references` runs natively without an editor on projects using Force Text serialization and visible meta files.
metadata:
author: mflRevan
version: '0.6.3'
+ homepage: https://unityctl.dev/skills/ucp-assets
---
- # UCP Assets & Files
+ # Assets, files, materials, references
- Focused micro-skill for the `ucp asset` command surface of the
- Unity Control Protocol (`ucp`) CLI. Always confirm the live surface with
- `ucp <cmd> --help` and see the docs at https://unityctl.dev.
+ Unity tracks assets by GUID in `.meta` files, and scenes, prefabs, and settings serialize
+ references as GUIDs. Renaming or moving through the filesystem breaks those references; moving
+ through the editor keeps them. This skill routes file work through the editor where that matters
+ and stays on the filesystem where it does not.
- ## Examples
+ ## Ground rules
+ - You usually have direct filesystem access. Edit scripts and text assets locally, then run
+ `ucp compile` (scripts) or let `ucp files write` / `ucp asset reimport` trigger the import.
+ - Use `ucp asset move` / `bulk-move` for renames and folder cleanup, never `mv`.
+ - Use `ucp asset import-settings` for FBX, texture, audio import options, never hand-edited
+ `.meta` files.
+ - Prefer `--json` and `--detail summary` in reference searches to keep payloads small.
+
+ ## Search and inspect
+
```bash
- ucp asset search -t Material --max 10
+ ucp asset search -t Material --max 20
+ ucp asset search -t Prefab -p Assets/Prefabs
ucp asset search -n '^SCN_[0-9]+$' --regex
- ucp asset move "Assets/Legacy/Enemy.prefab" "Assets/Characters/Enemy.prefab"
- ucp asset import-settings write "Assets/Textures/HUD.png" --field m_IsReadable --value true
- ucp asset reimport "Assets/Generated" --recursive
- ucp files write Assets/Scripts/EnemyAI.cs --content "..." # auto-reimports
- ucp shader errors "Assets/Shaders/Water.shader"
+ ucp asset info Assets/Materials/Crate.mat # type, guid, size, importer
+ ucp asset inspect Assets/Prefabs/Enemy.prefab # type-aware: renderers, materials, components
+ ucp asset inspect Assets/Materials/Crate.mat --max-fields 40
```
- ## When to use
+ `-t` takes Unity type names (`Texture2D`, `Material`, `Prefab`, `AudioClip`, `ScriptableObject`
+ subclasses by name). Results are capped at `--max` (default 50).
- Use to search assets, do Unity-aware moves/bulk-moves that preserve `.meta`/GUIDs, edit importer settings instead of raw `.meta`, reimport, or do sandboxed file read/write/patch.
+ ## Read and write serialized fields
- ## When NOT to use (use the omni skill instead)
+ ```bash
+ ucp asset read Assets/Config/EnemyConfig.asset
+ ucp asset read Assets/Config/EnemyConfig.asset --field maxHealth
+ ucp asset write Assets/Config/EnemyConfig.asset --field maxHealth --value 120
+ ucp asset write-batch Assets/Config/EnemyConfig.asset --values '{"maxHealth":120,"speed":3.5,"loot":{"path":"Assets/Items/Gold.asset"}}'
+ ucp asset create-so Assets/Config/BossConfig.asset --type EnemyConfig
+ ucp asset delete Assets/Config/Old.asset
+ ```
- Prefer direct workspace edits + `ucp compile` when you have filesystem access; use `ucp files` as a fallback. For material property edits use `ucp-materials`; for cross-project reference lookups use `ucp-references`.
+ Values are JSON. Object references accept `{"path": ...}`, `{"guid": ...}`, or
+ `{"instanceId": ...}`, and fail explicitly when unresolved.
- For broad, multi-surface Unity automation that spans several of these
- command groups at once, use the `unity-control-protocol` omni skill instead
- of this focused micro-skill.
+ ## Move and rename safely
+
+ ```bash
+ ucp asset move Assets/Legacy/Enemy.prefab Assets/Characters/Enemy.prefab
+ ucp asset move Assets/Legacy/Textures Assets/Art/Textures # whole folder, GUIDs kept
+ ucp asset bulk-move --moves '[{"from":"Assets/A.mat","to":"Assets/Materials/A.mat"},{"from":"Assets/B.mat","to":"Assets/Materials/B.mat"}]' --dry-run
+ ucp asset bulk-move --moves '{"Assets/A.mat":"Assets/Materials/A.mat"}' --continue-on-error
+ ucp references check Assets/Characters # any unresolved outgoing references after the move?
+ ```
+
+ Build-settings scene entries, prefab references, and material slots keep resolving because the
+ GUID never changes. `--dry-run` validates the whole batch (collisions, missing sources) first.
+
+ ## Project files
+
+ ```bash
+ ucp files read Assets/Scripts/Enemy.cs
+ ucp files write Assets/Scripts/Enemy.cs --content "..." # reimports; --compile waits for the recompile
+ ucp files write Assets/Data/table.json < table.json # content from stdin
+ ucp files patch Assets/Scripts/Enemy.cs --find "speed = 3f" --replace "speed = 5f"
+ ucp files write Assets/Tuning.txt --content "..." --no-reimport
+ ```
+
+ Paths are relative to the project root and sandboxed inside it. Writes under `Assets/` and
+ `Packages/` reimport automatically, including `.meta` files (which reimport their owning asset).
+
+ ## Importer settings
+
+ ```bash
+ ucp asset import-settings read Assets/Textures/HUD.png
+ ucp asset import-settings read Assets/Models/Enemy.fbx --field globalScale
+ ucp asset import-settings write Assets/Textures/HUD.png --field isReadable --value true
+ ucp asset import-settings write Assets/Textures/HUD.png --field textureType --value "Sprite"
+ ucp asset import-settings write-batch Assets/Textures/HUD.png --values '{"isReadable":true,"maxTextureSize":2048}' --no-reimport
+ ucp asset reimport Assets/Textures/HUD.png
+ ucp asset reimport Assets/Generated --recursive
+ ```
+
+ Field names are the importer's serialized or public names as shown by `import-settings read`.
+ Batch several writes with `--no-reimport`, then reimport once.
+
+ ## Materials
+
+ ```bash
+ ucp material create Assets/Materials/Crate.mat --shader "Universal Render Pipeline/Lit"
+ ucp material get-properties --path Assets/Materials/Crate.mat
+ ucp material get-property --path Assets/Materials/Crate.mat --property _BaseColor
+ ucp material set-property --path Assets/Materials/Crate.mat --property _BaseColor --value [0.8,0.3,0.1,1]
+ ucp material set-property --path Assets/Materials/Crate.mat --property _Metallic --value 0.4
+ ucp material set-property --path Assets/Materials/Crate.mat --property _BaseMap --value '{"path":"Assets/Textures/Crate.png"}'
+ ucp material keywords --path Assets/Materials/Crate.mat
+ ucp material set-keyword --path Assets/Materials/Crate.mat --keyword _EMISSION --enabled true
+ ucp material set-shader --path Assets/Materials/Crate.mat --shader Standard
+ ucp shader errors --errors-only # shader compile problems the editor knows about
+ ```
+
+ Property names are the shader's (`_BaseColor` in URP, `_Color` in Built-in). `get-properties`
+ lists what the current shader exposes.
+
+ ## References
+
+ ```bash
+ ucp references check # can this project be indexed natively? (Force Text + visible meta)
+ ucp references find --asset Assets/Materials/Crate.mat --detail summary
+ ucp references find --asset 933532a4fcc9baf4fa0491de14d08ed7 --json
+ ucp references find --asset Assets/Prefabs/Enemy.prefab --object 3cb6...:11400000
+ ucp references find-strings --pattern "SCN_Menu" # string ids Unity will not migrate
+ ucp references find-strings --pattern 'Level_[0-9]+' --regex -p Assets/Scenes
+ ucp references index build && ucp references index status
+ ucp references find --asset Assets/Materials/Crate.mat --approach bridge # force the in-editor path
+ ```
+
+ Native search reads Unity's YAML from disk in parallel and needs no running editor; `--detail
+ summary` collapses repetitive hits (200 renderers using one material become one line).
+
+ ## Scripts and project files
+
+ ```bash
+ ucp script doctor # stale .csproj / project files?
+ ucp script doctor --fix # delete stale generated files and regenerate
+ ucp compile # after local script edits
+ ```
+
+ ## Workflows
+
+ Retexture a prop end to end:
+
+ ```bash
+ ucp asset search -n crate -t Texture2D
+ ucp asset import-settings write Assets/Textures/Crate.png --field textureType --value "Default"
+ ucp material create Assets/Materials/Crate.mat --shader "Universal Render Pipeline/Lit"
+ ucp material set-property --path Assets/Materials/Crate.mat --property _BaseMap --value '{"path":"Assets/Textures/Crate.png"}'
+ ucp object set-property --id 46894 --component MeshRenderer --property m_Materials --value '[{"path":"Assets/Materials/Crate.mat"}]' --save
+ ```
+
+ Reorganize a folder without breaking anything:
+
+ ```bash
+ ucp references find --asset Assets/Legacy/Enemy.prefab --detail summary # who uses it
+ ucp asset bulk-move --moves '{"Assets/Legacy":"Assets/Characters/Legacy"}' --dry-run
+ ucp asset bulk-move --moves '{"Assets/Legacy":"Assets/Characters/Legacy"}'
+ ucp references check Assets/Characters # nothing unresolved
+ ```
+
+ ## Pitfalls
+
+ - `asset delete` and `asset move` are real Unity operations: they update the asset database and
+ can trigger reimports and recompiles. Expect the `[editor]` line to show `importing assets` or
+ `compiling` afterwards; the next command waits for it.
+ - Writing a `.cs` file starts a compile. Run `ucp compile` to get the `CS####` diagnostics
+ instead of discovering them three commands later.
+ - `references find` on a project that is not Force Text falls back to the editor bridge, which is
+ slower and requires the editor to be open.