@babylonjs/shared-ui-components 9.15.0 → 9.16.0

package/projects/overrideManager.d.ts

@@ -0,0 +1,176 @@
+import { type Scene } from "@babylonjs/core/scene.js";
+import { Observable, type Observer } from "@babylonjs/core/Misc/observable.js";
+import { type IOverrideEntry, type OverrideTargetType } from "./overrideEntry.js";
+/**
+ * Stateful handle for a scene's property override registry.
+ *
+ * Override behavior is exposed through module-level functions rather than
+ * class methods so callers can import only the operations they need.
+ *
+ * Overrides are property diffs applied to scene objects identified by name.
+ * They persist across reloads and are typically saved alongside a project
+ * file. The override manager is fully independent of any other scene
+ * subsystem (SmartAssetManager, loaders, etc.) — it works with any object
+ * in the scene's standard collections (meshes, materials, lights, …)
+ * regardless of how that object was created.
+ *
+ * When multiple objects share a name (e.g. two materials both called
+ * "Default" loaded from different glTFs), {@link IOverrideEntry.targetIndex}
+ * disambiguates: it stores the object's position among same-named siblings
+ * at capture time and is used to pick the correct one at apply time.
+ *
+ * @example
+ * ```typescript
+ * AddOverride(scene, {
+ *     targetType: "materials",
+ *     targetName: "canPaint",
+ *     targetIndex: 0,
+ *     propertyPath: "albedoColor",
+ *     value: [1, 0, 0],
+ * });
+ * ```
+ */
+export type OverrideManager = {
+    /**
+     * The scene this manager is attached to.
+     */
+    readonly scene: Scene;
+    /**
+     * Fires whenever the override registry or applied state changes.
+     */
+    readonly onChangedObservable: Observable<void>;
+};
+/**
+ * Returns the OverrideManager attached to the given scene, creating and
+ * attaching one if none exists.
+ * @param scene - The scene to look up or attach a manager to.
+ * @returns The existing or newly created OverrideManager.
+ */
+export declare function GetOverrideManager(scene: Scene): OverrideManager;
+/**
+ * Adds an observer that is notified whenever an OverrideManager is created.
+ * @param callback - The callback to invoke with each newly created manager.
+ * @returns The observer registration.
+ */
+export declare function AddOverrideManagerCreatedObserver(callback: (manager: OverrideManager) => void): Observer<OverrideManager>;
+/**
+ * Options for {@link AddOverride}.
+ */
+export type AddOverrideOptions = {
+    /**
+     * If the `originalValue` field is present, the override is recorded *without*
+     * re-applying it (the caller is presumed to have already mutated the entity)
+     * and the field's content is captured as the property's pre-override
+     * "original" so {@link RemoveOverride} can restore it later.
+     *
+     * Inspector-driven edits use this: by the time `onPropertyChanged` fires,
+     * the binding has already written the new value, but it still has the prior
+     * value in hand. Without this seeding path, an override created via
+     * Inspector could never be reverted (the manager would have no record of
+     * the pre-edit value).
+     *
+     * If the field is absent, the override is applied normally and the original
+     * is captured by reading the property's current value on first apply.
+     */
+    readonly originalValue?: unknown;
+};
+/**
+ * Adds an override entry and immediately applies it.
+ * If an override with the same target coordinates already exists, it is replaced.
+ *
+ * When the caller has already mutated the target (e.g. an Inspector edit),
+ * pass `{ originalValue }` containing the property's prior value — this seeds
+ * the original-value map (so {@link RemoveOverride} can restore it) and skips
+ * the redundant apply step.
+ * @param scene - The scene whose override registry to update.
+ * @param entry - The override to add.
+ * @param options - Optional behavior modifiers; see {@link AddOverrideOptions}.
+ */
+export declare function AddOverride(scene: Scene, entry: IOverrideEntry, options?: AddOverrideOptions): void;
+/**
+ * Removes a single override matching the given coordinates. Restores the
+ * original value if one was captured.
+ * @param scene - The scene whose override registry to update.
+ * @param targetType - The target type.
+ * @param targetName - The target object name.
+ * @param targetIndex - The target index among same-named siblings.
+ * @param propertyPath - The property path to un-override.
+ * @returns True if an override was removed.
+ */
+export declare function RemoveOverride(scene: Scene, targetType: OverrideTargetType, targetName: string, targetIndex: number, propertyPath: string): boolean;
+/**
+ * Returns all overrides currently registered with the scene.
+ * @param scene - The scene whose override registry to read.
+ * @returns A read-only array of override entries.
+ */
+export declare function GetOverrides(scene: Scene): readonly IOverrideEntry[];
+/**
+ * Removes all overrides, optionally restoring original values.
+ * @param scene - The scene whose override registry to clear.
+ * @param restoreOriginals - If true, restores all captured original values.
+ */
+export declare function ClearOverrides(scene: Scene, restoreOriginals?: boolean): void;
+/**
+ * Updates the target coordinates on the override matching a specific (type,
+ * old-name, old-index) so it follows an entity rename. Used by capture services
+ * to keep overrides attached to a specific object after the user renames it.
+ *
+ * Only the override at the exact `(targetType, oldName, oldIndex)` slot is
+ * updated, so other same-named siblings keep their own overrides untouched.
+ *
+ * @param scene - The scene whose override registry to update.
+ * @param targetType - The target type.
+ * @param oldName - The previous name of the renamed entity.
+ * @param oldIndex - The previous index of the renamed entity among same-named siblings.
+ * @param newName - The new name of the renamed entity.
+ * @param newIndex - The new index of the renamed entity among same-named siblings.
+ */
+export declare function RenameOverrideTarget(scene: Scene, targetType: OverrideTargetType, oldName: string, oldIndex: number, newName: string, newIndex: number): void;
+/**
+ * Rewrites override *values* that reference an entity by name when that entity
+ * has been renamed. Mirrors {@link RenameOverrideTarget} but operates on the
+ * `value` field rather than the `targetName` field, so overrides whose value
+ * is `"ref:oldName"` (material/light/camera references) or `"texture:oldName"`
+ * (non-SmartAsset texture references) follow the rename instead of silently
+ * pointing at a non-existent entity.
+ *
+ * SmartAsset texture references (`"samTexture:<key>"`) are unaffected because
+ * the SmartAsset key is decoupled from the texture's runtime `name` field.
+ *
+ * @param scene - The scene whose override registry to update.
+ * @param valueScheme - Which encoded-reference prefix to rewrite: `"ref"` for
+ * material/light/camera references, `"texture"` for non-SAM textures.
+ * @param oldName - The previous name embedded in the reference.
+ * @param newName - The new name embedded in the reference.
+ */
+export declare function RenameOverrideValueReferences(scene: Scene, valueScheme: "ref" | "texture", oldName: string, newName: string): void;
+/**
+ * Applies all overrides to their current targets in the scene.
+ *
+ * Call this after any scene mutation that might have invalidated previously
+ * applied state (asset reload, object recreation, project load). The override
+ * manager does not auto-subscribe to other scene subsystems — coordination is
+ * the caller's responsibility, which keeps the override system independent.
+ * @param scene - The scene whose overrides to apply.
+ */
+export declare function ApplyAllOverrides(scene: Scene): void;
+/**
+ * Serializes all overrides to a JSON-compatible array.
+ * The on-disk shape is identical to the in-memory `IOverrideEntry`.
+ * @param scene - The scene whose overrides to serialize.
+ * @returns An array of override entries (shallow copies).
+ */
+export declare function SerializeOverrides(scene: Scene): IOverrideEntry[];
+/**
+ * Loads overrides from a serialized array and applies them.
+ * @param scene - The scene whose override registry to populate.
+ * @param data - Array of override entries.
+ */
+export declare function DeserializeAndApplyOverrides(scene: Scene, data: IOverrideEntry[]): void;
+/**
+ * Disposes the manager, clearing all overrides and detaching it from its scene.
+ * Safe to call multiple times; subsequent calls are no-ops. Automatically invoked when the
+ * owning scene is disposed.
+ * @param manager - The override manager state.
+ */
+export declare function DisposeOverrideManager(manager: OverrideManager): void;