sa2kit 1.1.0 → 1.2.0

package/dist/mmd/index.d.mts

@@ -1,346 +1,255 @@
+import { Vector3 } from 'three';
 import React__default from 'react';
 
-/**
- * MMD 资源配置
- */
+/** MMD 资源配置 */
 interface MMDResources {
-    /** 模型路径 */
+    /** 模型文件路径 (.pmx/.pmd) */
     modelPath: string;
-    /** 动作路径 */
+    /** 动作文件路径 (.vmd) - 可选 */
     motionPath?: string;
-    /** 相机路径 */
+    /** 相机动画路径 (.vmd) - 可选 */
     cameraPath?: string;
-    /** 音频路径 */
+    /** 音频文件路径 - 可选 */
     audioPath?: string;
-    /**
-     * 场景模型路径 (.pmx/.pmd)
-     * 通常是静态的 3D 场景模型，如教室、舞台等
-     */
+    /** 舞台/场景模型路径 (.pmx/.x) - 可选 */
     stageModelPath?: string;
-    /**
-     * 背景图片路径
-     * 支持 jpg/png 等图片格式，将作为 360度背景 (Equirectangular) 或固定背景
-     */
-    backgroundPath?: string;
+    /** 附加动作文件 - 可选 */
+    additionalMotions?: string[];
 }
-/**
- * MMD 资源配置项（用于动态切换）
- */
+/** 资源列表项 - 用于预设切换 */
 interface MMDResourceItem {
-    /** 配置项 ID */
     id: string;
-    /** 配置项名称 */
     name: string;
-    /** 资源配置 */
     resources: MMDResources;
-}
-/**
- * MMD 资源选项（用于下拉框选择）
- */
-interface MMDResourceOption {
-    /** 选项 ID */
-    id: string;
-    /** 选项名称 */
-    name: string;
-    /** 资源路径 */
-    path: string;
-}
-/**
- * MMD 播放列表节点
- * 代表一个完整的 MMD 播放配置（模型+动作+音乐+相机+场景+背景）
- */
-interface MMDPlaylistNode {
-    /** 节点 ID */
-    id: string;
-    /** 节点名称 */
-    name: string;
-    /** 节点描述（可选） */
+    thumbnail?: string;
     description?: string;
-    /** 资源配置 */
-    resources: MMDResources;
-    /** 是否循环播放当前节点（默认 false） */
-    loop?: boolean;
 }
-/**
- * MMD 播放列表配置
- */
-interface MMDPlaylistConfig {
-    /** 播放列表 ID */
+/** 资源选项 - 用于自由组合 */
+interface ResourceOption {
     id: string;
-    /** 播放列表名称 */
     name: string;
-    /** 播放列表描述（可选） */
-    description?: string;
-    /** 播放节点列表 */
-    nodes: MMDPlaylistNode[];
-    /** 是否循环播放整个列表（默认 false） */
-    loop?: boolean;
-    /** 是否自动播放（默认 true） */
-    autoPlay?: boolean;
+    path: string;
+    thumbnail?: string;
 }
-/**
- * MMD 资源选项列表（用于独立选择模型、动作、音乐、相机等）
- */
 interface MMDResourceOptions {
-    /** 模型选项列表 */
-    models?: MMDResourceOption[];
-    /** 动作选项列表 */
-    motions?: MMDResourceOption[];
-    /** 音频选项列表 */
-    audios?: MMDResourceOption[];
-    /** 相机选项列表 */
-    cameras?: MMDResourceOption[];
-    /** 场景模型选项列表 */
-    stageModels?: MMDResourceOption[];
-    /** 背景图片选项列表 */
-    backgrounds?: MMDResourceOption[];
+    models: ResourceOption[];
+    motions: ResourceOption[];
+    cameras?: ResourceOption[];
+    audios?: ResourceOption[];
+    stages?: ResourceOption[];
 }
-/**
- * MMD 舞台配置
- */
+/** 舞台/场景配置 */
 interface MMDStage {
-    /** 背景色 */
+    /** 背景颜色 */
     backgroundColor?: string;
-    /**
-     * 背景类型
-     * 'color': 纯色背景 (默认)
-     * 'image': 固定背景图片 (backgroundPath)
-     * 'skybox': 360度全景图 (backgroundPath)
-     * @default 'color'
-     */
-    backgroundType?: 'color' | 'image' | 'skybox';
+    /** 背景图片 URL */
+    backgroundImage?: string;
+    /** 是否启用物理模拟 (默认 true) */
+    enablePhysics?: boolean;
+    /** 物理引擎路径 (ammo.wasm.js 的路径) */
+    physicsPath?: string;
+    /** 是否启用阴影 (默认 true) */
+    enableShadow?: boolean;
+    /** 环境光强度 (默认 0.5) */
+    ambientLightIntensity?: number;
+    /** 方向光强度 (默认 0.8) */
+    directionalLightIntensity?: number;
     /** 相机初始位置 */
     cameraPosition?: {
         x: number;
         y: number;
         z: number;
-    };
-    /** 相机目标位置 */
+    } | Vector3;
+    /** 相机目标点 */
     cameraTarget?: {
         x: number;
         y: number;
         z: number;
-    };
-    /** 启用物理引擎 */
-    enablePhysics?: boolean;
-    /** 启用网格 */
-    showGrid?: boolean;
-    /** Ammo.js 脚本路径 */
-    ammoPath?: string;
-    /** Ammo WASM 文件的基础路径 */
-    ammoWasmPath?: string;
+    } | Vector3;
 }
-/**
- * 基础 MMD 播放器属性（原始API）
- */
-interface MMDPlayerBaseProps {
-    /**
-     * URL to the PMX model file
-     */
-    modelUrl: string;
-    /**
-     * URL to the VMD motion file for the model
-     */
-    vmdUrl?: string;
-    /**
-     * URL to the VMD motion file for the camera
-     */
-    cameraUrl?: string;
-    /**
-     * URL to the audio file (wav, mp3)
-     */
-    audioUrl?: string;
-    /**
-     * Whether to enable physics simulation (requires Ammo.js)
-     * @default true
-     */
-    physics?: boolean;
-    /**
-     * Width of the player
-     * @default '100%'
-     */
-    width?: string | number;
-    /**
-     * Height of the player
-     * @default '100%'
-     */
-    height?: string | number;
-    /**
-     * Callback when resources are loaded
-     */
-    onLoad?: () => void;
-    /**
-     * Callback for loading progress
-     */
-    onProgress?: (xhr: ProgressEvent) => void;
-    /**
-     * Callback for loading error
-     */
-    onError?: (error: unknown) => void;
+/** 移动端优化配置 */
+interface MobileOptimization {
+    /** 是否启用优化 (默认 true) */
+    enabled: boolean;
+    /** 像素比 (默认 1.0, 桌面端通常为 window.devicePixelRatio) */
+    pixelRatio?: number;
+    /** 是否强制关闭物理引擎 (默认 false) */
+    disablePhysics?: boolean;
+    /** 是否降低阴影质量 (默认 true) */
+    reduceShadowQuality?: boolean;
 }
-/**
- * MMD 播放列表组件属性
- */
-interface MMDPlaylistProps {
-    /** 播放列表配置 */
-    playlist: MMDPlaylistConfig;
+/** MMDPlayerBase Ref 接口 */
+interface MMDPlayerBaseRef {
+    /** 开始播放 */
+    play: () => void;
+    /** 暂停播放 */
+    pause: () => void;
+    /** 停止播放 (重置到开头) */
+    stop: () => void;
+    /** 跳转到指定时间 (秒) */
+    seek: (time: number) => void;
+    /** 获取当前播放时间 */
+    getCurrentTime: () => number;
+    /** 获取总时长 */
+    getDuration: () => number;
+    /** 获取播放状态 */
+    isPlaying: () => boolean;
+    /** 截图并返回 Base64 字符串 */
+    snapshot: () => string;
+}
+/** 基础播放器属性 */
+interface MMDPlayerBaseProps {
+    /** 资源配置 */
+    resources: MMDResources;
     /** 舞台配置 */
     stage?: MMDStage;
-    /** 默认播放的节点索引（默认 0） */
-    defaultNodeIndex?: number;
-    /** 自定义样式类名 */
+    /** 移动端优化配置 */
+    mobileOptimization?: MobileOptimization;
+    /** 播放控制 */
+    autoPlay?: boolean;
+    loop?: boolean;
+    volume?: number;
+    muted?: boolean;
+    /** 调试与辅助 */
+    showAxes?: boolean;
+    /** 事件回调 */
+    onLoad?: () => void;
+    onLoadProgress?: (progress: number, item: string) => void;
+    onError?: (error: Error) => void;
+    onPlay?: () => void;
+    onPause?: () => void;
+    onEnded?: () => void;
+    onTimeUpdate?: (time: number) => void;
+    /** 样式 */
     className?: string;
-    /** 自定义样式 */
     style?: React.CSSProperties;
-    /** 资源加载完成回调 */
-    onLoad?: () => void;
-    /** 资源加载错误回调 */
-    onError?: (error: any) => void;
-    /** 节点切换回调 */
-    onNodeChange?: (nodeIndex: number, node: MMDPlaylistNode) => void;
-    /** 播放列表完成回调 */
-    onPlaylistComplete?: () => void;
 }
-/**
- * 增强版 MMD 播放器属性（支持resources和stage配置）
- */
-interface MMDPlayerEnhancedProps {
-    /** MMD资源配置（单个） */
+/** 增强播放器属性 */
+interface MMDPlayerEnhancedProps extends Omit<MMDPlayerBaseProps, 'resources'> {
+    /** 单一资源模式 */
     resources?: MMDResources;
-    /** MMD资源配置列表（用于动态切换），如果提供则显示设置按钮 */
+    /** 列表模式资源 */
     resourcesList?: MMDResourceItem[];
-    /** 默认选中的资源ID（当使用 resourcesList 时） */
-    defaultResourceId?: string;
-    /** MMD资源选项列表（用于下拉框独立选择），如果提供则显示设置按钮 */
+    /** 自由组合模式选项 */
     resourceOptions?: MMDResourceOptions;
-    /** 默认选中的资源（当使用 resourceOptions 时） */
+    /** 列表模式下的默认 ID */
+    defaultResourceId?: string;
+    /** 自由组合模式下的默认选择 */
     defaultSelection?: {
         modelId?: string;
         motionId?: string;
-        audioId?: string;
         cameraId?: string;
-        stageModelId?: string;
-        backgroundId?: string;
+        audioId?: string;
+        stageId?: string;
     };
+    /** 是否显示调试信息面板 */
+    showDebugInfo?: boolean;
+}
+/** 播放列表节点 */
+interface MMDPlaylistNode {
+    id: string;
+    name: string;
+    resources: MMDResources;
+    /** 该节点是否循环播放 */
+    loop?: boolean;
+    /** 预计时长（秒）- 用于进度计算 */
+    duration?: number;
+    /** 缩略图 */
+    thumbnail?: string;
+}
+/** 播放列表配置 */
+interface MMDPlaylistConfig {
+    id: string;
+    name: string;
+    nodes: MMDPlaylistNode[];
+    /** 整个播放列表是否循环 */
+    loop?: boolean;
+    /** 预加载策略
+     * - 'none': 不预加载 (默认)
+     * - 'next': 预加载下一个节点
+     * - 'all': 预加载所有节点
+     */
+    preload?: 'none' | 'next' | 'all';
+    /** 是否自动播放 */
+    autoPlay?: boolean;
+}
+/** 播放列表组件属性 */
+interface MMDPlaylistProps {
+    /** 播放列表配置 */
+    playlist: MMDPlaylistConfig;
     /** 舞台配置 */
     stage?: MMDStage;
-    /** 自动播放 */
-    autoPlay?: boolean;
-    /** 循环播放 */
-    loop?: boolean;
-    /** 自定义类名 */
+    /** 移动端优化配置 */
+    mobileOptimization?: MobileOptimization;
+    /** 事件回调 */
+    onNodeChange?: (node: MMDPlaylistNode, index: number) => void;
+    onPlaylistComplete?: () => void;
+    onError?: (error: Error) => void;
+    /** 是否显示调试信息面板 */
+    showDebugInfo?: boolean;
+    /** 样式 */
     className?: string;
-    /** 自定义样式 */
     style?: React.CSSProperties;
-    /** 加载完成回调 */
-    onLoad?: () => void;
-    /** 错误回调 */
-    onError?: (error: Error) => void;
-    /** 资源切换回调（resourcesList 模式） */
-    onResourceChange?: (resourceId: string) => void;
-    /** 资源选择回调（resourceOptions 模式） */
-    onSelectionChange?: (selection: {
-        modelId?: string;
-        motionId?: string;
-        audioId?: string;
-        cameraId?: string;
-        stageModelId?: string;
-        backgroundId?: string;
-    }) => void;
-    /** 音频播放结束回调 */
-    onAudioEnded?: () => void;
-    /** 动画播放结束回调（当没有音频或音频先结束时） */
-    onAnimationEnded?: () => void;
 }
-/**
- * MMD 播放器属性（联合类型）
- */
-type MMDPlayerProps = MMDPlayerBaseProps | MMDPlayerEnhancedProps;
 
-declare const MMDPlayerBase: React__default.FC<MMDPlayerBaseProps>;
+declare const MMDPlayerBase: React__default.ForwardRefExoticComponent<MMDPlayerBaseProps & React__default.RefAttributes<MMDPlayerBaseRef>>;
 
-/**
- * 增强版 MMD 播放器组件
- * 支持通过 resources 和 stage 配置快速使用
- * 所有资源均从 public 目录加载，无需额外配置
- */
-declare const MMDPlayerEnhanced: React__default.ForwardRefExoticComponent<MMDPlayerEnhancedProps & React__default.RefAttributes<any>>;
+declare const MMDPlayerEnhanced: React__default.FC<MMDPlayerEnhancedProps>;
 
 /**
- * MMD 播放列表组件（预加载版本）
- *
- * 在初始化时预加载所有节点的资源，切换时无需加载页面，实现无缝切换
+ * MMDPlaylist - 播放列表管理器
  *
- * @example
- * ```tsx
- * const playlist = {
- *   id: 'my-playlist',
- *   name: '我的播放列表',
- *   nodes: [
- *     {
- *       id: 'node1',
- *       name: '第一个节点',
- *       resources: { modelPath: '...', motionPath: '...', audioPath: '...' }
- *     },
- *     {
- *       id: 'node2',
- *       name: '第二个节点',
- *       resources: { modelPath: '...', motionPath: '...', audioPath: '...' }
- *     }
- *   ],
- *   loop: true,
- *   autoPlay: true
- * };
- *
- * <MMDPlaylist playlist={playlist} />
- * ```
+ * 核心功能：
+ * - 管理多个播放节点
+ * - 实现无缝切换（通过 key 变化触发组件重新挂载）
+ * - 预加载策略 (none / next / all)
+ * - 智能内存回收
+ * - 播放列表 UI
  */
 declare const MMDPlaylist: React__default.FC<MMDPlaylistProps>;
 
-interface AmmoConfig {
-    /** Ammo.js 脚本路径（例如：'/mikutalking/libs/ammo.wasm.js'） */
-    scriptPath: string;
-    /** Ammo WASM 文件的基础路径（例如：'/mikutalking/libs/'） */
-    wasmBasePath: string;
+interface MMDPlayerEnhancedDebugInfoProps {
+    isPlaying: boolean;
+    isLooping: boolean;
+    isFullscreen: boolean;
+    showAxes: boolean;
+    isLoading: boolean;
+    currentResourceId?: string;
+    currentResourceName?: string;
+    mode: 'single' | 'list' | 'options';
+    totalResources: number;
 }
-/**
- * 加载 Ammo.js 物理引擎
- * @param config Ammo.js 配置，包含脚本路径和 WASM 基础路径
- */
-declare const loadAmmo: (config: AmmoConfig) => Promise<void>;
+declare const MMDPlayerEnhancedDebugInfo: React__default.FC<MMDPlayerEnhancedDebugInfoProps>;
 
-/**
- * MMD 预设配置
- */
-interface MMDPreset {
-    /** 预设ID */
-    id: string;
-    /** 预设名称 */
-    name: string;
-    /** 预设简介 */
-    summary: string;
-    /** 预设标签 */
-    badges?: string[];
-    /** 资源配置 */
-    resources: MMDResources;
-    /** 舞台配置 */
-    stage?: MMDStage;
+interface MMDPlaylistDebugInfoProps {
+    playlistName: string;
+    currentIndex: number;
+    currentNode: MMDPlaylistNode;
+    totalNodes: number;
+    isPlaying: boolean;
+    isListLooping: boolean;
+    isNodeLooping: boolean;
+    preloadStrategy: 'none' | 'next' | 'all';
+    isLoading: boolean;
+    isFullscreen: boolean;
+    showAxes: boolean;
+    preloadedNodes: number[];
 }
+declare const MMDPlaylistDebugInfo: React__default.FC<MMDPlaylistDebugInfoProps>;
+
 /**
- * 默认预设 - 仅模型
- */
-declare const defaultMMDPreset: MMDPreset;
-/**
- * 完整动画预设 - 模型+动作+相机+音频
- */
-declare const catchTheWavePreset: MMDPreset;
-/**
- * 简单模型预设
+ * Ammo.js 加载器
+ * 用于异步加载 Ammo.js 物理引擎 (WASM 版本)
  */
-declare const simpleModelPreset: MMDPreset;
+declare global {
+    interface Window {
+        Ammo: any;
+    }
+}
 /**
- * 所有可用的预设
+ * 加载 Ammo.js
+ * @param path Ammo.js (WASM wrapper) 的路径，默认为 '/libs/ammo.wasm.js'
  */
-declare const availableMMDPresets: MMDPreset[];
+declare const loadAmmo: (path?: string) => Promise<any>;
 
-export { type AmmoConfig, MMDPlayerBase, type MMDPlayerBaseProps, MMDPlayerEnhanced, type MMDPlayerEnhancedProps, type MMDPlayerProps, MMDPlaylist, type MMDPlaylistConfig, type MMDPlaylistNode, type MMDPlaylistProps, type MMDPreset, type MMDResourceItem, type MMDResourceOption, type MMDResourceOptions, type MMDResources, type MMDStage, availableMMDPresets, catchTheWavePreset, defaultMMDPreset, loadAmmo, simpleModelPreset };
+export { MMDPlayerBase, type MMDPlayerBaseProps, type MMDPlayerBaseRef, MMDPlayerEnhanced, MMDPlayerEnhancedDebugInfo, type MMDPlayerEnhancedProps, MMDPlaylist, type MMDPlaylistConfig, MMDPlaylistDebugInfo, type MMDPlaylistNode, type MMDPlaylistProps, type MMDResourceItem, type MMDResourceOptions, type MMDResources, type MMDStage, type MobileOptimization, type ResourceOption, loadAmmo };