@nice2dev/game-engine 0.1.0 → 1.0.3

package/dist/types/engine/SaveSystemV2.d.ts

@@ -0,0 +1,155 @@
+import { EventBus } from '../core/EventBus';
+export type SaveSlotType = 'manual' | 'auto' | 'checkpoint' | 'quick';
+export type SaveConflictStrategy = 'local-wins' | 'remote-wins' | 'newest-wins' | 'merge' | 'prompt-user';
+export type SaveStorageBackend = 'indexeddb' | 'localstorage' | 'filesystem' | 'cloud';
+export type MigrationDirection = 'up' | 'down';
+export interface SaveSlotMeta {
+    slotId: string;
+    type: SaveSlotType;
+    label: string;
+    schemaVersion: number;
+    createdAt: number;
+    updatedAt: number;
+    playtimeMs: number;
+    /** Scene/level the player was in */
+    location: string;
+    /** Preview thumbnail (data URL) */
+    thumbnail?: string;
+    /** Compressed size in bytes */
+    sizeBytes: number;
+    /** CRC32 checksum */
+    checksum: number;
+    /** Cloud sync status */
+    cloudSynced: boolean;
+    cloudTimestamp?: number;
+    /** Custom tags for filtering */
+    tags: string[];
+}
+export interface SaveData {
+    meta: SaveSlotMeta;
+    payload: Record<string, unknown>;
+}
+export interface SaveMigration {
+    fromVersion: number;
+    toVersion: number;
+    description: string;
+    /** Transform the payload from one version to the next */
+    migrate: (payload: Record<string, unknown>) => Record<string, unknown>;
+    /** Optional rollback */
+    rollback?: (payload: Record<string, unknown>) => Record<string, unknown>;
+}
+export interface CloudSyncConfig {
+    enabled: boolean;
+    endpoint?: string;
+    apiKey?: string;
+    conflictStrategy: SaveConflictStrategy;
+    syncIntervalMs: number;
+    maxCloudSlots: number;
+}
+export interface AutoSaveConfig {
+    enabled: boolean;
+    intervalMs: number;
+    maxAutoSaves: number;
+    /** Only auto-save when game state is "safe" (not in combat, etc.) */
+    requireSafeState: boolean;
+}
+export interface SaveSystemConfig {
+    schemaVersion: number;
+    storageBackend: SaveStorageBackend;
+    storageKey: string;
+    maxSlots: number;
+    compressionEnabled: boolean;
+    autoSave: AutoSaveConfig;
+    cloud: CloudSyncConfig;
+}
+export declare const DEFAULT_SAVE_CONFIG: SaveSystemConfig;
+export interface SaveConflict {
+    slotId: string;
+    localMeta: SaveSlotMeta;
+    remoteMeta: SaveSlotMeta;
+    resolvedWith?: SaveConflictStrategy;
+}
+export interface SaveResult {
+    success: boolean;
+    slotId: string;
+    sizeBytes: number;
+    compressed: boolean;
+    error?: string;
+}
+/** Simple compression for JSON save data (dictionary-based) */
+export declare function compressSaveData(json: string): Uint8Array;
+/** Decompress save data */
+export declare function decompressSaveData(data: Uint8Array): string;
+export declare function crc32(data: Uint8Array): number;
+export declare class MigrationEngine {
+    private migrations;
+    register(migration: SaveMigration): void;
+    /** Migrate payload from fromVersion to toVersion */
+    migrate(payload: Record<string, unknown>, fromVersion: number, toVersion: number): {
+        payload: Record<string, unknown>;
+        applied: string[];
+    };
+    getRegistered(): readonly SaveMigration[];
+    canMigrate(from: number, to: number): boolean;
+}
+export declare class SaveSystemV2 {
+    private config;
+    private migrationEngine;
+    private eventBus;
+    private slots;
+    private autoSaveTimer;
+    private autoSaveCounter;
+    private safeToSave;
+    constructor(eventBus: EventBus, config?: Partial<SaveSystemConfig>);
+    private setupEventHandlers;
+    /** Register a schema migration */
+    registerMigration(migration: SaveMigration): void;
+    /** Save game state to a slot */
+    save(slotId: string, payload: Record<string, unknown>, options?: {
+        type?: SaveSlotType;
+        label?: string;
+        location?: string;
+        thumbnail?: string;
+        tags?: string[];
+    }): SaveResult;
+    /** Load game state from a slot */
+    load(slotId: string): {
+        payload: Record<string, unknown>;
+        meta: SaveSlotMeta;
+        migrated: boolean;
+    } | null;
+    /** Delete a save slot */
+    delete(slotId: string): boolean;
+    /** List all save slot metadata (sorted by updatedAt desc) */
+    listSlots(): SaveSlotMeta[];
+    /** Get slot metadata without loading payload */
+    getSlotMeta(slotId: string): SaveSlotMeta | null;
+    /** Check if a slot exists */
+    hasSlot(slotId: string): boolean;
+    /** Start auto-save timer */
+    startAutoSave(getPayload: () => Record<string, unknown>, getLocation: () => string): void;
+    /** Stop auto-save */
+    stopAutoSave(): void;
+    /** Quick save (overwriting the single quick save slot) */
+    quickSave(payload: Record<string, unknown>, location: string): SaveResult;
+    /** Quick load */
+    quickLoad(): ReturnType<SaveSystemV2['load']>;
+    /** Sync local saves to cloud (stub — needs actual endpoint) */
+    syncToCloud(): Promise<{
+        synced: string[];
+        conflicts: SaveConflict[];
+    }>;
+    /** Resolve a cloud sync conflict */
+    resolveConflict(conflict: SaveConflict, strategy: SaveConflictStrategy): SaveSlotMeta;
+    private persistSlot;
+    private removeFromStorage;
+    /** Load all slots from storage backend */
+    loadFromStorage(): Promise<number>;
+    /** Export all saves as a downloadable blob */
+    exportAll(): Blob;
+    /** Import saves from a blob */
+    importAll(blob: Blob): Promise<number>;
+    getConfig(): Readonly<SaveSystemConfig>;
+    getMigrationEngine(): MigrationEngine;
+    destroy(): void;
+}

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;

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

@@ -0,0 +1,69 @@
+import { PlatformExporter, type PlatformInfo, type NiceProject, type ExportOptions } from './PlatformExporter';
+export interface UnityExportOptions {
+    /** Namespace for generated C# scripts */
+    namespace?: string;
+    /** Generate assembly definition */
+    generateAsmdef?: boolean;
+    /** Unity version target */
+    unityVersion?: string;
+    /** Use Universal Render Pipeline */
+    useURP?: boolean;
+    /** Generate editor scripts */
+    generateEditor?: boolean;
+    /** Include Nice2Dev runtime */
+    includeRuntime?: boolean;
+}
+export declare class UnityExporter extends PlatformExporter {
+    readonly platformId: "unity";
+    readonly platformInfo: PlatformInfo;
+    private csharpExporter;
+    private graphToAST;
+    private guidMap;
+    private fileIdCounter;
+    protected doExport(project: NiceProject, options: ExportOptions): Promise<void>;
+    private exportProjectSettings;
+    private exportScripts;
+    private exportPrefabs;
+    private createPrefabYAML;
+    private exportScenes;
+    private createSceneYAML;
+    private addSceneSettings;
+    private createGameObjectHierarchy;
+    private addEntityComponents;
+    private addSpriteRenderer;
+    private addRigidbody2D;
+    private addBoxCollider2D;
+    private addCircleCollider2D;
+    private addAudioSource;
+    private addAnimator;
+    private addUIText;
+    private addUIImage;
+    private addUIButton;
+    private addParticleSystem;
+    private addScriptComponent;
+    private createTilemapGameObject;
+    private createTilemapLayer;
+    private exportMaterials;
+    private createMaterialYAML;
+    private exportAssets;
+    private exportSpriteAsset;
+    private exportAudioAsset;
+    private exportFontAsset;
+    private exportTilesetAsset;
+    private exportAnimationAsset;
+    private exportAssemblyDefinition;
+    private exportRuntimeBridge;
+    private exportPackageManifest;
+    private serializeUnityYAML;
+    private serializeYAMLObject;
+    private generateGuids;
+    private generateGUID;
+    private nextFileId;
+    private createMetaFile;
+    private createScriptMetaFile;
+    private parseColor;
+    private sanitizeFileName;
+    private toValidNamespace;
+    private getTextAlignment;
+}
+export default UnityExporter;

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

@@ -0,0 +1,58 @@
+import { PlatformExporter, type PlatformInfo, type NiceProject, type ExportOptions } from './PlatformExporter';
+export interface WebExportOptions {
+    /** Target framework */
+    framework: 'pixijs' | 'phaser' | 'threejs' | 'vanilla';
+    /** Use TypeScript instead of JavaScript */
+    typescript?: boolean;
+    /** Bundler to use */
+    bundler?: 'vite' | 'webpack' | 'parcel' | 'none';
+    /** Include PWA support */
+    pwa?: boolean;
+    /** Generate responsive design */
+    responsive?: boolean;
+    /** Enable hot reload for development */
+    hotReload?: boolean;
+    /** Framework version */
+    frameworkVersion?: string;
+}
+export declare class PixiJSExporter extends PlatformExporter {
+    readonly platformId: "pixijs";
+    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 exportScripts;
+    private exportAssetManifest;
+    private exportBundlerConfig;
+    private exportPWAFiles;
+    private exportUtilities;
+    private exportTSConfig;
+    private hexToNumber;
+    private sanitizeName;
+}
+export declare class PhaserExporter extends PlatformExporter {
+    readonly platformId: "phaser";
+    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 generateTilemapCode;
+    private getUsedAssets;
+    private exportScripts;
+    private exportBundlerConfig;
+    private exportTSConfig;
+    private sanitizeName;
+    private varName;
+}

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

@@ -0,0 +1,19 @@
+export { PlatformExporter, type PlatformId, type PlatformInfo, type PlatformFeature, type AssetType, type NiceProject, type ProjectSettings, type NiceScene, type NiceEntity, type NiceComponent, type NiceAsset, type NicePrefab, type NiceTilemap, type TilemapLayer, type ExportOptions, type ExportResult, type ExportedFile, type ExportError, type ExportWarning, type ExportStats, type DetectionResult, detectBestPlatform, registerPlatform, getPlatformInfo, getAllPlatforms, } from './PlatformExporter';
+export { UnityExporter, type UnityExportOptions } from './UnityExporter';
+export { GodotExporter, type GodotExportOptions } from './GodotExporter';
+export { PixiJSExporter, PhaserExporter, type WebExportOptions } from './WebExporter';
+export { ThreeJSExporter, type ThreeJSExportOptions } from './ThreeJSExporter';
+import type { PlatformId } from './PlatformExporter';
+import { PlatformExporter } from './PlatformExporter';
+/**
+ * Create an exporter instance for a given platform.
+ */
+export declare function createExporter(platform: PlatformId): PlatformExporter | null;
+/**
+ * Get list of all available exporters.
+ */
+export declare function getAvailableExporters(): PlatformId[];
+/**
+ * Check if an exporter is available for a platform.
+ */
+export declare function hasExporter(platform: PlatformId): boolean;

package/dist/types/import/AsepriteImporter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file AsepriteImporter.ts
+ * @description Import Aseprite sprite editor files (.aseprite, .ase)
+ * PRO-1.3: Scene Format Interoperability
+ *
+ * Supports:
+ * - Aseprite binary format (.aseprite, .ase)
+ * - Aseprite JSON export format
+ *
+ * Features:
+ * - Layers (normal, group, reference)
+ * - Frames and animation
+ * - Tags (animation clips)
+ * - Slices (9-slice, pivot)
+ * - Palette
+ * - Cel data
+ * - Blend modes
+ */
+import { SceneImporter, ImportOptions, ImportResult, ParsedScene, ParsedAsset, ImportError } from './SceneImporter';
+export declare class AsepriteImporter extends SceneImporter {
+    private aseFile;
+    constructor();
+    import(options: ImportOptions): Promise<ImportResult>;
+    parseFile(content: string | ArrayBuffer, filePath: string): Promise<ParsedScene | ParsedAsset | null>;
+    validate(sourcePath: string): Promise<ImportError[]>;
+    private parseJsonExport;
+    private parseBinaryFile;
+    private readHeader;
+    private readFrame;
+    private getFrameSize;
+    private processChunk;
+    private readLayerChunk;
+    private readCelChunk;
+    private readTagsChunk;
+    private readPaletteChunk;
+    private readSliceChunk;
+    private readExternalFilesChunk;
+    private readString;
+    private buildLayerHierarchy;
+    private createSpriteSheetFromBinary;
+    private createSpriteSheetAsset;
+    private createPaletteAsset;
+    private createSpriteScene;
+    private paletteColorToHex;
+    private readFile;
+}