babylon.quarks-editor 0.26.0 → 0.28.0

package/dist/core/editorSession.d.ts

@@ -0,0 +1,229 @@
+import { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera.js';
+import '@babylonjs/core/Culling/ray.js';
+import type { AbstractEngine } from '@babylonjs/core/Engines/abstractEngine.js';
+import { GizmoManager } from '@babylonjs/core/Gizmos/gizmoManager.js';
+import type { Texture } from '@babylonjs/core/Materials/Textures/texture.js';
+import type { Mesh } from '@babylonjs/core/Meshes/mesh.js';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode.js';
+import { Scene } from '@babylonjs/core/scene.js';
+import { BatchedRenderer } from 'babylon.quarks';
+import { type AssetDragPayload } from './assetTree.js';
+import { type AssetLoadProgress, type EffectAsset } from './assets.js';
+import type { EffectBinding } from './binding.js';
+import { EffectHistory } from './history.js';
+import { type PlaybackState } from './playback.js';
+import type { ProjectStore } from './projectStore.js';
+import { type SceneEntry } from './sceneEntries.js';
+/** What an editor session hands its host once it is live, and again whenever the focused effect changes. */
+export interface EffectEditorHostHandle {
+    /** The focused effect's binding; reading it throws when no effect is focused. */
+    binding: EffectBinding;
+    /** Undo/redo of the focused effect. */
+    history: EffectHistory;
+    /** The editor's preview scene. */
+    scene: Scene;
+    /** The renderer every effect in the scene draws through. */
+    renderer: BatchedRenderer;
+    /** Replaces the scene with this effect (it is also added to Assets). */
+    importJson: (json: unknown) => void;
+    /** Imports effect files (and the texture/geometry files they reference) into Assets. */
+    importAssets: (files: FileList | File[]) => Promise<void>;
+    /** @deprecated Renamed to `importAssets`. */
+    importGallery: (files: FileList | File[]) => Promise<void>;
+    /** The focused effect as quarks JSON; throws when no effect is focused. */
+    exportJson: () => string;
+}
+/** A project an editor session loads its assets and scene from, and saves them to. */
+export interface EditorProject {
+    /** Where the project lives. */
+    store: ProjectStore;
+    /** The project's id in `store`. */
+    id: string;
+    /** The project's display name. */
+    name: string;
+}
+/** Which prefab is open, as the host shows it. */
+export interface PrefabInfo {
+    /** The asset's display name. */
+    name: string;
+    /** The asset's path in Assets. */
+    path: string;
+}
+/** Live readouts a session writes every frame. */
+export interface EditorFrameStats {
+    /** Frames per second, rounded. */
+    fps: number;
+    /** Time and particle count of the focused effect, e.g. `1.2s / 3.0s · 240 particles`. */
+    counter: string;
+}
+/**
+ * How an editor session reports to its host. A React host passes its state setters. Callbacks
+ * run synchronously from the action that changed the value, except `frame` (from the render
+ * loop) and the results of asynchronous work: asset import progress and a project's load. None
+ * runs after the session is disposed.
+ */
+export interface EditorSessionView {
+    /** The focused effect's binding changed (`null`: nothing is focused). */
+    bindingChanged(binding: EffectBinding | null): void;
+    /** The node selected in the focused effect changed. */
+    selectedNodeChanged(node: TransformNode | null): void;
+    /** The focused effect's root changed. */
+    focusedRootChanged(root: TransformNode | null): void;
+    /** The scene's entries changed. */
+    entriesChanged(entries: SceneEntry[]): void;
+    /** Assets changed. */
+    assetsChanged(assets: EffectAsset[]): void;
+    /** The set of shown entries changed, by root `uniqueId`. */
+    visibleChanged(rootIds: number[]): void;
+    /** The entry shown alone changed (`null`: none). */
+    soloChanged(rootId: number | null): void;
+    /** An asset import started, progressed (a progress value) or ended (`null`). */
+    assetsLoadingChanged(progress: AssetLoadProgress | null): void;
+    /** The scene has unsaved changes, or no longer has. */
+    sceneDirtyChanged(dirty: boolean): void;
+    /** The project's scene finished loading, or failed to. */
+    projectLoaded(): void;
+    /** The open prefab changed (`null`: back to the scene). */
+    prefabChanged(info: PrefabInfo | null): void;
+    /** The open prefab has unsaved edits, or no longer has. */
+    prefabDirtyChanged(dirty: boolean): void;
+    /** Opening another asset waits on what to do with the open prefab's unsaved edits. */
+    prefabSwitchRequested(asset: {
+        id: number;
+        name: string;
+    }): void;
+    /** The asset drag hovering the viewport changed (`null`: none). */
+    dragHoverChanged(hover: {
+        label: string;
+        count: number;
+    } | null): void;
+    /** Something was added to Assets that the user should see. */
+    assetsRevealed(): void;
+    /** Something changed that has no state of its own, such as an undo stack; re-render. */
+    refresh(): void;
+    /** A short notice. */
+    toast(text: string): void;
+    /** A notice the user dismisses. */
+    message(title: string, text: string): void;
+    /** The session is live, or what it hands out changed. */
+    ready(handle: EffectEditorHostHandle): void;
+    /** A frame was drawn. */
+    frame(stats: EditorFrameStats): void;
+}
+/** What an editor session is built from. */
+export interface EditorSessionOptions {
+    /** The engine to draw with; its rendering canvas, if any, drives the camera and picking. */
+    engine: AbstractEngine;
+    /** Playback state shared with the host's transport and timeline. */
+    playback: PlaybackState;
+    /** How the session reports to its host; a callback left out is not called. */
+    view: Partial<EditorSessionView>;
+    /** The project to load and save; without it the session works in memory only. */
+    project?: EditorProject;
+    /** Quarks JSON to open when there is no project; a default effect is created when omitted. */
+    effectJson?: unknown;
+    /** Texture loader for new default effects. */
+    resolveTexture?: (url: string, scene: Scene) => Texture | null | undefined;
+    /** Texture URL of new default effects. */
+    defaultTextureUrl?: string;
+    /** True while an asset is being dragged over the viewport; viewport picking pauses meanwhile. */
+    isAssetDragActive?: () => boolean;
+    /** The node selected in the host, kept across undo and redo. */
+    getSelectedNode?: () => TransformNode | null;
+}
+/**
+ * The editor's headless half: the preview scene, the effects placed in it, Assets, prefab mode,
+ * the project's scene and undo, without any UI. `EffectEditorHost` is its React view; any
+ * other host can drive it through these actions and {@link EditorSessionView}.
+ */
+export interface EditorSession {
+    /** The engine the session draws with. */
+    readonly engine: AbstractEngine;
+    /** The preview scene. */
+    readonly scene: Scene;
+    /** The orbit camera. */
+    readonly camera: ArcRotateCamera;
+    /** The grid the effects stand on. */
+    readonly ground: Mesh;
+    /** The renderer every effect draws through. */
+    readonly renderer: BatchedRenderer;
+    /** Undo/redo of the focused effect. */
+    readonly history: EffectHistory;
+    /** The transform gizmos. */
+    readonly gizmoManager: GizmoManager;
+    /** The focused effect's binding, if any. */
+    readonly binding: EffectBinding | null;
+    /** The effects in the scene (in prefab mode, just the prefab's instance). */
+    readonly sceneEntries: SceneEntry[];
+    /** The shown entries, by root `uniqueId`. */
+    readonly visibleRootIds: number[];
+    /** Assets. */
+    readonly assets: EffectAsset[];
+    /** True while a prefab is open. */
+    readonly isPrefabOpen: boolean;
+    /** Imports effect files into Assets; throws when nothing new was found. */
+    importAssets(files: FileList | File[]): Promise<void>;
+    /** Replaces the scene with this effect, also added to Assets. */
+    importJson(json: unknown): void;
+    /** Focuses an entry and frames it. */
+    focusEntry(entry: SceneEntry | null, moveCamera?: boolean): void;
+    /** Shows or hides an entry. */
+    toggleVisible(entry: SceneEntry): void;
+    /** Shows an entry alone, or ends solo when it already is. */
+    toggleSolo(entry: SceneEntry): void;
+    /** Removes an entry from the scene. */
+    deleteEntry(entry: SceneEntry): void;
+    /** Removes the focused entry, if any; returns whether it did. */
+    deleteFocused(): boolean;
+    /** Adds a default effect at the camera target. */
+    createDefault(): void;
+    /** Where dragged assets would land, and what they are, for the drag preview. */
+    previewDrop(clientX: number, clientY: number): void;
+    /** Places dragged assets where they were dropped. */
+    placeDrop(clientX: number, clientY: number, dataTransfer?: DataTransfer): void;
+    /** Hides the drag preview while the drag goes on elsewhere. */
+    hideDropPreview(): void;
+    /** Hides the drag preview and forgets the drag, once it ended. */
+    clearDropPreview(): void;
+    /** Shows or hides wireframes of the focused effect's emitter shapes. */
+    setEmitterWireframesVisible(visible: boolean): void;
+    /** Adds assets at the camera target. */
+    addToScene(payload: AssetDragPayload): void;
+    /** Removes assets. */
+    deleteAssets(payload: AssetDragPayload): void;
+    /** Saves an entry as a new asset at `Folder/Name` and makes it an instance of it. */
+    saveEntryAsAsset(entry: SceneEntry, path: string): void;
+    /** Saves the scene to the project; resolves to false when it could not. */
+    saveScene(): Promise<boolean>;
+    /** Opens an asset on its own, setting the scene aside. */
+    openPrefab(assetId: number, discardChanges?: boolean): void;
+    /** Overwrites the open prefab's asset with the edits. */
+    overwritePrefab(): void;
+    /** Saves the open prefab as a new asset and keeps editing that one. */
+    savePrefabAsNew(path: string): void;
+    /** Leaves prefab mode without saving. */
+    closePrefab(): void;
+    /** Scene instances of the open prefab's asset. */
+    prefabInstanceCount(): number;
+    /** Undoes (`redo` false) or redoes a change to the focused effect. */
+    historyStep(redo: boolean): void;
+    /** Re-applies playback to the scene after the host changed `playback.stagePlaying`. */
+    syncPlayback(): void;
+    /** The handle a host hands to its embedder. */
+    makeHandle(): EffectEditorHostHandle;
+    /** Loads the project, or the initial effect, and starts the render loop. Later calls do nothing. */
+    start(): void;
+    /**
+     * Stops the render loop and frees the scene, the markers and the gizmos. Work still in flight
+     * (a project load, an asset import) is dropped when it finishes. The engine is the caller's.
+     */
+    dispose(): void;
+}
+/** `Folder/Name` typed by the user → a clean asset path ending in `.json`. */
+export declare function normalizeAssetPath(input: string): string;
+/** Position of `node` in its effect tree (0 = root), to find the same node after a rebuild. */
+export declare function nodeIndexInEffect(root: TransformNode, node: TransformNode | null): number;
+/** The node at `index` in an effect tree, as {@link nodeIndexInEffect} counts; the root when out of range. */
+export declare function nodeAtIndex(root: TransformNode, index: number): TransformNode;
+/** Builds the editor's scene on `options.engine`; call `start()` once the host is ready for callbacks. */
+export declare function createEditorSession(options: EditorSessionOptions): EditorSession;