Components
Since Trois is a Vue 3 custom renderer, it can support any Three.js class.
Out of the box, it supports the classes listed in the autoGeneratedComponents
array in the source code. To add more classes, see Extend.
Properties
Trois can also support any Three.js property on any component. Vue props and directives (ref
, v-for
, v-if
, key
, etc) are not passed onto Trois-created instances.
Trois will do its best to use the correct type for the prop:
:scale="[2, 2, 2]" // Vector3s that receive arrays will spread array values into <vector3>.set
:scale="2" // Vector3s that receive numbers will be set via <vector3>.setScalar
:color="'blue'" // colors will be set using `<color>.set`
:load="['texture.jpg']" // functions will be called with the prop array spread into the function.
// Function outputs will be saved as `$attached.<functionName>` on the parent.
// Example:
// <meshBasicMaterial :map="'$attached.load'">
// <textureLoader :load="['texture.jpg']/>
// </meshBasicMaterial>
You can also set nested props by replacing dots with dashes:
:position-x="2" // equivalent to <item>.position.x = 2
:scale-y="3" // equivalent to <item>.scale.y = 3
Trois reserves the following props for internal use:
args
- used when creating an instance of a Three.js class.args
must be an array; its values will be spread into the instantiation method.
<!-- a sphere with radius=15, widthSegments=32, heightSegments=16 -->
<sphereGeometry :args="[15, 32, 16]">
One-time use args
Each Trois component is only created once in its lifecycle, so args
will only apply on instantiation:
<template>
<TroisCanvas>
<mesh>
<sphereGeometry :args="[radius]"/>
</mesh>
</TroisCanvas>
</template>
<script>
export default {
data(){
return { radius: 5 }
},
mounted(){
// This will have no effect on the sphere - since the radius is 5 at instantiation,
// the value 20 will not be used again.
setTimeout(() => this.radius = 20, 1000)
// If you need a new sphere with the new radius, add the prop `:key="radius"`
// to the mesh to reinstantiate the entire component on radius change:
//
// <mesh :key="radius">
// <sphereGeometry :args="[radius]"/>
// </mesh>
//
// or edit the scale of the mesh for the same effect:
//
// <mesh :scale="radius === 5 ? 1 : 4">
}
}
</script>
Events
All Trois components emit an onAdded
and onReady
event:
<mesh @added="yourAddedMethod" @ready="yourReadyMethod"/>
onAdded
fires when the instance has been added to its scene or parent. onReady
fires when the instance has first been created - it may or may not exist in the scene yet. Both accept an object with the following properties:
{
element, // the trois component
instance, // the instantiated object
trois, // trois global config
scene, // the current scene
camera, // the current camera
renderer // the current renderer
}
Additional events available to Trois components are:
@ Naming
Note you can replace on
with @
in the event names below. onClick
is the same as @click
, etc.
Name | Parameters |
---|---|
onClick | { intersection: THREE.Intersection } |
onPointerUp | { intersection: THREE.Intersection } |
onPointerDown | { intersection: THREE.Intersection } |
onPointerOver | { intersection: THREE.Intersection } |
onPointerOut | { intersection: THREE.Intersection } |
onPointerEnter | { intersection: THREE.Intersection } |
onPointerLeave | { intersection: THREE.Intersection } |
onPointerMove | { intersection: THREE.Intersection } |
attach
You can pass instantiated items using the attach
prop and $attached.<propName>
strings. See Core Concepts for more details.