sa2kit 1.6.14 → 1.6.16

package/dist/mmd/index.d.mts

@@ -974,6 +974,10 @@ interface MMDVisualNovelProps {
     showAutoButton?: boolean;
     /** 是否显示历史记录按钮 */
     showHistoryButton?: boolean;
+    /** 自定义设置面板内容 */
+    customSettingsContent?: React.ReactNode;
+    /** 自定义关于面板内容 */
+    customAboutContent?: React.ReactNode;
     /** 样式 */
     className?: string;
     style?: React.CSSProperties;
@@ -1041,6 +1045,8 @@ interface MMDVisualNovelRef {
     setAutoMode: (enabled: boolean) => void;
     /** 跳过当前打字动画 */
     skipTyping: () => void;
+    /** 触发视觉特效 */
+    triggerEffect?: (effect: VisualEffect) => void;
 }
 
 /**
@@ -1055,6 +1061,105 @@ interface MMDVisualNovelRef {
  */
 declare const MMDVisualNovel: React__default.ForwardRefExoticComponent<MMDVisualNovelProps & React__default.RefAttributes<MMDVisualNovelRef>>;
 
+/** 模型选项 */
+interface ModelOption {
+    /** 唯一标识 */
+    id: string;
+    /** 显示名称 */
+    name: string;
+    /** 模型路径 */
+    path: string | string[];
+    /** 缩略图（可选） */
+    thumbnail?: string;
+}
+/** 模型选择器设置属性 */
+interface ModelSelectorSettingsProps {
+    /** 人物模型选项列表 */
+    characterModels: ModelOption[];
+    /** 场景模型选项列表 */
+    stageModels: ModelOption[];
+    /** 当前选中的人物模型 ID */
+    selectedCharacterId: string;
+    /** 当前选中的场景模型 ID */
+    selectedStageId: string;
+    /** 人物模型选择变化回调 */
+    onCharacterChange: (id: string) => void;
+    /** 场景模型选择变化回调 */
+    onStageChange: (id: string) => void;
+    /** 人物模型标签文字 */
+    characterLabel?: string;
+    /** 场景模型标签文字 */
+    stageLabel?: string;
+}
+/**
+ * ModelSelectorSettings - 模型选择器设置组件
+ *
+ * 用于在设置界面中选择人物模型和场景模型
+ */
+declare const ModelSelectorSettings: React__default.FC<ModelSelectorSettingsProps>;
+
+/** 模型选择器配置 */
+interface ModelSelectorConfig {
+    /** 人物模型选项列表 */
+    characterModels: ModelOption[];
+    /** 场景模型选项列表 */
+    stageModels: ModelOption[];
+    /** 默认选中的人物模型 ID（不提供则使用第一个） */
+    defaultCharacterId?: string;
+    /** 默认选中的场景模型 ID（不提供则使用第一个） */
+    defaultStageId?: string;
+    /** 人物模型标签文字 */
+    characterLabel?: string;
+    /** 场景模型标签文字 */
+    stageLabel?: string;
+}
+/** 带模型选择器的视觉小说组件属性 */
+interface MMDVisualNovelWithSelectorProps extends Omit<MMDVisualNovelProps, 'script'> {
+    /** 基础剧本配置（模型路径会被选择器覆盖） */
+    script: VisualNovelScript;
+    /** 模型选择器配置 */
+    modelSelector: ModelSelectorConfig;
+    /** 模型选择变化回调 */
+    onModelSelectionChange?: (characterId: string, stageId: string) => void;
+}
+/** 带模型选择器的视觉小说组件 Ref 接口 */
+interface MMDVisualNovelWithSelectorRef extends MMDVisualNovelRef {
+    /** 获取当前选中的人物模型 ID */
+    getSelectedCharacterId: () => string;
+    /** 获取当前选中的场景模型 ID */
+    getSelectedStageId: () => string;
+    /** 设置人物模型 */
+    setCharacterModel: (id: string) => void;
+    /** 设置场景模型 */
+    setStageModel: (id: string) => void;
+}
+/**
+ * MMDVisualNovelWithSelector - 带模型选择器的视觉小说组件
+ *
+ * 功能特性：
+ * - 在设置界面中提供人物模型和场景模型的下拉选择器
+ * - 选择的模型会应用到剧本中的所有节点
+ * - 完全兼容 MMDVisualNovel 的所有功能
+ *
+ * 使用示例：
+ * ```tsx
+ * <MMDVisualNovelWithSelector
+ *   script={myScript}
+ *   modelSelector={{
+ *     characterModels: [
+ *       { id: 'miku', name: '初音未来', path: '/models/miku.pmx' },
+ *       { id: 'luka', name: '巡音流歌', path: '/models/luka.pmx' },
+ *     ],
+ *     stageModels: [
+ *       { id: 'stage1', name: '教室', path: '/stages/classroom.pmx' },
+ *       { id: 'stage2', name: '公园', path: '/stages/park.pmx' },
+ *     ],
+ *   }}
+ * />
+ * ```
+ */
+declare const MMDVisualNovelWithSelector: React__default.ForwardRefExoticComponent<MMDVisualNovelWithSelectorProps & React__default.RefAttributes<MMDVisualNovelWithSelectorRef>>;
+
 /**
  * DialogueBox - Galgame 风格对话框组件
  *
@@ -1102,6 +1207,10 @@ interface LoadingOverlayProps {
     onStart?: () => void;
     /** 自定义类名 */
     className?: string;
+    /** 自定义设置面板内容 */
+    customSettingsContent?: React__default.ReactNode;
+    /** 自定义关于面板内容 */
+    customAboutContent?: React__default.ReactNode;
 }
 /**
  * LoadingOverlay - 加载遮罩和开始界面组件容器
@@ -1141,6 +1250,10 @@ interface StartScreenProps {
     onStart?: () => void;
     /** 自定义类名 */
     className?: string;
+    /** 自定义设置面板内容 */
+    customSettingsContent?: React__default.ReactNode;
+    /** 自定义关于面板内容 */
+    customAboutContent?: React__default.ReactNode;
 }
 /**
  * StartScreen - 开始界面组件
@@ -1333,9 +1446,52 @@ interface TrackInfoProps {
 }
 declare const TrackInfo: React__default.FC<TrackInfoProps>;
 
+/**
+ * AR 模式枚举
+ */
+declare enum ARMode {
+    /**
+     * 叠加模式 - 模型固定在屏幕上，跟随屏幕移动
+     * 特点：简单易用，不需要陀螺仪权限
+     */
+    Overlay = "overlay",
+    /**
+     * 世界固定模式 - 真正的 AR 体验
+     * 特点：模型固定在世界空间，移动设备时模型保持原位
+     * 需要：设备陀螺仪/加速度计权限
+     */
+    WorldFixed = "world-fixed"
+}
+/** 预设模型配置 */
+interface ModelPreset {
+    /** 预设ID */
+    id: string;
+    /** 显示名称 */
+    name: string;
+    /** 缩略图URL */
+    thumbnail?: string;
+    /** 模型路径 (.pmx) */
+    modelPath: string;
+}
+/** 预设动作配置 */
+interface MotionPreset {
+    /** 预设ID */
+    id: string;
+    /** 显示名称 */
+    name: string;
+    /** 动作路径 (.vmd) */
+    motionPath: string;
+}
+/** 预设音乐配置 */
+interface AudioPreset {
+    /** 预设ID */
+    id: string;
+    /** 显示名称 */
+    name: string;
+    /** 音乐路径 */
+    audioPath: string;
+}
 interface MMDARPlayerProps {
-    /** MMD 资源配置 */
-    resources: MMDResources;
     /** 舞台配置 */
     stage?: MMDStage;
     /** 移动端优化配置 */
@@ -1358,8 +1514,28 @@ interface MMDARPlayerProps {
     };
     /** 是否开启镜像显示 (通常前置摄像头需要开启) */
     mirrored?: boolean;
-    /** 是否显示设置按钮 (允许手动输入模型和动作路径) */
+    /** 是否显示设置按钮 */
     showSettings?: boolean;
+    /** 预设模型列表 */
+    modelPresets: ModelPreset[];
+    /** 预设动作列表 */
+    motionPresets: MotionPreset[];
+    /** 预设音乐列表 (可选) */
+    audioPresets?: AudioPreset[];
+    /** 默认模型ID */
+    defaultModelId?: string;
+    /** 默认动作ID */
+    defaultMotionId?: string;
+    /** 默认音乐ID (可选) */
+    defaultAudioId?: string;
+    /** 初始时是否显示模型 (false 则需要点击放置) */
+    initialModelVisible?: boolean;
+    /** 放置按钮文案 */
+    placementText?: string;
+    /** AR 模式 (默认 Overlay) */
+    arMode?: ARMode;
+    /** 默认 AR 模式 */
+    defaultARMode?: ARMode;
     /** 播放控制 */
     autoPlay?: boolean;
     loop?: boolean;
@@ -1367,6 +1543,8 @@ interface MMDARPlayerProps {
     onCameraReady?: (stream: MediaStream) => void;
     onCameraError?: (error: Error) => void;
     onResourcesChange?: (resources: MMDResources) => void;
+    onModelPlaced?: () => void;
+    onARModeChange?: (mode: ARMode) => void;
     onLoad?: () => void;
     onError?: (error: Error) => void;
     /** 样式 */
@@ -1382,6 +1560,16 @@ interface MMDARPlayerRef {
     switchCamera: () => Promise<void>;
     /** 截图 (包含视频背景和模型) */
     snapshot: () => Promise<string>;
+    /** 放置模型 */
+    placeModel: () => void;
+    /** 移除模型（重置位置） */
+    removeModel: () => void;
+    /** 切换模型 */
+    switchModel: (resources: MMDResources) => void;
+    /** 切换 AR 模式 */
+    setARMode: (mode: ARMode) => void;
+    /** 获取当前 AR 模式 */
+    getARMode: () => ARMode;
 }
 
 /**
@@ -1389,9 +1577,9 @@ interface MMDARPlayerRef {
  *
  * 功能：
  * - 调用设备摄像头作为背景
- * - 叠加透明背景的 MMD 模型渲染
- * - 支持前后摄像头切换
- * - 针对 AR 场景优化模型光照与定位
+ * - 点击放置模型交互
+ * - 支持两种 AR 模式：叠加模式 / 世界固定模式
+ * - 世界固定模式使用设备陀螺仪实现真正的 AR 体验
  */
 declare const MMDARPlayer: React__default.ForwardRefExoticComponent<MMDARPlayerProps & React__default.RefAttributes<MMDARPlayerRef>>;
 
@@ -2208,4 +2396,4 @@ interface FXThreePreviewProps {
 }
 declare const FXThreePreview: React__default.FC<FXThreePreviewProps>;
 
-export { type BranchCondition, CheerButton, type CheerButtonProps, CheerParticles, type CheerParticlesProps, type CheerParticlesRef, ChoiceMenu, type ChoiceMenuProps, DialogueBox, type DialogueBoxProps, type DialogueBoxTheme, type DialogueChoice, type DialogueHistoryItem, type DialogueLine, type EffectFileType, type FXComment, type FXController, type FXDefine, type FXEffect, type FXFileConfig, type FXMergeStrategy, type FXParameter, FXParser, type FXParserOptions, type FXPass, type FXShaderFunction, type FXStaticVariable, type FXSummary, type FXTechnique, type FXTexture, FXThreePreview, type FXThreePreviewProps, FXToThreeAdapter, FXViewer, type FXViewerProps, type GLSLShader, type GLSLShaders, HLSLToGLSLConverter, HistoryPanel, LoadingOverlay, type LoadingOverlayProps, LoadingScreen, type LoadingScreenProps, LoopConfirmDialog, MMDARPlayer, type MMDARPlayerProps, type MMDARPlayerRef, type MMDDiagnosticReport, MMDLightingDebugPanel, type MMDLightingDebugPanelProps, type MMDLightingParams, type MMDLoaderConfig, MMDMusicPlayer, type MMDMusicPlayerConfig, type MMDMusicPlayerProps, type MMDMusicPlayerRef, MMDPlayerBase, MMDPlayerBaseProps, MMDPlayerBaseRef, MMDPlayerEnhanced, MMDPlayerEnhancedDebugInfo, MMDPlayerEnhancedProps, MMDPlaylist, MMDPlaylistDebugInfo, MMDPlaylistNode, MMDPlaylistProps, MMDResources, type MMDSceneRefs, MMDStage, MMDVisualNovel, type MMDVisualNovelProps, type MMDVisualNovelRef, type MaterialTextureMapping, MobileOptimization, MultiFXAdapter, type MultiFXAdapterOptions, MusicControls, type MusicControlsProps, type MusicTrack, PMXEditor, PMXEditor$1 as PMXEditorCore, type PMXEditorProps, PMXExporter, type PMXHeader, type PMXMaterial, type PMXModelInfo, type PMXParseResult, PMXParser, type PMXTexture, type PMXVertex, PMXViewer, type PMXViewerProps, PlaylistPanel, type PlaylistPanelProps, type SphereTextureDiagnostic, StartScreen, type StartScreenProps, type ThreeMaterialConfig, type ThreeRenderConfig, TrackInfo, type TrackInfoProps, type VisualEffect, type VisualNovelNode, type VisualNovelScript, addDefaultSphereTextures, checkModelSphereDefinition, checkSphereTextures, compareFXEffects, configureMaterialsForMMD, configureRendererForMMD, createMMDLights, diagnoseMaterialsMMD, exportFXToJSON, exportFXToMarkdown, extractTexturePaths, filterDefinesByPrefix, fullSphereDiagnostic, generateAllToonTextures, generateToonTexture, getColorParameters, getConfigSummaryText, getFeatureFlags, getTextureDefines, hasFeature, inspectMaterial, listAllMaterials, loadAmmo, printDiagnosticReport, printModelSphereInfo, printSphereDiagnostic, quickDiagnose, validateFXEffect };
+export { ARMode, type AudioPreset, type BranchCondition, CheerButton, type CheerButtonProps, CheerParticles, type CheerParticlesProps, type CheerParticlesRef, ChoiceMenu, type ChoiceMenuProps, DialogueBox, type DialogueBoxProps, type DialogueBoxTheme, type DialogueChoice, type DialogueHistoryItem, type DialogueLine, type EffectFileType, type FXComment, type FXController, type FXDefine, type FXEffect, type FXFileConfig, type FXMergeStrategy, type FXParameter, FXParser, type FXParserOptions, type FXPass, type FXShaderFunction, type FXStaticVariable, type FXSummary, type FXTechnique, type FXTexture, FXThreePreview, type FXThreePreviewProps, FXToThreeAdapter, FXViewer, type FXViewerProps, type GLSLShader, type GLSLShaders, HLSLToGLSLConverter, HistoryPanel, LoadingOverlay, type LoadingOverlayProps, LoadingScreen, type LoadingScreenProps, LoopConfirmDialog, MMDARPlayer, type MMDARPlayerProps, type MMDARPlayerRef, type MMDDiagnosticReport, MMDLightingDebugPanel, type MMDLightingDebugPanelProps, type MMDLightingParams, type MMDLoaderConfig, MMDMusicPlayer, type MMDMusicPlayerConfig, type MMDMusicPlayerProps, type MMDMusicPlayerRef, MMDPlayerBase, MMDPlayerBaseProps, MMDPlayerBaseRef, MMDPlayerEnhanced, MMDPlayerEnhancedDebugInfo, MMDPlayerEnhancedProps, MMDPlaylist, MMDPlaylistDebugInfo, MMDPlaylistNode, MMDPlaylistProps, MMDResources, type MMDSceneRefs, MMDStage, MMDVisualNovel, type MMDVisualNovelProps, type MMDVisualNovelRef, MMDVisualNovelWithSelector, type MMDVisualNovelWithSelectorProps, type MMDVisualNovelWithSelectorRef, type MaterialTextureMapping, MobileOptimization, type ModelOption, type ModelPreset, type ModelSelectorConfig, ModelSelectorSettings, type ModelSelectorSettingsProps, type MotionPreset, MultiFXAdapter, type MultiFXAdapterOptions, MusicControls, type MusicControlsProps, type MusicTrack, PMXEditor, PMXEditor$1 as PMXEditorCore, type PMXEditorProps, PMXExporter, type PMXHeader, type PMXMaterial, type PMXModelInfo, type PMXParseResult, PMXParser, type PMXTexture, type PMXVertex, PMXViewer, type PMXViewerProps, PlaylistPanel, type PlaylistPanelProps, type SphereTextureDiagnostic, StartScreen, type StartScreenProps, type ThreeMaterialConfig, type ThreeRenderConfig, TrackInfo, type TrackInfoProps, type VisualEffect, type VisualNovelNode, type VisualNovelScript, addDefaultSphereTextures, checkModelSphereDefinition, checkSphereTextures, compareFXEffects, configureMaterialsForMMD, configureRendererForMMD, createMMDLights, diagnoseMaterialsMMD, exportFXToJSON, exportFXToMarkdown, extractTexturePaths, filterDefinesByPrefix, fullSphereDiagnostic, generateAllToonTextures, generateToonTexture, getColorParameters, getConfigSummaryText, getFeatureFlags, getTextureDefines, hasFeature, inspectMaterial, listAllMaterials, loadAmmo, printDiagnosticReport, printModelSphereInfo, printSphereDiagnostic, quickDiagnose, validateFXEffect };

package/dist/mmd/index.d.ts

@@ -974,6 +974,10 @@ interface MMDVisualNovelProps {
     showAutoButton?: boolean;
     /** 是否显示历史记录按钮 */
     showHistoryButton?: boolean;
+    /** 自定义设置面板内容 */
+    customSettingsContent?: React.ReactNode;
+    /** 自定义关于面板内容 */
+    customAboutContent?: React.ReactNode;
     /** 样式 */
     className?: string;
     style?: React.CSSProperties;
@@ -1041,6 +1045,8 @@ interface MMDVisualNovelRef {
     setAutoMode: (enabled: boolean) => void;
     /** 跳过当前打字动画 */
     skipTyping: () => void;
+    /** 触发视觉特效 */
+    triggerEffect?: (effect: VisualEffect) => void;
 }
 
 /**
@@ -1055,6 +1061,105 @@ interface MMDVisualNovelRef {
  */
 declare const MMDVisualNovel: React__default.ForwardRefExoticComponent<MMDVisualNovelProps & React__default.RefAttributes<MMDVisualNovelRef>>;
 
+/** 模型选项 */
+interface ModelOption {
+    /** 唯一标识 */
+    id: string;
+    /** 显示名称 */
+    name: string;
+    /** 模型路径 */
+    path: string | string[];
+    /** 缩略图（可选） */
+    thumbnail?: string;
+}
+/** 模型选择器设置属性 */
+interface ModelSelectorSettingsProps {
+    /** 人物模型选项列表 */
+    characterModels: ModelOption[];
+    /** 场景模型选项列表 */
+    stageModels: ModelOption[];
+    /** 当前选中的人物模型 ID */
+    selectedCharacterId: string;
+    /** 当前选中的场景模型 ID */
+    selectedStageId: string;
+    /** 人物模型选择变化回调 */
+    onCharacterChange: (id: string) => void;
+    /** 场景模型选择变化回调 */
+    onStageChange: (id: string) => void;
+    /** 人物模型标签文字 */
+    characterLabel?: string;
+    /** 场景模型标签文字 */
+    stageLabel?: string;
+}
+/**
+ * ModelSelectorSettings - 模型选择器设置组件
+ *
+ * 用于在设置界面中选择人物模型和场景模型
+ */
+declare const ModelSelectorSettings: React__default.FC<ModelSelectorSettingsProps>;
+
+/** 模型选择器配置 */
+interface ModelSelectorConfig {
+    /** 人物模型选项列表 */
+    characterModels: ModelOption[];
+    /** 场景模型选项列表 */
+    stageModels: ModelOption[];
+    /** 默认选中的人物模型 ID（不提供则使用第一个） */
+    defaultCharacterId?: string;
+    /** 默认选中的场景模型 ID（不提供则使用第一个） */
+    defaultStageId?: string;
+    /** 人物模型标签文字 */
+    characterLabel?: string;
+    /** 场景模型标签文字 */
+    stageLabel?: string;
+}
+/** 带模型选择器的视觉小说组件属性 */
+interface MMDVisualNovelWithSelectorProps extends Omit<MMDVisualNovelProps, 'script'> {
+    /** 基础剧本配置（模型路径会被选择器覆盖） */
+    script: VisualNovelScript;
+    /** 模型选择器配置 */
+    modelSelector: ModelSelectorConfig;
+    /** 模型选择变化回调 */
+    onModelSelectionChange?: (characterId: string, stageId: string) => void;
+}
+/** 带模型选择器的视觉小说组件 Ref 接口 */
+interface MMDVisualNovelWithSelectorRef extends MMDVisualNovelRef {
+    /** 获取当前选中的人物模型 ID */
+    getSelectedCharacterId: () => string;
+    /** 获取当前选中的场景模型 ID */
+    getSelectedStageId: () => string;
+    /** 设置人物模型 */
+    setCharacterModel: (id: string) => void;
+    /** 设置场景模型 */
+    setStageModel: (id: string) => void;
+}
+/**
+ * MMDVisualNovelWithSelector - 带模型选择器的视觉小说组件
+ *
+ * 功能特性：
+ * - 在设置界面中提供人物模型和场景模型的下拉选择器
+ * - 选择的模型会应用到剧本中的所有节点
+ * - 完全兼容 MMDVisualNovel 的所有功能
+ *
+ * 使用示例：
+ * ```tsx
+ * <MMDVisualNovelWithSelector
+ *   script={myScript}
+ *   modelSelector={{
+ *     characterModels: [
+ *       { id: 'miku', name: '初音未来', path: '/models/miku.pmx' },
+ *       { id: 'luka', name: '巡音流歌', path: '/models/luka.pmx' },
+ *     ],
+ *     stageModels: [
+ *       { id: 'stage1', name: '教室', path: '/stages/classroom.pmx' },
+ *       { id: 'stage2', name: '公园', path: '/stages/park.pmx' },
+ *     ],
+ *   }}
+ * />
+ * ```
+ */
+declare const MMDVisualNovelWithSelector: React__default.ForwardRefExoticComponent<MMDVisualNovelWithSelectorProps & React__default.RefAttributes<MMDVisualNovelWithSelectorRef>>;
+
 /**
  * DialogueBox - Galgame 风格对话框组件
  *
@@ -1102,6 +1207,10 @@ interface LoadingOverlayProps {
     onStart?: () => void;
     /** 自定义类名 */
     className?: string;
+    /** 自定义设置面板内容 */
+    customSettingsContent?: React__default.ReactNode;
+    /** 自定义关于面板内容 */
+    customAboutContent?: React__default.ReactNode;
 }
 /**
  * LoadingOverlay - 加载遮罩和开始界面组件容器
@@ -1141,6 +1250,10 @@ interface StartScreenProps {
     onStart?: () => void;
     /** 自定义类名 */
     className?: string;
+    /** 自定义设置面板内容 */
+    customSettingsContent?: React__default.ReactNode;
+    /** 自定义关于面板内容 */
+    customAboutContent?: React__default.ReactNode;
 }
 /**
  * StartScreen - 开始界面组件
@@ -1333,9 +1446,52 @@ interface TrackInfoProps {
 }
 declare const TrackInfo: React__default.FC<TrackInfoProps>;
 
+/**
+ * AR 模式枚举
+ */
+declare enum ARMode {
+    /**
+     * 叠加模式 - 模型固定在屏幕上，跟随屏幕移动
+     * 特点：简单易用，不需要陀螺仪权限
+     */
+    Overlay = "overlay",
+    /**
+     * 世界固定模式 - 真正的 AR 体验
+     * 特点：模型固定在世界空间，移动设备时模型保持原位
+     * 需要：设备陀螺仪/加速度计权限
+     */
+    WorldFixed = "world-fixed"
+}
+/** 预设模型配置 */
+interface ModelPreset {
+    /** 预设ID */
+    id: string;
+    /** 显示名称 */
+    name: string;
+    /** 缩略图URL */
+    thumbnail?: string;
+    /** 模型路径 (.pmx) */
+    modelPath: string;
+}
+/** 预设动作配置 */
+interface MotionPreset {
+    /** 预设ID */
+    id: string;
+    /** 显示名称 */
+    name: string;
+    /** 动作路径 (.vmd) */
+    motionPath: string;
+}
+/** 预设音乐配置 */
+interface AudioPreset {
+    /** 预设ID */
+    id: string;
+    /** 显示名称 */
+    name: string;
+    /** 音乐路径 */
+    audioPath: string;
+}
 interface MMDARPlayerProps {
-    /** MMD 资源配置 */
-    resources: MMDResources;
     /** 舞台配置 */
     stage?: MMDStage;
     /** 移动端优化配置 */
@@ -1358,8 +1514,28 @@ interface MMDARPlayerProps {
     };
     /** 是否开启镜像显示 (通常前置摄像头需要开启) */
     mirrored?: boolean;
-    /** 是否显示设置按钮 (允许手动输入模型和动作路径) */
+    /** 是否显示设置按钮 */
     showSettings?: boolean;
+    /** 预设模型列表 */
+    modelPresets: ModelPreset[];
+    /** 预设动作列表 */
+    motionPresets: MotionPreset[];
+    /** 预设音乐列表 (可选) */
+    audioPresets?: AudioPreset[];
+    /** 默认模型ID */
+    defaultModelId?: string;
+    /** 默认动作ID */
+    defaultMotionId?: string;
+    /** 默认音乐ID (可选) */
+    defaultAudioId?: string;
+    /** 初始时是否显示模型 (false 则需要点击放置) */
+    initialModelVisible?: boolean;
+    /** 放置按钮文案 */
+    placementText?: string;
+    /** AR 模式 (默认 Overlay) */
+    arMode?: ARMode;
+    /** 默认 AR 模式 */
+    defaultARMode?: ARMode;
     /** 播放控制 */
     autoPlay?: boolean;
     loop?: boolean;
@@ -1367,6 +1543,8 @@ interface MMDARPlayerProps {
     onCameraReady?: (stream: MediaStream) => void;
     onCameraError?: (error: Error) => void;
     onResourcesChange?: (resources: MMDResources) => void;
+    onModelPlaced?: () => void;
+    onARModeChange?: (mode: ARMode) => void;
     onLoad?: () => void;
     onError?: (error: Error) => void;
     /** 样式 */
@@ -1382,6 +1560,16 @@ interface MMDARPlayerRef {
     switchCamera: () => Promise<void>;
     /** 截图 (包含视频背景和模型) */
     snapshot: () => Promise<string>;
+    /** 放置模型 */
+    placeModel: () => void;
+    /** 移除模型（重置位置） */
+    removeModel: () => void;
+    /** 切换模型 */
+    switchModel: (resources: MMDResources) => void;
+    /** 切换 AR 模式 */
+    setARMode: (mode: ARMode) => void;
+    /** 获取当前 AR 模式 */
+    getARMode: () => ARMode;
 }
 
 /**
@@ -1389,9 +1577,9 @@ interface MMDARPlayerRef {
  *
  * 功能：
  * - 调用设备摄像头作为背景
- * - 叠加透明背景的 MMD 模型渲染
- * - 支持前后摄像头切换
- * - 针对 AR 场景优化模型光照与定位
+ * - 点击放置模型交互
+ * - 支持两种 AR 模式：叠加模式 / 世界固定模式
+ * - 世界固定模式使用设备陀螺仪实现真正的 AR 体验
  */
 declare const MMDARPlayer: React__default.ForwardRefExoticComponent<MMDARPlayerProps & React__default.RefAttributes<MMDARPlayerRef>>;
 
@@ -2208,4 +2396,4 @@ interface FXThreePreviewProps {
 }
 declare const FXThreePreview: React__default.FC<FXThreePreviewProps>;
 
-export { type BranchCondition, CheerButton, type CheerButtonProps, CheerParticles, type CheerParticlesProps, type CheerParticlesRef, ChoiceMenu, type ChoiceMenuProps, DialogueBox, type DialogueBoxProps, type DialogueBoxTheme, type DialogueChoice, type DialogueHistoryItem, type DialogueLine, type EffectFileType, type FXComment, type FXController, type FXDefine, type FXEffect, type FXFileConfig, type FXMergeStrategy, type FXParameter, FXParser, type FXParserOptions, type FXPass, type FXShaderFunction, type FXStaticVariable, type FXSummary, type FXTechnique, type FXTexture, FXThreePreview, type FXThreePreviewProps, FXToThreeAdapter, FXViewer, type FXViewerProps, type GLSLShader, type GLSLShaders, HLSLToGLSLConverter, HistoryPanel, LoadingOverlay, type LoadingOverlayProps, LoadingScreen, type LoadingScreenProps, LoopConfirmDialog, MMDARPlayer, type MMDARPlayerProps, type MMDARPlayerRef, type MMDDiagnosticReport, MMDLightingDebugPanel, type MMDLightingDebugPanelProps, type MMDLightingParams, type MMDLoaderConfig, MMDMusicPlayer, type MMDMusicPlayerConfig, type MMDMusicPlayerProps, type MMDMusicPlayerRef, MMDPlayerBase, MMDPlayerBaseProps, MMDPlayerBaseRef, MMDPlayerEnhanced, MMDPlayerEnhancedDebugInfo, MMDPlayerEnhancedProps, MMDPlaylist, MMDPlaylistDebugInfo, MMDPlaylistNode, MMDPlaylistProps, MMDResources, type MMDSceneRefs, MMDStage, MMDVisualNovel, type MMDVisualNovelProps, type MMDVisualNovelRef, type MaterialTextureMapping, MobileOptimization, MultiFXAdapter, type MultiFXAdapterOptions, MusicControls, type MusicControlsProps, type MusicTrack, PMXEditor, PMXEditor$1 as PMXEditorCore, type PMXEditorProps, PMXExporter, type PMXHeader, type PMXMaterial, type PMXModelInfo, type PMXParseResult, PMXParser, type PMXTexture, type PMXVertex, PMXViewer, type PMXViewerProps, PlaylistPanel, type PlaylistPanelProps, type SphereTextureDiagnostic, StartScreen, type StartScreenProps, type ThreeMaterialConfig, type ThreeRenderConfig, TrackInfo, type TrackInfoProps, type VisualEffect, type VisualNovelNode, type VisualNovelScript, addDefaultSphereTextures, checkModelSphereDefinition, checkSphereTextures, compareFXEffects, configureMaterialsForMMD, configureRendererForMMD, createMMDLights, diagnoseMaterialsMMD, exportFXToJSON, exportFXToMarkdown, extractTexturePaths, filterDefinesByPrefix, fullSphereDiagnostic, generateAllToonTextures, generateToonTexture, getColorParameters, getConfigSummaryText, getFeatureFlags, getTextureDefines, hasFeature, inspectMaterial, listAllMaterials, loadAmmo, printDiagnosticReport, printModelSphereInfo, printSphereDiagnostic, quickDiagnose, validateFXEffect };
+export { ARMode, type AudioPreset, type BranchCondition, CheerButton, type CheerButtonProps, CheerParticles, type CheerParticlesProps, type CheerParticlesRef, ChoiceMenu, type ChoiceMenuProps, DialogueBox, type DialogueBoxProps, type DialogueBoxTheme, type DialogueChoice, type DialogueHistoryItem, type DialogueLine, type EffectFileType, type FXComment, type FXController, type FXDefine, type FXEffect, type FXFileConfig, type FXMergeStrategy, type FXParameter, FXParser, type FXParserOptions, type FXPass, type FXShaderFunction, type FXStaticVariable, type FXSummary, type FXTechnique, type FXTexture, FXThreePreview, type FXThreePreviewProps, FXToThreeAdapter, FXViewer, type FXViewerProps, type GLSLShader, type GLSLShaders, HLSLToGLSLConverter, HistoryPanel, LoadingOverlay, type LoadingOverlayProps, LoadingScreen, type LoadingScreenProps, LoopConfirmDialog, MMDARPlayer, type MMDARPlayerProps, type MMDARPlayerRef, type MMDDiagnosticReport, MMDLightingDebugPanel, type MMDLightingDebugPanelProps, type MMDLightingParams, type MMDLoaderConfig, MMDMusicPlayer, type MMDMusicPlayerConfig, type MMDMusicPlayerProps, type MMDMusicPlayerRef, MMDPlayerBase, MMDPlayerBaseProps, MMDPlayerBaseRef, MMDPlayerEnhanced, MMDPlayerEnhancedDebugInfo, MMDPlayerEnhancedProps, MMDPlaylist, MMDPlaylistDebugInfo, MMDPlaylistNode, MMDPlaylistProps, MMDResources, type MMDSceneRefs, MMDStage, MMDVisualNovel, type MMDVisualNovelProps, type MMDVisualNovelRef, MMDVisualNovelWithSelector, type MMDVisualNovelWithSelectorProps, type MMDVisualNovelWithSelectorRef, type MaterialTextureMapping, MobileOptimization, type ModelOption, type ModelPreset, type ModelSelectorConfig, ModelSelectorSettings, type ModelSelectorSettingsProps, type MotionPreset, MultiFXAdapter, type MultiFXAdapterOptions, MusicControls, type MusicControlsProps, type MusicTrack, PMXEditor, PMXEditor$1 as PMXEditorCore, type PMXEditorProps, PMXExporter, type PMXHeader, type PMXMaterial, type PMXModelInfo, type PMXParseResult, PMXParser, type PMXTexture, type PMXVertex, PMXViewer, type PMXViewerProps, PlaylistPanel, type PlaylistPanelProps, type SphereTextureDiagnostic, StartScreen, type StartScreenProps, type ThreeMaterialConfig, type ThreeRenderConfig, TrackInfo, type TrackInfoProps, type VisualEffect, type VisualNovelNode, type VisualNovelScript, addDefaultSphereTextures, checkModelSphereDefinition, checkSphereTextures, compareFXEffects, configureMaterialsForMMD, configureRendererForMMD, createMMDLights, diagnoseMaterialsMMD, exportFXToJSON, exportFXToMarkdown, extractTexturePaths, filterDefinesByPrefix, fullSphereDiagnostic, generateAllToonTextures, generateToonTexture, getColorParameters, getConfigSummaryText, getFeatureFlags, getTextureDefines, hasFeature, inspectMaterial, listAllMaterials, loadAmmo, printDiagnosticReport, printModelSphereInfo, printSphereDiagnostic, quickDiagnose, validateFXEffect };