Editor: a view into the world

An editor edits engine data#

An editor is more than panels around a viewport. Every control must translate an intention into a valid scene change. QubicEngine’s Editor owns document state, selection, undo history, and tool interaction. It uses the same Scene, AssetStore, and Renderer contracts as the runtime. The hierarchy shows entity relationships. Properties expose component fields with meaningful units and validation. The viewport shows rendered output and tool overlays. The asset browser refers to import records and ready assets, not arbitrary GPU allocations.

Selection and coordinate spaces#

Clicking a rendered object needs a mapping from screen pixels to entity identity. An ID attachment can store a compact picking ID during a special pass, or a CPU ray can test bounds and geometry. GPU readback introduces latency; the selection policy should avoid blocking the graphics queue for every pointer move. A transform gizmo converts pointer motion into a world-space constraint. Local mode uses the selected object’s axes; world mode uses fixed world axes. Changing a parented object’s world pose requires converting the result back into its local transform.

Use the lab to see translation, scale, rotation, camera distance, and projection as distinct operations. A production gizmo must also handle snapping, multiple selection, cancellation, and a stable drag plane when the camera looks along a manipulated axis.

Commands make changes reversible#

An EditorCommand stores enough information to Apply and Revert an edit. A transform drag becomes one command when the gesture finishes, rather than hundreds of unrelated history entries. Cancellation restores the original pose. An asset import or hierarchy deletion may require a richer snapshot than a simple old/new number.

struct TransformCommand {
    Entity target;
    LocalTransform before;
    LocalTransform after;
    // Apply validates target generation, then writes after.
    // Revert validates target generation, then writes before.
};

Serialization and play mode#

Saving a document serializes stable IDs and asset references. A schema version lets import code migrate old files deliberately. Save to a temporary file and replace the destination only after the complete write succeeds; this avoids leaving half a scene after interruption. Play mode uses a separate simulation instance derived from the editable document. Runtime movement and spawned entities do not silently alter the authoring scene. Applying selected play-mode changes back to the document is an explicit editor action with validation and undo semantics.

Rendering editor views#

Each viewport has a camera and render dimensions. Resizing a panel schedules attachment recreation after in-flight uses complete. The editor can render several views, so a global camera singleton is a poor contract. Tool overlays use their own passes and must respect the intended depth behavior. The reference design supports an immediate-mode UI integration at the editor boundary. That library’s texture handles refer to backend-owned descriptors and need the same safe retirement as other GPU references. UI state is not a substitute for scene state.

Costs and failure modes#

Picking readbacks, high-resolution viewports, thumbnails, and continuous asset reimport can dominate an idle editor. Profile them separately. Pause hidden viewports and avoid generating thumbnails for every asset each frame. Undo that changes the wrong object suggests an identity or document-version error. A gizmo that jumps suggests mixing local and world coordinates. A viewport that corrupts after resize suggests attachment reuse before completion. This article describes a native editor architecture; the website provides focused teaching controls rather than a pretend editor UI.