three-editor-ai 0.0.0-stage → 0.0.1

package/declare/addons.d.ts

@@ -0,0 +1,88 @@
+import type * as THREE from "three";
+
+/* ------------------------------------------------------------------ *
+ * 内置核心 id
+ * ------------------------------------------------------------------ */
+
+/**
+ * 内置组件（核心）id。
+ * 其中仅 `model` 提供了 `install` 级服务，其余安装后为 `{}`。
+ */
+export type BuiltinCoreId =
+  | "inner"
+  | "light"
+  | "model"
+  | "mirror"
+  | "lightColumn";
+
+/* ------------------------------------------------------------------ *
+ * 内置特效
+ * ------------------------------------------------------------------ */
+
+/**
+ * 内置后期特效 id（随包注册的子集）。
+ * `outlinePass` / `outputPass` 默认启用。
+ */
+export type BuiltinEffectId = "outlinePass" | "outputPass";
+
+/* ------------------------------------------------------------------ *
+ * 模型核心（cores.model）
+ * ------------------------------------------------------------------ */
+
+/** 模型信息，用于 `cores.model.loadModel` */
+export interface ModelInfo {
+  url: string;
+
+  /** 传字符串给 `loadModel` 时按扩展名推断；传对象时需自带 */
+  type?: "FBX" | "GLB" | "GLTF" | "OBJ";
+}
+
+/** 加载进度回调集合 */
+export interface LoaderService {
+  /** `ratio` 为 `loaded / total` */
+  progress?: (ratio: number, xhr: { loaded: number; total: number }) => void;
+
+  complete?: (object: THREE.Object3D) => void;
+
+  error?: (error: unknown) => void;
+}
+
+/** 动画播放参数（`modelAnimationPlay` 运行时会读取 `actionIndexs`） */
+export interface AnimationPlayQuery {
+  /** 是否立即播放（存档还原时用） */
+  initPlay?: boolean;
+
+  /** 播放速度 */
+  speed?: number;
+
+  /** 起始时间 */
+  startTime?: number;
+
+  /** 是否循环 */
+  loop?: boolean;
+
+  /** 按索引指定要播放的动画；缺省或非数组时运行时会抛错 */
+  actionIndexs: boolean[];
+
+  /** 逐帧回调（无参，在 mixer 更新前调用） */
+  frameCallback?: () => void;
+}
+
+/** `cores.model` 提供的编辑器级服务 */
+export interface ModelCore {
+  /** 缺省模型地址 */
+  url: string;
+
+  progressList: unknown[];
+
+  /** 加载模型，返回模型信息与加载器服务 */
+  loadModel(
+    val: string | ModelInfo,
+  ): { modelInfo: ModelInfo; loaderService: LoaderService } | undefined;
+
+  /** 播放模型内置动画；`query.actionIndexs` 必填 */
+  modelAnimationPlay(
+    group: THREE.Object3D,
+    query: AnimationPlayQuery,
+  ): { actions: THREE.AnimationAction[]; mixer: THREE.AnimationMixer };
+}

package/declare/component.d.ts

@@ -0,0 +1,158 @@
+import type * as THREE from "three";
+import type { GUI } from "lil-gui";
+import type { EditorContext } from "./main";
+
+/** 带编辑器类型标记的场景物体（创建完成后由内核写入 `editorType`） */
+export interface ComponentRoot extends EditorObject3D {
+  editorType: string;
+}
+
+/**
+ * 编辑器在 `Object3D` 上挂载的运行时字段（克隆关系、组件类型）。
+ * 加入 / 移出场景请订阅 `scene-add` / `scene-remove`；
+ * 组件根节点移除另见 `component-remove`。
+ */
+export interface EditorObject3D extends THREE.Object3D {
+  editorType?: string;
+
+  /** 由本物体克隆出的实例列表 */
+  clones?: EditorObject3D[];
+
+  /** 若自身为克隆体，指向源物体 */
+  ORIGINAL?: EditorObject3D;
+}
+
+/**
+ * `Component.meta` 的配置类型。`function` 调用实例方法，不写入存档。
+ * `texture` 对应图片 URL 字符串或 `null`；面板显示图片预览和 URL 编辑框，清空时写入 `null`。
+ * 纹理加载、替换和释放由组件属性 setter 处理。
+ */
+export type ComponentMetaType =
+  | "number"
+  | "boolean"
+  | "string"
+  | "vec2"
+  | "vec3"
+  | "vec4"
+  | "euler"
+  | "color"
+  | "texture"
+  | "select"
+  | "function";
+
+export interface ComponentMetaOption {
+  label: string;
+
+  value: unknown;
+}
+
+/**
+ * 组件可配置字段约定，由宿主依据 `meta` 生成控件。
+ * `key` 支持 `position`、`children.0.material.color` 等路径，必须指向真实属性或方法。
+ * `meta.init` 的路径相对于组件的 `initParams`，省略 `initParams.` 前缀；
+ * `meta.props` 的路径相对于 `create` 返回的实例根节点。
+ * 宿主直接写入属性；需要重建几何等副作用时，由实例属性的 setter 处理。
+ */
+export interface ComponentMeta {
+  key: string;
+
+  type: ComponentMetaType;
+
+  label?: string;
+
+  min?: number;
+
+  max?: number;
+
+  step?: number;
+
+  /** `euler` 可用，例如 `"deg"`；Three.js 内部单位仍是弧度 */
+  unit?: string;
+
+  options?: ComponentMetaOption[];
+
+  default?: unknown;
+}
+
+/** 可配置项声明；声明数据不要求组件实现面板。 */
+export interface ComponentMetadata {
+  /**
+   * 创建前的参数，固定映射到组件的 `initParams`；宿主临时赋值后调用 `create`。
+   * `key: "count"` 对应 `initParams.count`，无需 `initParams.` 前缀，支持嵌套路径。
+   * 实例创建后不通过这些字段修改该实例。
+   */
+  init?: ComponentMeta[];
+
+  /** 实例可配置属性，路径相对于 create 返回的根节点 */
+  props?: ComponentMeta[];
+}
+
+/**
+ * 自定义组件（核心）描述符。
+ * `id`、`description` 与 `create` 必填；`id` 已存在时 `installComponent` / `register('component', …)` 会被忽略。
+ * 面板接口均为可选；组件可以仅实现创建与存档逻辑。
+ */
+export interface Component {
+  /** 必填，唯一标识，同时作为 `cores[id]` 与 `object3D.editorType` */
+  id: string;
+
+  /** 面板显示名 */
+  name?: string;
+
+  /** 必填，组件描述，说明用途、可配置内容及行为 */
+  description: string;
+
+  /**
+   * 初始化默认参数；提供 `meta.init` 时应定义其字段对应的默认值。
+   * 宿主通过 `meta.init` 配置此对象，`create` 通过 `this.initParams` 读取。
+   * 创建时用存档覆盖默认值，例如 `{ ...this.initParams, ...storage }`。
+   */
+  initParams?: Record<string, unknown>;
+
+  /** 编辑器级服务，返回值挂到 `cores[id]` */
+  install?: (ctx: EditorContext) => object;
+
+  /** 卸载时调用（`unInstallComponent`） */
+  unInstall?: (ctx: EditorContext) => void;
+
+  /** 初始参数面板（添加前） */
+  initPanel?: (folder: GUI, ctx: EditorContext) => void;
+
+  /**
+   * 必填，依据存档创建物体，可返回 Promise。
+   * `storage` 可能为 `null` / `undefined`；返回根对象，由内核设置 `editorType` 并加入场景。
+   * `storage` 为 `any`：各核心可收窄为自身存档结构（参数位置逆变，不宜用 unknown）。
+   */
+  create: (
+    storage: any,
+    ctx: EditorContext,
+  ) => THREE.Object3D | Promise<THREE.Object3D | null | undefined> | null | undefined;
+
+  /**
+   * 可选，渲染前更新场景中的每个组件实例。
+   * `root` 为 `create` 返回的实例根节点，可直接访问其数据和子对象，无需缓存实例引用。
+   * `delta` 为相邻渲染帧的间隔（秒）；
+   * `elapsed` 为编辑器渲染循环启动后的累计时间（秒），所有实例共享。
+   * 实例移出场景或组件卸载后停止调用，无需自行注册 RAF 或场景帧回调。
+   */
+  update?: (root: THREE.Object3D, delta: number, elapsed: number) => void;
+
+  /** 存档附加数据（与 `getMeshStorage` 合并），应为可序列化的自定义配置 */
+  getStorage?: (root: ComponentRoot, ctx: EditorContext) => Record<string, unknown>;
+
+  /**
+   * 还原附加数据（基础 mesh 字段由内核先还原）；支持空存档及重复调用。
+   * `storage` 为 `any`：各核心可收窄为自身存档结构。
+   */
+  setStorage?: (
+    root: ComponentRoot,
+    storage: any,
+    ctx: EditorContext,
+  ) => void;
+
+  /** 单个物体的控制面板 */
+  setPanel?: (root: ComponentRoot, folder: GUI, ctx: EditorContext) => void;
+
+  /** 标识组件可配置的内容，见 `ComponentMetadata`；有可配置属性时应提供 */
+  meta?: ComponentMetadata;
+}

package/declare/events.d.ts

@@ -0,0 +1,102 @@
+import type { Component, ComponentRoot, EditorObject3D } from "./component";
+
+/* ------------------------------------------------------------------ *
+ * 已知事件数据
+ * ------------------------------------------------------------------ */
+
+/** `component-register`：组件注册成功 */
+export interface ComponentRegisterEventData {
+  component: Component;
+}
+
+/** `component-create`：组件实例创建完成 */
+export interface ComponentCreateEventData {
+  component: Component;
+
+  /** 创建完成并已加入场景的组件根节点 */
+  instance: ComponentRoot;
+
+  /** 创建时传入的存档；面板「添加」路径为 `null` */
+  storage: unknown;
+}
+
+/** `component-remove`：组件根节点从场景移除 */
+export interface ComponentRemoveEventData {
+  /** 对应的组件原型（`cores.SHEET[editorType]`） */
+  component: Component;
+
+  instance: ComponentRoot;
+}
+
+/** `scene-add` / `scene-remove`：场景增删物体 */
+export interface SceneObjectEventData {
+  object: EditorObject3D;
+}
+
+/**
+ * 编辑器内置事件表。
+ * 键为事件名，值为该事件回调收到的唯一数据参数。
+ * `scene.emit` 与编辑器 `emit` 是同一个函数。
+ */
+export interface EditorEventMap {
+  "component-register": ComponentRegisterEventData;
+
+  "component-create": ComponentCreateEventData;
+
+  /**
+   * 组件根节点移除完成时触发。
+   * 在 `scene-remove` 同步阶段由 cores 发出（`editorType` 能命中 `SHEET`）。
+   */
+  "component-remove": ComponentRemoveEventData;
+
+  /** `scene.add` 完成后触发 */
+  "scene-add": SceneObjectEventData;
+
+  /** `scene.remove` 完成后触发 */
+  "scene-remove": SceneObjectEventData;
+}
+
+/* ------------------------------------------------------------------ *
+ * on / off / emit
+ * ------------------------------------------------------------------ */
+
+/** 已知事件的监听回调 */
+export type EditorEventListener<K extends keyof EditorEventMap> = (
+  data: EditorEventMap[K],
+) => void;
+
+/** 自定义（未知）事件的监听回调 */
+export type EditorUnknownEventListener = (...payload: unknown[]) => void;
+
+/** 挂在 `args` / `ThreeEditor` 上的事件操作（不暴露内部监听表） */
+export interface EditorEventApi {
+  /** 订阅已知事件 */
+  on<K extends keyof EditorEventMap>(
+    type: K,
+    fn: EditorEventListener<K>,
+  ): void;
+
+  /** 订阅自定义事件 */
+  on(type: string, fn: EditorUnknownEventListener): void;
+
+  /**
+   * 解除已知事件订阅。
+   * 省略 `fn` 时清空该 type 下全部监听。
+   */
+  off<K extends keyof EditorEventMap>(
+    type: K,
+    fn?: EditorEventListener<K>,
+  ): void;
+
+  /** 解除自定义事件订阅；省略 `fn` 时清空该 type 下全部监听 */
+  off(type: string, fn?: EditorUnknownEventListener): void;
+
+  /** 触发已知事件 */
+  emit<K extends keyof EditorEventMap>(
+    type: K,
+    data: EditorEventMap[K],
+  ): void;
+
+  /** 触发自定义事件 */
+  emit(type: string, ...payload: unknown[]): void;
+}

package/declare/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 类型声明汇总。
+ * - `component`：组件协议、根对象与可选面板字段
+ * - `main`：编辑器上下文、组件管理器、存档与面板 API
+ * - `events`：事件名与载荷（组件注册/创建/移除，场景添加/移除）
+ * - `modules`：scene / camera / renderer / controls / effectComposer / handler 等运行时模块
+ * - `addons`：内置核心与内置后期特效
+ * - 主类 `ThreeEditor`：仅从 `lib/main` / 包根 `index.d.ts` 导出（保证值侧）
+ */
+export * from "./main";
+export * from "./component";
+export * from "./events";
+export * from "./modules";
+export * from "./addons";
+
+export * as THREE from "three";
+export { default as gsap } from "gsap";

package/declare/main.d.ts

@@ -0,0 +1,287 @@
+import type * as THREE from "three";
+import type { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
+import type { Controller, GUI } from "lil-gui";
+import type { ModelCore } from "./addons";
+import type { EditorEventApi } from "./events";
+import type { Component, ComponentRoot } from "./component";
+import type {
+  EditorScene,
+  EditorCamera,
+  EditorRenderer,
+  EditorTransformControls,
+  EditorEffectComposer,
+  EditorCSS2DRenderer,
+  EditorCSS3DRenderer,
+  EditorStats,
+  EditorHandler,
+  EditorHelpers,
+  EditorPass,
+  EffectPassStorage,
+  LoopRenderFn,
+  SceneStorage,
+  CameraStorage,
+  RendererStorage,
+  ControlsStorage,
+  TransformControlsStorage,
+  EffectComposerStorage,
+  HandlerStorage,
+} from "./modules";
+
+/** 兼容原有组件类型导入路径，声明统一维护在 component.d.ts。 */
+export type * from "./component";
+
+/** `new ThreeEditor(DOM, parameters)` 的第二个参数 */
+export interface EditorParameters {
+  /** 渲染像素比，缺省取 `window.devicePixelRatio` */
+  pixelRatio?: number;
+
+  /** 透传给 `THREE.WebGLRenderer` 的参数，覆盖默认的 antialias / alpha / logarithmicDepthBuffer */
+  webglRenderParams?: THREE.WebGLRendererParameters;
+}
+
+/**
+ * 传入核心 / 面板 / 特效等扩展点的运行时上下文。
+ * 与内部 `args` 同形；组件 `create` / `install` 等收到的即此对象（含 `cores` / `handler`）。
+ */
+export interface EditorContext extends EditorEventApi {
+  scene: EditorScene;
+
+  camera: EditorCamera;
+
+  renderer: EditorRenderer;
+
+  controls: OrbitControls;
+
+  transformControls: EditorTransformControls;
+
+  effectComposer: EditorEffectComposer;
+
+  css3DRender: EditorCSS3DRenderer;
+
+  css2DRender: EditorCSS2DRenderer;
+
+  stats: EditorStats;
+
+  /** 挂载编辑器的容器 DOM */
+  DOM: HTMLElement;
+
+  /** 交互 / 按键 / 辅助工具管理 */
+  handler: EditorHandler;
+
+  /** 组件管理器 */
+  cores: Cores;
+}
+
+/** 编辑器启动后挂到 `lil-gui` 原型上的方法（`lib/Van/Panel.js`） */
+declare module "lil-gui" {
+  interface GUI {
+    /** 返回新建并打开的子文件夹，不是调用方自身 */
+    addOpenFolder(name: string): GUI;
+
+    addDateFolder(name: string): GUI;
+
+    /** 悬浮文件夹。缺省宽 `220`、高 `'auto'`。返回新建的子文件夹 */
+    addDragFolder(
+      name: string,
+      params?: { width?: number; height?: number | string },
+    ): GUI;
+
+    addFn(fn: () => unknown, ...args: unknown[]): Controller;
+
+    addHexColor(color: THREE.Color): Controller;
+
+    destroyPanel(): void;
+
+    message(text: string, duration?: number): void;
+  }
+}
+
+/**
+ * 组件管理器（`editor.cores`）。
+ * 内置核心为 `inner` / `light` / `model` / `mirror` / `lightColumn`，
+ * 其中仅 `model` 提供了 `install` 级服务，其余为 `{}`。
+ */
+export interface Cores {
+  /** 已注册的描述符表 */
+  SHEET: Record<string, Component>;
+
+  /** 实例根到其 `update` 帧回调；移出场景或卸载时移除 */
+  UPDATEMAP: WeakMap<ComponentRoot, LoopRenderFn>;
+
+  /** 运行时缓存位（当前实现初始化为 `null`） */
+  storage: CoresStorage | null;
+
+  /** 注册组件，返回该核心的服务对象；`id` 已存在时返回 `undefined`（不重复 install） */
+  installComponent(descriptor: Component): object | undefined;
+
+  /** 按 id 与存档创建实例并加入场景 */
+  createComponent(
+    id: string,
+    storage?: unknown,
+  ): Promise<ComponentRoot | undefined>;
+
+  /** 卸载组件：移除场景实例、调用 `unInstall`、清除注册表 */
+  unInstallComponent(id: string): void;
+
+  /**
+   * 存档还原时遇到未注册 id 的回调。
+   * 由 `ThreeEditor.needRegister` 注入。
+   */
+  needRegisterComponentCallBack?: (id: string, storage: MeshStorage[]) => void;
+
+  /** 内置模型服务。构造时已安装；`unRegister('component', 'model')` 之后没有该字段 */
+  model?: ModelCore;
+
+  /** 各核心 `install` 返回值挂在对应 id 下 */
+  [id: string]: unknown;
+}
+
+/* ------------------------------------------------------------------ *
+ * 存档结构
+ * ------------------------------------------------------------------ */
+
+/** 序列化后的三维向量 */
+export interface Vector3Like {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/** 序列化后的欧拉角（含 order） */
+export interface EulerLike {
+  x: number;
+  y: number;
+  z: number;
+  order?: THREE.EulerOrder;
+}
+
+/** 物体通用存档字段（Common/Mesh.js 序列化结果） */
+export interface MeshStorage {
+  name?: string;
+
+  visible?: boolean;
+
+  renderOrder?: number;
+
+  castShadow?: boolean;
+
+  receiveShadow?: boolean;
+
+  frustumCulled?: boolean;
+
+  position?: Vector3Like;
+
+  rotation?: EulerLike;
+
+  scale?: Vector3Like;
+
+  /** 层遮罩，取 `layers.mask` */
+  layers?: number;
+
+  /** 克隆体存档 */
+  clones?: MeshStorage[];
+
+  /** 核心自定义字段由各自的 getStorage 追加（`editorType` 不在基础序列化里，由 cores 分组键体现） */
+  [key: string]: unknown;
+}
+
+/** 键为核心 id，值为该核心下的物体存档。场景里没有实例的核心不会写入 */
+export type CoresStorage = Record<string, MeshStorage[]>;
+
+/** `getEditorStorage()` 的返回值，也是 `setEditorStorage()` 的入参 */
+export interface EditorStorage {
+  scene: SceneStorage;
+
+  camera: CameraStorage;
+
+  renderer: RendererStorage;
+
+  controls: ControlsStorage;
+
+  transformControls: TransformControlsStorage;
+
+  effectComposer: EffectComposerStorage;
+
+  handler: HandlerStorage;
+
+  cores: CoresStorage;
+}
+
+/* ------------------------------------------------------------------ *
+ * 面板 API
+ * ------------------------------------------------------------------ */
+
+/** 直接构建各分组面板的底层接口，`openEditorPanel` 内部即调用它们 */
+export interface PanelApi {
+  basicPanelApi: {
+    setRendererPanel(
+      renderer: EditorRenderer,
+      folder: GUI,
+      scene: EditorScene,
+    ): void;
+
+    setScenePanel(scene: EditorScene, folder: GUI): void;
+
+    setCameraPanel(camera: EditorCamera, folder: GUI): void;
+
+    setControlsPanel(controls: OrbitControls, folder: GUI): void;
+
+    setTransformControlsPanel(
+      transformControls: EditorTransformControls,
+      folder: GUI,
+    ): void;
+
+    setEffectComposerPanel(
+      effectComposer: EditorEffectComposer,
+      folder: GUI,
+    ): void;
+  };
+
+  handlerPanelApi: {
+    setStatsPanel(stats: EditorStats, folder: GUI): void;
+
+    setHelpersPanel(
+      scene: EditorScene,
+      transformControls: EditorTransformControls,
+      helpers: EditorHelpers,
+      folder: GUI,
+    ): void;
+  };
+}
+
+/* ------------------------------------------------------------------ *
+ * 注册 / 依赖注入
+ * ------------------------------------------------------------------ */
+
+/** `register` / `needRegister` 使用的模块类型 */
+export type RegisterModuleType = "component" | "effect";
+
+/** 构造结束时内置组件与特效注册表的快照（`editor.INNER_SHEETS`） */
+export interface InnerSheets {
+  component: Record<string, Component>;
+
+  effect: Record<string, EditorPass>;
+}
+
+/**
+ * `getSheetsByStorage` 的返回值。
+ * 只保留存档里出现、且不属于 `INNER_SHEETS` 的 id；当前未注册时值为 `undefined`。
+ */
+export interface StorageSheets {
+  component: Record<string, Component | undefined>;
+
+  effect: Record<string, EditorPass | undefined>;
+}
+
+/**
+ * 存档还原遇到未注册模块时的回调。
+ * 组件的 `storage` 是该 id 下的物体存档数组；特效的 `storage` 是单条 pass 存档。
+ */
+export interface NeedRegisterCallback {
+  (type: "component", id: string, storage: MeshStorage[]): void;
+
+  (type: "effect", id: string, storage: EffectPassStorage): void;
+}
+
+/** `ThreeEditor.inject` 的依赖表：值为模块对象或 import map URL */
+export type InjectDeps = Record<string, string | object>;