@nice2dev/game-engine 1.0.2 → 1.0.3

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

@@ -0,0 +1,237 @@
+/**
+ * @file Live2DImporter.ts
+ * @description Live2D Cubism Model Importer
+ * PRO-1.3: Scene Format Interoperability
+ *
+ * Live2D is a technology for animating 2D characters.
+ * Supports Cubism 3.0+ model format.
+ *
+ * File Types:
+ * - *.model3.json - Model settings
+ * - *.moc3 - Model data (binary)
+ * - *.physics3.json - Physics settings
+ * - *.pose3.json - Pose settings
+ * - *.exp3.json - Expression settings
+ * - *.motion3.json - Motion data
+ * - *.cdi3.json - Display info
+ */
+import { SceneImporter, ImportOptions, ImportResult, ParsedScene, ImportError } from './SceneImporter';
+/** Live2D Model Settings (model3.json) */
+export interface L2DModelSettings {
+    Version: number;
+    FileReferences: L2DFileReferences;
+    Groups?: L2DGroup[];
+    HitAreas?: L2DHitArea[];
+}
+export interface L2DFileReferences {
+    Moc: string;
+    Textures: string[];
+    Physics?: string;
+    Pose?: string;
+    DisplayInfo?: string;
+    Expressions?: L2DExpressionRef[];
+    Motions?: Record<string, L2DMotionRef[]>;
+    UserData?: string;
+}
+export interface L2DExpressionRef {
+    Name: string;
+    File: string;
+}
+export interface L2DMotionRef {
+    File: string;
+    FadeInTime?: number;
+    FadeOutTime?: number;
+    Sound?: string;
+    MotionSync?: string;
+}
+export interface L2DGroup {
+    Target: 'Parameter' | 'Part';
+    Name: string;
+    Ids: string[];
+}
+export interface L2DHitArea {
+    Id: string;
+    Name: string;
+}
+/** Live2D Physics Settings (physics3.json) */
+export interface L2DPhysics {
+    Version: number;
+    Meta: L2DPhysicsMeta;
+    PhysicsSettings: L2DPhysicsSetting[];
+}
+export interface L2DPhysicsMeta {
+    PhysicsSettingCount: number;
+    TotalInputCount: number;
+    TotalOutputCount: number;
+    VertexCount: number;
+    EffectiveForces?: {
+        Gravity: {
+            X: number;
+            Y: number;
+        };
+        Wind: {
+            X: number;
+            Y: number;
+        };
+    };
+    PhysicsDictionary?: L2DPhysicsDictEntry[];
+}
+export interface L2DPhysicsDictEntry {
+    Id: string;
+    Name: string;
+}
+export interface L2DPhysicsSetting {
+    Id: string;
+    Input: L2DPhysicsInput[];
+    Output: L2DPhysicsOutput[];
+    Vertices: L2DPhysicsVertex[];
+    Normalization: L2DPhysicsNormalization;
+}
+export interface L2DPhysicsInput {
+    Source: L2DPhysicsParameter;
+    Weight: number;
+    Type: 'X' | 'Y' | 'Angle';
+    Reflect: boolean;
+}
+export interface L2DPhysicsOutput {
+    Destination: L2DPhysicsParameter;
+    VertexIndex: number;
+    Scale: number;
+    Weight: number;
+    Type: 'X' | 'Y' | 'Angle';
+    Reflect: boolean;
+}
+export interface L2DPhysicsParameter {
+    Target: 'Parameter' | 'Part';
+    Id: string;
+}
+export interface L2DPhysicsVertex {
+    Position: {
+        X: number;
+        Y: number;
+    };
+    Mobility: number;
+    Delay: number;
+    Acceleration: number;
+    Radius: number;
+}
+export interface L2DPhysicsNormalization {
+    Position: L2DPhysicsNormValue;
+    Angle: L2DPhysicsNormValue;
+}
+export interface L2DPhysicsNormValue {
+    Minimum: number;
+    Default: number;
+    Maximum: number;
+}
+/** Live2D Pose Settings (pose3.json) */
+export interface L2DPose {
+    Version: number;
+    Type: 'Live2D Pose';
+    FadeInTime?: number;
+    Groups: L2DPoseGroup[][];
+}
+export interface L2DPoseGroup {
+    Id: string;
+    Link?: string[];
+}
+/** Live2D Expression (exp3.json) */
+export interface L2DExpression {
+    Version: number;
+    Type: 'Live2D Expression';
+    FadeInTime?: number;
+    FadeOutTime?: number;
+    Parameters?: L2DExpressionParameter[];
+}
+export interface L2DExpressionParameter {
+    Id: string;
+    Value: number;
+    Blend?: 'Add' | 'Multiply' | 'Overwrite';
+}
+/** Live2D Motion (motion3.json) */
+export interface L2DMotion {
+    Version: number;
+    Meta: L2DMotionMeta;
+    Curves: L2DMotionCurve[];
+    UserData?: L2DUserDataEvent[];
+}
+export interface L2DMotionMeta {
+    Duration: number;
+    Fps: number;
+    Loop?: boolean;
+    AreBeziersRestricted?: boolean;
+    CurveCount: number;
+    TotalSegmentCount: number;
+    TotalPointCount: number;
+    UserDataCount?: number;
+    TotalUserDataSize?: number;
+}
+export interface L2DMotionCurve {
+    Target: 'Model' | 'Parameter' | 'PartOpacity';
+    Id: string;
+    FadeInTime?: number;
+    FadeOutTime?: number;
+    Segments: number[];
+}
+export interface L2DUserDataEvent {
+    Time: number;
+    Value: string;
+}
+/** Live2D Display Info (cdi3.json) */
+export interface L2DDisplayInfo {
+    Version: number;
+    Parameters?: L2DParameterInfo[];
+    ParameterGroups?: L2DParameterGroupInfo[];
+    Parts?: L2DPartInfo[];
+}
+export interface L2DParameterInfo {
+    Id: string;
+    GroupId?: string;
+    Name?: string;
+}
+export interface L2DParameterGroupInfo {
+    Id: string;
+    GroupId?: string;
+    Name?: string;
+}
+export interface L2DPartInfo {
+    Id: string;
+    Name?: string;
+}
+/** Live2D User Data */
+export interface L2DUserData {
+    Version: number;
+    Meta: {
+        UserDataCount: number;
+        TotalUserDataSize: number;
+    };
+    UserData: L2DUserDataEntry[];
+}
+export interface L2DUserDataEntry {
+    Target: 'ArtMesh' | 'DrawOrder';
+    Id: string;
+    Value: string;
+}
+export declare class Live2DImporter extends SceneImporter {
+    private model;
+    private physics;
+    private pose;
+    private displayInfo;
+    private expressions;
+    private motions;
+    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 loadDependencies;
+    private convertModelToScene;
+    private convertModelToParsed;
+    private convertMotionCurves;
+    private getSegmentTypes;
+    private countKeyframes;
+    private readFile;
+    private getBaseDirectory;
+    private extractFileName;
+}
+export declare function createLive2DImporter(): Live2DImporter;

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 {};