Upgrade Guide

From v4 to v5

Cientos doesn't have any breaking changes from v4 to v5 but please check the Upgrade Guide of the core.

Migration Guide from v3

Updated defineExport properties

Since the beginning we exported our components' underlying Three.js instances using the name value. This created a very ambiguos situation with some components. When we access them using a ref in <template>, we ended up with something like:

<script>
  import { shallowRef, watch } from 'vue'
  import { TresCanvas } from '@tresjs/core'
  import { Stars } from '@tresjs/cientos'

  const starsRef = shallowRef()

  watch(starsRef, () => {
    // to access the instance we have a nested `value.value`
    console.log(starsRef.value.value)
    // Wrong in v4 ❌
  })
</script>

<template>
  <TresCanvas>
    ...
    <Stars ref="starsRef" />
    ...
  </TresCanvas>
</template>

This behavior caused confusion and resulted in a poor developer experience. To address it properly, we needed to introduce a breaking change, and we felt this was the right moment to do so.

The new implementation remains very similar conceptually. However, instead of having two ambiguous value references, we’ve standardized all components around instance. To access the component, you should now use:

// Correct in v4 ✅
console.log(starsRef.value.instance)

Remove TweakPane from deps

We removed the built-in useTweakPane integration because it was adding overhead and friction:

• Incompatible with Tweakpane v4
• Large bundle impact
• Repetitive boilerplate and not very intuitive

If you still want to use Tweakpane with Tres, follow the cookbook recipe: https://docs.tresjs.org/cookbook/tweakpane.html

Move directives to core

Community adoption of directives has been solid, so they now live in the core package. Import them from @tresjs/core:

// Correct ✅
import { vLog } from '@tresjs/core'

Instead of:

// Wrong ❌
import { vLog } from '@tresjs/cientos'

Changes in KeyboardControls

KeyboardControls was redesigned to provide floating controls similar to Unreal Engine, which better matches the component’s intent. We also bundled PointerLockControls inside KeyboardControls, so you don’t need to wire it manually anymore.

Learn more: https://cientos.tresjs.org/guide/controls/keyboard-controls