Skip to content

perro_editor.md

Latest commit

 

History

History
184 lines (132 loc) · 10.8 KB

perro_editor.md

File metadata and controls

184 lines (132 loc) · 10.8 KB
Raw

Perro Editor

Page Map

Header Link
Purpose Purpose
Use Cases Use Cases
Status Status
Start Start
Shell Shell
Workflow Workflow
Main Shortcuts Main Shortcuts
Safety Safety
Animation And GLB Animation And GLB
Selection And Scene Reuse Selection And Scene Reuse
Asset Moves And Tool Options Asset Moves And Tool Options
Release Gate Release Gate

Purpose

The Perro editor is a visual authoring tool — itself a Perro project in perro_editor — for building and previewing scenes without hand-writing .scn text. It gives you a node tree, 2D/3D/UI viewports, an inspector for node fields and script vars, animation editing, GLB inspection, undo/redo, file watching, and multi-scene tabs. Lay out and tweak scenes visually here, then run and ship them with the CLI. It is an in-development milestone: play/build launch and stable packaging remain follow-up work. Assets use direct disk refs; animation conversion stays explicit.

Use Cases

  • Open or create a project visually. Launch cargo run -p perro_cli -- dev --path perro_editor, then pick a folder with project.toml or create one in the project manager.
  • Author a scene without editing text. Add or select nodes in the Scene panel, edit fields in the Inspector, and save with Ctrl+S (or Ctrl+Shift+S for all dirty scenes).
  • Preview 2D, 3D, and UI in place. Switch viewports with 1 / 2 / 3 and frame the selection with F.
  • Edit animations with live preview. Select an AnimationPlayer to open the animation dock for clip selection, playhead control, key insert/delete, and interpolation changes.
  • Inspect an imported model. Open a .glb or .gltf to switch to the 3D model viewer with mesh, material, animation, skeleton, and texture summaries.
  • Run the editor's own release gate. check, clippy, and test through perro_cli --path perro_editor before landing editor changes.

Editor vs Code

Use the editor for topology, node fields, script_vars, asset refs, and visual preview. Use Rust source for lifecycle, methods, queries, and game decisions. #[expose] groups a state field in the inspector; pub decides whether a scene may inject that field, so an exposed field must also be pub for its authored value to apply.

Use text scene editing when reviewing a compact diff or applying a mechanical change. Use the editor when spatial context and ref pickers reduce mistakes. Both author the same .scn contract.

Status

The editor is an in-development Perro project in perro_editor.

The current milestone supports project selection, scene and asset authoring, 2D/3D/UI previews, inspector edits, animation editing, GLB inspection, undo/redo, file watching, and multi-scene tabs.

Play/build launch and stable release packaging remain follow-up work. Assets stay on disk with direct refs; there is no import database or automatic reimport queue.

Start

Run from the repository root:

cargo run -p perro_cli -- dev --path perro_editor

The project manager can open a folder with project.toml or create a project. Recent projects are stored under user:// and shown on the next launch.

Use Browse for a native folder picker, or paste a folder into Open Project Path and press Open. A source project does not need generated .perro/ files. The manager shows errors below its actions. Save dirty scenes before opening another project or reloading the current one.

After updating editor source, launch through the command above to rebuild its scripts and runtime. An older .output/Perro Editor.exe retains the code from its last release build.

Shell

Area Use
Activity rail Switch scene and GLB workspaces.
Left panel Browse scene nodes above project files.
Center Edit and preview UI, 2D, or 3D scenes.
Inspector Edit selected node fields, refs, and script vars.
Bottom dock Inspect output and animation state.
Scene tabs Keep independent scene docs, selections, undo stacks, and dirty state.

Use the command palette with Ctrl+Shift+P. Search terms can match any words in a command label. The compact shell keeps common actions visible. Find create, duplicate, delete, reparent, tree navigation, and expand/collapse actions in the palette. Output stays collapsed until requested, leaving more room for the scene viewport.

Workflow

  1. Open or create a project.
  2. Select a .scn file in Files and open it.
  3. Add or select nodes in Scene.
  4. Edit fields in Inspector or use viewport tools.
  5. Save with Ctrl+S or save all open dirty scenes with Ctrl+Shift+S.

The asset browser watches res/ plus project input and localization files. Script changes invalidate inspector schema caches. Clean open scenes reload after an external edit. A changed scene with unsaved editor work stays in memory and reports external change pending in Output.

Main Shortcuts

Shortcut Action
Ctrl+Shift+P Open command palette.
Ctrl+S / Ctrl+Shift+S Save scene / save all scenes.
Ctrl+Z / Ctrl+Y Undo / redo active scene.
Ctrl+N / Ctrl+Shift+N Add child / sibling node.
Ctrl+O Open selected file or selected node asset ref.
Ctrl+W / Ctrl+Shift+W Close active / all scene tabs.
Ctrl+Tab Cycle scene tabs.
Ctrl+R Refresh project assets.
1 / 2 / 3 Switch 2D / 3D / UI viewport.
F Frame selected node.
F2 Rename current selection.
Delete Delete selected node or asset.
Ctrl+Shift+F11 Toggle distraction-free layout.

Shortcuts pause while a text box owns focus. Escape closes active popups or cancels pending confirmation.

Safety

  • Dirty scene tabs show a marker and keep separate in-memory docs.
  • Closing a dirty tab asks for a second close action, saves, and closes only after the save succeeds.
  • Asset and folder deletion needs a second confirmation action.
  • Dirty assets cannot be renamed or deleted until saved.
  • External changes do not reload a dirty copy of the same scene.
  • Confirmation expires after a short timeout or selection change.

Save or copy work before resolving an external-change conflict. The editor keeps its in-memory version and does not merge scene text.

Animation And GLB

Select an AnimationPlayer to open its animation workflow. The dock supports clip selection, playhead control, key insertion/deletion, interpolation/ease changes, and undo/redo.

Opening a .glb or .gltf switches to the 3D model viewer. The viewer frames the model and exposes mesh, material, animation, skeleton, and texture summaries. Bracket shortcuts cycle embedded refs.

Selection And Scene Reuse

  • Use Ctrl + click to toggle tree selection; Shift + click to select a visible range.
  • Use copy/paste, duplicate, delete, and reparent in/out on the selection. Selected parents absorb selected descendants for subtree edits.
  • Keep one undo record per batch. Undo/redo and scene tabs retain the selection.
  • Copy captures scene data, so paste also works after deleting the source or switching scene tabs. Internal node refs follow the copied nodes.
  • Edit shared scalar/vector/ref fields in the inspector. Mixed values show (mixed); incompatible fields and containers stay out of the shared inspector.
  • Use move/rotate/scale in 2D and 3D. Drag projected axes or hold X/Y/Z at drag start; local/world and snap controls apply. Scale is uniform. Rotate/scale reject nonuniform parent scale; zero parent scale blocks all transforms.
  • Use UI move/resize/rotate on free-layout nodes. Parent layout ownership blocks direct transforms. A drag commits once; Escape restores its start state.
  • Use the command palette to save one branch as a new .scn, open an instance source, or instance the active scene asset. Branch save picks a fresh filename and retains the original scene.
  • Keep existing root_of behavior. Edit instance contents in their source scene; no instance-child override layer is added. Scene instance creation rejects dependency cycles.

2D viewport picking currently uses node origins within a small screen radius; 3D uses mesh picking. Tree selection also supports nodes without drawable geometry. Reparent in/out preserves authored local transforms, so world poses can change.

Asset Moves And Tool Options

Use Rename or the command palette's move-to-folder action for files and folders under res/. A background scan stages reference changes in scenes, project.toml, and saved tool options. Commit validates reference bytes, writes staged files, and moves the asset. Failure restores prior reference bytes where possible and reports rollback failures.

Save affected dirty scenes first. Unsupported text refs and glTF relative dependencies block unsafe moves. Linked paths and existing destinations also block moves. Scene/TOML serialization may reformat changed files; review their diffs. Filesystem moves are separate from scene undo.

Asset pickers enumerate GLB/glTF mesh, material, texture, and rig subrefs from metadata in a background job. Selection still writes ordinary res://...:mesh[n], :mat[n], :tex[n], or :rig[n] refs. Metadata scans do not decode textures or generate assets.

Open Animation Tools from the command palette. Set input, output, clip, FPS, skeleton, and optional retarget map/target rig. Choose a Perro CLI executable when automatic discovery cannot find one. Convert runs import_anim as an explicit background process and reports its output.

Save/Load applies only to these conversion options. Store versioned TOML under editor_tools/; paths resolve from the project root. Convert uses current fields and does not silently save them. The CLI path stays in user://editor_cli.txt, outside the portable options file. See CLI animation options.

See editor workflow measurements for scoped-view timings and verification limits.

See editor input and project recovery for callback regressions, file-browser fixes, and CPU probe measurements.

Release Gate

Run from the repository root:

cargo run -p perro_cli -- check --path perro_editor
cargo run -p perro_cli -- clippy --path perro_editor
cargo run -p perro_cli -- test --path perro_editor

clippy also runs project doctor checks for config, scene, asset, and script refs. CI runs all three editor commands on Linux.

For a manual smoke pass:

cargo run -p perro_cli -- dev --path perro_editor --timings --ui-profile

Check project manager launch, scene open/save, tab switching, node add/delete confirmation, asset refresh, viewport mode switching, inspector edits, animation dock, and GLB viewer.