Load Models

All models used in this guide are from Alvaro Saburido.

3D models are available in hundreds of file formats, each with different purposes, assorted features, and varying complexity.

For this guide we are going to focus on loading gLTF (GL Transmission Format) models, which are the most common format for 3D models on the web.

There are several ways to load models on TresJS:

WARNING

Please note that in the examples below use top level await. Make sure to wrap such code with a Vue's Suspense component.

Using useLoader

The useLoader composable allows you to pass any type of three.js loader and a URL to load the resource from. It returns a Promise with the loaded resource.

For a detailed explanation of how to use useLoader, check out the useLoader documentation.

import { useLoader } from '@tresjs/core'
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader'

const { scene } = await useLoader(GLTFLoader, '/models/AkuAku.gltf')

Then you can pass the model scene to a TresJS primitive component to render it:

<primitive :object="scene" />

The <primitive /> component is not a standalone component in the Tres source code. Instead, it's a part of the Tres core functionality. When you use <primitive>, it is translated to a createElement call, which creates the appropriate three.js object based on the provided "object" prop.

Notice in the example above that we are using the Suspense component to wrap the TresCanvas component. This is because useLoader returns a Promise and we need to wait for it to resolve before rendering the scene.

Using useGLTF

A more convenient way of loading models is using the useGLTF composable available from the @tresjs/cientos package.

import { useGLTF } from '@tresjs/cientos'

const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf')

An advantage of using useGLTFis that you can pass a draco prop to enable Draco compression for the model. This will reduce the size of the model and improve performance.

import { useGLTF } from '@tresjs/cientos'

const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf', { draco: true })

Alternatively you can easily select objects inside the model using the nodes property.

App.vue

<script setup lang="ts">
import Model from './Model.vue'
</script>

<template>
  <TresCanvas
    clear-color="#82DBC5"
    shadows
    alpha
  >
    <TresPerspectiveCamera :position="[11, 11, 11]" />
    <OrbitControls />
    <Suspense>
      <Model />
    </Suspense>
  </TresCanvas>
</template>

Model.vue

<script setup lang="ts">
import { useGLTF } from '@tresjs/cientos'

const { nodes } = await useGLTF('/models/AkuAku.gltf', { draco: true })
</script>

<template>
  <primitive :object="nodes.AkuAku" />
</template>

Using GLTFModel

The GLTFModel component is a wrapper around the useGLTF composable, which is available from the @tresjs/cientos package.

<script setup lang="ts">
import { OrbitControls, GLTFModel } from '@tresjs/cientos'
</script>
<template>
  <TresCanvas clear-color="#82DBC5" shadows alpha>
    <TresPerspectiveCamera :position="[11, 11, 11]" />
    <OrbitControls />
    <Suspense>
      <GLTFModel path="/models/AkuAku.gltf" draco />
    </Suspense>
    <TresDirectionalLight :position="[-4, 8, 4]" :intensity="1.5" cast-shadow />
  </TresCanvas>
</template>

This particular approach is more straightforward but gives you less control over the model.

useFBX

The useFBX composable is available from the @tresjs/cientos package.

import { useFBX } from '@tresjs/cientos'

const model = await useFBX('/models/AkuAku.fbx')

Then is as straightforward as adding the scene to your scene:

<primitive :object="model" />

FBXModel

The FBXModel component is a wrapper around the useFBX composable, which is available from the @tresjs/cientos package. It's similar in usage to GLTFModel:

<script setup lang="ts">
import { OrbitControls, FBXModel } from '@tresjs/cientos'
</script>
<template>
  <TresCanvas clear-color="#82DBC5" shadows alpha>
    <TresPerspectiveCamera :position="[11, 11, 11]" />
    <OrbitControls />
      <Suspense>
        <FBXModel path="/models/AkuAku.fbx" />
      </Suspense>
      <TresDirectionalLight :position="[-4, 8, 4]" :intensity="1.5" cast-shadow />
  </TresCanvas>
</template>