@realsee/dnalogel 3.81.10 → 3.81.11-alpha.2

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

@@ -0,0 +1,99 @@
+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;
+    /**
+     * 注入名牌气泡箭头的伪元素样式。
+     * 该样式是模块级全局资源（选择器为 .digital-performance-nameplate::after），
+     * 因此只在 mount 时按 id 幂等注入一次，而不是在每个名牌元素创建时重复注入。
+     * 当调用方完全自定义了 className 时，箭头选择器不会命中，也就无需注入。
+     */
+    private injectArrowStyle;
+    private isObjectVisible;
+    /** 同步单个绑定的调试包围盒；未开启时 no-op。 */
+    private syncDebugBox;
+    private removeDebugBox;
+    private clearDebugBoxes;
+    private getScreenPosition;
+}

package/libs/DigitalPerformancePlugin/core/DigitalPerformanceNameplate.js

@@ -0,0 +1,244 @@
+var T = Object.defineProperty, S = Object.defineProperties;
+var C = Object.getOwnPropertyDescriptors;
+var w = Object.getOwnPropertySymbols;
+var _ = Object.prototype.hasOwnProperty, M = Object.prototype.propertyIsEnumerable;
+var u = (r, e, t) => e in r ? T(r, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : r[e] = t, p = (r, e) => {
+  for (var t in e || (e = {}))
+    _.call(e, t) && u(r, t, e[t]);
+  if (w)
+    for (var t of w(e))
+      M.call(e, t) && u(r, t, e[t]);
+  return r;
+}, B = (r, e) => S(r, C(e));
+var a = (r, e, t) => (u(r, typeof e != "symbol" ? e + "" : e, t), t);
+import * as d from "three";
+const f = 30;
+function L(r, e = f) {
+  const t = typeof r == "string" ? r.trim() : "", s = Number.isFinite(e) ? Math.max(0, Math.floor(e)) : f;
+  return Array.from(t).slice(0, s).join("");
+}
+const D = [0, 0.12, 0], m = "digital-performance-nameplate", O = "digital-performance-nameplates", N = "digital-performance-nameplate-arrow-style", R = {
+  position: "absolute",
+  "z-index": "1",
+  display: "block",
+  padding: "6px 8px",
+  color: "#fff",
+  background: "rgba(0, 0, 0, 0.85)",
+  "border-radius": "6px",
+  "box-shadow": "0 6px 16px 0 rgba(0, 0, 0, 0.08),0 3px 6px -4px rgba(0, 0, 0, 0.12),0 9px 28px 8px rgba(0, 0, 0, 0.05)",
+  fontSize: "14px",
+  "line-height": "22px",
+  whiteSpace: "nowrap",
+  "pointer-events": "none",
+  transform: "translate3d(0, 0, 0) translate(-50%, calc(-100% - 8px))",
+  "will-change": "transform"
+}, j = {
+  position: "absolute",
+  inset: "0",
+  "z-index": "5",
+  overflow: "hidden",
+  "pointer-events": "none"
+};
+class z {
+  constructor(e, t = {}) {
+    a(this, "five");
+    a(this, "options");
+    a(this, "parent", null);
+    a(this, "container", null);
+    a(this, "bindings", /* @__PURE__ */ new Map());
+    a(this, "nameOverrides", /* @__PURE__ */ new Map());
+    a(this, "enabled", !0);
+    a(this, "onResize", () => this.update());
+    a(this, "anchor", new d.Vector3());
+    a(this, "box", new d.Box3());
+    a(this, "offset", new d.Vector3());
+    a(this, "debugBoxes", /* @__PURE__ */ new Map());
+    a(this, "debugBoxesVisible", !1);
+    this.five = e, this.options = p({}, t);
+  }
+  /** 将 overlay 挂到 Five canvas 的父级或业务提供的全屏相对定位容器。 */
+  mount(e, t) {
+    var s;
+    if (t && (this.options = p(p({}, this.options), t)), this.parent === e && this.container) {
+      this.applyContainerStyle(), this.update();
+      return;
+    }
+    this.unmount(), this.parent = e, this.container = document.createElement("div"), this.container.className = (s = this.options.containerClassName) != null ? s : O, this.applyContainerStyle(), this.injectArrowStyle(), e.appendChild(this.container), typeof window != "undefined" && window.addEventListener("resize", this.onResize, !1), this.update();
+  }
+  /** 移除 overlay，但保留 bindings，便于编辑端切换容器后重新 mount。 */
+  unmount() {
+    var e;
+    typeof window != "undefined" && window.removeEventListener("resize", this.onResize, !1), (e = this.container) == null || e.remove(), this.container = null, this.parent = null, this.bindings.forEach((t) => {
+      t.element = void 0;
+    });
+  }
+  /** 更新当前章节的角色绑定；id 是角色唯一键，同一模型复用时也不会互相覆盖。 */
+  setBindings(e) {
+    const t = new Set(e.map((i) => i.id)), s = this.bindings, n = /* @__PURE__ */ new Map();
+    e.forEach((i) => {
+      const o = s.get(i.id);
+      n.set(i.id, B(p({}, i), { element: o == null ? void 0 : o.element }));
+    }), s.forEach((i, o) => {
+      var l;
+      t.has(o) || ((l = i.element) == null || l.remove(), this.removeDebugBox(o), this.nameOverrides.delete(o));
+    }), this.bindings = n, this.update();
+  }
+  /** 实时更新指定角色名称，不需要重新加载模型或动画资源。 */
+  updateName(e, t) {
+    const s = L(t, this.getMaxLength());
+    this.nameOverrides.set(e, s), this.update();
+  }
+  setEnabled(e) {
+    this.enabled = e, this.container && (this.container.style.display = e ? "" : "none"), e && this.update();
+  }
+  /**
+   * 调试：显示/隐藏每个绑定模型的世界包围盒（THREE.BoxHelper）。
+   * 包围盒与名牌锚点使用的是同一个 Box3（setFromObject(model)），用于核对名牌定位。
+   * 默认关闭；不影响名牌本身。
+   */
+  setBoundingBoxVisible(e) {
+    this.debugBoxesVisible = e, e || this.clearDebugBoxes(), this.five.needsRender = !0, this.update();
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  /** 在数字人模型变换完成后调用，更新所有当前章节名牌的位置和可见性。 */
+  update() {
+    this.container && (this.container.style.display = this.enabled ? "" : "none", this.enabled && this.bindings.forEach((e) => {
+      this.syncDebugBox(e);
+      const t = this.getText(e.player, e.id), s = {
+        id: e.id,
+        text: t,
+        player: e.player,
+        model: e.model
+      };
+      if (!t || !this.isObjectVisible(e.model)) {
+        this.hideElement(e);
+        return;
+      }
+      const n = this.ensureElement(e, s), i = this.getScreenPosition(e.model);
+      if (!i) {
+        this.hideElement(e);
+        return;
+      }
+      this.applyElementContent(n, s), n.style.display = "block", n.style.transform = `translate3d(${i.x}px, ${i.y}px, 0) translate(-50%, calc(-100% - 8px))`;
+    }));
+  }
+  dispose() {
+    this.unmount(), this.clearDebugBoxes(), this.bindings.clear(), this.nameOverrides.clear();
+  }
+  getMaxLength() {
+    var e;
+    return (e = this.options.maxLength) != null ? e : f;
+  }
+  getText(e, t) {
+    var o, l, c, h;
+    const s = this.nameOverrides.get(t), n = (l = (o = this.options).getText) == null ? void 0 : l.call(o, e), i = (c = e.displayName) != null ? c : e.name;
+    return L((h = s != null ? s : n) != null ? h : i, this.getMaxLength());
+  }
+  ensureElement(e, t) {
+    var i, o, l, c;
+    if (e.element)
+      return e.element;
+    const s = (l = (o = (i = this.options).createElement) == null ? void 0 : o.call(i, t)) != null ? l : document.createElement("div");
+    return ((c = this.options.className) != null ? c : m).split(/\s+/).filter(Boolean).forEach((h) => s.classList.add(h)), s.setAttribute("data-digital-performance-nameplate-id", e.id), s.setAttribute("role", "status"), this.applyElementStyle(s), this.container.appendChild(s), e.element = s, s;
+  }
+  applyElementContent(e, t) {
+    this.options.updateElement ? this.options.updateElement(e, t) : e.textContent = t.text, e.setAttribute("aria-label", t.text);
+  }
+  hideElement(e) {
+    e.element && (e.element.style.display = "none");
+  }
+  applyContainerStyle() {
+    var e;
+    this.container && (Object.entries(j).forEach(([t, s]) => this.container.style.setProperty(t, s)), Object.entries((e = this.options.containerStyle) != null ? e : {}).forEach(([t, s]) => this.container.style.setProperty(t, s)));
+  }
+  applyElementStyle(e) {
+    var t;
+    Object.entries(R).forEach(([s, n]) => e.style.setProperty(s, n)), Object.entries((t = this.options.style) != null ? t : {}).forEach(([s, n]) => e.style.setProperty(s, n));
+  }
+  /**
+   * 注入名牌气泡箭头的伪元素样式。
+   * 该样式是模块级全局资源（选择器为 .digital-performance-nameplate::after），
+   * 因此只在 mount 时按 id 幂等注入一次，而不是在每个名牌元素创建时重复注入。
+   * 当调用方完全自定义了 className 时，箭头选择器不会命中，也就无需注入。
+   */
+  injectArrowStyle() {
+    var s;
+    if (typeof document == "undefined" || !document.head || !((s = this.options.className) != null ? s : m).split(/\s+/).includes(m) || document.getElementById(N))
+      return;
+    const t = document.createElement("style");
+    t.id = N, t.textContent = `
+      .digital-performance-nameplate::after {
+        content: '';
+        width: 16px;
+        height: 8px;
+        position: absolute;
+        top: 100%;
+        left: 50%;
+        transform: translateX(-50%) translateY(-1px) rotate(180deg);
+        background-color: rgba(0, 0, 0, 0.85);
+        clip-path: path('M 0 8 A 4 4 0 0 0 2.82842712474619 6.82842712474619 L 6.585786437626905 3.0710678118654755 A 2 2 0 0 1 9.414213562373096 3.0710678118654755 L 13.17157287525381 6.82842712474619 A 4 4 0 0 0 16 8 Z')
+      }
+    `, document.head.appendChild(t);
+  }
+  isObjectVisible(e) {
+    let t = e;
+    for (; t; ) {
+      if (!t.visible)
+        return !1;
+      t = t.parent;
+    }
+    return !0;
+  }
+  /** 同步单个绑定的调试包围盒；未开启时 no-op。 */
+  syncDebugBox(e) {
+    if (!this.debugBoxesVisible)
+      return;
+    let t = this.debugBoxes.get(e.id);
+    if (!t) {
+      t = new d.BoxHelper(e.model, 16726832);
+      const s = t.material;
+      s && (s.depthTest = !1, s.transparent = !0, s.opacity = 0.9), this.five.scene.add(t), this.debugBoxes.set(e.id, t);
+    }
+    t.update();
+  }
+  removeDebugBox(e) {
+    var s, n;
+    const t = this.debugBoxes.get(e);
+    t && (this.five.scene.remove(t), (s = t.geometry) == null || s.dispose(), (n = t.material) == null || n.dispose(), this.debugBoxes.delete(e));
+  }
+  clearDebugBoxes() {
+    this.debugBoxes.forEach((e) => {
+      var t, s;
+      this.five.scene.remove(e), (t = e.geometry) == null || t.dispose(), (s = e.material) == null || s.dispose();
+    }), this.debugBoxes.clear();
+  }
+  getScreenPosition(e) {
+    var x, E, y, g, b;
+    if (e.updateMatrixWorld(!0), this.box.setFromObject(e), this.box.isEmpty())
+      return null;
+    this.box.getCenter(this.anchor), this.anchor.y = this.box.max.y;
+    const t = (x = this.options.offset) != null ? x : D;
+    this.offset.fromArray(t), this.anchor.add(this.offset);
+    const s = this.anchor.clone().project(this.five.camera);
+    if (s.z < -1 || s.z > 1)
+      return null;
+    const n = this.five.project2d(this.anchor);
+    if (!n)
+      return null;
+    let i = n.x, o = n.y;
+    const l = this.five.getElement();
+    if (l && this.parent) {
+      const v = l.getBoundingClientRect(), A = this.parent.getBoundingClientRect();
+      i += v.left - A.left, o += v.top - A.top;
+    }
+    const c = (y = (E = this.parent) == null ? void 0 : E.clientWidth) != null ? y : 0, h = (b = (g = this.parent) == null ? void 0 : g.clientHeight) != null ? b : 0;
+    return c > 0 && h > 0 && (i < -200 || i > c + 200 || o < -100 || o > h + 100) ? null : { x: i, y: o };
+  }
+}
+export {
+  f as DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH,
+  z as DigitalPerformanceNameplate,
+  L as normalizeDigitalPerformanceName
+};

package/libs/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/libs/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/libs/DigitalPerformancePlugin/index.js

@@ -1,18 +1,22 @@
-import o from "./controller/index.js";
-import { DigitalHuman as D } from "./core/DigitalHuman.js";
-import { DigitalPlayground as c } from "./core/DigitalPlayground.js";
-import { DigitalStateMachine as d } from "./core/DigitalStateMachine.js";
+import t from "./controller/index.js";
+import { DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH as P, DigitalPerformanceNameplate as c, normalizeDigitalPerformanceName as u } from "./core/DigitalPerformanceNameplate.js";
+import { DigitalHuman as A } from "./core/DigitalHuman.js";
+import { DigitalPlayground as N } from "./core/DigitalPlayground.js";
+import { DigitalStateMachine as M } from "./core/DigitalStateMachine.js";
 import "three";
 import "./mock.js";
 import "../shared-utils/five/transformPosition.js";
 import "@realsee/five/gltf-loader";
 import "./core/Trace.js";
 import "@realsee/five";
-const g = (r, t) => new o(r, t);
+const f = (r, o) => new t(r, o);
 export {
-  D as DigitalHuman,
-  g as DigitalPerformancePlugin,
-  c as DigitalPlayground,
-  d as DigitalStateMachine,
-  g as default
+  P as DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH,
+  A as DigitalHuman,
+  c as DigitalPerformanceNameplate,
+  f as DigitalPerformancePlugin,
+  N as DigitalPlayground,
+  M as DigitalStateMachine,
+  f as default,
+  u as normalizeDigitalPerformanceName
 };

package/libs/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;
     /** 销毁插件、释放资源 */