diff --git a/docs/AGENT_INTEGRATION.md b/docs/AGENT_INTEGRATION.md index 4bac677..2e8269c 100644 --- a/docs/AGENT_INTEGRATION.md +++ b/docs/AGENT_INTEGRATION.md @@ -7,6 +7,8 @@ generated programming workspace still belong to the game project. ## Topics +- [Organize the scene explorer](/docs/guides/ai-agents/organize-scene-explorer) + - [Author scenes, models and playtests](/docs/guides/ai-agents/author-scenes-models-and-playtest) - [Connect an agent](/docs/guides/ai-agents/connect-an-agent) diff --git a/docs/AGENT_INTEGRATION/author-scenes-models-and-playtest.md b/docs/AGENT_INTEGRATION/author-scenes-models-and-playtest.md index af6f1c1..5ab29b8 100644 --- a/docs/AGENT_INTEGRATION/author-scenes-models-and-playtest.md +++ b/docs/AGENT_INTEGRATION/author-scenes-models-and-playtest.md @@ -51,7 +51,7 @@ Stop play and resolve any runtime-change review before editing or switching. Call `editor_status` again after switching to get that scene's object IDs. `scene_summary` reads the saved file; `editor_status` reads the live document. -`object_create` accepts `name` and `kind`: `empty`, `camera`, `light`, or `blockout`. +`object_create` accepts `name` and `kind`: `folder`, `empty`, `camera`, `light`, or `blockout`, with optional `parent`. Use its returned `entity_id` with `object_update`, for example: ```json @@ -75,6 +75,15 @@ whole component value. Read their exact JSON structure from `editor_status`. A null camera/light removes it. Invalid batches fail without partial object edits. `editor_undo` and `editor_redo` handle object edits. Save with `scene_save`. +## Organize folders and object subtrees + +Read `scene_explorer_guide` for the bundled hierarchy organization skill. +`object_create` with `kind:"folder"` creates actual scene explorer folders; +`object_duplicate` copies an object/folder and all descendants with fresh IDs; +`object_delete` removes the selected subtree with undo. Use `object_update` to +rename or reparent. See [Organize the scene explorer](/docs/guides/ai-agents/organize-scene-explorer) +for copyable examples, parent/transform behavior, recursive deletion and saving. + ## Model, preview, then place Agents should prefer Blender when installed, exporting a supported model such as diff --git a/docs/AGENT_INTEGRATION/organize-scene-explorer.md b/docs/AGENT_INTEGRATION/organize-scene-explorer.md new file mode 100644 index 0000000..7756a16 --- /dev/null +++ b/docs/AGENT_INTEGRATION/organize-scene-explorer.md @@ -0,0 +1,128 @@ +# Organize the scene explorer with AI + +[Back to AI agents & app data](/docs/guides/ai-agents). + +The bundled `rustic-scene-explorer` skill teaches agents how to organize the +scene explorer (Hierarchy panel), create folders and add, duplicate or delete +objects. These operations work directly through the plugin and the editor's undo +system. They do not require clicking the explorer through computer use. + +## Setup and inspect + +Open the game in the writable Rustic editor, reload the updated `rustic-workspace` +MCP connection and select the game with `workspace_info`. Call +`scene_explorer_guide` with `{}` to read the current skill, including on upgrades +that preserve customized agent instructions. The skill is also installed in +Rustic app data for Codex, Claude and the Codex plugin. Existing customized skill +files are preserved. + +Call `editor_status` with `{}` before changing the hierarchy. Each object has an +`entity_id`, `name`, `parent` (an object UUID or null) and `folder` flag. Use these +UUIDs to distinguish similarly named objects. `scene_summary` also reports folder +flags for saved files; use live status for unsaved edits. + +A scene folder is an organizational entity in the active scene, not a directory +on disk. File tools cannot create explorer folders by making asset directories. +This guide concerns scene hierarchy layout; editor dock/tab placement is a +separate preference. + +## Lay out useful groups + +Use a small, shallow structure that matches the game. For example, World might +contain Buildings and Vegetation, while Gameplay holds actors, triggers and spawn +points, with Lighting and UI as other top-level groups. Reuse existing naming +conventions and avoid creating empty groups without a purpose. + +Folders do not contribute translation, rotation or scale to their descendants. +Changing a folder's transform does not move its contents. Use an ordinary empty +root object for an assembly that should move as a group. + +Reparenting retains the child's **local** transform. Changing its non-folder +ancestors can change world placement: a folder adds no transform of its own, but +still inherits from any ordinary object above it. Inspect the ancestor chain and +calculate the intended local transform when needed. Folder membership does not +change script lifetime or make its children global. + +## Create folders and objects + +Pass the following to `object_create`: + +```json +{"name":"World","kind":"folder"} +``` + +The returned `entity_id` is the new folder UUID. Create a nested folder with that +UUID as `parent`: + +```json +{"name":"Buildings","kind":"folder","parent":""} +``` + +The supported kinds are `folder`, `empty`, `camera`, `light` and `blockout`. +Omit `parent` or pass null to create at scene root. Use `model_create` for finished +visible mesh assets, then parent the returned model object with `object_update`: + +```json +{"entity_id":"","properties":{"parent":""}} +``` + +Rename a folder or object through `object_update` with `properties.name`. +Use `properties.parent:null` to move it back to scene root. Missing parents, +invalid IDs and cycles are rejected without partially changing the hierarchy. + +## Duplicate an object or a folder subtree + +Call `object_duplicate`, for example: + +```json +{"entity_id":"","name":"Buildings copy"} +``` + +The entire subtree is copied with fresh object UUIDs and preserved internal +parent links, folder flags, local transforms and components. The source is +unchanged. By default the new root is a sibling under the original parent. +Supply `parent` to choose another destination, or `parent:null` for scene root. +`name` optionally renames only the copied root. + +The response contains the copied root `entity_id`, all new `entity_ids`, the +`source_entity_id` and `saved:false`. Use the **new** IDs to edit the copy. The copy +initially overlaps the original when using the same parent and transforms; move +it through `object_update` if that is not intended. A different parent can change +world placement because local transforms are retained. + +Mesh/material asset IDs and script source IDs stay shared. Script attachments +and their properties are copied, but arbitrary entity references inside script +properties are not automatically rewritten to the new objects. Inspect those +references when making the copy independent. + +## Delete and recover + +Inspect the target's descendants using `editor_status`, then call +`object_delete`: + +```json +{"entity_id":""} +``` + +Deleting a folder or object removes **every descendant**, as one undoable edit. +To keep children, move them to a surviving parent first. The response lists +`deleted_entity_ids` and `saved:false`. Asset files, script source files, global +scripts and scene startup lists are not deleted. + +`editor_undo` restores the deleted subtree with its IDs and parent links; +`editor_redo` deletes it again. Creation, duplication and reparenting also support +scene undo/redo. A duplicate operation is one undo step, including its optional +root name and parent. + +## Verify and save + +Re-read `editor_status` after changes to verify folder flags, parents and copied +IDs. Inspect the scene with `viewport_capture` to catch unintended placement +changes. Call `scene_save` to persist the hierarchy; these tools initially edit +the unsaved active scene. Refresh IDs after switching scenes. + +Stop play and resolve pending runtime-change review before editing. Read-only +editors cannot mutate the scene. If a tool is missing, update/reopen Rustic and +reload its MCP connection. If an operation fails, inspect status and correct the +ID or parent; do not modify a stale saved scene behind unsaved editor work or +claim a hierarchy change succeeded. diff --git a/lib/docs-catalog.ts b/lib/docs-catalog.ts index 7777b90..2143dfc 100644 --- a/lib/docs-catalog.ts +++ b/lib/docs-catalog.ts @@ -107,6 +107,7 @@ const categoryGroups: DocGroup[] = [ { slug: "guides/ai-agents/connect-an-agent", title: "Connect an agent", description: "Connect an agent for AI agents & app data.", source: "docs/AGENT_INTEGRATION/connect-an-agent.md", parent: "guides/ai-agents" }, { slug: "guides/ai-agents/read-and-edit-agent-information", title: "Read and edit agent information", description: "Read and edit agent information for AI agents & app data.", source: "docs/AGENT_INTEGRATION/read-and-edit-agent-information.md", parent: "guides/ai-agents" }, { slug: "guides/ai-agents/storage-and-migration", title: "Storage and migration", description: "Storage and migration for AI agents & app data.", source: "docs/AGENT_INTEGRATION/storage-and-migration.md", parent: "guides/ai-agents" }, + { slug: "guides/ai-agents/organize-scene-explorer", title: "Organize the scene explorer", description: "Use AI tools to create folders, organize hierarchy parents and duplicate or delete object subtrees with undo.", source: "docs/AGENT_INTEGRATION/organize-scene-explorer.md", parent: "guides/ai-agents" }, { slug: "guides/ai-agents/author-scenes-models-and-playtest", title: "Author scenes, models and playtests", description: "Use direct editor tools for modeling, scene authoring, script scopes and keyboard playtesting.", source: "docs/AGENT_INTEGRATION/author-scenes-models-and-playtest.md", parent: "guides/ai-agents" }, { slug: "guides/ai-agents/limits-and-troubleshooting", title: "Limits and troubleshooting", description: "Limits and troubleshooting for AI agents & app data.", source: "docs/AGENT_INTEGRATION/limits-and-troubleshooting.md", parent: "guides/ai-agents" }, { slug: "guides/gameplay-programming", title: "Gameplay programming", description: "Choose a focused guide to gameplay programming.", source: "docs/GAMEPLAY_PROGRAMMING.md" },