documentation for interfaces

Author: AgusDropOut

src/types/ast.ts

@@ -1,3 +1,9 @@
+// src/types/ast.ts
+
+/**
+ * Defines the available classifications for node instances within the engine.
+ * Every visual node placed on the canvas must map to one of these predefined registry types.
+ */
 export type NodeType = 
   | 'OUTPUT_FRAG' 
   | 'OUTPUT_VERT' 
@@ -27,14 +33,34 @@ export type NodeType =
   | 'BEAM_ENDPOINT'
   ;
 
+/**
+ * Specifies the supported GLSL data types used for mathematical evaluation and port connections.
+ */
 export type GLSLType = 'float' | 'vec2' | 'vec3' | 'vec4' | 'string';
 
+/**
+ * Represents an input or output connection point on a node instance.
+ * * @property id - The specific identifier for the port (e.g., 'color', 'uv_coords').
+ * @property type - The GLSL data type expected or emitted by this port.
+ * @property value - An optional constant value used if the input port has no active connection.
+ */
 export interface NodePort {
     id: string;
     type: GLSLType;
     value?: any;
 }
 
+/**
+ * Represents an active instance of a node placed within the visual editor.
+ * * @property id - The globally unique identifier for this specific node instance (e.g., 'noise-16843000').
+ * @property type - The overarching structural classification of the node.
+ * @property inputs - The array of available input ports and their current constant values.
+ * @property outputs - The array of available output ports.
+ * @property data - Optional arbitrary data required for specific node logic.
+ * @property isUniform - Flag indicating if this node instance should be compiled into a GLSL uniform.
+ * @property uniformName - The declared variable name used in the shader program if the node is a uniform.
+ * @property position - The physical X/Y coordinates of the node on the React Flow canvas, used for layout restoration.
+ */
 export interface ShaderNode {
     id: string;
     type: NodeType;
@@ -46,6 +72,14 @@ export interface ShaderNode {
     position?: { x: number; y: number };
 }
 
+/**
+ * Represents a directed structural link (wire) between an output port of one node and an input port of another.
+ * * @property id - The globally unique identifier for the connection wire.
+ * @property sourceNodeId - The instance ID of the node emitting data.
+ * @property sourcePortId - The specific port ID on the emitting node.
+ * @property targetNodeId - The instance ID of the node receiving data.
+ * @property targetPortId - The specific port ID on the receiving node.
+ */
 export interface ShaderConnection {
     id: string;
     sourceNodeId: string;
@@ -54,6 +88,12 @@ export interface ShaderConnection {
     targetPortId: string;
 }
 
+/**
+ * The root Abstract Syntax Tree (AST) structure encapsulating the entire visual logic.
+ * This is the primary data structure passed to the Compilers and Evaluators.
+ * * @property nodes - The complete collection of active node instances in the current workspace.
+ * @property connections - The collection of wires linking the node instances together.
+ */
 export interface ShaderGraph {
     nodes: ShaderNode[];
     connections: ShaderConnection[];

src/types/context.ts

@@ -5,31 +5,108 @@ import type * as THREE from 'three';
 import type { IWorkspaceExporter } from './export';
 import type { ShaderGraph } from './ast';
 
+/**
+ * Provides the core Three.js components required to initialize and render a 3D preview.
+ * * @property scene - The Three.js scene graph object.
+ * @property camera - The default perspective camera for the viewport.
+ * @property material - The shader material instance that will be updated by the AST.
+ */
 export interface RenderContext {
     scene: THREE.Scene;
     camera: THREE.PerspectiveCamera;
     material: THREE.ShaderMaterial;
 }
 
+/**
+ * Defines the lifecycle and rendering logic for a specific visual context in the 3D canvas.
+ */
 export interface IPreviewStrategy {
+    /**
+     * Called once when the preview canvas is mounted or the context is switched.
+     * * @param ctx - The rendering context containing the scene, camera, and material.
+     * @param settings - The current configuration settings for this context.
+     */
     init: (ctx: RenderContext, settings: Record<string, any>) => void;
+
+    /**
+     * Called every frame to animate and update the preview logic.
+     * * @param time - The elapsed time in milliseconds.
+     * @param settings - The current configuration settings for this context.
+     * @param graph - Optional reference to the current AST for real-time mathematical evaluation.
+     */
     update: (time: number, settings: Record<string, any>, graph?: ShaderGraph) => void;
+
+    /**
+     * Called when a configuration parameter is modified in the context's SettingsPanel.
+     * * @param settings - The updated configuration settings object.
+     */
     onSettingsChange: (settings: Record<string, any>) => void;
+
+    /**
+     * Called to safely dispose of geometry, materials, and helpers to prevent memory leaks.
+     */
     dispose: () => void;
 }
 
+/**
+ * Represents an isolated environment within the engine (e.g., Material, Trail, Beam).
+ * Encapsulates context-specific logic, UI, and rendering rules to maintain extensibility.
+ */
 export interface IProjectContext {
+    /** * @property id - Unique identifier for the context. 
+     */
     id: string;
+
+    /** * @property name - Display name used in the user interface. 
+     */
     name: string;
+
+    /** * @property requiresGlobalMaterial - Indicates if this context relies on the compiled shader from the global MATERIAL context. 
+     */
     requiresGlobalMaterial?: boolean;
+
+    /**
+     * Determines if the current settings require an orthographic camera projection.
+     * * @param settings - The current configuration settings for the context.
+     * @returns True if an orthographic camera should be used, false otherwise.
+     */
     isOrthographic?: (settings: Record<string, any>) => boolean;
+
+    /**
+     * Generates the default workspace layout.
+     * * @returns An array of initial React Flow nodes.
+     */
     getInitialNodes: () => Node[];
+
+    /**
+     * Evaluates whether a specific AST node type is permitted within this context.
+     * * @param nodeType - The string identifier of the node type to check.
+     * @returns True if the node is permitted, false otherwise.
+     */
     isNodeAllowed: (nodeType: string) => boolean;
+
+    /** * @property SettingsPanel - React component rendering the specific configuration controls for this context. 
+     */
     SettingsPanel: React.FC<{
         settings: Record<string, any>;
         onSettingChange: (key: string, value: any) => void;
     }>;
+
+    /**
+     * Instantiates the Three.js rendering strategy for the 3D preview.
+     * * @returns A new instance of the preview strategy.
+     */
     createPreviewStrategy: () => IPreviewStrategy;
+
+    /**
+     * Provides the fallback configuration values for the context settings.
+     * * @returns A dictionary of default settings.
+     */
     getDefaultSettings: () => Record<string, any>; 
+
+    /**
+     * Provides the exporter responsible for converting the AST into game-ready metadata.
+     * * @returns The configured workspace exporter or null if exporting is not supported.
+     */
     getExporter: () => IWorkspaceExporter | null; 
 }

src/types/export.ts

@@ -1,13 +1,24 @@
 // src/types/export.ts
 import type { ShaderGraph } from './ast';
 
+/**
+ * Defines the runtime origin for a shader uniform within the target game engine.
+ */
 export type UniformSource = 'GAME_TIME' | 'CUSTOM' | 'TEXTURE' | 'LIGHTMAP';
 
+/**
+ * Represents the metadata required by the game engine to bind a specific uniform.
+ * * @property type - The GLSL data type (e.g., 'float', 'vec3').
+ * @property source - The origin classification for the uniform data.
+ */
 export interface UniformMeta {
     type: string;
     source: UniformSource;
 }
 
+/**
+ * Defines the low-level graphics pipeline state required to render the material.
+ */
 export interface RenderState {
     blend_mode: 'OPAQUE' | 'TRANSLUCENT' | 'ADDITIVE' | 'MULTIPLY';
     cull_mode: 'BACK' | 'FRONT' | 'NONE';
@@ -16,28 +27,59 @@ export interface RenderState {
     alpha_cutoff: number; 
 }
 
+/**
+ * The standard JSON schema expected by the target game engine's metadata parser.
+ */
 export interface CosmosMetadata {
     name: string;
     vertex_format: string;
     render_state: RenderState;
     uniforms: Record<string, UniformMeta>;
 }
 
+/**
+ * Configuration parameters provided to the metadata extraction process.
+ */
 export interface ExportConfig {
     name: string;
     isTranslucent: boolean;
 }
 
+/**
+ * Contract for services that parse a ShaderGraph into valid engine metadata.
+ */
 export interface IMetadataExtractor {
+    /**
+     * Extracts metadata from a shader graph based on the provided configuration.
+     * * @param graph - The logical AST representing the visual shader.
+     * @param config - Export configuration parameters.
+     * @returns The generated Cosmos metadata schema.
+     */
     extract(graph: ShaderGraph, config: ExportConfig): CosmosMetadata;
 }
 
+/**
+ * Represents a discrete file generated during the export process.
+ * * @property fileName - The target name of the file including extension.
+ * @property fileContent - The raw string payload or binary blob.
+ * @property mimeType - The MIME classification for the file payload.
+ */
 export interface ExportResult {
     fileName: string;
     fileContent: string | Blob;
     mimeType: string;
 }
 
+/**
+ * Contract for context-specific exporters that compile ASTs into downloadable game assets.
+ */
 export interface IWorkspaceExporter {
+    /**
+     * Compiles the AST into an array of downloadable files.
+     * * @param graph - The logical AST representing the visual shader.
+     * @param settings - The current configuration settings for the context.
+     * @param globalSettings - Application-wide settings including namespace and project name.
+     * @returns A promise resolving to an array of export results.
+     */
     export(graph: ShaderGraph, settings: Record<string, any>, globalSettings: { namespace: string; projectName: string }): Promise<ExportResult[]>;
 }

src/types/node-def.ts

@@ -2,17 +2,37 @@
 import type { NodeType, GLSLType } from './ast';
 import type { NodeStrategy } from './compiler';
 
+/**
+ * Defines the user interface control rendered on a node for manipulating constant input values.
+ * * @property id - Optional identifier for the control. Defaults to the input port ID if omitted.
+ * @property label - The text label displayed next to the control in the UI.
+ * @property type - The visual representation of the control (e.g., a slider, a color picker, or a dropdown).
+ * @property min - The minimum allowed value (applicable to 'slider' and 'number' types).
+ * @property max - The maximum allowed value (applicable to 'slider' and 'number' types).
+ * @property step - The incremental step value for adjustments (applicable to 'slider' and 'number' types).
+ * @property options - An array of available string choices (applicable only to 'select' types).
+ */
 export interface NodeControl {
   id?: string;
   label: string;
-  type: 'slider' | 'color-rgb' | 'none'| 'select' | 'number';
+  type: 'slider' | 'color-rgb' | 'none' | 'select' | 'number';
   min?: number;
   max?: number;
   step?: number;
   options?: string[];
 }
 
-
+/**
+ * The structural blueprint used to register a mathematical or functional node within the engine.
+ * Every node available in the editor must have a corresponding NodeDefinition.
+ * * @property type - The unique AST identifier for the node (e.g., 'MATH_BINARY', 'TIME').
+ * @property label - The human-readable display name rendered on the node's header.
+ * @property color - The hexadecimal color code used to style the node's header background.
+ * @property inputs - An array defining the input ports, their expected data types, default values, and optional UI controls.
+ * @property outputs - An array defining the output ports and the mathematical data types they emit.
+ * @property strategy - The compilation logic used to translate this node into GLSL strings and executable TypeScript math.
+ * @property canHavePreview - Indicates if the node supports rendering an isolated 2D GLSL preview canvas within its body.
+ */
 export interface NodeDefinition {
   type: NodeType;
   label: string;