@nice2dev/game-engine 0.1.0 → 1.0.3

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

@@ -0,0 +1,387 @@
+/**
+ * @file NdgFormat.ts
+ * @description Nice2Dev Game (.ndg) Universal Format - Import/Export
+ * PRO-1.3: Scene Format Interoperability
+ *
+ * The .ndg format is Nice2Dev's native scene interchange format.
+ * Designed for:
+ * - Lossless round-trip conversion
+ * - Human-readable JSON structure
+ * - Full feature preservation
+ * - Version compatibility
+ *
+ * File Types:
+ * - .ndg - Single scene
+ * - .ndgp - Project with multiple scenes
+ * - .ndga - Asset bundle
+ */
+import { SceneImporter, ImportOptions, ImportResult, ParsedScene, ParsedAsset, ImportError, ImportSourceType } from './SceneImporter';
+import type { NiceProject, NiceScene, NiceAsset } from '../export/PlatformExporter';
+declare const NDG_MAGIC = "NDG1";
+export interface NdgFile {
+    /** Format magic identifier */
+    magic: typeof NDG_MAGIC;
+    /** Format version */
+    version: string;
+    /** File type */
+    type: 'scene' | 'project' | 'asset-bundle';
+    /** Creation timestamp */
+    created: string;
+    /** Last modified timestamp */
+    modified: string;
+    /** Generator info */
+    generator: NdgGenerator;
+    /** Original source info (if imported) */
+    source?: NdgSource;
+    /** File content */
+    content: NdgScene | NdgProject | NdgAssetBundle;
+}
+export interface NdgGenerator {
+    name: string;
+    version: string;
+    platform?: string;
+}
+export interface NdgSource {
+    /** Original format type */
+    type: ImportSourceType | 'unknown';
+    /** Original file path */
+    path: string;
+    /** Import timestamp */
+    importedAt: string;
+    /** Original format version */
+    formatVersion?: string;
+    /** Preserved original data */
+    originalData?: Record<string, unknown>;
+}
+export interface NdgProject {
+    /** Project name */
+    name: string;
+    /** Project description */
+    description?: string;
+    /** Project settings */
+    settings: NdgProjectSettings;
+    /** All scenes */
+    scenes: NdgScene[];
+    /** All assets */
+    assets: NdgAsset[];
+    /** Global scripts */
+    scripts?: NdgScript[];
+    /** Project metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface NdgProjectSettings {
+    /** Default resolution */
+    width: number;
+    height: number;
+    /** Target frame rate */
+    targetFPS?: number;
+    /** Physics settings */
+    physics?: NdgPhysicsSettings;
+    /** Audio settings */
+    audio?: NdgAudioSettings;
+    /** Rendering settings */
+    rendering?: NdgRenderingSettings;
+    /** Input mappings */
+    input?: NdgInputSettings;
+    /** Custom settings */
+    custom?: Record<string, unknown>;
+}
+export interface NdgPhysicsSettings {
+    gravity: {
+        x: number;
+        y: number;
+    };
+    velocityIterations: number;
+    positionIterations: number;
+    timeStep: number;
+    pixelsPerMeter?: number;
+}
+export interface NdgAudioSettings {
+    masterVolume: number;
+    musicVolume: number;
+    sfxVolume: number;
+    audioChannels: number;
+}
+export interface NdgRenderingSettings {
+    pixelPerfect: boolean;
+    antialiasing: boolean;
+    vsync: boolean;
+    maxFPS?: number;
+    backgroundColor: string;
+}
+export interface NdgInputSettings {
+    actions: NdgInputAction[];
+}
+export interface NdgInputAction {
+    name: string;
+    keys?: string[];
+    gamepadButtons?: number[];
+    mouseButtons?: number[];
+}
+export interface NdgScene {
+    /** Scene ID */
+    id: string;
+    /** Scene name */
+    name: string;
+    /** Scene settings */
+    settings: NdgSceneSettings;
+    /** All entities */
+    entities: NdgEntity[];
+    /** Layers definition */
+    layers?: NdgLayerDef[];
+    /** Tilemaps */
+    tilemaps?: NdgTilemap[];
+    /** Scene-level scripts */
+    scripts?: NdgScript[];
+    /** Scene metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface NdgSceneSettings {
+    width: number;
+    height: number;
+    backgroundColor: string;
+    gravity?: {
+        x: number;
+        y: number;
+    };
+    bounds?: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    camera?: NdgCameraSettings;
+    lighting?: NdgLightingSettings;
+}
+export interface NdgCameraSettings {
+    zoom: number;
+    bounds?: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    followTarget?: string;
+    smoothing?: number;
+}
+export interface NdgLightingSettings {
+    ambientColor: string;
+    ambientIntensity: number;
+}
+export interface NdgLayerDef {
+    id: string;
+    name: string;
+    zIndex: number;
+    visible: boolean;
+    locked: boolean;
+    parallax?: {
+        x: number;
+        y: number;
+    };
+    properties?: Record<string, unknown>;
+}
+export interface NdgEntity {
+    /** Entity ID */
+    id: string;
+    /** Entity name */
+    name: string;
+    /** Active state */
+    active: boolean;
+    /** Tags */
+    tags: string[];
+    /** Layer reference */
+    layer?: string;
+    /** Transform */
+    transform: NdgTransform;
+    /** Components */
+    components: NdgComponent[];
+    /** Children */
+    children: NdgEntity[];
+    /** Prefab reference */
+    prefab?: NdgPrefabRef;
+    /** Entity metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface NdgTransform {
+    position: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    rotation: number | {
+        x: number;
+        y: number;
+        z: number;
+    };
+    scale: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+}
+export interface NdgComponent {
+    /** Component type */
+    type: string;
+    /** Enabled state */
+    enabled: boolean;
+    /** Component data */
+    data: Record<string, unknown>;
+    /** Script reference (for script components) */
+    script?: NdgScriptRef;
+}
+export interface NdgPrefabRef {
+    id: string;
+    path?: string;
+    overrides?: NdgPrefabOverride[];
+}
+export interface NdgPrefabOverride {
+    path: string;
+    value: unknown;
+}
+export interface NdgScript {
+    id: string;
+    name: string;
+    language: 'typescript' | 'javascript' | 'gdscript' | 'lua' | 'csharp' | 'visual';
+    source: string;
+    compiled?: string;
+    dependencies?: string[];
+}
+export interface NdgScriptRef {
+    id: string;
+    path?: string;
+    parameters?: Record<string, unknown>;
+}
+export interface NdgTilemap {
+    id: string;
+    name: string;
+    tilesetId: string;
+    width: number;
+    height: number;
+    tileWidth: number;
+    tileHeight: number;
+    layers: NdgTilemapLayer[];
+}
+export interface NdgTilemapLayer {
+    id: string;
+    name: string;
+    data: number[];
+    visible: boolean;
+    opacity: number;
+    collisionEnabled?: boolean;
+}
+export interface NdgAsset {
+    /** Asset ID */
+    id: string;
+    /** Asset name */
+    name: string;
+    /** Asset type */
+    type: 'texture' | 'audio' | 'font' | 'shader' | 'animation' | 'tileset' | 'prefab' | 'script' | 'data';
+    /** File path */
+    path: string;
+    /** Import settings */
+    importSettings?: NdgAssetImportSettings;
+    /** Asset-specific data */
+    data?: Record<string, unknown>;
+    /** Asset metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface NdgAssetImportSettings {
+    compression?: 'none' | 'lz4' | 'zstd';
+    filterMode?: 'point' | 'bilinear' | 'trilinear';
+    wrapMode?: 'clamp' | 'repeat' | 'mirror';
+    generateMipmaps?: boolean;
+    maxSize?: number;
+    loadType?: 'decompress-on-load' | 'compressed-in-memory' | 'streaming';
+    quality?: number;
+    frameRate?: number;
+    loop?: boolean;
+}
+export interface NdgAssetBundle {
+    name: string;
+    assets: NdgAsset[];
+    compression?: 'none' | 'lz4' | 'zstd';
+}
+export declare class NdgImporter extends SceneImporter {
+    private ndgFile;
+    constructor();
+    canHandle(filePath: string): boolean;
+    import(options: ImportOptions): Promise<ImportResult>;
+    parseFile(content: string | ArrayBuffer, filePath: string): Promise<ParsedScene | ParsedAsset | null>;
+    validate(sourcePath: string): Promise<ImportError[]>;
+    private convertNdgSceneToNice;
+    private convertNdgEntityToNice;
+    private convertNdgAssetToNice;
+    private convertNdgSceneToParsed;
+    private convertNdgEntityToParsed;
+    private readFile;
+}
+export declare class NdgExporter {
+    private generatorName;
+    private generatorVersion;
+    /**
+     * Export a single scene to NDG format
+     */
+    exportScene(scene: NiceScene, source?: NdgSource): NdgFile;
+    /**
+     * Export a full project to NDG format
+     */
+    exportProject(project: NiceProject): NdgFile;
+    /**
+     * Export an asset bundle to NDG format
+     */
+    exportAssetBundle(name: string, assets: NiceAsset[]): NdgFile;
+    /**
+     * Serialize NDG file to JSON string
+     */
+    serialize(ndgFile: NdgFile, pretty?: boolean): string;
+    private convertNiceSceneToNdg;
+    private convertNiceEntityToNdg;
+    private convertNiceProjectToNdg;
+    private convertNiceAssetToNdg;
+    private extractMetadata;
+}
+export declare class NdgBidirectionalSync {
+    private importer;
+    private exporter;
+    /**
+     * Import and track original data for round-trip
+     */
+    importWithTracking(sourcePath: string, sourceType: ImportSourceType): Promise<{
+        scenes: NiceScene[];
+        assets: NiceAsset[];
+        source: NdgSource;
+    }>;
+    /**
+     * Export with source tracking for later re-import
+     */
+    exportWithTracking(scene: NiceScene, source?: NdgSource): string;
+    /**
+     * Check if NDG file has modifications compared to source
+     */
+    hasModifications(ndgFile: NdgFile): boolean;
+    /**
+     * Update the modified timestamp
+     */
+    touch(ndgFile: NdgFile): NdgFile;
+}
+/**
+ * Create NDG importer
+ */
+export declare function createNdgImporter(): NdgImporter;
+/**
+ * Create NDG exporter
+ */
+export declare function createNdgExporter(): NdgExporter;
+/**
+ * Create bidirectional sync helper
+ */
+export declare function createBidirectionalSync(): NdgBidirectionalSync;
+/**
+ * Quick export scene to NDG JSON string
+ */
+export declare function sceneToNdg(scene: NiceScene, pretty?: boolean): string;
+/**
+ * Quick import NDG JSON string to scene
+ */
+export declare function ndgToScene(ndgJson: string): Promise<NiceScene | null>;
+export {};

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

@@ -0,0 +1,237 @@
+/**
+ * @file OgmoImporter.ts
+ * @description OGMO Editor Level Importer
+ * PRO-1.3: Scene Format Interoperability
+ *
+ * OGMO Editor is a free, open-source 2D level editor.
+ * Supports OGMO 3 format (JSON-based).
+ *
+ * File Types:
+ * - .ogmo - Project file
+ * - .json - Level file (usually named *.ogmo.json or just *.json)
+ */
+import { SceneImporter, ImportOptions, ImportResult, ParsedScene, ImportError } from './SceneImporter';
+/** OGMO 3 Project File */
+export interface OgmoProject {
+    name: string;
+    ogmoVersion: string;
+    levelPaths?: string[];
+    backgroundColor: string;
+    gridColor: string;
+    anglesRadians: boolean;
+    directoryDepth: number;
+    layerGridDefaultSize: {
+        x: number;
+        y: number;
+    };
+    levelDefaultSize: {
+        x: number;
+        y: number;
+    };
+    levelMinSize: {
+        x: number;
+        y: number;
+    };
+    levelMaxSize: {
+        x: number;
+        y: number;
+    };
+    levelNamePattern?: string;
+    levelValues?: OgmoValueDef[];
+    defaultExportMode: string;
+    compactExport: boolean;
+    externalScript?: string;
+    playCommand?: string;
+    entityTags?: string[];
+    layers: OgmoLayerDef[];
+    entities: OgmoEntityDef[];
+    tilesets: OgmoTilesetDef[];
+}
+/** OGMO Layer Definition */
+export interface OgmoLayerDef {
+    name: string;
+    gridSize: {
+        x: number;
+        y: number;
+    };
+    exportID: string;
+    definition: 'tile' | 'entity' | 'decal';
+    /** For tile layers */
+    tileset?: string;
+    /** For entity layers */
+    requiredTags?: string[];
+    excludedTags?: string[];
+    /** For decal layers */
+    folder?: string;
+    scaleable?: boolean;
+    rotatable?: boolean;
+    tintable?: boolean;
+}
+/** OGMO Entity Definition */
+export interface OgmoEntityDef {
+    name: string;
+    exportID: string;
+    limit: number;
+    size: {
+        x: number;
+        y: number;
+    };
+    origin: {
+        x: number;
+        y: number;
+    };
+    originAnchored: boolean;
+    shape: OgmoEntityShape;
+    color: string;
+    tileX: boolean;
+    tileY: boolean;
+    tileSize: {
+        x: number;
+        y: number;
+    };
+    resizeableX: boolean;
+    resizeableY: boolean;
+    rotatable: boolean;
+    rotationDegrees: number;
+    canFlipX: boolean;
+    canFlipY: boolean;
+    canSetColor: boolean;
+    hasNodes: boolean;
+    nodeLimit: number;
+    nodeDisplay: 'path' | 'circuit' | 'fan' | 'none';
+    nodeGhost: boolean;
+    tags: string[];
+    values: OgmoValueDef[];
+    texture?: string;
+    textureX?: number;
+    textureY?: number;
+}
+export type OgmoEntityShape = {
+    label: 'Rectangle' | 'Ellipse' | 'Cross' | 'Diamond' | 'Octagon' | 'Point';
+} | {
+    label: 'Ellipse';
+} | {
+    label: 'Cross';
+} | {
+    label: 'Diamond';
+} | {
+    label: 'Octagon';
+} | {
+    label: 'Point';
+};
+/** OGMO Tileset Definition */
+export interface OgmoTilesetDef {
+    name: string;
+    path: string;
+    image: string;
+    tileWidth: number;
+    tileHeight: number;
+    tileSeparationX: number;
+    tileSeparationY: number;
+}
+/** OGMO Value Definition (custom properties) */
+export interface OgmoValueDef {
+    name: string;
+    definition: 'Bool' | 'Int' | 'Float' | 'String' | 'Text' | 'Enum' | 'Color' | 'FilePath';
+    defaults: unknown;
+    bounded?: boolean;
+    min?: number;
+    max?: number;
+    choices?: string[];
+}
+/** OGMO 3 Level File */
+export interface OgmoLevel {
+    ogmoVersion: string;
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
+    values?: Record<string, unknown>;
+    layers: OgmoLayerInstance[];
+}
+/** OGMO Layer Instance */
+export interface OgmoLayerInstance {
+    name: string;
+    _eid: string;
+    offsetX: number;
+    offsetY: number;
+    gridCellWidth: number;
+    gridCellHeight: number;
+    gridCellsX: number;
+    gridCellsY: number;
+    /** Tile layers */
+    tileset?: string;
+    data?: number[];
+    data2D?: number[][];
+    dataCoords?: Array<[number, number]>;
+    dataCoords2D?: Array<Array<[number, number]>>;
+    exportMode?: '1D' | '2D' | 'CSV' | 'Coords (1D)' | 'Coords (2D)';
+    arrayMode?: '1D' | '2D';
+    /** Entity layers */
+    entities?: OgmoEntityInstance[];
+    /** Decal layers */
+    decals?: OgmoDecalInstance[];
+    /** Grid layer (for collision/pathfinding) */
+    grid?: string[];
+    grid2D?: string[][];
+}
+/** OGMO Entity Instance */
+export interface OgmoEntityInstance {
+    name: string;
+    id: number;
+    _eid: string;
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+    originX?: number;
+    originY?: number;
+    rotation?: number;
+    flippedX?: boolean;
+    flippedY?: boolean;
+    color?: string;
+    nodes?: Array<{
+        x: number;
+        y: number;
+    }>;
+    values?: Record<string, unknown>;
+}
+/** OGMO Decal Instance */
+export interface OgmoDecalInstance {
+    x: number;
+    y: number;
+    texture: string;
+    scaleX?: number;
+    scaleY?: number;
+    rotation?: number;
+    color?: string;
+    originX?: number;
+    originY?: number;
+}
+export declare class OgmoImporter extends SceneImporter {
+    private project;
+    private entityDefs;
+    private tilesetDefs;
+    private layerDefs;
+    constructor();
+    canHandle(filePath: string): boolean;
+    import(options: ImportOptions): Promise<ImportResult>;
+    parseFile(content: string | ArrayBuffer, filePath: string): Promise<ParsedScene | null>;
+    validate(sourcePath: string): Promise<ImportError[]>;
+    private isProjectFile;
+    private isLevelFile;
+    private indexDefinitions;
+    private convertLevelToScene;
+    private convertLevelToParsed;
+    private convertLayer;
+    private convertLayerToParsed;
+    private convertTileLayer;
+    private convertEntity;
+    private convertEntityToParsed;
+    private convertDecal;
+    private convertGridLayer;
+    private readFile;
+    private resolvePath;
+    private extractFileName;
+}
+export declare function createOgmoImporter(): OgmoImporter;