Tresjs/tres @tresjs/[email protected]

Tags: beta: 2.0.0-beta.13, next: 5.0.0-next.6, alpha: 5.0.0-alpha.2

References: [Docs](./references/docs/_INDEX.md)

API Changes

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](./references/docs/content/1.getting-started/4.upgrade-guide.md)

• BREAKING: Pointer Events — renamed to native DOM names (e.g., @pointerdown instead of @pointer-down) in v5 [source](./references/docs/content/1.getting-started/4.upgrade-guide.md)

• BREAKING: useTexture — removed from core in v5, moved to @tresjs/cientos package [source](./references/docs/content/1.getting-started/4.upgrade-guide.md)

• BREAKING: ESM-only — TresJS v5 is ESM-only; UMD build and CommonJS require() are no longer supported [source](./references/docs/content/1.getting-started/4.upgrade-guide.md)

• BREAKING: TresCanvas Props — WebGL context props like alpha, antialias, stencil, and depth are now readonly and non-reactive in v5 [source](./references/docs/content/1.getting-started/4.upgrade-guide.md)

• BREAKING: useTresContext().camera — returns a state object in v5; use useTres().camera for the active camera instance [source](./references/docs/content/1.getting-started/4.upgrade-guide.md)

• BREAKING: Renderer Context — renderer is now readonly in useTresContext(); performance state was removed from context in v5 [source](./references/docs/content/1.getting-started/4.upgrade-guide.md)

• BREAKING: Event Bubbling — only the first intersected element triggers pointer events since v5 to align with standard behavior [source](./references/docs/content/1.getting-started/4.upgrade-guide.md)

• NEW: Context Component — exported in v5.5.0 (as TresCanvasContext) for advanced scene and state management [source](./references/releases/@tresjs/[email protected])

• NEW: Kebab-case Support — support for components written in kebab-case (e.g., <tres-mesh>) added in v5.1.0 [source](./references/releases/@tresjs/[email protected])

• NEW: primitive Prefix — added prefix option for primitives in v5.3.0 to avoid name collisions [source](./references/releases/@tresjs/[email protected])

• NEW: TresCanvasProps / TresCanvasEmits — explicitly exported types added in v5.2.0 for better TypeScript integration [source](./references/releases/@tresjs/[email protected])

• REMOVED: Legacy Composables — useRenderLoop, useCamera, useTresReady, useSeek, useRaycaster, and useLogger removed in v5 [source](./references/docs/content/1.getting-started/4.upgrade-guide.md)

• NEW: useForwardPropsEmits — integrated into TresCanvas in v5.3.0 for streamlined event and prop handling [source](./references/releases/@tresjs/[email protected])

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.

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](./references/docs/content/2.essentials/2.concepts/2.reactivity.md)

<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](./references/docs/content/3.api/5.advanced/performance.md)

• 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](./references/docs/content/3.api/5.advanced/performance.md)

• 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](./references/docs/content/3.api/5.advanced/performance.md)

• 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](./references/docs/content/3.api/2.composables/3.use-loop.md)

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](./references/docs/content/2.essentials/2.concepts/3.constructor-arguments.md)

• 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](./references/docs/content/3.api/2.composables/3.use-loop.md)

• 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](./references/docs/content/3.api/2.composables/3.use-loop.md)

• 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](./references/docs/content/3.api/5.advanced/performance.md)

• 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](./references/docs/content/3.api/2.composables/4.use-graph.md)