Plugin

Plugin 是构造期静态安装的轻量扩展，只包含可选 setup 与 dispose：

import type { Plugin } from '@tripo3d/engine';

const metricsPlugin: Plugin = {
  name: 'metrics',
  setup({ engine }) {
    console.log('renderer:', engine.renderer);
  },
  dispose({ engine }) {
    console.log('disposed:', engine.disposed);
  },
};

const engine = createEngine({
  plugins: [metricsPlugin],
});

契约

interface Plugin {
  readonly name: string;
  readonly setup?: (context: { engine: Engine }) => void;
  readonly dispose?: (context: { engine: Engine }) => void;
}

• Plugin 数组在原生资源取得前复制、校验并按 object identity 去重；
• setup 在构造期按声明顺序同步执行；
• setup 不能返回 Promise/thenable；
• Engine dispose 时，已接纳 Plugin 按逆安装顺序调用 dispose；
• Plugin 没有 runtime manager、动态 use/unuse、Definition replacement 或实例拦截能力。

需要运行时启停的领域功能应使用 System 或 Pass Definition，而不是动态 Plugin。

setup 边界

Plugin setup 可以读取已建立的 Engine、注册 System/Pass、订阅 Event，但不能在 construction scope 中调用 start、stop 或 dispose。

任一 Plugin setup 失败会使整个 createEngine 失败。Engine 保存原始错误为 primary，并尽力终结已接纳的 Plugin 与其他 owner；不会返回部分构造实例。

dispose 边界

Plugin 只释放自己创建或借用后明确拥有的业务资源。它不应该重复释放 Engine 的 renderer、Canvas、World、Entity 或内部 Composer。

Engine 先发布全局终态，再执行业务清理。因此 Plugin dispose 中可以观察 engine.disposed === true，但不能再进行 live mutation。

History adapter

import {
  createHistory,
  createHistoryPlugin,
} from '@tripo3d/engine/history';

const history = createHistory();
const engine = createEngine({
  plugins: [createHistoryPlugin(history)],
});

History Plugin 不把 History 变成 Engine 子系统，只在 dispose 时清空 borrowed 栈。

Vue adapter

import { createPluginVue } from '@tripo3d/engine/vue';

const engine = createEngine({
  plugins: [createPluginVue()],
});

Vue Plugin 只在构造时对已经固定存在的 Engine、Canvas、renderer、默认 Camera/World/View、Pipeline、Pointer 与 Raycaster 调用 markRaw。它不侵入 Core，不把 Component/System/Script 自动包装为 reactive，也不处理以后动态创建的 Three.js 对象。

业务仍应使用 shallowRef 保存外部实例，并在复杂对象进入 Vue 状态前显式 markRaw。

下一步

• History
• Vue 集成
• createEngine
• API：Plugin