agentleFS
skilld-devskilld-dev/vue-ecosystem-skills/skills/tresjs-core-skilld/SKILL.md

tresjs-core-skilld

Skill184 starsChanged 37 days agoMITView on GitHub

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.

  • Installs packages

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use shallowRef for template refs to Three.js instances and for any object passed to <primitive>.

    line 147
  2. Very specific:

    Prefer renderMode="on-demand" plus invalidate() for non-game scenes.

    line 148
  3. Very specific:

    Call dispose() (exported from @tresjs/core) on programmatically created objects used via <primitive>.

    line 153
  4. Very specific:

    Keep args static unless you intend instance recreation.

    line 154

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

@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).

Setup

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):

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

Minimal scene:

<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):

  • 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):

<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:

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:

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

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: TresCanvas props and events, TresCanvasContext, TresPortal, UseLoader component
  • references/composables.md: useTres vs useTresContext, useLoop, useLoader, useGraph, manager composables
  • references/performance.md: render modes, reactivity, disposal, dpr, fpsLimit
  • references/pointer-events.md: event names, hit rules, payloads, propagation
  • references/webgpu.md: custom renderer factory, isWebGPU, capability branching
  • references/migration-v4-v5.md: v4 to v5 migration detail

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.