@zylem/editor 0.9.0 → 0.9.3

package/dist/zylem-editor.d.ts

@@ -1,5 +1,5 @@
 import * as _zylem_bridge from '@zylem/bridge';
-import { BridgePose, EntitySelectMode, BridgeVec3, BridgeQuat, SnapSettingsPayload, BridgeDebugTool, SceneOperationPayload, EntityTypeDescriptor } from '@zylem/bridge';
+import { BridgePose, EntitySelectMode, BridgeVec3, BridgeQuat, LevelBuffer, SnapSettingsPayload, BridgeDebugTool, SceneOperationPayload, EntityTypeDescriptor } from '@zylem/bridge';
 import { LucideProps } from 'lucide-solid';
 import { Component } from 'solid-js';
 
@@ -34,7 +34,7 @@ declare function sendEntitySelect(uuid: string | null): void;
  * consumers.
  */
 declare function sendEntitySelectMany(uuids: string[], mode?: EntitySelectMode): void;
-/** Focus/frame the game debug camera on an entity. */
+/** Focus/frame the active editor camera on an entity. */
 declare function sendEntityFocus(uuid: string): void;
 /** Write a stage variable in the running game. */
 declare function sendStageVariable(key: string, value: unknown): void;
@@ -52,6 +52,8 @@ declare function sendEntityTransform(uuid: string, transform: {
 }): void;
 /** Arm the game's add tool with a catalog type, or `null` to disarm it. */
 declare function sendAddType(typeId: string | null, props?: Record<string, unknown>): void;
+/** Stream a recorded level into the running stage. */
+declare function sendLevelLoad(buffer: LevelBuffer): void;
 /** Spawn a catalog entity without a placement click. */
 declare function sendEntityCreate(typeId: string, options?: {
     props?: Record<string, unknown>;
@@ -61,6 +63,8 @@ declare function sendEntityCreate(typeId: string, options?: {
 declare function sendSnapSettings(snap: SnapSettingsPayload): void;
 /** Show or hide the game's construction-plane grid. */
 declare function sendGridVisible(visible: boolean): void;
+/** Make a game or editor camera the main view. */
+declare function sendCameraActivate(id: string): void;
 
 /**
  * Connection lifecycle for the editor side of the bridge.
@@ -165,6 +169,11 @@ interface DockRect {
     height: number;
 }
 declare const DOCK_SIDES: readonly DockSide[];
+/**
+ * The toolbar window. When it is the only panel on its edge it takes that
+ * whole edge, and every other dock lays out in the space left over.
+ */
+declare const TOOLBAR_PANEL_ID = "toolbar";
 declare const findDockedSide: (registry: DockRegistry, panelId: DockPanelId) => DockSide | null;
 interface DockLayoutOptions {
     /** Smallest slot extent along a zone's long axis. */
@@ -176,6 +185,11 @@ interface DockLayoutOptions {
  * Left and right zones take the full viewport height and win over top and
  * bottom, which inset horizontally to the space between them. Panels sharing a
  * zone split its long axis evenly.
+ *
+ * The toolbar is the exception when it is alone on its edge: that strip runs
+ * the full length of the edge, and the rules above apply to everyone else
+ * inside the leftover rectangle. Sharing its edge with another panel drops
+ * the exception and the toolbar splits that edge like any other panel.
  */
 declare const computeDockLayout: (registry: DockRegistry, viewport: Viewport, options?: DockLayoutOptions) => Record<DockPanelId, DockRect>;
 
@@ -234,6 +248,7 @@ declare const gameState: GameState;
 
 /** Registry id of the main editor panel; detached sections use their panel id. */
 declare const MAIN_PANEL_ID = "main";
+
 interface DetachedPanelState {
     position: {
         x: number;
@@ -273,6 +288,9 @@ declare const debugStore: {
     panelZOrder: string[];
     docks: DockRegistry;
     dockDefaultsApplied: boolean;
+    toolbarSeeded: boolean;
+    toolbarCollapsed: boolean;
+    mainCollapsed: boolean;
     draggingPanelId: string | null;
     dropTargetIndex: number | null;
 };
@@ -389,6 +407,55 @@ declare function redo(): boolean;
  */
 declare function clearHistory(): void;
 
+/**
+ * Level-editor mode.
+ *
+ * Build mode owns a buffer of catalog placements. Turning it on seeds that
+ * buffer from the stage currently loaded; turning it off freezes the buffer
+ * so later stage changes do not rewrite a level the user has stepped out of.
+ * Turning it on again reseeds.
+ */
+
+/**
+ * How a recorded entry was placed.
+ *
+ * `level` is the only role marked for bake. The editor does not merge meshes;
+ * the game bakes later. `actor` and `doodad` are recorded and left out of that set.
+ */
+type LevelRole = 'actor' | 'level' | 'doodad';
+/** Role and actor props, kept beside `LevelEntry` because the bridge entry has neither. */
+interface LevelAnnotation {
+    role: LevelRole;
+    props: Record<string, string>;
+}
+interface LevelState {
+    active: boolean;
+    /** Present after Build has been turned on at least once. Frozen while inactive. */
+    buffer: LevelBuffer | null;
+    /** Keyed by entry id. Entries that leave the buffer lose their annotation. */
+    annotations: Record<string, LevelAnnotation>;
+    /**
+     * Role stamped on entries that appear while the Add tool is armed.
+     * Cleared when the tool leaves Add, so a later stage update is not mis-tagged.
+     */
+    placementRole: LevelRole | null;
+}
+/** A plain copy of the buffer, safe to post across a frame or write to a file. */
+interface LevelSnapshot {
+    buffer: LevelBuffer;
+    annotations: Record<string, LevelAnnotation>;
+    /** Stage id the buffer was recorded against, when the game has published one. */
+    stageId: string | null;
+}
+declare const levelState: LevelState;
+/**
+ * Copy the recorded level out of the editor.
+ *
+ * `null` when Build has never been turned on. A buffer frozen by leaving Build
+ * mode is still returned. The copy is plain data, not the live proxy.
+ */
+declare function snapshotLevelBuffer(): LevelSnapshot | null;
+
 /**
  * Stage export.
  *
@@ -501,18 +568,19 @@ declare function selectTransformTool(tool: TransformTool): boolean;
 /** Toggle a gizmo mode from its button: a second press returns to the neutral tool. */
 declare function toggleTransformTool(tool: TransformTool): boolean;
 /**
- * Arm placement with a catalog type. Arming an armed tool leaves it armed —
- * Escape is the way out — so placing ten of something is one arm and ten clicks.
+ * Arm placement with a catalog type and the role those new entries are tagged
+ * with. Arming an armed tool leaves it armed — Escape is the way out — so
+ * placing ten of something is one arm and ten clicks.
  *
  * @returns `false` when the catalog has no such type.
  */
-declare function armAddType(typeId: string): boolean;
+declare function armAddType(typeId: string, role?: LevelRole): boolean;
 /**
  * Arm placement with what the Add button's face shows.
  *
  * @returns `false` on an empty catalog, the one state with nothing to arm.
  */
-declare function armAddTool(): boolean;
+declare function armAddTool(role?: LevelRole): boolean;
 /** Open the Add palette, if a toolbar is showing one. */
 declare function openAddPalette(): boolean;
 declare function toggleSnap(): void;
@@ -524,9 +592,9 @@ declare function togglePlayback(): void;
  * Keyboard shortcuts for the toolbar.
  *
  * The tool row follows the Godot/Unreal layout — Q select, W move, E rotate,
- * R scale — with mnemonics for the rest: A add, X delete, D debug, S snap,
- * G grid. Every key sits under the left hand on a QWERTY board, so the right
- * hand can stay on the mouse.
+ * R scale — with mnemonics for the rest: A add, B build, X delete, D debug,
+ * S snap, G grid. Every key sits under the left hand on a QWERTY board, so
+ * the right hand can stay on the mouse.
  *
  * The keys are live whenever the editor panel is open, playing or paused: the
  * panel being up is the signal that the keyboard is addressing the editor. The
@@ -551,6 +619,9 @@ declare const TOOLBAR_SHORTCUTS: {
     readonly debug: {
         readonly key: "d";
     };
+    readonly build: {
+        readonly key: "b";
+    };
     readonly select: {
         readonly key: "q";
     };
@@ -595,7 +666,7 @@ declare const TOOLBAR_SHORTCUTS: {
 };
 type ToolbarShortcutId = keyof typeof TOOLBAR_SHORTCUTS;
 /** The shortcuts this module runs; undo and redo are `history-shortcuts`'. */
-declare const TOOLBAR_ACTIONS: readonly ["debug", "select", "translate", "rotate", "scale", "add", "addPalette", "delete", "snap", "grid", "playback"];
+declare const TOOLBAR_ACTIONS: readonly ["debug", "build", "select", "translate", "rotate", "scale", "add", "addPalette", "delete", "snap", "grid", "playback"];
 type ToolbarAction = (typeof TOOLBAR_ACTIONS)[number];
 /**
  * A chord as tooltip text: `W`, `Shift+A`, `Cmd+Enter`.
@@ -804,7 +875,7 @@ declare class ZylemEditorElement extends HTMLElement {
     openPanel(): void;
     closePanel(): void;
     togglePanel(): void;
-    /** Whether the main panel is showing. Collapsed counts as showing; closed does not. */
+    /** Whether either editor window is showing. Collapsed counts as showing; closed does not. */
     isPanelOpen(): boolean;
     /**
      * Dock a panel to a viewport edge, or pass `null` to float it again.
@@ -915,13 +986,14 @@ interface MountZylemEditorOptions extends EditorStateBridgeOptions {
      */
     launcherMode?: EditorLauncherMode;
     /**
-     * Dock layout to seed on first run, keyed by viewport edge. `'main'` is the
-     * editor panel; any other id is a section such as `'console'`. Ignored once
-     * the user has a saved layout.
+     * Dock layout to seed on first run, keyed by viewport edge. `'toolbar'` is
+     * the tool strip, `'main'` is the panel container, and any other id is a
+     * section such as `'console'`. A host that omits the toolbar still gets it
+     * on top. Ignored once the user has a saved layout.
      *
      * @example
      * ```ts
-     * mountZylemEditor({ defaultDocks: { left: ['main'], bottom: ['console'] } });
+     * mountZylemEditor({ defaultDocks: { top: ['toolbar'], left: ['main'] } });
      * ```
      */
     defaultDocks?: EditorDockDefaults;
@@ -966,4 +1038,4 @@ type SceneOperationListener = (op: SceneOperationPayload) => void;
  */
 declare function onSceneOperation(listener: SceneOperationListener): () => void;
 
-export { type CatalogState, type ClickTool, DEFAULT_ROTATE_SNAP, DOCK_SIDES, type DockPanelId, type DockRect, type DockRegistry, type DockSide, type DockZoneState, type EditorDockDefaults, type EditorEvent, type EditorEventType, type EditorStateBridge, type EditorStateBridgeOptions, type EditorUpdatePayload, type HistoryState, Icon, MAIN_PANEL_ID, MAX_HISTORY_DEPTH, type MountZylemEditorOptions, type MountedZylemEditor, type SceneOperationListener, type ShortcutChord, type StageExport, type StageExportEntity, TOOLBAR_SHORTCUTS, type ToolbarAction, type ToolbarShortcutId, type ToolbarShortcutOptions, type TransformState, type TransformTool, type TransformToolGuardOptions, type ZylemEditorConfig, ZylemEditorElement, armAddTool, armAddType, attachEditorStateBridge, channel as bridgeChannel, buildStageExport, canRedo, canUndo, catalogState, clearHistory, computeDockLayout, connectEditorBridge, copyStageExport, debugState, debugStore, disarmTools, disconnectEditorBridge, dispatchEditorUpdate, dispatchToEditor, dockPanelToSide, editorEvents, findDockedSide, formatShortcut, gameState, getDockedSide, historyState, installToolbarShortcuts, installTransformToolGuard, mountZylemEditor, onSceneOperation, openAddPalette, redo, redoLabel, registerZylemEditor, releaseOrphanedTransformTool, runToolbarAction, selectTool, selectTransformTool, sendAddType, sendDebugEnabled, sendEntityCreate, sendEntityFocus, sendEntitySelect, sendEntitySelectMany, sendEntityTransform, sendGridVisible, sendPlayback, sendSnapSettings, sendStageVariable, sendTool, setArmedType, setEntityCatalog, setGridVisible, setSnapEnabled, setSnapIncrements, stageExportToString, stageState, toggleDebug, toggleGrid, togglePlayback, toggleSnap, toggleTool, toggleTransformTool, transformState, undo, undoLabel, undockPanelFromSides };
+export { type CatalogState, type ClickTool, DEFAULT_ROTATE_SNAP, DOCK_SIDES, type DockPanelId, type DockRect, type DockRegistry, type DockSide, type DockZoneState, type EditorDockDefaults, type EditorEvent, type EditorEventType, type EditorStateBridge, type EditorStateBridgeOptions, type EditorUpdatePayload, type HistoryState, Icon, type LevelSnapshot, MAIN_PANEL_ID, MAX_HISTORY_DEPTH, type MountZylemEditorOptions, type MountedZylemEditor, type SceneOperationListener, type ShortcutChord, type StageExport, type StageExportEntity, TOOLBAR_PANEL_ID, TOOLBAR_SHORTCUTS, type ToolbarAction, type ToolbarShortcutId, type ToolbarShortcutOptions, type TransformState, type TransformTool, type TransformToolGuardOptions, type ZylemEditorConfig, ZylemEditorElement, armAddTool, armAddType, attachEditorStateBridge, channel as bridgeChannel, buildStageExport, canRedo, canUndo, catalogState, clearHistory, computeDockLayout, connectEditorBridge, copyStageExport, debugState, debugStore, disarmTools, disconnectEditorBridge, dispatchEditorUpdate, dispatchToEditor, dockPanelToSide, editorEvents, findDockedSide, formatShortcut, gameState, getDockedSide, historyState, installToolbarShortcuts, installTransformToolGuard, levelState, mountZylemEditor, onSceneOperation, openAddPalette, redo, redoLabel, registerZylemEditor, releaseOrphanedTransformTool, runToolbarAction, selectTool, selectTransformTool, sendAddType, sendCameraActivate, sendDebugEnabled, sendEntityCreate, sendEntityFocus, sendEntitySelect, sendEntitySelectMany, sendEntityTransform, sendGridVisible, sendLevelLoad, sendPlayback, sendSnapSettings, sendStageVariable, sendTool, setArmedType, setEntityCatalog, setGridVisible, setSnapEnabled, setSnapIncrements, snapshotLevelBuffer, stageExportToString, stageState, toggleDebug, toggleGrid, togglePlayback, toggleSnap, toggleTool, toggleTransformTool, transformState, undo, undoLabel, undockPanelFromSides };