@realsee/dnalogel 3.80.8-alpha.2 → 3.81.0-alpha.1

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

@@ -0,0 +1,106 @@
+import type { Five } from '@realsee/five';
+import { DigitalPlayground } from './shared';
+import type { DigitalChapter } from './shared';
+import { PerformanceClock } from './PerformanceClock';
+import { CameraDirector } from './CameraDirector';
+import type { DigitalCameraKeyframe, CameraState } from '../typings';
+/** 取章节时长：所有含关键帧的 player 末帧 timeStamp 的最大值 */
+export declare function getChapterDuration(chapter: DigitalChapter): number;
+/**
+ * 取章节「模型动画」时长：仅统计 model players 末帧 timeStamp 的最大值（排除 camera player）。
+ * 章节总时长以模型动画为准；相机关键帧应被钳制为不超过该总时长，不参与时长计算。
+ */
+export declare function getChapterModelDuration(chapter: DigitalChapter): number;
+/**
+ * PerformancePlayground —— V2 的章节播放编排（统一时钟驱动）
+ *
+ * 复用 Shared_Core 的 DigitalPlayground 做模型/动画/道具加载与实例管理，
+ * 但用 PerformanceClock 统一驱动 DigitalHuman.renderAtTime，不使用 Legacy 的 playByChapter / 自驱 rAF。
+ */
+export declare class PerformancePlayground {
+    /** 复用 Shared_Core 的加载与实例管理 */
+    readonly loader: DigitalPlayground;
+    /** 运镜导演（消费 camera player，驱动 five 相机） */
+    readonly director: CameraDirector;
+    private readonly clock;
+    private currentChapter;
+    private shownHumans;
+    private unsubTick;
+    /** 结束当前 pending 的 playByChapter Promise 的句柄（用于 reset 时干净收尾，避免 await 泄漏） */
+    private currentPlayResolve;
+    constructor(five: Five, debug?: boolean);
+    getClock(): PerformanceClock;
+    getCurrentChapter(): DigitalChapter | null;
+    setScript(script: Parameters<DigitalPlayground['setScript']>[0]): void;
+    /**
+     * 播放指定章节：准备模型 → 统一时钟驱动 renderAtTime → 自然结束 resolve。
+     * 仅处理模型 player 的渲染；相机运镜在后续任务（CameraDirector 接入）中叠加。
+     * @param opts.prepare 加法式可选：在轨道绑定/attach 完成「之后」、时钟 start「之前」被 await 的钩子，
+     *   用于接管前 prepare（无突变 user→director 切换）。缺省（undefined）保持既有行为不变。
+     *   prepare 在时钟启动前执行，故不计入播放时间（时钟不推进）。失败时静默降级、仍照常播放。
+     */
+    playByChapter(chapter: DigitalChapter, fromTime?: number, opts?: {
+        prepare?: () => Promise<void>;
+    }): Promise<void>;
+    /** 暂停（保留时间） */
+    pause(): void;
+    /**
+     * 加法式新增：播放/预览专用切章准备（不启动时钟）。
+     * 复用 playByChapter 的「模型可见性切换 + 相机轨道重绑」逻辑：隐藏其它章节模型、显示目标章节模型、
+     * 按目标章节运镜重绑或解绑相机轨道（不 attach，故不接管 tick）、将时钟配置为目标章节时长并 seek 到 fromTime，
+     * 最后渲染该帧（模型）。不 start 时钟、不做编辑端联动。供 Controller.setCurrentChapterForPlayback 调用。
+     */
+    prepareChapter(chapter: DigitalChapter, fromTime?: number): void;
+    /**
+     * 加法式新增：立即结束当前 pending 的 playByChapter（resolve 其 Promise）并冻结时钟，
+     * 供连播中「跨章 seek 重定向」使用——上层连播循环 await 返回后据 seekRedirect 跳转到目标章节继续。
+     */
+    abortCurrentPlay(): void;
+    /** 显示目标章节的模型 player（visible + 外部驱动准备），返回展示的 DigitalHuman 列表 */
+    private showChapterModels;
+    /**
+     * 绑定目标章节相机轨道（存在非空 camera player 则绑定；否则解绑），失败静默降级。
+     * @param attach true 则 attach 到时钟（播放接管）；false 仅重绑轨道、detach 不接管（暂停态预览）。
+     */
+    private bindChapterCamera;
+    /** 续播 */
+    resume(): void;
+    /**
+     * 跳转到指定时间并渲染当前帧（seek 预览）。不改变播放/暂停状态。
+     * 有活动 tick 监听时由 clock.seek 触发渲染；否则直接渲染一次。
+     */
+    setTimelineTo(time: number): void;
+    /** 运镜开关（透传到 CameraDirector，立即生效） */
+    setCameraDirectionEnabled(enabled: boolean): void;
+    /**
+     * 加法式新增：立即将一个 CameraState 应用到 five（透传到 CameraDirector，复用其桥实例）。
+     * 供 controller 的「章节默认视角」应用使用；不改变播放/时钟状态、不绑定轨道。
+     * 统一 Mapview：应用后 five 即合法 orbit 状态，用户可立即正常拖拽。
+     */
+    applyCameraStateImmediately(state: CameraState): void;
+    /**
+     * 加法式新增：暂停态 scrub 预览，应用 `sample(time)`（透传 CameraDirector.previewAt）。
+     * 仅在运镜启用且轨道有内容时生效；否则 no-op。预览后用户可立即正常拖拽（Mapview orbit）。
+     */
+    previewCameraAt(time: number): void;
+    /**
+     * 加法式新增：接管前 prepare（透传到 CameraDirector）。
+     * enabled 且当前轨道有内容时，以内插动画平滑过渡到 `sample(time)` 并在过渡稳定后 resolve；
+     * 否则立即 resolve（no-op）。不触碰时钟/播放状态，调用方应在时钟 start/resume 前 await。
+     */
+    prepareCameraTo(time: number): Promise<void>;
+    /**
+     * 编辑期：用关键帧重建并绑定相机轨道，供后续 seek 预览/播放接管使用。
+     * 空序列时解绑轨道（不接管相机）。
+     * 注意：此处仅重建轨道，不主动 apply 到 five，避免「捕获关键帧」时改变用户当前的自由导航相机。
+     * 相机接管仅发生在播放 tick 或显式 setTimelineTo 预览（统一 Mapview，用户暂停时始终可自由 orbit/平移）。
+     */
+    setCameraKeyframes(keyframes: ReadonlyArray<DigitalCameraKeyframe>): void;
+    /** 重置：停止时钟、隐藏数字人、复位 loader 实例（保留已加载模型与 currentScript） */
+    reset(): void;
+    /** 释放资源 */
+    dispose(): void;
+    private renderShownAt;
+    private hideShownHumans;
+    private stopTick;
+}

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

@@ -0,0 +1,4 @@
+export { DigitalStateMachine } from '../../DigitalPerformancePlugin/core/DigitalStateMachine';
+export { DigitalHuman } from '../../DigitalPerformancePlugin/core/DigitalHuman';
+export { DigitalPlayground } from '../../DigitalPerformancePlugin/core/DigitalPlayground';
+export type { DigitalScript, DigitalChapter, DigitalModelPlayer, DigitalSubTitlePlayer, DigitalCameraPlayer, DigitalCameraKeyframe, DigitalModelKeyframe, DigitalModelState, DigitalCameraState, KeyframeType, StateType, } from '../../DigitalPerformancePlugin/core/DigitalStateMachine';

package/dist/DigitalPerformanceV2Plugin/index.d.ts

@@ -0,0 +1,9 @@
+import type { Five } from '@realsee/five';
+import DigitalPerformanceV2PluginController from './controller';
+export { default as DigitalPerformanceV2PluginController } from './controller';
+export type { V2Progress, V2ProgressListener } from './controller';
+export * from './typings';
+export type DigitalPerformanceV2PluginExportInterface = InstanceType<typeof DigitalPerformanceV2PluginController>;
+export type DigitalPerformanceV2PluginParamsInterface = ConstructorParameters<typeof DigitalPerformanceV2PluginController>[1];
+export declare const DigitalPerformanceV2Plugin: (five: Five, params?: DigitalPerformanceV2PluginParamsInterface) => DigitalPerformanceV2PluginController;
+export default DigitalPerformanceV2Plugin;

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

@@ -0,0 +1,113 @@
+import type * as THREE from 'three';
+export interface DigitalPerformanceV2PluginConfig {
+    /** 是否在加载剧本后自动播放第一个章节 */
+    autoPlay?: boolean;
+    /** 是否循环播放 */
+    loop?: boolean;
+    /** 是否输出调试日志 */
+    debug?: boolean;
+}
+/**
+ * 关键帧到下一关键帧的过渡缓动
+ * - 'linear'    : 线性（缺省）
+ * - 'easeInOut' : smoothstep 缓入缓出
+ * - 'instant'   : 直接 snap，不向下一帧插值
+ */
+export type CameraTransition = 'linear' | 'easeInOut' | 'instant';
+/**
+ * 运镜关键帧坐标空间（前向兼容标记）
+ * - 'five-world' : five 运行时世界系（target 直接来自 five 当前 Mapview 位姿，重播直接消费，不再变换）。缺省按此解释。
+ * - 'work-local' : 作品本地坐标系（与模型 player 同口径，加载时需经 transformPosition 变换）。
+ * 试点阶段统一写 'five-world'。
+ */
+export type CameraCoordinateSpace = 'five-world' | 'work-local';
+/**
+ * 运镜关键帧（序列化结构）—— 统一采用 five **Mapview**（地图态 / orbit）位姿。
+ *
+ * Mapview 下相机绕 `target`（注视点 = orbit 轴心）旋转：
+ *   相机位置 = target - coordinatesToVector(longitude, latitude) × distance，视线恒指向 `target`。
+ * 这样「播放」「暂停后用户拖拽」「续播」均在同一 orbit 参数系下表达，
+ * 暂停即天然交还用户做左键 orbit / 右键平移（无需 look-from→orbit 转换，无跳变）。
+ */
+export interface DigitalCameraKeyframe {
+    /** 时间点(ms)，章节内相对时间 */
+    timeStamp: number;
+    /** orbit 目标点（= 注视点 / 旋转轴心），five 世界坐标 [x,y,z] */
+    target: number[];
+    /** 水平角 longitude(rad) */
+    longitude: number;
+    /** 俯仰角 latitude(rad) */
+    latitude: number;
+    /** 相机到 target 的距离(m) */
+    distance: number;
+    /** 视场角（度），表达视角「缩放」 */
+    fov: number;
+    /** 到下一关键帧的过渡缓动（缺省 'linear'） */
+    transition?: CameraTransition;
+    /**
+     * 关键帧缩略图 URL（编辑端封面，运行时忽略）。
+     * 约定存 COS 直传得到的持久化 URL；编辑期的本地 blob 预览不写入此字段。
+     */
+    thumbnail?: string;
+}
+/** 运镜播放器（序列化进 script） */
+export interface DigitalCameraPlayer {
+    name: string;
+    type: 'camera';
+    keyframes: DigitalCameraKeyframe[];
+    /** 关键帧坐标空间（前向兼容标记；缺省按 'five-world' 解释） */
+    coordinateSpace?: CameraCoordinateSpace;
+}
+/**
+ * 运行时统一相机状态（采样器输出、桥的输入）—— five Mapview（orbit）位姿。
+ * 直接对应 `five.setState({ offset: target, longitude, latitude, distance, fov, mode: 'Mapview' })`。
+ */
+export interface CameraState {
+    /** orbit 目标点（注视点 / 旋转轴心），five 世界坐标 */
+    target: THREE.Vector3;
+    /** 水平角 longitude(rad) */
+    longitude: number;
+    /** 俯仰角 latitude(rad) */
+    latitude: number;
+    /** 相机到 target 距离(m) */
+    distance: number;
+    /** 视场角（度） */
+    fov: number;
+}
+/**
+ * 组级（整组连续播放）章节时间映射项 —— 加法式新增。
+ * 把 N 个章节按各自模型动画时长（getChapterModelDuration）逐章累计成单一组级时间轴上的区间。
+ */
+export interface GroupChapterTimeInfo {
+    /** 章节索引（0-based） */
+    index: number;
+    /** 章节名称 */
+    name: string;
+    /** 组级累计起点(ms)：startTime[0]=0，startTime[i]=endTime[i-1] */
+    startTime: number;
+    /** 组级累计终点(ms)：endTime[i]=startTime[i]+duration[i]，endTime[last]=组级总时长 */
+    endTime: number;
+    /** 该章节时长(ms) = getChapterModelDuration（排除 camera player） */
+    duration: number;
+}
+/**
+ * 组级（整组连续播放）进度聚合 —— 加法式新增，不替换章节级 V2Progress。
+ * 由「各章节 duration 的累计（getGroupChapterTimeMap）」+「当前章节 index」+「当前章节内时间」派生。
+ * 字段语义与 Legacy GlobalProgress 对齐，使展示端进度条 UI 可平滑复用。
+ */
+export interface GroupProgress {
+    /** 组级当前时间(ms) = 先序章节 duration 之和 + 当前章节内 currentTime（钳制） */
+    groupCurrentTime: number;
+    /** 组级总时长(ms) = 所有章节 duration 之和 */
+    groupTotalTime: number;
+    /** 组级进度百分比 [0,100] = groupCurrentTime / groupTotalTime * 100（groupTotalTime=0 时为 0） */
+    percentage: number;
+    /** 当前章节索引（0-based；无当前章节为 -1） */
+    currentChapterIndex: number;
+    /** 当前章节内时间(ms)（即 V2Progress.currentTime） */
+    currentChapterTime: number;
+    /** 当前章节总时长(ms)（即 V2Progress.totalTime） */
+    currentChapterTotalTime: number;
+    /** 章节总数 */
+    totalChapters: number;
+}