tresjs-core-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tresjs/tres

@tresjs/core

Tresjs/tres

@tresjs/core

Version: 5.5.0 (Feb 2026) Deps: @pmndrs/pointer-events@^6.6.17, @vue/devtools-api@^7.7.2, @vueuse/core@^13.9.0, radashi@^12.6.2 Tags: beta: 2.0.0-beta.13 (Apr 2023), next: 5.0.0-next.6 (Jun 2025), alpha: 5.0.0-alpha.2 (Sep 2025), rc: 5.0.0-rc.0 (Sep 2025), latest: 5.5.0 (Feb 2026)

References: Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • GitHub Discussions — Q&A, patterns, recipes • Releases — changelog, breaking changes, new APIs

**版本：**5.5.0（2026年2月） 依赖：@pmndrs/pointer-events@^6.6.17、@vue/devtools-api@^7.7.2、@vueuse/core@^13.9.0、radashi@^12.6.2 **版本标签：**beta: 2.0.0-beta.13（2023年4月）、next: 5.0.0-next.6（2025年6月）、alpha: 5.0.0-alpha.2（2025年9月）、rc:5.0.0-rc.0（2025年9月）、latest:5.5.0（2026年2月）

参考资源：文档——API参考、使用指南 • GitHub问题——bug报告、解决方案、边缘案例 • GitHub讨论——问答、模式、实践方案 • 版本发布记录——更新日志、破坏性变更、新API

API Changes

API变更

This section documents version-specific API changes — prioritize recent major/minor releases.

BREAKING:
```
useLoader
```
— returns reactive state
```
{ state, isLoading, error, progress }
```
since v5, no longer returns a Promise source
BREAKING: Pointer Events — renamed to native DOM names (e.g.,
```
@pointerdown
```
instead of
```
@pointer-down
```
) in v5 source
BREAKING:
```
useTexture
```
— removed from core in v5, moved to
```
@tresjs/cientos
```
package source
BREAKING: ESM-only — TresJS v5 is ESM-only; UMD build and CommonJS
```
require()
```
are no longer supported source
BREAKING:
```
TresCanvas
```
Props — WebGL context props like
```
alpha
```
,
```
antialias
```
,
```
stencil
```
, and
```
depth
```
are now readonly and non-reactive in v5 source
BREAKING:
```
useTresContext().camera
```
— returns a state object in v5; use
```
useTres().camera
```
for the active camera instance source
BREAKING: Renderer Context —
```
renderer
```
is now readonly in
```
useTresContext()
```
;
```
performance
```
state was removed from context in v5 source
BREAKING: Event Bubbling — only the first intersected element triggers pointer events since v5 to align with standard behavior source
NEW:
```
Context
```
Component — exported in v5.5.0 (as
```
TresCanvasContext
```
) for advanced scene and state management source
NEW: Kebab-case Support — support for components written in kebab-case (e.g.,
```
<tres-mesh>
```
) added in v5.1.0 source
NEW:
```
primitive
```
Prefix — added
```
prefix
```
option for primitives in v5.3.0 to avoid name collisions source
NEW:
```
TresCanvasProps
```
/
```
TresCanvasEmits
```
— explicitly exported types added in v5.2.0 for better TypeScript integration source

REMOVED: Legacy Composables —

useRenderLoop

useCamera

useTresReady

useSeek

useRaycaster

, and

useLogger

removed in v5 source

NEW:
```
useForwardPropsEmits
```
— integrated into
```
TresCanvas
```
in v5.3.0 for streamlined event and prop handling source

Also changed:

useLoop

replaces

useRenderLoop

useGraph

replaces

useSeek

@ready

event replaces

useTresReady

useTres()

replaces common

useTresContext()

usage ·

TresCanvas

supports

useLegacyLights

prop (deprecated) ·

useLoader

supports

extensions

and reactive paths.

本节记录特定版本的API变更——优先参考近期的主版本/次版本更新。

破坏性变更：
```
useLoader
```
——从v5版本开始返回响应式状态
```
{ state, isLoading, error, progress }
```
，不再返回Promise 来源
破坏性变更：Pointer Events——v5版本中重命名为原生DOM名称（例如使用
```
@pointerdown
```
替代
```
@pointer-down
```
）来源
破坏性变更：
```
useTexture
```
——v5版本中从核心库移除，迁移至
```
@tresjs/cientos
```
包来源
破坏性变更：仅支持ESM——TresJS v5仅支持ESM；不再支持UMD构建和CommonJS的
```
require()
```
语法来源
破坏性变更：
```
TresCanvas
```
属性——v5版本中，WebGL上下文属性如
```
alpha
```
、
```
antialias
```
、
```
stencil
```
和
```
depth
```
变为只读且非响应式来源
破坏性变更：
```
useTresContext().camera
```
——v5版本中返回状态对象；如需获取活跃相机实例，请使用
```
useTres().camera
```
来源
破坏性变更：渲染器上下文——v5版本中
```
useTresContext()
```
中的
```
renderer
```
变为只读；上下文移除了
```
performance
```
状态来源
破坏性变更：事件冒泡——v5版本中仅第一个被交叉检测到的元素触发指针事件，以对齐标准行为来源
新增功能：
```
Context
```
组件——v5.5.0版本中导出（别名
```
TresCanvasContext
```
），用于高级场景和状态管理来源
新增功能：短横线命名支持——v5.1.0版本中支持短横线命名的组件（例如
```
<tres-mesh>
```
）来源
新增功能：
```
primitive
```
前缀——v5.3.0版本中为primitive添加
```
prefix
```
选项，避免名称冲突来源
新增功能：
```
TresCanvasProps
```
/
```
TresCanvasEmits
```
——v5.2.0版本中显式导出类型，提升TypeScript集成体验来源
移除功能：遗留组合式函数——v5版本中移除
```
useRenderLoop
```
、
```
useCamera
```
、
```
useTresReady
```
、
```
useSeek
```
、
```
useRaycaster
```
和
```
useLogger
```
来源
新增功能：
```
useForwardPropsEmits
```
——v5.3.0版本中集成到
```
TresCanvas
```
，简化事件和属性处理来源

其他变更：

useLoop

替代

useRenderLoop

useGraph

替代

useSeek

@ready

事件替代

useTresReady

useTres()

替代

useTresContext()

的常见用法 ·

TresCanvas

支持

useLegacyLights

属性（已废弃） ·

useLoader

支持

extensions

和响应式路径。

Best Practices

最佳实践

Use
```
shallowRef
```
with template refs to access Three.js instances directly in high-frequency render loops. This avoids Vue's deep proxy overhead, which can be significantly slower than direct property access source

vue

<script setup lang="ts">
const meshRef = shallowRef<TresInstance | null>(null)
const { onBeforeRender } = useLoop()

onBeforeRender(({ elapsed }) => {
  if (meshRef.value) meshRef.value.rotation.y = elapsed
})
</script>

<template>
  <TresMesh ref="meshRef" />
</template>

Prefer
```
shallowRef
```
and
```
shallowReactive
```
over
```
ref
```
or
```
reactive
```
for Three.js objects. This maintains reactivity for the reference itself while preventing expensive deep tracking of complex internal Three.js properties source
Set
```
renderMode="on-demand"
```
on
```
<TresCanvas>
```
for non-game applications to reduce CPU/GPU usage. The scene will only re-render when props change or when manual invalidation is explicitly triggered source
Manually trigger a render using
```
invalidate()
```
from
```
useLoop
```
or
```
useTres
```
when modifying instances via template refs or direct mutations in
```
on-demand
```
mode, as these changes are invisible to Vue's reactivity system source
Ensure animations are frame-rate independent by using the
```
delta
```
parameter in
```
useLoop
```
callbacks. This guarantees consistent movement speed across different display refresh rates (e.g., 60Hz vs 144Hz) source

onBeforeRender(({ delta }) => {
  // Moves 2 units per second regardless of frame rate
  mesh.position.x += delta * 2
})

Use the
```
args
```
prop for values required at Three.js instantiation (like geometry dimensions). Note that changing these reactive values at runtime forces TresJS to recreate the entire instance, which is performance-heavy source
Take complete control of the render process using
```
render
```
from
```
useLoop
```
for custom post-processing or multi-pass setups. You must call
```
notifySuccess()
```
at the end of the function to maintain the loop state source
Orchestrate complex update sequences using the
```
priority
```
argument in
```
onBeforeRender
```
(default 0). Higher priority numbers ensure a callback runs after those with lower priorities within the same frame source
Explicitly call
```
dispose()
```
from
```
@tresjs/core
```
for Three.js objects created programmatically and used via
```
<primitive />
```
. TresJS automatically disposes of template-defined components but cannot track lifecycle for raw objects source
Use
```
useGraph
```
to generate a reactive map of named meshes, materials, and nodes from a complex hierarchy (like a loaded GLTF). This enables direct, named access without manually traversing the object tree source

在高频渲染循环中，使用
```
shallowRef
```
配合模板引用直接访问Three.js实例。这能避免Vue深度代理带来的性能开销，因为深度代理的速度远慢于直接属性访问来源

vue

<script setup lang="ts">
const meshRef = shallowRef<TresInstance | null>(null)
const { onBeforeRender } = useLoop()

onBeforeRender(({ elapsed }) => {
  if (meshRef.value) meshRef.value.rotation.y = elapsed
})
</script>

<template>
  <TresMesh ref="meshRef" />
</template>

对于Three.js对象，优先使用
```
shallowRef
```
和
```
shallowReactive
```
而非
```
ref
```
或
```
reactive
```
。这可以保持引用本身的响应式，同时避免对Three.js复杂内部属性进行昂贵的深度追踪来源
对于非游戏类应用，在
```
<TresCanvas>
```
上设置
```
renderMode="on-demand"
```
以降低CPU/GPU占用。场景仅会在属性变更或手动触发失效时重新渲染来源
在
```
on-demand
```
模式下，通过模板引用或直接修改实例时，需使用
```
useLoop
```
或
```
useTres
```
中的
```
invalidate()
```
手动触发渲染，因为这些变更无法被Vue的响应式系统检测到来源
使用
```
useLoop
```
回调中的
```
delta
```
参数确保动画帧率无关。这可以保证在不同刷新率的显示器（如60Hz vs 144Hz）上移动速度一致来源

onBeforeRender(({ delta }) => {
  // 无论帧率如何，每秒移动2个单位
  mesh.position.x += delta * 2
})

使用
```
args
```
属性传递Three.js实例化所需的值（如几何体尺寸）。注意：运行时修改这些响应式值会强制TresJS重新创建整个实例，性能开销较大来源
如需自定义后期处理或多通道渲染设置，使用
```
useLoop
```
中的
```
render
```
完全控制渲染流程。必须在函数末尾调用
```
notifySuccess()
```
以维持循环状态来源
使用
```
onBeforeRender
```
中的
```
priority
```
参数（默认值0）编排复杂的更新序列。优先级数值越高，回调在同一帧中执行的顺序越靠后来源
对于通过
```
<primitive />
```
使用的、以编程方式创建的Three.js对象，需显式调用
```
@tresjs/core
```
中的
```
dispose()
```
方法。TresJS会自动处理模板定义组件的生命周期，但无法追踪原生对象的生命周期来源
使用
```
useGraph
```
从复杂层级结构（如加载的GLTF）生成响应式的网格、材质和节点映射。无需手动遍历对象树即可直接通过名称访问目标元素来源