---
name: tresjs-core-skilld
description: Declarative Three.js using Vue components. ALWAYS use when writing code that imports "@tresjs/core" or touches TresCanvas, Tres components, useLoop, useLoader, useTres, useTresContext, TresPortal, pointer events, render modes, or TresJS debugging, upgrades, and performance work.
---

# @tresjs/core 5.9.0

Vue custom renderer for Three.js: any `THREE` class becomes a component by prefixing `Tres` (`<TresMesh>`, `<TresBoxGeometry>`). Prepared source: `package.json`, `dist/tres.d.ts` (public types), `dist/tres.js`.

npm dist-tags at generation time: `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.

## Environment limits

- ESM-only since v5. No UMD, no `require()`. `import { TresCanvas } from '@tresjs/core'`.
- Peer deps: `vue >=3.4`, `three >=0.133` (package.json:44-46). Built against three `^0.184`.
- Time source: three `Timer` on r179+, falls back to `Clock` on older three (dist/tres.d.ts:962-970).
- WebGPU is experimental; requires the `renderer` prop with a `three/webgpu` `Renderer` (see [references/webgpu.md](./references/webgpu.md)).

## Setup

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

Vite: spread `templateCompilerOptions` into the Vue plugin, or Tres components warn as unknown custom elements (README.md:36-50):

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

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

A separate subpath export `@tresjs/core/template-compiler-options` exists for hosts that only need compiler options (package.json:21-25). For Nuxt use `@tresjs/nuxt` instead of manual setup.

## Core model

- Component catalogue is autogenerated from the `THREE` namespace: `Tres` + capitalized class name, also available kebab-case (`<tres-mesh>`, supported since v5.1.0) (dist/tres.d.ts:497-509).
- `args` passes constructor arguments: `<TresBoxGeometry :args="[1, 2, 3]" />`. Changing reactive `args` recreates the whole instance; use props for everything settable after construction (dist/tres.d.ts:405-411).
- Props map to instance properties. Math types accept shorthand: `:position="[1, 2, 3]"`, `:rotation="[0, Math.PI, 0]"`, `color="#00ff00"` (dist/tres.d.ts:457-485).
- Child material/geometry auto-attach via `attach`: `<TresMesh><TresBoxGeometry /><TresMeshNormalMaterial /></TresMesh>` works without explicit `attach`.
- `extend({ MyObject })` before using non-THREE classes as `<TresMyObject>` (dist/tres.d.ts:872-874).
- `<primitive :object="existingThreeObject" />` mounts an object you created in JS. It does not own disposal; dispose manually (see [references/performance.md](./references/performance.md)).

Minimal scene:

```vue
<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>
```

Without an explicit camera, a default `PerspectiveCamera` is created (dist/tres.d.ts:682-685).

## API changes to know

v5 breaking (migrate with [references/migration-v4-v5.md](./references/migration-v4-v5.md)):

- `useLoader` returns reactive state `{ state, isLoading, error, progress, load }`, no longer a Promise (dist/tres.d.ts:40-65).
- Pointer events use native DOM names: `@pointerdown`, not `@pointer-down`. Only the first intersected object fires.
- `useTexture` moved to `@tresjs/cientos`. `useRenderLoop`, `useCamera`, `useSeek`, `useRaycaster`, `useTresReady`, `useTresEventManager`, `useLogger` were removed. Replacements: `useLoop`, `useTres`, `useGraph`, `@ready` event.
- `useTresContext().camera` is a camera manager; use `useTres().camera` for the active camera instance (dist/tres.d.ts:574-606).
- WebGL context props (`alpha`, `antialias`, `depth`, `stencil`, `powerPreference`, `logarithmicDepthBuffer`, `preserveDrawingBuffer`, `failIfMajorPerformanceCaveat`) are readonly; set once at mount (dist/tres.d.ts:141-206).

Recent additions:

- 5.9.0: `TresPortal` component reparents children into any `Object3D`/`Scene` target (dist/tres.d.ts:853-858), https://docs.tresjs.org/api/components/tres-portal
- 5.9.0: `isWebGPURenderer` guard and reactive `context.isWebGPU` flag (dist/tres.d.ts:350-367, 1204-1222)
- 5.9.0: `shadowMapType` defaults to `PCFShadowMap` on WebGL, `PCFSoftShadowMap` on WebGPU (dist/tres.d.ts:250-255)
- 5.8.0: `fpsLimit` prop caps render FPS (dist/tres.d.ts:692-696)
- 5.7.0: three `<r179` compatibility via `Timer` to `Clock` fallback (dist/tres.d.ts:962-970)
- 5.5.0: `TresCanvasContext` (the `Context` component) for bringing your own `<canvas>` (dist/tres.d.ts:680-708)
- 5.3.0: `customRendererOptions.primitivePrefix` renames `<primitive>` (dist/tres.d.ts:622-625)
- 5.2.0: `TresCanvasProps` / `TresCanvasEmits` types exported (dist/tres.d.ts:776-781)
- Full history: https://github.com/Tresjs/tres/blob/main/packages/core/CHANGELOG.md

## Common tasks

Animate with frame-rate independence (`delta` in seconds):

```vue
<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` only works inside child components of `TresCanvas`; on the canvas itself use `@before-loop` / `@loop` events (https://docs.tresjs.org/api/composables/use-loop).

Load a model:

```ts
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" />
```

Click a mesh:

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

Event payloads carry `point`, `object`, `distance`, `face`, `uv`, `xy`. `@pointermissed` on `TresCanvas` catches clicks on empty space. Details: [references/pointer-events.md](./references/pointer-events.md).

## Best practices

- Use `shallowRef` for template refs to Three.js instances and for any object passed to `<primitive>`; deep `ref` proxies cost real frame time. https://docs.tresjs.org/api/advanced/performance
- Prefer `renderMode="on-demand"` plus `invalidate()` for non-game scenes; `renderMode="manual"` plus `advance()` for full control (dist/tres.d.ts:134-139).
- In `on-demand` mode, call `invalidate()` after mutating objects through refs, since those mutations bypass Vue reactivity.
- Take over rendering with `useLoop().render(fn)` only for post-processing or multi-pass; the fn must call `notifySuccess()` or render modes break (https://docs.tresjs.org/api/composables/use-loop).
- Register ordered updates via the `priority` argument of `onBeforeRender`/`onRender` (default 0, higher runs later).
- `useGraph(object)` gives named `nodes`, `materials`, `meshes` maps for loaded GLTF scenes instead of manual traversal (dist/tres.d.ts:565).
- Call `dispose()` (exported from `@tresjs/core`) on programmatically created objects used via `<primitive>`; template-created objects are disposed automatically.
- Keep `args` static unless you intend instance recreation; animate via props or refs instead.
- Debug with `v-log` / `v-log:material`, `v-light-helper`, `v-distance-to` directives (dist/tres.d.ts:934-952), https://docs.tresjs.org/api/utils/directives

## References

- [references/components.md](./references/components.md): TresCanvas props and events, TresCanvasContext, TresPortal, UseLoader component
- [references/composables.md](./references/composables.md): useTres vs useTresContext, useLoop, useLoader, useGraph, manager composables
- [references/performance.md](./references/performance.md): render modes, reactivity, disposal, dpr, fpsLimit
- [references/pointer-events.md](./references/pointer-events.md): event names, hit rules, payloads, propagation
- [references/webgpu.md](./references/webgpu.md): custom renderer factory, isWebGPU, capability branching
- [references/migration-v4-v5.md](./references/migration-v4-v5.md): v4 to v5 migration detail

Official docs: https://docs.tresjs.org