harlan-zw/tresjs-core-skilld

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

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

• 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.

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

<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