Vixen
dd8b0a81

Editor · guide

The editor shell

The window the editor is made of, and the command registry every part of it is a view over.

Edit this page on GitHub

Documents

What it is

EditorShell is the editor's window: a menu bar, a mode bar, a toolbar, a docking workspace and a status bar, built into a UiDocument and nothing else — no platform, no device, no window. Inside it are CommandRegistry, the one table of everything the editor can be asked to do; EditorCommand, one entry in it; and KeyMap, which says what runs each of them from the keyboard. All three are Vixen.Ui.Controls types, so an application that is not the editor has them too.

What it is for

Menus, toolbars, context menus and the command palette are views over the registry rather than four places that each know how to save a file. An action added once appears everywhere it belongs, gets a keybinding, gets a place in the palette, and gets its enabled state from one predicate instead of four copies that drift.

The shell is deliberately constructible with no GPU, which is what makes the whole of the editor's chrome testable headless — a shell, synthetic input, and assertions against the real element tree.

You do not want it when you are writing a panel. A panel is a control over a model; which dock group it lands in and which commands act on it is the application's arbitration, and a panel that reached for the shell would be one that cannot be tested without one.

Using it

Register a panel, a layout and a command; the menu, the palette and the shortcut follow.

csharp
using var shell = new EditorShell(1600f, 1000f);shell.RegisterPanel("scene", new StringId("editor.panel.scene", "Scene"), panel => panel.Add<Viewport>());shell.Commands.Add(new EditorCommand("file.save", EditorStrings.CommandSave, project.Save) {    Enablement = () => project.IsDirty});shell.Keys.SetDefault("file.save", new KeyChord(InputKey.S, ModifierKeys.Control));

Enablement is a predicate, not a flag. A flag has to be pushed at every view whenever the world changes, which means a menu that is right only if somebody remembered to invalidate it. A menu asks as it opens and a toolbar asks on the tick, so neither can be stale — the cost is that the predicate runs often and has to be cheap.

A command carries no keybinding. That is KeyMap's, because a binding is the user's and a command is the application's. The map is three layers — the defaults the application ships, a chosen preset, and the user's own overrides — and only the last is saved, so a default moved in a release reaches everyone who had not deliberately rebound it. ⚠ KeyMap, KeyMapPreset and CommandDispatcher are Vixen.Ui.Controls types and are described in commands and the focus route; what stays here is the editor's own data — KeyMapPresets, its three shipped presets, and KeyMapYaml, the file they and a user's keymap are both written in.

A command may declare a context. Delete in the outliner and Delete in the content browser are two commands and one key. EditorCommand.Context names the place a verb belongs, EditorShell.Context says which place has the focus, and CommandRegistry.CanExecute refuses the one belonging somewhere else. Within a context a chord belongs to one command and a conflict is reported rather than resolved; across contexts, sharing a chord is the point.

Examples

The context mechanism is what an editor mode's claim on a key is built out of — see editor modes, where 1–4 mean the blockout element modes while that mode is active and view-bookmark recall while it is not.

A command that is declared but not built yet says so rather than being absent:

csharp
shell.Commands.Add(new EditorCommand("scene.bake-lighting", title, Bake) {    Unavailable = new StringId("editor.unavailable.bake", "There is no lightmapper yet")});

It is greyed wherever it appears, and the palette and the refusal notice both have a sentence to show. A menu line that is missing reads as an editor that cannot do the thing; one that is there and greyed reads as an editor that will.

See also

  • Editor modes — what the viewport's input means right now.
  • Sub-object picking — which face, edge or vertex of one mesh is under the pointer, which is the question a mode's element modes ask.
  • Showing what is selected — what a viewport draws round the object a click landed on, and why a pane drawn by a compositor cannot say it with colour.
  • Snapping — what a transform lands on, and which part of it lands there.
  • Building to a number — the work plane, typed transforms, the tape measure and the scale references.
  • Editable meshes in a scene — how an entity comes to carry geometry you can edit.
  • docs/plan/11 — the editor's shape, and the eight extension points a plugin writes against.
  • docs/plan/20 — the parity plan, panel by panel and menu by menu.

Next

  • Commands and the focus route — A menu declares what, and the focus decides who — a command id resolved by walking outwards from the focused element and on past the root to the document and the application, so two views can answer the same verb without knowing each other exists and an item nothing handles greys itself out.
  • Dialogs that answer — A modal question an application can await — confirm, prompt, choose, or one it fills in itself — queued one at a time, completed from the document's tick rather than from the click that answered it, and answered rather than dropped when the application goes away.
  • Strings and the catalogue — A label is an id plus the English it was written as, so a missing translation shows the sentence rather than the id — and the catalogue in use is a signal, so a language change re-labels a running interface with no code at any call site.
  • Background tasks — Long work that does not freeze the window — a task model with progress, status and cancellation whose properties are signals, a queue that lands every report on one point of the frame, and a manager whose disposal is what stops a cancelled import outliving the application that started it.
  • Editor modes — What the viewport's input means right now, and how a mode claims keys that already mean something else.
  • What a play session runs — How a module adds systems to the frame the editor's Play button steps — the `IPlaySystems` contribution, the `PlaySession` that owns their lifetime, and the physics world the editor now stands up on Play and takes away on Stop.
  • Edits made outside the editor — What happens when a file the editor has open is changed by something else, and why the editor's own saves do not count.
  • Saved filters in the project browser — A named search of the project, kept beside the layouts and the keymap — and why it stores the query rather than what the query matched.
  • Collections in the project browser — A named set of assets kept with the project — why it holds ids rather than paths, and why it lives under ProjectSettings while a saved filter lives beside your keymap.
  • Scene menus — A pie menu under the cursor and a list beside it, both filled by one registration and filtered by the active mode.
  • Prefab overrides — How a scene records that an entity came from a prefab and which of its members it has changed, and what happens when the prefab changes underneath it.
  • Icons — Declaring what a type looks like with SVG path data, and the parser that made the attribute buildable.
  • Utility styles — Styling an editor panel with Tailwind-shaped class names — the build step that compiles them, the one palette they resolve against, and which families the engine actually reads.
  • The editing pipeline — One path every edit in the editor takes, so undo, multi-object editing and mixed values are answered once rather than per panel.
  • Writing an editor plugin — What a plugin can contribute to the editor, how it registers, and how everything it added is taken back out when it unloads.
  • Editor scripts — A .cs file in your project's Editor/ folder is compiled by the running editor and loaded like a plugin — drop it in, and its menu item is there.
  • Inspectors in markup — Writing a custom inspector as a .vxml file with no code-behind, bound to the editing pipeline by name after the tree is built.
  • The frame panel — Editing a .vxcompositor as the Standard Frame's knobs, with the resolved quality waterfall and the per-camera volume stack shown beside them, and Explode as the one-way door out.
  • The network panel — Where a session's bandwidth is going, how the link is behaving over time, and what is inside one snapshot — an editor panel over the BandwidthLedger, SnapshotInspector, RoundTripEstimator and transport loss counters a game already has.
  • Sub-object picking — Which face, edge or vertex of one mesh the pointer is on, and why that is a different question from which entity.
  • Showing what is selected — The corner brackets a viewport draws round a selected object, and why a composed pane cannot say it with colour.
  • Snapping — What a transform lands on, which part of it lands there, and why that is one service rather than one per tool.
  • Building to a number — The work plane you build in, typing an exact distance mid-drag, the tape measure, and the scale references.
  • Editable meshes in a scene — How an entity comes to carry an editable mesh, how it is saved, and how an edit is undone.
  • Element selection — Vertex, edge and face modes over one mesh — what a click takes, what a loop walks, and what survives an edit.
  • The shape tool — Making block-out geometry — live parameters, the cube grid, the poly shape, and duplicate, mirror and array.
  • Face materials — Per-face materials, UV projection, smoothing groups and the block-out checker the viewport draws by default.
  • Booleans and handoff — Non-destructive union, subtract and intersect whose operands stay editable — and what turns a block-out into an asset.
  • Retopology and UV surfaces — Where a quad remesh and an unwrap are actually invoked from — the model importer, three command-line verbs, and the blockout mode's own verb and UV panel.
  • The VFX graph — The node library a .vxvfx is authored against — spawners, initializers, updaters and outputs — and the compiler that turns one graph into both an effect the CPU runs and a shader a device runs.
  • Shader-graph preview thumbnails — Compiling one node's sub-expression on its own, running it over a quad, and keeping the target alive across edits.
  • A material that draws with a shader graph — A graph emits a material feature rather than a whole shader, which is why the engine's existing draw can put one on a mesh.
  • Procedural and UV nodes in a shader graph — Noise, a checker and the two UV transforms — each one a call into the shader library rather than a second copy of it, which is also why they have no preview.
  • Graph diagnostics that name a node — How a complaint about a line of generated shader source becomes a complaint about a node the author can select, across sub-graph inlining.
  • Evaluating a texture plan — The plan of compute kernels a texture graph and a layer stack both compile to, the image pool that runs it, and the resolution rule that keeps a graph the same material at every size.
  • Compiling a texture graph — The compiler that turns a node graph into a texture plan, and the four things it hands back besides the plan — the outputs by usage, the pictures a host still owes it, the parameters an author exposed, and the per-node images a preview draws.
  • The texture graph plugin — The .vxtexgraph document, the panel that edits one, and the module that registers both through the plugin contract — plus the three things a plugin could not do when this module was written, each with the change that closed it.
  • Texture-graph node previews — The swatch under every node of a texture graph — one plan that keeps every node's image, one bake, and pixels handed to the host because a compute queue's images are not the interface's to sample.
  • Mesh maps as project assets — The bake panel a mesh-map bake is set up in, what the nine files are called, how a set is keyed on the model it came from, and how a generator finds one by usage rather than by path.
  • Baking a material — How a texture graph's outputs become files the engine already understands — the nine usages and the seven files they land in, the ORM packing, PNG or KTX2, the .vxmat, the GUID dance, and the provenance block that stops a painted-over map being regenerated.
  • Generators and the compound library — How a generator asks for a baked mesh map by what it measures rather than by which file it is, where a shipped compound lives, and why a graph must not name the mesh it is for.
  • Computing a sub-graph's port values — A published graph is inlined rather than called, so what its unfed ports are worth is decided during the walk — this is the seam that lets a front end compute one instead of only reading a number.