@realsee/dnalogel 3.81.11-alpha.2 → 3.81.11-alpha.4

package/dist/DigitalPerformancePlugin/animation-script-adapter.d.ts

@@ -0,0 +1,20 @@
+export interface LegacyScriptTransformer {
+    transformScriptData(detail: unknown, work?: unknown, totalDelay?: number): any;
+}
+export interface AnimationScriptAdapterOptions {
+    work?: unknown;
+    totalDelay?: number;
+    warn?: (message: string, context?: unknown) => void;
+    /** 仅供 dnalogel 自测注入 fake converter；生产调用应使用内置 transformScriptData。 */
+    transformer?: LegacyScriptTransformer;
+}
+export declare class AnimationScriptAdapterSafetyError extends Error {
+    readonly playerId: number | string | undefined;
+    readonly reason: 'converter-unsafe-matrix' | 'unsafe-canonical-output' | 'canonical-player-count-mismatch';
+    constructor(playerId: number | string | undefined, reason: 'converter-unsafe-matrix' | 'unsafe-canonical-output' | 'canonical-player-count-mismatch');
+}
+/**
+ * 将 raw animation detail 转换为两个 DigitalPerformance plugin 共用的 canonical DigitalScript。
+ * Legacy player 只调用一次既有 transformScriptData；完整 v2 player 按逻辑段复用同一转换器。
+ */
+export declare function transformAnimationDetailToDigitalScript(detail: any, options?: AnimationScriptAdapterOptions): any;

package/dist/DigitalPerformancePlugin/controller/index.d.ts

@@ -2,7 +2,7 @@ import type { Five } from '@realsee/five';
 import { DigitalPlayground } from '../core/DigitalPlayground';
 import type { DigitalHuman } from '../core/DigitalHuman';
 import type { DigitalScript, DigitalChapter, DigitalPerformancePluginConfig, GlobalProgress, ChapterTimeInfo, ChapterLocation, ProgressListener } from '../typings';
-import type { DigitalPerformanceNameplateOptions } from '../core/DigitalPerformanceNameplate';
+import { type AnimationScriptAdapterOptions } from '../animation-script-adapter';
 export default class DigitalPerformancePluginController {
     five: Five;
     playground: DigitalPlayground;
@@ -106,15 +106,6 @@ export default class DigitalPerformancePluginController {
      * 获取数字人实例
      */
     getDigitalHuman(modelUrl: string, id?: string): DigitalHuman | null;
-    /**
-     * 挂载模型头顶 2D 气泡名牌。编辑端和 C 端都可以传入自己的全屏 overlay 容器和 DOM 渲染逻辑。
-     * 名牌会按当前章节的 player.id 绑定到对应 DigitalHuman，不会因复用同一模型资源而串名。
-     */
-    mountNameplates(parent: HTMLElement, options?: DigitalPerformanceNameplateOptions): void;
-    unmountNameplates(): void;
-    setNameplatesEnabled(enabled: boolean): void;
-    /** 调试：显示/隐藏名牌绑定模型的世界包围盒（核对名牌锚点用）。 */
-    setNameplateBoundingBoxVisible(visible: boolean): void;
     /** 实时修改角色名牌；不重新加载模型和动画资源。 */
     updateModelName(id: string, value: string): void;
     private syncNameplates;
@@ -126,12 +117,14 @@ export default class DigitalPerformancePluginController {
         totalTime: number;
     } | null;
     /**
-     * 对原始 res 数据进行 transformPosition 处理和章节分组，返回完整结构
-     * @param res 原始数据
-     * @param work 可选，存在时才做transformPosition
-     * @param totalDelay 可选，默认0
+     * 对原始 res 数据进行 transformPosition 处理和章节分组，返回完整结构。
+     * 该方法保留用于兼容旧调用方，实际转换由共享纯函数执行。
      */
     transformScriptData(res: any, work?: any, totalDelay?: number): any;
+    /**
+     * 加载 raw animation detail。转换逻辑由 dnalogel 统一执行，随后复用 canonical loadScript。
+     */
+    loadAnimationDetail(detail: unknown, options?: AnimationScriptAdapterOptions): Promise<any>;
     /**
      * 清理进度缓存
      */

package/dist/DigitalPerformancePlugin/core/DigitalPerformanceNameplate.d.ts

@@ -35,6 +35,11 @@ export interface DigitalPerformanceNameplateOptions {
     containerClassName?: string;
     /** overlay 容器的额外内联样式。 */
     containerStyle?: Record<string, string>;
+    /**
+     * 调试：是否显示每个绑定模型的世界包围盒（THREE.BoxHelper），用于核对名牌锚点。
+     * 默认 false，不影响名牌本身。
+     */
+    debugBoundingBox?: boolean;
 }
 /**
  * DigitalPerformance 的 2D 名牌层。
@@ -50,6 +55,8 @@ export declare class DigitalPerformanceNameplate {
     private bindings;
     private nameOverrides;
     private enabled;
+    /** 是否由本层自动挂载到 five canvas 父容器（插件内置模式），无需调用方提供容器。 */
+    private autoMount;
     private readonly onResize;
     private readonly anchor;
     private readonly box;
@@ -59,7 +66,12 @@ export declare class DigitalPerformanceNameplate {
     constructor(five: Five, options?: DigitalPerformanceNameplateOptions);
     /** 将 overlay 挂到 Five canvas 的父级或业务提供的全屏相对定位容器。 */
     mount(parent: HTMLElement, options?: DigitalPerformanceNameplateOptions): void;
-    /** 移除 overlay，但保留 bindings，便于编辑端切换容器后重新 mount。 */
+    /**
+     * 内置自动挂载：把 overlay 挂到 five canvas 的父容器（与 canvas 同级），调用方无需提供容器。
+     * canvas 尚未进入 DOM 时不报错，会在后续 update() 中自动重试挂载。
+     */
+    enableAutoMount(options?: DigitalPerformanceNameplateOptions): void;
+    /** 移除 overlay，但保留 bindings；重新挂载（含换容器）时会复用 bindings。 */
     unmount(): void;
     /** 更新当前章节的角色绑定；id 是角色唯一键，同一模型复用时也不会互相覆盖。 */
     setBindings(bindings: DigitalPerformanceNameplateBinding[]): void;
@@ -72,10 +84,14 @@ export declare class DigitalPerformanceNameplate {
      * 默认关闭；不影响名牌本身。
      */
     setBoundingBoxVisible(visible: boolean): void;
+    /** 应用 `options.debugBoundingBox`；未配置时保持现状（不覆盖运行时的 setBoundingBoxVisible）。 */
+    private applyDebugBoundingBoxOption;
     isEnabled(): boolean;
     /** 在数字人模型变换完成后调用，更新所有当前章节名牌的位置和可见性。 */
     update(): void;
     dispose(): void;
+    /** 内置自动挂载的实际执行：解析 five canvas 的父容器并 mount；条件不满足时静默跳过。 */
+    private tryAutoMount;
     private getMaxLength;
     private getText;
     private ensureElement;

package/dist/DigitalPerformancePlugin/index.d.ts

@@ -7,6 +7,9 @@ export { DigitalPlayground } from './core/DigitalPlayground';
 export { DigitalStateMachine } from './core/DigitalStateMachine';
 export * from './controller';
 export * from './typings';
+export * from './animation-script-adapter';
+export * from './movement-track-classifier';
+export * from './transform-script-data';
 export type DigitalPerformancePluginExportInterface = InstanceType<typeof DigitalPerformancePluginController>;
 export type DigitalPerformancePluginParamsInterface = ConstructorParameters<typeof DigitalPerformancePluginController>[1];
 export declare const DigitalPerformancePlugin: (five: Five, params?: DigitalPerformancePluginParamsInterface) => DigitalPerformancePluginController;

package/dist/DigitalPerformancePlugin/movement-track-classifier.d.ts

@@ -0,0 +1,52 @@
+export declare const MOVEMENT_SCHEMA_VERSION: 2;
+export declare const MOVEMENT_POSITION_EPSILON = 0.001;
+export declare const MOVEMENT_OCCURRENCE_EPSILON = 1e-9;
+export type MovementPosition = {
+    x: number;
+    y: number;
+    z: number;
+};
+export type PointAction = {
+    animationUrl?: string;
+    duration?: number;
+    repeat?: boolean;
+    [key: string]: unknown;
+};
+export type MovementConfig = {
+    duration: number;
+    animationUrl: string;
+    repeat: 'loop' | 'once';
+    restartOnEnter?: boolean;
+};
+export type TrackPoint = {
+    point: MovementPosition;
+    actions?: PointAction[];
+    outgoingMovement?: MovementConfig;
+    [key: string]: unknown;
+};
+export type MovementTrackProjection = {
+    segmentIndex: number;
+    distance: number;
+};
+export type CanonicalMovementTrackPlan = {
+    path: MovementPosition[];
+    points: Array<TrackPoint & {
+        actions: PointAction[];
+    }>;
+    projections: MovementTrackProjection[];
+};
+export type MovementTrackConflictReason = 'unsupported-schema' | 'invalid-path' | 'invalid-points' | 'invalid-matrix' | 'invalid-actions' | 'invalid-movement' | 'terminal-movement' | 'invalid-projection' | 'matrix-origin-mismatch' | 'legacy-summary-mismatch';
+export type MovementTrackClassification = {
+    kind: 'canonical-v2';
+    plan: CanonicalMovementTrackPlan;
+} | {
+    kind: 'pure-legacy';
+} | {
+    kind: 'conflict-invalid';
+    reason: MovementTrackConflictReason;
+};
+export declare function getEffectivePointActionDuration(action: PointAction): number;
+export declare function getMovementActionDuration(actions: PointAction[]): number;
+export declare function isConverterSafeMovementMatrix(value: unknown): value is number[];
+export declare function hasMovementV2Signal(player: unknown): boolean;
+export declare function classifyMovementTrack(player: unknown): MovementTrackClassification;

package/dist/DigitalPerformancePlugin/transform-script-data.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 将 animation detail 转换为 dnalogel Legacy/V2 共用的 canonical script。
+ *
+ * 这是纯数据转换，不依赖 Five 实例，也不会修改调用方传入的 detail。
+ * outgoingMovement 的分段协议由上层 adapter 通过临时 Legacy detail 复用本函数。
+ */
+export declare function transformScriptData(res: any, work?: any, totalDelay?: number): any;

package/dist/DigitalPerformancePlugin/typings/index.d.ts

@@ -1,10 +1,18 @@
 import * as THREE from 'three';
 import type { DigitalChapter } from '../core/DigitalStateMachine';
+import type { DigitalPerformanceNameplateOptions } from '../core/DigitalPerformanceNameplate';
 export type { DigitalScript, DigitalChapter, DigitalModelPlayer, DigitalSubTitlePlayer, DigitalCameraPlayer, DigitalModelKeyframe, DigitalSubTitleKeyframe, DigitalCameraKeyframe, DigitalModelState, DigitalSubTitleState, DigitalCameraState, DigitalModelPlayerItem, DigitalModelPlayerEffect, DigitalEffectKeyframe, DigitalDataState, DigitalDataPlayer, KeyframeType, StateType, } from '../core/DigitalStateMachine';
 export interface DigitalPerformancePluginConfig {
     autoPlay?: boolean;
     loop?: boolean;
     debug?: boolean;
+    /**
+     * 是否展示模型头顶的 2D 气泡名牌（默认 true）。
+     * 插件会内置挂载到 five canvas 的父容器，调用方无需提供容器，仅需声明是否展示。
+     */
+    showNameplate?: boolean;
+    /** 内置名牌的自定义配置（class / 内联样式 / 文本 / 自定义渲染器等）。仅 showNameplate 为真时生效。 */
+    nameplateOptions?: DigitalPerformanceNameplateOptions;
 }
 export interface GlobalProgress {
     currentTime: number;

package/dist/DigitalPerformanceV2Plugin/controller/index.d.ts

@@ -1,7 +1,7 @@
 import type { Five } from '@realsee/five';
 import type { DigitalPerformanceV2PluginConfig, DigitalCameraKeyframe, DigitalCameraPlayer, CameraTransition, CameraCoordinateSpace, CameraState, GroupChapterTimeInfo, GroupProgress } from '../typings';
 import { PerformancePlayground } from '../core/Playground';
-import type { DigitalPerformanceNameplateOptions } from '../../DigitalPerformancePlugin/core/DigitalPerformanceNameplate';
+import { type AnimationScriptAdapterOptions } from '../../DigitalPerformancePlugin/animation-script-adapter';
 import type { DigitalScript, DigitalChapter } from '../core/shared';
 /** 播放进度（当前章节内） */
 export interface V2Progress {
@@ -123,6 +123,10 @@ export default class DigitalPerformanceV2PluginController {
     constructor(five: Five, config?: DigitalPerformanceV2PluginConfig);
     /** 加载剧本：预加载资源 + 将模型加入 five 场景；autoPlay 时自动播放首章 */
     loadScript(script: DigitalScript): Promise<void>;
+    /**
+     * 加载 raw animation detail。转换逻辑由 dnalogel 与 Legacy 插件共用，随后复用 canonical loadScript。
+     */
+    loadAnimationDetail(detail: unknown, options?: AnimationScriptAdapterOptions): Promise<any>;
     /** 播放指定章节 */
     playChapter(chapter: DigitalChapter): Promise<void>;
     /** 通过索引播放章节 */
@@ -356,12 +360,6 @@ export default class DigitalPerformanceV2PluginController {
         playing: boolean;
         currentChapter: DigitalChapter | null;
     };
-    /** 挂载模型头顶 2D 气泡名牌；编辑端与 C 端可使用同一套 API 和自定义渲染器。 */
-    mountNameplates(parent: HTMLElement, options?: DigitalPerformanceNameplateOptions): void;
-    unmountNameplates(): void;
-    setNameplatesEnabled(enabled: boolean): void;
-    /** 调试：显示/隐藏名牌绑定模型的世界包围盒（核对名牌锚点用）。 */
-    setNameplateBoundingBoxVisible(visible: boolean): void;
     /** 实时修改角色名牌；只更新文本和当前剧本，不重新加载模型/动画。 */
     updateModelName(id: string, value: string): void;
     private syncNameplates;

package/dist/DigitalPerformanceV2Plugin/typings/index.d.ts

@@ -1,4 +1,5 @@
 import type * as THREE from 'three';
+import type { DigitalPerformanceNameplateOptions } from '../../DigitalPerformancePlugin/core/DigitalPerformanceNameplate';
 export interface DigitalPerformanceV2PluginConfig {
     /** 是否在加载剧本后自动播放第一个章节 */
     autoPlay?: boolean;
@@ -8,6 +9,14 @@ export interface DigitalPerformanceV2PluginConfig {
     debug?: boolean;
     /** 是否显示人物运动轨迹线（默认 false，不显示）。仅 debug / 特殊需求开启。 */
     showTrace?: boolean;
+    /**
+     * 是否内置展示模型头顶的 2D 气泡名牌（默认 true）。
+     * 插件会自动挂载到 five canvas 的父容器（与 canvas 同级），消费方只需声明是否展示；
+     * 设为 false 时不挂载任何名牌 DOM。
+     */
+    showNameplate?: boolean;
+    /** 内置名牌的自定义配置（class / 内联样式 / 文本 / 自定义渲染器等）。仅 showNameplate 为真时生效。 */
+    nameplateOptions?: DigitalPerformanceNameplateOptions;
 }
 /**
  * 关键帧到下一关键帧的过渡缓动