@nice2dev/game-engine 1.0.2 → 1.0.4

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;

package/dist/types/export/GodotExporter.d.ts

@@ -0,0 +1,56 @@
+import { PlatformExporter, type PlatformInfo, type NiceProject, type ExportOptions } from './PlatformExporter';
+export interface GodotExportOptions {
+    /** Godot version (4.0, 4.1, 4.2, etc.) */
+    godotVersion?: string;
+    /** Use typed GDScript */
+    useTypedGDScript?: boolean;
+    /** Generate C# scripts instead of GDScript */
+    useCSharp?: boolean;
+    /** Include autoload singletons */
+    includeAutoloads?: boolean;
+    /** Renderer type */
+    renderer?: 'forward_plus' | 'mobile' | 'gl_compatibility';
+}
+export declare class GodotExporter extends PlatformExporter {
+    readonly platformId: "godot";
+    readonly platformInfo: PlatformInfo;
+    private gdscriptExporter;
+    private graphToAST;
+    private resourceIdCounter;
+    private uidCounter;
+    protected doExport(project: NiceProject, options: ExportOptions): Promise<void>;
+    private exportProjectFile;
+    private exportScripts;
+    private exportScenes;
+    private createSceneTSCN;
+    private createGodotNode;
+    private createComponentNode;
+    private createTilemapNode;
+    private exportPrefabs;
+    private createPrefabTSCN;
+    private exportResources;
+    private createMaterialTRES;
+    private createAnimationLibrary;
+    private exportTilesets;
+    private createTileSetTRES;
+    private exportAutoloads;
+    private exportEnvironment;
+    private exportAssetImports;
+    private createImportFile;
+    private getAssetPath;
+    private addScriptResource;
+    private addTextureResource;
+    private addAudioResource;
+    private addTileSetResource;
+    private serializeTSCN;
+    private serializeNodes;
+    private formatValue;
+    private hexToGodotColor;
+    private linearToDb;
+    private sanitizeName;
+    private nextResourceId;
+    private nextUID;
+    private getHorizontalAlignment;
+    private getVerticalAlignment;
+}
+export default GodotExporter;

package/dist/types/export/PlatformExporter.d.ts

@@ -0,0 +1,201 @@
+import type { ScriptGraph } from '../scripting/NodeGraph';
+export type PlatformId = 'unity' | 'godot' | 'unreal' | 'pixijs' | 'phaser' | 'threejs' | 'cocos' | 'gamemaker' | 'roblox' | 'minecraft' | 'rpgmaker' | 'construct3' | 'gdevelop' | 'defold' | 'solar2d' | 'pico8' | 'tic80' | 'web-generic';
+export interface PlatformInfo {
+    id: PlatformId;
+    name: string;
+    description: string;
+    icon?: string;
+    website: string;
+    features: PlatformFeature[];
+    supportedAssets: AssetType[];
+    exportFormats: string[];
+}
+export type PlatformFeature = '2d-rendering' | '3d-rendering' | 'physics-2d' | 'physics-3d' | 'audio' | 'networking' | 'ui-system' | 'visual-scripting' | 'tilemaps' | 'particles' | 'animation' | 'vr-ar';
+export type AssetType = 'sprite' | 'tileset' | 'audio' | 'font' | 'script' | 'scene' | 'prefab' | 'material' | 'shader' | 'animation' | 'tilemap' | 'particleSystem' | 'texture' | 'data';
+export interface NiceProject {
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    settings: ProjectSettings;
+    scenes: NiceScene[];
+    assets: NiceAsset[];
+    scripts: ScriptGraph[];
+    prefabs: NicePrefab[];
+}
+export interface ProjectSettings {
+    resolution: {
+        width: number;
+        height: number;
+    };
+    width?: number;
+    height?: number;
+    backgroundColor: string;
+    physics: {
+        gravity: {
+            x: number;
+            y: number;
+        };
+        enabled: boolean;
+        velocityIterations?: number;
+        positionIterations?: number;
+        timeStep?: number;
+    };
+    audio: {
+        masterVolume: number;
+        musicVolume?: number;
+        sfxVolume?: number;
+        audioChannels?: number;
+    };
+    rendering: {
+        pixelArt: boolean;
+        antialias: boolean;
+        pixelPerfect?: boolean;
+        antialiasing?: boolean;
+        vsync?: boolean;
+        backgroundColor?: string;
+    };
+    input?: Record<string, unknown>;
+}
+export interface NiceScene {
+    id: string;
+    name: string;
+    entities: NiceEntity[];
+    tilemaps?: NiceTilemap[];
+    metadata?: Record<string, unknown>;
+    settings?: Record<string, unknown>;
+}
+export interface NiceEntity {
+    id: string;
+    name: string;
+    type?: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    rotation?: number;
+    scale?: {
+        x: number;
+        y: number;
+    };
+    components: NiceComponent[];
+    children?: NiceEntity[];
+    prefabId?: string;
+    scriptId?: string;
+    tags?: string[];
+    active?: boolean;
+}
+export interface NiceComponent {
+    type: string;
+    properties?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+}
+export interface NiceAsset {
+    id: string;
+    type: AssetType;
+    name: string;
+    path: string;
+    metadata?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+}
+export interface NicePrefab {
+    id: string;
+    name: string;
+    entity: NiceEntity;
+}
+export interface NiceTilemap {
+    id: string;
+    name: string;
+    tilesetId: string;
+    width: number;
+    height: number;
+    tileSize: number;
+    layers: TilemapLayer[];
+}
+export interface TilemapLayer {
+    name: string;
+    data: number[];
+    visible: boolean;
+    opacity: number;
+}
+export interface ExportOptions {
+    /** Target platform */
+    platform: PlatformId;
+    /** Output directory path */
+    outputDir: string;
+    /** Project name (used for folder/file naming) */
+    projectName?: string;
+    /** Whether to minify generated code */
+    minify?: boolean;
+    /** Include debug information */
+    debug?: boolean;
+    /** Platform-specific options */
+    platformOptions?: Record<string, unknown>;
+}
+export interface ExportResult {
+    success: boolean;
+    platform: PlatformId;
+    outputFiles: ExportedFile[];
+    errors: ExportError[];
+    warnings: ExportWarning[];
+    stats: ExportStats;
+}
+export interface ExportedFile {
+    path: string;
+    content: string | Uint8Array;
+    type: 'text' | 'binary';
+}
+export interface ExportError {
+    code: string;
+    message: string;
+    file?: string;
+    line?: number;
+}
+export interface ExportWarning {
+    code: string;
+    message: string;
+    suggestion?: string;
+}
+export interface ExportStats {
+    totalFiles: number;
+    totalSize: number;
+    duration: number;
+    assetsProcessed: number;
+    scriptsGenerated: number;
+    scenesExported: number;
+}
+export declare abstract class PlatformExporter {
+    abstract readonly platformId: PlatformId;
+    abstract readonly platformInfo: PlatformInfo;
+    protected errors: ExportError[];
+    protected warnings: ExportWarning[];
+    protected files: ExportedFile[];
+    /**
+     * Export a Nice2Dev project to this platform.
+     */
+    export(project: NiceProject, options: ExportOptions): Promise<ExportResult>;
+    /**
+     * Check if this platform supports a feature.
+     */
+    supportsFeature(feature: PlatformFeature): boolean;
+    /**
+     * Check if this platform supports an asset type.
+     */
+    supportsAsset(type: AssetType): boolean;
+    protected addFile(path: string, content: string | Uint8Array, type?: 'text' | 'binary'): void;
+    protected addTextFile(path: string, content: string): void;
+    protected addBinaryFile(path: string, content: Uint8Array): void;
+    protected addError(code: string, message: string, file?: string, line?: number): void;
+    protected addWarning(code: string, message: string, suggestion?: string): void;
+    protected abstract doExport(project: NiceProject, options: ExportOptions): Promise<void>;
+}
+export interface DetectionResult {
+    platform: PlatformId;
+    confidence: number;
+    reasons: string[];
+}
+export declare function detectBestPlatform(project: NiceProject): DetectionResult[];
+export declare function registerPlatform(info: PlatformInfo): void;
+export declare function getPlatformInfo(id: PlatformId): PlatformInfo | undefined;
+export declare function getAllPlatforms(): PlatformInfo[];
+export default PlatformExporter;

package/dist/types/export/ThreeJSExporter.d.ts

@@ -0,0 +1,40 @@
+import { PlatformExporter, type PlatformInfo, type NiceProject, type ExportOptions } from './PlatformExporter';
+export interface ThreeJSExportOptions {
+    /** Use TypeScript */
+    typescript?: boolean;
+    /** Bundler to use */
+    bundler?: 'vite' | 'webpack' | 'parcel' | 'none';
+    /** Include VR/AR support */
+    xr?: boolean;
+    /** Use OrbitControls by default */
+    orbitControls?: boolean;
+    /** Include post-processing */
+    postProcessing?: boolean;
+    /** Physics engine */
+    physics?: 'cannon' | 'ammo' | 'rapier' | 'none';
+    /** Three.js version */
+    version?: string;
+}
+export declare class ThreeJSExporter extends PlatformExporter {
+    readonly platformId: "threejs";
+    readonly platformInfo: PlatformInfo;
+    private tsExporter;
+    private graphToAST;
+    protected doExport(project: NiceProject, options: ExportOptions): Promise<void>;
+    private exportPackageJson;
+    private exportIndexHtml;
+    private exportMainGame;
+    private exportScenes;
+    private exportScene;
+    private generateEntityCode;
+    private generateMeshCode;
+    private generateModelCode;
+    private generateLightCode;
+    private exportScripts;
+    private exportUtilities;
+    private exportShaders;
+    private exportBundlerConfig;
+    private exportTSConfig;
+    private sanitizeName;
+}
+export default ThreeJSExporter;