Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions content/editor/explorer.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,19 @@ Expected result: an imported model appears as a scene object. A recognised exten

## Files and scripts

The project separates assets, scenes, scripts, `ui/` Web assets, and configuration. **Programming → Object Component Script** creates and registers a script for the selected object; global and scene startup scopes also exist. Existing registered scripts can be attached through **Programming → Attach Existing Script** or Inspector. Double-clicking a script opens the external editor; right-click offers attachment scopes. See [the scripting guides](/docs/scripting/lua) for each language's setup, including Luau registration and optional external runtimes.
The project separates assets, scenes, scripts, `ui/` Web assets, and configuration. **Programming → Object Component Script** creates and registers a script for the selected object; global and scene startup scopes also exist. Existing registered scripts can be attached through **Programming → Attach Existing Script** or Inspector. Double-clicking a script opens the external editor. Right-click (or two-finger click on a trackpad) offers **Set As → Global Startup Script**, **Scene Startup Script**, or **Object Component Script**. Select the target scene object first to enable Object Component Script. See [the scripting guides](/docs/scripting/lua) for each language's setup, including Luau registration and optional external runtimes.

## Move or rename assets carefully
## Rename, move, copy, cut and delete

Explorer supports dragging a file/directory to another project directory, including the root. The move rejects unsafe paths, missing destinations, name collisions and moving a directory into itself. **The current move performs a filesystem rename only:** it does not migrate manifest paths, scene references, companion files or sidecar metadata. Back up first and update affected references before Play.
Hovering over a row does not start a move. Press and hold the primary mouse button on the item name, then drag to another project folder or the root. A folder's arrow expands or collapses it; dragging its name moves only that folder, and dragging a child moves the child.

There is no verified inline asset-rename control. Rename using the file manager only when you can also maintain those references. Preserve `.rmeta` alongside its source. Do not hand-edit scene attachments to contain script paths instead of registered IDs.
Click a file or folder name once to edit it inline. The field appears after the short double-click window so double-click can still open a file. Press **Enter** or click elsewhere to save; **Escape** cancels. Use a single filename, including its extension. Empty names, path separators and existing names are rejected; Console explains the failure.

Right-click an item, or use a two-finger trackpad click, for **Copy**, **Cut**, **Paste** and **Delete**. Copy/Cut stores an item in the editor clipboard; Paste on a folder uses that folder, and Paste on a file uses its containing folder. Right-click empty tree space for **Paste at Project Root**. Copies get a numbered name when needed. Cut leaves the source in place until a successful Paste. Delete moves the entry into `.rustic/trash/<identifier>/`; recover it with your operating system's file manager. Scene Undo does not undo filesystem actions.

These controls require a writable project and stopped Play. Moves and renames keep a file's `.rmeta` sidecar alongside it. Copies omit `.rmeta` so a new asset identity can be assigned on import or script registration. **Manifest paths, scene references and companion-file links are not rewritten.** Update affected references before Play; copied scripts must be registered using the script scope commands. A folder copy does not rewrite references within its files. Operations reject traversal, symbolic links, missing destinations, move collisions and moving/copying a folder into itself.

World/Local space applies to scene transforms: switch to **Project → Scene**, right-click the object and choose **Use World Space** or **Use Local Space**. This changes the active transform gizmo axes without changing the object's transform.

## Known limitations and diagnosis

Expand Down
8 changes: 5 additions & 3 deletions content/editor/scene-hierarchy.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ Prerequisites: open a writable project, stop Play, and switch the **Project** pa
1. Choose **+ Add → Folder** to create an organisational folder. Select the folder before adding children.
2. Choose **+ Add** and a primitive, **Camera** or **Light**. New items are parented to the selected folder, if one is selected.
3. Click the object's tree row. Inspector shows its name, persistent entity identifier and available components.
4. Edit the name field at the top of Inspector. Use descriptive names; scene lookup examples depend on the names and hierarchy you choose.
5. Drag a tree item onto a folder to reparent it, or onto the root drop zone to move it to the scene root. Invalid parenting, including cycles, is rejected; inspect Console for errors.
4. Click the object name to edit it inline, then press **Enter** or click elsewhere to save (**Escape** cancels). You can also edit the name field at the top of Inspector. Use descriptive names; scene lookup examples depend on the names and hierarchy you choose.
5. Press and hold on an item name, then drag it onto a folder to reparent it, or onto the root drop zone to move it to the scene root. Invalid parenting, including cycles, is rejected; inspect Console for errors.
6. Choose **File → Save scene**.

Expected result: the tree reflects the new name and hierarchy, Inspector tracks selection, and the saved scene retains the edits. Use **Edit → Undo** to revert an accidental authoring edit.
Expand All @@ -19,6 +19,8 @@ An entity combines a transform with the components appropriate to its role: prim

## Known limitations

The current scene tree has no verified Delete command or Delete-key handler. Do not assume another engine's deletion shortcut works here. Removal APIs in the world model are not evidence of an editor control. Creating a folder does not create a filesystem directory, and moving a scene object does not move its source asset.
Right-click an object (or two-finger click on a trackpad) for **Copy**, **Cut**, **Paste**, **Delete**, **Use World Space** and **Use Local Space**. Copy captures the object and its descendants; Paste gives them fresh entity IDs and preserves their internal parent links. Paste on an object makes the pasted root its child; right-click empty tree space for **Paste at Scene Root**. Cut moves the original tree only after a successful Paste. Delete removes the object and its descendants. Rename, Paste, Cut/Paste and Delete support **Edit → Undo/Redo** and are disabled during Play or read-only access.

World/Local space changes the active gizmo's axes without modifying the stored transform. Copied scripts and other components keep their existing asset references; embedded entity IDs in arbitrary component data are not rewritten. There is no Delete-key shortcut. Creating a folder does not create a filesystem directory, and moving a scene object does not move its source asset.

Related: [Inspector](/docs/guides/editor/inspector), [scene lookup API](/docs/api/scene), [scene object scripting](/docs/guides/scene-objects).
2 changes: 1 addition & 1 deletion content/user/scripting.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Rustic supports C, C++, C#, Python, JavaScript, Lua 5.4, Luau, Java, PHP and HTM

The editor scans recognized project source extensions and registers stable asset identities. Registered moves/renames preserve attachments. It maintains `config/scripts.ron`; users should not edit that registry or hand-write component JSON. Scripts under `scripts/` include `.lua`, `.luau`, `.js`, `.py`, `.c`, `.cpp`, `.cs`, `.java`; PHP/Web assets belong under `ui/`. Discovery does not guarantee an external compiler/interpreter is installed.

**Luau caveat:** `.luau` discovery, SDK and host are implemented, but the inspected script-creation menu omits Luau. Create a `.luau` file under `scripts/` in an external editor and select a target object, then right-click the file in Explorer and choose **Use Script As > Object Script** to register and attach it. Check Console discovery errors. The menu limitation does not make Luau interchangeable with Lua 5.4.
**Luau caveat:** `.luau` discovery, SDK and host are implemented, but the inspected script-creation menu omits Luau. Create a `.luau` file under `scripts/` in an external editor and select a target object, then right-click the file in Explorer and choose **Set As > Object Component Script** to register and attach it. Check Console discovery errors. The menu limitation does not make Luau interchangeable with Lua 5.4.

## Scope and execution order

Expand Down
2 changes: 1 addition & 1 deletion docs/Scripting/scriptingLuau/setup-and-attachment.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
1. Use the current Rustic installer, which bundles the Luau runtime. Rebuild or reinstall Rustic if the bundled host is missing.
Check the Project Manager’s **Settings** language tools and the editor **Console** for discovery errors. Contributors with a source checkout can optionally run `cargo xtask doctor` from `Engine/`.
2. Open your game project and scene. Select a **Part** object for this movement example.
3. The inspected creation menu omits Luau. Create a `.luau` file under `scripts/` with an external editor. In Explorer, right-click the file and choose **Use Script As > Object Script** while your target object is selected. This registers the asset and attaches it. Subsequent attachment can use **+ Add Component**.
3. The inspected creation menu omits Luau. Create a `.luau` file under `scripts/` with an external editor. In Explorer, right-click the file and choose **Set As > Object Component Script** while your target object is selected. This registers the asset and attaches it. Subsequent attachment can use **+ Add Component**.
Create global or scene scripts through their corresponding Programming commands.
Keep the editor-assigned Asset ID; do not edit the registry or scene files by hand.
4. Paste the [complete behavior example](/docs/scripting/luau/complete-behavior). Press **Play**, then hover or click the embedded
Expand Down
Loading