Instances #

The core idea of Tres is an autogenerated catalogue of all the ThreeJS elements. This catalogue is generated from the ThreeJS source code, so it's always up to date.

When using ThreeJS, you need to import the elements you want to use. For example, if you want to use a PerspectiveCamera, you need to import it from the three package:

import { PerspectiveCamera } from 'three'

const camera = new PerspectiveCamera(45, width / height, 1, 1000)

With Tres you don't need to import anything, that's because Tres automatically generate a Vue Component based of the Three Object you want to use in CamelCase with a Tres prefix. For example, if you want to use a PerspectiveCamera you would use <TresPerspectiveCamera /> component.

<template>
  <TresCanvas>
    <TresPerspectiveCamera />
    <!-- Your scene goes here -->
  </TresCanvas>
</template>

This means that you can use the same documentation as you would when using plain ThreeJS, but with the power of Vue.

Declaring objects #

If we follow this argument, you should be able to lay out an instance like this: ❌

<template>
  <TresCanvas>
    <TresPerspectiveCamera visible :position="new THREE.Vector3(1, 2, 3)" />
    <!-- Your scene goes here -->
  </TresCanvas>
</template>

But with Tres this is not needed, you can define properties declaratively like this: ✅

<template>
  <TresCanvas>
    <TresPerspectiveCamera visible :position="[1, 2, 3]" />
    <!-- Your scene goes here -->
  </TresCanvas>
</template>

Arguments #

Some ThreeJS objects have arguments, for example, the PerspectiveCamera constructor has the following arguments:

• fov - Camera frustum vertical field of view.
• aspect - Camera frustum aspect ratio.
• near - Camera frustum near plane.
• far - Camera frustum far plane.

To pass these arguments to the TresPerspectiveCamera component, you can use the args prop:

<template>
  <TresCanvas>
    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
    <!-- Your scene goes here -->
  </TresCanvas>
</template>

This is the same as doing this:

const camera = new PerspectiveCamera(45, 1, 0.1, 1000)

Props #

You can also pass props to the component, for example, the TresAmbientLight has a intensity property, so you can pass it to the component like this:

<TresAmbientLight :intensity="0.5" />

Set #

All properties whose underlying object has a .set() method have a shortcut to recieve the value as an array. For example, the TresPerspectiveCamera has a position property, which is a Vector3 object, so you can pass it to the component like this:

<TresPerspectiveCamera :position="[1, 2, 3]" />

To specify transformation properties such as position, rotation, and scale, a shorthand is available that allows you to directly indicate the axis you wish to set within the props. A similar shorthand is also available for color property.

<TresMesh :position-x="1" :scale-y="2" :rotation-x="Math.PI * 2">
  <TresMeshBasicMaterial :color-r="0.7" :color-b="0.3" />
</TresMesh>

<TresMesh :rotation-x="1" :rotation-y="2" :rotation-z="Math.PI * 2" />

<TresMesh :rotation-z="Math.PI * 2" :rotation-x="1" :rotation-y="2" />

<!-- Note that the order of the rotation properties matters, and swapping the order can result in different outcomes. -->

Scalar #

Another shortcut you can use is pass a scalar value to a property that expects a Vector3 object, using the same value for the rest of the Vector:

<TresPerspectiveCamera :position="5" /> ✅

<TresPerspectiveCamera :position="[5, 5, 5]" /> ✅

Colors #

You can pass colors to the components using the color prop, which accepts a string with the color name or a hex value:

<TresAmbientLight color="teal" /> ✅

<TresAmbientLight color="#008080" /> ✅

Methods #

Some underlying properties are actually methods, the TresPerspectiveCamera has a lookAt method inherit from Object3d, so you can pass it the coords to the component like this:

<TresPerspectiveCamera :look-at="[1, 2, 3]" />