@realsee/dnalogel 3.81.10-alpha.5 → 3.81.11-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # CHANGELOG
 
+## 3.81.10
+
+- feat: 音视频插件支持应用侧 PlaybackManager，统一播放前申请、取消和媒体操作；未接入时保留独立播放。
+- fix: 暂停或抢占后取消加载中的虚拟屏幕重播，保留共享音频池及旧任务保护。
+- fix: 路线暂停保留进度、续播恢复声音，恢复 iOS 音频就绪后补设暂停位置的兼容逻辑。
+- feat(PanoTagPlugin): 包含 alpha 阶段的虚拟屏幕遮挡与重新可见播放改进。
+
 ## 3.81.10-alpha.5
 
 - fix(PanoTagPlugin): 虚拟屏幕首次自动播放及重新可见重播前增加真实观察点视线遮挡检测，避免被楼板、墙体遮挡的屏幕在不可见处自动播放并抢占音频焦点；不改变标签原有显示策略

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 { DigitalPerformanceNameplateOptions } from '../core/DigitalPerformanceNameplate';
 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,18 @@ 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;
     /**
      * 获取当前播放进度信息
      */

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

@@ -0,0 +1,93 @@
+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>;
+}
+/**
+ * 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;
+    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，但保留 bindings，便于编辑端切换容器后重新 mount。 */
+    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;
+    isEnabled(): boolean;
+    /** 在数字人模型变换完成后调用，更新所有当前章节名牌的位置和可见性。 */
+    update(): void;
+    dispose(): void;
+    private getMaxLength;
+    private getText;
+    private ensureElement;
+    private applyElementContent;
+    private hideElement;
+    private applyContainerStyle;
+    private applyElementStyle;
+    private applyArrow;
+    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,5 +1,7 @@
 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';

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 { DigitalPerformanceNameplateOptions } from '../../DigitalPerformancePlugin/core/DigitalPerformanceNameplate';
 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，值为该章节相机关键帧的深拷贝；
@@ -352,6 +356,15 @@ 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;
     /** 重置播放（保留已加载资源） */
     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/PanoTagPlugin/utils/model/mediaPlane.d.ts

@@ -82,7 +82,8 @@ declare class VideoPlane extends MediaPlane {
      * @returns 播放结果。`'no-session'` 表示没拿到音频焦点（并非异常），
      * 调用方可据此降级为静音播放；`'disposed'`/`'stale'` 表示这次调用已失效。
      */
-    play(muted?: boolean, userAction?: boolean): Promise<'played' | 'no-session' | 'disposed' | 'stale'>;
+    play(muted?: boolean, userAction?: boolean): Promise<"disposed" | "played" | "no-session" | "stale">;
+    private startPlayback;
     /**
      * @description 从头播放。用于「离开可见范围后走回来」的场景：
      * 先重置进度，再尝试有声播放；有声不可用时回退静音，避免出现「既没声音也不播放」。