# Getting Started

Cientos (Spanish word for "hundreds", pronounced `/θjentos/`) is a collection of useful ready-to-go helpers and components that are not part of the **core** package. The name uses the word in Spanish to multiply by 100, to refer to the potential reach of the package to hold amazing abstractions.

::prose-note
The cientos package uses three-stdlib module under the hood instead of the `three/examples/jsm` module. This means that you don't need to extend the catalogue of components using the extend method, cientos does that for you.
::

It just works. 💯

## Next Steps

Continue your journey:

- [Installation guide](https://cientos.tresjs.org/getting-started/installation)
- [Usage](https://cientos.tresjs.org/getting-started/usage)
- [Upgrade guide](https://cientos.tresjs.org/getting-started/upgrade-guide)


# Installation Guide

## Manual installation

If you prefer to set up Cientos manually or add it to an existing [Tres.js](https://tresjs.org/){rel=""nofollow""} project

::code-group
```bash [pnpm]
pnpm add @tresjs/cientos
```

```bash [npm]
npm install @tresjs/cientos
```

```bash [yarn]
yarn add @tresjs/cientos
```
::

## Via `create-tres` wizard

When using `create-tres` to create a new project, the cli will prompt you to install cientos.

::code-group
```bash [npm]
npx create-tres my-tres-project
```

```bash [yarn]
yarn create tres my-tres-project
```

```bash [pnpm]
pnpm create tres my-tres-project
```
::

::read-more
---
to: https://docs.tresjs.org/getting-started/installation#quick-start-recommended
---
For more information about the `create-tres` wizard please refer to this link.
::

## Nuxt :u-icon{name="i-simple-icons-nuxt"}

If you're using nuxt, installing our nuxt module will detect automatically cientos.

::read-more
---
to: https://docs.tresjs.org/getting-started/installation#nuxt-project
---
For more information about the Nuxt module please refer to this link.
::


# Usage

## Basic Usage

All instances of cientos provide one (or many) examples of how to use it, similar to this one:

```js
import { OrbitControls } from '@tresjs/cientos'
```

Now you can use the `OrbitControls` component in your scene.

```vue
<template>
  <TresCanvas shadows alpha>
    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
    <OrbitControls />
  </TresCanvas>
</template>
```

::prose-note
Note that you don’t need to include the **Tres** prefix (for example, `<TresOrbitControl />`) to use the component. All cientos components have the same name as their three-stdlib counterpart.
::

### Props

All the props are listed with their respective instance and in case it is not specified all the props are **reactive**, for example:

```vue {3,15-16}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { MeshWobbleMaterial } from '@tresjs/cientos'

const speed = ref(0.1)
const factor = ref(0.6)
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" :look-at="[0, 0, 0]" />
    <TresMesh>
      <TresTorusGeometry />
      <MeshWobbleMaterial
        :speed="speed"
        :factor="factor"
      />
    </TresMesh>
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
  </TresCanvas>
</template>
```

::prose-note
All the props and properties are **reactive** unless the docs of the instance says the contrary.
::

### Events

Some instances fire events which you can listen to as you normally would do using Vue [emits](https://vuejs.org/guide/components/events.html#emitting-and-listening-to-events){rel="&#x22;nofollow&#x22;"}, for example:

```vue {3,5,11}
<script setup>
import { TresCanvas } from '@tresjs/core'
import { GlobalAudio } from '@tresjs/cientos'

const onPlay = (e) => console.log(e) // will trigger when the event change state
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 0, 7.5]" />
    <GlobalAudio :src="exampleAudio" @is-playing="onPlay" />
  </TresCanvas>
</template>
```

### Exposed properties

All instances expose a `instance` property by default which contains the base of its abstractions. For example:

```vue {2}
<script setup>
const edgesRef = shallowRef(null)

console.log(edgesRef.value.instance) // Inheritance of [LineSegments](https://threejs.org/docs/#api/en/objects/LineSegments)

<template>
    <Edges ref="edgesRef" />
</template>
```

Some instances expose more objects. For example Positional Audio:

```vue {2}
<script setup>
import { Box, PositionalAudio } from '@tresjs/cientos'
import { onUnmounted, shallowRef } from 'vue'

const positionalAudioRef = shallowRef(null)

onUnmounted(() => {
  positionalAudioRef?.value?.dispose()
})

const { helper, innerAngle, outerAngle, outerGain } = useControls({
  helper: true,
  innerAngle: {
    label: 'innerAngle',
    value: 195,
    min: 0,
    max: 360,
    step: 1,
  },
  outerAngle: {
    label: 'outerAngle',
    value: 260,
    min: 0,
    max: 360,
    step: 1,
  },
  outerGain: {
    label: 'outerGain',
    value: 0.3,
    min: 0,
    max: 1,
    step: 0.01,
  },
})
</script>

<template>
  <TresCanvas>
    <Box :args="[1, 1, 1]">
      <TresMeshNormalMaterial />
      <Suspense>
        <PositionalAudio
          ref="positionalAudioRef"
          url="your-sound.mp3"
          :inner-angle="innerAngle.value"
          :outer-angle="outerAngle.value"
          :outer-gain="outerGain.value"
          :helper="helper.value"
        />
      </Suspense>
    </Box>
  </TresCanvas>
</template>
```


# Loading Models

Cientos gives you three ways to get a `.glb`/`.gltf` model on screen. They are not alternatives to
each other so much as three points on the same line: the further down this page you go, the more
control you get over the model's tree.

| Approach                                                                             | Control                          | Typed    | Best for                                           |
| :----------------------------------------------------------------------------------- | :------------------------------- | :------- | :------------------------------------------------- |
| [`<GLTFModel />`](https://cientos.tresjs.org/api/loaders/gltf-model)                 | Whole scene, as-is               | No       | Dropping a model in as-is                          |
| [`useGLTF`](https://cientos.tresjs.org/api/loaders/use-gltf)                         | Pick nodes and materials by hand | Optional | Reusing parts of a model                           |
| [`tres gltf` codegen](https://cientos.tresjs.org/#generate-a-component-with-the-cli) | Every node is an element         | Yes      | Production scenes, interaction, per-node overrides |

## Drop the model in

The fastest path. `GLTFModel` loads the file and renders its scene graph untouched:

```vue [TheModel.vue]
<script setup lang="ts">
import { GLTFModel } from '@tresjs/cientos'
</script>

<template>
  <GLTFModel path="/models/mug.glb" />
</template>
```

You get the whole model or nothing. There is no way to swap one mesh's material, attach a click
handler to a door, or hide a node, because none of them exist as elements in your template.

## Pick the parts you need

`useGLTF` hands you the parsed `nodes` and `materials`, so you compose the scene yourself:

```vue [TheModel.vue]
<script setup lang="ts">
import { useGLTF } from '@tresjs/cientos'

const { nodes, materials, isLoading } = useGLTF('/models/mug.glb')
</script>

<template>
  <TresMesh
    v-if="!isLoading"
    :geometry="nodes.Mesh.geometry"
    :material="materials.coat"
    @click="onClick"
  />
</template>
```

This is the right tool when you only want a couple of nodes out of a bigger file. For a whole
model it stops scaling: you are hand-writing an element per node, re-reading the tree in Blender
to find the names, and re-writing all of it when the artist re-exports.

::prose-note
`nodes` and `materials` are keyed by the names in the file, so their shape is only known at
runtime. Pass the shape as generics to get them typed, see [Typed nodes and materials](https://cientos.tresjs.org/#typed-nodes-and-materials) below.
::

## Generate a component with the CLI

`@tresjs/cli` writes that element-per-node component for you, typed, from the model itself:

```bash
npx @tresjs/cli gltf public/models/mug.glb
# ✔ src/models/Mug.gen.vue
#   1 slot: Mug
```

```vue [src/models/Mug.gen.vue]
<script setup lang="ts">
/*
Auto-generated by @tresjs/cli. Do not edit.
Command: tres gltf public/models/mug.glb
Override the named slots from the parent instead; regenerating keeps your overrides.
*/
import type { Group, Mesh, MeshStandardMaterial } from 'three'
import { useGLTF } from '@tresjs/cientos'

interface ModelNodes {
  Scene: Group
  Mug: Group
  Mesh: Mesh
  Mesh_1: Mesh
}

interface ModelMaterials {
  '4k-Metal-Worn': MeshStandardMaterial
  'coat': MeshStandardMaterial
}

defineSlots<{
  Mug?: (props: { node: Group }) => any
}>()

const { nodes, materials, isLoading } = useGLTF<ModelNodes, ModelMaterials>('/models/mug.glb', { draco: true })

defineExpose({ nodes, materials })
</script>

<template>
  <TresGroup :dispose="null">
    <template v-if="!isLoading">
      <slot name="Mug" :node="nodes.Mug">
        <TresGroup :position="[0, 1, 0]">
          <TresMesh :geometry="nodes.Mesh.geometry" :material="materials['4k-Metal-Worn']" />
          <TresMesh :geometry="nodes.Mesh_1.geometry" :material="materials.coat" />
        </TresGroup>
      </slot>
    </template>
  </TresGroup>
</template>
```

Import it like any other component:

```vue [App.vue]
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import Mug from '@/models/Mug.gen.vue'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 2, 5]" />
    <Mug />
    <TresAmbientLight :intensity="1" />
  </TresCanvas>
</template>
```

### Overriding a node

Every named node is a `<slot>` whose fallback is the generated markup, so you change one mesh
from the parent without touching the generated file:

```vue [App.vue]
<template>
  <Mug>
    <template #Mug="{ node }">
      <TresMesh :geometry="node.geometry" :material="hologram" @click="onClick" />
    </template>
  </Mug>
</template>
```

Regenerate after the artist re-exports and the override survives, because it never lived in the
generated file. If the node is renamed, the override becomes a **type error** instead of quietly
doing nothing at runtime.

::prose-warning
Treat `*.gen.vue` files as build output: edit the parent, not the generated file. The CLI refuses
to overwrite a file it did not generate, so a hand-edited one needs `--force` to regenerate.
::

::read-more{to="https://docs.tresjs.org/cli/gltf"}
Full `tres gltf` reference: slots, animations, shadows, Draco and every flag.
::

## Typed nodes and materials

`useGLTF` takes two generics that type `nodes` and `materials`. The CLI writes them for you, but
you can also declare them by hand:

```ts
import type { Mesh, MeshStandardMaterial } from 'three'
import { useGLTF } from '@tresjs/cientos'

interface ModelNodes { Body: Mesh }
interface ModelMaterials { Skin: MeshStandardMaterial }

const { nodes, materials } = useGLTF<ModelNodes, ModelMaterials>('/models/robot.glb')

nodes.value.Body.geometry // Mesh, not any
```

::prose-note
The names come from the file at runtime, so these interfaces are a claim about the model, not a
proof. That is exactly why generating them from the model is worth it.
::

## Animated models

Clips live on the loaded `state`, and [`useAnimations`](https://cientos.tresjs.org/api/miscellaneous/use-animations) turns
them into actions:

```vue [Knight.vue]
<script setup lang="ts">
import { useAnimations, useGLTF } from '@tresjs/cientos'
import { computed, ref, watch } from 'vue'

const { state, nodes, isLoading } = useGLTF('/models/knight.glb')

const modelRef = ref()
const animations = computed(() => state.value?.animations ?? [])
const { actions } = useAnimations(animations, modelRef)

watch(actions, current => current.Idle?.play())
</script>

<template>
  <TresGroup ref="modelRef">
    <primitive v-if="!isLoading" :object="nodes.Rig" />
  </TresGroup>
</template>
```

A generated component wires all of that up and exposes `actions` keyed by a union of the model's
clip names, so `actions.Idle` type-checks and `actions.Idl` does not:

```vue [App.vue]
<script setup lang="ts">
import { onMounted, ref } from 'vue'
import Knight from '@/models/Knight.gen.vue'

const knight = ref<InstanceType<typeof Knight>>()

onMounted(() => knight.value?.actions.Idle?.play())
</script>

<template>
  <Knight ref="knight" />
</template>
```

::prose-note
Keep the element carrying the animation `ref` mounted and gate its **children** on loading. A
`ref` on a `v-if`ed element is still `undefined` one flush after the clips land, and the mixer
would then be built with no root to bind against.
::

## Draco-compressed models

Pass `draco: true` and the loader pulls the decoder from Google's CDN, or point `decoderPath` at
a local copy:

```ts
const { state } = useGLTF('/models/mug.glb', { draco: true })
```

A Draco model renders nothing without it. The CLI detects compression while parsing and writes
`{ draco: true }` into the generated component for you.

## Where to find models

- [poly.pizza](https://poly.pizza/){rel="&#x22;nofollow&#x22;"} — free 3D models
- [Pmndrs Market](https://market.pmnd.rs/){rel="&#x22;nofollow&#x22;"} — free assets, curated
- [KayKit](https://kaylousberg.itch.io/){rel="&#x22;nofollow&#x22;"} — animated CC0 character packs


# Upgrade Guide

## From v4 to v5

Cientos doesn't have any breaking changes from v4 to v5 but please check the [Upgrade Guide](https://docs.tresjs.org/getting-started/upgrade-guide){rel="&#x22;nofollow&#x22;"} of the core.

## Migration Guide from v3

The following are the breaking changes introduced in v4. We recommend reading through all of them to ensure a smooth transition.

### Updated defineExport properties

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

```html
<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 have standardized all components around `instance`. To access the component, you should now use:

```text
// 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](https://tweakpane.github.io/docs/){rel="&#x22;nofollow&#x22;"}
- Large bundle impact
- Repetitive boilerplate and not very intuitive

If you still want to use Tweakpane with Tres, you can follow the cookbook recipe: <https://docs.tresjs.org/cookbook/tweakpane>{rel="&#x22;nofollow&#x22;"}

### Move directives to core

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

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

Instead of:

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

### Changes in KeyboardControls

`KeyboardControls` was redesigned to provide floating controls similar to the 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/api/controls/keyboard-controls){rel="&#x22;nofollow&#x22;"}


# Align

::scene-controls-wrapper
:abstractions-align
::

Calculates a bounding box around its children and aligns them as a group within their parent. The component measures its contents and realigns on every frame unless `cacheKey` is set.

## Usage

```vue {2,13,18}
<script setup lang="ts">
import { Align, OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas clear-color="#222">
    <TresPerspectiveCamera />
    <OrbitControls />

    <TresAxesHelper :scale="2" />

    <Align top right back>
      <TresMesh>
        <TresBoxGeometry />
        <TresMeshNormalMaterial />
      </TresMesh>
    </Align>
  </TresCanvas>
</template>

```

## Props

All props are optional.

| Prop       | Description                                                                                                                      | Default     |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `top`      | If `true`, aligns bounding box bottom to `0` on the y-axis                                                                       | `false`     |
| `bottom`   | If `true`, aligns bounding box top to `0` on the y-axis.                                                                         | `false`     |
| `left`     | If `true`, aligns bounding box right to `0` on the x-axis.                                                                       | `false`     |
| `right`    | If `true`, aligns bounding box left to `0` on the x-axis.                                                                        | `false`     |
| `front`    | If `true`, aligns bounding box back to `0` on the z-axis.                                                                        | `false`     |
| `back`     | If `true`, aligns bounding box front to `0` on the z-axis.                                                                       | `false`     |
| `disable`  | If `true`, disables alignment on all axes.                                                                                       | `false`     |
| `disableX` | If `true`, disables alignment on the x-axis.                                                                                     | `false`     |
| `disableY` | If `true`, disables alignment on the y-axis.                                                                                     | `false`     |
| `disableZ` | If `true`, disables alignment on the z-axis.                                                                                     | `false`     |
| `precise`  | See [Box3.setFromObject](https://threejs.org/docs/index.html?q=box3#api/en/math/Box3.setFromObject){rel="&#x22;nofollow&#x22;"}. | `true`      |
| `onAlign`  | Callback that fires when updating, after measurement.                                                                            |             |
| `cacheKey` | If set, component will only update when `cacheKey`'s value changes. If unset, component will update every frame.                 | `undefined` |

## AlignCallbackOptions

```ts
export interface AlignCallbackOptions {
  /** The next parent above <Align /> */
  parent: Object3D
  /** The outmost container group of the <Align/> component */
  container: Object3D
  width: number
  height: number
  depth: number
  boundingBox: Box3
  boundingSphere: Sphere
  center: Vector3
  verticalAlignment: number
  horizontalAlignment: number
  depthAlignment: number
}
```


# Billboard

::scene-controls-wrapper
:abstractions-billboard
::

Adds a `THREE.Group` that always faces the camera.

## Usage

```vue {2,10,14}
<script setup lang="ts">
import { Billboard, Box, OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas clear-color="#333333">
    <OrbitControls />
    <TresPerspectiveCamera :position="[0, 0, 10]" />
    <Billboard>
      <Box :scale="[0.5, 0.5, 0.001]">
        <TresMeshNormalMaterial />
      </Box>
    </Billboard>
  </TresCanvas>
</template>

```

## Props

| Prop         | Description                                                                      | Default |
| :----------- | :------------------------------------------------------------------------------- | ------- |
| `autoUpdate` | Whether the `<Billboard />` should face the camera automatically on every frame. | `true`  |
| `lockX`      | Whether to lock the x-axis.                                                      | `false` |
| `lockY`      | Whether to lock the y-axis.                                                      | `false` |
| `lockZ`      | Whether to lock the z-axis.                                                      | `false` |


# Camera Shake

::scene-controls-wrapper
:abstractions-camera-shake
::

`<CameraShake />` is a component that adds **natural**, *noise-driven motion* to the **active camera**.
It offers **per-axis control**, **adjustable intensity**, and *optional decay* — perfect for *handheld feel*, *footsteps*, *impacts*, or *engine rumble* — and is based on the [Drei `CameraShake` component](https://drei.docs.pmnd.rs/staging/camera-shake#camerashake){rel="&#x22;nofollow&#x22;"}.

## Usage

```vue {2,11,16}
<script setup lang="ts">
import { CameraShake, OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas clear-color="#222">
    <TresPerspectiveCamera :position="[0, 2, 6]" />
    <OrbitControls make-default />

    <CameraShake :intensity="1" :max-yaw="0.01" :max-pitch="0.01" :max-roll="0.01" />
      <TresAxesHelper :scale="2" />
      <TresMesh :position-y="0.5">
        <TresBoxGeometry :args="[1, 1, 1]" />
        <TresMeshNormalMaterial />
      </TresMesh>
  </TresCanvas>
</template>
```

::prose-note
`<CameraShake />` is fully compatible with **`<OrbitControls />`**.
To ensure it works *as expected*, make sure to add the **`make-default`** prop:

```vue
<OrbitControls make-default />
```
::

## Props

| Prop             | Description                                         | Default |
| ---------------- | --------------------------------------------------- | ------- |
| `intensity`      | The intensity of the shake (0–1).                   | `1`     |
| `decay`          | If `true`, intensity decays over time.              | `false` |
| `decayRate`      | How fast intensity changes when `decay` is enabled. | `0.65`  |
| `maxYaw`         | Maximum yaw angle in radians.                       | `0.01`  |
| `maxPitch`       | Maximum pitch angle in radians.                     | `0.01`  |
| `maxRoll`        | Maximum roll angle in radians.                      | `0.01`  |
| `yawFrequency`   | Frequency of yaw oscillation.                       | `0.1`   |
| `pitchFrequency` | Frequency of pitch oscillation.                     | `0.1`   |
| `rollFrequency`  | Frequency of roll oscillation.                      | `0.1`   |


# Decal

`<Decal>` projects a flat texture onto the surface of a parent mesh,
conforming to its geometry. Multiple decals can stack on the same mesh
with explicit z-layering, the JSON layout round-trips losslessly, and
the entry-by-entry shape stays human-readable.

- 🎨 Drop-in **editor UI** via `<DecalDebugUI>` — placement, rotate / scale / snap, tint, flip, layers, undo / redo, import / export.
- 🛠 **Programmatic API** via [`useDecalEditor()`](https://cientos.tresjs.org/#programmatic-api-usedecaleditor) for custom panels and automation.
- 🖼️ **Texture palette** — pass an array of `Texture` to `:map`.
- 🧩 **Custom material** — override the default via the slot.
- 💾 **Lossless JSON** — `v-model:data` round-trips to plain JSON.
- ⚡ **BVH-accelerated** — auto-detected via [`useBVH`](https://cientos.tresjs.org/api/debug-performance/use-bvh); 10–100× faster on dense meshes.
- 📚 **Per-mesh stacking** — `zIndex` with automatic polygon-offset.

::scene-wrapper
:abstractions-decal
::

## Usage

The minimal setup is a `<Decal>` placed as a child of any `<TresMesh>`,
with a JSON list of stamped decals bound via `v-model:data` and one or
more textures via `:map`.

```vue
<script setup lang="ts">
import { Decal, OrbitControls, useTexture } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import { reactive } from 'vue'

const { state: texture } = useTexture('/textures/logo.png')

const decals = reactive([
  {
    id: 'logo-1',
    position: [0, 0, 0.5],
    orientation: [0, 0, 0],
    size: [0.75, 0.17, 1],
    zIndex: 0,
    map: 'logo.png',
  },
])
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[2, 2, 3]" />
    <OrbitControls />
    <TresMesh>
      <TresBoxGeometry />
      <TresMeshStandardMaterial color="white" />
      <Decal v-if="texture" v-model:data="decals" :map="texture" />
    </TresMesh>
  </TresCanvas>
</template>
```

::prose-note
The `v-model:data` array is the **single source of truth** — every
decal you can see lives in it. It serializes to plain JSON so you can
save / load it from a backend, localStorage, or a `.json` file.
::

## Multiple textures (palette)

Pass an array to `:map` to give users a palette of textures to pick
from. The array returned by [`useTextures`](https://cientos.tresjs.org/api/loaders/use-textures)
plugs in directly:

```vue
<script setup lang="ts">
import { Decal, useTextures } from '@tresjs/cientos'

const { textures } = useTextures([
  '/textures/logo.png',
  '/textures/badge.png',
  '/textures/sticker.png',
])
</script>

<template>
  <Decal v-model:data="decals" :map="textures" />
</template>
```

Each entry references its texture by `name` — `<Decal>` auto-fills
`texture.name` from the URL filename when missing, so JSON `map`
fields round-trip cleanly.

## Custom material

The default material is `MeshBasicMaterial`. Override it via the slot
to plug in any Three.js material — `MeshStandardMaterial`,
`MeshPhysicalMaterial`, or a custom shader.

```vue
<Decal v-model:data="decals" :map="texture">
  <TresMeshStandardMaterial :transparent="true" :polygon-offset="true" />
</Decal>
```

::prose-note
Keep `transparent: true` and `polygonOffset: true` on any custom
material, otherwise stacking and alpha handling won't work as expected.
Color / opacity tint from the editor only applies to materials
exposing `.color` and `.opacity` (`MeshBasicMaterial`,
`MeshStandardMaterial`, …) — bespoke shader materials are skipped
silently.
::

## Stacking decals (z-layering)

Each decal has a `zIndex` controlling its draw order on the parent
mesh. Higher = on top. The component handles z-fighting via
`polygonOffset` automatically — but if you stack many decals near
parallel surfaces and still see flicker, raise `layerGap`.

::scene-wrapper
:abstractions-decal-stacking
::

```vue
<Decal
  v-model:data="decals"
  :map="textures"
  :layer-gap="0.002"
/>
```

zIndex stacks are **per-mesh** — two decals on different meshes never
compete for the same layer slot.

## Editable mode + `<DecalDebugUI>`

Add the `editable` prop to mount the interactive editor, then pair it
with `<DecalDebugUI>` — a full in-canvas editor that ships as a drop-in
HTML overlay sitting **outside** `<TresCanvas>`.

::prose-warning
`<DecalDebugUI>` needs its stylesheet — import it **once** at your app
entry. `<Decal>` itself is style-less, so this is only needed when you
mount `<DecalDebugUI>`.

```ts
// Vite / Vue — in main.ts
import '@tresjs/cientos/styles.css'
```

```ts
// Nuxt — in nuxt.config.ts
export default defineNuxtConfig({
  css: ['@tresjs/cientos/styles.css'],
})
```
::

::scene-wrapper
:abstractions-decal-editable
::

Three panels: a floating **handle** anchored to the editing decal, a
bottom **dock** (texture picker + edit tools), a right-side **layer
panel**.

- **Floating handle** (rotate + scale + snap + live `scale% · rotation° · L<n>` badge)
- **Color tint & opacity**
- **Mirror** (flip X / flip Y)
- **Layer controls** (`L+` / `L-`)
- **Visibility toggle**
- **Per-row remove**
- **Layer panel** (mesh-grouped, drag-to-reorder)
- **Texture picker** (drag or click-to-arm)
- **Mode badge** (placing / editing status)
- **Undo / Redo** buttons
- **Import / Export** buttons

```vue
<script setup lang="ts">
import { Decal, DecalDebugUI, OrbitControls, useTextures } from '@tresjs/cientos'
import type { DecalEditorSession, DecalJsonEntry } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import { computed, reactive, shallowRef } from 'vue'

const { textures } = useTextures(['/textures/a.png', '/textures/b.png'])

const layout = reactive<Record<string, DecalJsonEntry[]>>({
  cube: [],
  sphere: [],
})

const decalRef = shallowRef<{ editor: DecalEditorSession } | null>(null)
const session = computed(() => decalRef.value?.editor ?? null)
</script>

<template>
  <DecalDebugUI :session="session" :textures="textures ?? []" :data="layout" />

  <TresCanvas>
    <TresPerspectiveCamera :position="[2, 2, 4]" />
    <OrbitControls />

    <TresMesh name="cube" :position="[-1.2, 0, 0]">
      <TresBoxGeometry />
      <TresMeshStandardMaterial color="white" />
      <Decal ref="decalRef" v-model:data="layout.cube" :map="textures" editable />
    </TresMesh>

    <TresMesh name="sphere" :position="[1.2, 0, 0]">
      <TresSphereGeometry :args="[0.7]" />
      <TresMeshStandardMaterial color="white" />
      <Decal v-model:data="layout.sphere" :map="textures" editable />
    </TresMesh>
  </TresCanvas>
</template>
```

### How the wiring works

- `v-model:data="layout.cube"` — each `<Decal>` owns one slice of the
  layout object. The slice's key matches the parent mesh's `name`.
- `ref="decalRef"` — grab a reference to any `<Decal>` in the canvas;
  the session is canvas-shared so it doesn't matter which.
- `session = decalRef.value?.editor` — the editor session powers
  `<DecalDebugUI>`. Pass it through.
- `:data="layout"` on `<DecalDebugUI>` — the full mesh-keyed layout, so
  the overlay can render the layer panel and route imports back to each
  Decal by name.

::prose-note
The overlay is full-viewport (`position: fixed; inset: 0`) by default.
When embedding inside a bounded stage (docs, modal, sidebar preview),
pass `contained` so the overlay positions itself absolutely against
the nearest positioned ancestor instead.
::

```vue
<div style="position: relative; height: 500px;">
  <DecalDebugUI contained ... />
  <TresCanvas>...</TresCanvas>
</div>
```

## Import / Export

The Export button in the dock auto-downloads the current layout as
`decal-layout-YYYY-MM-DD.json`. The Import button opens a file picker;
the loaded JSON is sanitised (unknown mesh keys and unknown texture
names are dropped with a warning) and routed back through each
`<Decal>` automatically — no extra host code needed.

```vue
<!-- Custom filename -->
<DecalDebugUI :export-filename="`${sceneName}.json`" ... />

<!-- Disable the built-in download — handle export yourself -->
<DecalDebugUI :export-filename="null" @export="postToBackend" ... />
```

## Targeting a loaded model (`.glb`)

A `<Decal>` can be a &#x2A;*direct child of `<primitive>`**. Auto-resolution
walks one step up the scene graph and only accepts a `Mesh` — so the
behaviour depends on what the `<primitive>` wraps.

### When `:object` is a `Mesh`

The decal auto-resolves the wrapped mesh as its target. This is the
simplest option for a single-mesh asset:

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

const { nodes } = useGLTF('/models/helmet.glb', { draco: true })
// nodes.Helmet is a Mesh in this asset.
</script>

<template>
  <primitive v-if="nodes?.Helmet" :object="nodes.Helmet">
    <Decal v-model:data="layout.helmet" :map="textures" editable />
  </primitive>
</template>
```

::prose-note
The resolved parent is the `<primitive>`'s retargeting proxy rather than
the raw object. This is transparent in practice — geometry, `matrixWorld`
and raycasting all forward to the wrapped object — so the decal projects
and follows transforms correctly.
::

### When `:object` is a `Group`

A named node in a `.glb` is often a `Group` containing several child
meshes (e.g. a ceramic body + a metallic interior). Auto-resolution
returns `null` in that case and the decal silently does nothing — pass
the actual target child via `:mesh`:

```vue
<script setup lang="ts">
import { Decal, useGLTF } from '@tresjs/cientos'
import { computed } from 'vue'
import type { Mesh } from 'three'

const { nodes } = useGLTF('/models/mug.glb', { draco: true })
// nodes.Mug is a Group — pick the child you want to decal.
const body = computed<Mesh | null>(
  () => (nodes.value?.Mug?.getObjectByName('Body') as Mesh) ?? null,
)
</script>

<template>
  <primitive v-if="nodes?.Mug" :object="nodes.Mug">
    <Decal v-model:data="layout.mug" :map="textures" :mesh="body" editable />
  </primitive>
</template>
```

### Targeting an extracted sub-mesh

Alternatively, **wrap a `<TresMesh>` around an extracted sub-mesh**. Reach
for this when you need to target one named sub-mesh of a larger model (and
keep its material): use
[`useGraph`](https://docs.tresjs.org/api/composables.html#usegraph){rel="&#x22;nofollow&#x22;"} to
pull the sub-mesh, then build a regular `<TresMesh>` around its
`:geometry`:

```vue
<script setup lang="ts">
import { useGraph, useLoader } from '@tresjs/core'
import { Decal } from '@tresjs/cientos'
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
import { computed } from 'vue'

const { state: model } = useLoader(GLTFLoader, '/models/helmet.glb')
const scene = computed(() => model.value?.scene)
const graph = useGraph(scene)
const nodes = computed(() => graph.value?.nodes)
</script>

<template>
  <TresMesh
    v-if="nodes?.Helmet.geometry"
    name="helmet"
    :geometry="nodes.Helmet.geometry"
  >
    <primitive :object="nodes.Helmet.material" attach="material" />
    <Decal v-model:data="layout.helmet" :map="textures" editable />
  </TresMesh>
</template>
```

The mesh's `geometry` and `material` come from the loaded model; the
`<Decal>` lives inside a regular `<TresMesh>` with a clean scene-graph
parent.

::prose-warning
A saved decal's `position` is stored in **world space**, so it is
re-projected onto the parent using the parent's transform **at load
time**. A persisted layout therefore only round-trips if the parent sits
at the same transform it had when the decal was authored. Parents under a
continuously- or randomly-animated wrapper (e.g. `<Levioso>`, which starts
at a random phase each reload) move out from under the saved point, so the
projection clips to nothing and the decal vanishes. Author and persist
decals on parents whose transform is deterministic at load time, or apply
the animation only after the layout has mounted.
::

## JSON schema

Each entry in the `data` array follows the `DecalJsonEntry` shape; the
layout passed to `<DecalDebugUI>` groups these by mesh name as
`DecalLayout = Record<string, DecalJsonEntry[]>`.

Full schema

```ts
interface DecalJsonEntry {
  id: string // stable UUID
  position: [number, number, number] // target-mesh local space (raycast hit, baked into the parent's frame)
  orientation: [number, number, number] // Euler XYZ
  size: [number, number, number] // extents along X/Y; Z = projection depth
  zIndex: number // per-mesh layer order, ≥ 0
  map: string | null // matches a texture's .name
  flipX?: boolean // omitted when false
  flipY?: boolean // omitted when false
  color?: string // hex (e.g. '#ff6b35'), omitted when no tint
  opacity?: number // 0..1, omitted when 1
  visible?: boolean // omitted when true; false hides the decal
}

type DecalLayout = Record<string, DecalJsonEntry[]>
// { sphere: [...], cube: [...] }
```

## `<Decal>` props

| Prop              | Description                                                                                                                                                                                                                                                                                                                   | Default   |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **data**          | Two-way list of stamped decals (use with `v-model:data`).                                                                                                                                                                                                                                                                     | `[]`      |
| **map**           | A single `Texture` or array of `Texture[]`. With multiple, the editor lets the user cycle through them as a palette.                                                                                                                                                                                                          | `null`    |
| **mesh**          | Optional explicit target mesh (`Mesh` or `ShallowRef<Mesh>`). When omitted, the scene-graph parent of `<Decal>` is auto-resolved via a hidden anchor `<TresGroup>`. The decal mesh is imperatively parented to the target so it follows the target's runtime `position` / `rotation` / `scale` via the scene-graph hierarchy. | `null`    |
| **editable**      | When `true`, mounts the interactive editor (raycast, hover, click-to-place, drag-from-thumbnail). Required for `<DecalDebugUI>` interactions to work on this Decal.                                                                                                                                                           | `false`   |
| **baseSize**      | Reference size used to derive each decal's size from the texture aspect ratio.                                                                                                                                                                                                                                                | `1`       |
| **baseOffset**    | Distance along the surface normal (parent units) to avoid z-fighting between the decal and the host mesh.                                                                                                                                                                                                                     | `0.01`    |
| **layerGap**      | Extra offset added per `zIndex` step on top of `baseOffset`. Increase if stacked decals still flicker.                                                                                                                                                                                                                        | `0.001`   |
| **cullThreshold** | Drops projected triangles whose face normal makes an angle steeper than `acos(threshold)` with the projector. Mitigates [#21187](https://github.com/mrdoob/three.js/issues/21187){rel="&#x22;nofollow&#x22;"}. Pass `0` to disable.                                                                                           | `0.2`     |
| **edgeColor**     | Color of the edge outline drawn around a decal while it is hovered (pointer or layer panel) in editable mode.                                                                                                                                                                                                                 | `#0000ff` |

## `<Decal>` events

| Event         | Payload                                    | Description                                                               |
| ------------- | ------------------------------------------ | ------------------------------------------------------------------------- |
| `update:data` | `DecalJsonEntry[]`                         | v-model partner — fires whenever the JSON list changes.                   |
| `add`         | `DecalEntry`                               | A new decal has been committed (create mode → confirm).                   |
| `update`      | `DecalEntry`                               | An existing decal has been committed (update mode → confirm).             |
| `delete`      | `DecalEntry`                               | A decal has been removed (delete button or `Del` / `Backspace`).          |
| `select`      | `DecalEntry`                               | Edition began on `entry` (panel click, 3D click, or programmatic).        |
| `cancel`      | —                                          | Edition was aborted without commit (`Esc`, click-outside in create mode). |
| `decalClick`  | `{ entry: DecalEntry, event: MouseEvent }` | Fires on click of any stamped decal, even when `editable` is `false`.     |

## `<Decal>` exposed (via `ref`)

The template ref resolves to `DecalImperativeApi` — import the type for
full autocompletion:

```ts
import type { DecalImperativeApi } from '@tresjs/cientos'

const decalRef = ref<DecalImperativeApi | null>(null)
```

| Property        | Type                      | Description                                                                            |
| --------------- | ------------------------- | -------------------------------------------------------------------------------------- |
| `editor`        | `DecalEditorSession`      | The canvas-shared editor session. Pass it to `<DecalDebugUI :session>`.                |
| `beginEditById` | `(id: string) => boolean` | Programmatically start editing a specific decal. Returns `false` if the id is unknown. |
| `commit`        | `() => void`              | Commit the in-flight edit (same as `Enter`).                                           |
| `cancel`        | `() => void`              | Abort the in-flight edit (same as `Esc`).                                              |
| `remove`        | `() => void`              | Delete the currently edited decal (same as `Del`).                                     |

## `<DecalDebugUI>` props

| Prop               | Description                                                                                                                                                                 | Default                        |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **session**        | `DecalEditorSession | null` — obtained from any `<Decal>` ref via `decalRef.value?.editor`. Mandatory for the overlay to wire up the interactive logic.                     | `null`                         |
| **data**           | Mesh-name-keyed map of decal slices — `{ sphere: [...], cube: [...] }`. Each key matches a `<TresMesh name="...">` whose child `<Decal>` owns the slice.                    | `{}`                           |
| **textures**       | The full texture palette shown in the dock's picker.                                                                                                                        | `[]`                           |
| **theme**          | `'light'` or `'dark'` — overlay theme tokens.                                                                                                                               | `'light'`                      |
| **snapAngle**      | Rotation step (degrees) applied when the snap toggle is on. Snap-tick ring on the handle adapts automatically.                                                              | `15`                           |
| **exportFilename** | Filename for the built-in JSON download. When omitted, defaults to `decal-layout-YYYY-MM-DD.json`. Pass `null` to skip the auto-download (the `@export` event still fires). | `decal-layout-YYYY-MM-DD.json` |
| **contained**      | Scope the overlay to the nearest positioned ancestor instead of pinning it to the viewport. Useful for embedding the editor inside a docs page or a bounded host stage.     | `false`                        |

## `<DecalDebugUI>` events

| Event    | Payload       | Description                                                                                                                              |
| -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `export` | `DecalLayout` | Fires after the user clicks Export. The download (if enabled) has already been triggered — use this for side effects (POST, analytics…). |
| `import` | `DecalLayout` | Fires after the user picks a JSON file. The layout has been sanitised (unknown keys dropped) and already applied to the bound Decals.    |

## Caveats

- ✨ The overlay sits at `position: fixed; inset: 0; pointer-events: none` with
  individual panels opting back in. It sits **above** the canvas by default
  (`z-index: 1000000`) — adjust via host CSS if needed.
- 🎨 `<DecalDebugUI>` ships its own theme in a global stylesheet under the
  `.cientos-decal-ui` namespace, so host styles aren't affected. The CSS
  variables (`--accent`, `--dock-bg`, etc.) can be overridden by targeting
  the namespace.
- 🔶 Decals are **per-canvas** — if you have multiple `<TresCanvas>` in your
  app, each one has its own independent session. Pair each `<DecalDebugUI>`
  with the right `session` (from one of the Decals inside that canvas).
- 🧩 The parent mesh resolution defaults to the scene-graph parent. If your
  setup needs a different target (e.g. a mesh referenced from outside the
  Decal's parent slot), pass `:mesh="meshRef"`.

## Limitations

::prose-note
Decal vertices are baked into the **target mesh's local space** at
build time (the decal mesh is imperatively re-parented to the target,
so `position` / `rotation` / `scale` on the parent are followed via
the scene graph — no rebuild needed).

Runtime deformations that change vertex positions outside of a
transform are **not** followed:

- **`SkinnedMesh`** skinning is not applied — the decal stays in rest
  pose. See [three.js#7926](https://github.com/mrdoob/three.js/issues/7926){rel=""nofollow""}.
- **`morphAttributes`** on the parent are ignored.
- Direct mutations of the parent's `geometry.attributes.position`
  (e.g. CPU wave displacement, GPGPU) — the projection is baked once.
- Decals near silhouettes can wrap around onto opposite faces (see
  [three.js#21187](https://github.com/mrdoob/three.js/issues/21187){rel=""nofollow""}) —
  mitigated by the `cullThreshold` prop, default `0.2`.

`<Decal>` warns once per parent mesh when it detects these conditions.
::

## Keyboard shortcuts

| Shortcut          | Action                                           |
| ----------------- | ------------------------------------------------ |
| `Enter`           | Confirm the in-flight edit                       |
| `Esc`             | Cancel (revert updates, drop pending placements) |
| `Del` / `⌫`       | Delete the edited decal (or cancel a create)     |
| `⌘Z` / `Ctrl+Z`   | Undo                                             |
| `⇧⌘Z` / `Ctrl+⇧Z` | Redo                                             |
| Click outside     | Auto-commit an in-flight update; cancel a create |

## Programmatic API (`useDecalEditor`)

Skip `<DecalDebugUI>` entirely or augment it with custom panels —
`useDecalEditor()` returns the same canvas-scoped session every Decal
shares. Call it from any component inside `<TresCanvas>` (after at
least one `<Decal>` has mounted).

```ts
import { useDecalEditor } from '@tresjs/cientos'

const session = useDecalEditor()
```

The session exposes reactive state (`editingEntry`, `editingMode`,
`canUndo`, `canRedo`, …), by-id mutators (`beginEditById`,
`setZIndexById`, `setVisibilityById`, `removeById`), batched updates
(`setMeshData`), commit / delete / cancel listeners, undo / redo, and
a `registerDecalEntry` hook for external entries. Helper utilities
(`ensureTextureNames`, `getTextureName`, `getTextureAspect`,
`invalidateDecalGeometry`) are exported alongside.

Full API reference

### Reactive state

```ts
session.editingEntry // ShallowRef<DecalEntry | null>
session.editingMode // Ref<'create' | 'update' | null>
session.lockedMeshUuid // Ref<string | null>
session.hoveredEntry // ShallowRef<DecalEntry | null>
session.canUndo // Ref<boolean>
session.canRedo // Ref<boolean>
```

### Mutating decals by id

```ts
session.beginEditById(id) // start editing a placed decal
session.setZIndexById(id, newZ) // reorder one decal
session.setVisibilityById(id, false) // hide / show
session.removeById(id) // delete
```

When the targeted id matches the **currently editing** entry, mutations
land on the in-flight buffer (committed on `Enter`, reverted on `Esc`).
Otherwise they update `data` immediately and record history.

### Batched mesh updates

```ts
session.setMeshData(meshName, nextEntries, { recordHistory: true })
```

A single emit avoids the stale-snapshot race that hits multiple
back-to-back `setZIndexById` calls in the same tick.

### Listening to commits

```ts
const off = session.onCommit((entry, mode) => {
  console.log(mode, entry) // mode: 'create' | 'update'
})
session.onDelete((entry) => { /* … */ })
session.onCancel(() => { /* … */ })

// All return an unsubscribe function:
onBeforeUnmount(off)
```

### Undo / redo

```ts
session.canUndo.value // Ref<boolean>
session.undo() // returns true if something was undone
session.redo()
```

History is per-canvas, capped at 100 operations, disabled mid-edit.

### Power user — external entries

Plug a decal-like object that lives outside a `<Decal>` (custom data
source, server snapshot, fake entry for tests) by registering a
`DecalEntryActions` bundle so the `*ById` session methods route to it:

```ts
import type { DecalEntryActions } from '@tresjs/cientos'

session.registerDecalEntry('decal-7', {
  beginEdit: () => { /* … */ },
  setZIndex: (newZ) => { /* … */ },
  setVisibility: (visible) => { /* … */ },
  remove: () => { /* … */ },
} satisfies DecalEntryActions)
onBeforeUnmount(() => session.unregisterDecalEntry('decal-7'))
```

### Helper utilities

| Helper                          | Use                                                                             |
| ------------------------------- | ------------------------------------------------------------------------------- |
| `ensureTextureNames(textures)`  | Back-fills `texture.name` from `userData.name` or the filename in `image.src`.  |
| `getTextureName(texture)`       | Single-texture variant — returns a stable name or `null`.                       |
| `getTextureAspect(texture)`     | `{ x, y }` aspect ratio for custom-sized decals.                                |
| `invalidateDecalGeometry(mesh)` | Force a rebuild on the next frame — call when the parent mesh moved or swapped. |


# Edges

::scene-controls-wrapper
:abstractions-edges
::

The `cientos` package provides an abstraction of [EdgesGeometry](https://threejs.org/docs/#api/en/geometries/EdgesGeometry){rel="&#x22;nofollow&#x22;"} from Three.js, `<Edges>` is specifically designed for rendering visible edges of objects in a scene graph. This enhances the visual quality by highlighting contours and providing a stylized appearance which contributes to the artistic aspect of 3D visualizations.

## Usage

```vue {3,12}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Box, Edges, OrbitControls } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 2, 5]" />
    <OrbitControls />
    <Box>
      <TresMeshBasicMaterial />
      <Edges />
    </Box>
  </TresCanvas>
</template>
```

## Props

`<Edges>` is based on [LineSegments](https://threejs.org/docs/#api/en/objects/LineSegments){rel="&#x22;nofollow&#x22;"} & [Line](https://threejs.org/docs/#api/en/objects/Line){rel="&#x22;nofollow&#x22;"} and supports all of its props.

| Prop          | Description                                                                                                                                                                                                                                                         | Default   |
| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| **color**     | `THREE.Color` — Color of the edges. :br More informations : [TresColor](https://docs.tresjs.org/api/instances-arguments-and-props.html#colors){rel="&#x22;nofollow&#x22;"} — [THREE.Color](https://threejs.org/docs/#api/en/math/Color){rel="&#x22;nofollow&#x22;"} | `#ff0000` |
| **threshold** | `number` — An edge is only rendered if the angle (in degrees) between the face normals of the adjoining faces exceeds this value                                                                                                                                    | `1`       |


# Fit

::scene-wrapper
:abstractions-fit
::

`<Fit />` uniformly scales and positions its children as a group. By default, it fits its children into a 1 × 1 × 1 box at the world origin.

Alternatively, the children can be fit into a `Box3` or an `Object3D`.

Or the children can simply be resized. With `<Fit />` the children are scaled relative to the center of their calculated bounding box.

## Usage

```vue {2,20,27}
<script setup lang="ts">
import { Fit, OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import { BoxGeometry, MeshNormalMaterial } from 'three'

const positions: number[][] = []
for (let y = 100; y <= 120; y += 10) {
  for (let x = 100; x <= 120; x += 10) {
    positions.push([x, y, 9999])
  }
}
const geom = new BoxGeometry()
const mat = new MeshNormalMaterial()
</script>

<template>
  <TresCanvas clear-color="#4F4F4F">
    <TresPerspectiveCamera :position="[1, 1, 1]" />
    <OrbitControls />
    <Fit>
      <TresMesh
        v-for="(pos, index) in positions"
        :key="index"
        :position="pos"
        :args="[geom, mat]"
      />
    </Fit>
    <TresGridHelper :args="[1, 1]" />
  </TresCanvas>
</template>

```

## Props

| Name        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **into**    | If `into` is:* omitted or explicitly `undefined`: position/scale children to fit into a 1 × 1 × 1 `Box3` at world origin.
* `null`: turn off `<Fit />`; reset scale/position of children.
* `number`: convert argument to `Vector3(number, number, number)`.
* `[number, number, number]`: convert argument to `Vector3`.
* `Vector3`: position/scale children to fit inside a `Box3` of size `Vector3` at target objects' cumulative center.
* `Box3`: position/scale children to fit inside `Box3`.
* `Object3D`: position/scale children to fit inside calculated `Box3`. [See `THREE.Box3.setFromObject`](https://threejs.org/docs/#api/en/math/Box3.setFromObject){rel="&#x22;nofollow&#x22;"}. `<Fit />` must not contain the `Object3D` and vice-versa.:br default: :br`new Box3(new Vector3(-0.5, -0.5, -0.5), new Vector3(0.5, 0.5, 0.5))` |
| **precise** | [See `precise` argument in `THREE.Box3.setFromObject`](https://threejs.org/docs/index.html?q=box3#api/en/math/Box3.setFromObject){rel="&#x22;nofollow&#x22;"}:br:br default: :br`false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |


# Abstractions

:api-list{list-name="abstraction-list"}


# Instances

::scene-controls-wrapper
:abstractions-instances
::

Rendering the same mesh many times is one drawcall per copy, and drawcalls are what a scene runs
out of first. `<Instances />` owns a single `THREE.InstancedMesh` and `<Instance />` is a
placeholder that registers itself with it, so a `v-for` of a thousand nodes costs **one** drawcall.

An `<Instance />` behaves like any other node in the graph: give it `position`, nest it under a
group, animate that group, toggle it with `v-if`, listen for `@click` on one of them.

## Usage

```vue {3,14,16-21}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Instance, Instances } from '@tresjs/cientos'
import { BoxGeometry, MeshStandardMaterial } from 'three'

const geometry = new BoxGeometry(0.35, 0.35, 0.35)
const material = new MeshStandardMaterial()

const cubes = Array.from({ length: 900 }, (_, i) => [i % 30 - 15, 0, Math.floor(i / 30) - 15])
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[14, 10, 14]" />
    <Instances :geometry="geometry" :material="material">
      <Instance
        v-for="(position, i) in cubes"
        :key="i"
        :position="position"
        color="#38bdf8"
      />
    </Instances>
  </TresCanvas>
</template>
```

::prose-note
The `geometry` and `material` are yours: `<Instances />` never disposes them.
::

## Per-instance color

`<Instance />` takes a `color` prop, written into the batch's `instanceColor` buffer. The buffer is
only allocated once at least one instance asks for a color, so an uncolored batch pays nothing.

```vue
<Instance :position="[0, 0, 0]" :color="isSelected ? '#f97316' : '#38bdf8'" />
```

## Pointer events

Each placeholder raycasts against the batch's geometry at its own transform, so pointer events land
on the single instance you clicked, not on the whole batch.

```vue
<Instance :position="position" @click="select(id)" @pointer-enter="hover(id)" />
```

## Hiding instances

Two ways, and they differ in what they cost:

- `:visible="false"` keeps the instance registered but drops it from the batch for that frame.
  Use it for something that toggles often.
- `v-if` unmounts the placeholder and unregisters it. Use it when the node is really gone.

Either way the remaining instances are packed densely, so hidden ones cost nothing on the GPU.

## Nesting and transforms

Instances read their world matrix, so parent transforms work exactly as you would expect:

```vue
<Instances :geometry="geometry" :material="material">
  <Levioso>
    <TresGroup :position="[0, 3, 0]">
      <!-- floats with the group, still the same drawcall -->
      <Instance v-for="i in 12" :key="i" :position="ringPosition(i)" />
    </TresGroup>
  </Levioso>
</Instances>
```

## Animating instances

Anything that moves an instance's node moves it in the batch, because the batch re-reads world
matrices every frame. An `AnimationMixer` included: a mixer resolves its tracks by `Object3D`
name, and an `<Instance />` takes a `name` like any other node, so a clip can drive one directly.

```vue
<Instances :geometry="geometry" :material="material">
  <!-- "Blade" is driven by the clip; everything under "Rotor" rides along with it -->
  <TresGroup name="Rotor">
    <Instance name="Blade" />
    <Instance v-for="i in 12" :key="i" :position="ringPosition(i)" />
  </TresGroup>
</Instances>
```

::prose-note
Inside a `<Merged />`, `name` and `batch` are different things: `batch` picks which
`InstancedMesh` to join, `name` is what this node is called. `tres gltf --instance` emits both,
because a batch is keyed after its first mesh and every copy in it shares that key.
::

A track that finds no node is not silent: three logs
`THREE.PropertyBinding: No target node found for track: <name>.position.` once for it.

## Limit and growth

`limit` is the initial buffer allocation, not a cap. If more instances register than it allows, the
batch reallocates its buffers (doubling), keeps every instance, and warns once in dev telling you
which `limit` would have avoided the reallocation.

```vue
<Instances :geometry="geometry" :material="material" :limit="5000">
```

Set it close to your real maximum when you know it: reallocating mid-scene is avoidable work.

## Why every instance shows up in the scene graph

Open the devtools on a batch of 500 and you will see 500 nodes. That is expected, not a leak.

Each `<Instance />` is a real `Object3D` in the graph. That is precisely what buys you the ergonomics:
`position` is just a transform, nesting under a group works because the group is its parent, `v-if`
works because unmounting a node unregisters it, and `@click` works because there is a node to hit.
The batch reads each node's world matrix every frame and packs it into the instance buffer.

What those nodes do **not** do is render. They carry no geometry and never enter the render list, so
500 of them still cost one drawcall. What you are seeing in the graph is bookkeeping, not draw work.

The costs that are real:

|                 | Cost                                                                                                                                                    |
| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Per frame       | One world-matrix update and one matrix multiply per instance.                                                                                           |
| On pointer move | A raycast per instance, but only for instances that have a pointer handler (or inherit one from an ancestor). A scatter with no handlers costs nothing. |
| Memory          | One bare `Object3D` per instance.                                                                                                                       |

::prose-note
If you have tens of thousands of instances that never move, never toggle and never need picking, a
`TresInstancedMesh` whose `instanceMatrix` you fill yourself will always be cheaper. `<Instances />`
trades that per-node overhead for being able to write instances as ordinary Vue nodes.
::

## Props

### Instances

| Prop       | Description                                                       | Default     |
| :--------- | :---------------------------------------------------------------- | ----------- |
| `geometry` | Geometry shared by every instance. Not disposed by the component. | *required*  |
| `material` | Material shared by every instance. Not disposed by the component. | *required*  |
| `limit`    | Initial buffer allocation. Grows automatically when exceeded.     | `1000`      |
| `batch`    | Key this batch registers under with an ancestor `<Merged />`.     | `undefined` |
| `name`     | Name for the `InstancedMesh` itself.                              | `undefined` |

Exposes the underlying `THREE.InstancedMesh` through `instance`.

### Instance

| Prop      | Description                                                                              | Default     |
| :-------- | :--------------------------------------------------------------------------------------- | ----------- |
| `batch`   | Batch to join, by its key in `<Merged :meshes />`. Omit for the nearest `<Instances />`. | `undefined` |
| `name`    | Name for this instance's node, so a mixer or `getObjectByName` can find it.              | `undefined` |
| `color`   | Per-instance color, written into `instanceColor`.                                        | `undefined` |
| `visible` | `false` drops the instance from the batch without unregistering it.                      | `true`      |

Transform props (`position`, `rotation`, `scale`, …) and pointer events behave like any other node.

::read-more{to="https://cientos.tresjs.org/api/abstractions/merged"}
Instancing several meshes at once, for example every node of a glTF model, is what `<Merged />` is for.
::


# Levioso (Float)

::scene-controls-wrapper
:abstractions-levioso
::

![Leviosa](https://media.giphy.com/media/HaCFT5ghY6L1m/giphy.gif)

The `cientos` package provides a `<Levioso />` wrapper that makes its content … float, just like Magic 🪄✨

## Usage

```vue {3,11,13}
<script setup lang="ts">
import { TresCanvas } from "@tresjs/core";
import { Levioso, OrbitControls, Box } from "@tresjs/cientos";

</script>

<template>
  <TresCanvas :clear-color="0x82dbc5">
    <TresPerspectiveCamera :position="[0, 0, 5]" :look-at="[0, 0, 0]" />
    <OrbitControls />
    <Levioso :speed="4">
      <Box />
    </Levioso>
    <TresAmbientLight :intensity="1" />
    <TresDirectionalLight :intensity="1" :position="[2, 2, 2]" />
    <TresGridHelper :position="[0, -1, 0]" />
  </TresCanvas>
</template>

```

## Props

| Prop             | Description                                          | Default       |
| :--------------- | :--------------------------------------------------- | ------------- |
| `speed`          | Floating speed, higher it rocks more 🤘.             | `1`           |
| `rotationFactor` | Factor for Euler rotation.                           | `1`           |
| `floatFactor`    | Factor for Up/down movement.                         | `1`           |
| `range`          | Range of y-axis values the object will float within. | `[-0.1, 0.1]` |


# Mask

::scene-controls-wrapper
:abstractions-mask
::

`<Mask/>` uses the stencil buffer to cut out areas of the screen.

::prose-warning
To use `<Mask />` you *must* add `:stencil="true"` to your `<TresCanvas />`.

`<Mask />` relies on the [`stencil buffer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer){rel=""nofollow""}. In recent versions of THREE.js, by default, the stencil buffer is not created.
::

## Usage

```vue {2,16-19}
<script setup lang="ts">
import { Mask, OrbitControls, useMask } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas :stencil="true" clear-color="#4f4f4f">
    <TresPerspectiveCamera />
    <OrbitControls />

    <TresGroup :scale="2">
      <TresMesh>
        <TresRingGeometry :args="[0.95, 1, 64]" />
        <TresMeshBasicMaterial color="white" />
      </TresMesh>
      <Mask :id="1">
        <TresCircleGeometry />
        <TresMeshBasicMaterial color="#fbb03b" />
      </Mask>
    </TresGroup>

    <TresMesh :position-z="-1">
      <TresBoxGeometry />
      <TresMeshNormalMaterial v-bind="useMask(1)" />
    </TresMesh>

    <TresMesh :position-z="-3">
      <TresBoxGeometry />
      <TresMeshNormalMaterial v-bind="useMask(1)" />
    </TresMesh>

    <TresMesh :position-z="-5">
      <TresBoxGeometry />
      <TresMeshNormalMaterial />
    </TresMesh>
  </TresCanvas>
</template>

```

## Props

| Prop             | Description                                                                                                  | Default |
| :--------------- | :----------------------------------------------------------------------------------------------------------- | ------- |
| **`id`**         | Id of the stencil buffer to use. Each mask must have a `number` id. Multiple masks can refer to the same id. |         |
| **`colorWrite`** | Whether the colors of the mask's own material will leak through.                                             | `false` |
| **`depthWrite`** | Whether the depth of the mask's own material will leak through.                                              | `false` |

## useMask

Composable that returns the stencil configuration to apply a mask to a material. Use it with `v-bind` on materials that should be affected by the mask.

**Parameters:**

- `id` - The mask id to use (number or Ref)
- `inverse` - Whether to invert the mask (boolean or Ref), defaults to `false`

```vue
<TresMeshNormalMaterial v-bind="useMask(1)" />
```


# Merged

::scene-controls-wrapper
:abstractions-merged
::

`<Merged />` takes a `{ name: mesh }` map and builds one instanced batch per entry. Any descendant,
at any depth and in any component, joins one by key with `<Instance batch="..." />`.

That is what makes repeating a whole model cheap: a robot made of two meshes drawn 49 times is
**two** drawcalls, not 98.

## Usage

The model becomes its own component, and knows nothing about the batches beyond their names:

```vue [Robot.vue]
<script setup lang="ts">
import { Instance } from '@tresjs/cientos'
</script>

<template>
  <TresGroup>
    <Instance batch="Body" :position="[0, 0.6, 0]" />
    <Instance batch="Body" :position="[0, 1.6, 0]" :scale="0.6" />
    <Instance batch="Eye" :position="[-0.18, 1.7, 0.32]" />
    <Instance batch="Eye" :position="[0.18, 1.7, 0.32]" />
  </TresGroup>
</template>
```

The provider hands over the meshes and renders as many copies as it likes:

```vue {12-18}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Merged, useGLTF } from '@tresjs/cientos'
import Robot from './Robot.vue'

const { nodes } = useGLTF('/robot.glb')
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[12, 9, 12]" />
    <Merged :meshes="{ Body: nodes.Body, Eye: nodes.Eye }">
      <Robot :position="[-2, 0, 0]" />
      <Robot :position="[0, 0, 0]" />
      <Robot :position="[2, 0, 0]" />
    </Merged>
  </TresCanvas>
</template>
```

::prose-note
Nothing needs to be threaded through props or slots: the batches are provided, so an `<Instance />`
finds the one it names no matter how deep it sits or how many components stand between them.
::

## Instancing a whole glTF

`useGLTF` gives you `nodes`, so instancing every repeated mesh of a model is a matter of picking the
ones worth batching:

```vue
<Merged :meshes="{ Screw: nodes.Screw, Bolt: nodes.Bolt }">
  <Machine v-for="i in 20" :key="i" :position="layout[i]" />
</Merged>
```

The payoff is across models, not within one: twenty machines sharing two batches is two drawcalls.

## Opting a node out

An `<Instance />` is all-or-nothing per node: it uses the batch's geometry and material. When one
node needs its own material, a different geometry, or its own shader, render a normal `<TresMesh />`
instead of an `<Instance />`. You trade one drawcall for full control over that node, and every
other node stays batched.

## Props

| Prop     | Description                                                                                                      | Default    |
| :------- | :--------------------------------------------------------------------------------------------------------------- | ---------- |
| `meshes` | One batch per entry, keyed by what `<Instance batch="..." />` joins.                                             | *required* |
| `limit`  | Initial buffer allocation per batch. One batch per entry in `meshes`, so it defaults lower than `<Instances />`. | `100`      |

Exposes the named batch registry through `instances`.

::read-more{to="https://cientos.tresjs.org/api/abstractions/instances"}
Per-instance colors, pointer events, visibility and the `limit` growth behaviour are documented on `<Instances />`.
::


# Outline

::scene-controls-wrapper
:abstractions-outline
::

`<Outline />` creates an inverted-hull outline using its parent's geometry. Supported parents are `<TresMesh>` and `<TresSkinnedMesh>`.

## Usage

```vue {3,15,20}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { OrbitControls, Outline } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas clear-color="#4f4f4f">
    <TresPerspectiveCamera />
    <OrbitControls />
    <TresAmbientLight :intensity="3.14" />
    <TresPointLight :intensity="50" :position="[2, 2, 0]" />
    <TresMesh :position-x="-0.75">
      <TresBoxGeometry />
      <TresMeshPhongMaterial />
      <Outline :thickness="7.5" color="#82dbc5" />
    </TresMesh>
    <TresMesh :position-x="0.75">
      <TresSphereGeometry :args="[0.5]" />
      <TresMeshPhongMaterial />
      <Outline :thickness="7.5" color="#fbb03b" />
    </TresMesh>
  </TresCanvas>
</template>

```

## Props

| Props       | Description                                                                                                                                                                                        | Default   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| color       | Outline color                                                                                                                                                                                      | `'black'` |
| screenspace | Whether line thickness is independent of zoom                                                                                                                                                      | `false`   |
| opacity     | Outline opacity                                                                                                                                                                                    | `1`       |
| transparent | Outline transparency                                                                                                                                                                               | `false`   |
| thickness   | Outline thickness                                                                                                                                                                                  | `0.05`    |
| angle       | Geometry crease angle (`0` is no crease). See [BufferGeometryUtils.toCreasedNormals](https://threejs.org/docs/#examples/en/utils/BufferGeometryUtils.toCreasedNormals){rel="&#x22;nofollow&#x22;"} | `Math.PI` |


# Sampler

::scene-controls-wrapper
:abstractions-sampler
::

Declarative abstraction around MeshSurfaceSampler & InstancedMesh. It samples points from the passed mesh and transforms an InstancedMesh's matrix to distribute instances on the points.

## Usage

```vue {2,11-20}
<script setup lang="ts">
import { OrbitControls, Sampler } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas clear-color="#82DBC5">
    <TresPerspectiveCamera :position="[0, 0.5, 5]" />
    <OrbitControls />

    <Sampler :count="50">
      <TresMesh>
        <TresTorusGeometry />
      </TresMesh>

      <TresInstancedMesh :args="[null!, null!, 1000]">
        <TresBoxGeometry :args="[0.1, 0.1, 0.1]" />
        <TresMeshNormalMaterial />
      </TresInstancedMesh>
    </Sampler>
    <TresGridHelper :args="[10, 10]" />
  </TresCanvas>
</template>

```

## Props

| Props        | Description                                                        |
| ------------ | ------------------------------------------------------------------ |
| mesh         | **Mesh** Surface mesh from which to sample                         |
| count        | **Number** Number of samples                                       |
| instanceMesh | **InstanceMesh** InstanceMesh to scatter                           |
| weight       | **String** A vertex attribute to be used as a weight when sampling |
| transform    | **Function** A function that can be used as a custom sampling      |

## useSurfaceSampler

A hook to obtain the result of the :sampler[as a buffer. Useful for driving anything other than InstancedMesh via the Sampler.]

```vue {2,10}
<script setup lang="ts">
import { OrbitControls, useSurfaceSampler } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import { ref, watch } from 'vue'

const torusRef = ref()
const instancesRef = ref()

watch(torusRef, (value) => {
  useSurfaceSampler(value, 50, instancesRef.value, 'color')
})
</script>

<template>
  <TresCanvas clear-color="#82DBC5">
    <TresPerspectiveCamera :position="[0, 0.5, 5]" />
    <OrbitControls />

    <TresMesh ref="torusRef">
      <TresTorusGeometry />
    </TresMesh>

    <TresInstancedMesh
      ref="instancesRef"
      :args="[null!, null!, 1_000]"
    >
      <TresSphereGeometry :args="[0.1, 32, 32]" />
      <TresMeshNormalMaterial />
    </TresInstancedMesh>

    <TresGridHelper :args="[10, 10]" />
  </TresCanvas>
</template>
```


# ScreenSizer

::scene-wrapper
:abstractions-screen-sizer
::

Adds a `<TresObject3D />` wrapper that scales to "screen space". By default `1` THREE world unit will be translated to 1 screen pixel.

E.g. a BoxGeometry with a height, width, and depth of 100 each, will be scaled to 100 screen pixels in each dimension.

## Usage

```vue {3,10,15}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { OrbitControls, ScreenSizer } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas clear-color="#3f3f3f">
    <TresPerspectiveCamera :position="[10, 10, 10]" />
    <OrbitControls />
    <ScreenSizer>
      <TresMesh>
        <TresBoxGeometry :args="[100, 100, 100]" />
        <TresMeshNormalMaterial />
      </TresMesh>
    </ScreenSizer>
    <TresMesh :position-x="5">
      <TresBoxGeometry />
      <TresMeshNormalMaterial />
    </TresMesh>
    <TresGridHelper :args="[10, 10]" />
  </TresCanvas>
</template>
```

## Props

Inherits all props from `THREE.Object3D`.


# ScreenSpace

::scene-controls-wrapper
:abstractions-screen-space
::

`<ScreenSpace />` wraps its children in a `<TresGroup />` and positions them in front of the active camera at `:depth`.

Additionally, the `top`, `bottom`, `left`, `right` props can be used to position them similarly to CSS `position: absolute` property when using a `PerspectiveCamera` or an `OrtographicCamera`.

## Usage

```vue {2,11,16}
<script setup lang="ts">
import { OrbitControls, ScreenSpace } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas clear-color="#333">
    <TresPerspectiveCamera />
    <OrbitControls />

    <ScreenSpace :depth="5">
      <TresMesh>
        <TresTorusGeometry />
        <TresMeshNormalMaterial />
      </TresMesh>
    </ScreenSpace>

    <TresGridHelper :args="[10, 10]" />
  </TresCanvas>
</template>

```

## Props

| Prop     | Description                                                 | Default                                 |
| :------- | :---------------------------------------------------------- | --------------------------------------- |
| `depth`  | Distance from the camera                                    | `-1`                                    |
| `top`    | Similar to CSS `top` property. Cannot be used with `bottom` | `0.5` (vertical center of the screen)   |
| `bottom` | Similar to CSS `bottom` property. Cannot be used with `top` |                                         |
| `left`   | Similar to CSS `left` property. Cannot be used with `right` | `0.5` (horizontal center of the screen) |
| `right`  | Similar to CSS `right` property. Cannot be used with `left` |                                         |


# Camera Controls

::scene-controls-wrapper
:controls-camera-controls
::

[CameraControls](https://github.com/yomotsu/camera-controls){rel="&#x22;nofollow&#x22;"} is a camera controller similar to [OrbitControls](https://cientos.tresjs.org/api/controls/orbit-controls) yet supports smooth transitions and more features.

However, it is thirty party library for ThreeJS. So to use it you would need to install and import using [npm](https://www.npmjs.com/package/camera-controls){rel="&#x22;nofollow&#x22;"}.

## Usage

```vue {7}
<script setup>
import { CameraControls } from "@tresjs/cientos"
</script>
<template>
  <TresCanvas clear-color="#82DBC5">
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <CameraControls />
    <Box :scale="2">
      <TresMeshToonMaterial color="orange" />
    </Box>
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
    <TresGridHelper />
  </TresCanvas>
</template>
```

::prose-warning
Is really important that the Perspective camera is set first in the canvas. Otherwise might break.
::

## Props

Certainly! Here's the properties of the object in raw markdown table format:

| Prop                      | Description                                                                                                                                                                               | Default                                                                              |
| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **makeDefault**           | Whether to make this the default controls.                                                                                                                                                | `false`                                                                              |
| **camera**                | The camera to control.                                                                                                                                                                    | `undefined`                                                                          |
| **domElement**            | The DOM element to listen to.                                                                                                                                                             | `undefined`                                                                          |
| **minPolarAngle**         | Minimum vertical angle in radians.                                                                                                                                                        | `0`                                                                                  |
| **maxPolarAngle**         | Maximum vertical angle in radians.                                                                                                                                                        | `Math.PI`                                                                            |
| **minAzimuthAngle**       | Minimum horizontal angle in radians.                                                                                                                                                      | `-Infinity`                                                                          |
| **maxAzimuthAngle**       | Maximum horizontal angle in radians.                                                                                                                                                      | `Infinity`                                                                           |
| **distance**              | Current distance.                                                                                                                                                                         | `camera.position.z`                                                                  |
| **minDistance**           | Minimum distance for dolly. PerspectiveCamera only.                                                                                                                                       | `Number.EPSILON`                                                                     |
| **maxDistance**           | Maximum distance for dolly. PerspectiveCamera only.                                                                                                                                       | `Infinity`                                                                           |
| **infinityDolly**         | `true` to enable Infinity Dolly for wheel and pinch.                                                                                                                                      | `false`                                                                              |
| **minZoom**               | Minimum camera zoom.                                                                                                                                                                      | `0.01`                                                                               |
| **maxZoom**               | Maximum camera zoom.                                                                                                                                                                      | `Infinity`                                                                           |
| **smoothTime**            | Approximate time in seconds to reach the target. A smaller value will reach the target faster.                                                                                            | `0.25`                                                                               |
| **draggingSmoothTime**    | The smoothTime while dragging.                                                                                                                                                            | `0.125`                                                                              |
| **maxSpeed**              | Max transition speed in units per second.                                                                                                                                                 | `Infinity`                                                                           |
| **azimuthRotateSpeed**    | Speed of azimuth (horizontal) rotation.                                                                                                                                                   | `1.0`                                                                                |
| **polarRotateSpeed**      | Speed of polar (vertical) rotation.                                                                                                                                                       | `1.0`                                                                                |
| **dollySpeed**            | Speed of mouse-wheel dollying.                                                                                                                                                            | `1.0`                                                                                |
| **dollyDragInverted**     | `true` to invert direction when dollying or zooming via drag.                                                                                                                             | `false`                                                                              |
| **truckSpeed**            | Speed of drag for truck and pedestal.                                                                                                                                                     | `2.0`                                                                                |
| **dollyToCursor**         | `true` to enable Dolly-in to the mouse cursor coords.                                                                                                                                     | `false`                                                                              |
| **dragToOffset**          | Whether to drag to offset.                                                                                                                                                                | `false`                                                                              |
| **verticalDragToForward** | The same as `.screenSpacePanning` in Three.js's OrbitControls.                                                                                                                            | `false`                                                                              |
| **boundaryFriction**      | Friction ratio of the boundary.                                                                                                                                                           | `0.0`                                                                                |
| **restThreshold**         | Controls how soon the `rest` event fires as the camera slows.                                                                                                                             | `0.01`                                                                               |
| **colliderMeshes**        | An array of Meshes to collide with the camera. Be aware colliderMeshes may decrease performance. The collision test uses 4 raycasters from the camera since the near plane has 4 corners. | `[]`                                                                                 |
| **mouseButtons**          | Configuration of actions on mouse input.                                                                                                                                                  | See [`User input config`](https://cientos.tresjs.org/#user-input-config) for details |
| **touches**               | Configuration of actions on touch.                                                                                                                                                        | See [`User input config`](https://cientos.tresjs.org/#user-input-config) for details |

## User input config

You can easily override the default user input config by defining `mouseButtons` and/or `touches` props that correspond to [`camera-controls` settings](https://github.com/yomotsu/camera-controls?#user-input-config){rel="&#x22;nofollow&#x22;"}. For ease of use, we're re-exporting the `CameraControls` class as `BaseCameraControls` which gives you access to the `ACTION` enum.

```vue
<script lang="ts" setup>
import { BaseCameraControls, CameraControls } from '@tresjs/cientos'
</script>

<template>
  ...
  <CameraControls
    :mouse-buttons="{ left: BaseCameraControls.ACTION.DOLLY }"
    :touches="{ one: BaseCameraControls.ACTION.TOUCH_TRUCK }"
  />
  ...
</template>
```

### Mouse buttons

| Button to assign        | Options                                                        | Default                                                         |
| ----------------------- | -------------------------------------------------------------- | --------------------------------------------------------------- |
| `mouseButtons.left`     | `ROTATE` \| `TRUCK` \| `OFFSET` \| `DOLLY` \| `ZOOM` \| `NONE` | `ROTATE`                                                        |
| `mouseButtons.right`    | `ROTATE` \| `TRUCK` \| `OFFSET` \| `DOLLY` \| `ZOOM` \| `NONE` | `TRUCK`                                                         |
| `mouseButtons.wheel` ¹  | `ROTATE` \| `TRUCK` \| `OFFSET` \| `DOLLY` \| `ZOOM` \| `NONE` | `DOLLY` for Perspective camera, `ZOOM` for Orthographic camera. |
| `mouseButtons.middle` ² | `ROTATE` \| `TRUCK` \| `OFFSET` \| `DOLLY` \| `ZOOM` \| `NONE` | `DOLLY`                                                         |

1. Mouse wheel event for scroll "up/down", on mac "up/down/left/right".
2. Mouse wheel "button" click event.

### Touches

| Fingers to assign | Options                                                                                                                                                                                                                                 | Default                                                                                |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `touches.one`     | `TOUCH_ROTATE` \| `TOUCH_TRUCK` \| `TOUCH_OFFSET` \| `DOLLY` \| `ZOOM` \| `NONE`                                                                                                                                                        | `TOUCH_ROTATE`                                                                         |
| `touches.two`     | `TOUCH_DOLLY_TRUCK` \| `TOUCH_DOLLY_OFFSET` \| `TOUCH_DOLLY_ROTATE` \| `TOUCH_ZOOM_TRUCK` \| `TOUCH_ZOOM_OFFSET` \| `TOUCH_ZOOM_ROTATE` \| `TOUCH_DOLLY` \| `TOUCH_ZOOM` \| `TOUCH_ROTATE` \| `TOUCH_TRUCK` \| `TOUCH_OFFSET` \| `NONE` | `TOUCH_DOLLY_TRUCK` for Perspective camera, `TOUCH_ZOOM_TRUCK` for Othographic camera. |
| `touches.three`   | `TOUCH_DOLLY_TRUCK` \| `TOUCH_DOLLY_OFFSET` \| `TOUCH_DOLLY_ROTATE` \| `TOUCH_ZOOM_TRUCK` \| `TOUCH_ZOOM_OFFSET` \| `TOUCH_ZOOM_ROTATE` \| `TOUCH_ROTATE` \| `TOUCH_TRUCK` \| `TOUCH_OFFSET` \| `NONE`                                  | `TOUCH_TRUCK`                                                                          |

## Events

```vue
<CameraControls @change="onChange" @start="onStart" @end="onEnd" />
```

| Event      | Description                                   |
| :--------- | :-------------------------------------------- |
| **start**  | Dispatched when the control starts to change. |
| **change** | Dispatched when the control changes.          |
| **end**    | Dispatched when the control ends to change.   |


# Controls

:api-list{list-name="control-list"}


# Keyboard Controls

::scene-controls-wrapper
:controls-keyboard-controls
::

`<KeyboardControls />` is a simple keyboard controller for the camera. The camera's movements are bound to:

| Keyboard  | Action        |
| :-------- | :------------ |
| `W` / `↑` | Move forward  |
| `S` / `↓` | Move backward |
| `A` / `←` | Move left     |
| `D` / `→` | Move right    |
| `E`       | Move up       |
| `Q`       | Move down     |

::prose-note
`KeyboardControls` uses `PointerLockControls` under the hood. You can use [PointerLockControls props and events](https://cientos.tresjs.org/pointer-lock-controls#props).
::

## Usage

```vue {3,10}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { KeyboardControls, Box } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera />
    <Box :position-y="0.5" />
    <KeyboardControls />
    <TresGridHelper />
  </TresCanvas>
</template>
```

::prose-warning
Is really important that the Perspective camera is set first in the canvas. Otherwise might break.
::

## Props

| Prop            | Description                                                                         | Default     |
| :-------------- | :---------------------------------------------------------------------------------- | ----------- |
| **moveSpeed**   | Speed movement.                                                                     | 0.2         |
| **makeDefault** | If `true`, the controls will be set as the default controls for the scene.          | `true`      |
| **camera**      | The camera to control.                                                              | `undefined` |
| **domElement**  | The DOM element to listen to.                                                       | `undefined` |
| **selector**    | Accept an id element as string. If set, the new element will be used as the trigger | `undefined` |

## Events

```vue
<KeyboardControls @change="onChange" @is-lock="(state) => isActive(state)" />
```

| Event      | Description                                                        |
| :--------- | :----------------------------------------------------------------- |
| **isLock** | Return `true` if "lock", `false` if "unlock" events are triggered. |
| **change** | Dispatched when the control changes.                               |


# Map Controls

::scene-controls-wrapper
:controls-map-controls
::

[MapControls](https://threejs.org/docs/index.html?q=controls#examples/en/controls/MapControls){rel="&#x22;nofollow&#x22;"} similar to OrbitControls, this control is intended for transforming a camera over a map from bird's eye perspective, but uses a specific preset for mouse/touch interaction and disables screen space panning by default.

## Usage

```vue {7}
<script setup>
import { MapControls } from "@tresjs/cientos"
</script>
<template>
  <TresCanvas clear-color="#82DBC5">
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <MapControls />
    <Box :scale="2">
      <TresMeshToonMaterial color="orange" />
    </Box>
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
    <TresGridHelper />
  </TresCanvas>
</template>
```

::prose-warning
It is really important that the perspective camera is set first in the canvas. Otherwise the scene might break.
::

## Props

| Prop                   | Description                                                                                                                                                                                | Default     |
| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **makeDefault**        | If `true`, the controls will be set as the default controls for the scene.                                                                                                                 | `false`     |
| **camera**             | The camera to control.                                                                                                                                                                     | `undefined` |
| **domElement**         | The dom element to listen to.                                                                                                                                                              | `undefined` |
| **screenSpacePanning** | Defines how the camera's position is translated when panning. If `true`, the camera pans in screen space. Otherwise, the camera pans in the plane orthogonal to the camera's up direction. | `false`     |

::prose-note
All the props of the orbit controls component apply here too.
::


# Orbit Controls

::scene-controls-wrapper
:controls-orbit-controls
::

[OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls){rel="&#x22;nofollow&#x22;"} is a camera controller that allows you to orbit around a target. It's a great way to explore your scene.

## Usage

```vue {7}
<script setup>
import { OrbitControls } from "@tresjs/cientos"
</script>
<template>
  <TresCanvas clear-color="#82DBC5">
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <OrbitControls />
    <Box :scale="2">
      <TresMeshToonMaterial color="orange" />
    </Box>
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
    <TresGridHelper />
  </TresCanvas>
</template>
```

::prose-warning
Is really important that the Perspective camera is set first in the canvas. Otherwise might break.
::

## Props

| Prop                   | Description                                                                                                                                                                                | Default                                                                          |
| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **makeDefault**        | If `true`, the controls will be set as the default controls for the scene.                                                                                                                 | `false`                                                                          |
| **camera**             | The camera to control.                                                                                                                                                                     | `undefined`                                                                      |
| **domElement**         | The dom element to listen to.                                                                                                                                                              | `undefined`                                                                      |
| **target**             | The target to orbit around.                                                                                                                                                                | `undefined`                                                                      |
| **enableDamping**      | If `true`, the controls will use damping (inertia), which can be used to give a sense of weight to the controls.                                                                           | `true`                                                                           |
| **dampingFactor**      | The damping inertia used if `.enableDamping` is set to true.                                                                                                                               | `0.05`                                                                           |
| **autoRotate**         | Set to true to automatically rotate around the target.                                                                                                                                     | `false`                                                                          |
| **autoRotateSpeed**    | How fast to rotate around the target if `.autoRotate` is true.                                                                                                                             | `2`                                                                              |
| **enablePan**          | Whether to enable panning.                                                                                                                                                                 | `true`                                                                           |
| **keyPanSpeed**        | How fast to pan the camera when the keyboard is used. Default is 7.0 pixels per keypress.                                                                                                  | `7.0`                                                                            |
| **keys**               | This object contains references to the keycodes for controlling camera panning. Default is the 4 arrow keys.                                                                               | `{ LEFT: 'ArrowLeft', UP: 'ArrowUp', RIGHT: 'ArrowRight', BOTTOM: 'ArrowDown' }` |
| **maxAzimuthAngle**    | How far you can orbit horizontally, upper limit. If set, the interval [min, max] must be a sub-interval of [- 2 PI, 2 PI], with ( max - min < 2 PI ). Default is Infinity.                 | `Infinity`                                                                       |
| **minAzimuthAngle**    | How far you can orbit horizontally, lower limit. If set, the interval [min, max] must be a sub-interval of [- 2 PI, 2 PI], with ( max - min < 2 PI ). Default is - Infinity.               | `-Infinity`                                                                      |
| **maxPolarAngle**      | How far you can orbit vertically, upper limit. Range is 0 to Math.PI radians, and default is Math.PI.                                                                                      | `Math.PI`                                                                        |
| **minPolarAngle**      | How far you can orbit vertically, lower limit. Range is 0 to Math.PI radians, and default is 0.                                                                                            | `0`                                                                              |
| **minDistance**        | The minimum distance of the camera to the target. Default is 0.                                                                                                                            | `0`                                                                              |
| **maxDistance**        | The maximum distance of the camera to the target. Default is Infinity.                                                                                                                     | `Infinity`                                                                       |
| **minZoom**            | The minimum field of view angle, in radians. Default is 0.                                                                                                                                 | `0`                                                                              |
| **maxZoom**            | The maximum field of view angle, in radians. ( OrthographicCamera only ). Default is Infinity.                                                                                             | `Infinity`                                                                       |
| **touches**            | This object contains references to the touch actions used by the controls.                                                                                                                 | `{ ONE: TOUCH.ROTATE, TWO: TOUCH.DOLLY_PAN }`                                    |
| **mouseButtons**       | This object contains references to the mouse actions used by the controls. LEFT: Rotate around the target, MIDDLE: Zoom the camera, RIGHT: Pan the camera.                                 | `{ LEFT: MOUSE.ROTATE, MIDDLE: MOUSE.DOLLY, RIGHT: MOUSE.PAN }`                  |
| **enableZoom**         | Whether to enable zooming.                                                                                                                                                                 | `true`                                                                           |
| **zoomSpeed**          | How fast to zoom in and out. Default is 1.                                                                                                                                                 | `1`                                                                              |
| **enableRotate**       | Whether to enable rotating.                                                                                                                                                                | `true`                                                                           |
| **rotateSpeed**        | How fast to rotate around the target. Default is 1.                                                                                                                                        | `1`                                                                              |
| **screenSpacePanning** | Defines how the camera's position is translated when panning. If `true`, the camera pans in screen space. Otherwise, the camera pans in the plane orthogonal to the camera's up direction. | `true`                                                                           |

## Events

```vue
<OrbitControls @change="onChange" @start="onStart" @end="onEnd" />
```

| Event      | Description                                   |
| :--------- | :-------------------------------------------- |
| **start**  | Dispatched when the control starts to change. |
| **change** | Dispatched when the control changes.          |
| **end**    | Dispatched when the control ends to change.   |


# PointerLock Controls

::scene-controls-wrapper
:controls-pointer-lock-controls
::

[PointerLockControls](https://threejs.org/docs/index.html?q=pointe#examples/en/controls/PointerLockControls){rel="&#x22;nofollow&#x22;"} is a camera controller that allows you to capture the mouse movement and simulate a first person camera. It is a perfect choice for first person 3D games.

::prose-warning
This control uses the [[](https://cientos.tresjs.org/api/controls/orbit-controls){style="color:#f7f7f7;text-decoration:none"}[`Pointer Lock API`](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API){rel=""nofollow""}]{style="background-color:#222;padding:0.25rem;border-radius:4px;"}, the same rules are applied, for example, you need to interact with the browser to "lock" or start the event.
In addition, you need to wait 1 second between canceling and re-starting the event
::

## Usage

```vue {3,10}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { PointerLockControls, Box } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera />
    <Box :position-y="0.5" />
    <PointerLockControls />
    <TresGridHelper />
  </TresCanvas>
</template>
```

::prose-warning
Is really important that the Perspective camera is set first in the canvas. Otherwise might break.
::

## Props

| Prop            | Description                                                                               | Default     |
| :-------------- | :---------------------------------------------------------------------------------------- | ----------- |
| **makeDefault** | If `true`, the controls will be set as the default controls for the scene.                | `false`     |
| **camera**      | The camera to control.                                                                    | `undefined` |
| **domElement**  | The dom element to listen to.                                                             | `undefined` |
| **selector**    | Accept an id element as string, if it is set, the new element will be used as the trigger | `undefined` |

## Events

```vue
<PointerLockControls @change="onChange" @is-lock="(state) => isActive(state)" />
```

| Event      | Description                                                      |
| :--------- | :--------------------------------------------------------------- |
| **isLock** | Return `true` if "lock", `false` if "unlock" events are trigger. |
| **change** | Dispatched when the control changes.                             |


# Transform Controls

The [Transform Controls](https://threejs.org/docs/#examples/en/controls/TransformControls){rel="&#x22;nofollow&#x22;"} are a set of three gizmos that can be used to translate, rotate and scale objects in the scene. It adapts a similar interaction model of DCC tools like Blender

::scene-controls-wrapper
:controls-transform-controls
::

## Usage

To use the Transform Controls, simply add the `TransformControls` component to your scene. You can pass the `templateRef`of the instance you want to control as a prop.

```vue {7-8}
<script setup>
const boxRef = shallowRef()
</script>
<template>
  <TresCanvas>
    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
    <OrbitControls make-default />
    <TransformControls :object="boxRef" />
    <TresMesh ref="boxRef" :position="[0, 4, 0]" cast-shadow>
      <TresBoxGeometry :args="[1.5, 1.5, 1.5]" />
      <TresMeshToonMaterial color="#4F4F4F" />
    </TresMesh>
  </TresCanvas>
</template>
```

::prose-warning
If you are using other controls [[OrbitControls](https://cientos.tresjs.org/api/controls/orbit-controls){style="color:#f7f7f7;text-decoration:none"}]{style="background-color:#222;padding:0.25rem;border-radius:4px;"} they will interfere with each other when dragging. To avoid this, you can set the `makeDefault` prop to `true` on the **OrbitControls**.
::

## Modes

The Transform Controls can be used in three different modes:

### Translate

![Translate](https://cientos.tresjs.org/cientos/transform-controls-translate.png)

The default mode allows you to move the object around the scene.

```vue
<TransformControls mode="translate" :object="sphereRef" />
```

### Rotate

![Rotate](https://cientos.tresjs.org/cientos/transform-controls-rotate.png)

The rotate mode allows you to rotate the object around the scene.

```vue
<TransformControls mode="rotate" :object="boxRef" />
```

### Scale

![Scale](https://cientos.tresjs.org/cientos/transform-controls-scale.png)

The scale mode allows you to scale the object around the scene.

```vue
<TransformControls mode="scale" :object="sphereRef" />
```

## Props

| Prop                | Description                                                                                                               | Default     |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------ | ----------- |
| **object**          | The instance [Object3D](https://threejs.org/docs/index.html#api/en/core/Object3D){rel="&#x22;nofollow&#x22;"} to control. | `null`      |
| **mode**            | The mode of the controls. Can be `translate`, `rotate` or `scale`.                                                        | `translate` |
| **enabled**         | If `true`, the controls will be enabled.                                                                                  | `true`      |
| **axis**            | The axis to use for the controls. Can be `X`, `Y`, `Z`, `XY`, `YZ`, `XZ`, `XYZ`.                                          | `XYZ`       |
| **space**           | The space to use for the controls. Can be `local` or `world`.                                                             | `local`     |
| **size**            | The size of the controls.                                                                                                 | `1`         |
| **translationSnap** | The distance to snap to when translating. (World units)                                                                   | `null`      |
| **rotationSnap**    | The angle to snap to when rotating. (Radians)                                                                             | `null`      |
| **scaleSnap**       | The scale to snap to when scaling.                                                                                        | `null`      |
| **showX**           | If `true`, the X-axis helper will be shown.                                                                               | `true`      |
| **showY**           | If `true`, the Y-axis helper will be shown.                                                                               | `true`      |
| **showZ**           | If `true`, the Z-axis helper will be shown.                                                                               | `true`      |

## Events

| Event            | Description                                                    |
| :--------------- | :------------------------------------------------------------- |
| **dragging**     | Fired when the user starts or stops dragging the controls.     |
| **change**       | Fired when the user changes the controls.                      |
| **mouseDown**    | Fired when the user clicks on the controls.                    |
| **mouseUp**      | Fired when the user releases the mouse button on the controls. |
| **objectChange** | Fired when the user changes the object.                        |


# useGLTF

::scene-wrapper
:loaders-gltf
::

A composable that allows you to easily load glb/glTF models into your **TresJS** scene.

## Usage

::code-group
```vue [TheModel.vue] {2,5}
<script setup lang="ts">
import { useGLTF } from '@tresjs/cientos'

const path = './blender-cube.glb'
const { state, nodes, materials } = useGLTF(path)
</script>

<template>
  <primitive v-if="state" :object="state?.scene" />
</template>
```

```vue [app.vue]
<script setup lang="ts">
import { OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import TheModel from './TheModel.vue'
</script>

<template>
  <TresCanvas clear-color="#F78B3D">
    <TresPerspectiveCamera :position="[3, 2, 5]" />
    <OrbitControls />
    <TheModel />
    <TresDirectionalLight
      :intensity="2"
      :position="[3, 3, 3]"
    />
    <TresAmbientLight :intensity="1" />
  </TresCanvas>
</template>
```
::

An advantage of using `useGLTF` is that you can pass a `draco` prop to enable [Draco compression](https://threejs.org/docs/index.html?q=drac#examples/en/loaders/DRACOLoader){rel="&#x22;nofollow&#x22;"} for the model. This will reduce the size of the model and improve performance.

```ts
import { useGLTF } from '@tresjs/cientos'

const { state, nodes, materials } = useGLTF('/models/AkuAku.gltf', { draco: true })
```

## Return Values

| Name          | Type                                                    | Description                                 |
| :------------ | ------------------------------------------------------- | ------------------------------------------- |
| **state**     | `Ref<GLTF | null>`                                      | The loaded GLTF, or `null` until it arrives |
| **nodes**     | `ComputedRef<TNodes>`                                   | All nodes in the scene, keyed by name       |
| **materials** | `ComputedRef<TMaterials>`                               | All materials in the scene, keyed by name   |
| **isLoading** | `Ref<boolean>`                                          | Whether the model is currently loading      |
| **error**     | `Ref<unknown>`                                          | Whatever the loader threw, if anything      |
| **progress**  | `{ loaded: number, total: number, percentage: number }` | Progress of the current load                |
| **load**      | `(path: string) => void`                                | Load a different model into the same state  |
| **execute**   | `(delay?: number) => Promise<GLTF>`                     | Re-run the load                             |

## Options

| Name            | Type       | Default                                                     | Description                                                      |
| :-------------- | ---------- | ----------------------------------------------------------- | ---------------------------------------------------------------- |
| **draco**       | `boolean`  | `false`                                                     | Whether to enable Draco compression.                             |
| **decoderPath** | `string`   | `'https://www.gstatic.com/draco/versioned/decoders/1.5.6/'` | Path to the Draco decoder.                                       |
| **traverse**    | `Function` |                                                             | A traverse function applied to the scene upon loading the model. |

## Accessing Nodes and Materials

The composable provides computed properties to easily access nodes and materials in your scene:

```ts
const { nodes, materials } = useGLTF('/model.glb')

// Access a specific node
const mesh = nodes.value.MeshName

// Access a specific material
const material = materials.value.MaterialName
```

This makes it easier to manipulate specific parts of your model or apply materials programmatically.

## Typing Nodes and Materials

The keys of `nodes` and `materials` come from the file, so by default both are a loose record and
`nodes.value.Body` is an `any`. Pass the shape of your model as generics to get them typed:

```ts
import type { Mesh, MeshStandardMaterial } from 'three'
import { useGLTF } from '@tresjs/cientos'

interface ModelNodes { Body: Mesh }
interface ModelMaterials { Skin: MeshStandardMaterial }

const { nodes, materials } = useGLTF<ModelNodes, ModelMaterials>('/models/robot.glb')

nodes.value.Body.geometry // Mesh, not any
```

::prose-note
These interfaces are a claim about the model, not a proof: nothing checks them against the file at
runtime. `tres gltf` reads them off the model and writes them for you, which is the only version
of this that cannot drift.
::

## Generating a Component Instead

For a whole model, writing an element per node by hand does not scale. The
[TresJS CLI](https://docs.tresjs.org/cli/gltf){rel="&#x22;nofollow&#x22;"} generates that component from the model itself,
typed, with a slot for every node so your overrides survive the next export:

```bash
npx @tresjs/cli gltf public/models/robot.glb
# ✔ src/models/Robot.gen.vue
#   3 slots: Head, Body, Base
```

::read-more{to="https://cientos.tresjs.org/getting-started/loading-models"}
The three ways to load a model, and when to reach for each one.
::


# GLTFModel

::scene-wrapper
:loaders-gltf
::

The `GLTFModel` component is a wrapper around [`useGLTF`](https://cientos.tresjs.org/use-gltf) composable and accepts the same options as props.

## Usage

::code-group
```vue [TheModel.vue] {2,8}
<script setup lang="ts">
import { GLTFModel } from '@tresjs/cientos'

const path = './blender-cube.glb'
</script>

<template>
  <GLTFModel :path="path" />
</template>
```

```vue [app.vue]
<script setup lang="ts">
import { OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import TheModel from './TheModel.vue'
</script>

<template>
  <TresCanvas clear-color="#F78B3D">
    <TresPerspectiveCamera :position="[3, 2, 5]" />
    <OrbitControls />
    <TheModel />
    <TresDirectionalLight
      :intensity="2"
      :position="[3, 3, 3]"
    />
    <TresAmbientLight :intensity="1" />
  </TresCanvas>
</template>
```
::

## Model reference

The component exposes the loaded GLTF as `instance`, so a template ref gets you the parsed model:

```vue
<script setup lang="ts">
import { GLTFModel } from '@tresjs/cientos'
import { ref, watch } from 'vue'

const modelRef = ref<InstanceType<typeof GLTFModel>>()

// `instance` is null until the file lands, so watch it rather than the ref
watch(() => modelRef.value?.instance, (gltf) => {
  gltf?.scene.position.set(0, 0, 0)
})
</script>

<template>
  <GLTFModel
    ref="modelRef"
    path="https://raw.githubusercontent.com/Tresjs/assets/main/models/gltf/blender-cube.glb"
  />
</template>
```

## Props

| Prop            | Description                                                                                                                                       | Default                                                     |
| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| `path`          | Path to the model file. **Required**.                                                                                                             | `undefined`                                                 |
| `draco`         | Enable [Draco compression](https://threejs.org/docs/index.html?q=drac#examples/en/loaders/DRACOLoader){rel="&#x22;nofollow&#x22;"} for the model. | `false`                                                     |
| `decoderPath`   | Path to a Draco decoder.                                                                                                                          | `'https://www.gstatic.com/draco/versioned/decoders/1.4.1/'` |
| `castShadow`    | Apply `cast-shadow` to all meshes inside your model.                                                                                              | `false`                                                     |
| `receiveShadow` | Apply `receive-shadow` to all meshes inside your model.                                                                                           | `false`                                                     |

::prose-note
`path` is not reactive: the component reads it once on setup. Use
[`useGLTF`](https://cientos.tresjs.org/use-gltf) with a `ref` path if you need to swap models at runtime.
::

## When to reach for something else

`GLTFModel` renders the model's scene graph as-is, which means there is no element to hang a
material swap, a click handler or a `v-if` on. When you need that, use
[`useGLTF`](https://cientos.tresjs.org/use-gltf) to compose the parts yourself, or let the
[TresJS CLI](https://docs.tresjs.org/cli/gltf){rel="&#x22;nofollow&#x22;"} generate a typed component with a slot per node:

```bash
npx @tresjs/cli gltf public/models/robot.glb
```

::read-more{to="https://cientos.tresjs.org/getting-started/loading-models"}
The three ways to load a model, and when to reach for each one.
::


# useFBX

::scene-wrapper
:loaders-fbx
::

A composable that allows you to easily load FBX models into your **TresJS** scene.

## Usage

::code-group
```vue [TheModel.vue] {2,6}
<script setup lang="ts">
import { useFBX } from '@tresjs/cientos'

const path = 'https://raw.githubusercontent.com/'
  + 'Tresjs/assets/main/models/fbx/low-poly-truck/Jeep_done.fbx'
const { state, nodes, materials } = useFBX(path)
</script>

<template>
  <primitive v-if="state" :object="state" :scale="0.025" />
</template>
```

```vue [app.vue]
<script setup lang="ts">
import { OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import TheModel from './TheModel.vue'
</script>

<template>
  <TresCanvas clear-color="#1F90FF">
    <TresPerspectiveCamera :position="[11, 11, 11]" />
    <OrbitControls />
    <TheModel />
    <TresDirectionalLight
      :intensity="2"
      :position="[3, 3, 3]"
    />
    <TresAmbientLight :intensity="1" />
  </TresCanvas>
</template>
```
::

## Return Values

| Name          | Type                  | Description                                           |
| :------------ | --------------------- | ----------------------------------------------------- |
| **state**     | `Group`               | The loaded FBX model state                            |
| **nodes**     | `object`              | Computed object containing all nodes in the scene     |
| **materials** | `object`              | Computed object containing all materials in the scene |
| **isLoading** | `boolean`             | Whether the model is currently loading                |
| **execute**   | `() => Promise<void>` | Function to reload the model                          |

## Options

| Name         | Type       | Description                                                      |
| :----------- | ---------- | ---------------------------------------------------------------- |
| **traverse** | `Function` | A traverse function applied to the scene upon loading the model. |

## Accessing Nodes and Materials

The composable provides computed properties to easily access nodes and materials in your scene:

```ts
const { nodes, materials } = useFBX('/model.fbx')

// Access a specific node
const mesh = nodes.value.MeshName

// Access a specific material
const material = materials.value.MaterialName
```

This makes it easier to manipulate specific parts of your model or apply materials programmatically.


# FBXModel

::scene-wrapper
:loaders-fbx
::

The `FBXModel` component is a wrapper around [`useFBX`](https://cientos.tresjs.org/use-fbx) composable and accepts the same options as props.

## Usage

::code-group
```vue [TheModel.vue] {2,8}
<script setup lang="ts">
import { FBXModel } from '@tresjs/cientos'

const path = './Jeep_done.fbx'
</script>

<template>
  <FBXModel :path="path" />
</template>
```

```vue [app.vue]
<script setup lang="ts">
import { OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import TheModel from './TheModel.vue'
</script>

<template>
  <TresCanvas clear-color="#F78B3D">
    <TresPerspectiveCamera :position="[3, 2, 5]" />
    <OrbitControls />
    <TheModel />
    <TresDirectionalLight
      :intensity="2"
      :position="[3, 3, 3]"
    />
    <TresAmbientLight :intensity="1" />
  </TresCanvas>
</template>
```
::

## Model reference

You can access the model reference by passing a `ref` to the `FBXModel` component and then using it to get the object.

```vue
<script setup lang="ts">
import type { TresObject } from '@tresjs/core'
import { FBXModel } from '@tresjs/cientos'

const modelRef = shallowRef<TresObject>()

watch(modelRef, (model) => {
  // Do something with the model
  model.position.set(0, 0, 0)
})
</script>

<template>
  <FBXModel
    ref="modelRef"
    path="https://raw.githubusercontent.com/Tresjs/assets/main/models/fbx/low-poly-truck/Jeep_done.fbx"
  />
</template>
```

## Props

| Prop            | Description                                             | Default     |
| :-------------- | :------------------------------------------------------ | ----------- |
| `path`          | Path to the model file.                                 | `undefined` |
| `castShadow`    | Apply `cast-shadow` to all meshes inside your model.    | `false`     |
| `receiveShadow` | Apply `receive-shadow` to all meshes inside your model. | `false`     |


# useTexture

::scene-wrapper
:loaders-use-texture
::

A composable that allows you to load textures using the [Three.js texture loader](https://threejs.org/docs/#api/en/loaders/TextureLoader){rel="&#x22;nofollow&#x22;"} into your **TresJS** scene.

## Usage

```vue {2,4,10}
<script setup lang="ts">
import { useTexture } from '@tresjs/cientos'

const { state: texture, isLoading, error } = useTexture(path)
</script>

<template>
  <TresMesh>
    <TresSphereGeometry />
    <TresMeshStandardMaterial :map="texture" />
  </TresMesh>
</template>
```

## Options

| Name        | Type                   | Default     | Description                                 |
| :---------- | ---------------------- | ----------- | ------------------------------------------- |
| **path**    | `string`               | `undefined` | The path to the texture.                    |
| **manager** | `THREE.LoadingManager` | `undefined` | The loading manager to use for the texture. |

## Return Values

| Name        | Type             | Description                     |
| :---------- | :--------------- | :------------------------------ |
| `state`     | `Texture | null` | The loaded texture              |
| `isLoading` | `boolean`        | Whether the texture is loading  |
| `error`     | `string | null`  | Error message if loading failed |

## Component Usage

You can also use the `UseTexture` component directly in your template:

```vue {2,16-21,26}
<script setup lang="ts">
import { UseTexture } from '@tresjs/cientos'

const path = 'https://raw.githubusercontent.com/Tresjs/assets/main/textures/black-rock/Rock035_2K_Color.jpg'

const handleLoaded = (texture: Texture) => {
  console.log('Loaded texture', texture)
}

const handleError = (error: unknown) => {
  console.error('error', error)
}
</script>

<template>
  <UseTexture
    v-slot="{ state: texture }"
    :path="path"
    @loaded="handleLoaded"
    @error="handleError"
  >
    <TresMesh>
      <TresSphereGeometry />
      <TresMeshStandardMaterial :map="texture" />
    </TresMesh>
  </UseTexture>
</template>
```


# useTextures

::scene-wrapper
:loaders-use-textures
::

A composable that allows you to load multiple textures at once using the [Three.js texture loader](https://threejs.org/docs/#api/en/loaders/TextureLoader){rel="&#x22;nofollow&#x22;"} into your **TresJS** scene.

## Usage

```vue {2,12,19-21}
<script setup lang="ts">
import { useTextures } from '@tresjs/cientos'

// Define an array of texture paths
const texturePaths = [
  '/textures/color.jpg',
  '/textures/normal.jpg',
  '/textures/roughness.jpg'
]

// Load all textures at once
const { textures, isLoading, error } = useTextures(texturePaths)
</script>

<template>
  <TresMesh>
    <TresSphereGeometry />
    <TresMeshStandardMaterial
      :map="textures[0]"
      :normal-map="textures[1]"
      :roughness-map="textures[2]"
    />
  </TresMesh>
</template>
```

## PBR Textures Example

Here's a more advanced example showing how to load and apply PBR (Physically Based Rendering) textures to a material:

```vue [PBRTextures.vue]
<script setup lang="ts">
import { TresCanvas, vLightHelper } from '@tresjs/core'
import { Environment, OrbitControls, useGLTF, useTextures } from '@tresjs/cientos'
import { MeshStandardMaterial } from 'three'

// Load the 3D model
const { state: model } = useGLTF('/blender-cube-draco.glb', { draco: true })
const cube = computed(() => model.value?.nodes?.BlenderCube)
const material = computed(() => model.value?.materials?.Material)

// Define texture paths
const texturePaths = [
  '/textures/Metal053C_4K-JPG/Metal053C_4K-JPG_Color.jpg',
  '/textures/Metal053C_4K-JPG/Metal053C_4K-JPG_NormalGL.jpg',
  '/textures/Metal053C_4K-JPG/Metal053C_4K-JPG_Roughness.jpg',
  '/textures/Metal053C_4K-JPG/Metal053C_4K-JPG_Metalness.jpg',
  '/textures/Metal053C_4K-JPG/Metal053C_4K-JPG_Displacement.jpg'
]

// Load all PBR textures at once
const { textures, isLoading, error } = useTextures(texturePaths)

// Apply textures to material when loaded
watch([material, textures], ([modelMaterial, textures]) => {
  if (modelMaterial && textures && textures.length === texturePaths.length) {
    // Cast to MeshStandardMaterial to access PBR properties
    const pbrMaterial = modelMaterial as MeshStandardMaterial

    // Apply textures
    pbrMaterial.map = textures[0]
    pbrMaterial.normalMap = textures[1]
    pbrMaterial.roughnessMap = textures[2]
    pbrMaterial.metalnessMap = textures[3]
    pbrMaterial.displacementMap = textures[4]

    // Set material properties
    pbrMaterial.displacementScale = 0
    pbrMaterial.metalness = 0.8
    pbrMaterial.roughness = 0.2
  }
})

// Handle loading state and errors
watch(isLoading, (_loading) => {
  // Handle loading state
})

watch(error, (errs) => {
  if (errs) {
    console.error('Error loading textures:', errs)
  }
})
</script>

<template>
  <TresCanvas clear-color="#4f4f4f">
    <Suspense>
      <Environment preset="studio" background :blur="1" />
    </Suspense>
    <TresPerspectiveCamera :position="[8, 8, 8]" />
    <OrbitControls />
    <TresGridHelper />
    <TresAmbientLight :intensity="2" />
    <TresDirectionalLight v-light-helper :position="[5, 5, 5]" :intensity="0.5" color="#ff0000" />
    <TresDirectionalLight v-light-helper :position="[-5, 2, 2]" :intensity="0.5" color="#0000ff" />
    <TresGroup position-y="2">
      <primitive v-if="cube" :object="cube" />
    </TresGroup>
  </TresCanvas>
</template>
```

## API

### Parameters

| Name      | Type       | Default     | Description                     |
| :-------- | ---------- | ----------- | ------------------------------- |
| **paths** | `string[]` | `undefined` | Array of paths to the textures. |

### Returns

| Name          | Type             | Description                                     |
| :------------ | ---------------- | ----------------------------------------------- |
| **textures**  | `Texture[]`      | Array of loaded textures.                       |
| **isLoading** | `boolean`        | Whether any textures are still loading.         |
| **error**     | `Error[] | null` | Array of errors if any occurred during loading. |

## Benefits

- **Simplified API**: Load multiple textures with a single function call
- **Consolidated loading state**: Track loading state for all textures at once
- **Unified error handling**: Collect and report errors from all texture loads
- **Type safety**: Proper TypeScript typing throughout the implementation


# useSVG

::scene-wrapper
:loaders-use-svg
::

Load and display SVG elements in your **TresJS** scene. This guide covers both the `useSVG` composable for advanced use cases and the `SVG` component for simple declarative rendering.

## useSVG Composable

The `useSVG` composable provides direct access to processed SVG layers, giving you full control over the resulting geometries and materials.

### Usage

::code-group
```vue [TheModel.vue] {2,5-8}
<script setup lang="ts">
import { useSVG } from '@tresjs/cientos'

const svgPath = './logo.svg'
const { state, layers, isLoading, dispose } = useSVG(svgPath, {
  skipFills: false,
  fillMaterial: { transparent: true, opacity: 0.8 }
})
</script>

<template>
  <TresGroup v-if="!isLoading">
    <TresMesh
      v-for="(layer, index) in layers"
      :key="`layer-${index}`"
      :geometry="layer.geometry"
      :render-order="index"
    >
      <TresMeshBasicMaterial v-bind="layer.material" />
    </TresMesh>
  </TresGroup>
</template>
```

```vue [app.vue]
<script setup lang="ts">
import { OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import TheModel from './TheModel.vue'
</script>

<template>
  <TresCanvas clear-color="#333">
    <TresPerspectiveCamera :position="[0, 2, 10]" />
    <OrbitControls />
    <TheModel />
    <TresAmbientLight />
    <TresDirectionalLight />
  </TresCanvas>
</template>
```
::

The `useSVG` composable provides direct access to processed SVG layers, giving you full control over how they're rendered. This is particularly useful when you need to:

- Manually control layer rendering
- Apply custom animations to individual layers
- Access geometry data programmatically
- Implement complex material logic

### SVG Data Sources

The composable accepts both file paths and inline SVG strings:

```ts
import { useSVG } from '@tresjs/cientos'

// From file
const { layers } = useSVG('/path/to/file.svg')

// Inline SVG string
const svgString = `<svg viewBox="0 0 100 100">
  <circle cx="50" cy="50" r="40" fill="red" />
</svg>`
const { layers } = useSVG(svgString)
```

### Return Values

| Name          | Type         | Description                                          |
| :------------ | ------------ | ---------------------------------------------------- |
| **state**     | `SVGResult`  | The loaded SVG state from SVGLoader                  |
| **layers**    | `SVGLayer[]` | Computed array of processed geometries and materials |
| **isLoading** | `boolean`    | Whether the SVG is currently loading                 |
| **dispose**   | `() => void` | Function to dispose of all geometries                |

### Options

| Name               | Type                                          | Default         | Description                               |
| :----------------- | --------------------------------------------- | --------------- | ----------------------------------------- |
| **skipStrokes**    | `boolean`                                     | `false`         | Whether to skip rendering strokes         |
| **skipFills**      | `boolean`                                     | `false`         | Whether to skip rendering fills           |
| **fillMaterial**   | `MeshBasicMaterialParameters`                 | `{}`            | Material properties for fill layers       |
| **strokeMaterial** | `MeshBasicMaterialParameters`                 | `{}`            | Material properties for stroke layers     |
| **depth**          | `'renderOrder' | 'flat' | 'offsetZ' | number` | `'renderOrder'` | How layers should be rendered in 3D space |

### Working with Layers

The `layers` computed property returns an array of processed SVG elements, each containing:

```ts
interface SVGLayer {
  geometry: BufferGeometry // Three.js geometry for the layer
  material: MeshBasicMaterialParameters // Material properties
  isStroke: boolean // Whether this layer is a stroke or fill
}
```

#### Accessing Individual Layers

```vue {2,4}
<script setup lang="ts">
import { useSVG } from '@tresjs/cientos'

const { layers } = useSVG('/complex-icon.svg')

// Apply different materials based on layer type
const getFillColor = (layer: SVGLayer, index: number) => {
  return layer.isStroke ? '#000000' : `hsl(${index * 30}, 70%, 50%)`
}
</script>

<template>
  <TresGroup>
    <TresMesh
      v-for="(layer, index) in layers"
      :key="index"
      :geometry="layer.geometry"
    >
      <TresMeshBasicMaterial
        v-bind="layer.material"
        :color="getFillColor(layer, index)"
      />
    </TresMesh>
  </TresGroup>
</template>
```

### Depth Handling

The `depth` option controls how SVG layers are rendered in 3D space. It accepts the following values:

#### `'renderOrder'` (Default)

**Use case: Lone SVGs or applications that don't rely on stacked SVGs**

This is the default `depth` option.

This value sets the materials' `depthWrite` to `false` and increments the mesh layers [`renderOrder`](https://threejs.org/docs/?q=mesh#api/en/core/Object3D.renderOrder){rel="&#x22;nofollow&#x22;"}. This makes the SVG layers render dependably regardless of perspective.

**Disadvantage**: Scene objects may render out of order.

SVG layers with higher [`renderOrder`](https://threejs.org/docs/?q=mesh#api/en/core/Object3D.renderOrder){rel="&#x22;nofollow&#x22;"} will be rendered after (i.e., sometimes "on top of") other objects in the scene graph with a lower [`renderOrder`](https://threejs.org/docs/?q=mesh#api/en/core/Object3D.renderOrder){rel="&#x22;nofollow&#x22;"}. Depending on their settings, those other objects may render behind the SVG, even if they are closer to the camera.

```ts
const { layers } = useSVG('/icon.svg', { depth: 'renderOrder' })
```

#### flat

**Use case: simple SVGs**

This option sets the materials [`depthWrite`](https://threejs.org/docs/?q=mesh#api/en/materials/Material.depthWrite){rel="&#x22;nofollow&#x22;"} to `false`.

**Disadvantage**: SVG layers may render out of order.

Overlapping layers in an SVG may be drawn out of order, depending on viewing perspective.

```ts
const { layers } = useSVG('/icon.svg', { depth: 'flat' })
```

#### offsetZ

**Use case: unscaled SVGs seen from the front**

When this value is passed, the result is a 3D "stack" of mesh layers. A small space is added between each mesh layer in the "stack".

**Disadvantage**: "Bottom" of the "stack" is visible; layers may z-fight.

When seen from behind, the "bottom" of the mesh layer "stack" is visible. The space between the layers may be noticeable depending on viewing perspective and scale. The layers may [z-fight](https://en.wikipedia.org/wiki/Z-fighting){rel="&#x22;nofollow&#x22;"}, particularly if the SVG is scaled down.

```ts
const { layers } = useSVG('/icon.svg', { depth: 'offsetZ' })
```

#### `number`

**Use case: SVGs seen from the front**

This is the same as `'offsetZ'` but allows you to specify how much space is added between each layer, in order to eliminate [z-fighting](https://en.wikipedia.org/wiki/Z-fighting){rel="&#x22;nofollow&#x22;"}. For most use cases, this should be a value greater than 0.025 and less than 1.

**Disadvantage**: "Bottom" of the "stack" is visible.

```ts
const { layers } = useSVG('/icon.svg', { depth: 0.1 })
```

### Memory Management

Always dispose of geometries when the component unmounts:

```vue
<script setup lang="ts">
import { useSVG } from '@tresjs/cientos'
import { onUnmounted } from 'vue'

const { dispose } = useSVG('/icon.svg')

onUnmounted(() => {
  dispose()
})
</script>
```

### Advanced Usage

#### Conditional Layer Rendering

```vue
<script setup lang="ts">
import { useSVG } from '@tresjs/cientos'
import { computed } from 'vue'

const showDetails = ref(true)
const { layers } = useSVG('/detailed-icon.svg')

const visibleLayers = computed(() =>
  showDetails.value
    ? layers.value
    : layers.value.filter(layer => !layer.isStroke)
)
</script>

<template>
  <TresGroup>
    <TresMesh
      v-for="(layer, index) in visibleLayers"
      :key="index"
      :geometry="layer.geometry"
    >
      <TresMeshBasicMaterial v-bind="layer.material" />
    </TresMesh>
  </TresGroup>
</template>
```

#### Material Customization per Layer

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

const { layers } = useSVG('/logo.svg', {
  fillMaterial: {
    transparent: true,
    opacity: 0.9
  },
  strokeMaterial: {
    transparent: true,
    opacity: 1.0,
    color: '#000000'
  }
})
</script>

<template>
  <TresGroup>
    <TresMesh
      v-for="(layer, index) in layers"
      :key="index"
      :geometry="layer.geometry"
    >
      <TresMeshBasicMaterial
        v-bind="layer.material"
        :wireframe="layer.isStroke"
      />
    </TresMesh>
  </TresGroup>
</template>
```

## UseSVG Component

For simple, declarative SVG rendering without the need for programmatic control, you can use the `UseSVG` component:

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

<template>
  <TresGroup :scale="0.01" :position="[-2.1, 1, 0]">
    <UseSVG
      src="/path/to/logo.svg"
      :skip-fills="false"
      :fill-material="{ transparent: true,
                        opacity: 0.8 }"
      depth="renderOrder"
    />
  </TresGroup>
</template>
```

### Props

| Prop                | Type                                          | Description                                                                                            | Default       |
| :------------------ | --------------------------------------------- | :----------------------------------------------------------------------------------------------------- | ------------- |
| **src**             | `string`                                      | Either a path to an SVG *or* an SVG string                                                             |               |
| **skipStrokes**     | `boolean`                                     | If `true`, the SVG strokes will not be rendered.                                                       | `false`       |
| **skipFills**       | `boolean`                                     | If `true`, the SVG fills will not be rendered.                                                         | `false`       |
| **strokeMaterial**  | `MeshBasicMaterialParameters`                 | Props to assign to the stroke materials of the resulting meshes.                                       | `undefined`   |
| **fillMaterial**    | `MeshBasicMaterialParameters`                 | Props to assign to the fill materials of the resulting meshes.                                         | `undefined`   |
| **strokeMeshProps** | `TresOptions`                                 | Props to assign to the resulting stroke meshes.                                                        | `undefined`   |
| **fillMeshProps**   | `TresOptions`                                 | Props to assign to the resulting fill meshes.                                                          | `undefined`   |
| **depth**           | `'renderOrder' | 'flat' | 'offsetZ' | number` | Specify how SVG layers are to be rendered. ([See "Depth"](https://cientos.tresjs.org/#depth-handling)) | `renderOrder` |

## Troubleshooting

::alert{type="warning"}
This is not a general-purpose SVG renderer. Many SVG features are unsupported.
::

Here are some things to try if you run into problems:

### Error: "XML Parsing Error: unclosed token"

- In the SVG source, convert hex colors to rgb, e.g., convert `#ff0000` to `rgb(255, 0, 0)`.

### Parts of the SVG render in the wrong order or disappear, depending on viewing angle

- In your `useSVG` options, [change the `depth` option](https://cientos.tresjs.org/#depth-handling).
- In the SVG source, use `fill="none"` rather than `fill-opacity="0"`.

### Parts of the SVG ["z-fight"](https://en.wikipedia.org/wiki/Z-fighting){rel="&#x22;nofollow&#x22;"}

- In your `useSVG` options, [change the `depth` option](https://cientos.tresjs.org/#depth-handling).
- Increase the distance between the SVG and other on-screen elements.

### The SVG is not visible

- If importing an SVG, make sure the path is correct – check the console for loading errors.
- Try scaling the SVG down, e.g., wrap it in a `TresGroup` with `:scale="0.01"`.
- Try moving the SVG up (+y), e.g., `:position="[0,2,0]"`.
- Check that `layers.length > 0` before rendering.

### Performance issues with many layers

- Use the `dispose()` function when components unmount to clean up geometries.
- Consider using `skipStrokes` or `skipFills` to reduce the number of rendered layers.
- For complex SVGs with many layers, consider simplifying the SVG source.

## When to Use `useSVG` vs `SVG` Component

**Use `useSVG` when you need:**

- Direct access to individual SVG layers
- Custom rendering logic
- Layer-specific animations
- Programmatic geometry manipulation
- Advanced material customization per layer

**Use the `SVG` component when you need:**

- Simple, declarative SVG rendering
- Quick prototyping
- Standard SVG display without custom logic
- Less code and setup


# Loaders

:api-list{list-name="loaders-list"}


# useProgress

A composable to convenience wrap `THREE.DefaultLoadingManager` and returns the progress of the loading assets into the scene.

This comes handy to show an HTML loading bar or a spinner while the assets are being loaded.

## Usage

```ts
import { useProgress } from '@tresjs/cientos'

const { hasFinishLoading, progress, items } = await useProgress()
```

Then you can use the `progress` value to show a loading bar or a spinner:

```vue
<template>
  <Transition
    name="fade-overlay"
    enter-active-class="opacity-1 transition-opacity duration-200"
    leave-active-class="opacity-0 transition-opacity duration-200"
  >
    <div
      v-show="!hasFinishLoading"
      class="absolute bg-grey-600 t-0 l-0 w-full h-full z-20 flex justify-center items-center text-black font-mono"
    >
      <div class="w-200px">
        Loading... {{ progress }} %
        <i class="i-ic-twotone-catching-pokemon animate-rotate-in"></i>
      </div>
    </div>
  </Transition>
  <TresCanvas preset="realistic">
    <TresPerspectiveCamera :position="[11, 11, 11]" />
    <OrbitControls />
    <Suspense>
      <Environment
        background
        :files="environmentFiles"
        path="https://raw.githubusercontent.com/Tresjs/assets/main/textures/environmentMap"
      />
    </Suspense>
  </TresCanvas>
</template>
```

::alert{type="warning"}
This component use top level await. Please check the [Suspense API](https://vuejs.org/guide/built-ins/suspense.html#suspense){rel=""nofollow""} for more info
::

## Return Values

| Name               | Type      | Description                              |
| :----------------- | :-------- | :--------------------------------------- |
| `hasFinishLoading` | `boolean` | Whether all items have finished loading  |
| `progress`         | `number`  | Loading progress as percentage (0-100)   |
| `items`            | `Array`   | Array of loading items with their status |

::prose-warning
This component use top level await it needs to be wrapped on a [`Suspense`](https://vuejs.org/guide/built-ins/suspense.html#suspense){rel=""nofollow""}. Please check the [`Suspense API`](https://vuejs.org/guide/built-ins/suspense.html#suspense){rel=""nofollow""} for more info
::


# useVideoTexture

::scene-wrapper
:loaders-use-video-texture
::

A composable to easily use videos as textures in your meshes.

This composable is based on the Drei [useVideoTexture](https://github.com/pmndrs/drei/tree/master#usevideotexture){rel="&#x22;nofollow&#x22;"}

## Usage

::code-group
```vue [app.vue]
<script setup lang="ts">
import { OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import TheModel from './TheModel.vue'
</script>

<template>
  <TresCanvas clear-color="#333">
    <TresPerspectiveCamera
      :position="[0, 5, 9]"
      :look-at="[0, 1, 0]"
    />
    <OrbitControls />
    <Suspense>
      <TheModel />
    </Suspense>
    <TresGridHelper />
    <TresAmbientLight />
  </TresCanvas>
</template>
```

```vue [TheVideoTexture.vue] {3,8,13}
<script setup lang="ts">
import { ref } from 'vue'
import { Sphere, useVideoTexture } from '@tresjs/cientos'

const videoPath = 'https://raw.githubusercontent.com/'
  + 'Tresjs/assets/main/textures/video-textures/useVideoTexture.mp4'
const texture = ref()
texture.value = await useVideoTexture(videoPath, { loop: false })
</script>

<template>
   <Sphere :position="[0, 2, 0]">
      <TresMeshBasicMaterial :map="texture" />
    </Sphere>
</template>
```
::

## Props

| Prop          | Description                                                              | Default          |
| :------------ | :----------------------------------------------------------------------- | ---------------- |
| `src`         | Path to the video.                                                       | `undefined`      |
| `unsuspend`   | Path to the model file.                                                  | `loadedmetadata` |
| `crossOrigin` | Whether to use CORS to fetch the related video.                          | `Anonymous`      |
| `muted`       | Whether to set the audio silenced.                                       | true             |
| `loop`        | Automatically seek back to the start upon reaching the end of the video. | true             |
| `start`       | To play to the video once loaded or not.                                 | true             |
| `playsInline` | To be play the video inline or not.                                      | true             |

- Any other attribute for a `<video>` tag is accepted and will automatically set


# Custom Shader Material

::scene-wrapper
:materials-custom-shader-material
::

The `cientos` package provides `<TresCustomShaderMaterial />` component which is a wrapper around the [`three-custom-shader-material`](https://github.com/FarazzShaikh/THREE-CustomShaderMaterial){rel="&#x22;nofollow&#x22;"&#x7D; class. As states in the repo, it &#x2A;"lets you extend Three.js' material library with your own Vertex and Fragment shaders"*.

## Usage

```vue {2,13-27}
<script setup lang="ts">
import { TresCustomShaderMaterial } from '@tresjs/cientos'
import { shallowRef } from 'vue'

const customShaderMaterialRef = shallowRef()
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <TresMesh>
      <TresBoxGeometry />
      <TresCustomShaderMaterial
        ref="customShaderMaterialRef"
        :vertex-shader="vertexShader"
        :fragment-shader="fragmentShader"
        :uniforms="{
          u_time: { value: 0 },
          u_color: { value: new THREE.Color(0.2, 0.0, 0.1) },
          u_resolution: { value: new THREE.Vector2() }
        }"
        :transparent="true"
        :side="THREE.DoubleSide"
        base-material="MeshLambertMaterial"
        silent
        :map="texture"
        :color="0xff0000"
      />
    </TresMesh>
    <TresAmbientLight />
  </TresCanvas>
</template>
```

## Props

Being a wrapper around the `CustomShaderMaterial` class, the `<TresCustomShaderMaterial />` component accepts all the props that the class does. You can find the full list of props in the [official repo](https://github.com/FarazzShaikh/THREE-CustomShaderMaterial){rel="&#x22;nofollow&#x22;"}.


# Mesh Glass Material

::scene-wrapper
:materials-glass-material
::

The `cientos` package provides a new`<MeshGlassMaterial />` component that makes a geometry look like glass. This is achieved by re-defining the `MeshPhysicalMaterial`.

## Usage

### You can use it like you normally do with TresJs

```vue {2,10}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { MeshGlassMaterial } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" :look-at="[0, 0, 0]" />
    <TresMesh>
      <TresTorusGeometry />
      <MeshGlassMaterial />
    </TresMesh>
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
  </TresCanvas>
</template>
```

## Props

No props are required. The component extends `THREE.MeshPhysicalMaterial` and accepts all the same props plus additional reflection-specific properties.

### You can also replace the material of an existing mesh like this:

```vue {4,6-15,20}
<script setup lang="ts">
import { ref, shallowRef, watch } from 'vue'
import { TresCanvas } from '@tresjs/core'
import { MeshGlassMaterial, Box } from '@tresjs/cientos'

const glassMaterialRef = shallowRef()
const boxRef = shallowRef()

watch(glassMaterialRef, value => {
  // For good practice we dispose the old material
  boxRef.value.instance.material.dispose()

  // We assign the new MeshGlassMaterialClass
  boxRef.value.instance.material = value.MeshGlassMaterialClass
})
</script>
<template>
  <TresMesh>
    <TresTorusGeometry />
    <MeshGlassMaterial ref="glassMaterialRef" />
  </TresMesh>
  <!-- Mesh to be replaced -->
  <TresMesh ref="boxRef">
    <TresBoxGeometry />
    <MeshBasicMaterial  />
  </TresMesh>
</template>
```

## Tips

- For more fine tuning effects you can provide an environment map texture as an envMap and play with the intensity to achieve a more realistic effect
- Another good option is to provide a normal texture as clearcoatNormalMap to add different results


# Holographic Material

::scene-controls-wrapper
:materials-holographic-material
::

## A simple to use holographic material for TresJS

Dive into a world of mesmerizing holographic wonders with the HolographicMaterial for vanilla Three.js. This enchanting Three.js material brings your virtual reality experiences to life, infusing them with a burst of vibrant colors, dynamic scanlines, and a touch of futuristic brilliance.

While this material operates independently of any post-processing, it achieves an enhanced visual appeal when coupled with bloom effects. The utilization of bloom proves particularly effective in rendering a captivating glow effect, especially in areas where overexposure is prevalent.

::prose-note
This component ports Anderson Mancini's threejs-vanilla-holographic-material to TresJS. All credit goes to him.
::

## Usage

```vue {3,10}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { HolographicMaterial, Sphere } from '@tresjs/cientos'

</script>
<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" :look-at=[0,0,0] />
    <Sphere :scale="0.5">
      <HolographicMaterial />
    </Sphere>
    <TresAmbientLight />
  </TresCanvas>
</template>
```

## Props

| Prop                   | Description                                                   | Type                                                | default     |
| :--------------------- | :------------------------------------------------------------ | --------------------------------------------------- | ----------- |
| **fresnelAmount**      | Value of the Fresnel effect. Ranges from 0.0 to 1.0.          | `Number`                                            | `0.45`      |
| **fresnelOpacity**     | Opacity of the Fresnel effect. Ranges from 0.0 to 1.0.        | `Number`                                            | `1.0`       |
| **scanlineSize**       | Size of the scanlines. Ranges from 1 to 15.                   | `Number`                                            | `8.0`       |
| **hologramBrightness** | Brightness of the hologram. Ranges from 0.0 to 2.0.           | `Number`                                            | `1.2`       |
| **signalSpeed**        | Speed of the signal effect. Ranges from 0.0 to 2.0.           | `Number`                                            | `0.45`      |
| **hologramColor**      | Specifies the color of the hologram.                          | `String`                                            | `"#00d5ff"` |
| **enableBlinking**     | Enables or disables the blinking effect.                      | `Boolean`                                           | `true`      |
| **hologramOpacity**    | Specifies the opacity of the hologram.                        | `Number`                                            | `1.0`       |
| **blinkFresnelOnly**   | Enables or disables the blinking effect for the Fresnel only. | `Boolean`                                           | `true`      |
| **enableAdditive**     | Enables or disables the Additive Blend Mode.                  | `Boolean`                                           | `true`      |
| **side**               | Specifies side for the material, as String.                   | `THREE.FrontSide, THREE.BackSide, THREE.DoubleSide` | `FrontSide` |


# Materials

:api-list{list-name="material-list"}


# Mesh Discard Material

`<MeshDiscardMaterial />` hides the object it's attached to. The object's shadows and children will be rendered.

## Usage

```vue {3,11}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { MeshDiscardMaterial } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera />
    <TresMesh>
      <TresBoxGeometry />
      <MeshDiscardMaterial />
    </TresMesh>
  </TresCanvas>
</template>
```


# Mesh Portal Material

::scene-controls-wrapper
:materials-mesh-portal-material
::

The `cientos` package provides a `<MeshPortalMaterial />` component that renders its
declarative children into a private off-main scene and projects that scene onto the
host mesh as a perspective-correct window.

Children declared inside the component render into the **portal scene**, not the main
scene. The portal scene is rendered to a frame buffer each frame using the active
camera, so contents sit in world-space (move the camera and you get parallax through
the surface, not a flat decal). The mesh geometry masks the result, and `blend`
cross-fades between the world (`0`) and the portal (`1`).

::prose-note
This component is a port of the [drei MeshPortalMaterial](https://drei.docs.pmnd.rs/portals/mesh-portal-material){rel=""nofollow""}. All credit goes to the original authors.
::

## Usage

```vue
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { MeshPortalMaterial, OrbitControls } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 0, 6]" />
    <OrbitControls />
    <TresMesh>
      <TresPlaneGeometry :args="[3, 4]" />
      <MeshPortalMaterial :blend="0">
        <!-- children render INTO the portal scene -->
        <TresAmbientLight :intensity="0.5" />
        <TresMesh :position="[0, 0, -1]">
          <TresTorusKnotGeometry :args="[0.6, 0.25, 128, 32]" />
          <TresMeshStandardMaterial color="#fbb03b" />
        </TresMesh>
      </MeshPortalMaterial>
    </TresMesh>
  </TresCanvas>
</template>
```

## Props

| Prop             | Type      | Default | Description                                                                                           |
| ---------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `blend`          | `number`  | `0`     | `0` = world only, `1` = portal only; cross-fades between.                                             |
| `resolution`     | `number`  | `512`   | Frame buffer resolution for the portal render.                                                        |
| `worldUnits`     | `boolean` | `false` | Keep portal contents in world units instead of host-relative.                                         |
| `renderPriority` | `number`  | `0`     | Render-loop priority for the blend takeover. Applied at mount — changing it later requires a remount. |

## Setting the portal's background or environment

`<MeshPortalMaterial>` overrides the injected scene context for its children, so
helpers that target "the scene" affect the **portal** scene, not the world. Both of
these give the portal its own look, independent of the main scene:

```vue
<MeshPortalMaterial :blend="blend">
  <!-- Imperative helper — works because the injected scene is the portal scene -->
  <Suspense>
    <Environment preset="dawn" :background="true" />
  </Suspense>

  <!-- Or declarative attach (also lands on the portal scene) -->
  <TresColor attach="background" :args="[0.1, 0.1, 0.18]" />

  <!-- ...portal scene contents... -->
</MeshPortalMaterial>
```

::prose-note
**How it works:** the component `provide()`s a context whose `scene` points at the
private portal scene. Vue's `provide`/`inject` follows the mounted tree (it reaches
slot content through the internal `<TresPortal>`/`<Teleport>`), so both imperative
helpers (`useTres().scene`, e.g. `<Environment>`) and declarative `attach` configure
the portal scene. Only the `scene` is swapped — renderer, camera and sizes are shared.
::

::prose-warning
**On-demand rendering:** the portal renders its scene to a frame buffer on every
frame so the window keeps tracking animated contents and the `blend` takeover stays
in sync. To do this it calls `invalidate()` each frame, which keeps the render loop
running continuously — a mesh using `<MeshPortalMaterial>` effectively opts out of
[on-demand rendering](https://docs.tresjs.org/api/advanced/performance#mode-on-demand){rel=""nofollow""} while mounted.
::

::prose-note
**Limitations (MVP):** `blur` (edge fade) and pointer-event forwarding into the
portal scene are not yet implemented. WebGPU is not yet supported.
::


# Mesh Reflection Material

::scene-controls-wrapper
:materials-mesh-reflection-material
::

The `cientos` package provides a `<MeshReflectionMaterial />` component for making floors or walls that reflect the objects in your `Scene`.

The component is based on the excellent [Drei](https://github.com/pmndrs/drei){rel="&#x22;nofollow&#x22;"} component of the same name.

It extends `THREE.MeshStandardMaterial` and accepts all the same props.

## Usage

```vue {3,16-19}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { MeshReflectionMaterial } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" :look-at="[0, 0, 0]" />
    <TresMesh :rotation="[-Math.PI / 2, 0, 0]">
      <TresPlaneGeometry :args="[10, 10]" />
      <MeshReflectionMaterial
        :blur="[300, 100]"
        :mixBlur="30"
        :mixStrength="80"
        :mixContrast="1"
        color="#a0a0a0"
        metalness="0.5"
        roughness="1"
        mirror="0"
      />
    </TresMesh>
    <TresMesh :position="[0, 1, 0]">
      <TresBoxGeometry />
      <TresMeshStandardMaterial color="orange" />
    </TresMesh>
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
  </TresCanvas>
</template>
```

## Props

| Name                | Description                                                                                                                                                            | Default     |
| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `resolution`        | Length in pixels of one side of the square reflective textures                                                                                                         | `256`       |
| `mix`               | Overall strength of the reflection                                                                                                                                     | `1`         |
| `sharpMix`          | Strength of the sharp reflection on smooth surfaces                                                                                                                    | `1`         |
| `sharpDepthScale`   | Sharp reflection can be faded out by depth – distance from the reflective surface. Performance note: if the value is greater than `0`, a depth texture will be created | `1`         |
| `sharpDepthBias`    | Sharp reflection depth falloff bias                                                                                                                                    | `0`         |
| `sharpDepthEdgeMin` | Sharp reflection depth falloff start                                                                                                                                   | `0`         |
| `sharpDepthEdgeMax` | Sharp reflection depth falloff end                                                                                                                                     | `0.2`       |
| `blurMixSmooth`     | Strength of the blurred reflection on smooth surfaces                                                                                                                  | `1`         |
| `blurMixRough`      | Strength of the blurred reflection on rough surfaces                                                                                                                   | `1`         |
| `blurDepthScale`    | Blurred reflection can spread out by depth – distance from the reflective surface. Performance note: if the value is greater than `0`, depth texture will be rendered  | `1`         |
| `blurDepthBias`     | Blurred reflection depth spread bias                                                                                                                                   | `0`         |
| `blurDepthEdgeMin`  | Blurred reflection depth spread start                                                                                                                                  | `0`         |
| `blurDepthEdgeMax`  | Blurred reflection depth spread end                                                                                                                                    | `0.2`       |
| `blurSize`          | Size of the blur. If `[number, number]`, first number is width, second is height. Performance note: if other than `[0, 0]` or `0`, a blur texture will be rendered     | `[0, 0]`    |
| `distortionMap`     | Texture for offsetting the reflection                                                                                                                                  | `undefined` |
| `distortion`        | Influence of `distortionMap`                                                                                                                                           | `0`         |
| `reflectorOffset`   | Offsets the reflection                                                                                                                                                 | `0`         |

Additionally, the component extends `THREE.MeshStandardMaterial` and accepts all the same props including `color`, `roughness`, `metalness`, `map`, `normalMap`, `roughnessMap`, `metalnessMap`, and more.


# Mesh Transmission Material

::scene-controls-wrapper
:materials-mesh-transmission-material
::

The `cientos` package provides a `<MeshTransmissionMaterial />` component that produces high-quality glass and transmission effects.

The material renders the scene into a buffer texture each frame to simulate refraction, chromatic aberration, distortion, and anisotropic blur, effects that `<TresMeshPhysicalMaterial>` alone cannot achieve.

::prose-note
This component is a port of the [drei MeshTransmissionMaterial](https://drei.docs.pmnd.rs/shaders/mesh-transmission-material){rel=""nofollow""}. All credit goes to the original authors.
::

## Usage

```vue {3,10-16}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { MeshTransmissionMaterial, Environment } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 0, 5]" />
    <Environment preset="city" />
    <TresMesh>
      <TresTorusKnotGeometry :args="[1, 0.3, 128, 32]" />
      <MeshTransmissionMaterial
        :transmission="1"
        :thickness="0.5"
        :chromatic-aberration="0.03"
        :resolution="512"
      />
    </TresMesh>
  </TresCanvas>
</template>
```

## Props

| Prop                  | Description                                                                                       | Type                   |    Default   |
| :-------------------- | :------------------------------------------------------------------------------------------------ | :--------------------- | :----------: |
| `transmission`        | Glass opacity (maps to the internal `_transmission` uniform)                                      | `number`               |      `1`     |
| `thickness`           | Thickness of the glass volume                                                                     | `number`               |      `0`     |
| `roughness`           | Surface roughness                                                                                 | `number`               |      `0`     |
| `chromaticAberration` | Chromatic aberration intensity                                                                    | `number`               |    `0.03`    |
| `anisotropicBlur`     | Anisotropic blur amount                                                                           | `number`               |     `0.1`    |
| `distortion`          | Distortion amount                                                                                 | `number`               |      `0`     |
| `distortionScale`     | Scale of the distortion noise                                                                     | `number`               |     `0.5`    |
| `temporalDistortion`  | Animates the distortion over time                                                                 | `number`               |      `0`     |
| `ior`                 | Index of refraction                                                                               | `number`               |     `1.5`    |
| `color`               | Base color of the glass                                                                           | `TresColor`            |    `white`   |
| `clearcoat`           | Clearcoat layer intensity                                                                         | `number`               |      `0`     |
| `clearcoatRoughness`  | Clearcoat roughness                                                                               | `number`               |      `0`     |
| `attenuationDistance` | Distance at which light is attenuated through the volume                                          | `number`               |  `Infinity`  |
| `attenuationColor`    | Color the light shifts to as it passes through the volume                                         | `TresColor`            |    `white`   |
| `backside`            | Render back faces into a separate buffer for proper glass thickness                               | `boolean`              |    `false`   |
| `backsideThickness`   | Thickness used during the backside pass                                                           | `number`               |      `0`     |
| `resolution`          | Resolution of the FBO render target in pixels                                                     | `number`               |     `256`    |
| `backsideResolution`  | Resolution of the backside FBO. Defaults to `resolution`                                          | `number`               | `resolution` |
| `background`          | Override the scene background during the FBO pass                                                 | `THREE.Color | null`   |  `undefined` |
| `buffer`              | Supply your own render-target texture, skipping the internal FBO pass                             | `THREE.Texture | null` |  `undefined` |
| `samples`             | Number of refraction samples. &#x2A;*Baked at compile time — changing requires remount.**         | `number`               |      `6`     |
| `transmissionSampler` | Use THREE's built-in transmission sampler instead of an FBO pass. &#x2A;*Baked at compile time.** | `boolean`              |    `false`   |

The component extends `THREE.MeshPhysicalMaterial` and accepts all the same props.

## Tips

- An `<Environment>` or `envMap` on the scene is strongly recommended. Without one, the material will render dark.
- `samples` and `transmissionSampler` are baked into the shader at compile time. Changing them at runtime triggers a remount automatically.
- Enable `backside` with a non-zero `backsideThickness` for more convincing thick-glass effects.
- Lower `resolution` (e.g. `128`) improves performance at the cost of refraction sharpness.


# Point Material

::scene-wrapper
:materials-point-material
::

`<PointMaterial />` extends `THREE.PointsMaterial`. It renders the points as dots, rather than the default squares.

::prose-warning
N.B., stacking order and transparency of objects using THREE.PointsMaterial and by extension PointMaterial can be somewhat unintuitive, especially when combined with other on-screen objects. Please see discussions at threejs.org for more infomation.
::

## Usage

```vue {3,12-14}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { PointMaterial, OrbitControls } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" :look-at="[0, 0, 0]" />
    <OrbitControls />
    <TresPoints>
      <TresIcosahedronGeometry :args="[1, 4]" />
      <PointMaterial
        :size="5"
        color="orange"
      />
    </TresPoints>
    <TresAmbientLight />
  </TresCanvas>
</template>
```

## Props

All [`THREE.PointsMaterial` properties](https://threejs.org/docs/#api/en/materials/PointsMaterial){rel="&#x22;nofollow&#x22;"} are inherited by `PointMaterial`.


# Wobble Material

::scene-controls-wrapper
:materials-wobble-material
::

The `cientos` package provides a `<MeshWobbleMaterial />` component that makes a geometry wobble and wave around.

## Usage

```vue {3,11-15}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { MeshWobbleMaterial } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" :look-at="[0, 0, 0]" />
    <TresMesh>
      <TresTorusGeometry />
      <MeshWobbleMaterial
        color="#f25042"
        :speed="1"
        :factor="0.6"
      />
    </TresMesh>
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
  </TresCanvas>
</template>
```

## Props

| Prop       | Description                                           | Default |
| :--------- | :---------------------------------------------------- | ------- |
| **speed**  | how fast the wobble effect would be.                  | `1`     |
| **factor** | how strong the wobble effect will deform the geometry | `1`     |

This material extends `THREE.MeshStandardMaterial` and accepts all the same props plus additional reflection-specific properties.


# Box

::scene-controls-wrapper
:shapes-box
::

The `cientos` package provides a `<Box />` component that serves as a short-cut for a `BoxGeometry`.

```text
args: [
  width: number,
  height: number,
  depth: number,
  widthSegments: number,
  heightSegments: number,
  depthSegments: number
]
```

Reference: [BoxGeometry](https://threejs.org/docs/?q=box#api/en/geometries/BoxGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<Box :args="[1, 1, 1]" color="orange" />

// Box with a custom material transformations
<Box ref="boxRef" :args="[1, 1, 1]" :position="[0, 4, 0]">
  <TresMeshToonMaterial color="orange" />
</Box>
```


# CatmullRomCurve3

::scene-wrapper
:shapes-catmull-rom-curve3
::

The `cientos` package provides a `<CatmullRomCurve3 />` component that allows you to make smooth(ish) 3D lines.

`<CatmullRomCurve3 />` wraps [Three.js's `CatmullRomCurve3`](https://threejs.org/docs/index.html?q=catmu#api/en/extras/curves/CatmullRomCurve3){rel="&#x22;nofollow&#x22;"} functionality, but applies it to Cientos' `<Line2 />` under the hood, meaning you can use [all the props from `<Line2 />`.](https://cientos.tresjs.org/line2#props)

## Usage

```vue {3,10-14}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { CatmullRomCurve3 } from '@tresjs/cientos'
import { Vector3 } from 'three'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <CatmullRomCurve3
      :points="[new Vector3(-1, 0, 0), new Vector3(0, 1, 0), new Vector3(1, 0, 0)]"
      :segments="50"
      color="orange"
      :line-width="3"
    />
    <TresAmbientLight />
  </TresCanvas>
</template>
```

## Props

| Prop            | Type                                        | Description                                                                                                                                          | Default       |
| --------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| points          | `Array<Vector3 | [number, number, number]>` | Curve's control points                                                                                                                               |               |
| segments        | `number`                                    | Number of segments in the resulting curve (higher = smoother)                                                                                        | 20            |
| closed          | `boolean`                                   | The curve will loop back onto itself when this is true.                                                                                              | false         |
| curveType       | `'centripetal' | 'chordal' | 'catmullrom'`  | Curve type                                                                                                                                           | 'centripetal' |
| tension         | `number`                                    | Catmullrom's tension, when curveType is 'catmullrom'                                                                                                 | 0.5           |
| vertexColors    | `TresColor[]`                               | Vertex colors, if using                                                                                                                              | null          |
| color           | `TresColor`                                 | Color for the line – multiplies vertex colors                                                                                                        | 'white'       |
| lineWidth       | `number`                                    | Width of the line – in world units with size attenuation, pixels otherwise                                                                           | 1             |
| worldUnits      | `boolean`                                   | Whether the line width is in world units or pixels                                                                                                   | false         |
| alphaToCoverage | `boolean`                                   | Enables alpha to coverage. Can only be used with MSAA-enabled contexts (meaning when the renderer was created with antialias parameter set to true). | false         |
| dashed          | `boolean`                                   | Whether the line is dashed                                                                                                                           | false         |
| dashSize        | `number`                                    | Dash size                                                                                                                                            | 1             |
| gapSize         | `number`                                    | Gap size in dashed line                                                                                                                              | 1             |
| dashScale       | `number`                                    | Scale of the dashes/gaps                                                                                                                             | 1             |
| dashOffset      | `number`                                    | Dash offset                                                                                                                                          | 0             |


# Circle

::scene-controls-wrapper
:shapes-circle
::

The `cientos` package provides a `<Circle />` component that serves as a short-cut for a `CircleGeometry`.

```text
args: [radius: number, segments: number, thetaStart: number, thetaLength: number]
```

Reference: [CircleGeometry](https://threejs.org/docs/?q=circle#api/en/geometries/CircleGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<Circle :args="[1, 32]" color="orange" />

// Circle with a custom material transformations
<Circle ref="circleRef" :args="[1, 32]" :position="[0, 0, 0]">
  <TresMeshToonMaterial color="orange" />
</Circle>
```


# Cone

::scene-controls-wrapper
:shapes-cone
::

The `cientos` package provides a `<Cone />` component that serves as a short-cut for a `ConeGeometry`.

```text
args: [
  radius: number,
  height: number,
  radialSegments: number,
  heightSegments: number,
  openEnded: boolean,
  thetaStart: number,
  thetaLength: number
]
```

Reference: [ConeGeometry](https://threejs.org/docs/?q=cone#api/en/geometries/ConeGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<Cone :args="[1, 1, 8]" color="orange" />

// Cone with a custom material transformations
<Cone ref="coneRef" :args="[1, 1, 8]" :position="[0, 4, 0]">
  <TresMeshToonMaterial color="orange" />
</Cone>
```


# Cubic Bezier Line

::scene-wrapper
:shapes-cubic-bezier-line
::

`<CubicBezierLine />` renders a `<Line2 />` between start and end points, with additional 2 control points.

## Usage

```vue
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { CubicBezierLine } from '@tresjs/cientos'
import { Vector3 } from 'three'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <CubicBezierLine
      :start="new Vector3(-1, 0, 0)"
      :end="new Vector3(1, 0, 0)"
      :midA="new Vector3(-0.5, 1, 0)"
      :midB="new Vector3(0.5, 1, 0)"
      :segments="50"
      color="orange"
      :line-width="3"
    />
    <TresAmbientLight />
  </TresCanvas>
</template>
```

## Props

`<CubicBezierLine />` inherits all props but `points` from `<Line2 />`.

| Prop       | Type                                 | Description                                                   | Default |
| ---------- | ------------------------------------ | ------------------------------------------------------------- | ------- |
| `start`    | `Vector3 | [number, number, number]` | Starting point                                                |         |
| `end`      | `Vector3 | [number, number, number]` | Ending point                                                  |         |
| `midA`     | `Vector3 | [number, number, number]` | First control point                                           |         |
| `midB`     | `Vector3 | [number, number, number]` | Second control point                                          |         |
| `segments` | `number`                             | Number of segments in the resulting curve (higher = smoother) | 20      |


# Cylinder

::scene-controls-wrapper
:shapes-cylinder
::

The `cientos` package provides a `<Cylinder />` component that serves as a short-cut for a `CylinderGeometry`.

```text
args: [
  radiusTop: number,
  radiusBottom: number,
  height: number,
  radialSegments: number,
  heightSegments: number,
  openEnded: boolean,
  thetaStart: number,
  thetaLength: number
]
```

Reference: [CylinderGeometry](https://threejs.org/docs/?q=cylinder#api/en/geometries/CylinderGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<Cylinder :args="[1, 1, 1, 32, 1, false, 0, Math.PI * 2]" color="orange" />

// Cylinder with a custom material transformations
<Cylinder ref="cylinderRef" :args="[1, 1, 1, 32, 1, false, 0, Math.PI * 2]" :position="[0, 4, 0]">
  <TresMeshToonMaterial color="orange" />
</Cylinder>
```


# Dodecahedron

::scene-controls-wrapper
:shapes-dodecahedron
::

The `cientos` package provides a `<Dodecahedron />` component that serves as a short-cut for a `DodecahedronGeometry`.

```text
args: [radius: number, detail: number]
```

Reference: [DodecahedronGeometry](https://threejs.org/docs/?q=dode#api/en/geometries/DodecahedronGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<Dodecahedron :args="[1, 0]" color="orange" />

// Dodecahedron with a custom material transformations
<Dodecahedron ref="dodecahedronRef" :args="[1, 0]" :position="[2, 4, 0]">
  <TresMeshToonMaterial color="orange" />
</Dodecahedron>
```


# Grid

::scene-controls-wrapper
:shapes-grid
::

`<Grid />` creates a shader-based grid plane. It has customizable grid cell and section lines, as well as fade out.

## Usage

```vue {2,10-21}
<script setup lang="ts">
import { Grid, OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas clear-color="#222222">
    <TresPerspectiveCamera :position="[8, 10, 10]" :fov="25" />
    <OrbitControls />
    <Grid
      :args="[10.5, 10.5]"
      cell-color="#82dbc5"
      :cell-size="0.6"
      :cell-thickness="0.5"
      section-color="#fbb03b"
      :section-size="2"
      :section-thickness="1.3"
      :infinite-grid="true"
      :fade-from="0"
      :fade-distance="12"
      :fade-strength="1"
    />
  </TresCanvas>
</template>
```

## Props

| Prop                 | Description                                      | Default          |
| :------------------- | :----------------------------------------------- | ---------------- |
| **cellSize**         | Cell size                                        | `0.5`            |
| **cellThickness**    | Thickness of cell lines                          | `0.5`            |
| **cellColor**        | Color of cell lines                              | `'black'`        |
| **sectionSize**      | Section size                                     | `1`              |
| **sectionThickness** | Thickness of section lines                       | `1`              |
| **sectionColor**     | Color of cell lines                              | `'blue'`         |
| **followCamera**     | Whether to follow camera                         | `false`          |
| **infiniteGrid**     | Whether to display an infinite grid              | `false`          |
| **fadeDistance**     | Fade distance                                    | `100`            |
| **fadeStrength**     | Fade strength                                    | `1`              |
| **fadeFrom**         | Fade from camera (1) or origin (0) or in between | `1`              |
| **side**             | Material side                                    | `THREE.BackSide` |


# Icosahedron

::scene-controls-wrapper
:shapes-icosahedron
::

The `cientos` package provides a `<Icosahedron />` component that serves as a short-cut for a `IcosahedronGeometry`.

```text
args: [radius: number, detail: number]
```

Reference: [IcosahedronGeometry](https://threejs.org/docs/?q=ico#api/en/geometries/IcosahedronGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<Icosahedron :args="[1, 0]" color="orange" />

// Icosahedron with a custom material transformations
<Icosahedron ref="icosahedronRef" :args="[1, 0]" :position="[2, 4, 0]">
  <TresMeshToonMaterial color="orange" />
</Icosahedron>
```


# Shapes

:api-list{list-name="shape-list"}


# Line2

::scene-wrapper
:shapes-line2
::

The `cientos` package provides a `<Line2 />` component for creating 3-D lines. It wraps [Three.js's `Line2`](https://github.com/mrdoob/three.js/blob/e2bcdfff6427c2f106cb819b18d88d1e13aa508a/examples/jsm/lines/Line2.js){rel="&#x22;nofollow&#x22;"}.

## Usage

```vue {3,8-12}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Line2 } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <Line2
      :points="[[0, 0, 0], [1, 1, 0], [1, 1, 1], [0, 0, 1]]"
      color="orange"
      :line-width="3"
    />
    <TresAmbientLight />
  </TresCanvas>
</template>
```

## Props

| Prop            | Type                                            | Description                                                                                                                                          | Default |
| --------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| points          | [See below](https://cientos.tresjs.org/#points) | Points representing the line                                                                                                                         |         |
| vertexColors    | `TresColor[]`                                   | Vertex colors, if using                                                                                                                              | null    |
| color           | `TresColor`                                     | Color for the line – multiplies vertex colors                                                                                                        | 'white' |
| lineWidth       | `number`                                        | Width of the line – in world units with size attenuation, pixels otherwise                                                                           | 1       |
| worldUnits      | `boolean`                                       | Whether the line width is in world units or pixels                                                                                                   | false   |
| alphaToCoverage | `boolean`                                       | Enables alpha to coverage. Can only be used with MSAA-enabled contexts (meaning when the renderer was created with antialias parameter set to true). | false   |
| dashed          | `boolean`                                       | Whether the line is dashed                                                                                                                           | false   |
| dashSize        | `number`                                        | Dash size                                                                                                                                            | 1       |
| gapSize         | `number`                                        | Gap size in dashed line                                                                                                                              | 1       |
| dashScale       | `number`                                        | Scale of the dashes/gaps                                                                                                                             | 1       |
| dashOffset      | `number`                                        | Dash offset                                                                                                                                          | 0       |

### Points

The points prop has the following type:

`Array<Vector3 | Vector2 | [number, number, number] | [number, number] | number>`

The passed array is converted to `Array<number>` – i.e., a series of x, y, z vertex coordinates. This is done array entry by array entry, as follows:

| Entry type                 | Interpretation                                         |
| -------------------------- | ------------------------------------------------------ |
| `Vector3`                  | Insert the vector's x, y, z into the result array      |
| `[number, number, number]` | Insert the array values into the result array          |
| `Vector2`                  | Insert the vector's x, y, then 0 into the result array |
| `[number, number]`         | Insert the array values, then 0 into the result array  |
| `number`                   | Insert the number into the result array                |

::prose-warning
If you pass bare numbers in the points array, ensure that you pass triplets – groups of three numbers. Otherwise, you'll corrupt the coordinates that follow.
::

```vue
<!-- Wrong -->
<Line2 :points="[[1,1], 2, 2, [3,3]]" />
<!-- result: (1,1,0) (2,2,3) (3,0,❌) -->

<!-- Right -->
<Line2 :points="[[1, 1], 2, 2, 0, [3, 3]]" />
<!-- result: (1,1,0) (2,2,0) (3,3,0) -->
```

The component, like Three.js, will not keep you from shooting yourself in the foot.


# Octahedron

::scene-controls-wrapper
:shapes-octahedron
::

The `cientos` package provides a `<Octahedron />` component that serves as a short-cut for a `OctahedronGeometry`.

```text
args: [radius: number, detail: number]
```

Reference: [OctahedronGeometry](https://threejs.org/docs/?q=octa#api/en/geometries/OctahedronGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<Octahedron :args="[1, 0]" color="orange" />

// Octahedron with a custom material transformations
<Octahedron ref="icosahedronRef" :args="[1, 0]" :position="[2, 4, 0]">
  <TresMeshToonMaterial color="orange" />
</Octahedron>
```


# Plane

::scene-controls-wrapper
:shapes-plane
::

The `cientos` package provides a `<Plane />` component that serves as a short-cut for a `PlaneGeometry`.

```text
args: [width: number, height: number, widthSegments: number, heightSegments: number]
```

Reference: [PlaneGeometry](https://threejs.org/docs/?q=plane#api/en/geometries/PlaneGeometry){rel="&#x22;nofollow&#x22;"}

::prose-note
A convenient default rotation is applied to the x-axis of the plane (-Math.PI / 2), so that it is facing up (along the Y axis).
::

## Usage

```vue
<Plane :args="[1, 1]" color="orange" />

// Plane with a custom material transformations
<Plane ref="planeRef" :args="[8, 8]" :position="[0, 4, 0]">
  <TresMeshToonMaterial color="orange" />
</Plane>
```


# Quadratic Bezier Line

::scene-wrapper
:shapes-quadratic-bezier-line
::

`<QuadraticBezierLine />` renders a `<Line2 />` between start and end points, with an optional control point.

## Usage

```vue
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { QuadraticBezierLine } from '@tresjs/cientos'
import { Vector3 } from 'three'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <QuadraticBezierLine
      :start="new Vector3(-1, 0, 0)"
      :end="new Vector3(1, 0, 0)"
      :mid="new Vector3(0, 1, 0)"
      :segments="50"
      color="orange"
      :line-width="3"
    />
    <TresAmbientLight />
  </TresCanvas>
</template>
```

## Props

`<QuadraticBezierLine />` inherits all props but `points` from `<Line2 />`.

| Prop       | Type                                 | Description                                                   | Default | Required |
| ---------- | ------------------------------------ | ------------------------------------------------------------- | ------- | -------- |
| `start`    | `Vector3 | [number, number, number]` | Starting point                                                |         | yes      |
| `end`      | `Vector3 | [number, number, number]` | Ending point                                                  |         | yes      |
| `mid`      | `Vector3 | [number, number, number]` | Control point                                                 |         | no       |
| `segments` | `number`                             | Number of segments in the resulting curve (higher = smoother) | 20      | no       |


# Ring

::scene-controls-wrapper
:shapes-ring
::

The `cientos` package provides a `<Ring />` component that serves as a short-cut for a `RingGeometry`.

```text
args: [
  innerRadius: number,
  outerRadius: number,
  thetaSegments: number,
  phiSegments: number,
  thetaStart: number,
  thetaLength: number
]
```

Reference: [RingGeometry](https://threejs.org/docs/?q=ring#api/en/geometries/RingGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<Ring :args="[0.5, 1, 32]" color="orange" />

// Ring with a custom material transformations
<Ring ref="ringRef" :args="[0.5, 1, 32]" :position="[2, 4, 0]">
  <TresMeshToonMaterial color="orange" />
</Ring>
```


# Rounded Box

::scene-controls-wrapper
:shapes-rounded-box
::

The `cientos` package provides a `<RoundedBox />` component that serves as a short-cut for a `RoundedBoxGeometry` .

```text
args: [
  width: number, // default 1
  height: number, // default 1
  depth: number, // default 1
  segments: number, // default 2
  radius: number, // default 0.1
]
```

Reference: [RoundedBoxGeometry](https://github.com/mrdoob/three.js/blob/master/examples/jsm/geometries/RoundedBoxGeometry.js){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<RoundedBox :args="[1, 1, 1, 2, 0.1]" color="orange" />

// RoundedBox with a custom material transformations
<RoundedBox ref="boxRef" :position="[0, 4, 0]">
  <TresMeshToonMaterial color="orange" />
</RoundedBox>
```


# Rounded Plane

::scene-controls-wrapper
:shapes-rounded-plane
::

The `cientos` package provides a `<RoundedPlane />` component that serves as a short-cut for a `RoundedPlaneGeometry`: a plane with rounded corners. The geometry is vendored from [pmndrs/maath](https://github.com/pmndrs/maath/blob/main/packages/maath/src/geometry.ts){rel="&#x22;nofollow&#x22;"} (MIT), so it ships with no extra dependency.

```text
args: [
  width: number, // default 1
  height: number, // default 1
  radius: number, // default 0.2
  segments: number, // default 16
]
```

## Usage

```vue
<RoundedPlane :args="[1.5, 1, 0.2, 16]" color="orange" />

// RoundedPlane with a custom material
<RoundedPlane ref="planeRef" :position="[0, 4, 0]">
  <TresMeshStandardMaterial color="orange" />
</RoundedPlane>
```


# Screen Quad

::scene-wrapper
:shapes-screen-quad
::

A triangle that fills the screen when using a THREE.OrthographicCamera. Useful for full-screen fragment shader work.

## Usage

```vue
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { ScreenQuad } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresOrthographicCamera />
    <ScreenQuad>
      <TresMeshToonMaterial color="orange" />
    </ScreenQuad>
  </TresCanvas>
</template>
```

## References

- [Why a triangle?](https://www.cginternals.com/en/blog/2018-01-10-screen-aligned-quads-and-triangles.html){rel="&#x22;nofollow&#x22;"}
- [Simple postprocessing in Three.js](https://luruke.medium.com/simple-postprocessing-in-three-js-91936ecadfb7){rel="&#x22;nofollow&#x22;"}


# Sphere

::scene-controls-wrapper
:shapes-sphere
::

The `cientos` package provides a `<Sphere />` component that serves as a short-cut for a `SphereGeometry`.

```text
args: [
  radius: number,
  widthSegments: number,
  heightSegments: number,
  phiStart: number,
  phiLength: number,
  thetaStart: number,
  thetaLength: number
]
```

Reference: [SphereGeometry](https://threejs.org/docs/?q=sphere#api/en/geometries/SphereGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<Sphere :args="[1, 1, 1]" color="orange" />

// Sphere with a custom material transformations
<Sphere ref="planeRef" :args="[1, 1, 1]" :position="[2, 4, 0]">
  <TresMeshToonMaterial color="orange" />
</Sphere>
```


# Superformula

::scene-controls-wrapper
:shapes-super-formula
::

The `cientos` package provides a `<Superformula />` component that produces a configurable [3D plot of the superformula](https://en.wikipedia.org/wiki/Superformula){rel="&#x22;nofollow&#x22;"}.

## Usage

```vue {3,9-14}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Superformula } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <Superformula
      :width-segments="64"
      :height-segments="64"
      :num-arms-a="5"
      :exp-a="[40, 1.3, 0.9]"
      color="#ff6b6b"
    />
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
  </TresCanvas>
</template>
```

## Props

The `<Superformula />` 3D plot is the product of 2 2D superformulas, referred to as "A" and "B" in the props. See this [Wikipedia article about the superformula](https://en.wikipedia.org/wiki/Superformula){rel="&#x22;nofollow&#x22;"} for more information about the function's arguments.

| Name               | Description                                                  | Default          |
| :----------------- | :----------------------------------------------------------- | :--------------- |
| **widthSegments**  | Number of horizontal mesh segments                           | `32`             |
| **heightSegments** | Number of vertical mesh segments                             | `32`             |
| **numArmsA**       | For A, number of radial arms/ripples                         | `4`              |
| **expA**           | A's 3 exponents                                              | `[40, 1.3, 0.9]` |
| **numArmsB**       | For B, number of radial arms/ripples                         | `4`              |
| **expB**           | B's 3 exponents                                              | `[40, 1.3, 0.9]` |
| **color**          | If no material is provided, a color for the default material | `'white'`        |

## Slot

`<Superformula />` has a single slot for an optional material.


# Tetrahedron

::scene-controls-wrapper
:shapes-tetrahedron
::

The `cientos` package provides a `<Tetrahedron />` component that serves as a short-cut for a `TetrahedronGeometry`.

```text
args: [radius: number, detail: number]
```

Reference: [TetrahedronGeometry](https://threejs.org/docs/?q=tetr#api/en/geometries/TetrahedronGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<Tetrahedron :args="[1, 0]" color="orange" />

// Tetrahedron with a custom material transformations
<Tetrahedron ref="tetrahedronRef" :args="[1, 0]" :position="[2, 4, 0]">
  <TresMeshToonMaterial color="orange" />
</Tetrahedron>
```


# Torus

::scene-controls-wrapper
:shapes-torus
::

The `cientos` package provides a `<Torus />` component that serves as a short-cut for a `TorusGeometry`.

```text
args: [
  radius: number,
  tube: number,
  radialSegments: number,
  tubularSegments: number,
  arc: number
]
```

Reference: [TorusGeometry](https://threejs.org/docs/?q=torus#api/en/geometries/TorusGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<Torus :args="[2, 0.4, 42, 100]" color="orange" />

// Torus with a custom material transformations
<Torus ref="torusRef" :args="[0.75, 0.4, 16, 80]" :position="[-2, 6, 0]">
  <TresMeshToonMaterial color="orange" />
</Torus>
```


# Torus Knot

::scene-controls-wrapper
:shapes-torus-knot
::

The `cientos` package provides a `<TorusKnot />` component that serves as a short-cut for a `TorusKnotGeometry`.

```text
args: [
  radius: number,
  tube: number,
  tubularSegments: number,
  radialSegments: number,
  p: number,
  q: number
]
```

Reference: [TorusKnotGeometry](https://threejs.org/docs/?q=torus#api/en/geometries/TorusKnotGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<TorusKnot :args="[0.6, 0.2, 64, 8]" color="orange" />

// TorusKnot with a custom material transformations
<TorusKnot ref="torusKnotRef" :args="[0.6, 0.2, 64, 8]" :position="[-2, 6, 2]">
  <TresMeshToonMaterial color="orange" />
</TorusKnot>
```


# Tube

::scene-controls-wrapper
:shapes-tube
::

The `cientos` package provides a `<Tube />` component that serves as a short-cut for a `TubeGeometry`.

Reference: [TubeGeometry](https://threejs.org/docs/?q=tube#api/en/geometries/TubeGeometry){rel="&#x22;nofollow&#x22;"}

## Usage

```vue
<script setup lang="ts">
import { Tube } from '@tresjs/cientos'
import { CubicBezierCurve3, Vector3 } from 'three'
import { ref } from 'vue'

const tubePath = ref(new CubicBezierCurve3(
  new Vector3(-1, 0, 0),
  new Vector3(-0.5, -1, 0),
  new Vector3(0.5, 1, 0),
  new Vector3(1, 0, 0),
))
</script>

<template>
  <!-- TubeGeometry needs a curve path to be construct -->
  <Tube :args="[tubePath, 20, 0.2, 8, false]" color="orange" />

  <!-- Tube with a custom material transformations -->
  <Tube :args="[tubePath, 20, 0.2, 8, false]" :position="[0, 4, 0]">
    <TresMeshToonMaterial color="orange" />
  </Tube>
</template>
```

## Args

```text
type CurveType = QuadraticBezierCurve3 | CubicBezierCurve3 | CatmullRomCurve3 | LineCurve3

args: [
  path: CurveType,
  tubularSegments: number,
  radius: number,
  radialSegments: number,
  closed: boolean
]
```


# Helper

::scene-wrapper
:debug-performance-helper
::

`<Helper />` handles instantiation, updates, and removal/disposal of THREE Helpers.

## Usage

```vue {3,13}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Helper } from '@tresjs/cientos'
import { BoxHelper } from 'three'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <TresMesh ref="boxRef">
      <TresBoxGeometry />
      <TresMeshNormalMaterial />
      <Helper :type="BoxHelper" :args="[0xff0000]" />
    </TresMesh>
    <TresAmbientLight />
  </TresCanvas>
</template>
```

## Props

| Prop     | Description                   | Default |
| :------- | :---------------------------- | ------- |
| **type** | Helper constructor - required |         |
| **args** | Helper constructor args       | `[]`    |


# Debug/Performance

:api-list{list-name="debug-performance-list"}


# LOD

::scene-wrapper
:debug-performance-lod
::

Level of Detail - show meshes with more or less geometry based on distance from the camera.

`<LOD />` is a wrapper for THREE's [LOD](https://threejs.org/docs/?q=LOD#api/en/objects/LOD){rel="&#x22;nofollow&#x22;"} class.

## Usage

```vue
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { LOD } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 2, 5]" />
    <LOD :levels="[0, 5, 10]">
      <!-- High detail mesh - shown when close -->
      <TresMesh>
        <TresSphereGeometry :args="[1, 32, 32]" />
        <TresMeshStandardMaterial color="red" />
      </TresMesh>
      <!-- Medium detail mesh - shown at mid distance -->
      <TresMesh>
        <TresSphereGeometry :args="[1, 16, 16]" />
        <TresMeshStandardMaterial color="orange" />
      </TresMesh>
      <!-- Low detail mesh - shown when far -->
      <TresMesh>
        <TresSphereGeometry :args="[1, 8, 8]" />
        <TresMeshStandardMaterial color="yellow" />
      </TresMesh>
    </LOD>
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
  </TresCanvas>
</template>
```

## Props

| Prop           | Description                                                                                                                   | Default |
| :------------- | :---------------------------------------------------------------------------------------------------------------------------- | ------- |
| **levels**     | `number[]` - The distances at which to display each level of detail. There should be one `levels` value for each `LOD` child. |         |
| **hysteresis** | Threshold used to avoid flickering at LOD boundaries, as a fraction of distance.                                              | `0.0`   |


# Stats

[stats.js](https://github.com/mrdoob/stats.js/){rel="&#x22;nofollow&#x22;"} is a JavaScript performance monitor, made by [mrdoob](https://github.com/mrdoob){rel="&#x22;nofollow&#x22;"}. stats.js provides a simple info box that will help you monitor your code performance.

**Cientos** provides a component called `Stats` that creates a panel without effort or configuration in the top left corner where you'll be able to monitor your app.

## Basic usage

```vue {3,8}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Stats } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <Stats />
  </TresCanvas>
</template>
```

## Props

| Prop          | Type     | Default | Description  |
| :------------ | -------- | ------- | ------------ |
| **showPanel** | `number` | `0`     | FPS monitor. |

- 0: FPS Frames rendered in the last second. The higher the number the better.
- 1: MS Milliseconds needed to render a frame. The lower the number the better.
- 2: MB MBytes of allocated memory. (Run Chrome with --enable-precise-memory-info)
- 3+: CUSTOM User-defined panel support. For more info please check [stats.js](https://github.com/mrdoob/stats.js/){rel="&#x22;nofollow&#x22;"}.


# StatsGl

[stats-gl](https://github.com/RenaudRohlinger/stats-gl){rel="&#x22;nofollow&#x22;"} is a powerful WebGL performance monitoring tool created by [RenaudRohlinger](https://github.com/RenaudRohlinger){rel="&#x22;nofollow&#x22;"}.
It offers simple information boxes to track code performance and serves as a more advanced alternative to [stats.js](https://github.com/mrdoob/stats.js/){rel="&#x22;nofollow&#x22;"}, capable of displaying CPU and GPU metrics.

In TresJS, you can effortlessly create a performance monitoring panel in the top left corner of your canvas by using the StatsGl component.
Simply drop the StatsGl component into your TresCanvas for easy performance monitoring.

## Basic usage

```vue {3,8}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { StatsGl } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <StatsGl />
  </TresCanvas>
</template>
```

## Options

| Name              | Type      | Default | Description                                                                                                                                               |
| :---------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **logsPerSecond** | `number`  | `20`    | How often to log performance data, in logs per second.                                                                                                    |
| **samplesLog**    | `number`  | `100`   | Number of recent log samples to keep for computing averages.                                                                                              |
| **samplesGraph**  | `number`  | `10`    | Number of recent graph samples to keep for computing averages.                                                                                            |
| **precision**     | `number`  | `2`     | Precision of the data, in the number of decimal places (only affects CPU and GPU).                                                                        |
| **horizontal**    | `boolean` | `true`  | Display the canvases on the X-axis, set to align on the vertical axis.                                                                                    |
| **minimal**       | `boolean` | `false` | A boolean value to control the minimalistic mode of the panel display. If set to true, a simple click on the panel will switch between different metrics. |
| **mode**          | `number`  | `0`     | Sets the initial panel to display - 0 for FPS, 1 for CPU, and 2 for GPU (if supported).                                                                   |


# useBVH

::scene-controls-wrapper
:debug-performance-use-bounding-volume-hierarchy
::

A composable that dramatically improves raycasting performance by building a Bounding Volume Hierarchy (BVH) for your meshes. This can speed up raycasting by **orders of magnitude**, especially for complex models with many triangles.

Built on top of [three-mesh-bvh](https://github.com/gkjohnson/three-mesh-bvh){rel="&#x22;nofollow&#x22;"} by [Garrett Johnson](https://github.com/gkjohnson){rel="&#x22;nofollow&#x22;"}.

## What is BVH?

BVH (Bounding Volume Hierarchy) is a spatial data structure that organizes geometry into a tree of bounding boxes. Instead of testing every triangle during raycasting, the algorithm tests bounding boxes first and only checks triangles in boxes that intersect the ray. This reduces raycasting complexity from O(n) to O(log n).

**Use cases:**

- Interactive 3D applications with raycasting (mouse picking, selection)
- Complex models with thousands of triangles
- Scenes with multiple raycasting operations per frame

## Usage

### Basic Usage

```vue {2,5-8,10}
<script setup lang="ts">
import { useGLTF, useBVH } from '@tresjs/cientos'

const { state: model } = useGLTF('/models/complex-model.glb')
useBVH(() => model.value?.scene)
</script>

<template>
  <primitive v-if="model" :object="model.scene" />
</template>
```

### With Debug Visualization

Enable debug mode to visualize the BVH bounding boxes:

```vue {4-7}
<script setup lang="ts">
import { useGLTF, useBVH } from '@tresjs/cientos'

const { state: model } = useGLTF('/models/model.glb')

useBVH(
  () => model.value?.scene,
  {
    debug: true, // Show BVH bounding boxes
  }
)
</script>
```

### Reactive Enabled State

Control BVH optimization dynamically:

```vue {4,6-9}
<script setup lang="ts">
import { ref, computed } from 'vue'
import { useGLTF, useBVH } from '@tresjs/cientos'

const bvhEnabled = ref(true)

const { state: model } = useGLTF('/models/model.glb')

useBVH(
  () => model.value?.scene,
  {
    enabled: bvhEnabled,
  }
)

</script>

<template>
  <div>
    <button @click="bvhEnabled = !bvhEnabled">
      Toggle BVH
    </button>
    <primitive v-if="model" :object="model.scene" />
  </div>
</template>
```

## Options

Options are divided into **reactive** (can change at runtime) and **static** (set once at creation - changing requires toggling `enabled` off/on to rebuild).

### Reactive Options

| Option      | Type                        | Default | Description                                                        |
| :---------- | :-------------------------- | :------ | :----------------------------------------------------------------- |
| **enabled** | `MaybeRefOrGetter<boolean>` | `true`  | Enable/disable BVH optimization. Toggling rebuilds BVH structures. |
| **debug**   | `MaybeRefOrGetter<boolean>` | `false` | Show debug visualization of BVH bounding boxes.                    |

### Static Options (BVH Construction)

These options configure how the BVH is built. Changing them after creation has no effect - toggle `enabled` off/on to rebuild with new values.

| Option             | Type                           | Default | Description                                                                  |
| :----------------- | :----------------------------- | :------ | :--------------------------------------------------------------------------- |
| **firstHitOnly**   | `boolean`                      | `false` | Use `raycastFirst` for better performance when only the first hit is needed. |
| **splitStrategy**  | `'CENTER' | 'AVERAGE' | 'SAH'` | `'SAH'` | BVH build strategy. See section below.                                       |
| **maxDepth**       | `number`                       | `40`    | Maximum tree depth for the BVH structure.                                    |
| **maxLeafSize**    | `number`                       | `10`    | Target number of triangles per leaf node.                                    |
| **verbose**        | `boolean`                      | `false` | Print construction warnings and progress to console.                         |
| **setBoundingBox** | `boolean`                      | `true`  | Automatically set geometry bounding box after BVH construction.              |
| **indirect**       | `boolean`                      | `false` | If false, creates and rearranges index buffer for better performance.        |

### Split Strategies

- **SAH (Surface Area Heuristic)** - Slowest to build, fastest at runtime, uses least memory. Best for production.
- **AVERAGE** - Balanced build time and runtime performance.
- **CENTER** - Fastest to build, slower at runtime.

## Advanced Usage

### Fine-tuning Performance

Adjust BVH construction parameters for your use case:

```ts
useBVH(
  target,
  {
    splitStrategy: 'SAH', // Best runtime performance
    maxDepth: 30, // Shallower tree (faster build)
    maxLeafSize: 5, // Smaller leaves (better culling)
    verbose: true, // Debug construction
  }
)
```

### First Hit Only Mode

When you only need the closest intersection (e.g., mouse picking):

```ts
useBVH(
  target,
  {
    firstHitOnly: true, // Uses raycastFirst internally
  }
)
```

This is significantly faster than computing all intersections when you only need one.

## Important Notes

- **Side-effect free**: BVH is automatically removed on unmount and when disabled.
- **Reactive options**: Only `enabled` and `debug` are reactive. Construction options (`splitStrategy`, `maxDepth`, etc.) are static - to apply new values, toggle `enabled` off/on.
- **Memory efficient**: BVH structures are properly disposed when removed.
- **Automatic mesh detection**: Works with `Mesh` and `SkinnedMesh` instances.
- **Draco models**: Works seamlessly with Draco-compressed GLTF models.

## Performance Tips

1. **Use firstHitOnly** when you only need the closest intersection
2. **SAH strategy** gives best runtime performance for production
3. **Adjust maxLeafSize** based on triangle density (smaller for dense meshes)
4. **Enable debug mode** during development to verify BVH coverage

## Integration with useGLTF

Perfect pairing with `useGLTF` for optimized model loading:

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

const { state: model } = useGLTF('/models/high-poly-model.glb', {
  draco: true
})

useBVH(
  () => model.value?.scene,
  { splitStrategy: 'SAH' }
)
</script>
```

## Troubleshooting

### BVH not applying to some meshes

- Ensure meshes have valid geometry with position attributes
- Check console with `verbose: true` to see which meshes are skipped
- Verify the object is an `Object3D` (use `primitive` in templates)

### Performance not improving

- Enable `firstHitOnly` if you only need one intersection
- Try different split strategies (`SAH` is usually best)
- Verify raycasting is the bottleneck (use Stats/StatsGl)
- Consider LOD for very distant objects


# Accumulative Shadows

::scene-controls-wrapper
:light-shadow-accumulative-shadows
::

`<AccumulativeShadows />` is a `THREE.DirectionalLight`-based shadow component. It displays shadows on a single shadow catcher plane, included in the component. It is based on [Drei component of the same name](http://drei.docs.pmnd.rs/staging/accumulative-shadows){rel="&#x22;nofollow&#x22;"}.

## Usage

```vue {2,15-19}
<script setup lang="ts">
import { AccumulativeShadows } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas clear-color="#fbb03b" :shadows="true">
      <TresPerspectiveCamera
      :look-at="[0, 0, 0]"
    />
    <TresMesh :position-y="0.3" :scale="0.4" :cast-shadow="true">
      <TresTorusKnotGeometry />
      <TresMeshNormalMaterial />
    </TresMesh>
    <AccumulativeShadows
      :blend="100"
      color="#fbb03b"
      once
      :position-y="-0.4"
    />
  </TresCanvas>
</template>
```

## Props

| Prop         | Description                                                                                                                                                                                                                 | Default    |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `once`       | Whether shadow creation only happens once (resets after props change)                                                                                                                                                       | `false`    |
| `accumulate` | Whether shadows accumulate progressively over several frames                                                                                                                                                                | `true`     |
| `frames`     | Number of frames to render. More yields cleaner results but takes more time. If `accumulate && once`, 1 frame will be consumed every update for `frames` updates. Otherwise, `frames` frames are consumed for every update. | `40`       |
| `blend`      | If `accumulate`, controls the refresh ratio                                                                                                                                                                                 | `100`      |
| `limit`      | If less than `Infinity`, limits the amount of frames rendered. Use this to increase performance once a movable scene has settled                                                                                            | `Infinity` |
| `scale`      | Scale of the plane                                                                                                                                                                                                          | `10`       |
| `opacity`    | Opacity of the plane                                                                                                                                                                                                        | `1`        |
| `alphaTest`  | Discards alpha pixels                                                                                                                                                                                                       | `0.65`     |
| `color`      | Shadow color                                                                                                                                                                                                                | `'black'`  |
| `colorBlend` | If less than `Infinity`, limits the amount of frames rendered. Use this to increase performance once a movable scene has settled                                                                                            | `Infinity` |
| `resolution` | Buffer resolution                                                                                                                                                                                                           | `1024`     |
| `toneMapped` | Texture tonemapping                                                                                                                                                                                                         | `true`     |

## Slot

You can bring your own lights to `<AccumulatedShadows />`, but it's designed to be used with `<RandomizedLights />`.

By default, there's a [`<RandomizedLights />`](https://cientos.tresjs.org/api/light-shadow/randomized-lights) instance provided in `<AccumulatedShadows />`'s `<slot />`. You can replace it with your own [`<RandomizedLights />`](https://cientos.tresjs.org/api/light-shadow/randomized-lights) or an alternative by passing it as a child component.


# Bake Shadows

::scene-wrapper
:light-shadow-bake-shadows
::

**Cientos** provides a component called `BakeShadows`. Basically this component set the renderer.shadowMap.autoUpdate to `false`, so the shadows are casted just in the first frame which is really great for performance, the downside of this method is that the shadows will not be updated.

## Basic usage

::prose-warning
You have to set the shadows in the TresCanvas (renderer), your light sources and objects to receive and cast accordantly as you normally would do.
::

```vue {2,26}
<script setup lang="ts">
import { BakeShadows } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import { shallowRef } from 'vue'

const cubeRef = shallowRef()

function onLoop({ elapsed }: { elapsed: number }) {
  if (cubeRef.value) {
    cubeRef.value.rotation.y = elapsed * 0.5
    cubeRef.value.rotation.x = elapsed * 0.5
  }
}
</script>

<template>
  <TresCanvas
    clear-color="#82DBC5"
    shadows
    @loop="onLoop"
  >
    <TresPerspectiveCamera
      :position="[0, 2, 5]"
      :look-at="[0, 0, 0]"
    />
    <BakeShadows />
    <TresMesh
      ref="cubeRef"
      cast-shadow
    >
      <TresBoxGeometry />
      <TresMeshStandardMaterial color="orange" />
    </TresMesh>
    <TresMesh
      receive-shadow
      :position="[0, -2, 0]"
      :rotation-x="-Math.PI / 2"
    >
      <TresPlaneGeometry :args="[5, 5]" />
      <TresMeshStandardMaterial :color="0xF7F7F7" />
    </TresMesh>
    <TresDirectionalLight
      cast-shadow
      :position="[0, 10, 0]"
    />
  </TresCanvas>
</template>

```


# Circle Shadow

::scene-controls-wrapper
:light-shadow-circle-shadow
::

`<CircleShadow />` is a cheap, texture-based radial gradient on a `THREE.PlaneGeometry`.

## Usage

```vue {2,15}
<script setup lang="ts">
import { CircleShadow, OrbitControls } from "@tresjs/cientos";
import { TresCanvas } from "@tresjs/core";
</script>

<template>
  <TresCanvas clear-color="#82DBC5">
    <TresPerspectiveCamera />
    <OrbitControls />
    <TresGroup :position-y="-0.5">
      <TresMesh :position-y="1">
        <TresBoxGeometry />
        <TresMeshToonMaterial color="orange" />
      </TresMesh>
      <CircleShadow :scale="1.5" />
    </TresGroup>
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
  </TresCanvas>
</template>

```

## Props

All props are optional.

| Name         | Description                                                                                          | Default   |
| :----------- | :--------------------------------------------------------------------------------------------------- | --------- |
| `color`      | Color of the shadow as a `Color | number | string`                                                   | `'black'` |
| `opacity`    | Opacity of the shadow                                                                                | `0.5`     |
| `offset`     | Placement of the first radial gradient color stop. `0.0` is the center of the circle. `1.0` is edge. | `0`       |
| `fog`        | Whether the material is affected by fog                                                              | `false`   |
| `depthWrite` | Whether rendering the material has any effect on the depth buffer                                    | `false`   |


# Contact Shadows

::scene-controls-wrapper
:light-shadow-contact-shadow
::

`<ContactShadows />` is a "fake", non-lighting-based shadow component. It displays shadows on a single plane. The component is based on the [Three.js contact shadows example](https://threejs.org/examples/webgl_shadow_contact.html){rel="&#x22;nofollow&#x22;"} by [@mrdoob](https://twitter.com/mrdoob){rel="&#x22;nofollow&#x22;"}.

## Usage

```vue {2,13}
<script setup lang="ts">
import { ContactShadows, Levioso, TorusKnot } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas clear-color="white">
    <Levioso :speed="2" :range="[0, 0.7]" :rotation-factor="9">
      <TorusKnot :scale="0.45">
        <TresMeshNormalMaterial />
      </TorusKnot>
    </Levioso>
    <ContactShadows :position-y="-1" color="#335" :scale="20" />
  </TresCanvas>
</template>
```

## Props

| Prop         | Description                                                                                 | Default                  |
| ------------ | ------------------------------------------------------------------------------------------- | ------------------------ |
| `opacity`    | The opacity of the shadows.                                                                 | `1`                      |
| `blur`       | The blur of the shadows.                                                                    | `1`                      |
| `color`      | The color of the shadows.                                                                   | `'#000000'`              |
| `tint`       | If provided, the color of the "core" of the shadows. "Added" to `color`.                    | `undefined`              |
| `scale`      | The scale of the shadows/shadow plane. Can be a number or an array of two numbers `[x, y]`. | 10                       |
| `width`      | The width of the shadow plane.                                                              | `1`                      |
| `height`     | The height of the shadow plane.                                                             | `1`                      |
| `far`        | The distance of the orthographic shadow camera extends above the shadow plane.              | `10`                     |
| `smooth`     | Whether the shadows should be smoothed to reduce artifacts.                                 | `true`                   |
| `resolution` | The resolution of the shadow textures.                                                      | `512`                    |
| `frames`     | For performance, optionally stop updating shadows after `frames` frames.                    | `Math.POSITIVE_INFINITY` |
| `depthWrite` | Whether the shadows should write to the depth buffer or not.                                | `false`                  |


# Light/Shadow

:api-list{list-name="light-shadow-list"}


# Lensflare

::scene-controls-wrapper
:light-shadow-lensflare
::

`<Lensflare />` wraps the [Three.js Lensflare](https://threejs.org/docs/#examples/en/objects/Lensflare){rel="&#x22;nofollow&#x22;"}.

## Usage

```vue {3,9}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Lensflare } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPointLight>
      <Lensflare />
    </TresPointLight>
  </TresCanvas>
</template>
```

## Props

| Name          | Description                                                                      | Default     |
| :------------ | :------------------------------------------------------------------------------- | :---------- |
| **scale**     | `number` – multiplier for lensflare element sizes                                | `1.0`       |
| **distance**  | `number` – multiplier for element distances from flare center                    | `1.0`       |
| **elements**  | `Partial&lt;LensflareElementProps&gt;[]` – array of lensflare element properties | `undefined` |
| **seed**      | `number` – random seed for generating random seeded elements                     | `undefined` |
| **seedProps** | `SeedProps[]` – specifications for generating random seeded elements             | `undefined` |
| **color**     | `TresColor` – default color of lensflare elements                                | `undefined` |
| **texture**   | `Texture | string` – default texture of lensflare elements                       | `undefined` |

## `elements`

You can specify individual lensflare element properties directly using the component's `elements` prop.

The `elements` prop expects an instance of `(Partial<LensflareElementProps>)[]`.

Every object in `elements` may have any (or none) of the following properties.

| Name         | Description                                                                  |
| :----------- | :--------------------------------------------------------------------------- |
| **texture**  | `string | Texture` - an image URL or texture to use on the lensflare element |
| **color**    | `TresColor` - color of the lensflare element                                 |
| **distance** | `number` - distance of the lensflare element from the lensflare center       |
| **size**     | `number` - size of the lensflare element                                     |

## `seed`

Adding a `seed` prop to a component enables seeded random element generation.

The `seed` prop is used as the "seed" in a [pseudorandom number generator (PRNG)](https://en.wikipedia.org/wiki/Pseudorandom_number_generator){rel="&#x22;nofollow&#x22;"}. The PRNG is in turn used to build lensflare elements, by selecting values from an array of `SeedProps`.

::prose-note
If you set a seed but not seedProps, the component will fall back to the default, built-in SeedProps [].
::

### Example

```vue
<Lensflare :seed="seedRef" />
```

Below, the results of setting `seedRef.value` to `0`, `1`, `2`, `3`, `4`, respectively.

![Lensflare seeds 0-4](https://cientos.tresjs.org/cientos/lensflare_seeds.png)

## `seedProps`

Adding a `seedProps` prop to the component enables seeded random element generation.

The `seedProps` prop expects an instance of `SeedProps[]`. It specifies rules and acceptable values for creating random lensflare elements.

Every element in `seedProps` has this shape.

| Name         | Description                                                                                                                        | Required |
| :----------- | :--------------------------------------------------------------------------------------------------------------------------------- | -------- |
| **texture**  | `string[]` - array of 1 or more image URLs; a single texture will be selected per generated element                                | yes      |
| **color**    | `TresColor[]` - array of 1 or more colors; a single color will be selected per generated element                                   | yes      |
| **distance** | `[number, number]` - minimum and maximum allowable distance from the flare center                                                  | yes      |
| **size**     | `[number, number]` - minimum and maximum allowable size                                                                            | yes      |
| **length**   | `[number, number]` - minimum and maximum allowable number of elements to generate                                                  | yes      |
| **seed**     | `number` - if set, when this entry is processed, the random number generator with a combination of the incoming seed and this seed | no       |

::prose-note
If you set seedProps but not seed, the component will fall back to a default seed of 0.
::

## Random elements and non-random properties

`<Lensflare />` was designed to make it easy to get a lensflare on screen. You can simply add the component with no props and the component will generate seeded random lensflare elements.

```vue
<Lensflare />
```

### Non-random properties

You can provide a list of lensflare element properties using the [`elements`](https://cientos.tresjs.org/#elements) prop.

```vue
<Lensflare :elements="[{ color: 'red' }, { color: 'yellow' }]" />
```

This will produce a lensflare with 2 elements. The first element will be red. The second will be yellow. The unspecified properties – `distance`, `size`, `texture` – will be filled in by the built-in defaults in this case.

You can also provide default props which will overwrite random generated props.

```vue
<Lensflare color:"red" />
```

Since `elements` is not defined here, the component will generate random lensflare elements. The specified `color` prop – "red" – will overwrite the color property of the generated lensflare elements.

See [precedence](https://cientos.tresjs.org/#precedence) for details about how properties are filled in.

### Random elements

You can let the component generate random elements ...

... by not adding an [`elements` prop](https://cientos.tresjs.org/#elements)

```vue
<Lensflare />
```

... by adding a [`seed` prop](https://cientos.tresjs.org/#seed)

```vue
<Lensflare :seed="7127" />
```

... by adding a [`seedProps` prop](https://cientos.tresjs.org/#seedprops)

```vue
<Lensflare :seedProps="[{...}, {...}]" />
```

### Mixing random elements and non-random properties

You can mix your own properties and random elements.

```vue
<Lensflare :elements="[{...}, {...}]" :seed="8193" />
```

Here, both `elements` and `seed` are defined. The component will generate random elements and overwrite their properties with the contents of `elements`, according to the [order of precedence](https://cientos.tresjs.org/#precedence).

::prose-note
When mixing random elements with elements, the final number of lensflare elements equals whichever is larger, the length of the array of generated random elements or the length of elements.
::

### Precedence

If more than one source sets the same property on a given element, the following order of precendence is used. Higher in the list (lower number) equals higher precendence.

1. `elements`
2. `color`, `texture` – default element properties
3. `seed`, `seedProps` – generated random elements
4. built-in default element properties

::prose-note
`scale` and `distance` are applied as **multipliers** at render time, not as default values. They proportionally adjust all element sizes and distances respectively, preserving the variation between elements. Use `scale` to make the entire lensflare larger or smaller, and `distance` to spread or compress the scattered elements.
::

::prose-note
If elements, seed, and seedProps are all undefined, a seed of 0 and built-in default seedProps will be used to generate the lensflare elements.
::

### Precedence example

Here's an example of precedence. Assume this is in our vue template.

```vue
<Lensflare
  :elements="[
    {size:512, texture='http://example.net/circle.png'},
    {color:'yellow', distance:0.5}
  ]"
  :texture="http://example.net/ring.png"
  color="red"
  :seed="1"
/>
```

`seed` is defined, so the component will produce random elements.

Assume the random element generator produces this, based on `seed`:

```js
[
  {
    color: 'white',
    distance: 0,
    size: 1024,
    texture: 'http://example.net/rays.png',
  },
  {
    color: 'white',
    distance: 1,
    size: 512,
    texture: 'http://example.net/circle.png',
  },
  {
    color: 'white',
    distance: 2,
    size: 512,
    texture: 'http://example.net/circle.png',
  },
]
```

When random elements are mixed with `elements`, the final number of elements in the lensflare is determined by whichever is longer.

Here, `elements` contains 2 entries. The random element generator produced 3. So the resulting lensflare will have 3 elements.

Therefore, resulting lensflare will have 3 elements.

The resulting 3 lensflare elements will have the following properties, from the following sources:

```js
[
  {
    color: 'yellow', // from `elements`
    distance: 0, // from random element generator
    size: 512, // from `elements`
    texture: 'http://example.net/circle.png', // from `elements`
  },
  {
    color: 'red', // from component prop `color`
    distance: 0.5, // from `elements`
    size: 512, // from random element generator
    texture: 'http://example.net/ring.png', // from component prop `texture`
  },
  {
    color: 'red', // from component prop `color`
    distance: 2, // from random element generator
    size: 512, // from random element generator
    texture: 'http://example.net/ring.png', // from component prop `texture`
  },
]
```


# Randomized Lights

::scene-wrapper
:light-shadow-randomized-lights
::

`<RandomizedLights />` internally creates multiple lights and jiggles them. You would normally add it as a child of `<AccumulativeShadows />`.

It is based on this [Drei component](http://drei.docs.pmnd.rs/staging/randomized-light){rel="&#x22;nofollow&#x22;"}.

## Usage

```vue {4,16-23}
<script setup lang="ts">
import { TresCanvas } from "@tresjs/core";
import {
  RandomizedLights,
  AccumulativeShadows,
  OrbitControls,
  Plane,
} from "@tresjs/cientos";
</script>

<template>
  <TresCanvas shadows>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <OrbitControls />
    <AccumulativeShadows :blend="100" color="#fbb03b" once :position-y="-1">
      <RandomizedLights
        :ambient="0.25"
        :bias="0.001"
        :count="8"
        :intensity="Math.PI"
        :map-size="1024"
        :position="[5, 5, -10]"
        :radius="2"
      />
    </AccumulativeShadows>
    <TresMesh cast-shadow>
      <TresBoxGeometry />
      <TresMeshToonMaterial color="orange" />
    </TresMesh>
    <Plane :position="[0, -2, 0]" receive-shadow :args="[10, 10]">
      <TresMeshStandardMaterial />
    </Plane>
    <TresAmbientLight />
  </TresCanvas>
</template>

```

## Props

| Prop         | Description                                                               | Default       |
| ------------ | ------------------------------------------------------------------------- | ------------- |
| `count`      | Number of lights                                                          | `8`           |
| `radius`     | Radius of the jiggle, higher values make softer light                     | `1`           |
| `intensity`  | Light intensity                                                           | `Math.PI`     |
| `ambient`    | "Ambient occlusion" to directional light ratio, lower values mean less AO | `0.5`         |
| `castShadow` | If the lights cast shadows                                                | `true`        |
| `bias`       | Default shadow bias                                                       | `0`           |
| `mapSize`    | Size of the lights' shadow map                                            | `512`         |
| `size`       | Size of the lights' shadow camera frustum                                 | `10`          |
| `near`       | Lights' shadow camera near value                                          | `0.5`         |
| `far`        | Lights' shadow camera far value                                           | `500`         |
| `position`   | Position                                                                  | `[5, 5, -10]` |


# Soft Shadows

::scene-controls-wrapper
:light-shadow-soft-shadows
::

Injects percent closer soft shadows (pcss) into THREE's shader chunk. Mounting/unmounting this component or changing its props will cause all shaders to be recompiled.

## Usage

```vue {2,18}
<script setup lang="ts">
import { SoftShadows, Levioso, TorusKnot, Plane } from "@tresjs/cientos";
import { TresCanvas } from "@tresjs/core";
</script>

<template>
  <TresCanvas shadows clear-color="#82DBC5">
    <Levioso :speed="4" :range="[0, 0.7]" :rotation-factor="9">
      <TorusKnot cast-shadow :scale="0.45">
        <TresMeshStandardMaterial color="orange" />
      </TorusKnot>
    </Levioso>
    <Plane :position="[0, -2, 0]" receive-shadow :args="[10, 10]">
      <TresMeshStandardMaterial />
    </Plane>
    <TresDirectionalLight cast-shadow :position="[0, 3, 0]" />
    <TresAmbientLight :intensity="0.5" />
    <SoftShadows />
  </TresCanvas>
</template>
```

## Props

| Name    | Description                                                                     | Default             |
| :------ | :------------------------------------------------------------------------------ | ------------------- |
| size    | Size of the light source (the larger the softer the light)                      | `25`                |
| samples | Number of samples (more samples less noise but more expensive)                  | `10`                |
| focus   | Depth focus, use it to shift the focal point (where the shadow is the sharpest) | `0` (the beginning) |


# Environment

::scene-controls-wrapper
:staging-environment
::

Is a component abstraction that automatically sets up a global cubemap, which affects the default `scene.environment`, and optionally `scene.background`.

It uses the composable [useEnvironment](https://cientos.tresjs.org/api/staging/use-environment) under the hood to load the cubemap.

## Usage

```vue
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Environment } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <Suspense>
      <Environment
        :files="[
          '/px.jpg',
          '/nx.jpg',
          '/py.jpg',
          '/ny.jpg',
          '/pz.jpg',
          '/nz.jpg',
        ]"
      />
    </Suspense>
  </TresCanvas>
</template>
```

You can also pass the `.hdr` file directly:

```vue
<Suspense>
   <Environment files="/sunset.hdr" />
</Suspense>
```

![Environment](https://cientos.tresjs.org/cientos/envmaps.png)

## Texture reference

You can access the model reference by passing a `ref` to the `<Environment />` prop

```vue {4,6,9,14,17}
<script setup lang="ts">
import { Environment } from '@tresjs/cientos'

const environmentRef = shallowRef()

watch(environmentRef, texture => {
  console.log(texture)
})
</script>

<template>
  <Environment ref="environmentRef" />
  <TresMesh>
    <TresSphereGeometry />
    <TresMeshStandardMaterial :env-map="envMap" />
  </TresMesh>
</template>
```

## Presets

You can use one of the available presets by passing the `preset` prop:

```vue
<Environment preset="city" />
```

### Preset quality

Presets are served from the [`Tresjs/assets`](https://github.com/Tresjs/assets/tree/main/textures/hdr){rel="&#x22;nofollow&#x22;"} CDN at **1K** by default. For higher-fidelity scenes — reflective materials, large backgrounds, hero shots — you can opt into a higher-resolution variant with the `quality` prop:

```vue
<Environment preset="sunset" quality="4k" />
```

Available tiers: `'1k'` (default), `'2k'`, `'4k'`.

::warning
Higher tiers are significantly larger: **4K HDRs are ≈30–60MB** versus ≈1–3MB at 1K. Use `'2k'` / `'4k'` only when you need the extra detail, and prefer lazy-loading for large backgrounds.
::

The `quality` prop only applies when `preset` is set — it is ignored when loading via `files` / `path`. An unsupported value falls back to `'1k'` with a console warning.

::warning
**`quality` has no visible effect when you pass [Lightformers](https://cientos.tresjs.org/api/staging/lightformer) (or any children).** With children present, `<Environment>` bakes the environment and background into a `WebGLCubeRenderTarget` sized by the `resolution` prop (default `256`), so a high-res preset gets downsampled to that cube — the background will look pixelated regardless of `quality`. For a sharp high-res background, either omit the children or raise `resolution` (a cube big enough to match 4K is expensive to render each frame).
::

## Environment Rotation

The environment component supports both background and environment rotation. You can control them independently or sync them together:

```vue
<template>
  <Environment
    preset="sunset"
    :background="true"
    :background-rotation="[0, Math.PI / 2, 0]"
    :environment-rotation="[0, Math.PI / 4, 0]"
  />
</template>
```

### Syncing Rotations

You can sync the environment rotation with the background rotation using the `syncMaterials` prop:

```vue
<template>
  <Environment
    preset="sunset"
    :background="true"
    :sync-materials="true"
    :background-rotation="[0, Math.PI / 2, 0]"
  />
</template>
```

When `syncMaterials` is enabled:

- The environment rotation will automatically match the background rotation
- All materials in the scene will update to reflect the new rotation
- This ensures visual consistency between the background and environment reflections

## Props

| Prop                   | Description                                                                                    | Default                                                               |
| :--------------------- | :--------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `files`                | Array of 6 urls to images, one for each side of the CubeTexture, or an HDR file                | `undefined`                                                           |
| `path`                 | Path to the environment map files                                                              | `undefined`                                                           |
| `encoding`             | Encoding of the environment map                                                                | `SRGBColorSpace` for array files, `LinearEncoding` for single texture |
| `background`           | If `true`, the environment map will be used as the scene background                            | `false`                                                               |
| `blur`                 | Blur factor between 0 and 1 (only works with three 0.146 and up)                               | 0                                                                     |
| `preset`               | Preset environment map                                                                         | `undefined`                                                           |
| `quality`              | Resolution variant of the preset HDR (`1k` \| `2k` \| `4k`). Only applies when `preset` is set | `1k`                                                                  |
| `resolution`           | The resolution of the WebGLCubeRenderTarget                                                    | 256                                                                   |
| `near`                 | The near of the CubeCamera                                                                     | 1                                                                     |
| `far`                  | The far of the CubeCamera                                                                      | 1000                                                                  |
| `frames`               | The frames of the cubeCamera.update                                                            | Infinity                                                              |
| `backgroundIntensity`  | Intensity of the background                                                                    | 1                                                                     |
| `environmentIntensity` | Intensity of the environment                                                                   | 1                                                                     |
| `backgroundRotation`   | Rotation of the background (in radians)                                                        | [0, 0, 0]                                                             |
| `environmentRotation`  | Rotation of the environment (in radians)                                                       | [0, 0, 0]                                                             |
| `syncMaterials`        | If true, environment rotation will sync with background rotation                               | false                                                                 |

### Presets

```text
sunset
studio
city
umbrellas
night
forest
snow
dawn
hangar
urban
modern
shangai
```


# useEnvironment

::scene-wrapper
:staging-environment
::

`useEnvironment` composable that automatically sets up a global cubemap, which affects the default `scene.environment`, and optionally `scene.background`.

It uses the [CubeTextureLoader](https://threejs.org/docs/#api/en/loaders/CubeTextureLoader){rel="&#x22;nofollow&#x22;"} to load the cubemap

## Usage

::prose-warning
UseEnvironment needs to be wrapped by a Suspense component
::

```vue
<script setup lang="ts">
import { useEnvironment } from '@tresjs/cientos'
import { SRGBColorSpace } from 'three'

const texture = await useEnvironment({
  files: [
    '/textures/environmentMaps/0/px.jpg',
    '/textures/environmentMaps/0/nx.jpg',
    '/textures/environmentMaps/0/py.jpg',
    '/textures/environmentMaps/0/ny.jpg',
    '/textures/environmentMaps/0/pz.jpg',
    '/textures/environmentMaps/0/nz.jpg',
  ],
  path: '',
  encoding: SRGBColorSpace,
})
</script>
```

Then you can use the `texture` in your scene:

```vue {3}
<TresMesh>
  <TresSphereGeometry />
  <TresMeshStandardMaterial :map="texture" />
</TresMesh>
```

You can also pass the `.hdr` file directly

```ts
import { useEnvironment } from '@tresjs/cientos'

const texture = await useEnvironment({
  files: '/sunset.hdr',
  path: '',
  encoding: SRGBColorSpace,
})
```

## Options

| Name                     | Type                   | Default                                                                          | Description                                                                            |
| :----------------------- | ---------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **files**                | `Array`                | `undefined`                                                                      | Array of 6 urls to images, one for each side of the CubeTexture. or and HDR            |
| **path**                 | `boolean`              | `false`                                                                          | Path to the environment map files.                                                     |
| **encoding**             | `Encoding`             | `SRGBColorSpace` for an array of files and `LinearEncoding` for a single texture | Encoding of the environment map.                                                       |
| **background**           | `boolean`              | `false`                                                                          | If `true` the texture will be used as the scene background.                            |
| **blur**                 | `number`               | `0`                                                                              | Blur factor between 0 and 1. (only works with three 0.146 and up)                      |
| **preset**               | `string`               | `undefined`                                                                      | Preset environment map.                                                                |
| **quality**              | `'1k' | '2k' | '4k'`   | `'1k'`                                                                           | Resolution variant of the preset HDR. Only applies when `preset` is set. 4K ≈ 30–60MB. |
| **backgroundIntensity**  | `number`               | `1`                                                                              | Intensity of the background.                                                           |
| **environmentIntensity** | `number`               | `1`                                                                              | Intensity of the environment.                                                          |
| **backgroundRotation**   | `VectorFlexibleParams` | `[0, 0, 0]`                                                                      | Rotation of the background.                                                            |
| **environmentRotation**  | `VectorFlexibleParams` | `[0, 0, 0]`                                                                      | Rotation of the environment.                                                           |


# Lightformer

::scene-controls-wrapper
:staging-lightformer
::

You can incorporate `Lightformer` into the environment just like a slot.

```vue
<script setup>
import { Enviroment, LightFormer } from '@tres/cientos'
</script>

<template>
  <Environment>
    <Lightformer :intensity="0.75" :position="[0, 5, -9]" />
    <Lightformer from="ring" :rotation-y="-Math.PI / 2" :scale="[10, 10, 1]" />
  </Environment>
</template>
```

### Props

Lightformer inherits from mesh, and its extension parameters include:

| Prop        | Description                                      | Default                                                      |
| :---------- | :----------------------------------------------- | ------------------------------------------------------------ |
| `from`      | `circle`, `ring`, `rect`, or any other Mesh type | `rect`                                                       |
| `intensity` | The intensity of the light                       | 1                                                            |
| `color`     | The color of the light                           | `0xffffff`                                                   |
| `args`      | The arguments of the Geometry                    | When using other geometries, set the corresponding arguments |


# Backdrop

::scene-controls-wrapper
:staging-backdrop
::

The `cientos` package provides a `<Backdrop />` component. It's just a curved plane, like a studio backdrop. Meant is for presentational purposes, to break up light and shadows more interestingly.

## Usage

```vue {3,9}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Backdrop } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <Backdrop />
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
  </TresCanvas>
</template>
```

Or with a custom material

```html
<Backdrop :floor="1.5" :segments="20" receive-shadow>
  <TresMeshPhysicalMaterial color="orange" :roughness="1" />
</Backdrop>
```

## Props

| Name          | Type    | Default | Required |
| :------------ | :------ | ------- | -------- |
| floor         | number  | `0.25`  | No       |
| segments      | number  | `20`    | No       |
| receiveShadow | boolean | `false` | No       |


# Staging

:api-list{list-name="staging-list"}


# Ocean

::scene-controls-wrapper
:staging-ocean
::

`<Ocean />` is a wrapper for the [Three.js `Water` add-on](https://threejs.org/examples/?q=ocean#webgl_shaders_ocean){rel="&#x22;nofollow&#x22;"}.

::prose-warning
Ocean comes with a default texture, so it needs to be wrapped in a Suspense component.
::

## Usage

```vue {3,9}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Ocean } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <Suspense>
      <Ocean />
    </Suspense>
  </TresCanvas>
</template>
```

### SKY

`<Ocean />` works hand in hand with the Sky component, detecting the position of the sun and reflecting on the water.
(`<Sky />` is not required for making this component work.)

### Fog

The `<Ocean />` component also reacts when there's [Fog](https://threejs.org/docs/index.html?q=fog#api/en/scenes/Fog){rel="&#x22;nofollow&#x22;"} or [FogExp2](https://threejs.org/docs/index.html?q=fog#api/en/scenes/FogExp2){rel="&#x22;nofollow&#x22;"} in your scene.

## Custom Geometry

You can use custom geometry by adding it as a child.

```vue {3,9-11}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Ocean } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <Suspense>
      <Ocean>
        <TresCircleGeometry :args="[50, 16]" />
      </Ocean>
    </Suspense>
  </TresCanvas>
</template>
```

## Props

::prose-tip
Props marked with ✅ support reactive changes at runtime. Props marked with ❌ are only read at construction time and cannot be changed after the component is mounted.
::

| Prop                | Description                                                                                            | Default                                                                                                                                                 | Reactive |
| :------------------ | :----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: |
| **textureWidth**    | Width of the mirror texture                                                                            | `512`                                                                                                                                                   |     ❌    |
| **textureHeight**   | Height of the mirror texture                                                                           | `512`                                                                                                                                                   |     ❌    |
| **waterNormals**    | URL of the water normal texture                                                                        | [Water\_1\_M\_Normal.jpg](https://raw.githubusercontent.com/Tresjs/assets/main/textures/water-normals/Water_1_M_Normal.jpg){rel="&#x22;nofollow&#x22;"} |     ❌    |
| **sunDirection**    | Sun direction to be reflected on the water                                                             | `Vector3(0,0,0)`                                                                                                                                        |     ❌    |
| **sunColor**        | Sun color to be reflected on the water                                                                 | `0xffffff`                                                                                                                                              |     ✅    |
| **waterColor**      | Water color                                                                                            | `0x001e0f`                                                                                                                                              |     ✅    |
| **distortionScale** | Distortion scale on reflected objects                                                                  | `3.7`                                                                                                                                                   |     ✅    |
| **size**            | Size of the water normals                                                                              | `1`                                                                                                                                                     |     ✅    |
| **clipBias**        | Clip bias for the render target                                                                        | `0.0`                                                                                                                                                   |     ❌    |
| **alpha**           | Alpha transparency of the water                                                                        | `1.0`                                                                                                                                                   |     ✅    |
| **side**            | Which side of the mesh renders the water                                                               | `FrontSide`                                                                                                                                             |     ❌    |
| **speed**           | Animation speed multiplier applied to the wave animation. Higher values make the water animate faster. | `1`                                                                                                                                                     |     ✅    |


# Precipitation

::scene-controls-wrapper
:staging-precipitation
::

`<Precipitation />` is a fully flexible component that renders an infinite particle flow, It comes with several props that allow you customize it to create different effects like precipitation, snow, waterfall, beams, etc.

## Usage

You can use `<Precipitation />` component without passing any props, this will achieve a snowy effect, like the before example.

```vue {3,9}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Precipitation } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <Precipitation />
    <TresAmbientLight />
  </TresCanvas>
</template>
```

### Rain

By setting the randomness to 0, increase the speed and reduce the count. You can easily achieve a more rainy effect.

```vue {3,9-13}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Precipitation } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <Precipitation
      :count="2000"
      :speed="0.3"
      :randomness="0"
    />
    <TresAmbientLight />
  </TresCanvas>
</template>
```

### Storm

A storm effect? Easy just increase the randomness.

```vue {3,9-13}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Precipitation } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <Precipitation
      :count="3000"
      :speed="0.5"
      :randomness="1.5"
    />
    <TresAmbientLight />
  </TresCanvas>
</template>
```

### Beam

What about an infinite beam? Just set the area, to the axis that you need constrain.

```vue {3,9-15}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Precipitation } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <Precipitation
      :area="[0.5, 0.5, 20]"
      :count="1000"
      :speed="0.2"
      :size="0.3"
      color="#00ff00"
    />
    <TresAmbientLight />
  </TresCanvas>
</template>
```

You can create much more! ☔

::prose-warning
Be careful with the performance this components render infinite particles in movement
::

## Props

| Prop                | Description                                             | Default      |
| :------------------ | :------------------------------------------------------ | ------------ |
| **size**            | The size of the drops.                                  | 0.1          |
| **area**            | The size of the precipitation area.                     | [10, 10, 20] |
| **color**           | The color of the drops.                                 | 0xffffff     |
| **map**             | Color texture of the drops.                             | null         |
| **alphaMap**        | Alpha texture of the Drops.                             | null         |
| **alphaTest**       | Enables the WebGL to know when not to render the pixel. | 0.01         |
| **opacity**         | Set the opacity of the drops.                           | 0.8          |
| **count**           | Number of drops.                                        | 5000         |
| **speed**           | Drops speed.                                            | 0.1          |
| **randomness**      | Add randomness to the drops.                            | 0.5          |
| **depthWrite**      | Whether should write to the depth buffer or not. drops. | true         |
| **transparent**     | Transparency on the drops texture                       | false        |
| **sizeAttenuation** | Keep the same size regardless distance. drops.          | true         |


# Sky

::scene-controls-wrapper
:staging-sky
::

`<Sky />` is a wrapper for the [Three.js `Sky` add-on](https://threejs.org/examples/?q=sky#webgl_shaders_sky){rel="&#x22;nofollow&#x22;"}.

## Usage

```vue {2,9}
<script setup lang="ts">
import { OrbitControls, Sky } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas :tone-mapping-exposure="0.25">
    <TresPerspectiveCamera :position="[0, 15, 200]" />
    <Sky />
    <OrbitControls />
    <TresGridHelper :args="[1000, 20]" />
  </TresCanvas>
</template>

```

## Props

| Name                | Type     | Description                                                                                                                                                 | Default  | Required |
| :------------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------- |
| **turbidity**       | `number` | Haziness                                                                                                                                                    | `3.4`    | No       |
| **rayleigh**        | `number` | [Rayleigh scattering](https://en.wikipedia.org/wiki/Rayleigh_scattering){rel="&#x22;nofollow&#x22;"}                                                        | `3`      | No       |
| **mieCoefficient**  | `number` | [Mie scattering](https://en.wikipedia.org/wiki/Mie_scattering){rel="&#x22;nofollow&#x22;"} amount                                                           | `0.005`  | No       |
| **mieDirectionalG** | `number` | [Mie scattering](https://en.wikipedia.org/wiki/Mie_scattering){rel="&#x22;nofollow&#x22;"} direction                                                        | `0.7`    | No       |
| **elevation**       | `number` | Sun's elevation from the horizon, in degrees                                                                                                                | `0.6`    | No       |
| **azimuth**         | `number` | Sun's [azimuth angle](https://en.wikipedia.org/wiki/Solar_azimuth_angle){rel="&#x22;nofollow&#x22;"}, in degrees – its horizontal coordinate on the horizon | `180`    | No       |
| **distance**        | `number` | Sky box scale                                                                                                                                               | `450000` | No       |


# Smoke

::scene-wrapper
:staging-smoke
::

`<Smoke />` is a component that renders a smoke in your scene. It is an abstraction that use a combination of textures, transparency and some calculation, to create a beautiful smoke - cloud - fog effect

## Usage

::prose-warning
Smoke component comes with a default texture abstraction it needs to be wrapped by a Suspense component
::

You can use `<Smoke />` component without passing any props, but still if you want you can tweak the props to find the best setup for you

```vue
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Smoke } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <Suspense>
      <Smoke />
    </Suspense>
    <TresAmbientLight />
  </TresCanvas>
</template>
```

## Props

| Name          | Type        | Description                      | Default                                                                                                                   |
| :------------ | :---------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
| **color**     | `TresColor` | The color of the smoke.          | `'#ffffff'`                                                                                                               |
| **opacity**   | `number`    | The strength of the opacity.     | `0.5`                                                                                                                     |
| **speed**     | `number`    | The rotation speed of the smoke. | `0.4`                                                                                                                     |
| **depth**     | `number`    | The base depth.                  | `0.3`                                                                                                                     |
| **segments**  | `number`    | The number of smoke to render.   | `10`                                                                                                                      |
| **texture**   | `string`    | The texture of the smoke.        | [link](https://raw.githubusercontent.com/Tresjs/assets/main/textures/clouds/defaultCloud.png){rel="&#x22;nofollow&#x22;"} |
| **depthTest** | `boolean`   | The depthTest.                   | `false`                                                                                                                   |
| **spreadY**   | `number`    | Spread on the Y axis.            | `0.1`                                                                                                                     |
| **spreadX**   | `number`    | Spread on the X axis.            | `0.5`                                                                                                                     |
| **scale**     | `number`    | scale                            | `1`                                                                                                                       |

### Default texture

![Default texture](https://raw.githubusercontent.com/Tresjs/assets/main/textures/clouds/defaultCloud.png)


# Sparkles

`<Sparkles />` makes sparkles on your geometry's vertices – optionally guided by a directional light.

## Usage

### Basic

```vue {3,11}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Sparkles } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <TresMesh>
      <TresSphereGeometry />
      <Sparkles />
    </TresMesh>
    <TresAmbientLight />
  </TresCanvas>
</template>
```

### With TresDirectionalLight

By default, sparkles appear on the up-facing vertices. However, you can pass a directional light to the component. Moving the directional light will cause "lit" vertices to emit sparkles.

```vue {6,14,17}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Sparkles } from '@tresjs/cientos'
import { shallowRef } from 'vue'

const directionalLightRef = shallowRef()
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <TresMesh>
      <TresSphereGeometry />
      <Sparkles :directional-light="directionalLightRef" />
    </TresMesh>
    <TresDirectionalLight
      ref="directionalLightRef"
      :position="[3, 3, 3]"
      :intensity="2"
    />
    <TresAmbientLight />
  </TresCanvas>
</template>
```

### Sequences

All props beginning with `:sequence-` are used to define how a particle changes as it progresses [(See also: Mixes)](https://cientos.tresjs.org/#mixes). `:sequence-` props are of the type `Gradient<T>`, which can be any one of:

- `T`: a single value
- `[T, T, T, ...]`: an evenly distributed series of values
- `[[number, T], [number, T], ...]`: an unevently distributed series of values, where `number` is a gradient "stop" from `0` to `1`.

For example, all of these are acceptable values for `Gradient<TresColor>`:

- `'red'`
- `['red', 'blue', 'green']`
- `[[0.1, 'red'], [0.25, 'blue'], [0.5, 'green']]`

```vue {11-14}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Sparkles } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <TresMesh>
      <TresSphereGeometry />
      <Sparkles
        :sequence-color="['red', 'blue', 'green']"
        :sequence-alpha="[[0.0, 0.0], [0.10, 1.0], [0.5, 1.0], [0.9, 0.0]]"
        :sequence-size="[0.0, 1.0, 0.5]"
      />
    </TresMesh>
    <TresAmbientLight />
  </TresCanvas>
</template>
```

### Mixes

All props beginning with `:mix-` allow you to specify how a particle "progresses" through a corresponding `:sequence-` prop. E.g., `:mix-alpha` affects `:sequence-alpha`.

- If the `:mix-` prop is `0.0`, 'progress' through the `:sequence-` is determined entirely by the light shining on the surface of the sparkling mesh.[1](https://cientos.tresjs.org/#precisely)
- If the `:mix-` prop is `1.0`, 'progress' through the `:sequence-` is determined entirely by the particle's lifetime.

[](){#precisely} More precisely, the value is determined by the dot product of the `directionalLight`'s inverted normalized position and each of the sparkling mesh's vertex normals.

```vue {3,14-18}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Sparkles } from '@tresjs/cientos'
import { shallowRef } from 'vue'

const directionalLightRef = shallowRef()
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <TresMesh>
      <TresSphereGeometry />
      <Sparkles
        :directional-light="directionalLightRef"
        :mix-color="0.8"
        :mix-alpha="0.5"
        :mix-size="0.2"
      />
    </TresMesh>
    <TresDirectionalLight
      ref="directionalLightRef"
      :position="[3, 3, 3]"
    />
    <TresAmbientLight />
  </TresCanvas>
</template>
```

## Props

| Name                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **map**                     | Type: `Texture | string`:br Default: `'https://raw.githubusercontent.com/Tresjs/asset...'`:br:br Texture or image path for individual sparkles                                                                                                                                                                                                                                                                                                                                                   |
| **geometry**                | Type: `Object3D | BufferGeometry`:br Default: `undefined`:br:br Vertices of the geometry will be used to emit sparkles. Geometry normals are used for sparkles' traveling direction and for responding to the directional light prop. :br* If provided, the component will use the passed geometry.
* If no geometry is provided, the component will try to make a copy of the parent object's geometry.
* If no parent geometry exists, the component will create and use an IcosphereGeometry. |
| **directionalLight**        | Type: `Object3D`:br Default: `undefined`:br:br Particles "light up" when their normal "faces" the light. If no `directionalLight` is provided, the default "up" vector will be used.                                                                                                                                                                                                                                                                                                             |
| **lifetimeSec**             | Type: `number`:br Default: `0.4`:br:br Particle lifetime in seconds                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **cooldownSec**             | Type: `number`:br Default: `2.0`:br:br Particle cooldown in seconds – time between lifetime end and respawn                                                                                                                                                                                                                                                                                                                                                                                      |
| **normalThreshold**         | Type: `number`:br Default: `0.7`:br:br Number from 0-1 indicating how closely the particle needs to be faced towards the light to "light up". (Lower == more flexible)                                                                                                                                                                                                                                                                                                                           |
| **noiseScale**              | Type: `number`:br Default: `3.0`:br:br Scale of the noise period (lower == more slowly cycling noise)                                                                                                                                                                                                                                                                                                                                                                                            |
| **scaleNoise**              | Type: `number`:br Default: `1.0`:br:br Noise coefficient applied to particle scale                                                                                                                                                                                                                                                                                                                                                                                                               |
| **offsetNoise**             | Type: `number`:br Default: `0.1`:br:br Noise coefficient applied to particle offset                                                                                                                                                                                                                                                                                                                                                                                                              |
| **lifetimeNoise**           | Type: `number`:br Default: `0.0`:br:br Noise coefficient applied to particle lifetime                                                                                                                                                                                                                                                                                                                                                                                                            |
| **size**                    | Type: `number`:br Default: `1.0`:br:br Particle scale multiplier                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **alpha**                   | Type: `number`:br Default: `1.0`:br:br Opacity multiplier                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **offset**                  | Type: `number`:br Default: `1.0`:br:br Offset multiplier                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **surfaceDistance**         | Type: `number`:br Default: `1.0`:br:br Surface distance multiplier                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **sequenceColor**           | Type: `Gradient<TresColor>`:br Default: `[[0.7, '#82dbc5'], [0.8, '#fbb03b']]`:br:br '*Sequence' props: specify how a particle changes as it "progresses". See also "mix*" props. :br Color sequence as particles progress                                                                                                                                                                                                                                                                       |
| **sequenceAlpha**           | Type: `Gradient<number>`:br Default: `[[0.0, 0.0], [0.10, 1.0], [0.5, 1.0], [0.9, 0.0]]`:br:br Opacity sequence as particles progress                                                                                                                                                                                                                                                                                                                                                            |
| **sequenceOffset**          | Type: `Gradient<[number, number, number]>`:br Default: `[0.0, 0.0, 0.0]`:br:br Distance sequence as particles progress                                                                                                                                                                                                                                                                                                                                                                           |
| **sequenceNoise**           | Type: `Gradient<[number, number, number]>`:br Default: `[0.1, 0.1, 0.1]`:br:br Noise sequence as particles progress                                                                                                                                                                                                                                                                                                                                                                              |
| **sequenceSize**            | Type: `Gradient<number>`:br Default: `[0.0, 1.0]`:br:br Size sequence as particles progress                                                                                                                                                                                                                                                                                                                                                                                                      |
| **sequenceSurfaceDistance** | Type: `Gradient<number>`:br Default: `[0.05, 0.08, 0.1]`:br:br Distance from surface (along normal) as particles progress                                                                                                                                                                                                                                                                                                                                                                        |
| **mixColor**                | Type: `number`:br Default: `0.5`:br:br 'mix\*' props: A particle "progresses" with a mix of two factors: :br* its normal "facing" the directionalLight
* its lifetime'mix\*' props specify the relationship between the two factors. :br How is a particle's progress for color calculated? (0: normal, 1: particle lifetime)                                                                                                                                                                    |
| **mixAlpha**                | Type: `number`:br Default: `1.`:br:br How is a particle's progress for alpha calculated? (0: normal, 1: particle lifetime)                                                                                                                                                                                                                                                                                                                                                                       |
| **mixOffset**               | Type: `number`:br Default: `1.`:br:br How is a particle's progress for offset calculated? (0: normal, 1: particle lifetime)                                                                                                                                                                                                                                                                                                                                                                      |
| **mixSize**                 | Type: `number`:br Default: `0.`:br:br How is a particle's progress for size calculated? (0: normal, 1: particle lifetime)                                                                                                                                                                                                                                                                                                                                                                        |
| **mixSurfaceDistance**      | Type: `number`:br Default: `1.`:br:br How is a particle's progress for surface distance calculated? (0: normal, 1: particle lifetime)                                                                                                                                                                                                                                                                                                                                                            |
| **mixNoise**                | Type: `number`:br Default: `1.`:br:br How is a particle's progress for lifetime calculated? (0: normal, 1: particle lifetime)                                                                                                                                                                                                                                                                                                                                                                    |
| **blending**                | Type: `Blending`:br Default: `AdditiveBlending`:br:br Material blending                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **transparent**             | Type: `boolean`:br Default: `true`:br:br Material transparency                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **depthWrite**              | Type: `boolean`:br Default: `false`:br:br Material depth write                                                                                                                                                                                                                                                                                                                                                                                                                                   |


# Stage

::scene-wrapper
:staging-stage
::

This component creates a "stage" for your models. It sets up:

- model lighting
- ground shadows
- zoom to fit
- environment

::prose-note
If you are using other camera controls, be sure to make them the 'default'.

```vue
<OrbitControls make-default />
```
::

::prose-note
If you are using shadows='accumulative', enable shadows on your canvas and on your objects.

```vue
<TresCanvas shadows />
```

```vue
<TresMesh cast-shadow />
  ...
</TresMesh>
```
::

## Usage

```vue {3,10-15}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Stage, OrbitControls, Plane } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas shadows>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <OrbitControls make-default />
    <Stage
      lighting="rembrandt"
      shadows="contact"
      :adjust-camera="true"
      environment="city"
      :intensity="0.5"
    >
      <TresMesh cast-shadow>
        <TresBoxGeometry />
        <TresMeshStandardMaterial color="orange" />
      </TresMesh>
      <Plane :position="[0, -2, 0]" receive-shadow :args="[5, 5]">
        <TresMeshStandardMaterial />
      </Plane>
    </Stage>
  </TresCanvas>
</template>
```

## Props

| Prop             | Description                                                                                                                                | Default       |
| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
| **lighting**     | Lighting setup. Options: `null | undefined | false | 'rembrandt' | 'portrait' | 'upfront' | 'soft' | { main: [x, y, z], fill: [x, y, z] }` | `'rembrandt'` |
| **shadows**      | Controls the ground shadows. Options: `boolean | 'contact' | 'accumulative' | StageShadows`                                                | `'contact'`   |
| **adjustCamera** | Optionally wraps and thereby centers the models using `<Bounds>`, can also be a camera offset                                              | `true`        |
| **environment**  | The default environment                                                                                                                    | `'city'`      |
| **intensity**    | Lighting intensity, `0` removes lights                                                                                                     | `0.5`         |
| **align**        | To adjust alignment                                                                                                                        | `undefined`   |

### StageShadows Type

When using custom shadow configuration, you can pass an object with the following properties:

| Prop           | Description                               | Default   |
| :------------- | :---------------------------------------- | :-------- |
| **type**       | Shadow type: `'contact' | 'accumulative'` | -         |
| **offset**     | Shadow plane offset                       | `0`       |
| **bias**       | Shadow bias                               | `-0.0001` |
| **normalBias** | Shadow normal bias                        | `0`       |
| **size**       | Shadow map size                           | `1024`    |

Additionally inherits all props from `AccumulativeShadowsProps`, `RandomizedLightsProps`, and `ContactShadowsProps`.


# Stars

::scene-controls-wrapper
:staging-stars
::

`<Stars />` is a component that renders a stars in the sky of your scene. It is an abstraction that use Points, PointsMaterial and BufferGeometry to create a beautiful stars effect

## Usage

You can use `<Stars />` component without passing any props,

```vue {3,9}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Stars } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 3, 5]" />
    <Stars />
    <TresAmbientLight />
  </TresCanvas>
</template>
```

## Props

| Prop                | Description                                                 | Default |
| :------------------ | :---------------------------------------------------------- | ------- |
| **size**            | The size of the stars                                       | 0.1     |
| **sizeAttenuation** | keep the same size regardless distance.                     | true    |
| **transparent**     | show transparency on the stars texture                      | true    |
| **alphaTest**       | enables the WebGL to know when not to render the pixeltext. | 0.01    |
| **alphaMap**        | texture of the stars                                        | null    |
| **count**           | number of stars                                             | 5000    |
| **depth**           | depth of star's shape                                       | 50      |
| **radius**          | Radius of star's shape                                      | 100     |


# AnimatedSprite

::scene-controls-wrapper
:objects-animated-sprite
::

`<AnimatedSprite />` displays 2D animations defined in a [texture atlas](https://en.wikipedia.org/wiki/Texture_atlas){rel="&#x22;nofollow&#x22;"}. A typical `<AnimatedSprite />` will use:

- An image containing multiple sprites
- A JSON atlas containing the individual sprite coordinates in the image

## Usage

```vue {2,10-14}
<script setup lang="ts">
import { AnimatedSprite } from '@tresjs/cientos'

const currentAnimation = ref('cientosIdle')
</script>

<template>
  <TresCanvas>
    <Suspense>
      <AnimatedSprite
        image="https://raw.githubusercontent.com/Tresjs/assets/main/textures/animated-sprite/cientosTexture.png"
        atlas="https://raw.githubusercontent.com/Tresjs/assets/main/textures/animated-sprite/cientosAtlas.json"
        :animation="currentAnimation"
      />
    </Suspense>
  </TresCanvas>
</template>
```

::prose-warning
`<AnimatedSprite />` loads resources asynchronously, so it must be wrapped in a `<Suspense />`.
::

## Compiling an atlas

In typical usage, `<AnimatedSprite />` requires both the URL to a texture of compiled sprite images and a JSON atlas containing information about the sprites in the texture.

- [example compiled texture](https://raw.githubusercontent.com/Tresjs/assets/main/textures/animated-sprite/cientosTexture.png){rel="&#x22;nofollow&#x22;"}
- [example JSON atlas](https://raw.githubusercontent.com/Tresjs/assets/main/textures/animated-sprite/cientosAtlas.json){rel="&#x22;nofollow&#x22;"}

Compiling source images into a texture atlas is usually handled by third-party software. You may find [TexturePacker](https://www.codeandweb.com/texturepacker){rel="&#x22;nofollow&#x22;"} useful.

## Without an atlas

There may be cases where you don't want to supply an atlas to the `atlas` prop. To do so:

- Compile your source images into a single image texture.
- Space each sprite into equally sized columns and rows in the compiled image texture.
- Ensure no extra padding has been added to the compiled image texture.
- Set the `atlas` prop to number of columns, number of rows as `[number, number]`.

## Spritesheets in the wild

::prose-warning
In the wild, spritesheets are often distributed without atlases and the images are often compiled by hand. It can be difficult or impossible to use these resources directly with `<AnimatedSprite />`. In many cases, it's advisable to recompile the spritesheet.
::

### How to recompile an existing spritesheet image

- Cut individual sprites from the spritesheet and paste them into separate layers in an image editing application, e.g., GIMP.
- Align the layers for animation. Toggling layer visibility on/off will show you how the animation will display, frame to frame.
- Export layers as individual images.
- Name the individual images according to the following pattern: :br`[animation name][frame number].[extension]` :br E.g., walk000.png, walk001.png, idle000.png, idle001.png
- Compile individual images into an image texture and atlas using a texture packing application, like TexturePacker.

## Props

| Name        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Default      |
| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------- |
| image       | `string` – URL of the image texture or an image dataURL. This prop is not reactive.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |              |
| atlas       | `string | Atlasish` – * If `string`, the URL of the JSON atlas.
* If `number`, the number of columns in the texture.
* If `[number, number]`, the number of columns/rows in the texture.
* If `AtlasData`, the atlas as a JS object.:br This prop is not reactive.                                                                                                                                                                                                                                                                                                                                                                                                 |              |
| definitions | `Record<string, string>` – Specify playback frame order and repeated frames (delays). `definitions` is a record where keys are atlas animation names and values are strings containing an animation definition. :br:br A "animation definition" comma-separated string of frame numbers with optional parentheses-surrounded durations. :br:br Here is how various definition strings convert to arrays of frames for playback:* "0,2,1" - [0,2,1], i.e., play frame 0, 2, then 1.
* "2(10)" - [2,2,2,2,2,2,2,2,2,2], i.e., play from 2 10 times.
* "1-4" - [1,2,3,4]
* "10-5(2)" - [10,10,9,9,8,8,7,7,6,6,5,5]
* "1-4(3),10(2)" - [1,1,1,2,2,2,3,3,3,4,4,4,10,10] |              |
| fps         | `number` – Desired frames per second of the animation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `30`         |
| loop        | `boolean` – Whether or not the animation should loop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `true`       |
| animation   | `string | [number, number] | number` – If `string`, name of the animation to play. If `[number, number]`, start and end frames of the animation. If `number`, frame number to display.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `0`          |
| paused      | `boolean` – Whether the animation is paused.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`      |
| reversed    | `boolean` – Whether to play the animation in reverse.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `false`      |
| flipX       | `boolean` – Whether the sprite should be flipped, left to right.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `false`      |
| resetOnEnd  | `boolean` – For a non-looping animation, when the animation ends, whether to display the zeroth frame.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`      |
| asSprite    | `boolean` – Whether to display the object as a THREE.Sprite. [See THREE.Sprite](https://threejs.org/docs/?q=sprite#api/en/objects/Sprite){rel="&#x22;nofollow&#x22;"}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `true`       |
| center      | `TresVector2` – Anchor point of the object. A value of [0.5, 0.5] corresponds to the center. [0, 0] is left, bottom.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `[0.5, 0.5]` |
| alphaTest   | `number` – Alpha test value for the material. [See THREE.Material.alphaTest](https://threejs.org/docs/#api/en/materials/Material.alphaTest){rel="&#x22;nofollow&#x22;"}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `0.0`        |
| depthTest   | `boolean` – Depth test value for the material. [See THREE.Material.depthTest](https://threejs.org/docs/#api/en/materials/Material.depthTest){rel="&#x22;nofollow&#x22;"}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `true`       |
| depthWrite  | `boolean` – Depth write value for the material. [See THREE.Material.depthWrite](https://threejs.org/docs/#api/en/materials/Material.depthWrite){rel="&#x22;nofollow&#x22;"}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `true`       |

## Events

| Event   | Description                                                                                       | Argument                                            |
| ------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `frame` | Emitted when the displayed animation frame changes – at most once per tick, frames may be dropped | `string` – Name of the newly displayed frame        |
| `end`   | Emitted when the animation ends – `props.loop` must be set to `false`                             | `string` – Name of the ending frame                 |
| `loop`  | Emitted when the animation loops – `props.loop` must be set to `true`                             | `string` – Name of the frame at the end of the loop |

## Animation

The `:animation` prop holds either the name of the currently playing animation or a range of frames to play, or a frame number to display.

### Using named animations as animation

When individual files are converted to a spritesheet/atlas, typically the original images' filenames will be included in the atlas.

`<AnimatedSprite />` uses those filenames to automatically group images into animations.

Use either of the following naming conventions for your source images ...

- `[animation name][frame number].[file_extension]`
- `[animation name]_[frame number].[file_extension]`

... then `<AnimatedSprite />` will automatically make all `[animation name]` available for playback. Just pass `[animation name]` to the component's `:animation` prop.

### Example

For our Cientos heart cartoon character animation, here's how the filenames map to animation names.

| Filenames                                     | Animation name              |
| --------------------------------------------- | --------------------------- |
| cientosIdle0000.png, cientosIdle0001.png, ... | cientosIdle                 |
| cientosIdleToWalkTransition0000.png           | cientosIdleToWalkTransition |
| cientosWalk0000.png, cientosWalk0001.png, ... | cientosWalk                 |

## Definitions

You can supply an object to the `:definitions` prop. Any [named animation](https://cientos.tresjs.org/#animation) can be a key. The value is a string that specifies frame order and delays.

### Demo

In this demo, the 'idle' animation is comprised of six different images. By default, those images will play sequentially when the `:animation` prop is `'idle'`.

But below, we've added a `:definitions` prop with this value for the `idle` key:

```text
'0-5, 0(10), 1-2, 3(20), 4-5, 0-5(3)'
```

So, instead of playing images 0-5 sequentially, this animation will play instead:

- `0-5` – Play all six images (`0-5`) of the animation normally.
- `0(10), 1-2, 3(20), 4-5` – Play all six images again with a delay of ten frames at the bottom of the bounce (`0(10)`) and a delay of twenty frames at the top of the bounce (`3(20)`).
- `0-5(3)` – Finally, play all six images of the animation with a delay of three frames each.

## Center

In addition to being the sprite's anchor point, the `:center` prop also controls how differently sized source images will "grow" and "shrink". Namely, they "grow out from" and "shrink towards" the center.


# CubeCamera

::scene-controls-wrapper
:objects-cube-camera
::

`<CubeCamera />` creates a `THREE.CubeCamera` and uses it to render an environment map of your scene. The environment map is then applied to component's children.

`<CubeCamera />` makes its children invisible while rendering to the internal buffer so that they are not included in the reflection.

## Usage

```vue {2,10,15}
<script setup lang="ts">
import { CubeCamera, OrbitControls } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 2, 5]" />
    <OrbitControls />

    <CubeCamera :resolution="256" :frames="Infinity">
      <TresMesh>
        <TresSphereGeometry :args="[1, 32, 32]" />
        <TresMeshStandardMaterial :metalness="1" :roughness="0" />
      </TresMesh>
    </CubeCamera>

    <TresAmbientLight :intensity="0.5" />
    <TresDirectionalLight :position="[0, 2, 4]" />
  </TresCanvas>
</template>
```

## Props

| Prop         | Description                                                                                   | Default    |
| :----------- | :-------------------------------------------------------------------------------------------- | ---------- |
| `frames`     | Number of frames to render. Set to `1` for a static scene. `Infinity` to update continuously. | `Infinity` |
| `resolution` | Resolution of the FBO                                                                         | `255`      |
| `near`       | Camera near                                                                                   | `0.1`      |
| `far`        | Camera far                                                                                    | `1000`     |
| `envMap`     | Custom environment map that is temporarily set as the scene's background                      |            |
| `fog`        | Custom fog that is temporarily set as the scene's fog                                         |            |


# Fbo

::scene-wrapper
:objects-fbo
::

An FBO (or Frame Buffer Object) is generally used to render to a texture. This is useful for post-processing effects like blurring, or for rendering to a texture that will be used as a texture in a later draw call.

Cientos provides an `<Fbo />` component make it easy to use FBOs in your application.

## Usage

```vue {2,23-26}
<script setup lang="ts">
import { Fbo, OrbitControls } from '@tresjs/cientos'
import type { TresObject } from '@tresjs/core'
import { TresCanvas } from '@tresjs/core'
import { shallowRef } from 'vue'

const fboRef = shallowRef<InstanceType<typeof Fbo> | null>(null)
const torusRef = shallowRef<TresObject | null>(null)

function onLoop({ elapsed }: { elapsed: number }) {
  if (!torusRef.value) { return }
  torusRef.value.rotation.x = elapsed * 0.745
  torusRef.value.rotation.y = elapsed * 0.361
}
</script>

<template>
  <TresCanvas :clear-color="0x222" @loop="onLoop">
    <TresPerspectiveCamera :position="[0, 0.5, 5]" />
    <OrbitControls />

    <TresGridHelper :args="[10, 10]" />
    <Fbo
      ref="fboRef"
      :depth="false"
      :settings="{ samples: 1 }"
    />
    <TresMesh>
      <TresBoxGeometry :args="[1, 1, 1]" />

      <TresMeshBasicMaterial
        :color="0xFFFFFF"
        :map="fboRef?.instance?.texture ?? null"
      />
    </TresMesh>

    <TresMesh
      ref="torusRef"
      :position="[3, 0, 0]"
    >
      <TresTorusGeometry :args="[1, 0.5, 16, 100]" />
      <TresMeshNormalMaterial />
    </TresMesh>
  </TresCanvas>
</template>
```

## Props

| Prop             | Description                                                                                                                                                                                        | Default              |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **`width`**      | `number` - The width of the FBO.                                                                                                                                                                   | Width of the canvas  |
| **`height`**     | `number` - the height of the FBO                                                                                                                                                                   | Height of the canvas |
| **`depth`**      | `boolean` - Whether or not the FBO should render the depth to a [`depthTexture`](https://threejs.org/docs/?q=webglre#api/en/renderers/WebGLRenderTarget.depthTexture){rel="&#x22;nofollow&#x22;"}. | `false`              |
| **`settings`**   | `WebGLRenderTargetOptions` - Every other configuration property for the [`WebGLRenderTarget` class](https://threejs.org/docs/#api/en/renderers/WebGLRenderTarget){rel="&#x22;nofollow&#x22;"}      | `{}`                 |
| **`autoRender`** | `boolean` - Whether to automatically render the FBO on the default scene.                                                                                                                          | `true`               |

## useFBO

An FBO (or Frame Buffer Object) is generally used to render to a texture. This is useful for post-processing effects like blurring, or for rendering to a texture that will be used as a texture in a later draw call.

Cientos provides a `useFBO` composable to make it easy to use FBOs in your application.

::prose-warning
The `useFBO` composable must be used inside of a child component since it needs the context of TresCanvas.
::

### Usage

```vue {2,4-11,20}
<script setup lang="ts">
import { useFBO } from '@tresjs/cientos'

const fboTarget = useFBO({
  depth: true,
  width: 512,
  height: 512,
  settings: {
    samples: 1,
  },
})
</script>

<template>
  <TresMesh>
    <TresBoxGeometry :args="[1, 1, 1]" />

    <TresMeshBasicMaterial
      :color="0xFFFFFF"
      :map="fboTarget?.texture ?? null"
    />
  </TresMesh>
</template>

```

### Options

| Prop           | Description                                                                                                                                                                                        | Default              |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **`width`**    | `number` - The width of the FBO.                                                                                                                                                                   | Width of the canvas  |
| **`height`**   | `number` - the height of the FBO                                                                                                                                                                   | Height of the canvas |
| **`depth`**    | `boolean` - Whether or not the FBO should render the depth to a [`depthTexture`](https://threejs.org/docs/?q=webglre#api/en/renderers/WebGLRenderTarget.depthTexture){rel="&#x22;nofollow&#x22;"}. | `false`              |
| **`settings`** | `WebGLRenderTargetOptions` - Every other configuration property for the [`WebGLRenderTarget` class](https://threejs.org/docs/#api/en/renderers/WebGLRenderTarget){rel="&#x22;nofollow&#x22;"}      | `{}`                 |


# GradientTexture

::scene-wrapper
:objects-gradient-texture
::

`<GradientTexture />` creates a gradient in a THREE.Texture and attaches it to its parent THREE.Material's `map` by default.

## Usage

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

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 0, 5]" />

    <TresMesh>
      <TresPlaneGeometry :args="[2, 2]" />
      <TresMeshBasicMaterial>
        <GradientTexture
          :stops="[0, 1]"
          :colors="['#ff0000', '#0000ff']"
        />
      </TresMeshBasicMaterial>
    </TresMesh>
  </TresCanvas>
</template>
```

## Props

| Prop                | Description                                                                                                                              | Default    |
| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `stops`             | A `number[]` of values between `0` and `1` representing the color positions in the gradient. `stops.length` should match `color.length`. |            |
| `colors`            | A `THREE.ColorRepresentation[]` representing the colors in the gradient.                                                                 |            |
| `attach`            | Where the component should be attached within its parent.                                                                                | `'map'`    |
| `height`            | Height of the canvas used to draw the gradient.                                                                                          | `1024`     |
| `width`             | Width of the canvas used to draw the gradient.                                                                                           | `16`       |
| `type`              | `'linear' | 'radial'` Type of gradient to draw.                                                                                          | `'linear'` |
| `innerCircleRadius` | Radius of the inner circle of a radial gradient.                                                                                         | `0`        |
| `outerCircleRadius` | Radius of the outer circle of a radial gradient.                                                                                         | `'auto'`   |


# HTML

This component allows you to project HTML content to any object in your scene. TresJS will automatically update the position of the HTML content to match the position of the object in the scene.

🚀 Works seamlessly with both **PerspectiveCamera** and **OrthographicCamera** — the active camera is automatically detected by the `<Html>` component.

::scene-wrapper
:objects-html
::

## Usage

```vue {2,13-18}
<script setup lang="ts">
import { Html, OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas clear-color="#82DBC5">
    <TresPerspectiveCamera :position="[2, 2, 5]" />
    <OrbitControls />
    <TresMesh :position="[1, 1, 1]">
      <TresBoxGeometry />
      <TresMeshNormalMaterial />
      <Html
        center
        transform
        :distance-factor="4"
        :position="[0, 0, 0.65]"
        :scale="[0.75, 0.75, 0.75]"
      >
        <h1 class="title">I'm a Box 📦</h1>
      </Html>
    </TresMesh>
    <TresGridHelper />
    <TresAmbientLight />
  </TresCanvas>
</template>
<style scoped>
.title {
  background-color: #1e1e1e;
  color: #ffffff;
  font-size: 0.75rem;
  padding: 0.25rem;
  border-radius: 0.375rem;
}
</style>
```

## Occlusion

By default, the HTML content will be visible through other objects in the scene. You can use the `occlude` prop to make the HTML content occlude other objects in the scene.

Html can be hidden behind one or more objects in your scene using the `occlude` prop.

```vue
<Html occlude>
```

If `occlude`, then `<Html>` will be hidden by any objects that pass in front of its position.

::scene-wrapper
:objects-html-occlusion
::

Demo code

```html
<TresMesh :position="[0, 1, -2]">
  <TresBoxGeometry />
  <TresMeshNormalMaterial />
  <html center transform occlude :distance-factor="4" :position="[0, 0, 2]" :z-index-range="[28, 0]">
    <h1 class="bg-white dark:bg-dark text-xs p-1 rounded">Move camera</h1>
  </html>
</TresMesh>
```

You can also choose which object or objects should occlude the HTML content by passing either a single object ref or an array of object refs to the `occlude` prop:

### Single occluder

```vue
<Html occlude="[mesh]">
```

::scene-wrapper
:objects-html-single-occluder
::

Demo code

```html
<TresMesh :position="[0, 1, 0]">
  <TresBoxGeometry />
  <TresMeshNormalMaterial />
  <html center transform :occlude="[sphereRef]" :distance-factor="4" :z-index-range="[28, 0]">
    <h1 class="bg-white dark:bg-dark text-xs p-1 rounded">Move camera</h1>
  </html>
</TresMesh>
```

### Multiple occluders

```vue
<Html occlude="[mesh1, mesh2, mesh3, ...]" />
```

OR

```vue
<Html occlude="meshesArray" />
```

In the demo below, a `v-for&#x60; loop generates multiple spheres around the cube.
All resulting &#x2A;*`Mesh`*&#x2A; instances are collected into an array and passed to the &#x2A;*`occlude`** prop, allowing each sphere to occlude the HTML content.

This demo also uses the &#x2A;*`on-occlude`** event, which is triggered whenever the occlusion state changes.
Here, the event updates a **reactive value** to control element styles — for example, toggling between *light* and *dark* themes.

::scene-wrapper
:objects-html-occlude-complex-demo
::

Demo code

```html
<TresMesh :position="[0, 1, 0]">
  <TresBoxGeometry />
  <TresMeshNormalMaterial />
  <html
    v-bind="htmlProps"
    :occlude="occluderRefs"
    :distance-factor="4"
    :z-index-range="[28, 0]"
    @on-occlude="(event: boolean) => isOccluded = event"
  >
    <h1 class="bg-white dark:bg-dark text-xs p-1 rounded">Move camera</h1>
  </html>
</TresMesh>
```

### Blending Occlusion

`<Html>` can hide behind geometry as if it was part of the 3D scene using this mode. It can be enabled by using "blending" as the occlude prop.

```vue
<Html occlude="blending">
```

The **demo below ⬇️*&#x2A; &#x2A;(left black example)* shows a **basic usage example**.

::scene-wrapper
:objects-html-occlude-blending-demo
::

Demo code

```vue {2,32,34-39,62-72,63-72,74-84,86-96,98-108}
<script setup lang="ts">
import { Html, Levioso, OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import { shallowRef } from 'vue'
import { CircleGeometry, MeshStandardMaterial } from 'three'

const gl = {
  clearColor: '#82DBC5',
  clearAlpha: 1,
  shadows: true,
  alpha: true,
}

const targetDirectionLightRef = shallowRef(null)

const geometries = [
  {
    component: 'TresBoxGeometry',
    args: [1, 1, 1],
  },
  {
    component: 'TresSphereGeometry',
    args: [0.7, 32, 32],
  },
  {
    component: 'TresTorusGeometry',
    args: [0.5, 0.2, 16, 100],
    bind: { castShadow: true, receiveShadow: true },
  },
]

const customGeometry = shallowRef(new CircleGeometry(1.25, 32))

const customMaterial = shallowRef(new MeshStandardMaterial({
  color: 'red',
  side: 2,
  opacity: 1,
  transparent: true,
}))
</script>

<template>
  <div class="html-demo-wrapper aspect-video">
    <TresCanvas v-bind="gl">
      <TresPerspectiveCamera :position="[0, 1.5, 7.5]" />
      <OrbitControls />

      <Levioso
        v-for="(geometry, index) in geometries"
        :key="`html-occlude-blending-demo-${index}`"
        :speed="3"
        :float-factor="3.5"
        :rotation-factor="1"
        :range="[-0.35, 0.35]"
      >
        <TresMesh :position="[index * 3.5 - 3.5, 1, 0]" v-bind="geometry.bind">
          <component :is="geometry.component" :args="geometry.args" />
          <TresMeshNormalMaterial />
        </TresMesh>
      </Levioso>

      <Html
        center
        transform
        occlude="blending"
        :position="[-4, .75, -2]"
        :z-index-range="[28, 0]"
      >
        <div class="text-center text-s p-2 bg-[#1B1C1E] text-light">
          BASIC 💛 <br />
          <em>occlude=blending</em>
        </div>
      </Html>

      <Html
        center
        transform
        occlude="blending"
        :position="[0, .85, -2]"
        :geometry="customGeometry"
        :z-index-range="[28, 0]"
      >
        <div class="text-xs p-8 text-center bg-[#F6B03B] text-dark">
          CUSTOM <br /> <strong>CIRCLE <br /> GEOMETRY</strong>
        </div>
      </Html>

      <Html
        ref="targetDirectionLightRef"
        center
        transform
        occlude="blending"
        :position="[4, .5, -2]"
        :material="customMaterial"
        receive-shadow
        :z-index-range="[28, 0]"
      >
        <div style="width: 100px; height: auto; aspect-ratio: 250/250;"></div>
      </Html>

      <Html
        center
        transform
        occlude="blending"
        :position="[4, 2.5, -2]"
        :z-index-range="[28, 0]"
      >
        <div class="text-center text-xs p-2 text-dark bg-[#FF0000]">
          <strong>HTML + Custom material </strong> <br />
          <em>+ receive-shadow </em> ⬇️
        </div>
      </Html>

      <TresDirectionalLight
        v-if="targetDirectionLightRef?.instance"
        :target="targetDirectionLightRef?.instance"
        :shadow-normalBias="0.075"
        :position="[5, 0, 5]"
        :intensity="2"
        cast-shadow
      />

      <TresGridHelper :position-y="-1" />
      <TresAmbientLight :intensity="1" />
    </TresCanvas>
  </div>
</template>

<style scoped>
.html-demo-wrapper {
  width: 100%;
  height: 100%;
  position: relative;
  overflow: hidden;
  background-color: #82dbc5;
}
</style>

```

## Custom Geometry

By default, when using `occlude="blending"`, occlusion works correctly only with **rectangular HTML elements** (using a `PlaneGeometry`).
For *non-rectangular content&#x2A;, you can use the &#x2A;*`geometry`** prop to provide a matching custom geometry.

In the **demo above ⬆️*&#x2A; &#x2A;(middle yellow example)*, a [`CircleGeometry`](https://threejs.org/docs/#api/en/geometries/CircleGeometry){rel="&#x22;nofollow&#x22;"} is used as a **custom geometry**.

::prose-list
- The `geometry` prop only defines the **occlusion shape** in 3D and does not modify your HTML content.
- You can provide any [`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry){rel=""nofollow""}, for example to simulate **CSS-like styles** such as `border-radius` using a rounded rectangle or squircle geometry (see [`RoundedRectangle / Squircle geometry`](https://discourse.threejs.org/t/roundedrectangle-squircle/28645){rel=""nofollow""} for example).
::

### Custom Material

You can also assign material properties to the HTML content using the `material` prop.
In the **demo above ⬆️*&#x2A; &#x2A;(right red example)*, a **custom material** is used with shadow.

::prose-note
The `material` prop is only available when `occlude="blending"` is **enabled**.
::

::prose-note
Enable shadows using the **`castShadow`** and **`receiveShadow`** props.
Shadows are supported **only** when using a **custom material**. By default, shadows do **not** work with *`MeshBasicMaterial`* or *`ShaderMaterial`*. :br
::

## Using `<Transition>`

The native Vue [`<Transition>`](https://vuejs.org/guide/built-ins/transition){rel="&#x22;nofollow&#x22;"} component works seamlessly with `<Html>`.
This means you can **animate** how your projected HTML content *enters* and *leaves* the scene, exactly as you would in a regular Vue application.

::prose-note
All **standard interactions** are supported just like on a regular HTML element — **hover effects**, **events**, and *any kind of DOM interaction* are fully possible.
::

::scene-controls-wrapper
:objects-html-transition-demo
::

Demo code

```vue {2,73-92}
<script setup lang="ts">
import { Html, Levioso, OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import { ref } from 'vue'

const gl = {
  clearColor: '#82DBC5',
  clearAlpha: 0,
  shadows: true,
  alpha: true,
  antialias: true,
}

const rootRef = ref<HTMLElement>()

const bgColor = ref('#F6B03B')

const geometries = [
  {
    component: 'TresBoxGeometry',
    args: [1, 1, 1],
  },
  {
    component: 'TresSphereGeometry',
    args: [0.7, 32, 32],
  },
  {
    component: 'TresTorusGeometry',
    args: [0.5, 0.2, 16, 100],
  },
  {
    component: 'TresConeGeometry',
    args: [0.7, 1.4, 32],
  },
]

const getRandomBackgroundColor = (): string => {
  const colors = ['#F6B03B', '#82DBC5', '#FF5733', '#33FF57', '#3357FF', '#F333FF', '#33FFF5']
  const idx = Math.floor(Math.random() * colors.length)
  return colors[idx] ?? '#F6B03B'
}

const updateBackgroundColor = () => {
  bgColor.value = getRandomBackgroundColor()
}
</script>

<template>
  <div ref="rootRef" class="html-demo-wrapper">
    <TresCanvas v-bind="gl" class="!pointer-events-none">
      <TresPerspectiveCamera :position="[0, 1.5, 7.5]" />
      <OrbitControls :dom-element="rootRef" />

      <Levioso
        v-for="(geometry, index) in geometries"
        :key="`html-occlude-blending-demo-${index}`"
        :speed="3"
        :float-factor="3.5"
        :rotation-factor="1"
        :range="[-0.4, 0.4]"
      >
        <TresMesh :position="[(index - (geometries.length - 1) / 2) * 2, 1, 0]">
          <component :is="geometry.component" :args="geometry.args" />
          <TresMeshNormalMaterial />
        </TresMesh>
      </Levioso>

      <Html
        center
        transform
        occlude="blending"
        :position="[0, .75, -2]"
        :scale="1.15"
        :z-index-range="[28, 0]"
      >
        <Transition name="transition-basic">
          <h1
            v-if="showTransition"
            :style="{ backgroundColor: bgColor }"
            class="html-demo-transition-heading will-change-transform transition-transform,background-color cursor-pointer duration-500 text-center p-2 text-light shadow-lg"
            @click="updateBackgroundColor"
          >
            <strong>TRANSITION + </strong><br />
            <em>occlude=blending 💛</em>
          </h1>
        </Transition>
      </Html>

      <TresGridHelper :position-y="-1.25" />
      <TresAmbientLight :intensity="1" />
    </TresCanvas>
  </div>
</template>

<style scoped>
.html-demo-wrapper {
  width: 100%;
  height: 100%;
  position: relative;
  overflow: hidden;
  background-color: #82dbc5;
}

.html-demo-transition-heading:hover {
  transform: scale(1.05);
}

.transition-basic-enter-from,
.transition-basic-leave-to {
  opacity: 0;
  transform: translateY(-20px);
}

.transition-basic-enter-active,
.transition-basic-leave-active {
  transition: all 0.5s ease;
}

.transition-basic-enter-to,
.transition-basic-leave-from {
  opacity: 1;
  transform: translateY(0);
}
</style>
```

### Using `iframes`

You can achieve pretty cool results with the `Html` component by using iframes. For example, you can use an iframe to display a YouTube video in your scene or a webpage with a 3D model.

::scene-wrapper
:objects-html-iframe-demo
::

Demo code

```html
<html
  transform
  center
  :cast-shadow="true"
  :receive-shadow="true"
  occlude="blending"
  :z-index-range="[28, 0]"
  :position-y="2.5"
  :portal="portalRef"
  :style="{ userSelect: 'none' }"
>
  <iframe class="w-[700px] h-[500px]" src="https://tresjs.org" frameborder="0" :width="700" :height="500"></iframe>
</html>
```

::info
The demos use `:z-index-range="[28, 0]"` simply to ensure the HTML elements stay below the documentation header (which uses `z-index: 30`).
**This value is for the docs only — you can ignore it or adjust it as needed.**
::

## Props

| Prop                    | Description                                                                                                                                                                                                                                                                                                                                                                                             | Default                                                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **as**                  | Wrapping *HTML element*.                                                                                                                                                                                                                                                                                                                                                                                | `'div'`                                                                                                                                   |
| **wrapperClass**        | The `className` of the wrapping element. element.                                                                                                                                                                                                                                                                                                                                                       |                                                                                                                                           |
| **prepend**             | Projects content *behind* the canvas.                                                                                                                                                                                                                                                                                                                                                                   | `false`                                                                                                                                   |
| **center**              | Adds a `transform: translate(-50%, -50%)`. :br ➡️ &#x2A;Ignored in **transform** mode.*                                                                                                                                                                                                                                                                                                                 | `false`                                                                                                                                   |
| **fullscreen**          | Aligns to the upper-left corner and fills the screen. :br ➡️ &#x2A;Ignored in **transform** mode.*                                                                                                                                                                                                                                                                                                      | `false`                                                                                                                                   |
| **distanceFactor**      | Children are scaled by this factor and also by distance to a `PerspectiveCamera`, or zoom when using an `OrthographicCamera`.                                                                                                                                                                                                                                                                           |                                                                                                                                           |
| **zIndexRange**         | Defines the *Z-order range*.                                                                                                                                                                                                                                                                                                                                                                            | `[16777271, 0]`                                                                                                                           |
| **portal**              | Reference to a target container (for rendering into a different DOM node). container.                                                                                                                                                                                                                                                                                                                   |                                                                                                                                           |
| **transform**           | If `true`, applies `matrix3d` transformations — the element appears as if it is inside the 3D scene.                                                                                                                                                                                                                                                                                                    | `false`                                                                                                                                   |
| **sprite**              | Renders as a *sprite*. :br ➡️ &#x2A;Only in **transform** mode.*                                                                                                                                                                                                                                                                                                                                        | `false`                                                                                                                                   |
| **calculatePosition**   | Callback function to override the default positioning logic. :br&#x2A;*Type:** `(object: Object3D, camera: Camera, size: { width: number; height: number }) => [number, number, number]` :br Receives the related 3D object, the active camera, and the current viewport size, and must return `[x, y, z]` pixel coordinates for placing the HTML element. :br ➡️ &#x2A;Ignored in **transform** mode.* | [Default `calculatePosition`](https://github.com/Tresjs/cientos/blob/main/src/core/misc/html/utils.ts#L9-L19){rel="&#x22;nofollow&#x22;"} |
| **occlude**             | Enables occlusion. Possible values: :br - `true` → Occlusion against *all* scene objects :br - `Ref<TresObject3D>[]` → Occlusion is enabled only against the specified objects. :br - `'blending'` → Uses a *blending-based* occlusion method (CSS-like depth blending).                                                                                                                                |                                                                                                                                           |
| **geometry**            | Custom `geometry` to be used.                                                                                                                                                                                                                                                                                                                                                                           | [`PlaneGeometry`](https://threejs.org/docs/?q=geometry#api/en/geometries/PlaneGeometry){rel="&#x22;nofollow&#x22;"}                       |
| **material**            | **Custom shader *material* used for the occlusion mesh.** :br **Only applies when `occlude="blending"` is enabled** (an occlusion mesh is created). :br &#x2A;Ignored in raycast occlusion modes (`true`, object refs).*                                                                                                                                                                                |                                                                                                                                           |
| **transparentMaterial** | **Enables *transparent* rendering for the occlusion material.** :br &#x2A;*Only applies when `occlude="blending"` creates an occlusion mesh.** :br &#x2A;Ignored in raycast occlusion modes (`true`, object refs).*                                                                                                                                                                                     | `false`                                                                                                                                   |

## Events

| Event     | Description                              |
| --------- | ---------------------------------------- |
| onOcclude | Called when the occlusion state changes. |

## Exposed properties

| Property          | Type                       | Description                                                                                                                         |
| ----------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **instance**      | `Ref<TresObject3D | null>` | Reference to the root &#x2A;*`<TresGroup>`** used by `<Html>`.                                                                      |
| **isVisible**     | `Ref<boolean>`             | Reactive value that indicates whether the HTML content is **currently visible** or **occluded**.                                    |
| **occlusionMesh** | `Ref<TresObject3D | null>` | Reference to the **occlusion mesh** created when `occlude="blending"` is **enabled**. Used internally for geometry-based occlusion. |

## Caveats

- ✨ When using &#x2A;*`<Html occlude>`**, if the `<Html>` component is **overlapping** or **inside a 3D object**, it will be considered **occluded** and therefore **hidden**. To avoid this, **adjust the position** of the `<Html>` component in your scene.
- 🎨 When using &#x2A;*`<Html occlude="blending">`**, the HTML content is no longer **selectable** because it is rendered **behind the canvas**. This is required to achieve the blending effect.
- ⚙️ When using a **custom material** with occlusion in `blending` mode, there are a few important requirements to ensure the HTML content renders correctly ⬇️

  See more information

  1. If you provide your own material, it must be **transparent** (`transparent: true`) with an **opacity < 1**.
  2. If you are not providing a custom material, enable &#x2A;*`transparentMaterial`** so the internal shader becomes transparent.
  3. The occlusion mesh requires a **fully transparent canvas background**; otherwise, thin borders or halo artifacts may appear.
  4. To compensate for the transparent canvas, you may **reapply your previous clear-color as a CSS background** on the `html`, `body`, or a wrapper `div`.
- 🔶 When using &#x2A;*`transparentMaterial`**, overlapping `<Html>` elements (especially multiple `occlude="blending"` instances) may cause **z-index or depth-order artifacts**.
  This happens because the occlusion mesh uses transparency in the WebGL layer while the DOM element uses CSS stacking order.
- 🔵 To avoid thin border artifacts when using `occlude="blending"`, make sure your `<TresCanvas>` is fully transparent:
  ```vue
  <TresCanvas :alpha="true" :clearAlpha="0" />
  ```

| Prop                  | Description                                                                                                          | Default         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------- |
| **as**                | Wrapping html element.                                                                                               | `'div'`         |
| **wrapperClass**      | The className of the wrapping element.                                                                               |                 |
| **prepend**           | Project content behind the canvas.                                                                                   | `false`         |
| **center**            | Adds a -50%/-50% CSS transform. [Ignored in transform mode]                                                          | `false`         |
| **fullscreen**        | Aligns to the upper-left corner, fills the screen. [Ignored in transform mode]                                       | `false`         |
| **distanceFactor**    | Children will be scaled by this factor, and also by distance to a PerspectiveCamera / zoom by an OrthographicCamera. |                 |
| **zIndexRange**       | Z-order range.                                                                                                       | `[16777271, 0]` |
| **portal**            | Reference to target container.                                                                                       |                 |
| **transform**         | If true, applies matrix3d transformations.                                                                           | `false`         |
| **sprite**            | Renders as sprite, but only in transform mode.                                                                       | `false`         |
| **calculatePosition** | Override default positioning function. [Ignored in transform mode]                                                   |                 |
| **occlude**           | Can be `true`, `Ref<TresObject3D>[]`, `'raycast'`, or `'blending'`. True occludes the entire scene.                  |                 |
| **geometry**          | Custom `geometry` to be use                                                                                          | `PlaneGeometry` |
| **material**          | Custom shader `material` to be use                                                                                   |                 |

## Events

| Event     | Description                              |
| --------- | ---------------------------------------- |
| onOcclude | Called when the occlusion state changes. |


# Image

::scene-controls-wrapper
:objects-image
::

`<Image />` is a shader-based component that optionally loads then displays an image texture on a default plane or on your custom geometry.

## Usage

```vue {3,10-12}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Image } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 0, 5]" />

    <Image
      url="https://upload.wikimedia.org/wikipedia/commons/f/f0/Cyanistes_caeruleus_Oulu_20150516.JPG"
      :scale="[2, 2]"
    />
  </TresCanvas>
</template>
```

## Props

::prose-warning
`<Image />` is a THREE.Mesh and most Mesh attributes can be used as props on the component.
::

| Prop          | Description                                                                                                                                                                                                                  | Default     |
| :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `segments`    | Number of divisions in the default geometry.                                                                                                                                                                                 | `1`         |
| `scale`       | Scale of the geometry. `number | [number, number]`                                                                                                                                                                           | `1`         |
| `color`       | Color multiplied into the image texture.                                                                                                                                                                                     | `'white'`   |
| `zoom`        | Shrinks or enlarges the image texture.                                                                                                                                                                                       | `1`         |
| `radius`      | Border radius applied to the image texture. (Intended for rectangular geometries. Use with `transparent`.)                                                                                                                   | `0`         |
| `grayscale`   | Power of grayscale effect. 0 is off. 1 is full grayscale.                                                                                                                                                                    | `0`         |
| `toneMapped`  | Whether this material is tone mapped according to the renderers toneMapping settings. [See THREE.material.tonemapped](https://threejs.org/docs/?q=material#api/en/materials/Material.toneMapped){rel="&#x22;nofollow&#x22;"} | `0`         |
| `transparent` | Whether the image material should be transparent. [See THREE.material.transparent](https://threejs.org/docs/?q=material#api/en/materials/Material.transparent){rel="&#x22;nofollow&#x22;"}                                   | `false`     |
| `transparent` | Whether the image material should be transparent. [See THREE.material.transparent](https://threejs.org/docs/?q=material#api/en/materials/Material.transparent){rel="&#x22;nofollow&#x22;"}                                   | `false`     |
| `opacity`     | Opacity of the image material. [See THREE.material.transparent](https://threejs.org/docs/?q=material#api/en/materials/Material.transparent){rel="&#x22;nofollow&#x22;"}                                                      | `1`         |
| `side`        | THREE.Side of the image material. [See THREE.material.side](https://threejs.org/docs/?q=material#api/en/materials/Material.side){rel="&#x22;nofollow&#x22;"}                                                                 | `FrontSide` |
| `texture`     | Image texture to display on the geometry.                                                                                                                                                                                    |             |
| `url`         | Image URL to load and display on the geometry.                                                                                                                                                                               |             |

## Caveats

By default, images loaded via the `url` prop use the renderer’s output color space. For advanced control, pass a `THREE.Texture` via the `texture` prop and set its `colorSpace` (e.g., `THREE.SRGBColorSpace` or `THREE.LinearSRGBColorSpace`).

```vue
<script setup>
import { useTexture } from '@tresjs/cientos'
import { SRGBColorSpace } from 'three'

const { state } = useTexture(URL)
watch(state, (texture) => {
  texture.colorSpace = SRGBColorSpace // assign a custom color space
})
</script>

<template>
  <Image :texture="texture" />
</template>
```


# Objects

Components for creating 3D objects, sprites, text, and textures in your scene.

:api-list{list-name="objects-list"}


# MarchingCubes

::scene-controls-wrapper
:objects-marching-cubes
::

`<MarchingCubes />` is a wrapper around [THREE's Marching Cubes](https://threejs.org/examples/#webgl_marchingcubes){rel="&#x22;nofollow&#x22;"}.

It includes 3 components:

- `<MarchingCubes />` – container element for `<MarchingCube />`s and `<MarchingPlane />`s
- `<MarchingCube />` - an individual metaball
- `<MarchingPlane />` – optional bounding plane that interacts with the metaballs

## Usage

```vue {2,15-23}
<script setup lang="ts">
import { MarchingCube, MarchingCubes, MarchingPlane, OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import { NoToneMapping, Vector3 } from 'three'

const rand = () => (Math.random() - 0.5) * 1.25
const positions = Array.from({ length: 40 }, () => new Vector3(rand(), rand(), rand()))
</script>

<template>
  <TresCanvas clear-color="#222" :tone-mapping="NoToneMapping">
    <TresPerspectiveCamera />
    <OrbitControls />

    <MarchingCubes :resolution="40" :max-poly-count="40000">
      <MarchingPlane plane-type="y" />
      <MarchingCube
        v-for="position, i of positions"
        :key="i"
        :position="position"
      />
      <TresMeshPhongMaterial specular="#111111" :shininess="30" color="#049ef4" :reflectivity="1" />
    </MarchingCubes>

    <TresAxesHelper />
    <TresDirectionalLight color="#ffffff" :intensity="3" :position="[0, 200, 0]" />
    <TresDirectionalLight color="#ffffff" :intensity="3" :position="[100, 200, 100]" />
  </TresCanvas>
</template>
```

## Props

| Prop           | Description                                                                                                              | Default |
| :------------- | :----------------------------------------------------------------------------------------------------------------------- | ------- |
| `resolution`   | Resolution of the marching cube field. Higher resolution produces smoother meshes at the cost of performance and memory. | `28`    |
| `maxPolyCount` | Maximum number of polygons to generate.                                                                                  | `10000` |
| `enableUvs`    | Whether UVs are enabled.                                                                                                 | `false` |
| `enableColors` | Whether vertex colors are enabled.                                                                                       | `false` |

## MarchingCube Props

| Prop       | Description                                             | Default |
| :--------- | :------------------------------------------------------ | ------- |
| `strength` | How strongly this cube affects the marching cube field. | `0.5`   |
| `subtract` | How quickly strength moves to `0` over distance.        | `12`    |

## MarchingPlane Props

| Prop        | Description                                              | Default |
| :---------- | :------------------------------------------------------- | ------- |
| `planeType` | Which axis the plane appears on. `'x' | 'y' | 'z'`       | `'x'`   |
| `strength`  | How strongly this plane affects the marching cube field. | `0.5`   |
| `subtract`  | How quickly strength moves to `0` over distance.         | `12`    |


# Reflector

::scene-controls-wrapper
:objects-reflector
::

The `cientos` package provides an abstraction of the [Reflector class](https://github.com/mrdoob/three.js/blob/dev/examples/jsm/objects/Reflector.js){rel="&#x22;nofollow&#x22;"}, which creates a Mesh showing a real-time reflection of your scene. This Mesh extends from `Mesh` so all the default props can be passed as well:

## Usage

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

<template>
  <TresCanvas shadows alpha>
    <TresPerspectiveCamera :position="[0, 0, 3]" />
    <OrbitControls />

    <Suspense>
      <Reflector
        :rotation="[-Math.PI * 0.5, 0, 0]"
        :position-y="-2"
        color="#fff"
      >
        <TresCircleGeometry :args="[10, 10]" />
      </Reflector>
    </Suspense>
  </TresCanvas>
</template>
```

## Props

| Prop              | Description                                          | Default                   |
| :---------------- | :--------------------------------------------------- | ------------------------- |
| **color**         | The base color that's combine with the mirror effect | '#333'                    |
| **textureWidth**  | the width of the texture to render on the mirror     | 512                       |
| **textureHeight** | the height of the texture to render on the mirror    | 512                       |
| **clipBias**      | to use the clipBias property                         | 0                         |
| **multisample**   | how many samplers will be render                     | 4                         |
| **shader**        | The texture of the smoke.                            | Reflector.ReflectorShader |

::prose-warning
All the props except the `color`, are not reactive
::

## Custom mirror effect

You can provide your own shader by passing a full shader object with `uniforms`, `vertexShader`, and `fragmentShader`. The example below adds animated circular ripples emanating from the center of the surface, while preserving the color tint:

```vue
<script setup lang="ts">
import { Reflector } from '@tresjs/cientos'
import { useLoop } from '@tresjs/core'
import { shallowRef } from 'vue'

const reflectorRef = shallowRef()

const customShader = {
  uniforms: {
    color: { value: null },
    tDiffuse: { value: null },
    textureMatrix: { value: null },
    time: { value: 0 },
  },
  vertexShader: /* glsl */`
    uniform mat4 textureMatrix;
    varying vec4 vUv;
    varying vec2 vPos;
    void main() {
      vUv = textureMatrix * vec4(position, 1.0);
      vPos = position.xy;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }`,
  fragmentShader: /* glsl */`
    uniform vec3 color;
    uniform sampler2D tDiffuse;
    uniform float time;
    varying vec4 vUv;
    varying vec2 vPos;
    float blendOverlay(float base, float blend) {
      return(base < 0.5 ? (2.0 * base * blend) : (1.0 - 2.0 * (1.0 - base) * (1.0 - blend)));
    }
    vec3 blendOverlay(vec3 base, vec3 blend) {
      return vec3(blendOverlay(base.r, blend.r), blendOverlay(base.g, blend.g), blendOverlay(base.b, blend.b));
    }
    void main() {
      float dist = length(vPos);
      float wave = sin(dist * 6.0 - time * 4.0) * 0.02;
      vec2 dir = dist > 0.001 ? normalize(vPos) : vec2(0.0);
      vec4 distortedUv = vUv + vec4(dir * wave, 0.0, 0.0);
      vec4 base = texture2DProj(tDiffuse, distortedUv);
      gl_FragColor = vec4(blendOverlay(base.rgb, color), 1.0);
      #include <tonemapping_fragment>
      #include <colorspace_fragment>
    }`,
}

const { onBeforeRender } = useLoop()
onBeforeRender(({ elapsed }) => {
  const uniforms = reflectorRef.value?.instance?.material?.uniforms
  if (uniforms?.time) { uniforms.time.value = elapsed }
})
</script>

<template>
  <Reflector
    ref="reflectorRef"
    :rotation="[-Math.PI * 0.5, 0, 0]"
    :position-y="-2"
    color="#fff"
    :shader="customShader"
  >
    <TresCircleGeometry :args="[10, 10]" />
  </Reflector>
</template>
```

The Reflector shader use the following configuration by default:

You can extend, modify or just play with them

### Default shader

```js
const shader = {
  name: 'ReflectorShader',
  uniforms: {
    color: {
      value: null
    },
    tDiffuse: {
      value: null
    },
    textureMatrix: {
      value: null
    }
  },
  vertexShader: /* glsl */`
  uniform mat4 textureMatrix;
  varying vec4 vUv;

  #include <common>
  #include <logdepthbuf_pars_vertex>

  void main() {
    vUv = textureMatrix * vec4( position, 1.0 );
    gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );

    #include <logdepthbuf_vertex>

  }`,
  fragmentShader: /* glsl */`
  uniform vec3 color;
  uniform sampler2D tDiffuse;
  varying vec4 vUv;

  #include <logdepthbuf_pars_fragment>

  float blendOverlay( float base, float blend ) {
    return( base < 0.5 ? ( 2.0 * base * blend ) : ( 1.0 - 2.0 * ( 1.0 - base ) * ( 1.0 - blend ) ) );
  }

  vec3 blendOverlay( vec3 base, vec3 blend ) {
    return vec3( blendOverlay( base.r, blend.r ), blendOverlay( base.g, blend.g ), blendOverlay( base.b, blend.b ) );
  }

  void main() {
    #include <logdepthbuf_fragment>

    vec4 base = texture2DProj( tDiffuse, vUv );
    gl_FragColor = vec4( blendOverlay( base.rgb, color ), 1.0 );

    #include <tonemapping_fragment>
    #include <colorspace_fragment>
  }`

}
```


# Refractor

::scene-controls-wrapper
:objects-refractor
::

The `cientos` package provides an abstraction of the [Refractor class](https://github.com/mrdoob/three.js/blob/dev/examples/jsm/objects/Refractor.js){rel="&#x22;nofollow&#x22;"}, which creates a Mesh that renders what is behind it with a refractive distortion effect — useful for glass panels, water surfaces, and other transmissive materials. This Mesh extends from `Mesh` so all the default props can be passed as well.

## Usage

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

<template>
  <TresCanvas shadows alpha>
    <TresPerspectiveCamera :position="[0, 2, 8]" />
    <OrbitControls />

    <!-- Place objects behind the refracting plane -->
    <TresMesh :position="[-2, 0, -2]">
      <TresTorusKnotGeometry />
      <TresMeshStandardMaterial color="hotpink" />
    </TresMesh>

    <Suspense>
      <Refractor color="#9ec8d4">
        <TresPlaneGeometry :args="[8, 5]" />
      </Refractor>
    </Suspense>
  </TresCanvas>
</template>
```

## Props

| Prop              | Description                                          | Default                     |
| :---------------- | :--------------------------------------------------- | --------------------------- |
| **color**         | Color tint blended with the refracted image          | `'#7f7f7f'`                 |
| **textureWidth**  | Width of the internal render target texture          | `512`                       |
| **textureHeight** | Height of the internal render target texture         | `512`                       |
| **clipBias**      | Clip bias for the virtual camera projection          | `0`                         |
| **multisample**   | Number of MSAA samples for the render target         | `4`                         |
| **shader**        | Custom shader object to override the built-in shader | `Refractor.RefractorShader` |

::prose-warning
All the props except `color` are not reactive
::

## Custom refraction effect

You can provide your own shader by passing a full shader object with `uniforms`, `vertexShader`, and `fragmentShader`. The example below adds animated circular ripples emanating from the center of the surface, while preserving the color tint:

```vue
<script setup lang="ts">
import { Refractor } from '@tresjs/cientos'
import { useLoop } from '@tresjs/core'
import { shallowRef } from 'vue'

const refractorRef = shallowRef()

const customShader = {
  uniforms: {
    color: { value: null },
    tDiffuse: { value: null },
    textureMatrix: { value: null },
    time: { value: 0 },
  },
  vertexShader: /* glsl */`
    uniform mat4 textureMatrix;
    varying vec4 vUv;
    varying vec2 vPos;
    void main() {
      vUv = textureMatrix * vec4(position, 1.0);
      vPos = position.xy;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }`,
  fragmentShader: /* glsl */`
    uniform vec3 color;
    uniform sampler2D tDiffuse;
    uniform float time;
    varying vec4 vUv;
    varying vec2 vPos;
    float blendOverlay(float base, float blend) {
      return(base < 0.5 ? (2.0 * base * blend) : (1.0 - 2.0 * (1.0 - base) * (1.0 - blend)));
    }
    vec3 blendOverlay(vec3 base, vec3 blend) {
      return vec3(blendOverlay(base.r, blend.r), blendOverlay(base.g, blend.g), blendOverlay(base.b, blend.b));
    }
    void main() {
      float dist = length(vPos);
      float wave = sin(dist * 6.0 - time * 4.0) * 0.02;
      vec2 dir = dist > 0.001 ? normalize(vPos) : vec2(0.0);
      vec4 distortedUv = vUv + vec4(dir * wave, 0.0, 0.0);
      vec4 base = texture2DProj(tDiffuse, distortedUv);
      gl_FragColor = vec4(blendOverlay(base.rgb, color), 1.0);
      #include <tonemapping_fragment>
      #include <colorspace_fragment>
    }`,
}

const { onBeforeRender } = useLoop()
onBeforeRender(({ elapsed }) => {
  const uniforms = refractorRef.value?.instance?.material?.uniforms
  if (uniforms?.time) { uniforms.time.value = elapsed }
})
</script>

<template>
  <Refractor
    ref="refractorRef"
    color="#9ec8d4"
    :shader="customShader"
  >
    <TresPlaneGeometry :args="[8, 5]" />
  </Refractor>
</template>
```

The Refractor shader uses the following configuration by default:

### Default shader

```js
const shader = {
  uniforms: {
    color: {
      value: null
    },
    tDiffuse: {
      value: null
    },
    textureMatrix: {
      value: null
    }
  },
  vertexShader: /* glsl */`
    uniform mat4 textureMatrix;
    varying vec4 vUv;

    void main() {
      vUv = textureMatrix * vec4( position, 1.0 );
      gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
    }`,
  fragmentShader: /* glsl */`
    uniform vec3 color;
    uniform sampler2D tDiffuse;
    varying vec4 vUv;

    float blendOverlay( float base, float blend ) {
      return( base < 0.5 ? ( 2.0 * base * blend ) : ( 1.0 - 2.0 * ( 1.0 - base ) * ( 1.0 - blend ) ) );
    }

    vec3 blendOverlay( vec3 base, vec3 blend ) {
      return vec3( blendOverlay( base.r, blend.r ), blendOverlay( base.g, blend.g ), blendOverlay( base.b, blend.b ) );
    }

    void main() {
      vec4 base = texture2DProj( tDiffuse, vUv );
      gl_FragColor = vec4( blendOverlay( base.rgb, color ), 1.0 );

      #include <tonemapping_fragment>
      #include <colorspace_fragment>
    }`
}
```


# Text3D

::scene-controls-wrapper
:objects-text
::

`<Text3D />` is a component that renders text in 3D. It is a wrapper around the [TextGeometry](https://threejs.org/docs/#api/en/geometries/TextGeometry){rel="&#x22;nofollow&#x22;"} class.

## Usage

To use the `<Text3D />` component you need to pass the `font` prop with the URL of the font JSON file you want to use. TextGeometry uses `typeface`.json generated fonts, you can generate yours [here](http://gero3.github.io/facetype.js/){rel="&#x22;nofollow&#x22;"}

```vue
<template>
  <TresCanvas>
    <Suspense>
      <Text3D
        text="TresJS"
        font="/fonts/FiraCodeRegular.json"
      >
        <TresMeshNormalMaterial />
      </Text3D>
    </Suspense>
  </TresCanvas>
</template>
```

Notice that you need to pass the `<TresMeshNormalMaterial />` component as a child of the `<Text3D />` component. This is because `<Text3D />` is a `Mesh` component, so it needs a material. The geometry is created automatically. Also you can pass the text as a slot or as a prop like this:

```vue
<template>
  <TresCanvas>
    <Suspense>
      <Text3D font="/fonts/FiraCodeRegular.json">
        TresJS
        <TresMeshNormalMaterial />
      </Text3D>
    </Suspense>
  </TresCanvas>
</template>
```

In addition, you can use the power of Vue to add reactivity, but you need to apply the needUpdates prop, for example you can create a reactive value, apply a v-model and make the bound, the Text3D component will update

```vue
<template>
  <input v-model="myReactiveText" />
  <TresCanvas>
    <Suspense>
      <Text3D
        :text="myReactiveText"
        font="/fonts/FiraCodeRegular.json"
        center
        need-updates
      />
    </Suspense>
  </TresCanvas>
</template>
```

## Props

| Prop               | Description                                                            | Default |
| :----------------- | :--------------------------------------------------------------------- | ------- |
| **font**           | The font data or font name to use for the text.                        |         |
| **text**           | The text to display.                                                   |         |
| **size**           | The size of the text.                                                  | 0.5     |
| **height**         | The height of the text.                                                | 0.2     |
| **curveSegments**  | The number of curve segments to use when generating the text geometry. | 5       |
| **bevelEnabled**   | A flag indicating whether beveling should be enabled for the text.     | true    |
| **bevelThickness** | The thickness of the beveled edge on the text.                         | 0.05    |
| **bevelSize**      | The size of the beveled edge on the text.                              | 0.02    |
| **bevelOffset**    | The offset of the beveled edge on the text.                            | 0       |
| **bevelSegments**  | The number of bevel segments to use when generating the text geometry. | 4       |
| **center**         | To center the text                                                     | false   |
| **needUpdates**    | This props add reactivity                                              | false   |


# All

## 📦 Abstraction

:api-list{list-name="abstraction-list" path="/api/abstractions"}

## 🎮 Controls

:api-list{list-name="controls-list" path="/api/controls"}

## 📂 Loaders

:api-list{list-name="loaders-list" path="/api/loaders"}

## 🎨 Materials

:api-list{list-name="materials-list" path="/api/materials"}

## 🔷 Shapes

:api-list{list-name="shapes-list" path="/api/shapes"}

## 📊 Debug & Performance

:api-list{list-name="debug-list" path="/api/debug-performance"}

## 💡 Light & Shadow

:api-list{list-name="light-list" path="/api/light-shadow"}

## 🎭 Staging

:api-list{list-name="staging-list" path="/api/staging"}

## 🎬 Objects

:api-list{list-name="objects-list" path="/api/objects"}

## 🛠️ Miscellaneous

:api-list{list-name="misc-list" path="/api/miscellaneous"}


# Bounds

::scene-wrapper
:miscellaneous-bounds
::

Calculates a boundary box and centers the camera accordingly. Its `lookAt` method accepts a target to look at imperatively e.g., after a click.

::prose-note
If you are using other camera controls, be sure to make them the 'default'.

```vue
<OrbitControls make-default />
```
::

## Usage

```vue {3,6-7,9-11,18,23}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { Bounds, OrbitControls } from '@tresjs/cientos'
import { shallowRef } from 'vue'

const boundsRef = shallowRef()
const objectRef = shallowRef()

function focusObject() {
  boundsRef.value?.instance.lookAt(objectRef.value)
}
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 2, 5]" />
    <OrbitControls make-default />
    <Bounds ref="boundsRef" clip use-mounted :offset="0.75">
      <TresMesh ref="objectRef" @click="(e) => focusObject()">
        <TresBoxGeometry />
        <TresMeshNormalMaterial />
      </TresMesh>
    </Bounds>
  </TresCanvas>
</template>
```

## Props

| Name         | Description                                                                                | Default        |
| :----------- | :----------------------------------------------------------------------------------------- | -------------- |
| `duration`   | Duration of the `lookAt` animation in seconds                                              | `1.0`          |
| `offset`     | Additional distance from the target when using `lookAt` with a `Box3` or `Object3D`        | `0.2`          |
| `useResize`  | Whether to re`lookAt` the last target when the screen is resized                           | `false`        |
| `useMounted` | Whether to `lookAt` the `Bounds` object when the component is mounts                       | `false`        |
| `clip`       | Whether to adjust the camera's `near` and `far` settings when using `lookAt`               | `false`        |
| `easing`     | Animation's easing function. `t` and the returned value should be in the interval `[0, 1]` | Cubic ease out |

## lookAt

`<Bounds />` `lookAt` points the camera at its first argument: an `Object3D`, `Box3` or `Vector3`.

### Method Signatures

```text
/**
 * Calculates a boundary box around an `Object3D` and centers the camera accordingly.
 */
lookAt(object: Object3D): void

/**
 * Calculates a boundary box around an `Object3D` and centers the camera accordingly and animates the camera's `up` vector.
 */
lookAt(object: Object3D, up: VectorFlexibleParams): void

/**
 * Centers the camera's viewport on a `Box3`.
 */
lookAt(box3: Box3): void

/**
 * Centers the camera's viewport on a `Box3` and animates the camera's `up` vector.
 */
lookAt(box3: Box3, up: VectorFlexibleParams): void

/**
 * Look at a `Vector3`.
 */
lookAt(target: VectorFlexibleParams): void

/**
 * Look at a `Vector3`, if provided. Move the camera to `position`.
 */
lookAt(target: VectorFlexibleParams | undefined | null, position: VectorFlexibleParams): void

/**
 * Look at a `Vector3`, if provided. Move the camera to `position` and animate the camera's `up` vector.
 */
lookAt(target: VectorFlexibleParams | undefined | null, position: VectorFlexibleParams, up: VectorFlexibleParams): void

/**
 * Rerun `lookAt` using the prior arguments. If `lookAt` has never been called, uses the `Bounds` object.
 */
lookAt(): void
```


# GlobalAudio

The `cientos` package provides a `<GlobalAudio />` component that serves to easily add a global sound to your scene.

Reference: [Audio](https://threejs.org/docs/index.html?q=audio#api/en/audio/Audio){rel="&#x22;nofollow&#x22;"}

## Usage

```vue {3,9}
<script setup>
import { TresCanvas } from '@tresjs/core'
import { GlobalAudio } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas>
    <TresPerspectiveCamera :position="[0, 0, 7.5]" />
    <GlobalAudio :src="exampleAudio" />
  </TresCanvas>
</template>
```

\*The `src` prop is required

## Props

| Prop           | Description                                              | Default               |
| :------------- | :------------------------------------------------------- | --------------------- |
| `src`          | Path to your audio file                                  |                       |
| `playTrigger`  | Id of the DOM element that triggers the play/pause state | `renderer.domElement` |
| `stopTrigger`  | Id of the DOM element that triggers the stop state       |                       |
| `loop`         | If the audio must be replayed when ends                  | `false`               |
| `volume`       | Volume of the audio                                      | `0.5`                 |
| `playbackRate` | PlaybackRate of the audio                                | `1`                   |

## Events

| Event       | Description                                                      |
| :---------- | :--------------------------------------------------------------- |
| `isPlaying` | Dispatched when the Audio change its state (play, pause or stop) |


# Miscellaneous

Utility components and composables for audio, animations, intersections, and more.

:api-list{list-name="misc-list"}


# MouseParallax

::scene-controls-wrapper
:miscellaneous-mouse-parallax
::

`<MouseParallax />` is a component that allows you to easily create a [parallax](https://en.wikipedia.org/wiki/Parallax){rel="&#x22;nofollow&#x22;"} effect. The camera will update automatically according to the mouse position.

## Usage

You only need to import and add it to your template as `<MouseParallax />`. Additionally, you can pass the following props:

`factor` is a number to increase the movement range of the camera. This could be an array of two values corresponding to the x and y values, in that order: `:factor=[x,y]`.

`ease` is a number that smooths the movement. This could be an array of two values corresponding to the x and y values, in that order: `:ease=[x,y]`.

`local` is a boolean that enables movement based on the position of the mouse on the canvas rather than the window.

```vue {2,12}
<script setup lang="ts">
import { MouseParallax, TorusKnot } from "@tresjs/cientos";
import { TresCanvas } from "@tresjs/core";
</script>

<template>
  <TresCanvas clear-color="#82DBC5">
    <TresPerspectiveCamera :position="[0, 0, 7.5]" :fov="75" />
    <TorusKnot>
      <TresMeshToonMaterial color="orange" />
    </TorusKnot>
    <MouseParallax :factor="5" :ease="[3, 0.1]" />
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
  </TresCanvas>
</template>
```

## Props

| Prop         | Description                                                                 | Default |
| :----------- | :-------------------------------------------------------------------------- | ------- |
| **disabled** | Enable or disable the effect                                                | false   |
| **factor**   | Increase the range of the parallax                                          | 2.5     |
| **ease**     | Increase the camera movement speed                                          | 0.1     |
| **local**    | Whether the mouse coordinates are calculated from the element or the window | false   |


# PositionalAudio

::scene-controls-wrapper
:miscellaneous-positional-audio
::

The `cientos` package provides an abstraction of the [PositionalAudio](https://threejs.org/docs/index.html?q=posi#api/en/audio/PositionalAudio){rel="&#x22;nofollow&#x22;"}.
`<PositionalAudio>` is an object specifically designed for controlling sounds in a scene graph space. This allows, for the simulation of various audio environments, creating a more immersive user experience.

`<PositionalAudio>` includes a helper 🛠️ that allows you to view the directional cone of te audio. The helper is based on the [PositionalAudioHelper](https://threejs.org/docs/#examples/en/helpers/PositionalAudioHelper){rel="&#x22;nofollow&#x22;"} class.

## Usage

The `<PositionalAudio>` component is very simple to set up and use, allowing you to bring your 3D scenes to life. All you need to do is call the `<PositionalAudio>` component and set the `url`. It must be wrapped around the `<Suspense>` component to enable it to load your audio asynchronously. 💥

```vue {2,17-19}
<script setup lang="ts">
import { Box, PositionalAudio } from '@tresjs/cientos'
import { onUnmounted, shallowRef } from 'vue'

const positionalAudioRef = shallowRef(null)

onUnmounted(() => {
  positionalAudioRef?.value?.dispose()
})
</script>

<template>
  <TresCanvas>
    <Box :args="[1, 1, 1]">
      <TresMeshNormalMaterial />
      <Suspense>
        <PositionalAudio
          ref="positionalAudioRef"
          url="your-sound.mp3"
        />
      </Suspense>
    </Box>
  </TresCanvas>
</template>
```

::prose-warning
AudioContext is authorized when a user gesture has been made on the page. The property `:autoplay="true"` cannot be activated if no user gesture has been made previously [`read more`](https://goo.gl/7K7WLu){rel=""nofollow""}.
If you are sure that there will be a user gesture before your `<PositionAudio>` component appears/is created, you can directly add `:ready="true"` and `autoplay="true"` for a direct launch.
::

## How does it work?

![Diagram explaining how positional audio works](https://cientos.tresjs.org/cientos/sketch.jpg){.mx-auto}

## Props

| Prop           | Description                                                                                                                                                                                                                                                                             | Default |
| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **url**        | `string` - **required** — The path or URL to the file.                                                                                                                                                                                                                                  |         |
| **helper**     | `boolean` — Selects whether helper mode is enabled. :b&#x72; &#x2A;(Useful for visualising the angle of sound propagation)*                                                                                                                                                             | `false` |
| **distance**   | `number&#x60; — The distance at which the volume reduction starts taking effect. &#x2A;**A non-negative number.***                                                                                                                                                                      | `1`     |
| **ready**      | `boolean` — Tells `<PositionalAudio>` that `AudioContext` is authorised because an user gesture has been made on the page. This is imperative, as `autoplay` cannot be activated if no user gesture has been made previously (<https://goo.gl/7K7WLu>{rel="&#x22;nofollow&#x22;"}). :br | `false` |
| **autoplay**   | `boolean` — Selects whether the audio is launched automatically. Please refer to the `ready` prop for a better understanding of how to use autoplay.                                                                                                                                    | `false` |
| **loop**       | `boolean` — Specifies whether the audio should loop.                                                                                                                                                                                                                                    | `false` |
| **innerAngle** | `number` — A parameter for directional audio sources, this is an angle, inside of which there will be no volume reduction.                                                                                                                                                              | `360`   |
| **outerAngle** | `number` — A parameter for directional audio sources, this is an angle, outside of which the volume will be reduced to a constant value of `outerGain` prop.                                                                                                                            | `0`     |
| **outerGain**  | `number` — A parameter for directional audio sources, this is the amount of volume reduction outside of the `outerAngle` prop. When the value is `0` no sound can be heard.                                                                                                             | `0`     |

## Exposed properties

| Event       | Description                                                                                                                                                  |
| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `instance`  | Instance reference — Inheritance of [PositionalAudio](https://threejs.org/docs/index.html?q=posi#api/en/audio/PositionalAudio){rel="&#x22;nofollow&#x22;"}.  |
| `play()`    | Play audio — &#x2A;Cannot be fired if audio is already running.*                                                                                             |
| `pause()`   | Pause audio — &#x2A;Cannot be fired if audio is already paused.*                                                                                             |
| `stop()`    | Stop audio — &#x2A;Cannot be fired if audio is already stopped.*                                                                                             |
| `dispose()` | Dispose component — Deletion of the AudioListener in the camera, disconnection of the audio source and deletion of the PositionalAudioHelper (if it exists). |

```typescript
const positionalAudioRef = shallowRef(null)

console.log(positionalAudioRef.value.instance) // instance properties

const handlerAudio = (action: string) => {
  if (!positionalAudioRef.value) { return }

  const { play, pause, stop } = positionalAudioRef.value

  if (action === 'play') { play() }
  else if (action === 'pause') { pause() }
  else if (action === 'stop') { stop() }
}
```

```vue
<template>
  <button @click="handlerAudio('play')">play</button>
  <button @click="handlerAudio('pause')">pause</button>
  <button @click="handlerAudio('stop')">stop</button>

  <TresCanvas>
    <Sphere>
      <Suspense>
        <PositionalAudio />
      </Suspense>
    </Sphere>
  </TresCanvas>
</template>
```

## Events

| Event        | Description                                                                                                       |
| :----------- | :---------------------------------------------------------------------------------------------------------------- |
| `is-playing` | Triggered when the audio changes its state (play, pause, or stop) :br `@is-playing="(e) => yourIsPlayingRef = e"` |


# useAnimations

`useAnimations` is a composable that returns a `shallowReactive` with all the models actions based on the animations provided. It is a wrapper around the [AnimationMixer](https://threejs.org/docs/#api/en/animation/AnimationMixer){rel="&#x22;nofollow&#x22;"} class.

## Usage

### Basic Usage (Automatic Updates)

By default, `useAnimations` automatically updates the animation mixer on each frame using the `useLoop` composable:

```ts {1,7}
import { useAnimations, useGLTF } from '@tresjs/cientos'

const { state } = useGLTF('/models/ugly-naked-bunny.gltf')

const animations = computed(() => state.value?.animations || [])
const model = computed(() => state?.value?.scene)
const { actions } = useAnimations(animations, model)

const currentAction = ref()

watch(actions, (newActions) => {
  currentAction.value = newActions.Greeting
  currentAction.value.play()
})
```

### Manual Updates

To gain finer control over animation mixer updates, enable `manualUpdate: true` and manage the update cycle manually.

```ts {1,8-10,15}
import { useAnimations, useGLTF } from '@tresjs/cientos'
import { useLoop } from '@tresjs/core'

const { state } = useGLTF('/models/ugly-naked-bunny.gltf')

const animations = computed(() => state.value?.animations || [])
const model = computed(() => state?.value?.scene)
const { actions, mixer } = useAnimations(animations, model, {
  manualUpdate: true,
})

// Handle updates manually
const { onBeforeRender } = useLoop()
onBeforeRender(({ delta }) => {
  mixer.value.update(delta)
})

const currentAction = ref()

watch(actions, (newActions) => {
  currentAction.value = newActions.Greeting
  currentAction.value.play()
})
```

## Options

- `manualUpdate` (optional): Default is `false`. If set to `true`, disables automatic animation mixer updates. You'll need to call `mixer.value.update(delta)` manually.


# useGLTFExporter

[GLTFExporter](https://threejs.org/docs/index.html?q=expo#examples/en/exporters/GLTFExporter){rel="&#x22;nofollow&#x22;"} is an addon in Three.js that allows you to download any object3D in a [GLTF](https://www.khronos.org/gltf){rel="&#x22;nofollow&#x22;"} format. **TresJS** provides a composable that simplifies this process with just a few lines of code.

## Basic usage

```vue {3,10}
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { useGLTFExporter } from '@tresjs/cientos'
import { shallowRef } from 'vue'

const boxRef = shallowRef()

// the second argument – options – is not required
const downloadBox = () => {
  useGLTFExporter(boxRef.value, { fileName: 'cube', binary: true })
}
</script>
<template>
  <TresCanvas clear-color="#82DBC5" window-size >
    <TresPerspectiveCamera :position="[0, 2, 5]" />
    <TresMesh
      ref="boxRef"
      :position-z="30"
      :scale="10"
      @click="downloadBox"
    >
      <TresBoxGeometry :args="[1, 1, 1]" />
      <TresMeshStandardMaterial :color="0x00ff00" />
    </TresMesh>
    <TresDirectionalLight :position="[0, 10, 10]" />
  </TresCanvas>
</template>

```

## Arguments

| Name         | Type       | Default     | Description                                          |
| :----------- | ---------- | ----------- | ---------------------------------------------------- |
| **Selector** | `Object3D` | Required    | The object to download. Could be an array of objects |
| **Options**  | `Options`  | `undefined` | Description below                                    |

### Options

| Name                        | Type                   | Default       | Description                                                                  |
| :-------------------------- | :--------------------- | :------------ | :--------------------------------------------------------------------------- |
| **trs**                     | `bool`                 | `false`       | Export position, rotation and scale instead of matrix per node               |
| **onlyVisible**             | `bool`                 | `true`        | Export only visible objects                                                  |
| **binary**                  | `bool`                 | `false`       | Export in binary (.glb) format, returning an ArrayBuffer                     |
| **maxTextureSize**          | `number`               | `Infinity`    | Restricts the image maximum size (both width and height) to the given value  |
| **animations**              | `Array<AnimationClip>` | `undefined`   | List of animations to be included in the export                              |
| **includeCustomExtensions** | `bool`                 | `false`       | Export custom glTF extensions defined on an object's userData.gltfExtensions |
| **fileName**                | `string`               | `Object name` | Name of the generated file                                                   |


# useIntersect

`useIntersect` is a function that returns `intersect`, a `Ref<boolean>` that's updated when the observed object enters or leaves the screen. This relies on [THREE.Object3D.onBeforeRender](https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender){rel="&#x22;nofollow&#x22;"} so it only works on objects that are effectively rendered, like meshes, lines, sprites. It won't work on other types like group, object3d, bone, etc.

## Usage

::prose-warning
`useIntersect` requires a `TresCanvas` context, so it is only available in `TresCanvas` descendant components' `<script setup>`.
::

```vue {2,4}
<script setup lang="ts">
import { Torus, useIntersect } from '@tresjs/cientos'

const { ref, intersect, off } = useIntersect()
</script>

<template>
  <Torus ref="ref">
    <TresMeshNormalMaterial />
  </Torus>
</template>
```

## Arguments

| Name         | Description                                                                                | Type                               |
| :----------- | ------------------------------------------------------------------------------------------ | ---------------------------------- |
| **onChange** | Optional callback function triggered when the observed object enters or leaves the screen. | `(isIntersected: boolean) => void` |

## Return

| Name           | Description                                                     | Type                   |
| :------------- | --------------------------------------------------------------- | ---------------------- |
| **ref**        | Vue `ShallowRef` to pass to the object to be observed.          | `ShallowRef<Object3D>` |
| **intersects** | Updates when the observed object's intersect status changes.    | `ShallowRef<boolean>`  |
| **off**        | Calling this function stops `useIntersect` until `ref` changes. | `() => void`           |