@realsee/dnalogel 3.80.6 → 3.81.0-alpha.0

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

@@ -0,0 +1,330 @@
+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 { DigitalScript, DigitalChapter } from '../core/shared';
+/** 播放进度（当前章节内） */
+export interface V2Progress {
+    /** 当前时间(ms) */
+    currentTime: number;
+    /** 当前章节总时长(ms) */
+    totalTime: number;
+    /** 当前章节索引（0-based；无当前章节为 -1） */
+    currentChapterIndex: number;
+    /** 当前动画组内的章节总数 */
+    totalChapters: number;
+}
+export type V2ProgressListener = (progress: V2Progress) => void;
+/** 组级进度监听 */
+export type GroupProgressListener = (progress: GroupProgress) => void;
+/** 运镜关键帧捕获/编辑的可选项 */
+export interface CameraKeyframeOptions {
+    /** 到下一关键帧的过渡缓动（缺省 'linear'） */
+    transition?: CameraTransition;
+    /** 关键帧缩略图 URL（COS 直传得到；运行时忽略） */
+    thumbnail?: string;
+}
+/** 运镜关键帧增删改操作结果（拒绝时 success=false 并保持序列不变） */
+export interface CameraKeyframeResult {
+    success: boolean;
+    /** 失败原因（success=false 时存在） */
+    error?: string;
+    /** 操作后的最新关键帧序列（升序，副本） */
+    keyframes: DigitalCameraKeyframe[];
+}
+/** setTimelineTo 操作结果 */
+export interface SetTimelineResult {
+    success: boolean;
+    error?: string;
+}
+/** 序列化运镜 player 的结果 */
+export interface SerializeCameraResult {
+    success: boolean;
+    error?: string;
+    player?: DigitalCameraPlayer;
+}
+/** 关键帧序列变更监听（携带升序最新序列） */
+export type CameraKeyframesChangedListener = (keyframes: DigitalCameraKeyframe[]) => void;
+/** 当前章节信息（编辑端用） */
+export interface CurrentChapterInfo {
+    /** 当前章节索引（0-based；无当前章节为 -1） */
+    index: number;
+    /** 当前章节名称（无当前章节为空串） */
+    name: string;
+    /** 当前章节总时长(ms)：该章节模型动画时长（排除相机 player） */
+    duration: number;
+}
+/** 当前章节变更监听（携带最新当前章节信息） */
+export type CurrentChapterChangedListener = (info: CurrentChapterInfo) => void;
+/**
+ * DigitalPerformanceV2Plugin 控制器（最小可用版）
+ *
+ * 试点 fork：独立于现有 DigitalPerformancePlugin（Legacy），不修改其既有行为。
+ * 本版本提供：剧本加载（复用 Shared_Core 加载 + 模型入场景）、播放/暂停/续播、
+ * 基于统一时钟的进度与 seek 预览。相机运镜（CameraTrack/CameraDirector）在后续任务叠加。
+ */
+export default class DigitalPerformanceV2PluginController {
+    five: Five;
+    config: DigitalPerformanceV2PluginConfig;
+    readonly NAME = "Dnalogel-DigitalPerformanceV2Plugin";
+    playground: PerformancePlayground;
+    state: {
+        enabled: boolean;
+        playing: boolean;
+        continuousPlaying: boolean;
+        currentChapter: DigitalChapter | null;
+        currentScript: DigitalScript | null;
+        /** 编辑端：当前选中的运镜项下标（无选中为 null）。切换章节时清除。 */
+        selectedShotIndex: number | null;
+    };
+    private progressListeners;
+    private groupProgressListeners;
+    private keyframesChangedListeners;
+    private currentChapterChangedListeners;
+    private unsubClockTick;
+    /**
+     * 进入编辑时的运镜内存态快照：以章节对象为 key，值为该章节相机关键帧的深拷贝；
+     * 值为 null 表示进入编辑时该章节不存在 camera player。null（整体）表示尚未打过快照。
+     */
+    private cameraEditSnapshot;
+    /**
+     * 组级章节时间映射缓存（加法式）：按 currentScript 引用缓存。
+     * - `groupChapterTimeMapCacheScript` 记录缓存对应的 script 引用；
+     * - script 变更 / loadScript 时引用不一致 ⇒ 缓存失效、下次请求重算。
+     */
+    private groupChapterTimeMapCache;
+    private groupChapterTimeMapCacheScript;
+    /**
+     * D-SEEK-LIVE（方案 A）：连播中「跨章 seek」的重定向令牌。
+     * 播放态跨章 seek 时置位 { index, fromTime } 并 abortCurrentPlay；连播循环 await 返回后据此跳转到目标章节继续播放。
+     */
+    private seekRedirect;
+    constructor(five: Five, config?: DigitalPerformanceV2PluginConfig);
+    /** 加载剧本：预加载资源 + 将模型加入 five 场景；autoPlay 时自动播放首章 */
+    loadScript(script: DigitalScript): Promise<void>;
+    /** 播放指定章节 */
+    playChapter(chapter: DigitalChapter): Promise<void>;
+    /** 通过索引播放章节 */
+    playChapterByIndex(index: number): Promise<void>;
+    /** 从当前章节连续播放到最后一章（连播中跨章 seek 可经 seekRedirect 令牌无缝重定向） */
+    playAllRemaining(): Promise<void>;
+    /** 从第一章开始按顺序连续播放（用于"重播全部"，保留已捕获的各章节运镜） */
+    playAllFromStart(): Promise<void>;
+    /** 从指定章节索引开始，按顺序连续播放到本动画组最后一章（保留已捕获的各章节运镜） */
+    playFromChapterIndex(index: number): Promise<void>;
+    /**
+     * 编辑态：仅播放当前章节（不连播下一章）。
+     * 章节自然播放到末尾（ended）后，由 controller 执行「进度归零 + 恢复当前章节默认视角」，
+     * SHALL NOT 自动连播下一章节（区别于展示端 playAllRemaining 的章节连续播放）。
+     * 无当前章节时为 no-op。
+     */
+    playCurrentChapterForEdit(): Promise<void>;
+    /** 暂停 */
+    pause(): void;
+    /**
+     * 续播（当前章节）。
+     * - `continue()` / `continue({ prepare: false })`：同步 plain 续播，直接 resume 时钟，返回 `void`（既有语义不变）。
+     * - `continue({ prepare: true })`：先 `await prepareCameraTo(currentChapterTime)` 平滑 glide-back（不计时）再 resume，
+     *   返回 `Promise<void>`。展示端与编辑端均传 `prepare: true` 以保证续播无跳变（D-RESUME）。
+     */
+    continue(): void;
+    continue(options: {
+        prepare?: false;
+    }): void;
+    continue(options: {
+        prepare: true;
+    }): Promise<void>;
+    /**
+     * 编辑态暂停（playing→paused，相机由「导演」交还「用户」拥有）。
+     * 统一 Mapview 后，导演接管期间 five 始终是合法 Mapview orbit 状态，暂停瞬间画面不变、
+     * 且 five 手势天然为正常模型视角（左键绕 target orbit、右键平移），无需特殊转换。见设计 §5.3.1。
+     * 仅供编辑端（camera-mode）暂停路径调用。
+     */
+    pauseForEdit(): void;
+    /**
+     * 编辑态续播（当前章节）：在恢复时钟前先 `await prepareCameraTo(当前时间)`，
+     * 以内插动画平滑回到暂停瞬间对应的运镜视角（无突变 user→director 切换，Req 13.9 / 18.9），
+     * prepare 不计入播放时间（时钟在 prepare 期间不推进）后再 resume。
+     * 章节无运镜关键帧时 prepare 为 no-op。不改变通用 `continue()`/`pause()` 语义。
+     */
+    continueForEdit(): Promise<void>;
+    /** 运镜开关：关闭后播放仅驱动模型动画，不接管 five 相机（立即生效） */
+    setCameraDirectionEnabled(enabled: boolean): void;
+    /**
+     * seek 预览：跳转到指定时间并渲染当前帧（不改变播放/暂停状态）。
+     * - 无当前章节：不改时钟、不渲染，返回失败指示且不抛异常。
+     * - 运镜启用：经 director seek 应用相机；运镜禁用：仅驱动 DigitalHuman。
+     */
+    setTimelineTo(time: number): SetTimelineResult;
+    /**
+     * 在指定时间捕获当前 five 相机为一个运镜关键帧。
+     * - 位姿取自 five 当前 Mapview 状态（target=offset、longitude、latitude、distance）；fov 取自 fiveState（缺省读 five.getCurrentState()）。
+     * - 按 timeStamp 升序插入；同 timeStamp 覆盖。
+     * 拒绝（保持序列不变并返回 error）：未加载 script / 无当前章节 / time 非负有限数校验失败。
+     */
+    addCameraKeyframe(time: number, fiveState?: {
+        fov?: number;
+    }, options?: CameraKeyframeOptions): CameraKeyframeResult;
+    /**
+     * 更新指定下标关键帧：合并 patch 中出现的字段，按 timeStamp 重排序。
+     * 拒绝（保持序列不变）：未加载 script / 无章节 / index 越界 / patch.timeStamp 非负有限数校验失败。
+     */
+    updateCameraKeyframe(index: number, patch: Partial<DigitalCameraKeyframe>): CameraKeyframeResult;
+    /** 移除指定下标关键帧。拒绝（保持序列不变）：未加载 script / 无章节 / index 越界。 */
+    removeCameraKeyframe(index: number): CameraKeyframeResult;
+    /** 获取当前章节的运镜关键帧（升序副本；无章节/无 camera player 时返回空数组） */
+    getCameraKeyframes(): DigitalCameraKeyframe[];
+    /**
+     * 序列化当前章节的运镜 player。
+     * keyframes 按 timeStamp 升序，仅写入已设置的可选字段（不写 undefined 占位）。
+     * 空/无 camera player 返回 keyframes:[]；未加载 script / 无章节 时拒绝并返回 error。
+     */
+    serializeCameraPlayer(): SerializeCameraResult;
+    /**
+     * 序列化全部章节中"含非空关键帧"的运镜 player，按章节索引返回。
+     * 供编辑端按"章节起始动画 id"聚合后整组保存。未加载 script 时返回空数组。
+     */
+    serializeAllCameraPlayers(): Array<{
+        chapterIndex: number;
+        player: DigitalCameraPlayer;
+    }>;
+    /**
+     * 按章节索引批量加载运镜（用于从持久化数据还原）：替换对应章节 camera player 的关键帧。
+     * 调用方负责"对账"（只传锚点命中的章节），越界索引忽略。
+     */
+    loadCameraPlayersByChapterIndex(byChapterIndex: Record<number, {
+        keyframes: DigitalCameraKeyframe[];
+        coordinateSpace?: CameraCoordinateSpace;
+        name?: string;
+    }>): void;
+    /** 注册关键帧序列变更监听（camera-keyframes-changed）；返回反订阅函数 */
+    onCameraKeyframesChanged(listener: CameraKeyframesChangedListener): () => void;
+    /**
+     * 章节默认视角（Chapter_Default_View）。
+     * - 章节存在 ≥1 个运镜关键帧：返回该章节相机轨道 `sample(0)`（因首帧夹紧，等于首帧 CameraState）。
+     * - 章节存在 0 个运镜关键帧：返回 `undefined`。
+     * 默认视角不单独持久化，完全由关键帧派生（不在 cameraPlayers 新增字段）。
+     */
+    getChapterDefaultView(chapterIndex: number): CameraState | undefined;
+    /**
+     * 应用章节默认视角到 five。
+     * - 章节存在关键帧：经 FiveModelCameraBridge 立即应用 `sample(0)`。
+     * - 章节存在 0 个关键帧：no-op（保持当前 five 相机状态、不强制移动）。
+     */
+    applyChapterDefaultView(chapterIndex: number): void;
+    /**
+     * 设为当前编辑章节（不开始播放）。该次调用内联动完成：
+     * 切暂停 → `seek(0)`（进度归零、各 DigitalHuman 渲染 t=0）→ 重建 director 轨道到该章节关键帧 →
+     * 应用该章节默认视角 → 读取并更新该章节总时长 → 清除已选中运镜项 → 派发 onCurrentChapterChanged。
+     * 越界索引为 no-op。
+     */
+    setCurrentChapter(chapterIndex: number): void;
+    /** 当前章节信息：{ index, name, duration }；duration 为该章节模型动画时长（排除相机 player） */
+    getCurrentChapterInfo(): CurrentChapterInfo;
+    /** 注册当前章节变更监听（current-chapter-changed）；返回反订阅函数 */
+    onCurrentChapterChanged(listener: CurrentChapterChangedListener): () => void;
+    /**
+     * 进入运镜编辑：对全部章节运镜内存态打一次深快照（供 discardCameraChanges 还原）。
+     * 仅记录内存快照，不触碰持久化、不改相机/播放状态。
+     */
+    beginCameraEditSession(): void;
+    /**
+     * 放弃运镜修改：将运镜内存态还原到 `beginCameraEditSession` 时的快照（不走服务端重载）。
+     * 未打过快照时为 no-op。还原后重建当前章节 director 轨道并派发关键帧变更事件。
+     */
+    discardCameraChanges(): void;
+    /** 当前进度（当前章节内 currentTime/totalTime，单位 ms；含当前章节索引/总章节数） */
+    getProgress(): V2Progress;
+    /** 注册进度监听；返回反订阅函数 */
+    onProgressChanged(listener: V2ProgressListener): () => void;
+    /**
+     * 组级章节时间映射（加法式）：每章 { index, name, startTime, endTime, duration } 逐章累计。
+     * - duration[i] = getChapterModelDuration(chapters[i])（排除 camera player）
+     * - startTime[0]=0、startTime[i]=endTime[i-1]、endTime[i]=startTime[i]+duration[i]
+     * - 未加载 / 空章节组返回 []；纯读，不修改任何引擎状态。
+     * 按 currentScript 引用缓存；loadScript / script 变更时失效重算。
+     */
+    getGroupChapterTimeMap(): GroupChapterTimeInfo[];
+    /**
+     * 组级进度聚合（加法式）：由章节级 getProgress() + getGroupChapterTimeMap() 派生。
+     * - groupTotalTime = Σ duration
+     * - groupCurrentTime = startTime[currentChapterIndex] + clamp(currentTime, 0, duration[idx])（无当前章节为 0）
+     * - 0 ≤ groupCurrentTime ≤ groupTotalTime；percentage ∈ [0,100]（groupTotalTime=0 时为 0）
+     * 纯读，不修改任何引擎状态。
+     */
+    getGroupProgress(): GroupProgress;
+    /**
+     * 注册组级进度监听（加法式，独立监听集合）；返回反订阅函数。
+     * 在既有 emitProgress() 内追加组级广播，每 tick / 章节切换 / pause / seek 时随章节级广播一并触发。
+     */
+    onGroupProgressChanged(listener: GroupProgressListener): () => void;
+    /**
+     * 播放/预览专用：设为当前章节（不开始播放，区别于编辑端 setCurrentChapter）。
+     * 透传 playground.prepareChapter：切模型可见性 + 重绑相机轨道 + 配置时钟时长并 seek 到 fromTime（不 start）。
+     * 不做编辑端默认视角设置 / 选中清理等联动。越界索引为 no-op。
+     */
+    setCurrentChapterForPlayback(index: number, fromTime: number): void;
+    /**
+     * 跳转到组级时间(ms)：映射为 (章节 index, 章节内时间)，必要时切章后 setTimelineTo。
+     * 保留 seek 前的播放/暂停状态（D-SEEK-LIVE，方案 A）：
+     * - 暂停态：跨章则先 setCurrentChapterForPlayback 切章，再 setTimelineTo 预览该帧后交还用户。
+     * - 播放态同章：clock.seek 续播（经 setTimelineTo）。
+     * - 播放态跨章：置 seekRedirect 并 abortCurrentPlay，由连播循环跳到目标章节从 localTime 继续。
+     * 越界钳制到 [0, groupTotalTime]；未加载 script 返回 { success:false } 不抛异常。
+     */
+    seekToGroupTime(groupTimeMs: number): SetTimelineResult;
+    /** 跳转到组级百分比 [0,100]（= seekToGroupTime(clamp(pct,0,100)/100 * groupTotalTime)） */
+    seekToGroupPercentage(percentage: number): SetTimelineResult;
+    /**
+     * 组级时间 → (章节索引, 章节内时间)（加法式内部）。
+     * - g ≤ 0          → { index: 0, localTime: 0 }
+     * - g ≥ groupTotal → { index: last, localTime: duration[last] }
+     * - 否则 startTime[index] ≤ g < endTime[index] 且 localTime = g - startTime[index]
+     * - 零时长章节（start==end）被自动跳过（不会定位其内部）
+     * 前置条件：timeMap 非空。
+     */
+    private mapGroupTimeToChapter;
+    /** 数值钳制工具 */
+    private clamp;
+    /** 当前可用章节 */
+    getChapters(): DigitalChapter[];
+    /** 当前状态快照 */
+    getState(): {
+        playing: boolean;
+        currentChapter: DigitalChapter | null;
+    };
+    /** 重置播放（保留已加载资源） */
+    reset(): void;
+    /** 销毁插件、释放资源 */
+    dispose(): void;
+    /** 预加载模型 / 动画 / 道具（复用 Shared_Core 加载） */
+    private preloadResources;
+    private emitProgress;
+    /** 组级进度广播（加法式新增；独立监听集合，既有 onProgressChanged 语义不变） */
+    private emitGroupProgress;
+    /** 编辑前置校验：未加载 script / 无当前章节时返回拒绝结果，否则返回 null */
+    private guardKeyframeEdit;
+    /** 拒绝结果：保持当前序列不变并返回 error */
+    private rejectKeyframe;
+    /** 当前章节的 camera player（不存在返回 null） */
+    private getCameraPlayer;
+    /** 指定章节的 camera player（不存在返回 null） */
+    private cameraPlayerOf;
+    /** 把 camera player 的关键帧序列化为升序、仅含已设置可选字段的副本（Mapview 位姿） */
+    private serializeKeyframes;
+    /** 获取当前章节的 camera player，不存在则创建并挂到章节 players 上 */
+    private ensureCameraPlayer;
+    /** fov 取值：优先 fiveState.fov，否则读 five 当前状态 */
+    private resolveFov;
+    /** 捕获 five 当前 Mapview 位姿（target=offset、longitude、latitude、distance） */
+    private captureCameraPose;
+    /** 关键帧变更后：重建并绑定相机轨道（供 seek 预览/后续播放接管），派发事件，返回成功结果 */
+    private afterKeyframesChanged;
+    private emitKeyframesChanged;
+    private emitCurrentChapterChanged;
+    /** 当前章节索引（0-based；无当前章节为 -1），按引用或名称匹配 */
+    private getCurrentChapterIndex;
+    /** 由指定章节的相机关键帧构建一条 CameraTrack（无章节/无 camera player 返回 null） */
+    private buildChapterCameraTrack;
+    /** 深拷贝关键帧序列（数组字段亦深拷贝），供快照/还原使用（Mapview 位姿） */
+    private cloneKeyframes;
+}