@nice2dev/game-engine 0.1.0 → 1.0.3

package/dist/types/editor/ShaderGraph.d.ts

@@ -0,0 +1,207 @@
+/**
+ * @file ShaderGraph.ts
+ * @description Visual Shader Graph Editor System
+ * PRO-1.4: Professional Editor Features
+ *
+ * Features:
+ * - Node-based shader editing
+ * - GLSL/WGSL/HLSL generation
+ * - Real-time preview
+ * - Material templates
+ * - Custom node creation
+ * - Subgraph support
+ * - PBR and unlit workflows
+ */
+export type ShaderTarget = 'glsl' | 'wgsl' | 'hlsl' | 'metal' | 'spirv';
+export type ShaderStage = 'vertex' | 'fragment' | 'compute';
+export type ShaderPrecision = 'lowp' | 'mediump' | 'highp';
+export type ShaderDataType = 'float' | 'vec2' | 'vec3' | 'vec4' | 'int' | 'ivec2' | 'ivec3' | 'ivec4' | 'bool' | 'bvec2' | 'bvec3' | 'bvec4' | 'mat2' | 'mat3' | 'mat4' | 'sampler2D' | 'samplerCube' | 'sampler3D' | 'void';
+export type ShaderBlendMode = 'opaque' | 'alpha' | 'additive' | 'multiply' | 'premultiplied';
+export type ShaderCullMode = 'none' | 'front' | 'back';
+export type ShaderDepthTest = 'always' | 'never' | 'less' | 'lequal' | 'greater' | 'gequal' | 'equal' | 'notequal';
+export interface ShaderPortDef {
+    name: string;
+    type: ShaderDataType;
+    description?: string;
+    default?: number | number[];
+    min?: number;
+    max?: number;
+    hidden?: boolean;
+}
+export interface ShaderNodeDef {
+    id: string;
+    name: string;
+    category: ShaderNodeCategory;
+    description?: string;
+    inputs: ShaderPortDef[];
+    outputs: ShaderPortDef[];
+    /** GLSL code template with {{input}}, {{output}} placeholders */
+    glsl?: string;
+    /** WGSL code template */
+    wgsl?: string;
+    /** HLSL code template */
+    hlsl?: string;
+    /** Preview function name */
+    previewFunc?: string;
+    /** Custom properties */
+    properties?: ShaderPropertyDef[];
+    /** Whether this node is a master/output node */
+    isMaster?: boolean;
+    /** Stage restriction */
+    stage?: ShaderStage;
+}
+export type ShaderNodeCategory = 'input' | 'output' | 'math' | 'vector' | 'matrix' | 'texture' | 'uv' | 'color' | 'lighting' | 'channel' | 'procedural' | 'utility' | 'custom' | 'subgraph';
+export interface ShaderPropertyDef {
+    name: string;
+    type: 'float' | 'int' | 'bool' | 'color' | 'texture' | 'dropdown' | 'vec2' | 'vec3' | 'vec4';
+    default?: unknown;
+    options?: string[];
+    min?: number;
+    max?: number;
+}
+export interface ShaderPort {
+    nodeId: string;
+    portName: string;
+}
+export interface ShaderConnection {
+    id: string;
+    from: ShaderPort;
+    to: ShaderPort;
+}
+export interface ShaderNodeInstance {
+    id: string;
+    type: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    properties: Record<string, unknown>;
+    /** Collapsed state */
+    collapsed?: boolean;
+    /** Preview enabled */
+    previewEnabled?: boolean;
+    /** Custom title override */
+    title?: string;
+    /** Comment/note */
+    comment?: string;
+}
+export interface ShaderSubgraph {
+    id: string;
+    name: string;
+    description?: string;
+    nodes: ShaderNodeInstance[];
+    connections: ShaderConnection[];
+    inputs: ShaderPortDef[];
+    outputs: ShaderPortDef[];
+}
+export interface ShaderGraphDef {
+    id: string;
+    name: string;
+    description?: string;
+    target: ShaderTarget;
+    stage: ShaderStage;
+    nodes: ShaderNodeInstance[];
+    connections: ShaderConnection[];
+    /** Exposed properties for material instances */
+    properties: ShaderExposedProperty[];
+    /** Graph-level settings */
+    settings: ShaderGraphSettings;
+    /** Subgraphs */
+    subgraphs?: ShaderSubgraph[];
+    /** Custom functions */
+    customFunctions?: ShaderCustomFunction[];
+    /** Metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface ShaderExposedProperty {
+    id: string;
+    name: string;
+    displayName: string;
+    type: ShaderDataType;
+    default: unknown;
+    min?: number;
+    max?: number;
+    group?: string;
+    tooltip?: string;
+}
+export interface ShaderGraphSettings {
+    precision: ShaderPrecision;
+    blendMode: ShaderBlendMode;
+    cullMode: ShaderCullMode;
+    depthWrite: boolean;
+    depthTest: ShaderDepthTest;
+    alphaClip?: number;
+    castShadows: boolean;
+    receiveShadows: boolean;
+    doubleSided: boolean;
+    /** Surface type */
+    surfaceType: 'opaque' | 'transparent';
+    /** Render queue */
+    renderQueue: number;
+    /** Custom defines */
+    defines?: Record<string, string | number | boolean>;
+}
+export interface ShaderCustomFunction {
+    name: string;
+    returnType: ShaderDataType;
+    parameters: {
+        name: string;
+        type: ShaderDataType;
+    }[];
+    body: string;
+}
+export declare const SHADER_NODE_LIBRARY: ShaderNodeDef[];
+export interface GeneratedShader {
+    vertex: string;
+    fragment: string;
+    uniforms: ShaderUniform[];
+    defines: string[];
+}
+export interface ShaderUniform {
+    name: string;
+    type: ShaderDataType;
+    value?: unknown;
+}
+export declare class ShaderCodeGenerator {
+    private graph;
+    private nodeLibrary;
+    private generatedCode;
+    private uniforms;
+    private defines;
+    private nodeCounter;
+    constructor(graph: ShaderGraphDef);
+    generate(): GeneratedShader;
+    private generateNode;
+    private defaultValue;
+    private formatValue;
+    private buildVertexShader;
+    private buildFragmentShader;
+}
+export interface ShaderGraphEditorState {
+    graph: ShaderGraphDef;
+    selectedNodes: string[];
+    hoveredNode: string | null;
+    hoveredPort: ShaderPort | null;
+    draggingConnection: {
+        from: ShaderPort;
+        toPosition: {
+            x: number;
+            y: number;
+        };
+    } | null;
+    viewOffset: {
+        x: number;
+        y: number;
+    };
+    zoom: number;
+    previewEnabled: boolean;
+    generatedShader: GeneratedShader | null;
+    compileErrors: string[];
+}
+export declare function createShaderGraphEditorState(graph?: ShaderGraphDef): ShaderGraphEditorState;
+export declare function createEmptyShaderGraph(): ShaderGraphDef;
+export declare function createShaderGraph(name: string, target?: ShaderTarget): ShaderGraphDef;
+export declare function generateShader(graph: ShaderGraphDef): GeneratedShader;
+export declare function getNodeLibrary(): ShaderNodeDef[];
+export declare function getNodesByCategory(category: ShaderNodeCategory): ShaderNodeDef[];
+export declare function findNodeDef(nodeType: string): ShaderNodeDef | undefined;

package/dist/types/editor/TimelineEditor.d.ts

@@ -0,0 +1,393 @@
+/**
+ * @file TimelineEditor.ts
+ * @description Timeline System for Cutscenes, Cinematics, and Sequencing
+ * PRO-1.4: Professional Editor Features
+ *
+ * Features:
+ * - Multi-track timeline
+ * - Track types: animation, audio, event, property, activation
+ * - Keyframe animation with curves
+ * - Clips with blending
+ * - Markers and events
+ * - Playback control
+ * - Recording mode
+ * - Debugger integration
+ */
+import type { EntityId, Vec2 } from '../core/types';
+export type TimelinePlayState = 'stopped' | 'playing' | 'paused' | 'recording';
+export type TimelineWrapMode = 'once' | 'loop' | 'pingPong' | 'clampForever';
+export type TrackType = 'animation' | 'audio' | 'event' | 'property' | 'activation' | 'camera' | 'transform' | 'group' | 'override';
+export type TangentMode = 'auto' | 'smooth' | 'linear' | 'constant' | 'free';
+export type EasingFunction = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInQuart' | 'easeOutQuart' | 'easeInOutQuart' | 'easeInQuint' | 'easeOutQuint' | 'easeInOutQuint' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine' | 'easeInExpo' | 'easeOutExpo' | 'easeInOutExpo' | 'easeInCirc' | 'easeOutCirc' | 'easeInOutCirc' | 'easeInBack' | 'easeOutBack' | 'easeInOutBack' | 'easeInElastic' | 'easeOutElastic' | 'easeInOutElastic' | 'easeInBounce' | 'easeOutBounce' | 'easeInOutBounce';
+export interface Keyframe<T = number> {
+    id: string;
+    time: number;
+    value: T;
+    /** Easing to next keyframe */
+    easing?: EasingFunction;
+    /** Bezier tangent mode */
+    tangentMode?: TangentMode;
+    /** In tangent (for bezier) */
+    inTangent?: Vec2;
+    /** Out tangent (for bezier) */
+    outTangent?: Vec2;
+    /** In weight (0-1) */
+    inWeight?: number;
+    /** Out weight (0-1) */
+    outWeight?: number;
+}
+export interface AnimationCurve {
+    id: string;
+    property: string;
+    keyframes: Keyframe<number>[];
+    /** Pre-infinity mode */
+    preWrap?: TimelineWrapMode;
+    /** Post-infinity mode */
+    postWrap?: TimelineWrapMode;
+}
+export interface BaseClip {
+    id: string;
+    name: string;
+    trackId: string;
+    /** Start time in timeline */
+    startTime: number;
+    /** Duration of clip */
+    duration: number;
+    /** Clip can be trimmed from start */
+    clipIn?: number;
+    /** Speed multiplier */
+    speed?: number;
+    /** Blend in duration */
+    blendInDuration?: number;
+    /** Blend out duration */
+    blendOutDuration?: number;
+    /** Custom color */
+    color?: string;
+    /** Is this clip muted? */
+    muted?: boolean;
+    /** Is this clip locked? */
+    locked?: boolean;
+}
+export interface AnimationClip extends BaseClip {
+    type: 'animation';
+    /** Animation curves */
+    curves: AnimationCurve[];
+    /** Root motion */
+    rootMotion?: {
+        extractPosition: boolean;
+        extractRotation: boolean;
+    };
+    /** Target binding */
+    binding?: {
+        type: 'entity' | 'component' | 'property';
+        path: string;
+    };
+}
+export interface AudioClip extends BaseClip {
+    type: 'audio';
+    /** Audio asset reference */
+    audioSource: string;
+    /** Volume (0-1) */
+    volume: number;
+    /** Volume curve */
+    volumeCurve?: AnimationCurve;
+    /** Spatial blend (0 = 2D, 1 = 3D) */
+    spatialBlend?: number;
+    /** Loop */
+    loop?: boolean;
+}
+export interface EventClip extends BaseClip {
+    type: 'event';
+    /** Event name to fire */
+    eventName: string;
+    /** Event payload */
+    payload?: Record<string, unknown>;
+    /** Fire once or every frame */
+    fireMode: 'once' | 'every-frame' | 'on-exit';
+}
+export interface PropertyClip extends BaseClip {
+    type: 'property';
+    /** Target property path */
+    propertyPath: string;
+    /** Property curves */
+    curves: AnimationCurve[];
+}
+export interface ActivationClip extends BaseClip {
+    type: 'activation';
+    /** Entity to activate/deactivate */
+    targetEntity: EntityId;
+    /** Activation state */
+    active: boolean;
+}
+export interface TransformClip extends BaseClip {
+    type: 'transform';
+    /** Position curve */
+    positionCurve?: {
+        x: AnimationCurve;
+        y: AnimationCurve;
+        z: AnimationCurve;
+    };
+    /** Rotation curve (euler) */
+    rotationCurve?: {
+        x: AnimationCurve;
+        y: AnimationCurve;
+        z: AnimationCurve;
+    };
+    /** Scale curve */
+    scaleCurve?: {
+        x: AnimationCurve;
+        y: AnimationCurve;
+        z: AnimationCurve;
+    };
+}
+export interface CameraClip extends BaseClip {
+    type: 'camera';
+    /** Camera property curves */
+    fieldOfView?: AnimationCurve;
+    nearClip?: AnimationCurve;
+    farClip?: AnimationCurve;
+    /** Depth of field */
+    dof?: {
+        focusDistance: AnimationCurve;
+        aperture: AnimationCurve;
+        focalLength: AnimationCurve;
+    };
+    /** Camera shake */
+    shake?: {
+        amplitude: AnimationCurve;
+        frequency: AnimationCurve;
+    };
+    /** Look-at target */
+    lookAtTarget?: EntityId;
+}
+export type TimelineClip = AnimationClip | AudioClip | EventClip | PropertyClip | ActivationClip | TransformClip | CameraClip;
+export interface BaseTrack {
+    id: string;
+    name: string;
+    type: TrackType;
+    /** Parent track (for grouping) */
+    parentId?: string;
+    /** Track color */
+    color?: string;
+    /** Is track muted? */
+    muted?: boolean;
+    /** Is track locked? */
+    locked?: boolean;
+    /** Is track collapsed in UI? */
+    collapsed?: boolean;
+    /** Track height in editor */
+    height?: number;
+    /** Clips on this track */
+    clips: TimelineClip[];
+    /** Override tracks (for track mixing) */
+    overrides?: string[];
+}
+export interface AnimationTrack extends BaseTrack {
+    type: 'animation';
+    /** Binding target */
+    binding?: {
+        entityId: EntityId;
+        animator?: string;
+    };
+    /** Default animator state */
+    defaultState?: string;
+}
+export interface AudioTrack extends BaseTrack {
+    type: 'audio';
+    /** Output audio group */
+    outputGroup?: string;
+    /** Master volume */
+    volume?: number;
+}
+export interface EventTrack extends BaseTrack {
+    type: 'event';
+    /** Target listener */
+    listenerPath?: string;
+}
+export interface PropertyTrack extends BaseTrack {
+    type: 'property';
+    /** Target entity */
+    targetEntity: EntityId;
+    /** Property path */
+    propertyPath: string;
+}
+export interface ActivationTrack extends BaseTrack {
+    type: 'activation';
+    /** Target entity */
+    targetEntity: EntityId;
+}
+export interface TransformTrack extends BaseTrack {
+    type: 'transform';
+    /** Target entity */
+    targetEntity: EntityId;
+    /** Space */
+    space: 'local' | 'world';
+}
+export interface CameraTrack extends BaseTrack {
+    type: 'camera';
+    /** Target camera entity */
+    cameraEntity: EntityId;
+}
+export interface GroupTrack extends BaseTrack {
+    type: 'group';
+    /** Child track IDs */
+    children: string[];
+}
+export type TimelineTrack = AnimationTrack | AudioTrack | EventTrack | PropertyTrack | ActivationTrack | TransformTrack | CameraTrack | GroupTrack;
+export interface TimelineMarker {
+    id: string;
+    name: string;
+    time: number;
+    color?: string;
+    /** Marker type */
+    type: 'marker' | 'signal' | 'jump';
+    /** For signal markers */
+    signalName?: string;
+    signalPayload?: Record<string, unknown>;
+    /** For jump markers */
+    jumpTarget?: string;
+    jumpCondition?: string;
+}
+export interface TimelineDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    /** Total duration */
+    duration: number;
+    /** Frames per second */
+    fps: number;
+    /** Wrap mode */
+    wrapMode: TimelineWrapMode;
+    /** Tracks */
+    tracks: TimelineTrack[];
+    /** Markers */
+    markers: TimelineMarker[];
+    /** Metadata */
+    metadata?: {
+        author?: string;
+        version?: string;
+        created?: number;
+        modified?: number;
+        tags?: string[];
+    };
+    /** Editor settings */
+    editorSettings?: {
+        snapToFrames: boolean;
+        showCurves: boolean;
+        showAudioWaveforms: boolean;
+        zoom: number;
+        scrollOffset: number;
+    };
+}
+export type TimelineEventType = 'play' | 'pause' | 'stop' | 'seek' | 'marker' | 'signal' | 'clip-enter' | 'clip-exit' | 'loop' | 'complete' | 'event';
+export interface TimelineEvent {
+    type: TimelineEventType;
+    time: number;
+    data?: unknown;
+}
+export declare function applyEasing(t: number, easing?: EasingFunction): number;
+export declare function evaluateCurve(curve: AnimationCurve, time: number): number;
+export declare class TimelinePlayer {
+    private definition;
+    private state;
+    private currentTime;
+    private speed;
+    private direction;
+    /** Active clips per track */
+    private activeClips;
+    /** Previous time for detecting clip transitions */
+    private previousTime;
+    /** Event listeners */
+    private listeners;
+    /** Property bindings */
+    private propertyBindings;
+    /** Audio context */
+    private audioContext?;
+    private audioNodes;
+    /** Debug mode */
+    debugMode: boolean;
+    private history;
+    constructor(definition: TimelineDefinition);
+    play(): void;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    seekToMarker(markerName: string): boolean;
+    setSpeed(speed: number): void;
+    getSpeed(): number;
+    update(dt: number): void;
+    private processTracks;
+    private processTrack;
+    private onClipEnter;
+    private onClipExit;
+    private updateClip;
+    private updateAnimationClip;
+    private updatePropertyClip;
+    private updateEventClip;
+    private updateTransformClip;
+    private updateCameraClip;
+    private updateAudioClip;
+    private fireEventClip;
+    private playAudioClip;
+    private stopAudioClip;
+    private stopAllAudio;
+    private processMarkers;
+    private evaluateCondition;
+    bindProperty(path: string, setter: (value: unknown) => void): void;
+    unbindProperty(path: string): void;
+    private applyProperty;
+    on(event: TimelineEventType, listener: (event: TimelineEvent) => void): void;
+    off(event: TimelineEventType, listener: (event: TimelineEvent) => void): void;
+    private emit;
+    getState(): TimelinePlayState;
+    getCurrentTime(): number;
+    getDuration(): number;
+    getProgress(): number;
+    isPlaying(): boolean;
+    isPaused(): boolean;
+    isStopped(): boolean;
+    getDefinition(): TimelineDefinition;
+    getHistory(): TimelineEvent[];
+    clearHistory(): void;
+    getDebugInfo(): {
+        state: TimelinePlayState;
+        time: number;
+        duration: number;
+        progress: number;
+        speed: number;
+        activeClipCount: number;
+    };
+}
+export interface RecordingOptions {
+    targetTrack: string;
+    propertyPath?: string;
+    sampleRate?: number;
+    autoKeyMode?: 'none' | 'all' | 'modified';
+}
+export declare class TimelineRecorder {
+    private player;
+    private options;
+    private recording;
+    private recordedKeyframes;
+    private lastSampleTime;
+    constructor(player: TimelinePlayer, options: RecordingOptions);
+    startRecording(): void;
+    stopRecording(): Map<string, Keyframe<number>[]>;
+    isRecording(): boolean;
+    recordValue(property: string, value: number): void;
+    getRecordedKeyframes(): Map<string, Keyframe<number>[]>;
+}
+export declare function createTimelineDefinition(name: string, duration?: number): TimelineDefinition;
+export declare function createTimelinePlayer(definition: TimelineDefinition): TimelinePlayer;
+export declare function createTimelineRecorder(player: TimelinePlayer, options: RecordingOptions): TimelineRecorder;
+export declare function createTrack(name: string, type: TrackType): TimelineTrack;
+export declare function createAnimationClip(trackId: string, startTime: number, duration: number): AnimationClip;
+export declare function createAudioClip(trackId: string, startTime: number, duration: number, audioSource: string): AudioClip;
+export declare function createEventClip(trackId: string, time: number, eventName: string): EventClip;
+export declare function createPropertyClip(trackId: string, startTime: number, duration: number, propertyPath: string): PropertyClip;
+export declare function createTransformClip(trackId: string, startTime: number, duration: number): TransformClip;
+export declare function createCameraClip(trackId: string, startTime: number, duration: number): CameraClip;
+export declare function createAnimationCurve(property: string): AnimationCurve;
+export declare function createKeyframe<T = number>(time: number, value: T, easing?: EasingFunction): Keyframe<T>;
+export declare function createMarker(name: string, time: number): TimelineMarker;
+export declare function createSignalMarker(name: string, time: number, signalName: string, payload?: Record<string, unknown>): TimelineMarker;