vrtalk-web-sdk 0.1.521 → 0.1.523

package/dist/src/index.d.ts

@@ -2,3 +2,5 @@ export * from './model';
 export * from './player';
 export * from './parent';
 export { migrateTriggersToCentralized } from './utils/trigger-migration';
+export { migrateXrVariableTypeEnum } from './utils/xr-variable-type-enum-migration';
+export { pickMultiLanguageStr, normalizeMultiLanguageStr, createMultiLanguageStr, normalizeBrowserLanguage, pickCurrentLanguage, } from './utils/multi-language-str-util';

package/dist/src/model/general/free-button.d.ts

@@ -1,12 +1,13 @@
 import { VRTalkBaseData } from './vrtalk-base-data';
 import { XrAnyAction, XrVariable } from '@/model';
+import { MultiLanguageStr } from './multi-language-str';
 /**
  * 自由按钮，在其他组件中动态创建出来的按钮
  * 样式跟随当时的场景决定，该模型只定义按钮信息和对应的触发器
  * 如内容卡片、vrflow步骤中等等
  */
 export declare class FreeButton extends VRTalkBaseData {
-    name: string;
+    name: MultiLanguageStr;
     color: import("@/model").Color;
     textColor: import("@/model").Color;
     additionalData: {};

package/dist/src/model/general/multi-language-str.d.ts

@@ -11,10 +11,11 @@ export declare class LanguageTypeDefine {
     static readonly ES: LanguageType;
     static readonly FR: LanguageType;
     static readonly DE: LanguageType;
+    static readonly ALL: LanguageType[];
 }
 export declare class MultiLanguageStr {
     original_content: string;
-    language_type: LanguageType;
+    only_use_original_content: boolean;
     zh_cn: string;
     zh_tw: string;
     zh_hk: string;

package/dist/src/model/vr/vr-action.d.ts

@@ -1,6 +1,7 @@
 import { Color, type MediaLoopMode, Vector2, Vector3, VrCameraMoveTransitionType } from '../general';
 import { VrComponent2dDeformationSettings } from '../vr-component/vr-component-data';
 import { XrTypedValue, XrVariableScopeType, XrVariableTarget } from './xr-logic';
+import { MultiLanguageStr } from '../general/multi-language-str';
 export declare type XrActionCategory = 'basic' | 'condition' | 'count_loop' | 'expression_loop';
 export declare class XrActionCategoryDefine {
     static readonly BASIC: XrActionCategory;
@@ -45,7 +46,7 @@ export declare class XrExpressionLoopAction {
     checkExpressionPosition: XrExpressionLoopActionCheckExpressionPosition;
     actionList: XrAnyAction[];
 }
-export declare type VrActionType = 'system_common_wait' | 'system_set_interactive_state' | 'system_ui_settings_change' | 'component_general_change_visibility' | 'component_general_change_transform' | 'component_general_play_transition_animation' | 'component_general_stop_transition_animation' | 'component_2d_general_change_deformation_settings' | 'component_general_audio_source_play_control' | 'component_general_audio_source_pause' | 'component_general_audio_source_change_loop_mode' | 'component_2d_image_change_source' | 'component_2d_video_change_source' | 'component_2d_video_change_play_state' | 'component_2d_video_change_mute_state' | 'component_2d_text_change_source' | 'component_2d_panel_change_scene' | 'component_2d_panel_button_change_enabled' | 'component_3d_box_change_color' | 'component_3d_model_play_animation_clip' | 'component_3d_model_stop_animation_clip' | 'information_content_card_show' | 'information_content_card_close' | 'information_link_open' | 'information_link_close' | 'audio_center_play_list' | 'audio_center_pause' | 'audio_center_player_change_display_mode' | 'audio_center_set_volume' | 'sweep_change_enabled' | 'sweep_change_panorama' | 'sweep_marker_change_enabled' | 'sweep_reset_to_default' | 'sweep_only_enable_current' | 'camera_move_to' | 'camera_dolly_move' | 'camera_dolly_stop' | 'navigation_start' | 'navigation_stop' | 'logic_variable_modify' | 'logic_variable_number_add' | 'logic_variable_number_subtract' | 'logic_variable_string_append' | 'logic_variable_string_trim_end' | 'logic_variable_string_advanced' | 'logic_variable_boolean_toggle' | 'flow_enter' | 'flow_exit' | 'monitor_change_enabled' | 'monitor_switch_active_tab' | 'monitor_component_change_visibility' | 'layer_change_visibility' | 'hamburger_menu_node_change_visibility' | 'canvas_component_change_visibility' | 'message_card_change_show_state' | 'tts_play_voice' | 'tts_realtime_stream' | 'background_thread_start' | 'background_thread_pause' | 'background_thread_stop' | 'ai_agent_activate' | 'ai_agent_hide' | 'ai_agent_trigger_monologue' | 'ai_agent_trigger_conversation' | 'ability_enable' | 'ability_stop' | 'cloud_form_show_dialog' | 'cloud_form_collect_field' | 'cloud_form_submit' | 'cloud_form_reset' | 'hit_analytics_event' | 'popup_user_form_show_dialog' | 'logic_random_number' | 'logic_random_color' | 'logic_current_time' | 'logic_random_pick_string' | 'logic_random_pick_number' | 'logic_random_pick_boolean' | 'logic_random_pick_enum' | 'logic_random_pick_color' | 'logic_random_pick_css_color';
+export declare type VrActionType = 'system_common_wait' | 'system_set_interactive_state' | 'system_ui_settings_change' | 'component_general_change_visibility' | 'component_general_change_transform' | 'component_general_play_transition_animation' | 'component_general_stop_transition_animation' | 'component_2d_general_change_deformation_settings' | 'component_general_audio_source_play_control' | 'component_general_audio_source_pause' | 'component_general_audio_source_change_loop_mode' | 'component_2d_image_change_source' | 'component_2d_video_change_source' | 'component_2d_video_change_play_state' | 'component_2d_video_change_mute_state' | 'component_2d_text_change_source' | 'component_2d_panel_change_scene' | 'component_2d_panel_button_change_enabled' | 'component_3d_box_change_color' | 'component_3d_model_play_animation_clip' | 'component_3d_model_stop_animation_clip' | 'information_content_card_show' | 'information_content_card_close' | 'information_link_open' | 'information_link_close' | 'audio_center_play_list' | 'audio_center_pause' | 'audio_center_player_change_display_mode' | 'audio_center_set_volume' | 'sweep_change_enabled' | 'sweep_change_panorama' | 'sweep_marker_change_enabled' | 'sweep_reset_to_default' | 'sweep_only_enable_current' | 'camera_move_to' | 'camera_dolly_move' | 'camera_dolly_stop' | 'navigation_start' | 'navigation_stop' | 'logic_variable_modify' | 'logic_variable_number_add' | 'logic_variable_number_subtract' | 'logic_variable_string_append' | 'logic_variable_string_trim_end' | 'logic_variable_string_advanced' | 'logic_variable_boolean_toggle' | 'flow_enter' | 'flow_exit' | 'monitor_change_enabled' | 'monitor_switch_active_tab' | 'monitor_component_change_visibility' | 'layer_change_visibility' | 'hamburger_menu_node_change_visibility' | 'canvas_component_change_visibility' | 'message_card_change_show_state' | 'tts_play_voice' | 'tts_realtime_stream' | 'background_thread_start' | 'background_thread_pause' | 'background_thread_stop' | 'ai_agent_activate' | 'ai_agent_hide' | 'ai_agent_trigger_monologue' | 'ai_agent_trigger_conversation' | 'ability_enable' | 'ability_stop' | 'cloud_form_show_dialog' | 'cloud_form_collect_field' | 'cloud_form_submit' | 'cloud_form_reset' | 'hit_analytics_event' | 'popup_user_form_show_dialog' | 'logic_random_number' | 'logic_random_color' | 'logic_current_time' | 'logic_random_pick_string' | 'logic_random_pick_number' | 'logic_random_pick_boolean' | 'logic_random_pick_enum' | 'logic_random_pick_color' | 'logic_random_pick_css_color' | 'logic_random_pick_from_recommend_options';
 export declare class VrActionTypeDefine {
     static readonly SYSTEM_COMMON_WAIT: VrActionType;
     static readonly COMPONENT_GENERAL_CHANGE_VISIBILITY: VrActionType;
@@ -125,9 +126,9 @@ export declare class VrActionTypeDefine {
     static readonly LOGIC_RANDOM_PICK_STRING: VrActionType;
     static readonly LOGIC_RANDOM_PICK_NUMBER: VrActionType;
     static readonly LOGIC_RANDOM_PICK_BOOLEAN: VrActionType;
-    static readonly LOGIC_RANDOM_PICK_ENUM: VrActionType;
     static readonly LOGIC_RANDOM_PICK_COLOR: VrActionType;
     static readonly LOGIC_RANDOM_PICK_CSS_COLOR: VrActionType;
+    static readonly LOGIC_RANDOM_PICK_FROM_RECOMMEND_OPTIONS: VrActionType;
 }
 export declare class VrActionParamsAbilityEnable {
     abilityId: string;
@@ -393,7 +394,7 @@ export declare class TtsTextModeDefine {
 export declare class VrActionParamsTtsPlayVoice {
     voiceId: string;
     textMode: TtsTextMode;
-    text: string;
+    text: MultiLanguageStr;
     textRef?: XrTypedValue<string>;
     textExpression: string;
     showSubtitle: boolean;
@@ -405,7 +406,7 @@ export declare class VrActionParamsTtsPlayVoice {
 export declare class VrActionParamsTtsRealtimeStream {
     voiceId: string;
     textMode: TtsTextMode;
-    text: string;
+    text: MultiLanguageStr;
     textRef?: XrTypedValue<string>;
     textExpression: string;
     showSubtitle: boolean;
@@ -526,12 +527,12 @@ export declare class PopupUserFormDataTypeDefaultVariant {
     static getDefault(dataType: PopupUserFormDataType): PopupUserFormControlVariant;
 }
 export declare class PopupUserFormOption {
-    label: string;
+    label: MultiLanguageStr;
     value: string | number;
     iconUrl: string;
     imageUrl: string;
-    description: string;
-    badge: string;
+    description: MultiLanguageStr;
+    badge: MultiLanguageStr;
     color: string;
     disabled: boolean;
 }
@@ -580,8 +581,8 @@ export declare class PopupUserFormControlConfig {
     colorSwatchSize: number;
     colorSwatchShape: 'square' | 'circle';
     colorSwatchColumns: number;
-    booleanTrueLabel: string;
-    booleanFalseLabel: string;
+    booleanTrueLabel: MultiLanguageStr;
+    booleanFalseLabel: MultiLanguageStr;
     booleanTrueIconUrl: string;
     booleanFalseIconUrl: string;
     booleanTrueColor: string;
@@ -593,9 +594,9 @@ export declare class PopupUserFormControlConfig {
 }
 export declare class PopupUserFormField {
     fieldKey: string;
-    label: string;
-    description: string;
-    placeholder: string;
+    label: MultiLanguageStr;
+    description: MultiLanguageStr;
+    placeholder: MultiLanguageStr;
     required: boolean;
     dataType: PopupUserFormDataType;
     defaultValue: string | number | boolean | object | null;
@@ -604,10 +605,10 @@ export declare class PopupUserFormField {
     boundVariableKey: string;
 }
 export declare class VrActionParamsPopupUserFormShowDialog {
-    title: string;
-    description: string;
-    submitButtonText: string;
-    cancelButtonText: string;
+    title: MultiLanguageStr;
+    description: MultiLanguageStr;
+    submitButtonText: MultiLanguageStr;
+    cancelButtonText: MultiLanguageStr;
     showCancelButton: boolean;
     blockInteraction: boolean;
     closeOnOverlayClick: boolean;
@@ -661,10 +662,6 @@ export declare class VrActionParamsLogicRandomPickBoolean {
     target: XrVariableTarget;
     candidates: XrTypedValue<boolean>[];
 }
-export declare class VrActionParamsLogicRandomPickEnum {
-    target: XrVariableTarget;
-    candidates: XrTypedValue<string>[];
-}
 export declare class VrActionParamsLogicRandomPickColor {
     target: XrVariableTarget;
     candidates: XrTypedValue<Color>[];
@@ -673,3 +670,15 @@ export declare class VrActionParamsLogicRandomPickCssColor {
     target: XrVariableTarget;
     candidates: XrTypedValue<string>[];
 }
+/**
+ * 逻辑 - 从变量自身的"推荐选项"中随机选一个并写入。
+ * 运行时按变量 type 读取对应字段：
+ *   - string  → stringRecommendOptions[i].value
+ *   - number  → numberRecommendOptions[i]
+ *   - color   → colorRecommendOptions[i]
+ *   - css_color → cssColorRecommendOptions[i]
+ * 推荐选项为空时变量值不变，仅 warn。
+ */
+export declare class VrActionParamsLogicRandomPickFromRecommendOptions {
+    target: XrVariableTarget;
+}

package/dist/src/model/vr/vr-content-card.d.ts

@@ -1,5 +1,6 @@
 import { FreeButton } from '../general/free-button';
 import { VRTalkBaseData } from '../general/vrtalk-base-data';
+import { MultiLanguageStr } from '../general/multi-language-str';
 export declare type VrContentCardShowStyle = 'bubble' | 'dialog' | 'drawer';
 export declare type VrContentCardMediaType = 'video' | 'image' | 'audio' | '3d_model' | 'link' | 'document';
 export declare class VrContentCardMediaTypeDefine {
@@ -23,8 +24,8 @@ export declare class VrContentCard extends VRTalkBaseData {
     name: string;
     dialogWidth: string;
     dialogHeight: string;
-    title: string;
-    richText: string;
+    title: MultiLanguageStr;
+    richText: MultiLanguageStr;
     isAvailableForAi: boolean;
     modules: VrContentCardModule[];
     buttonList: FreeButton[];

package/dist/src/model/vr/vr-content-data.d.ts

@@ -27,6 +27,7 @@ import { XrCameraDollyPath } from '../../model/vr/xr-camera-dolly-path';
 import { XrPrepareSettings } from '../../model/vr/xr-prepare';
 import { XrAbility, XrAbilityGroup } from '@/model/vr/xr-ability';
 import { XrHamburgerMenu } from './xr-hamburger-menu';
+import { LanguageType } from '../general/multi-language-str';
 /**
  * VR内容数据构建器
  */
@@ -77,6 +78,7 @@ export declare class VrContentData {
     vrDataKey: string;
     mpModelId: string;
     vrUnicode: string;
+    supportedLanguages: LanguageType[];
     vrCoverSettings: VrCoverSettings;
     vrPlayerUiSettings: VrPlayerUiSettings;
     hamburgerMenu: XrHamburgerMenu;

package/dist/src/model/vr/vr-cover-settings.d.ts

@@ -1,3 +1,4 @@
+import { MultiLanguageStr } from '../general/multi-language-str';
 /**
  * VR封面背景类型
  */
@@ -56,13 +57,13 @@ export declare class VrCoverSettings {
     coverContentFitType: VrCoverBackgroundFitType;
     coverMaskColor: import("../general/color").Color;
     coverMaskBlur: number;
-    coverTitle: string;
-    coverDescription: string;
+    coverTitle: MultiLanguageStr;
+    coverDescription: MultiLanguageStr;
     enabledEnterVrButton: boolean;
     enterVrButtonType: VrCoverButtonType;
     enterButtonBackgroundColor: import("../general/color").Color;
     enterButtonForegroundColor: import("../general/color").Color;
     enterButtonShadowColor: import("../general/color").Color;
-    textButtonContent: string;
+    textButtonContent: MultiLanguageStr;
     constructor();
 }

package/dist/src/model/vr/vr-flow.d.ts

@@ -3,6 +3,7 @@ import { VrSignalTrigger } from './vr-signal';
 import { XrAnyAction } from './vr-action';
 import { Vector2 } from '../general';
 import { XrVariable } from './xr-logic';
+import { MultiLanguageStr } from '../general/multi-language-str';
 export declare type VrFlowStatus = 'draft' | 'published';
 export declare class VrFlowStatusDefine {
     static readonly DRAFT: VrFlowStatus;
@@ -41,10 +42,10 @@ export declare class VrFlowStep {
     id: string;
     type: VrFlowStepType;
     name: string;
-    title: string;
-    description: string;
+    title: MultiLanguageStr;
+    description: MultiLanguageStr;
     showArriveDescription: boolean;
-    arriveDescription: string;
+    arriveDescription: MultiLanguageStr;
     note: string;
     flagImageSrc: string;
     flagImageSize: Vector2;

package/dist/src/model/vr/xr-hamburger-menu.d.ts

@@ -102,6 +102,7 @@ export declare class XrHamburgerMenuGroup extends XrHamburgerMenuNode {
     constructor();
     icon: string;
     children: XrHamburgerMenuAnyNode[];
+    defaultExpanded: boolean;
 }
 /**
  * 富文本节点
@@ -138,10 +139,13 @@ export declare type XrHamburgerMenuAnyNode = XrHamburgerMenuTextItem | XrHamburg
  */
 export declare class XrHamburgerMenu {
     drawerTitle: MultiLanguageStr;
+    drawerTitleColor: string;
     drawerDescription: MultiLanguageStr;
+    drawerDescriptionColor: string;
     nodeList: XrHamburgerMenuAnyNode[];
     pcLayoutMode: XrHamburgerMenuPcLayoutMode;
     backgroundColor: string;
+    backgroundBlur: number;
     pcWidth: number;
 }
 export declare type XrHamburgerCanvasComponentType = 'image' | 'text' | 'progress-bar' | 'video' | 'button';
@@ -233,13 +237,14 @@ export declare class XrHamburgerCanvasComponentText extends XrHamburgerCanvasCom
     type: XrHamburgerCanvasComponentType;
     width: number;
     height: number;
-    textContent: string;
+    textContent: MultiLanguageStr;
     textColor: string;
     textSize: number;
     textVerticalAlign: XrHamburgerCanvasComponentVerticalAlign;
     textAlign: XrHamburgerCanvasComponentTextAlign;
     textBold: boolean;
     textItalic: boolean;
+    textUnderline: boolean;
 }
 export declare class XrHamburgerCanvasComponentProgressBar extends XrHamburgerCanvasComponentBase {
     type: XrHamburgerCanvasComponentType;
@@ -271,11 +276,12 @@ export declare class XrHamburgerCanvasComponentButton extends XrHamburgerCanvasC
     paddingY: number;
     backgroundColor: string;
     hoverBackgroundColor: string;
-    textContent: string;
+    textContent: MultiLanguageStr;
     textColor: string;
     textSize: number;
     textBold: boolean;
     textItalic: boolean;
+    textUnderline: boolean;
     iconSrc: string;
     iconPosition: XrHamburgerCanvasComponentButtonIconPosition;
 }

package/dist/src/model/vr/xr-logic.d.ts

@@ -1,31 +1,45 @@
-import { Color, type MediaLoopMode, Vector3, VRTalkBaseData } from '../general';
+import { Color, type MediaLoopMode, MultiLanguageStr, Vector3, VRTalkBaseData } from '../general';
 import type { XrMonitorComponentType, XrMonitorComponentImageMode, XrMonitorComponentTextAlign, XrMonitorComponentVerticalAlign, XrMonitorComponentProgressBarDirection, XrMonitorComponentVideoObjectFit, XrMonitorComponentButtonIconPosition } from './xr-monitor';
 import { VrSignalTrigger } from '@/model';
 import type { XrAnyAction } from './vr-action';
-export declare type XrVariableType = 'string' | 'number' | 'boolean' | 'enum' | 'color' | 'css_color';
+export declare type XrVariableType = 'string' | 'number' | 'boolean' | 'color' | 'css_color';
 export declare class XrVariableTypeDefine {
     static readonly STRING: XrVariableType;
     static readonly NUMBER: XrVariableType;
     static readonly BOOLEAN: XrVariableType;
-    static readonly ENUM: XrVariableType;
     static readonly COLOR: XrVariableType;
     static readonly CSS_COLOR: XrVariableType;
 }
+/**
+ * string 类型变量的"推荐选项"。
+ * value 是写入变量的实际字符串；label 用于在 UI / 2D 面板按钮上展示，支持多语言。
+ * 仅 string 类型有 label 多语言概念；number / color / css_color 的推荐选项是裸值数组。
+ */
+export declare class XrRecommendStringOption {
+    value: string;
+    label: MultiLanguageStr;
+}
 export declare class XrVariable {
     key: string;
     name: string;
     type: XrVariableType;
     value: string;
     stringDefaultValue: string;
+    stringRecommendOptions: XrRecommendStringOption[];
     numberDefaultValue: number;
     numberStep: number;
     numberMinValue: number;
     numberMaxValue: number;
+    numberRecommendOptions: number[];
     booleanDefaultValue: boolean;
-    enumOptions: string[];
-    enumDefaultValue: string;
     colorDefaultValue: Color;
+    colorRecommendOptions: Color[];
     cssColorDefaultValue: string;
+    cssColorRecommendOptions: string[];
+    /** @deprecated 已迁移至 stringRecommendOptions */
+    enumOptions?: string[];
+    /** @deprecated 已迁移至 stringDefaultValue */
+    enumDefaultValue?: string;
 }
 /**
  * 变量作用域类型
@@ -249,6 +263,7 @@ export declare class XrMonitorComponentRuntimeState {
     textAlign: XrMonitorComponentTextAlign;
     textBold: boolean;
     textItalic: boolean;
+    textUnderline: boolean;
     textVerticalAlign: XrMonitorComponentVerticalAlign;
     progressBarColor: string;
     progressRange: number;

package/dist/src/model/vr/xr-message-card.d.ts

@@ -1,9 +1,10 @@
 import { FreeButton, VRTalkBaseData } from '../../model';
+import { MultiLanguageStr } from '../general/multi-language-str';
 export declare class XrMessageCard extends VRTalkBaseData {
     name: string;
     remark: string;
     iconSrc: string;
-    title: string;
-    content: string;
+    title: MultiLanguageStr;
+    content: MultiLanguageStr;
     buttonList: FreeButton[];
 }

package/dist/src/model/vr/xr-monitor.d.ts

@@ -1,5 +1,6 @@
 import { Vector2, VRTalkBaseData } from '../../model';
 import type { XrAnyAction } from './vr-action';
+import { MultiLanguageStr } from '../general/multi-language-str';
 export declare type XrMonitorComponentType = 'image' | 'text' | 'progress-bar' | 'video' | 'button';
 export declare class XrMonitorComponentTypeDefine {
     static readonly IMAGE: XrMonitorComponentType;
@@ -79,13 +80,14 @@ export declare class XrMonitorComponentText extends XrMonitorComponentBase {
     height: number;
     positionX: number;
     positionY: number;
-    textContent: string;
+    textContent: MultiLanguageStr;
     textColor: string;
     textSize: number;
     textVerticalAlign: XrMonitorComponentVerticalAlign;
     textAlign: XrMonitorComponentTextAlign;
     textBold: boolean;
     textItalic: boolean;
+    textUnderline: boolean;
 }
 export declare class XrMonitorComponentProgressBar extends XrMonitorComponentBase {
     type: XrMonitorComponentType;
@@ -117,22 +119,24 @@ export declare class XrMonitorComponentButton extends XrMonitorComponentBase {
     paddingY: number;
     backgroundColor: string;
     hoverBackgroundColor: string;
-    textContent: string;
+    textContent: MultiLanguageStr;
     textColor: string;
     textSize: number;
     textBold: boolean;
     textItalic: boolean;
+    textUnderline: boolean;
     iconSrc: string;
     iconPosition: XrMonitorComponentButtonIconPosition;
 }
 export declare class XrMonitor extends VRTalkBaseData {
     name: string;
     remark: string;
-    title: string;
+    title: MultiLanguageStr;
     description: string;
     icon: string;
     size: Vector2;
     defaultEnabled: boolean;
     backgroundColor: import("../general/color").Color;
+    backgroundBlur: number;
     componentList: XrMonitorComponentBase[];
 }

package/dist/src/model/vr/xr-prepare.d.ts

@@ -13,8 +13,8 @@ export declare class XrPrepareSettings {
 }
 export declare class XrVariablePreFill {
     variableKey: string;
-    defaultValue: string;
-    title: string;
-    hint: string;
+    defaultValue: MultiLanguageStr;
+    title: MultiLanguageStr;
+    hint: MultiLanguageStr;
     required: boolean;
 }

package/dist/src/model/vr-component/vr-component-2d-panel-data.d.ts

@@ -1,13 +1,13 @@
 import { VrComponentData2d } from '../vr-component/vr-component-data';
 import { MultiLanguageStr } from '../../model';
-export declare type VrComponent2dPanelSceneMode = 'menu' | 'answering' | 'enum-modifier';
+export declare type VrComponent2dPanelSceneMode = 'menu' | 'answering' | 'variable-modifier' | 'enum-modifier';
 /**
  * 2D面板的模式定义
  */
 export declare class VrComponent2dPanelSceneModeDefine {
     static MENU: VrComponent2dPanelSceneMode;
     static ANSWERING: VrComponent2dPanelSceneMode;
-    static ENUM_MODIFIER: VrComponent2dPanelSceneMode;
+    static VARIABLE_MODIFIER: VrComponent2dPanelSceneMode;
 }
 /**
  * VR组件 - 2D面板组件数据
@@ -29,7 +29,9 @@ export declare class VrComponent2dPanelSceneData {
     textDataList: VrComponent2dPanelTextItemData[];
     imageDataList: VrComponent2dPanelImageItemData[];
     answeringModeSettings: VrComponent2dPanelAnsweringModeSettings;
-    enumModifierModeSettings: VrComponent2dPanelEnumModifierModeSettings;
+    variableModifierModeSettings: VrComponent2dPanelVariableModifierModeSettings;
+    /** @deprecated 老 enum 数据，迁移工具读完后清空 */
+    enumModifierModeSettings?: any;
     style: VrComponent2dPanelSceneStyle;
     snapshotImageSrc: string;
 }
@@ -41,10 +43,12 @@ export declare class VrComponent2dPanelAnsweringModeSettings {
     correctButtonIdList: string[];
 }
 /**
- * 2D面板-枚举修改器模式相关设置
+ * 2D面板-变量推荐选项修改器模式相关设置（替代旧 VrComponent2dPanelEnumModifierModeSettings）
+ * 仅支持绑定 string 或 number 类型变量；其他类型在编辑器侧禁选
  */
-export declare class VrComponent2dPanelEnumModifierModeSettings {
+export declare class VrComponent2dPanelVariableModifierModeSettings {
     variableKey: string;
+    variableType?: 'string' | 'number';
 }
 /**
  * 2D面板元素类型
@@ -105,7 +109,23 @@ export declare class VrComponent2dPanelTextItemData extends VrComponent2dPanelIt
 export declare class VrComponent2dPanelButtonItemData extends VrComponent2dPanelItem {
     type: VrComponent2dPanelItemType;
     name: string;
-    enumOptionValue: string;
+    /**
+     * 变量修改器模式下：点击按钮写入变量的"实际值"。
+     * - 当绑定 string 变量：取 string
+     * - 当绑定 number 变量：取 number
+     * 老字段 enumOptionValue (string) 在迁移时会被复制到这里。
+     */
+    optionValue: string | number;
+    /**
+     * 变量修改器模式下：按钮显示文字（多语言、可单独编辑覆盖）。
+     * 与 buttonText 的关系：buttonText 用于 menu/answering 模式（富文本 HTML）；optionLabel 仅用于 variable-modifier。
+     * 渲染端 fallback 链：
+     *   1. optionLabel.original_content 非空：按当前语言取，空则取 original_content
+     *   2. 否则：string 变量 → 查 stringRecommendOptions 中 value === optionValue 的 label；number 变量 → String(optionValue)
+     */
+    optionLabel: MultiLanguageStr;
+    /** @deprecated 老 enum 数据，迁移工具读完后复制到 optionValue/optionLabel 并清空 */
+    enumOptionValue?: string;
     enabled: boolean;
     buttonType: VrComponent2dPanelButtonType;
     buttonText: string;

package/dist/src/model/vr-component/vr-component-2d-text-data.d.ts

@@ -1,4 +1,5 @@
 import { VrComponentData2d } from '../vr-component/vr-component-data';
+import { MultiLanguageStr } from '../general/multi-language-str';
 export declare type VrComponent2dTextMode = 'basic' | 'marquee';
 export declare type VrComponent2dTextHorizontalAlign = 'left' | 'center' | 'right';
 export declare type VrComponent2dTextVerticalAlign = 'top' | 'center' | 'bottom';
@@ -44,7 +45,7 @@ export declare class VrComponent2dTextData extends VrComponentData2d {
  */
 export declare class VrComponent2dTextSourceData {
     id: string;
-    textContent: string;
+    textContent: MultiLanguageStr;
     description: string;
 }
 export declare class VrComponent2dTextBasicModeSettings {

package/dist/src/model/vr-component/vr-component-tag-data.d.ts

@@ -1,6 +1,7 @@
 import { VrComponentData } from '../vr-component/vr-component-data';
 import { Vector3 } from '../general/vector';
 import { VrContentCardShowStyle } from '../vr';
+import { MultiLanguageStr } from '../general/multi-language-str';
 export declare type VrComponentTagTextLocation = 'none' | 'top' | 'bottom';
 export declare class VrComponentTagTextLocationDefine {
     static readonly NONE: VrComponentTagTextLocation;
@@ -29,9 +30,9 @@ export declare class VrComponentTagData extends VrComponentData {
     isHoverShowContentCardBubble: boolean;
     isClickShowContentCard: boolean;
     clickShowContentCardStyle: VrContentCardShowStyle;
-    triggerButtonTitle: string;
+    triggerButtonTitle: MultiLanguageStr;
     tipTextLocation: VrComponentTagTextLocation;
-    tipTextContent: string;
+    tipTextContent: MultiLanguageStr;
     tipTextColor: import("../general/color").Color;
     tipTextBackgroundColor: import("../general/color").Color;
     tipTextFontSize: number;

package/dist/src/utils/multi-language-str-util.d.ts

@@ -0,0 +1,34 @@
+import { LanguageType, MultiLanguageStr } from '../model/general/multi-language-str';
+/**
+ * 从 MultiLanguageStr 中按当前语言取值，含 fallback 逻辑：
+ *  1) 数据为 string（老数据兜底）→ 直接返回
+ *  2) only_use_original_content 命中 → 返回 original_content
+ *  3) 当前语言有非空值 → 返回该值
+ *  4) 默认语言有非空值 → 返回默认语言值
+ *  5) 最终降级 → 返回 original_content
+ *  6) 全空 → 返回 ''
+ */
+export declare function pickMultiLanguageStr(mls: MultiLanguageStr | string | null | undefined, currentLang: LanguageType, defaultLang?: LanguageType): string;
+/**
+ * 构造一个 MultiLanguageStr 实例，便于带默认 originalContent 的字段初始化。
+ */
+export declare function createMultiLanguageStr(originalContent?: string, onlyUseOriginalContent?: boolean): MultiLanguageStr;
+/**
+ * 将"任意输入"统一规范化为 MultiLanguageStr 对象。
+ * 用于消费层兜底兼容：
+ *  - string → { original_content: 该值, only_use_original_content: true, 其他全空 }
+ *  - 已是 MultiLanguageStr 对象 → 原样返回
+ *  - null / undefined → 新建空对象
+ */
+export declare function normalizeMultiLanguageStr(raw: MultiLanguageStr | string | null | undefined): MultiLanguageStr;
+/**
+ * 将浏览器语言代码（如 ja-JP / zh-CN）规范化为 LanguageType。
+ * 不能匹配时返回 undefined（调用方应降级到 supportedLanguages[0]）。
+ */
+export declare function normalizeBrowserLanguage(browserLang: string | undefined | null): LanguageType | undefined;
+/**
+ * 给定 vr.supportedLanguages，挑选当前应该使用的语言：
+ *  - 若浏览器语言能映射到 LanguageType 且在 supportedLanguages 中 → 用浏览器语言
+ *  - 否则 → 用 supportedLanguages[0]（默认语言）
+ */
+export declare function pickCurrentLanguage(supportedLanguages: LanguageType[], browserLang: string | undefined | null): LanguageType;

package/dist/src/utils/xr-variable-type-enum-migration.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 变量类型 enum → string + 推荐选项 迁移工具
+ *
+ * 背景：
+ *   重构前 XrVariableType 包含 'enum' 类型，本质是带 enumOptions 候选列表的字符串。
+ *   重构后取消 'enum' 类型，统一用 'string' + stringRecommendOptions（带多语言 label）替代。
+ *   同时 2D 面板的 'enum-modifier' 模式改名为 'variable-modifier'，按钮 enumOptionValue
+ *   改为 optionValue/optionLabel；logic_random_pick_enum Action 改名为
+ *   logic_random_pick_from_recommend_options（candidates 数据丢弃）。
+ *
+ * 此工具是幂等的：所有转换都基于"老字段是否存在"判断，多次调用安全。
+ *
+ * 必须遍历的所有变量列表持有者（共 18 处）：
+ *   1. vrContentData.variableList                                                      （全局）
+ *   2. vrContentData.abilityList[*].contextVariableList                                  （能力）
+ *   3. vrContentData.abilityList[*].activeActionListLocalVariableList
+ *   4. vrContentData.abilityList[*].stopActionListLocalVariableList
+ *   5. vrContentData.abilityList[*].triggerList[*].localVariableList
+ *   6. vrContentData.vrFlowList[*].flowScopeVariableList                                 （Flow）
+ *   7. vrContentData.vrFlowList[*].stepList[*].stepScopeVariableList                     （Step）
+ *   8. vrContentData.vrFlowList[*].stepList[*].triggerList[*].trigger.localVariableList
+ *   9. vrContentData.vrFlowList[*].stepList[*].finishInjectTriggerList[*].localVariableList
+ *  10. vrContentData.vrFlowList[*].stepList[*].buttonList[*].localVariableList
+ *  11. vrContentData.triggerList[*].localVariableList                                    （顶层）
+ *  12. vrContentData.backgroundThreadList[*].localVariableList                           （后台线程）
+ *  13. vrContentData.prepareSettings.vrInitLocalVariableList                             （Prepare）
+ *  14. vrContentData.prepareSettings.arInitLocalVariableList
+ *  15. vrContentData.prepareSettings.allInitLocalVariableList
+ *  16. vrContentData.componentList[*].localVariableList                                  （装修组件）
+ *  17. vrContentData.componentList[*].triggerList[*].localVariableList
+ *  18. vrContentData.messageCardList[*].buttonList[*].localVariableList                  （消息卡片）
+ */
+import { VrContentData } from '../model/vr/vr-content-data';
+/**
+ * 主入口：将老的 enum 变量类型迁移到 string + 推荐选项；将 2D 面板 enum-modifier 模式
+ * 迁移到 variable-modifier；将 logic_random_pick_enum Action 改为
+ * logic_random_pick_from_recommend_options。幂等。
+ */
+export declare function migrateXrVariableTypeEnum(vrContentData: VrContentData): void;