three-editor-ai 0.0.0-stage → 0.0.2

package/declare/modules.d.ts

@@ -0,0 +1,593 @@
+import type * as THREE from "three";
+import type { TransformControls } from "three/examples/jsm/controls/TransformControls.js";
+import type { EffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
+import type { Pass } from "three/examples/jsm/postprocessing/Pass.js";
+import type { CSS2DRenderer } from "three/examples/jsm/renderers/CSS2DRenderer.js";
+import type { CSS3DRenderer } from "three/examples/jsm/renderers/CSS3DRenderer.js";
+import type Stats from "three/examples/jsm/libs/stats.module.js";
+import type { GUI } from "lil-gui";
+import type { Vector3Like } from "./main";
+import type { EditorEventApi } from "./events";
+import type { ComponentMetadata } from "./component";
+
+/* ------------------------------------------------------------------ *
+ * 场景
+ * ------------------------------------------------------------------ */
+
+/** 帧循环回调，delta / elapsed 为帧间隔 / 累计时间（秒） */
+export type LoopRenderFn = (delta: number, elapsed: number) => void;
+
+/**
+ * `THREE.Scene` 的编辑器扩展。
+ * `add` / `remove` 被改写：完成后经 `emit` 触发 `scene-add` / `scene-remove`。
+ * `remove` 会解开变换控制、连带移除克隆，并释放非克隆体资源。
+ * 组件根移除时由 cores 在 `scene-remove` 同步阶段发出 `component-remove`（含组件原型）。
+ */
+export interface EditorScene extends THREE.Scene {
+  /** 与编辑器 `emit` 为同一函数 */
+  emit: EditorEventApi["emit"];
+  /** 默认射线对象，`layers.enableAll()` 已开启 */
+  raycaster: THREE.Raycaster;
+
+  /** 场景上的变换控制器引用，由 `transformControls` 注入 */
+  transformControls: EditorTransformControls;
+
+  /** 每帧执行的回调列表 */
+  COMMON_UPDATE_LIST: LoopRenderFn[];
+
+  /**
+   * 环境贴图变化时触发的回调表。
+   * key 为材质或模型等宿主，同 key 覆盖不重复。
+   */
+  envMapChangeUseList: Map<unknown, () => void>;
+
+  /** 是否启用环境贴图，赋值时同步 `scene.environment` */
+  environmentEnabled: boolean;
+
+  /** 环境贴图。未设置时为 `undefined`，`resetEnv` 后为 `null` */
+  envBackground: THREE.CubeTexture | null | undefined;
+
+  /** 环境贴图地址。仅 `setEnvBackground` 写入；`resetEnv` 不清除 */
+  envBackgroundUrls?: string[] | null;
+
+  /** 天空盒地址。仅 `setSceneBackground` 写入；`resetEnv` 不清除 */
+  backgroundUrls?: string[] | null;
+
+  /** 天空盒贴图加载完成回调 */
+  backgroundLoadCallback?: (texture: THREE.CubeTexture) => void;
+
+  /** 添加到场景并立即挂到变换控制器上 */
+  attach_add(object: THREE.Object3D): void;
+
+  /** 清空帧列表、雾、除控制器与相机外的所有子物体，并重置环境 */
+  reset(): void;
+
+  /** 执行一帧，由内部渲染循环调用 */
+  update(delta: number, elapsed: number): void;
+
+  /** 注册每帧回调，重复注册同一函数时替换 */
+  addLoopRender(fn: LoopRenderFn): void;
+
+  /** 移除每帧回调 */
+  removeLoopRender(fn: LoopRenderFn): void;
+
+  /** 设置天空盒，`urls` 为正负 XYZ 六个面的贴图地址 */
+  setSceneBackground(urls: string[]): void;
+
+  /** 设置环境贴图，`urls` 为正负 XYZ 六个面的贴图地址 */
+  setEnvBackground(urls: string[]): void;
+
+  /** 释放并清空天空盒与环境贴图对象；`backgroundUrls` / `envBackgroundUrls` 保留 */
+  resetEnv(): void;
+}
+
+/** `THREE.PerspectiveCamera`，初始位置 (10, 10, 10) */
+export interface EditorCamera extends THREE.PerspectiveCamera {
+  /** 依据容器尺寸重算 aspect 并更新投影矩阵 */
+  resize(): void;
+}
+
+/** 渲染序列中的一项，可开关以跳过对应的每帧逻辑 */
+export interface RenderListEntry {
+  name: string;
+
+  /** delta / elapsed 为帧间隔 / 累计时间（秒） */
+  fn: (delta: number, elapsed: number) => void;
+
+  enabled: boolean;
+}
+
+/** `THREE.WebGLRenderer` 的编辑器扩展 */
+export interface EditorRenderer extends THREE.WebGLRenderer {
+  /** 渲染序列配置，修改 `enabled` 后需调用 `refreshRenderList()` 生效 */
+  renderListCompare: RenderListEntry[];
+
+  /** 依据 `renderListCompare` 的 enabled 状态重建实际渲染序列 */
+  refreshRenderList(): void;
+}
+
+/** `TransformControls` 的编辑器扩展 */
+export interface EditorTransformControls extends TransformControls {
+  /** Box3 辅助框。未创建时没有该字段，关闭后为 `null` */
+  box3Helper?: THREE.Box3Helper | null;
+
+  /** 拖拽开始 / 结束回调，参数为 `dragging-changed` 的 `value`。历史模块在初始化时写入，监听里会直接调用 */
+  drag_change_callback: (value: boolean) => void;
+
+  /** 拖拽过程中的回调 */
+  dragChangeCallback?: (value: boolean) => void;
+}
+
+/* ------------------------------------------------------------------ *
+ * 后期处理
+ * ------------------------------------------------------------------ */
+
+/** 描述符安装后生成的 Pass */
+export interface EditorPass extends Pass {
+  /** 生成该 Pass 的描述符 */
+  originInfo?: EffectDescriptor;
+}
+
+/** 安装自定义特效时传入的参数（与 `EditorContext` 场景相关字段同形） */
+export interface EffectInstallArgs {
+  scene: EditorScene;
+
+  camera: EditorCamera;
+
+  renderer: EditorRenderer;
+
+  DOM: HTMLElement;
+}
+
+/**
+ * 自定义后期特效描述符。
+ * `id`、`description` 与 `install` 必填；`id` 已存在时 `installEffect` 直接返回已有 Pass。
+ */
+export interface EffectDescriptor {
+  /** 必填，唯一标识，同时作为 `effectComposer.SHEET[id]` 的键 */
+  id: string;
+
+  /** 面板显示名 */
+  name?: string;
+
+  /** 必填，通道描述，说明用途、可配置内容及行为 */
+  description: string;
+
+  /**
+   * 安装前的默认值。提供 `meta.init` 时定义对应字段。
+   * `install` 读取此对象写入新建的 Pass；已安装的通道不随它变化。
+   */
+  initParams?: Record<string, unknown>;
+
+  /**
+   * 外层可配置项。`meta.init` 相对 `initParams`，`meta.props` 相对 `install` 返回的 Pass。
+   * 内核面板仍使用 `setPanel`。
+   */
+  meta?: ComponentMetadata;
+
+  /** 必填，返回一个 Pass */
+  install: (args: EffectInstallArgs) => Pass | null | undefined;
+
+  /** 卸载时调用（`unInstallEffect`） */
+  unInstall?: (args: EffectInstallArgs) => void;
+
+  /** 存档附加数据 */
+  getStorage?: (pass: Pass) => Record<string, unknown> | void;
+
+  /** 还原附加数据（`enabled` 由内核单独还原） */
+  setStorage?: (pass: Pass, storage: unknown) => void;
+
+  /** 控制面板（`enabled` 开关由内核先添加） */
+  setPanel?: (pass: Pass, folder: GUI) => void;
+}
+
+/** 单条后期特效存档（`passes` 数组元素） */
+export interface EffectPassStorage {
+  id: string;
+
+  enabled?: boolean;
+
+  [key: string]: unknown;
+}
+
+/** `EffectComposer` 的编辑器扩展 */
+export interface EditorEffectComposer extends EffectComposer {
+  /** 已安装的 Pass 表，键为描述符 id */
+  SHEET: Record<string, EditorPass>;
+
+  /** 名单排序用的 id 序列，由 `setPassOrder` 维护 */
+  passSortIds?: string[];
+
+  /** 渲染方式，切换时改写 `effectRender`；缺省 `'effectComposer'` */
+  renderWay: "effectComposer" | "renderer";
+
+  /** 每帧执行的渲染函数，由 `renderWay` 决定 */
+  effectRender(): void;
+
+  /**
+   * 按 id 名单重排 `passes`：无 originInfo 的（如 RenderPass）在前，
+   * 名单内已安装的按序，其余有 originInfo 的留在末尾。
+   * 传入 `ids` 时同时写入 `passSortIds`。
+   */
+  setPassOrder(ids?: string[]): void;
+
+  /** 还原单个 Pass 的 `enabled` 与描述符 `setStorage` */
+  setPassStorage(pass: EditorPass, storage?: EffectPassStorage | null): void;
+
+  /** 安装特效；已存在同 id 时返回已有 Pass */
+  installEffect(effect: EffectDescriptor): EditorPass | undefined;
+
+  /** 卸载特效：从名单移除、dispose、调用 `unInstall` */
+  unInstallEffect(id: string): void;
+
+  /**
+   * 设置轮廓光选中物体（安装 `outlinePass` 后可用）。
+   * 不传或空数组表示清空。
+   */
+  setOutlineSelects?(meshList?: THREE.Object3D[]): void;
+
+  /** 读取轮廓光当前选中列表（安装 `outlinePass` 后可用） */
+  getOutlineSelects?(): THREE.Object3D[];
+
+  /**
+   * 存档还原时遇到未注册特效 id 的回调。
+   * 由 `ThreeEditor.needRegister` 注入。
+   */
+  needRegisterEffectCallBack?: (id: string, storage: EffectPassStorage) => void;
+}
+
+/* ------------------------------------------------------------------ *
+ * CSS 渲染器 / 性能监控
+ * ------------------------------------------------------------------ */
+
+/** `CSS2DRenderer` 的编辑器扩展 */
+export interface EditorCSS2DRenderer extends CSS2DRenderer {
+  resize(): void;
+
+  reset(): void;
+}
+
+/** `CSS3DRenderer` 的编辑器扩展 */
+export interface EditorCSS3DRenderer extends CSS3DRenderer {
+  resize(): void;
+
+  reset(): void;
+}
+
+/** `Stats` 的编辑器扩展 */
+export interface EditorStats extends Stats {
+  /** 出于定位需求在标准 Stats 之外补上的 DOM 引用 */
+  domElement: HTMLDivElement;
+
+  /** 偏移配置，`resize()` 时读取 */
+  style: { offsetTop: number; offsetLeft: number };
+
+  /** 是否在容器中显示，赋值时挂载 / 卸载 DOM */
+  showStats: boolean;
+
+  /** 0 fps，1 ms，2 mb */
+  statsMode: number;
+
+  /** 依据容器尺寸重算位置 */
+  resize(): void;
+
+  /** 设置偏移并立即生效 */
+  setOffset(offsetTop: number, offsetLeft: number): void;
+
+  /** 将 DOM 挂到容器 */
+  created(): void;
+
+  /** 将 DOM 从容器移除 */
+  destroy(): void;
+}
+
+/* ------------------------------------------------------------------ *
+ * 交互管理
+ * ------------------------------------------------------------------ */
+
+/** 鼠标交互模式 */
+export type HandlerMode = "transform" | "select" | "none";
+
+/** 坐标轴辅助配置 */
+export interface AxesHelperState {
+  showAxes: boolean;
+
+  axesLength: number;
+
+  axesHelper: THREE.AxesHelper | null;
+}
+
+/** 网格辅助配置 */
+export interface GridHelperState {
+  showGrid: boolean;
+
+  size: number;
+
+  divisions: number;
+
+  colorCenterLine: THREE.ColorRepresentation;
+
+  colorGrid: THREE.ColorRepresentation;
+
+  gridHelper: THREE.GridHelper | null;
+}
+
+/** Box3 辅助配置 */
+export interface Box3HelperState {
+  useBox3: boolean;
+
+  color: THREE.ColorRepresentation;
+}
+
+/** 辅助工具集合 */
+export interface EditorHelpers {
+  axes: AxesHelperState;
+
+  grid: GridHelperState;
+
+  box3: Box3HelperState;
+}
+
+/** 历史栈中的一条 PRS 记录 */
+export interface HandlerHistoryRecord {
+  object: THREE.Object3D;
+
+  transform: {
+    position: Vector3Like;
+    rotation: Vector3Like;
+    scale: Vector3Like;
+  };
+}
+
+/** 撤销 / 重做栈 */
+export interface HandlerHistory {
+  list: HandlerHistoryRecord[];
+
+  reList: HandlerHistoryRecord[];
+
+  /** 当前游标，初始为 `-1` */
+  index: number;
+
+  reset(): void;
+}
+
+/** 内置右键菜单项 */
+export interface RightClickMenu {
+  name: string;
+
+  key: "selected" | "basicConf" | "materialConf" | "relatedConf" | "removeObject";
+}
+
+/** 场景点击命中的信息 */
+export interface SceneEventInfo {
+  /** 命中的物体（已按 `selectChildLevel` 上溯） */
+  object: THREE.Object3D;
+
+  /** 所属根模型 */
+  rootObject: THREE.Object3D;
+
+  /** 命中点的世界坐标 */
+  point: THREE.Vector3;
+}
+
+/** 交互、按键与辅助工具的管理对象 */
+export interface EditorHandler {
+  /** 交互模式，影响点击行为；缺省 `'transform'` */
+  mode: HandlerMode;
+
+  /** 模式下拉框选项（显示名 → 值） */
+  modeList: Record<string, HandlerMode>;
+
+  /** 是否监听键盘快捷键，赋值时绑定 / 解绑事件 */
+  openKeyEnable: boolean;
+
+  /** 是否启用右键菜单，赋值时绑定 / 解绑事件 */
+  rightClickMenusEnable: boolean;
+
+  /** 是否选中子物体而非根模型 */
+  selectChildEnabled: boolean;
+
+  /** 子物体上溯层级 */
+  selectChildLevel: number;
+
+  stats: EditorStats;
+
+  helpers: EditorHelpers;
+
+  handlerHistory: HandlerHistory;
+
+  /** 最近一次场景点击的信息（首次点击前可能尚未赋值） */
+  currentInfo?: SceneEventInfo;
+
+  /** 由编辑器初始化时注入的右键菜单分发器 */
+  setActivePanel?: (event: MouseEvent, menu: RightClickMenu) => void;
+
+  /** 取消变换控制与轮廓选中 */
+  noSelect(): void;
+
+  /** 按当前 `mode` 选中物体（先 `noSelect`） */
+  toSelect(object?: THREE.Object3D | null): void;
+
+  /** 当前选中：变换控制对象，或轮廓列表首项 */
+  getSelect(): THREE.Object3D | undefined;
+
+  /** 清空选中并重置历史栈 */
+  reset(): void;
+}
+
+/* ------------------------------------------------------------------ *
+ * 模块存档
+ * ------------------------------------------------------------------ */
+
+export interface SceneFogStorage {
+  name?: string;
+
+  type?: "linear" | "exp2";
+
+  density?: number;
+
+  color?: number;
+
+  near?: number;
+
+  far?: number;
+}
+
+export interface SceneStorage {
+  background?: { colorSpace?: string };
+
+  backgroundUrls?: string[] | null;
+
+  envBackgroundUrls?: string[] | null;
+
+  backgroundBlurriness?: number;
+
+  backgroundIntensity?: number;
+
+  environmentEnabled?: boolean;
+
+  fog?: SceneFogStorage | null;
+}
+
+export interface CameraStorage {
+  fov: number;
+
+  near: number;
+
+  far: number;
+
+  zoom: number;
+
+  /** 取 `camera.layers.mask` */
+  layers: number;
+
+  filmOffset: number;
+
+  filmGauge: number;
+
+  position: Vector3Like;
+}
+
+export interface RendererStorage {
+  outputColorSpace: string;
+
+  toneMapping: number;
+
+  toneMappingExposure: number;
+
+  shadowMap: { enabled: boolean; type: number };
+
+  color: number;
+
+  opacity: number;
+
+  sortObjects: boolean;
+
+  autoClear: boolean;
+
+  autoClearColor: boolean;
+
+  renderListCompare: Array<{ name: string; enabled: boolean }>;
+}
+
+export interface ControlsStorage {
+  autoRotate: boolean;
+
+  autoRotateSpeed: number;
+
+  enableDamping: boolean;
+
+  dampingFactor: number;
+
+  minDistance: number;
+
+  maxDistance: number;
+
+  minAzimuthAngle: number;
+
+  maxAzimuthAngle: number;
+
+  minPolarAngle: number;
+
+  maxPolarAngle: number;
+
+  minTargetRadius: number;
+
+  maxTargetRadius: number;
+
+  enablePan: boolean;
+
+  panSpeed: number;
+
+  enableRotate: boolean;
+
+  rotateSpeed: number;
+
+  enableZoom: boolean;
+
+  zoomSpeed: number;
+
+  zoomToCursor: boolean;
+
+  target: Vector3Like;
+}
+
+export interface TransformControlsStorage {
+  mode: "translate" | "rotate" | "scale";
+
+  space: "world" | "local";
+
+  size: number;
+
+  showX: boolean;
+
+  showY: boolean;
+
+  showZ: boolean;
+
+  translationSnap: number | null;
+
+  rotationSnap: number | null;
+
+  scaleSnap: number | null;
+}
+
+export interface EffectComposerStorage {
+  renderWay: "effectComposer" | "renderer";
+
+  /** 已安装特效的有序列表（含 id / enabled / 自定义字段）。`getEffectComposerStorage` 总会写入，空列表为 `[]` */
+  passes: EffectPassStorage[];
+}
+
+export interface StatsStorage {
+  showStats: boolean;
+
+  statsMode: number;
+}
+
+export interface HelpersStorage {
+  axes: Pick<AxesHelperState, "showAxes" | "axesLength">;
+
+  grid: Pick<
+    GridHelperState,
+    "showGrid" | "size" | "divisions" | "colorCenterLine" | "colorGrid"
+  >;
+
+  box3: Box3HelperState;
+}
+
+export interface HandlerStorage {
+  mode: HandlerMode;
+
+  openKeyEnable: boolean;
+
+  rightClickMenusEnable: boolean;
+
+  selectChildEnabled: boolean;
+
+  selectChildLevel: number;
+
+  stats: StatsStorage;
+
+  helpers: HelpersStorage;
+}