@nice2dev/game-engine 1.0.2 → 1.0.3

package/dist/types/scripting/ScriptAST.d.ts

@@ -0,0 +1,312 @@
+export type ASTDataType = 'void' | 'bool' | 'int' | 'float' | 'string' | 'vector2' | 'vector3' | 'color' | 'entity' | 'array' | 'dictionary' | 'any' | 'custom';
+export interface ASTTypeInfo {
+    type: ASTDataType;
+    /** For array/dictionary/custom types */
+    genericArgs?: ASTTypeInfo[];
+    /** Custom type name for 'custom' type */
+    customName?: string;
+    /** Whether the type is nullable */
+    nullable?: boolean;
+}
+export type ASTExpression = ASTLiteral | ASTIdentifier | ASTBinaryOp | ASTUnaryOp | ASTCall | ASTMethodCall | ASTPropertyAccess | ASTIndexAccess | ASTConditional | ASTArrayLiteral | ASTDictionaryLiteral | ASTCast | ASTLambda | ASTNew;
+export interface ASTNodeBase {
+    kind: string;
+    /** Source node ID for debugging/mapping */
+    sourceNodeId?: string;
+    /** Line comment to emit */
+    comment?: string;
+}
+export interface ASTLiteral extends ASTNodeBase {
+    kind: 'literal';
+    valueType: ASTDataType;
+    value: unknown;
+}
+export interface ASTIdentifier extends ASTNodeBase {
+    kind: 'identifier';
+    name: string;
+    dataType?: ASTTypeInfo;
+}
+export interface ASTBinaryOp extends ASTNodeBase {
+    kind: 'binaryOp';
+    operator: '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '<' | '>' | '<=' | '>=' | '&&' | '||' | '&' | '|' | '^' | '<<' | '>>';
+    left: ASTExpression;
+    right: ASTExpression;
+}
+export interface ASTUnaryOp extends ASTNodeBase {
+    kind: 'unaryOp';
+    operator: '!' | '-' | '~' | '++' | '--';
+    operand: ASTExpression;
+    prefix: boolean;
+}
+export interface ASTCall extends ASTNodeBase {
+    kind: 'call';
+    callee: string;
+    args: ASTExpression[];
+    /** Generic type arguments for the call */
+    typeArgs?: ASTTypeInfo[];
+}
+export interface ASTMethodCall extends ASTNodeBase {
+    kind: 'methodCall';
+    object: ASTExpression;
+    method: string;
+    args: ASTExpression[];
+}
+export interface ASTPropertyAccess extends ASTNodeBase {
+    kind: 'propertyAccess';
+    object: ASTExpression;
+    property: string;
+}
+export interface ASTIndexAccess extends ASTNodeBase {
+    kind: 'indexAccess';
+    object: ASTExpression;
+    index: ASTExpression;
+}
+export interface ASTConditional extends ASTNodeBase {
+    kind: 'conditional';
+    condition: ASTExpression;
+    ifTrue: ASTExpression;
+    ifFalse: ASTExpression;
+}
+export interface ASTArrayLiteral extends ASTNodeBase {
+    kind: 'arrayLiteral';
+    elements: ASTExpression[];
+    elementType?: ASTTypeInfo;
+}
+export interface ASTDictionaryLiteral extends ASTNodeBase {
+    kind: 'dictionaryLiteral';
+    entries: Array<{
+        key: ASTExpression;
+        value: ASTExpression;
+    }>;
+}
+export interface ASTCast extends ASTNodeBase {
+    kind: 'cast';
+    expression: ASTExpression;
+    targetType: ASTTypeInfo;
+}
+export interface ASTLambda extends ASTNodeBase {
+    kind: 'lambda';
+    params: ASTParameter[];
+    body: ASTStatement[] | ASTExpression;
+    returnType?: ASTTypeInfo;
+}
+export interface ASTNew extends ASTNodeBase {
+    kind: 'new';
+    typeName: string;
+    args: ASTExpression[];
+}
+export type ASTStatement = ASTVarDecl | ASTAssignment | ASTIf | ASTWhile | ASTFor | ASTForEach | ASTReturn | ASTBreak | ASTContinue | ASTExpressionStatement | ASTBlock | ASTSwitch | ASTTry | ASTYield | ASTAwait | ASTMatch | ASTSignalEmit;
+export interface ASTVarDecl extends ASTNodeBase {
+    kind: 'varDecl';
+    name: string;
+    varType?: ASTTypeInfo;
+    initializer?: ASTExpression;
+    isConst?: boolean;
+    /** Export for Godot @export, [SerializeField] for Unity */
+    isExported?: boolean;
+}
+export interface ASTAssignment extends ASTNodeBase {
+    kind: 'assignment';
+    target: ASTExpression;
+    operator: '=' | '+=' | '-=' | '*=' | '/=' | '%=';
+    value: ASTExpression;
+}
+export interface ASTIf extends ASTNodeBase {
+    kind: 'if';
+    condition: ASTExpression;
+    thenBranch: ASTStatement[];
+    elseBranch?: ASTStatement[];
+    elseIfs?: Array<{
+        condition: ASTExpression;
+        body: ASTStatement[];
+    }>;
+}
+export interface ASTWhile extends ASTNodeBase {
+    kind: 'while';
+    condition: ASTExpression;
+    body: ASTStatement[];
+}
+export interface ASTFor extends ASTNodeBase {
+    kind: 'for';
+    init?: ASTStatement;
+    condition?: ASTExpression;
+    update?: ASTExpression;
+    body: ASTStatement[];
+}
+export interface ASTForEach extends ASTNodeBase {
+    kind: 'forEach';
+    variable: string;
+    iterable: ASTExpression;
+    body: ASTStatement[];
+}
+export interface ASTReturn extends ASTNodeBase {
+    kind: 'return';
+    value?: ASTExpression;
+}
+export interface ASTBreak extends ASTNodeBase {
+    kind: 'break';
+}
+export interface ASTContinue extends ASTNodeBase {
+    kind: 'continue';
+}
+export interface ASTExpressionStatement extends ASTNodeBase {
+    kind: 'expressionStatement';
+    expression: ASTExpression;
+}
+export interface ASTBlock extends ASTNodeBase {
+    kind: 'block';
+    statements: ASTStatement[];
+}
+export interface ASTSwitch extends ASTNodeBase {
+    kind: 'switch';
+    expression: ASTExpression;
+    cases: Array<{
+        value: ASTExpression;
+        body: ASTStatement[];
+    }>;
+    defaultCase?: ASTStatement[];
+}
+export interface ASTTry extends ASTNodeBase {
+    kind: 'try';
+    tryBlock: ASTStatement[];
+    catchBlocks?: Array<{
+        errorType?: string;
+        errorVar?: string;
+        body: ASTStatement[];
+    }>;
+    finallyBlock?: ASTStatement[];
+}
+export interface ASTYield extends ASTNodeBase {
+    kind: 'yield';
+    value?: ASTExpression;
+}
+export interface ASTAwait extends ASTNodeBase {
+    kind: 'await';
+    expression: ASTExpression;
+}
+export interface ASTMatch extends ASTNodeBase {
+    kind: 'match';
+    expression: ASTExpression;
+    arms: Array<{
+        pattern: ASTExpression;
+        guard?: ASTExpression;
+        body: ASTStatement[];
+    }>;
+}
+export interface ASTSignalEmit extends ASTNodeBase {
+    kind: 'signalEmit';
+    signalName: string;
+    args: ASTExpression[];
+}
+export interface ASTParameter {
+    name: string;
+    paramType: ASTTypeInfo;
+    defaultValue?: ASTExpression;
+    /** Variadic parameter (...args) */
+    isVariadic?: boolean;
+}
+export interface ASTFunction extends ASTNodeBase {
+    kind: 'function';
+    name: string;
+    params: ASTParameter[];
+    returnType: ASTTypeInfo;
+    body: ASTStatement[];
+    isAsync?: boolean;
+    isStatic?: boolean;
+    visibility?: 'public' | 'private' | 'protected' | 'internal';
+    /** Virtual/override for inheritance */
+    isVirtual?: boolean;
+    isOverride?: boolean;
+    isAbstract?: boolean;
+    /** Coroutine for Unity/Godot yields */
+    isCoroutine?: boolean;
+    /** Attributes/decorators */
+    attributes?: string[];
+}
+export interface ASTField {
+    name: string;
+    fieldType: ASTTypeInfo;
+    initializer?: ASTExpression;
+    visibility?: 'public' | 'private' | 'protected' | 'internal';
+    isStatic?: boolean;
+    isConst?: boolean;
+    isReadonly?: boolean;
+    isExported?: boolean;
+    attributes?: string[];
+    comment?: string;
+}
+export interface ASTProperty {
+    name: string;
+    propType: ASTTypeInfo;
+    getter?: ASTStatement[];
+    setter?: ASTStatement[];
+    visibility?: 'public' | 'private' | 'protected' | 'internal';
+    isStatic?: boolean;
+    attributes?: string[];
+}
+export interface ASTSignalDef {
+    name: string;
+    params: ASTParameter[];
+}
+export interface ASTEnumMember {
+    name: string;
+    value?: number | string;
+}
+export interface ASTEnum {
+    name: string;
+    members: ASTEnumMember[];
+}
+export interface ASTClass extends ASTNodeBase {
+    kind: 'class';
+    name: string;
+    baseClass?: string;
+    interfaces?: string[];
+    fields: ASTField[];
+    properties?: ASTProperty[];
+    methods: ASTFunction[];
+    signals?: ASTSignalDef[];
+    enums?: ASTEnum[];
+    nestedClasses?: ASTClass[];
+    isAbstract?: boolean;
+    isSealed?: boolean;
+    isPartial?: boolean;
+    attributes?: string[];
+    comment?: string;
+}
+export interface ASTImport {
+    module: string;
+    /** Named imports */
+    names?: string[];
+    /** Import all: import * as X */
+    alias?: string;
+    /** Default import */
+    defaultImport?: string;
+}
+export interface ASTScript {
+    /** Script/file name without extension */
+    name: string;
+    imports: ASTImport[];
+    classes: ASTClass[];
+    /** Top-level functions (for languages that support it) */
+    functions?: ASTFunction[];
+    /** Top-level statements (for scripting languages) */
+    topLevel?: ASTStatement[];
+    /** Module-level enums */
+    enums?: ASTEnum[];
+    /** File header comment */
+    headerComment?: string;
+}
+export declare function createLiteral(value: unknown, valueType?: ASTDataType): ASTLiteral;
+export declare function createIdentifier(name: string, dataType?: ASTTypeInfo): ASTIdentifier;
+export declare function createBinaryOp(operator: ASTBinaryOp['operator'], left: ASTExpression, right: ASTExpression): ASTBinaryOp;
+export declare function createCall(callee: string, args: ASTExpression[]): ASTCall;
+export declare function createMethodCall(object: ASTExpression, method: string, args: ASTExpression[]): ASTMethodCall;
+export declare function createPropertyAccess(object: ASTExpression, property: string): ASTPropertyAccess;
+export declare function createAssignment(target: ASTExpression, value: ASTExpression, operator?: ASTAssignment['operator']): ASTAssignment;
+export declare function createVarDecl(name: string, varType?: ASTTypeInfo, initializer?: ASTExpression): ASTVarDecl;
+export declare function createIf(condition: ASTExpression, thenBranch: ASTStatement[], elseBranch?: ASTStatement[]): ASTIf;
+export declare function createReturn(value?: ASTExpression): ASTReturn;
+export declare function createExprStatement(expression: ASTExpression): ASTExpressionStatement;
+export declare function createType(type: ASTDataType, nullable?: boolean): ASTTypeInfo;
+export declare function createArrayType(elementType: ASTTypeInfo): ASTTypeInfo;
+export declare function createCustomType(name: string, nullable?: boolean): ASTTypeInfo;

package/dist/types/scripting/VisualScripting2.d.ts

@@ -0,0 +1,353 @@
+/**
+ * @file VisualScripting2.ts
+ * @description Visual Scripting 2.0 — Node-based Scripting System with Debugger
+ * PRO-1.4: Professional Editor Features
+ *
+ * Features:
+ * - Node-based visual programming (like Unreal Blueprints)
+ * - Real-time debugger with breakpoints
+ * - Step-by-step execution
+ * - Watch expressions
+ * - Variable inspection
+ * - Call stack visualization
+ * - Live preview in editor
+ */
+import type { EntityId, Vec2 } from '../core/types';
+import type { EventBus } from '../core/EventBus';
+/** Extended data types for visual scripting */
+export type VSDataType = 'flow' | 'bool' | 'int' | 'float' | 'string' | 'vec2' | 'vec3' | 'color' | 'entity' | 'component' | 'asset' | 'array' | 'map' | 'struct' | 'object' | 'enum' | 'delegate' | 'wildcard';
+/** Type color mapping for visual identification */
+export declare const VS_TYPE_COLORS: Record<VSDataType, string>;
+export interface VSPort {
+    id: string;
+    name: string;
+    direction: 'input' | 'output';
+    type: VSDataType;
+    subType?: VSDataType;
+    structDef?: string;
+    enumDef?: string;
+    defaultValue?: unknown;
+    description?: string;
+    /** Multiple connections allowed (outputs only) */
+    multi?: boolean;
+    /** Optional execution flow port */
+    optional?: boolean;
+    /** Hidden in compact mode */
+    advanced?: boolean;
+}
+export type VSNodeCategory = 'event' | 'flow' | 'math' | 'logic' | 'string' | 'array' | 'entity' | 'component' | 'physics' | 'audio' | 'animation' | 'input' | 'ui' | 'time' | 'transform' | 'debug' | 'variable' | 'function' | 'macro' | 'comment' | 'reroute' | 'custom';
+export interface VSNodeDefinition {
+    type: string;
+    name: string;
+    category: VSNodeCategory;
+    description: string;
+    keywords?: string[];
+    icon?: string;
+    color?: string;
+    ports: VSPort[];
+    /** Is this a pure node (no side effects, can be cached)? */
+    pure?: boolean;
+    /** Is this a latent node (async, takes multiple frames)? */
+    latent?: boolean;
+    /** Is this node deprecated? */
+    deprecated?: boolean;
+    /** Compact display (single-line) */
+    compact?: boolean;
+    /** Minimum required license tier */
+    licenseTier?: 'free' | 'pro' | 'enterprise';
+    /** Execute function */
+    execute: (inputs: Record<string, unknown>, context: VSExecutionContext) => Record<string, unknown> | Promise<Record<string, unknown>> | void;
+    /** Validate node configuration */
+    validate?: (node: VSNodeInstance) => VSValidationResult[];
+    /** Custom rendering callback */
+    renderCustom?: (node: VSNodeInstance, ctx: CanvasRenderingContext2D) => void;
+}
+export interface VSValidationResult {
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    portId?: string;
+}
+export interface VSNodeInstance {
+    id: string;
+    type: string;
+    position: Vec2;
+    size?: Vec2;
+    /** Input port values (overrides defaults) */
+    inputs: Record<string, unknown>;
+    /** Cached output values */
+    outputs: Record<string, unknown>;
+    /** User comment */
+    comment?: string;
+    /** Is node collapsed? */
+    collapsed?: boolean;
+    /** Is node disabled? */
+    disabled?: boolean;
+    /** Breakpoint set on this node */
+    breakpoint?: VSBreakpoint;
+    /** Custom data for specific node types */
+    customData?: Record<string, unknown>;
+}
+export interface VSConnection {
+    id: string;
+    fromNode: string;
+    fromPort: string;
+    toNode: string;
+    toPort: string;
+    /** Connection style */
+    style?: 'bezier' | 'linear' | 'stepped';
+    /** Reroute points for wire organization */
+    reroutePoints?: Vec2[];
+}
+export interface VSVariable {
+    id: string;
+    name: string;
+    type: VSDataType;
+    subType?: VSDataType;
+    structDef?: string;
+    enumDef?: string;
+    value: unknown;
+    defaultValue: unknown;
+    /** Variable scope */
+    scope: 'local' | 'graph' | 'instance' | 'global';
+    /** Is this variable exposed to editor? */
+    exposed?: boolean;
+    /** Category for organization */
+    category?: string;
+    /** Description */
+    description?: string;
+    /** Replicated in multiplayer */
+    replicated?: boolean;
+    /** Save in game save */
+    savedGame?: boolean;
+}
+export interface VSFunction {
+    id: string;
+    name: string;
+    description?: string;
+    category?: string;
+    /** Input parameters */
+    inputs: VSPort[];
+    /** Output values */
+    outputs: VSPort[];
+    /** Local variables */
+    localVariables: VSVariable[];
+    /** Is this a pure function? */
+    pure?: boolean;
+    /** Function graph */
+    graph: VSGraph;
+}
+export interface VSMacro {
+    id: string;
+    name: string;
+    description?: string;
+    /** Input tunnels */
+    inputs: VSPort[];
+    /** Output tunnels */
+    outputs: VSPort[];
+    /** Contained graph */
+    graph: VSGraph;
+    /** Instance color */
+    color?: string;
+}
+export interface VSGraph {
+    id: string;
+    name: string;
+    description?: string;
+    nodes: VSNodeInstance[];
+    connections: VSConnection[];
+    variables: VSVariable[];
+    functions: VSFunction[];
+    macros: VSMacro[];
+    /** Graph-level parameters (for subgraph use) */
+    parameters: VSPort[];
+    /** Graph type */
+    graphType: 'blueprint' | 'function' | 'macro' | 'animgraph' | 'statemachine';
+    /** Parent entity/component this graph is attached to */
+    parentEntity?: EntityId;
+    parentComponent?: string;
+    /** Metadata */
+    metadata?: {
+        author?: string;
+        version?: string;
+        created?: number;
+        modified?: number;
+        tags?: string[];
+    };
+}
+export interface VSStructDefinition {
+    name: string;
+    description?: string;
+    fields: Array<{
+        name: string;
+        type: VSDataType;
+        defaultValue?: unknown;
+    }>;
+}
+export interface VSEnumDefinition {
+    name: string;
+    description?: string;
+    values: Array<{
+        name: string;
+        displayName?: string;
+        value?: number;
+    }>;
+}
+export interface VSExecutionContext {
+    /** Current entity */
+    entityId: EntityId | null;
+    /** Delta time */
+    dt: number;
+    /** Total elapsed time */
+    time: number;
+    /** World reference */
+    world: unknown;
+    /** Event bus */
+    events: EventBus;
+    /** Graph variables */
+    variables: Map<string, unknown>;
+    /** Global variables */
+    globals: Map<string, unknown>;
+    /** Service locator */
+    services: Map<string, unknown>;
+    /** Trigger flow output */
+    triggerFlow: (portId: string) => void;
+    /** Get component */
+    getComponent: <T>(entityId: EntityId, componentType: string) => T | null;
+    /** Set component data */
+    setComponent: (entityId: EntityId, componentType: string, data: unknown) => void;
+    /** Spawn entity */
+    spawnEntity: (prefab: string, position: Vec2) => EntityId;
+    /** Destroy entity */
+    destroyEntity: (entityId: EntityId) => void;
+    /** Find entities */
+    findEntities: (tag: string) => EntityId[];
+    /** Log message */
+    log: (level: 'info' | 'warn' | 'error', message: string) => void;
+    /** Print to screen */
+    print: (message: string, duration?: number, color?: string) => void;
+}
+export interface VSBreakpoint {
+    id: string;
+    nodeId: string;
+    enabled: boolean;
+    condition?: string;
+    hitCount?: number;
+    logMessage?: string;
+    temporary?: boolean;
+}
+export interface VSWatchExpression {
+    id: string;
+    expression: string;
+    value: unknown;
+    type: VSDataType;
+    error?: string;
+}
+export interface VSCallStackFrame {
+    nodeId: string;
+    nodeName: string;
+    graphId: string;
+    graphName: string;
+    functionName?: string;
+    variables: Map<string, unknown>;
+}
+export type VSDebuggerState = 'running' | 'paused' | 'stepping' | 'stopped';
+export interface VSDebuggerSession {
+    state: VSDebuggerState;
+    /** Current execution position */
+    currentNode: string | null;
+    currentGraph: string | null;
+    /** Call stack */
+    callStack: VSCallStackFrame[];
+    /** Breakpoints */
+    breakpoints: Map<string, VSBreakpoint>;
+    /** Watch expressions */
+    watches: VSWatchExpression[];
+    /** Execution history for step-back */
+    history: VSExecutionSnapshot[];
+    historyIndex: number;
+    /** Profiling data */
+    profiling: VSProfilingData;
+}
+export interface VSExecutionSnapshot {
+    timestamp: number;
+    nodeId: string;
+    inputs: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+    variables: Map<string, unknown>;
+}
+export interface VSProfilingData {
+    enabled: boolean;
+    nodeExecutionTimes: Map<string, number[]>;
+    totalFrameTime: number;
+    frameCount: number;
+}
+export type VSDebuggerEventType = 'breakpoint-hit' | 'step-completed' | 'execution-error' | 'variable-changed' | 'node-executed' | 'graph-started' | 'graph-completed';
+export interface VSDebuggerEvent {
+    type: VSDebuggerEventType;
+    timestamp: number;
+    data: unknown;
+}
+export declare class VSDebugger {
+    private session;
+    private eventListeners;
+    constructor();
+    private createSession;
+    start(): void;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    getState(): VSDebuggerState;
+    stepOver(): void;
+    stepInto(): void;
+    stepOut(): void;
+    stepBack(): void;
+    addBreakpoint(nodeId: string, options?: Partial<VSBreakpoint>): VSBreakpoint;
+    removeBreakpoint(breakpointId: string): void;
+    toggleBreakpoint(nodeId: string): VSBreakpoint | null;
+    setBreakpointCondition(breakpointId: string, condition: string): void;
+    enableBreakpoint(breakpointId: string, enabled: boolean): void;
+    getBreakpoints(): VSBreakpoint[];
+    addWatch(expression: string): VSWatchExpression;
+    removeWatch(watchId: string): void;
+    updateWatches(context: VSExecutionContext): void;
+    getWatches(): VSWatchExpression[];
+    pushStack(frame: VSCallStackFrame): void;
+    popStack(): VSCallStackFrame | undefined;
+    getCallStack(): VSCallStackFrame[];
+    getCurrentFrame(): VSCallStackFrame | null;
+    recordSnapshot(snapshot: VSExecutionSnapshot): void;
+    getHistory(): VSExecutionSnapshot[];
+    enableProfiling(enabled: boolean): void;
+    recordNodeTime(nodeId: string, timeMs: number): void;
+    getNodeAverageTime(nodeId: string): number;
+    getProfilingData(): VSProfilingData;
+    evaluateExpression(expr: string, context: VSExecutionContext): unknown;
+    private getNestedValue;
+    on(event: VSDebuggerEventType, listener: (event: VSDebuggerEvent) => void): void;
+    off(event: VSDebuggerEventType, listener: (event: VSDebuggerEvent) => void): void;
+    private emit;
+    onNodeStartExecution(nodeId: string, inputs: Record<string, unknown>): boolean;
+    onNodeCompleteExecution(nodeId: string, outputs: Record<string, unknown>, timeMs: number): void;
+}
+export declare class VSGraphExecutor {
+    private nodeLibrary;
+    private debugger;
+    private executionQueue;
+    constructor(debuggerInstance?: VSDebugger);
+    registerNode(definition: VSNodeDefinition): void;
+    registerNodes(definitions: VSNodeDefinition[]): void;
+    getNodeDefinition(type: string): VSNodeDefinition | undefined;
+    getAllNodeDefinitions(): VSNodeDefinition[];
+    searchNodes(query: string): VSNodeDefinition[];
+    execute(graph: VSGraph, entryType: string, context: VSExecutionContext): void;
+    executeNode(graph: VSGraph, node: VSNodeInstance, context: VSExecutionContext): void;
+    private followFlowConnections;
+    getDebugger(): VSDebugger;
+    resumeExecution(): void;
+}
+export declare function createBuiltInNodes(): VSNodeDefinition[];
+export declare function createVSGraph(name: string): VSGraph;
+export declare function createVSNode(type: string, position: Vec2): VSNodeInstance;
+export declare function createVSConnection(fromNode: string, fromPort: string, toNode: string, toPort: string): VSConnection;
+export declare function createVSDebugger(): VSDebugger;
+export declare function createVSExecutor(debuggerInstance?: VSDebugger): VSGraphExecutor;