@onerjs/smart-filters 8.25.0

package/src/command/command.ts

@@ -0,0 +1,59 @@
+/**
+ * Represents the owner of a command.
+ */
+export interface ICommandOwner {
+    /**
+     * The friendly name of the owner.
+     */
+    readonly name: string;
+
+    /**
+     * The blockType of the owner;
+     */
+    readonly blockType: string;
+}
+
+/**
+ * Represents a the action of a @see Command. This is what will be executed during a command buffer execution.
+ */
+export type CommandAction = () => void;
+
+/**
+ * Represents a command to execute.
+ *
+ * A command contains a function that will be executed at runtime by the smart filter.
+ *
+ * It also contains the owner of the command for debugging purposes.
+ */
+export type Command = {
+    /**
+     * The friendly name of the command.
+     */
+    readonly name: string;
+
+    /**
+     * The owner of the command.
+     * In practice, it will mostly be a block, the smart filter or a tool injecting commands.
+     */
+    readonly owner: ICommandOwner;
+
+    /**
+     * Defines the action to execute.
+     */
+    readonly action: CommandAction;
+};
+
+/**
+ * Creates a new command.
+ * @param name - The friendly name of the command
+ * @param owner - The owner of the command
+ * @param action - The action to execute when the command is executed
+ * @returns The new command
+ */
+export function CreateCommand(name: string, owner: ICommandOwner, action: CommandAction): Command {
+    return {
+        name,
+        owner,
+        action,
+    };
+}

package/src/command/commandBuffer.ts

@@ -0,0 +1,71 @@
+import type { Command } from "./command.js";
+
+/**
+ * Represents the action to run when calling `visitCommands` on a @see CommandBuffer.
+ */
+export type CommandsVisitor = (command: Command) => void;
+
+/**
+ * @see CommandsVisitor used to execute the commands of a @see CommandBuffer.
+ * @param command - The command to execute.
+ */
+function ExecuteCommandsVisitor(command: Command) {
+    command.action();
+}
+
+/**
+ * A command buffer is a list of commands to execute.
+ * This is used to store the list of tasks the current smart filter needs to execute.
+ */
+export class CommandBuffer {
+    private readonly _commands: Command[] = [];
+
+    /**
+     * Creates a new command buffer.
+     * @param args - the list of commands to add to the command buffer
+     */
+    constructor(...args: Command[]) {
+        for (const command of args) {
+            this.push(command);
+        }
+    }
+
+    /**
+     * Adds a command to the command buffer.
+     * @param command - the command to add
+     */
+    public push(command: Command) {
+        this._commands.push(command);
+    }
+
+    /**
+     * Clears the command buffer and empty the list of commands.
+     */
+    public clear() {
+        this._commands.length = 0;
+    }
+
+    /**
+     * Visits all the commands in the command buffer.
+     * @param commandVisitor - The action to execute on each command
+     */
+    public visitCommands(commandVisitor: CommandsVisitor): void {
+        for (const command of this._commands) {
+            commandVisitor(command);
+        }
+    }
+
+    /**
+     * Execute all the commands in the command buffer.
+     */
+    public execute() {
+        this.visitCommands(ExecuteCommandsVisitor);
+    }
+
+    /**
+     * Dispose the resources associated to the command buffer.
+     */
+    public dispose() {
+        this.clear();
+    }
+}

package/src/command/commandBufferDebugger.ts

@@ -0,0 +1,14 @@
+import { Logger } from "core/Misc/logger.js";
+import type { CommandBuffer } from "./commandBuffer.js";
+
+/**
+ * Logs all the commands associated to a command buffer.
+ * @param commandBuffer - The command buffer to log
+ */
+export function LogCommands(commandBuffer: Readonly<CommandBuffer>) {
+    Logger.Log("----- Command buffer commands -----");
+    commandBuffer.visitCommands((command) => {
+        Logger.Log(`  Owner: ${command.owner.blockType} (${command.owner.name}) - Command: ${command.name}`);
+    });
+    Logger.Log("-----------------------------------");
+}

package/src/command/index.ts

@@ -0,0 +1,7 @@
+export * from "./command.js";
+// Back compat for when camelCase was used
+export { CreateCommand as createCommand } from "./command.js";
+export * from "./commandBuffer.js";
+export { LogCommands } from "./commandBufferDebugger.js";
+// Back compat for when camelCase was used
+export { LogCommands as logCommands } from "./commandBufferDebugger.js";

package/src/connection/connectionPoint.ts

@@ -0,0 +1,205 @@
+import type { Nullable } from "core/types.js";
+import { ConnectionPointCompatibilityState, GetCompatibilityIssueMessage } from "./connectionPointCompatibilityState.js";
+import { ConnectionPointDirection } from "./connectionPointDirection.js";
+import type { BaseBlock } from "../blockFoundation/baseBlock.js";
+import type { ConnectionPointType, ConnectionPointValue } from "./connectionPointType.js";
+import type { StrongRef } from "../runtime/strongRef.js";
+
+/**
+ * This represents a strong reference to the data being passed through a connection point.
+ */
+export type RuntimeData<U extends ConnectionPointType> = StrongRef<ConnectionPointValue<U>>;
+
+/**
+ * This defines a connection point.
+ *
+ * A connection point is any input/output of a block.
+ * It can be linked to another connection point following some rules:
+ *  - The type of the connection point must be compatible with the other one.
+ *  - The direction of the connection point must be different from the other one.
+ *  - The connection cannot create a cycle in the list of blocks.
+ * The relationship is always 1:N for input:output
+ */
+export class ConnectionPoint<U extends ConnectionPointType = ConnectionPointType> {
+    /**
+     * The name of the connection point.
+     * This is used to identify the connection point inside a block.
+     */
+    public readonly name: string;
+
+    /**
+     * The type of the connection point (float, texture, etc.)
+     */
+    public readonly type: U;
+
+    /**
+     * The direction of the connection point (input or output)
+     */
+    public readonly direction: ConnectionPointDirection;
+
+    /**
+     * The smart filter block the connection point belongs to.
+     */
+    public readonly ownerBlock: BaseBlock;
+
+    /**
+     * User provided name for the connection point.
+     */
+    public displayName: Nullable<string> = null;
+
+    /**
+     * The @see RunTimeData used during the init phase to reference the result of the previous block.
+     * Those are only used for input connection points.
+     * The previous block are "pushing" this in during the init stage.
+     */
+    public runtimeData: Nullable<RuntimeData<U>> = null;
+
+    /**
+     * The default runtimeData used when no connection is made to the connection point.
+     */
+    public readonly defaultRuntimeData: Nullable<RuntimeData<U>> = null;
+
+    private _connectedTo: Nullable<ConnectionPoint<U>> = null;
+    private _endpoints: Array<ConnectionPoint<U>> = [];
+
+    /**
+     * Create a new connection point.
+     * @param name - The name the connection point has in the block
+     * @param ownerBlock - The block the connection point belongs to
+     * @param type - The type of the connection point
+     * @param direction - The direction of the connection point
+     * @param defaultRuntimeData - The default runtime data to use when no connection is made to the connection point
+     */
+    constructor(name: string, ownerBlock: BaseBlock, type: U, direction: ConnectionPointDirection, defaultRuntimeData: Nullable<RuntimeData<U>> = null) {
+        this.name = name;
+        this.ownerBlock = ownerBlock;
+        this.type = type;
+        this.direction = direction;
+        this.defaultRuntimeData = defaultRuntimeData;
+        this.runtimeData = defaultRuntimeData;
+    }
+
+    /**
+     * @returns The connection point this connection point is connected to.
+     * (the one on the other side of the connection)
+     * Only input connection points have a connected point which they received their value from.
+     * (Relation is always 1:N for input:output)
+     */
+    public get connectedTo(): Nullable<ConnectionPoint<U>> {
+        return this._connectedTo;
+    }
+
+    /**
+     * @returns The connection points this output connection point is connected to.
+     * (the ones on the other side of the connection)
+     * Only output connection points have a list of endpoints which they provide their value to.
+     * (Relation is always 1:N for input:output)
+     */
+    public get endpoints(): ReadonlyArray<ConnectionPoint<U>> {
+        return this._endpoints;
+    }
+
+    /**
+     * Gets a state indicating if the current point can be connected to another point
+     * @param other - defines the other connection point
+     * @returns the compatibility state
+     */
+    public checkCompatibilityState(other: ConnectionPoint<U>): ConnectionPointCompatibilityState {
+        // Only connects output to input
+        if (this.direction === ConnectionPointDirection.Input) {
+            return other.checkCompatibilityState(this);
+        }
+
+        // Check types
+        if (this.type !== other.type) {
+            return ConnectionPointCompatibilityState.TypeIncompatible;
+        }
+
+        // Check directions
+        if (this.direction === other.direction) {
+            return ConnectionPointCompatibilityState.DirectionIncompatible;
+        }
+
+        // Check hierarchy
+        if (other.ownerBlock.isAnAncestorOf(this.ownerBlock)) {
+            return ConnectionPointCompatibilityState.HierarchyIssue;
+        }
+
+        return ConnectionPointCompatibilityState.Compatible;
+    }
+
+    /**
+     * Checks if the connection point can be connected to another one.
+     * @param connectionPoint - The other connection point to check compatibility with
+     * @returns true if the connection point can be connected to the other one
+     */
+    public canConnectTo(connectionPoint: ConnectionPoint<U>) {
+        return this.checkCompatibilityState(connectionPoint) === ConnectionPointCompatibilityState.Compatible;
+    }
+
+    /**
+     * Connect this connection point to another one.
+     * @param other - The other connection point to connect to
+     * @throws if the connection point cannot be connected to the other one
+     */
+    public connectTo(other: ConnectionPoint<U>): void {
+        // Only connects output to input
+        if (this.direction === ConnectionPointDirection.Input) {
+            other.connectTo(this);
+            return;
+        }
+
+        // Check compatibility
+        const compatibility = this.checkCompatibilityState(other);
+        if (compatibility !== ConnectionPointCompatibilityState.Compatible) {
+            throw GetCompatibilityIssueMessage(compatibility);
+        }
+
+        // Adds the connection point to the list of endpoints
+        this._endpoints.push(other);
+        // Fill at the same time the connectedTo property of the other connection point
+        other._connectedTo = this;
+    }
+
+    /**
+     * Disconnects this point from one of his endpoint
+     * @param endpoint - defines the other connection point
+     */
+    public disconnectFrom(endpoint: ConnectionPoint<U>): void {
+        const index = this._endpoints.indexOf(endpoint);
+        if (index === -1) {
+            return;
+        }
+
+        // Remove the connection point from the list of endpoints
+        this._endpoints.splice(index, 1);
+
+        // Connections are double-linked - remove the reference back to this connection point from the one we just disconnected from
+        endpoint._connectedTo = null;
+        endpoint.runtimeData = endpoint.defaultRuntimeData;
+    }
+
+    /**
+     * Disconnects this point from all its endpoints.
+     */
+    public disconnectAllEndpoints(): void {
+        // Detach outputs
+        let endpoint: ConnectionPoint<U> | undefined;
+        while ((endpoint = this._endpoints[0])) {
+            this.disconnectFrom(endpoint);
+        }
+    }
+
+    /**
+     * Propagates the current runtime data to all endpoints.
+     */
+    public propagateRuntimeData(): void {
+        if (!this.runtimeData) {
+            this.runtimeData = {} as RuntimeData<U>;
+        }
+
+        for (const endpoint of this.endpoints) {
+            endpoint.runtimeData = this.runtimeData;
+        }
+    }
+}

package/src/connection/connectionPointCompatibilityState.ts

@@ -0,0 +1,31 @@
+/**
+ * Defines how compatible connection points are.
+ */
+export enum ConnectionPointCompatibilityState {
+    /** Points are compatibles */
+    Compatible,
+    /** Points are incompatible because of their types */
+    TypeIncompatible,
+    /** Points are incompatible because of their directions */
+    DirectionIncompatible,
+    /** Points are incompatible because they are in the same hierarchy **/
+    HierarchyIssue,
+}
+
+/**
+ * Gets a user friendly message for the given compatibility state.
+ * @param state - Defines the compatibility state
+ * @returns the message associated with a compatibility state.
+ */
+export function GetCompatibilityIssueMessage(state: ConnectionPointCompatibilityState): string {
+    switch (state) {
+        case ConnectionPointCompatibilityState.TypeIncompatible:
+            return "Cannot connect two different connection types";
+        case ConnectionPointCompatibilityState.DirectionIncompatible:
+            return "Cannot connect with the same direction";
+        case ConnectionPointCompatibilityState.HierarchyIssue:
+            return "Source block cannot be connected with one of its ancestors";
+        default:
+            return "";
+    }
+}

package/src/connection/connectionPointDirection.ts

@@ -0,0 +1,9 @@
+/**
+ * Defines the direction of a connection point.
+ */
+export enum ConnectionPointDirection {
+    /** Input */
+    Input = 0,
+    /** Output */
+    Output = 1,
+}

package/src/connection/connectionPointType.ts

@@ -0,0 +1,45 @@
+import type { ThinTexture } from "core/Materials/Textures/thinTexture.js";
+import type { IColor3Like, IColor4Like, IVector2Like } from "core/Maths/math.like.js";
+import type { Nullable } from "core/types.js";
+
+/**
+ * Defines the type of a connection point.
+ */
+export enum ConnectionPointType {
+    /** Float */
+    Float = 1,
+    /** Texture */
+    Texture = 2,
+    /** Color3 */
+    Color3 = 3,
+    /** Color4 */
+    Color4 = 4,
+    /** Boolean */
+    Boolean = 5,
+    /** Vector2 */
+    Vector2 = 6,
+}
+
+/**
+ * A union of all supported connection point types
+ */
+export type AllConnectionPointTypes =
+    | ConnectionPointType.Float
+    | ConnectionPointType.Texture
+    | ConnectionPointType.Color3
+    | ConnectionPointType.Color4
+    | ConnectionPointType.Boolean
+    | ConnectionPointType.Vector2;
+
+/**
+ * Retrieves the type of the value from the Connection point type.
+ */
+// prettier-ignore
+export type ConnectionPointValue<T extends ConnectionPointType = ConnectionPointType> =
+    T extends ConnectionPointType.Float ? number :
+    T extends ConnectionPointType.Texture ? Nullable<ThinTexture> :
+    T extends ConnectionPointType.Color3 ? IColor3Like :
+    T extends ConnectionPointType.Color4 ? IColor4Like :
+    T extends ConnectionPointType.Boolean ? boolean :
+    T extends ConnectionPointType.Vector2 ? IVector2Like :
+    never;

package/src/connection/connectionPointWithDefault.ts

@@ -0,0 +1,27 @@
+import type { BaseBlock } from "../blockFoundation/baseBlock.js";
+import { ConnectionPoint, type RuntimeData } from "./connectionPoint.js";
+import type { ConnectionPointDirection } from "./connectionPointDirection.js";
+import type { ConnectionPointType } from "./connectionPointType.js";
+
+/**
+ * A ConnectionPoint whose runtimeData is never null - if not hooked up to a connection, it will use a default value.
+ */
+export class ConnectionPointWithDefault<U extends ConnectionPointType = ConnectionPointType> extends ConnectionPoint<U> {
+    /**
+     * The runtime data for this ConnectionPoint - it will never be null - if not hooked up to a connection, it will use the default value.
+     */
+    public override runtimeData: RuntimeData<U>;
+
+    /**
+     * Create a new ConnectionPointWithDefault
+     * @param name - The name the connection point has in the block
+     * @param ownerBlock - The block the connection point belongs to
+     * @param type - The type of the connection point
+     * @param direction - The direction of the connection point
+     * @param runtimeData - The runtimeData to use for this connection point if no connection is made
+     */
+    constructor(name: string, ownerBlock: BaseBlock, type: U, direction: ConnectionPointDirection, runtimeData: RuntimeData<U>) {
+        super(name, ownerBlock, type, direction, runtimeData);
+        this.runtimeData = runtimeData;
+    }
+}

package/src/connection/index.ts

@@ -0,0 +1,8 @@
+export { ConnectionPointDirection } from "./connectionPointDirection.js";
+export { ConnectionPointType } from "./connectionPointType.js";
+export { type ConnectionPointValue } from "./connectionPointType.js";
+export { ConnectionPointCompatibilityState, GetCompatibilityIssueMessage } from "./connectionPointCompatibilityState.js";
+// Back compat for when camelCase was used
+export { GetCompatibilityIssueMessage as getCompatibilityIssueMessage } from "./connectionPointCompatibilityState.js";
+export { ConnectionPoint } from "./connectionPoint.js";
+export { type RuntimeData } from "./connectionPoint.js";

package/src/editorUtils/editableInPropertyPage.ts

@@ -0,0 +1,106 @@
+import type { Observable } from "core/Misc/observable.js";
+
+/**
+ * Enum defining the type of properties that can be edited in the property pages in the node editor
+ */
+export enum PropertyTypeForEdition {
+    /** property is a boolean */
+    Boolean,
+    /** property is a float */
+    Float,
+    /** property is a int */
+    Int,
+    /** property is a Vector2 */
+    Vector2,
+    /** property is a list of values */
+    List,
+}
+
+/**
+ * Interface that defines an option in a variable of type list
+ */
+export interface IEditablePropertyListOption {
+    /** label of the option */
+    label: string;
+    /** value of the option */
+    value: number | string;
+}
+
+/**
+ * Interface that defines the options available for an editable property
+ */
+export interface IEditablePropertyOption {
+    /** min value */
+    min?: number;
+    /** max value */
+    max?: number;
+    /** notifiers: indicates which actions to take when the property is changed */
+    notifiers?: {
+        /** the entity should be rebuilt */
+        rebuild?: boolean;
+        /** the preview should be updated */
+        update?: boolean;
+        /** the onPreviewCommandActivated observer of the preview manager should be triggered */
+        activatePreviewCommand?: boolean;
+        /** a callback to trigger */
+        callback?: () => boolean | undefined | void;
+        /** a callback to validate the property. Returns true if the property is ok, else false. If false, the rebuild/update/callback events won't be called */
+        onValidation?: (block: any, propertyName: string) => boolean;
+    };
+    /** a list of the options for a property of type list */
+    options?: IEditablePropertyListOption[] | Observable<IEditablePropertyListOption[]>;
+    /** whether the options' values should be treated as strings */
+    valuesAreStrings?: boolean;
+    /** If supplied, the sub property to read/write */
+    subPropertyName?: string;
+}
+
+/**
+ * Interface that describes an editable property
+ */
+export interface IPropertyDescriptionForEdition {
+    /** name of the property */
+    propertyName: string;
+    /** display name of the property */
+    displayName: string;
+    /** type of the property */
+    type: PropertyTypeForEdition;
+    /** group of the property - all properties with the same group value will be displayed in a specific section */
+    groupName: string;
+    /** options for the property */
+    options: IEditablePropertyOption;
+    /** name of the class that contains the property */
+    className: string;
+}
+
+/**
+ * Decorator that flags a property in a node block as being editable
+ * @param displayName - the display name of the property
+ * @param propertyType - the type of the property
+ * @param groupName - the group name of the property
+ * @param options - the options of the property
+ * @returns the decorator
+ */
+export function EditableInPropertyPage(
+    displayName: string,
+    propertyType: PropertyTypeForEdition = PropertyTypeForEdition.Boolean,
+    groupName: string = "PROPERTIES",
+    options?: IEditablePropertyOption
+) {
+    return (target: any, propertyKey: string) => {
+        let propStore: IPropertyDescriptionForEdition[] = target._propStore;
+        if (!propStore) {
+            propStore = [];
+            target._propStore = propStore;
+        }
+
+        propStore.push({
+            propertyName: propertyKey,
+            displayName: displayName,
+            type: propertyType,
+            groupName: groupName,
+            options: options ?? {},
+            className: target.constructor.name,
+        });
+    };
+}

package/src/editorUtils/index.ts

@@ -0,0 +1,3 @@
+export * from "./editableInPropertyPage.js";
+// Back compat for when camelCase was used
+export { EditableInPropertyPage as editableInPropertyPage } from "./editableInPropertyPage.js";

package/src/index.ts

@@ -0,0 +1,16 @@
+/* eslint-disable import/no-internal-modules */
+export * from "./command/index.js";
+export * from "./connection/index.js";
+export * from "./blockFoundation/index.js";
+export * from "./editorUtils/index.js";
+export * from "./optimization/index.js";
+export * from "./runtime/index.js";
+export * from "./serialization/index.js";
+export * from "./utils/index.js";
+
+export { type IDisposable } from "./IDisposable.js";
+export { SmartFilter, type InitializationData } from "./smartFilter.js";
+export * from "./version.js";
+
+// So that users of the Smart Filters core can easily modify the logger settings (e.g. to change the logging level)
+export { Logger } from "core/Misc/logger.js";