tresjs-core-skilld

@tresjs/core 5.9.0

Three.js 的 Vue 自定义渲染器：为任何 THREE 类添加前缀 Tres，即可将其作为组件使用（<TresMesh>、<TresBoxGeometry>）。已准备的源文件：package.json、dist/tres.d.ts（公共类型）、dist/tres.js。

生成时的 npm dist-tag：latest 5.9.0、rc 5.0.0-rc.0、next 5.0.0-next.6、beta 2.0.0-beta.13、alpha 5.0.0-alpha.2。

环境限制

• 自 v5 起仅支持 ESM。不提供 UMD，也不支持 require()。import { TresCanvas } from '@tresjs/core'。
• Peer 依赖：vue >=3.4、three >=0.133（package.json:44-46）。基于 three ^0.184 构建。
• 时间源：r179 及更高版本使用 three Timer，较旧版本的 three 使用 Clock（dist/tres.d.ts:962-970）。
• WebGPU 仍处于实验阶段；需要使用 three/webgpu 的 Renderer 作为 renderer prop（参见 references/webgpu.md）。

设置

pnpm i @tresjs/core three
pnpm i @types/three -D   # TypeScript

Vite：将 templateCompilerOptions 展开传入 Vue 插件，否则 Tres 组件会被警告为未知自定义元素（README.md:36-50）：

import { templateCompilerOptions } from '@tresjs/core'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [vue({ ...templateCompilerOptions })],
})

另有单独的子路径导出 @tresjs/core/template-compiler-options，供只需要编译器选项的宿主使用（package.json:21-25）。Nuxt 项目请使用 @tresjs/nuxt，而非手动设置。

核心模型

• 组件目录根据 THREE 命名空间自动生成：类名首字母大写并加上 Tres 前缀，也支持 kebab-case（<tres-mesh>，自 v5.1.0 起支持）（dist/tres.d.ts:497-509）。
• args 用于传递构造函数参数：<TresBoxGeometry :args="[1, 2, 3]" />。更改响应式 args 会重新创建整个实例；对于构造后可设置的属性，请使用 props（dist/tres.d.ts:405-411）。
• Props 会映射到实例属性。数学类型支持简写：:position="[1, 2, 3]"、:rotation="[0, Math.PI, 0]"、color="#00ff00"（dist/tres.d.ts:457-485）。
• 子级材质和几何体会通过 attach 自动附加：<TresMesh><TresBoxGeometry /><TresMeshNormalMaterial /></TresMesh> 无需显式指定 attach 即可运行。
• 将非 THREE 类用作 <TresMyObject> 前，先调用 extend({ MyObject })（dist/tres.d.ts:872-874）。
• <primitive :object="existingThreeObject" /> 会挂载你在 JS 中创建的对象。它不负责释放对象；请手动释放（参见 references/performance.md）。

最简场景：

<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas shadows>
    <TresPerspectiveCamera :position="[3, 3, 3]" :look-at="[0, 0, 0]" />
    <TresMesh>
      <TresBoxGeometry :args="[1, 1, 1]" />
      <TresMeshNormalMaterial />
    </TresMesh>
    <TresDirectionalLight :position="[3, 3, 3]" :intensity="1" cast-shadow />
  </TresCanvas>
</template>

如果未显式指定相机，系统会创建默认的 PerspectiveCamera（dist/tres.d.ts:682-685）。

需要了解的 API 变更

v5 破坏性变更（请参照 references/migration-v4-v5.md 进行迁移）：

• useLoader 返回响应式状态 { state, isLoading, error, progress, load }，不再返回 Promise（dist/tres.d.ts:40-65）。
• 指针事件使用原生 DOM 名称：使用 @pointerdown，而不是 @pointer-down。只有第一个相交对象会触发事件。
• useTexture 已移至 @tresjs/cientos。useRenderLoop、useCamera、useSeek、useRaycaster、useTresReady、useTresEventManager、useLogger 已移除。替代方案：useLoop、useTres、useGraph、@ready 事件。
• useTresContext().camera 是相机管理器；使用 useTres().camera 获取当前激活的相机实例（dist/tres.d.ts:574-606）。
• WebGL 上下文属性（alpha、antialias、depth、stencil、powerPreference、logarithmicDepthBuffer、preserveDrawingBuffer、failIfMajorPerformanceCaveat）为只读；请在挂载时一次性设置（dist/tres.d.ts:141-206）。

近期新增：

• 5.9.0：TresPortal 组件可将子项重新挂载到任意 Object3D/Scene 目标（dist/tres.d.ts:853-858），https://docs.tresjs.org/api/components/tres-portal
• 5.9.0：isWebGPURenderer 守卫和响应式 context.isWebGPU 标志（dist/tres.d.ts:350-367, 1204-1222）
• 5.9.0：在 WebGL 上，shadowMapType 默认为 PCFShadowMap；在 WebGPU 上默认为 PCFSoftShadowMap（dist/tres.d.ts:250-255）
• 5.8.0：fpsLimit 属性可限制渲染 FPS（dist/tres.d.ts:692-696）
• 5.7.0：通过 Timer 回退到 Clock，兼容 <r179 版本的 three（dist/tres.d.ts:962-970）
• 5.5.0：TresCanvasContext（Context 组件），用于使用自有的 <canvas>（dist/tres.d.ts:680-708）
• 5.3.0：customRendererOptions.primitivePrefix 可重命名 <primitive>（dist/tres.d.ts:622-625）
• 5.2.0：导出 TresCanvasProps / TresCanvasEmits 类型（dist/tres.d.ts:776-781）
• 完整历史记录：https://github.com/Tresjs/tres/blob/main/packages/core/CHANGELOG.md

常见任务

使用帧率无关的方式进行动画（delta 的单位为秒）：

<script setup lang="ts">
import { useLoop } from '@tresjs/core'
const { onBeforeRender } = useLoop()
const cube = shallowRef<TresInstance | null>(null)

onBeforeRender(({ delta, elapsed }) => {
  if (!cube.value) return
  cube.value.rotation.y += delta * 2        // 2 rad/s on any refresh rate
  cube.value.position.y = Math.sin(elapsed * 3) * 0.5
})
</script>

<template>
  <TresMesh ref="cube">
    <TresBoxGeometry :args="[1, 1, 1]" />
    <TresMeshNormalMaterial />
  </TresMesh>
</template>

useLoop 只能在 TresCanvas 的子组件中使用；在画布本身上，请使用 @before-loop / @loop 事件（https://docs.tresjs.org/api/composables/use-loop）。

加载模型：

import { useLoader } from '@tresjs/core'
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'

const { state: model, isLoading, error, progress } = useLoader(
  GLTFLoader,
  '/models/duck.gltf',            // MaybeRef<string>: changing the ref reloads
  { extensions: (loader) => loader.setDRACOLoader(dracoLoader) },
)
// template: <primitive v-if="!isLoading && model?.scene" :object="model.scene" />

点击网格：

<TresMesh @click="(e) => e.object.material.color.set('#ff0000')">
  <TresBoxGeometry />
  <TresMeshNormalMaterial />
</TresMesh>

事件载荷包含 point、object、distance、face、uv、xy。TresCanvas 上的 @pointermissed 可捕获点击空白区域的事件。详情请参阅：references/pointer-events.md。

最佳实践

• 对 Three.js 实例的模板引用，以及传入 <primitive> 的任何对象，使用 shallowRef；深层 ref 代理会实实在在地占用帧时间。https://docs.tresjs.org/api/advanced/performance
• 对非游戏场景，优先使用 renderMode="on-demand" 和 invalidate()；需要完全控制时，使用 renderMode="manual" 和 advance()（dist/tres.d.ts:134-139）。
• 在 on-demand 模式下，通过引用修改对象后，请调用 invalidate()，因为这些修改会绕过 Vue 响应式系统。
• 仅在后期处理或多通道渲染时使用 useLoop().render(fn) 接管渲染；fn 必须调用 notifySuccess()，否则渲染模式会失效（https://docs.tresjs.org/api/composables/use-loop）。
• 通过 onBeforeRender / onRender 的 priority 参数注册有顺序的更新（默认值为 0，值越大执行得越晚）。
• 对于已加载的 GLTF 场景，useGraph(object) 可提供按名称索引的 nodes、materials、meshes 映射，无需手动遍历（dist/tres.d.ts:565）。
• 对通过 <primitive> 使用的程序化创建对象，请调用 dispose()（从 @tresjs/core 导出）；通过模板创建的对象会自动释放。
• 除非要重新创建实例，否则请保持 args 静态；应通过属性或引用执行动画。
• 使用 v-log / v-log:material、v-light-helper、v-distance-to 指令进行调试（dist/tres.d.ts:934-952），https://docs.tresjs.org/api/utils/directives

参考资料

• references/components.md：TresCanvas 属性和事件、TresCanvasContext、TresPortal、UseLoader 组件
• references/composables.md：useTres 与 useTresContext、useLoop、useLoader、useGraph、管理器组合式函数
• references/performance.md：渲染模式、响应性、释放资源、dpr、fpsLimit
• references/pointer-events.md：事件名称、命中规则、载荷、传播
• references/webgpu.md：自定义渲染器工厂、isWebGPU、能力分支
• references/migration-v4-v5.md：v4 到 v5 的迁移详情

官方文档：https://docs.tresjs.org