disposeObject3D()

释放一个 Object3D 子树中 Engine 定义的标准 Three.js 资源。它是独立工具：不需要 Engine 实例，也不会修改 Object3D 父子关系或发布 Entity 生命周期。

签名

function disposeObject3D(
  root: Object3D,
  options?: DisposeObject3DOptions,
): void;

interface DisposeObject3DOptions {
  /** 忽略 userData.shared 标记。默认 false。 */
  readonly force?: boolean;
}

默认共享保护

标准资源的 userData.shared === true 时，默认不会调用其 dispose()：

texture.userData.shared = true;
disposeObject3D(model); // texture 保留

disposeObject3D(model, { force: true }); // texture 也被释放

shared 是每个资源独立的标记。Geometry、Material、Texture、Scene 的背景/环境纹理、Skeleton 与其 boneTexture 都分别判断。工具不维护全局引用计数；同一调用内仅按 identity 去重，多次调用遵循 Three.js 自身的重复 dispose 语义。

Skeleton 与其 boneTexture 的 shared 标记应当成对设置。只标记 Skeleton 时，Skeleton 自身保留，其 boneTexture 仍会被释放，留下一个持有已释放纹理的存活 Skeleton。

扫描边界

会扫描并释放：Object3D 子树的 direct geometry、material（含数组）、Material 自身直接 Texture 数据属性、Scene direct background / environment，以及 SkinnedMesh direct skeleton 和 boneTexture。

不会读取 getter 或原型属性，也不会进入 Shader uniforms、userData 内容、业务容器、WebGLRenderTarget、Pass、customDepthMaterial、customDistanceMaterial 或 Scene.overrideMaterial。这些由创建方自行释放。

失败语义

调用先固定资源快照，再尽力尝试全部资源。一个失败原样抛出；多个失败以发生顺序组成 AggregateError。资源 dispose 不会解绑 Object3D，也不影响 Entity/World/Engine 生命周期。

与 Engine 终态的关系

Entity、World 和 Engine 的终态均复用同一资源处置内核，且始终采用默认 shared 保护。若确实需要忽略保护，请在终态前显式调用 disposeObject3D(root, { force: true })。