@realsee/dnalogel 3.81.12-alpha.1 → 3.81.12

package/CHANGELOG.md

@@ -1,8 +1,15 @@
 # CHANGELOG
 ## 3.81.12
 
-- feat(FireScenePlugin): 新增消防演绎插件
-- 
+- feat(FireScenePlugin): 新增消防演绎插件，包含 `FireControl`（三维实体控制器）和 `FireScenePlayer`（时间轴播放器）
+
+## 3.81.11
+
+- feat(DigitalPerformancePlugin/DigitalPerformanceV2Plugin): 数字人播放器新增默认开启的模型头顶 2D 名牌，支持通过 `showNameplate` 关闭，并可用 `nameplateOptions` 自定义文本、DOM、样式、偏移、容器和调试包围盒。
+- feat(DigitalPerformancePlugin/DigitalPerformanceV2Plugin): 新增 `updateModelName`，无需重载模型或动画即可更新名牌；新增 `loadAnimationDetail`，可将动画详情转换为既有脚本后加载。
+- feat(DigitalPerformancePlugin): 支持 `schemaVersion: 2` 动画详情的分段移动轨迹、重复次数、进入时重启和点动作转换，并导出共享动画转换与轨迹分类能力。
+- fix(DigitalPerformancePlugin): 增强动画详情转换的矩阵、路径投影与输出安全校验；无法安全转换时抛出 `AnimationScriptAdapterSafetyError`，不完整或无效的 V2 数据会降级为 Legacy 摘要。
+- fix(DigitalPerformancePlugin/DigitalPerformanceV2Plugin): 名牌箭头样式按实例 id 幂等注入，避免重复插入全局样式。
 
 ## 3.81.10
 

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,6 +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 AnimationScriptAdapterOptions } from '../animation-script-adapter';
 export default class DigitalPerformancePluginController {
     five: Five;
     playground: DigitalPlayground;
@@ -22,6 +23,8 @@ export default class DigitalPerformancePluginController {
     private progressUpdateTimer;
     private _autoPlayOnNaturalEnd;
     private playingPlayersListeners;
+    private nameplate;
+    private readonly onNameplateRender;
     constructor(five: Five, config?: DigitalPerformancePluginConfig);
     /**
      * 加载剧本数据
@@ -103,6 +106,9 @@ export default class DigitalPerformancePluginController {
      * 获取数字人实例
      */
     getDigitalHuman(modelUrl: string, id?: string): DigitalHuman | null;
+    /** 实时修改角色名牌；不重新加载模型和动画资源。 */
+    updateModelName(id: string, value: string): void;
+    private syncNameplates;
     /**
      * 获取当前播放进度信息
      */
@@ -111,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

@@ -0,0 +1,115 @@
+import type { Five } from '@realsee/five';
+import * as THREE from 'three';
+import type { DigitalModelPlayer } from './DigitalStateMachine';
+export declare const DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH = 30;
+/** 规范化名牌文本，使用 Unicode code point 计数，避免 emoji 被截成半个字符。 */
+export declare function normalizeDigitalPerformanceName(value: unknown, maxLength?: number): string;
+export interface DigitalPerformanceNameplateBinding {
+    id: string;
+    player: DigitalModelPlayer;
+    /** 用于计算包围盒和世界坐标的数字人模型根节点。 */
+    model: THREE.Object3D;
+}
+export interface DigitalPerformanceNameplateRenderContext {
+    id: string;
+    text: string;
+    player: DigitalModelPlayer;
+    model: THREE.Object3D;
+}
+export interface DigitalPerformanceNameplateOptions {
+    /** 名牌最多展示的 Unicode 字符数，默认 30。 */
+    maxLength?: number;
+    /** 相对模型包围盒顶部的世界坐标偏移，默认 [0, 0.12, 0]。 */
+    offset?: [number, number, number];
+    /** 自定义名牌文本，默认使用 displayName ?? name。 */
+    getText?: (player: DigitalModelPlayer) => string | undefined | null;
+    /** 自定义名牌元素；不传时创建默认气泡 div。 */
+    createElement?: (context: DigitalPerformanceNameplateRenderContext) => HTMLElement;
+    /** 自定义名牌更新逻辑；不传时将 textContent 更新为当前文本。 */
+    updateElement?: (element: HTMLElement, context: DigitalPerformanceNameplateRenderContext) => void;
+    /** 名牌元素 class。 */
+    className?: string;
+    /** 名牌元素的额外内联样式。 */
+    style?: Record<string, string>;
+    /** overlay 容器 class。 */
+    containerClassName?: string;
+    /** overlay 容器的额外内联样式。 */
+    containerStyle?: Record<string, string>;
+    /**
+     * 调试：是否显示每个绑定模型的世界包围盒（THREE.BoxHelper），用于核对名牌锚点。
+     * 默认 false，不影响名牌本身。
+     */
+    debugBoundingBox?: boolean;
+}
+/**
+ * DigitalPerformance 的 2D 名牌层。
+ *
+ * 它只负责「模型世界坐标 → 播放器 overlay DOM」和名牌生命周期，
+ * 由 Legacy/V2 controller 在各自的模型帧更新完成后调用 update()，因此两个播放器共用同一套 DOM 规则。
+ */
+export declare class DigitalPerformanceNameplate {
+    private readonly five;
+    private options;
+    private parent;
+    private container;
+    private bindings;
+    private nameOverrides;
+    private enabled;
+    /** 是否由本层自动挂载到 five canvas 父容器（插件内置模式），无需调用方提供容器。 */
+    private autoMount;
+    private readonly onResize;
+    private readonly anchor;
+    private readonly box;
+    private readonly offset;
+    private readonly debugBoxes;
+    private debugBoxesVisible;
+    constructor(five: Five, options?: DigitalPerformanceNameplateOptions);
+    /** 将 overlay 挂到 Five canvas 的父级或业务提供的全屏相对定位容器。 */
+    mount(parent: HTMLElement, options?: DigitalPerformanceNameplateOptions): void;
+    /**
+     * 内置自动挂载：把 overlay 挂到 five canvas 的父容器（与 canvas 同级），调用方无需提供容器。
+     * canvas 尚未进入 DOM 时不报错，会在后续 update() 中自动重试挂载。
+     */
+    enableAutoMount(options?: DigitalPerformanceNameplateOptions): void;
+    /** 移除 overlay，但保留 bindings；重新挂载（含换容器）时会复用 bindings。 */
+    unmount(): void;
+    /** 更新当前章节的角色绑定；id 是角色唯一键，同一模型复用时也不会互相覆盖。 */
+    setBindings(bindings: DigitalPerformanceNameplateBinding[]): void;
+    /** 实时更新指定角色名称，不需要重新加载模型或动画资源。 */
+    updateName(id: string, value: string): void;
+    setEnabled(enabled: boolean): void;
+    /**
+     * 调试：显示/隐藏每个绑定模型的世界包围盒（THREE.BoxHelper）。
+     * 包围盒与名牌锚点使用的是同一个 Box3（setFromObject(model)），用于核对名牌定位。
+     * 默认关闭；不影响名牌本身。
+     */
+    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;
+    private applyElementContent;
+    private hideElement;
+    private applyContainerStyle;
+    private applyElementStyle;
+    /**
+     * 注入名牌气泡箭头的伪元素样式。
+     * 该样式是模块级全局资源（选择器为 .digital-performance-nameplate::after），
+     * 因此只在 mount 时按 id 幂等注入一次，而不是在每个名牌元素创建时重复注入。
+     * 当调用方完全自定义了 className 时，箭头选择器不会命中，也就无需注入。
+     */
+    private injectArrowStyle;
+    private isObjectVisible;
+    /** 同步单个绑定的调试包围盒；未开启时 no-op。 */
+    private syncDebugBox;
+    private removeDebugBox;
+    private clearDebugBoxes;
+    private getScreenPosition;
+}

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

@@ -32,7 +32,9 @@ interface DigitalModelPlayerEffect {
 }
 interface DigitalModelPlayer {
     id: string;
+    /** 兼容已有 name；业务需要独立展示字段时优先使用 displayName。 */
     name: string;
+    displayName?: string;
     type: 'model';
     model: string;
     keyframes: DigitalModelKeyframe[];

package/dist/DigitalPerformancePlugin/index.d.ts

@@ -1,10 +1,15 @@
 import type { Five } from '@realsee/five';
 import DigitalPerformancePluginController from './controller';
+export { DigitalPerformanceNameplate, normalizeDigitalPerformanceName, DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH, } from './core/DigitalPerformanceNameplate';
+export type { DigitalPerformanceNameplateBinding, DigitalPerformanceNameplateOptions, DigitalPerformanceNameplateRenderContext, } from './core/DigitalPerformanceNameplate';
 export { DigitalHuman } from './core/DigitalHuman';
 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,6 +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 AnimationScriptAdapterOptions } from '../../DigitalPerformancePlugin/animation-script-adapter';
 import type { DigitalScript, DigitalChapter } from '../core/shared';
 /** 播放进度（当前章节内） */
 export interface V2Progress {
@@ -80,6 +81,9 @@ export default class DigitalPerformanceV2PluginController {
     private groupProgressListeners;
     private keyframesChangedListeners;
     private currentChapterChangedListeners;
+    private nameplate;
+    private unsubNameplateRender;
+    private unsubNameplateCameraUpdate;
     private unsubClockTick;
     /**
      * 进入编辑时的运镜内存态快照：以章节对象为 key，值为该章节相机关键帧的深拷贝；
@@ -119,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>;
     /** 通过索引播放章节 */
@@ -352,6 +360,9 @@ export default class DigitalPerformanceV2PluginController {
         playing: boolean;
         currentChapter: DigitalChapter | null;
     };
+    /** 实时修改角色名牌；只更新文本和当前剧本，不重新加载模型/动画。 */
+    updateModelName(id: string, value: string): void;
+    private syncNameplates;
     /** 重置播放（保留已加载资源） */
     reset(): void;
     /** 销毁插件、释放资源 */

package/dist/DigitalPerformanceV2Plugin/core/Playground.d.ts

@@ -17,6 +17,7 @@ export declare function getChapterModelDuration(chapter: DigitalChapter): number
  * 复用 Shared_Core 的 DigitalPlayground 做模型/动画/道具加载与实例管理，
  * 但用 PerformanceClock 统一驱动 DigitalHuman.renderAtTime，不使用 Legacy 的 playByChapter / 自驱 rAF。
  */
+export type PerformanceRenderListener = (time: number, delta: number) => void;
 export declare class PerformancePlayground {
     /** 复用 Shared_Core 的加载与实例管理 */
     readonly loader: DigitalPlayground;
@@ -25,12 +26,15 @@ export declare class PerformancePlayground {
     private readonly clock;
     private currentChapter;
     private shownHumans;
+    private renderListeners;
     private unsubTick;
     /** 结束当前 pending 的 playByChapter Promise 的句柄（用于 reset 时干净收尾，避免 await 泄漏） */
     private currentPlayResolve;
     constructor(five: Five, debug?: boolean);
     getClock(): PerformanceClock;
     getCurrentChapter(): DigitalChapter | null;
+    /** 在模型 renderAtTime 完成后执行，供名牌等跟随 UI 使用。 */
+    onRender(listener: PerformanceRenderListener): () => void;
     setScript(script: Parameters<DigitalPlayground['setScript']>[0]): void;
     /**
      * 播放指定章节：准备模型 → 统一时钟驱动 renderAtTime → 自然结束 resolve。

package/dist/DigitalPerformanceV2Plugin/index.d.ts

@@ -2,6 +2,8 @@ import type { Five } from '@realsee/five';
 import DigitalPerformanceV2PluginController from './controller';
 export { default as DigitalPerformanceV2PluginController } from './controller';
 export type { V2Progress, V2ProgressListener } from './controller';
+export { DigitalPerformanceNameplate, normalizeDigitalPerformanceName, DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH, } from '../DigitalPerformancePlugin/core/DigitalPerformanceNameplate';
+export type { DigitalPerformanceNameplateBinding, DigitalPerformanceNameplateOptions, DigitalPerformanceNameplateRenderContext, } from '../DigitalPerformancePlugin/core/DigitalPerformanceNameplate';
 export * from './typings';
 export type DigitalPerformanceV2PluginExportInterface = InstanceType<typeof DigitalPerformanceV2PluginController>;
 export type DigitalPerformanceV2PluginParamsInterface = ConstructorParameters<typeof DigitalPerformanceV2PluginController>[1];

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;
 }
 /**
  * 关键帧到下一关键帧的过渡缓动