Getting Started

Your First Scene

Structuring Your App

As a first step we’re creating a new Svelte file called App.svelte where we are importing the <Canvas> component.

<script>
  import { Canvas } from '@threlte/core'
  import Scene from './Scene.svelte'
</script>

<Canvas>
  <Scene />
</Canvas>

The <Canvas> component is the root component of your Threlte application. It creates a renderer and sets up some sensible defaults for you like antialiasing and color management. It also creates a default camera and provides the context in which your Threlte application will run. For improving access to this runtime context, it’s best practice to create a seperate component called Scene.svelte and including it in our App.svelte file.

Creating Objects

At this point we’re looking at a blank screen. Let’s add a simple cube to it.

In Scene.svelte, we’re importing the <T> component which is the main building block of your Threlte application. It’s a generic component that we use to render any Three.js object. In this case we’re creating a THREE.Mesh which is made up from a THREE.BoxGeometry and a THREE.MeshBasicMaterial.

We should now be looking at a white cube on a transparent background.

<script>
  import { T } from '@threlte/core'
</script>

<T.Mesh>
  <T.BoxGeometry />
  <T.MeshBasicMaterial />
</T.Mesh>

<script>
  import { T } from '@threlte/core'
</script>

<T.Mesh>
  <T.BoxGeometry attach="geometry" />
  <T.MeshBasicMaterial attach="material" />
</T.Mesh>

// creating the objects
const geometry = new THREE.BoxGeometry()
const material = new THREE.MeshBasicMaterial()
const mesh = new THREE.Mesh()

// "attaching" the objects
mesh.geometry = geometry
mesh.material = material

Modifying Objects

That cube is still a bit boring. Let’s add some color to it, and make it a bit bigger! We also want to move it up a little to highlight it. We can do this by passing props to the <T> component.

<script>
import { T } from '@threlte/core'
</script>

<T.Mesh position.y={1}>
<T.BoxGeometry args={[1, 2, 1]} />
<T.MeshBasicMaterial color="hotpink" />
</T.Mesh>

Threlte automatically generates props for <T> based on the underlying Three.js object. This means you can easily guess most <T> props based on the Three.js docs for the class you are using.

const mesh = new THREE.Mesh()
const geometry = new THREE.BoxGeometry(1, 2, 1)
const material = new THREE.MeshBasicMaterial()
mesh.position.y = 1
material.color.set('hotpink')

The special args prop we use in <T.BoxGeometry> corresponds to the object’s constructor arguments. Props interpreted from the underlying Three.js object are called auto props, like color in our <T.MeshBasicMaterial>. Leveraging Threlte’s Pierced Props you can directly assigned to attributes of props like position.y in our <T.Mesh>.

Pointing the Camera

We’re still staring at the side of a cube, let’s add a camera and offset it from the center:

<script>
  import { T } from '@threlte/core'
</script>

<T.PerspectiveCamera
  makeDefault
  position={[10, 10, 10]}
  oncreate={({ ref }) => {
    ref.lookAt(0, 1, 0)
  }}
/>

<T.Mesh position.y={1}>
  <T.BoxGeometry args={[1, 2, 1]} />
  <T.MeshBasicMaterial color="hotpink" />
</T.Mesh>

We’re again using the <T> component to create a THREE.PerspectiveCamera. We’re also passing a makeDefault prop which will make this camera the default camera of our application. The renderer now uses this camera to render our scene.

Enabling Interactivity

Let’s say we want to scale our cube as soon as we hover over it. We first have to import the plugin interactivity from @threlte/extras and invoke it in our Scene.svelte file; We can now add interaction event listeners to our <T> components. We will add pointerenter and pointerleave event listeners to our cube. In the event handlers we’ll update the value of a Svelte spring store and apply the stores value to the property scale of the component <T.Mesh>.

<script>
  import { T } from '@threlte/core'
  import { interactivity } from '@threlte/extras'
  import { spring } from 'svelte/motion'

  interactivity()
  const scale = spring(1)
</script>

<T.PerspectiveCamera
  makeDefault
  position={[10, 10, 10]}
  oncreate={({ ref }) => {
    ref.lookAt(0, 1, 0)
  }}
/>

<T.Mesh
  position.y={1}
  scale={$scale}
  onpointerenter={() => scale.set(1.5)}
  onpointerleave={() => scale.set(1)}
>
  <T.BoxGeometry args={[1, 2, 1]} />
  <T.MeshBasicMaterial color="hotpink" />
</T.Mesh>

Adding Animation

Let’s add some motion to our cube. We will use Threlte’s useTask hook to tap into Threlte’s unified frame loop and run a function on every frame. We again use a Pierced Prop to let the cube rotate around its y-axis.

<script>
  import { T, useTask } from '@threlte/core'
  import { interactivity } from '@threlte/extras'
  import { spring } from 'svelte/motion'

  interactivity()
  const scale = spring(1)

  let rotation = 0
  useTask((delta) => {
    rotation += delta
  })
</script>

<T.PerspectiveCamera
  makeDefault
  position={[10, 10, 10]}
  oncreate={({ ref }) => {
    ref.lookAt(0, 1, 0)
  }}
/>

<T.Mesh
  rotation.y={rotation}
  position.y={1}
  scale={$scale}
  onpointerenter={() => scale.set(1.5)}
  onpointerleave={() => scale.set(1)}
>
  <T.BoxGeometry args={[1, 2, 1]} />
  <T.MeshBasicMaterial color="hotpink" />
</T.Mesh>

useTask registers a callback that will be invoked on every frame. The callback receives the time delta since the last frame as an argument. We use the delta to update the rotation independent of the frame rate – the cube will rotate at the same speed regardless of the frame rate.

Adjusting the Lighting

We’re almost done. Let’s add some shading to our cube and a light source. We’ll use a THREE.MeshStandardMaterial on our cube and a THREE.DirectionalLight to illuminate our scene.

<script>
  import { T, useTask } from '@threlte/core'
  import { interactivity } from '@threlte/extras'
  import { spring } from 'svelte/motion'

  interactivity()
  const scale = spring(1)
  let rotation = 0
  useTask((delta) => {
    rotation += delta
  })
</script>

<T.PerspectiveCamera
  makeDefault
  position={[10, 10, 10]}
  oncreate={({ ref }) => {
    ref.lookAt(0, 1, 0)
  }}
/>

<T.DirectionalLight position={[0, 10, 10]} />

<T.Mesh
  rotation.y={rotation}
  position.y={1}
  scale={$scale}
  onpointerenter={() => scale.set(1.5)}
  onpointerleave={() => scale.set(1)}
>
  <T.BoxGeometry args={[1, 2, 1]} />
  <T.MeshStandardMaterial color="hotpink" />
</T.Mesh>

Casting Shadows

We would like our cube to cast a shadow. To do so, we need a floor for it to cast a shadow on, so we add a new <T.Mesh> but this time with <T.CircleGeometry>. To enable shadows, we need to set castShadow on both the light and our cube, and set receiveShadow on our new floor:

<script>
  import { T, useTask } from '@threlte/core'
  import { interactivity } from '@threlte/extras'
  import { spring } from 'svelte/motion'

  interactivity()
  const scale = spring(1)
  let rotation = 0
  useTask((delta) => {
    rotation += delta
  })
</script>

<T.PerspectiveCamera
  makeDefault
  position={[10, 10, 10]}
  oncreate={({ ref }) => {
    ref.lookAt(0, 1, 0)
  }}
/>

<T.DirectionalLight
  position={[0, 10, 10]}
  castShadow
/>

<T.Mesh
  rotation.y={rotation}
  position.y={1}
  scale={$scale}
  onpointerenter={() => scale.set(1.5)}
  onpointerleave={() => scale.set(1)}
  castShadow
>
  <T.BoxGeometry args={[1, 2, 1]} />
  <T.MeshStandardMaterial color="hotpink" />
</T.Mesh>

<T.Mesh
  rotation.x={-Math.PI / 2}
  receiveShadow
>
  <T.CircleGeometry args={[4, 40]} />
  <T.MeshStandardMaterial color="white" />
</T.Mesh>

Conclusion

Congratulations, you’ve just created your first Three.js scene with Threlte! It includes important Three.js and Threlte concepts and should give you a good starting point for your first Threlte project.