================================================
FILE: docs/.vitepress/theme/components/TransformControlsDemo.vue
================================================
================================================
FILE: docs/.vitepress/theme/components/UseFBODemo.vue
================================================
================================================
FILE: docs/.vitepress/theme/components/UseFBXDemo.vue
================================================
================================================
FILE: docs/.vitepress/theme/components/UseGLTFDemo.vue
================================================
================================================
FILE: docs/.vitepress/theme/components/UseSurfaceSamplerDemo.vue
================================================
================================================
FILE: docs/.vitepress/theme/components/UseTextureDemo.vue
================================================
================================================
FILE: docs/.vitepress/theme/components/VideoTextureDemo.vue
================================================
================================================
FILE: docs/.vitepress/theme/components/WobbleMaterialDemo.vue
================================================
================================================
FILE: docs/.vitepress/theme/index.ts
================================================
// https://vitepress.dev/guide/custom-theme
import Theme from 'vitepress/theme'
import TresLayout from './TresLayout.vue'
import './style.css'
import 'uno.css'
export default {
...Theme,
Layout: TresLayout,
enhanceApp(ctx) {
Theme.enhanceApp(ctx)
/* ctx.app.use(plausible) */
},
}
================================================
FILE: docs/.vitepress/theme/style.css
================================================
:root {
--vp-home-hero-name-color: #82dbc5;
--vp-c-brand: #82dbc5;
--vp-c-dark: #1f1f1e;
}
/**
* Component: Button
* -------------------------------------------------------------------------- */
:root {
--vp-button-brand-border: var(--vp-c-brand-light);
--vp-button-brand-text: var(--vp-c-text-dark-1);
--vp-button-brand-text: var(--vp-c-dark);
--vp-button-brand-bg: var(--vp-c-brand);
--vp-button-brand-hover-border: var(--vp-c-brand-light);
--vp-button-brand-hover-text: var(--vp-c-text-dark-1);
--vp-button-brand-hover-text: var(--vp-c-dark);
--vp-button-brand-hover-bg: var(--vp-c-brand-light);
--vp-button-brand-active-border: var(--vp-c-brand-light);
--vp-button-brand-active-text: var(--vp-c-text-dark-1);
--vp-button-brand-active-text: var(--vp-c-dark);
--vp-button-brand-active-bg: var(--vp-button-brand-bg);
--vp-button-alt-border: var(--vp-c-gray-light-3);
--vp-button-alt-text: var(--vp-c-text-light-1);
--vp-button-alt-bg: var(--vp-c-gray-light-5);
--vp-button-alt-hover-border: var(--vp-c-gray-light-3);
--vp-button-alt-hover-text: var(--vp-c-text-light-1);
--vp-button-alt-hover-bg: var(--vp-c-gray-light-4);
--vp-button-alt-active-border: var(--vp-c-gray-light-3);
--vp-button-alt-active-text: var(--vp-c-text-light-1);
--vp-button-alt-active-bg: var(--vp-c-gray-light-3);
--vp-button-alt-border: var(--vp-c-border);
--vp-button-alt-text: var(--vp-c-neutral);
--vp-button-alt-bg: var(--vp-c-mute);
--vp-button-alt-hover-border: var(--vp-c-border);
--vp-button-alt-hover-text: var(--vp-c-neutral);
--vp-button-alt-hover-bg: var(--vp-c-mute-dark);
--vp-button-alt-active-border: var(--vp-c-border);
--vp-button-alt-active-text: var(--vp-c-neutral);
--vp-button-alt-active-bg: var(--vp-c-mute-darker);
--vp-button-sponsor-border: var(--vp-c-gray-light-3);
--vp-button-sponsor-text: var(--vp-c-text-light-2);
}
.VPSidebar .link.active span {
font-weight: bold;
}
.vp-doc a {
text-decoration: dashed;
font-weight: bold;
}
.VPButton.medium.brand {
color: var(--vp-button-brand-text);
}
.VPButton.medium.alt {
border-color: var(--vp-button-alt-border);
color: var(--vp-button-alt-text);
background-color: var(--vp-button-alt-bg);
}
.demo-scene {
height: auto;
margin: 2rem 0;
overflow: hidden;
aspect-ratio: 16/9;
border-radius: 8px;
}
================================================
FILE: docs/api-examples.md
================================================
---
outline: deep
---
# Runtime API Examples
This page demonstrates usage of some of the runtime APIs provided by VitePress.
The main `useData()` API can be used to access site, theme, and page data for the current page. It works in both `.md` and `.vue` files:
```md
## Results
### Theme Data
{{ theme }}
### Page Data
{{ page }}
### Page Frontmatter
{{ frontmatter }}
```
## Results
### Theme Data
{{ theme }}
### Page Data
{{ page }}
### Page Frontmatter
{{ frontmatter }}
## More
Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata).
================================================
FILE: docs/component-list/components.ts
================================================
export default [
{
text: 'Abstractions',
items: [
{ text: 'AnimatedSprite', link: '/guide/abstractions/animated-sprite' },
{ text: 'Edges', link: '/guide/abstractions/edges' },
{ text: 'Text3D', link: '/guide/abstractions/text-3d' },
{ text: 'Levioso (Float)', link: '/guide/abstractions/levioso' },
{ text: 'useAnimations', link: '/guide/abstractions/use-animations' },
{ text: 'MouseParallax', link: '/guide/abstractions/mouse-parallax' },
{ text: 'Lensflare', link: '/guide/abstractions/lensflare' },
{ text: 'Reflector', link: '/guide/abstractions/reflector' },
{ text: 'GlobalAudio', link: '/guide/abstractions/global-audio' },
{ text: 'Fbo', link: '/guide/abstractions/fbo' },
{ text: 'useFBO', link: '/guide/abstractions/use-fbo' },
{
text: 'useSurfaceSampler',
link: '/guide/abstractions/use-surface-sampler',
},
{ text: 'Sampler', link: '/guide/abstractions/sampler' },
{ text: 'PositionalAudio', link: '/guide/abstractions/positional-audio' },
{ text: 'MarchingCubes', link: '/guide/abstractions/marching-cubes' },
{ text: 'Mask', link: '/guide/abstractions/mask' },
{ text: 'CubeCamera', link: '/guide/abstractions/cube-camera' },
{ text: 'GradientTexture', link: '/guide/abstractions/gradient-texture' },
{ text: 'ScreenSizer', link: '/guide/abstractions/screen-sizer' },
{ text: 'ScreenSpace', link: '/guide/abstractions/screen-space' },
{ text: 'Outline', link: '/guide/abstractions/outline' },
{ text: 'Image', link: '/guide/abstractions/image' },
{ text: 'Billboard', link: '/guide/abstractions/billboard' },
],
},
{
text: 'Controls',
items: [
{ text: 'OrbitControls', link: '/guide/controls/orbit-controls' },
{ text: 'CameraControls', link: '/guide/controls/camera-controls' },
{ text: 'TransformControls', link: '/guide/controls/transform-controls' },
{
text: 'PointerLockControls',
link: '/guide/controls/pointer-lock-controls',
},
{ text: 'KeyboardControls', link: '/guide/controls/keyboard-controls' },
{ text: 'ScrollControls', link: '/guide/controls/scroll-controls' },
{ text: 'MapControls', link: '/guide/controls/map-controls' },
{ text: 'Helper', link: '/guide/controls/helper' },
],
},
{
text: 'Loaders',
items: [
{ text: 'useProgress', link: '/guide/loaders/use-progress' },
{ text: 'useGLTF', link: '/guide/loaders/use-gltf' },
{ text: 'GLTFModel', link: '/guide/loaders/gltf-model' },
{ text: 'useTexture', link: '/guide/loaders/use-texture' },
{ text: 'useTextures', link: '/guide/loaders/use-textures' },
{ text: 'useFBX', link: '/guide/loaders/use-fbx' },
{ text: 'FBXModel', link: '/guide/loaders/fbx-model' },
{ text: 'useVideoTexture', link: '/guide/loaders/use-video-texture' },
{ text: 'useSVG', link: '/guide/loaders/use-svg' },
],
},
{
text: 'Materials',
collapsed: true,
items: [
{ text: 'MeshReflectionMaterial', link: '/guide/materials/mesh-reflection-material' },
{ text: 'WobbleMaterial', link: '/guide/materials/wobble-material' },
{ text: 'MeshGlassMaterial', link: '/guide/materials/glass-material' },
{
text: 'CustomShaderMaterial',
link: '/guide/materials/custom-shader-material',
},
{
text: 'HolographicMaterial',
link: '/guide/materials/holographic-material',
},
{
text: 'PointMaterial',
link: '/guide/materials/point-material',
},
{
text: 'MeshDiscardMaterial',
link: '/guide/materials/mesh-discard-material',
},
],
},
{
text: 'Shapes',
collapsed: true,
items: [
{ text: 'Box', link: '/guide/shapes/box' },
{ text: 'CatmullRomCurve3', link: '/guide/shapes/catmullromcurve3' },
{ text: 'Circle', link: '/guide/shapes/circle' },
{ text: 'Cone', link: '/guide/shapes/cone' },
{ text: 'CubicBezierLine', link: '/guide/shapes/cubic-bezier-line' },
{ text: 'Cylinder', link: '/guide/shapes/cylinder' },
{ text: 'Dodecahedron', link: '/guide/shapes/dodecahedron' },
{ text: 'Icosahedron', link: '/guide/shapes/icosahedron' },
{ text: 'Line2', link: '/guide/shapes/line2' },
{ text: 'Octahedron', link: '/guide/shapes/octahedron' },
{ text: 'Plane', link: '/guide/shapes/plane' },
{ text: 'QuadraticBezierLine', link: '/guide/shapes/quadratic-bezier-line' },
{ text: 'Ring', link: '/guide/shapes/ring' },
{ text: 'RoundedBox', link: '/guide/shapes/rounded-box' },
{ text: 'ScreenQuad', link: '/guide/shapes/screen-quad' },
{ text: 'Sphere', link: '/guide/shapes/sphere' },
{ text: 'Superformula', link: '/guide/shapes/superformula' },
{ text: 'Tetrahedron', link: '/guide/shapes/tetrahedron' },
{ text: 'Torus', link: '/guide/shapes/torus' },
{ text: 'TorusKnot', link: '/guide/shapes/torus-knot' },
{ text: 'Tube', link: '/guide/shapes/tube' },
],
},
{
text: 'Staging',
items: [
{ text: 'Backdrop', link: '/guide/staging/backdrop' },
{ text: 'Environment', link: '/guide/staging/environment' },
{ text: 'useEnvironment', link: '/guide/staging/use-environment' },
{ text: 'Sky', link: '/guide/staging/sky' },
{ text: 'Stars', link: '/guide/staging/stars' },
{ text: 'Smoke', link: '/guide/staging/smoke' },
{ text: 'AccumulativeShadows', link: '/guide/staging/accumulative-shadows' },
{ text: 'ContactShadows', link: '/guide/staging/contact-shadows' },
{ text: 'Precipitation', link: '/guide/staging/precipitation' },
{ text: 'Sparkles', link: '/guide/staging/sparkles' },
{ text: 'Ocean', link: '/guide/staging/ocean' },
{ text: 'Fit', link: '/guide/staging/fit' },
{ text: 'Align', link: '/guide/staging/align' },
{ text: 'SoftShadows', link: '/guide/staging/soft-shadows' },
{ text: 'Grid', link: '/guide/staging/grid' },
{ text: 'CircleShadow', link: '/guide/staging/circle-shadow' },
{ text: 'Bounds', link: '/guide/staging/bounds' },
{ text: 'RandomizedLights', link: '/guide/staging/randomized-lights' },
{ text: 'Stage', link: '/guide/staging/stage' },
],
},
{
text: 'Misc',
collapsed: true,
items: [
{ text: 'Stats', link: '/guide/misc/stats' },
{ text: 'Html', link: '/guide/misc/html-component' },
{ text: 'StatsGl', link: '/guide/misc/stats-gl' },
{ text: 'useGLTFExporter', link: '/guide/misc/use-gltf-exporter' },
{ text: 'BakeShadows', link: '/guide/misc/bake-shadows' },
{ text: 'useIntersect', link: '/guide/misc/use-intersect' },
{ text: 'LOD', link: '/guide/misc/lod' },
],
},
] as { text: string, items: { text: string, link: string }[] }[]
export const icons = {
abstractions: '📦',
controls: '🕹️',
staging: '🎭',
loaders: '⏳',
materials: '👔',
directives: '📢',
shapes: '🔷',
misc: '🛠️',
}
================================================
FILE: docs/component-list/index.md
================================================
# Components
================================================
FILE: docs/guide/abstractions/animated-sprite.md
================================================
# AnimatedSprite
`` displays 2D animations defined in a [texture atlas](https://en.wikipedia.org/wiki/Texture_atlas). A typical `` will use:
* an image containing multiple sprites
* a JSON atlas containing the individual sprite coordinates in the image
## Usage
<<< @/.vitepress/theme/components/AnimatedSpriteDemo.vue{3,12-20}
::: warning Suspense
`` loads resources asynchronously, so it must be wrapped in a ``.
:::
## Compiling an atlas
In typical usage, `` 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)
* [example JSON atlas](https://raw.githubusercontent.com/Tresjs/assets/main/textures/animated-sprite/cientosAtlas.json)
Compiling source images into a texture atlas is usually handled by third-party software. You may find [TexturePacker](https://www.codeandweb.com/texturepacker) 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
::: 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 ``. 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: `[animation name][frame number].[extension]` 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.
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.
A "animation definition" comma-separated string of frame numbers with optional parentheses-surrounded durations.
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
true
center
TresVector2 – Anchor point of the object. A value of [0.5, 0.5] corresponds to the center. [0, 0] is left, bottom.
## 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.
`` 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 `` 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 |
Try it out by clicking a few times on the character below:
<<< @/.vitepress/theme/components/AnimatedSpriteNamedAnimationDemo.vue
## `definitions`
You can supply an object to the `:definitions` prop. Any [named animation](#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:
```
'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.
<<< @/.vitepress/theme/components/AnimatedSpriteDefinitionsDemo.vue{17-19}
## `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.
Below is a simple animation containing differently sized source images. The anchor is visible at world position `0, 0, 0`.
================================================
FILE: docs/guide/abstractions/billboard.md
================================================
# Billboard
Adds a `THREE.Group` that faces the camera.
## Usage
<<< @/.vitepress/theme/components/BillboardDemo.vue
## Props
| Prop | Description | Default |
| :--------------- | :--------------------------------------------------- | ------------- |
| `autoUpdate` | Whether the `` 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` |
================================================
FILE: docs/guide/abstractions/cube-camera.md
================================================
# 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.
`` makes its children invisible while rendering to the internal buffer so that they are not included in the reflection.
## Usage
<<< @/.vitepress/theme/components/CubeCameraDemo.vue
## 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 | |
================================================
FILE: docs/guide/abstractions/edges.md
================================================
# Edges
The `cientos` package provides an abstraction of [EdgesGeometry](https://threejs.org/docs/#api/en/geometries/EdgesGeometry) from Three.js, `` 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
<<< @/.vitepress/theme/components/EdgesDemo.vue
The `` component is easy to set up as it automatically derives geometry from its parent. You can simply wrap it around any [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Mesh](https://threejs.org/docs/#api/en/objects/Mesh), or [primitive](https://docs.tresjs.org/advanced/primitive.html) to automatically apply edge rendering. You can provide a custom material to ``. When a custom material is used, the color prop has no effect. *(see code bellow)*
```vue
```
## Props
`` is based on [LineSegments](https://threejs.org/docs/#api/en/objects/LineSegments) & [Line](https://threejs.org/docs/#api/en/objects/Line) and supports all of its props.
| Prop | Description | Default |
| :---------------- | :--------------------------------------------------- | ------------------------- |
| **color** | `THREE.Color` — Color of the edges. More informations : [TresColor](https://docs.tresjs.org/api/instances-arguments-and-props.html#colors) — [THREE.Color](https://threejs.org/docs/#api/en/math/Color) | `#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` |
## Exposed properties
| Event | Description |
| :---------- | :--------------------------------------------------------------- |
| `instance` | Instance reference — Inheritance of [LineSegments](https://threejs.org/docs/#api/en/objects/LineSegments).|
```typescript{1}
const edgesRef = shallowRef(null)
console.log(edgesRef.value.instance) // instance properties
```
```vue{2}
```
================================================
FILE: docs/guide/abstractions/fbo.md
================================================
# 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 `` component make it easy to use FBOs in your application.
## Usage
<<< @/.vitepress/theme/components/FboDemo.vue{3,15,48-51,58}
## 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). | `false` |
| **`settings`** | `WebGLRenderTargetOptions` - Every other configuration property for the [`WebGLRenderTarget` class](https://threejs.org/docs/#api/en/renderers/WebGLRenderTarget) | `{}` |
| **`autoRender`** | `boolean` - Whether to automatically render the FBO on the default scene. | `true` |
================================================
FILE: docs/guide/abstractions/global-audio.md
================================================
# GlobalAudio
The `cientos` package provides a `` 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)
## Usage
```vue{3,9}
```
*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) |
================================================
FILE: docs/guide/abstractions/gradient-texture.md
================================================
# GradientTexture
`` creates a gradient in a THREE.Texture and attaches it to its parent THREE.Material's `map` by default.
## Usage
<<< @/.vitepress/theme/components/GradientTextureDemo.vue
## 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'` |
================================================
FILE: docs/guide/abstractions/image.md
================================================
# Image
`` is a shader-based component that optionally loads then displays an image texture on a default plane or on your custom geometry.
## Usage
<<< @/.vitepress/theme/components/ImageDemo.vue
## Props
::: info
`` 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) | `0` |
| `transparent` | Whether the image material should be transparent. [See THREE.material.transparent](https://threejs.org/docs/?q=material#api/en/materials/Material.transparent) | `false` |
| `transparent` | Whether the image material should be transparent. [See THREE.material.transparent](https://threejs.org/docs/?q=material#api/en/materials/Material.transparent) | `false` |
| `opacity` | Opacity of the image material. [See THREE.material.transparent](https://threejs.org/docs/?q=material#api/en/materials/Material.transparent) | `1` |
| `side` | THREE.Side of the image material. [See THREE.material.side](https://threejs.org/docs/?q=material#api/en/materials/Material.side) | `FrontSide` |
| `texture` | Image texture to display on the geometry. | |
| `url` | Image URL to load and display on the geometry. | |
================================================
FILE: docs/guide/abstractions/lensflare.md
================================================
# Lensflare
`` wraps the [three.js Lensflare](https://threejs.org/docs/#examples/en/objects/Lensflare).
## Usage
```vue{3,9}
```
## Props
| Name | Description | Default |
| :--- | :---------- | :------ |
| **scale** | `number` – scale of the lensflare | `1.0` |
| **elements** | `Partial<LensflareElementProps>[]` – 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` |
| **distance** | `number` – default distance of lensflare elements from flare center | `undefined` |
| **size** | `number` – default size 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)[]`.
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). The PRNG is in turn used to build lensflare elements, by selecting values from an array of `SeedProps`.
::: info
If you set a `seed` but not `seedProps`, the component will fall back to the default, built-in `SeedProps[]`.
:::
### Example
```vue
```
Below, the results of setting `seedRef.value` to `0`, `1`, `2`, `3`, `4`, respectively.

## `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 |
::: info
If you set `seedProps` but not `seed`, the component will fall back to a default `seed` of `0`.
:::
## Random elements and non-random properties
`` 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
```
### Non-random properties
You can provide a list of lensflare element properties using the [`elements`](#elements) prop.
```vue
```
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
```
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](#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](#elements)
```vue
```
... by adding a [`seed` prop](#seed)
```vue
```
... by adding a [`seedProps` prop](#seedprops)
```vue
```
### Mixing random elements and non-random properties
You can mix your own properties and random elements.
```vue
```
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](#precedence).
:::info
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`, `distance`, `size`, `texture` – default element properties
3. `seed`, `seedProps` – generated random elements
4. built-in default element properties
::: info
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.
:::
:::details Precedence example
Here's an example of precedence. Assume this is in our vue template.
```vue
```
`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: 256, // from component prop `size`
texture: 'http://example.net/ring.png', // from component prop `texture`
},
{
color: 'red', // from component prop `color`
distance: 2, // from random element generator
size: 256, // from component prop `size`
texture: 'http://example.net/ring.png', // from component prop `texture`
},
]
```
:::
================================================
FILE: docs/guide/abstractions/levioso.md
================================================
# Levioso (Float)

The `cientos` package provides a `` wrapper that makes its content … float, just like Magic 🪄✨
## Usage
<<< @/.vitepress/theme/components/Feather.vue
## 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]` |
================================================
FILE: docs/guide/abstractions/marching-cubes.md
================================================
# MarchingCubes
`` is a wrapper around [THREE's Marching Cubes](https://threejs.org/examples/#webgl_marchingcubes).
It includes 3 components:
* `` – container element for ``s and ``s
* `` - an individual metaball
* `` – optional bounding plane that interacts with the metaballs
## Usage
<<< @/.vitepress/theme/components/MarchingCubesDemo.vue
## 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` |
## `` 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` |
## `` 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` |
================================================
FILE: docs/guide/abstractions/mask.md
================================================
# Mask
`` uses the stencil buffer to cut out areas of the screen.
::: warning
To use `` you *must* add `:stencil="true"` to your ``.
`` relies on the [stencil buffer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer). In recent versions of THREE.js, by default, the stencil buffer is not created.
:::
## Usage
<<< @/.vitepress/theme/components/MaskDemo.vue
## 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` |
================================================
FILE: docs/guide/abstractions/mouse-parallax.md
================================================
# MouseParallax
`` is a component that allows you to easily create a [parallax](https://en.wikipedia.org/wiki/Parallax) effect. The camera will update automatically according to the mouse position.
## Usage
You only need to import it and add it to your template as ``. 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.
<<< @/.vitepress/theme/components/MouseParallaxDemo.vue{3,15-18}
## 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 |
================================================
FILE: docs/guide/abstractions/outline.md
================================================
# Outline
`` creates an inverted-hull outline using its parent's geometry. Supported parents are `` and ``.
## Usage
<<< @/.vitepress/theme/components/OutlineDemo.vue
## 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) | `Math.PI` |
================================================
FILE: docs/guide/abstractions/positional-audio.md
================================================
# PositionalAudio
---
The `cientos` package provides an abstraction of the [PositionalAudio](https://threejs.org/docs/index.html?q=posi#api/en/audio/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.
`` 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) class.
## Usage
The `` 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 `` component and set the `url`. It must be wrapped around the `` component to enable it to load your audio asynchronously. 💥
```vue
```
:::warning
AudioContext is authorised when an user gesture has been made on the page. `:autoplay="true"` cannot be activated if no user gesture has been made previously (https://goo.gl/7K7WLu).
If you are sure that there will be a user gesture before your `` component appears/is created, you can directly add `:ready="true"` and `autoplay="true"` for a direct launch.
:::
## How does it work?
## Props
| Prop | Description | Default |
| :---------------- | :--------------------------------------------------- | ------------------------- |
| **url** | `string` - **required** — The path or URL to the file. | |
| **helper** | `boolean` — Selects whether helper mode is enabled. *(Useful for visualising the angle of sound propagation)* | `false` |
| **distance** | `number` — The distance at which the volume reduction starts taking effect. ***A non-negative number.*** | `1` |
| **ready** | `boolean` — Tells `` 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). | `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).|
| `play()` | Play audio — *Cannot be fired if audio is already running.* |
| `pause()` | Pause audio — *Cannot be fired if audio is already paused.* |
| `stop()` | Stop audio — *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{1,3,8}
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{2-4,9}
```
## Events
| Event | Description |
| :---------- | :--------------------------------------------------------------- |
| `is-playing` | Triggered when the audio changes its state (play, pause, or stop) `@is-playing="(e) => yourIsPlayingRef = e"` |
================================================
FILE: docs/guide/abstractions/reflector.md
================================================
# Reflector
The `cientos` package provides an abstraction of the [Reflector class](https://github.com/mrdoob/three.js/blob/dev/examples/jsm/objects/Reflector.js), 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
<<< @/.vitepress/theme/components/ReflectorDemo.vue{6,26-32}
## 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 |
::: warning
All the props except the `color`, are not reactive
:::
## Custom mirror effect
For more complex effect you can provide your own shaders, you could do this creating an object and pass the uniforms, vertexShaders or fragmentShaders:
```vue{2,4-6,15}
...
...
```
### 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
```
| Event | Description |
| :--------- | :-------------------------------------------- |
| **start** | Dispatched when the control starts to change. |
| **change** | Dispatched when the control changes. |
| **end** | Dispatched when the control ends to change. |
================================================
FILE: docs/guide/controls/helper.md
================================================
# Helper
`` handles instantiation, updates, and removal/disposal of THREE Helpers.
## Usage
<<< @/.vitepress/theme/components/HelperDemo.vue
## Props
| Prop | Description | Default |
| :------------------ | :-------------------------------------------------------------------------------------------- | ----------- |
| **type** | Helper constructor - required | |
| **args** | Helper constructor args | `[]` |
================================================
FILE: docs/guide/controls/keyboard-controls.md
================================================
# KeyboardControls
`` is a simple keyboard controller for the camera. The camera's movements are bound to:
* WASD on QWERTY keyboards or equivalent keys on non-QWERTY keyboards
* Arrow keys
::: info
`` uses `` under the hood. You can use [`` props and events](pointer-lock-controls#props).
:::
## Usage
```vue{3,10}
```
::: warning
You must add a `` to your scene before adding ``.
:::
## 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
isActive(state)" />
```
| Event | Description |
| :--------- | :--------------------------------------------------------------- |
| **isLock** | Return `true` if "lock", `false` if "unlock" events are triggered. |
| **change** | Dispatched when the control changes. |
================================================
FILE: docs/guide/controls/map-controls.md
================================================
# MapControls
[MapControls](https://threejs.org/docs/index.html?q=controls#examples/en/controls/MapControls) 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.
However, as it is not part of the core of ThreeJS, to use it you would need to import it from the `three/examples/jsm/controls/MapControls` module.
Here is where the fancy part begins. ✨
The `cientos` package provides a component called ``, which is a wrapper of the `MapControls` from the [`three-stdlib`](https://github.com/pmndrs/three-stdlib) module.
The nicest part? You don't need to extend the catalog or pass any arguments.
It just works. 💯
## Usage
<<< @/.vitepress/theme/components/MapControlsDemo.vue{3,9}
::: 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` |
================================================
FILE: docs/guide/controls/orbit-controls.md
================================================
# OrbitControls
[OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) is a camera controller that allows you to orbit around a target. It's a great way to explore your scene.
However, it is not part of the core of ThreeJS. So to use it you would need to import it from the `three/examples/jsm/controls/OrbitControls` module.
Here is where the fancy part begins. ✨
The `cientos` package provides a component called `` that is a wrapper of the `OrbitControls` from the [`three-stdlib`](https://github.com/pmndrs/three-stdlib) module.
The nicest part? You don't need to extend the catalog or pass any arguments.
It just works. 💯
## Usage
<<< @/.vitepress/theme/components/OrbitControlsDemo.vue{3,9}
::: 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` |
## Events
```vue
```
| Event | Description |
| :--------- | :-------------------------------------------- |
| **start** | Dispatched when the control starts to change. |
| **change** | Dispatched when the control changes. |
| **end** | Dispatched when the control ends to change. |
================================================
FILE: docs/guide/controls/pointer-lock-controls.md
================================================
# PointerLockControls
[PointerLockControls](https://threejs.org/docs/index.html?q=pointe#examples/en/controls/PointerLockControls) 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.
However, as it is not part of the core of ThreeJS, to use it you would need to import it from the `three/examples/jsm/controls/PointerLockControls` module.
Here is where the fancy part begins. ✨
The `cientos` package provides a component called ``, which is a wrapper of the `PointerLockControls` from the [`three-stdlib`](https://github.com/pmndrs/three-stdlib) module.
The nicest part? You don't need to extend the catalog or pass any arguments.
It just works. 💯
::: warning
This control uses the [Pointer Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API), 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{4}
```
Or using your own HTML element to trigger the event
```vue{3}
```
::: 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
isActive(state)" />
```
| Event | Description |
| :--------- | :--------------------------------------------------------------- |
| **isLock** | Return `true` if "lock", `false` if "unlock" events are trigger. |
| **change** | Dispatched when the control changes. |
================================================
FILE: docs/guide/controls/scroll-controls.md
================================================
# ScrollControls
`ScrollControls` use scroll as a trigger for control the scene, you can use the HTML native scroll or use the one that it get creates for you.
The `cientos` package create this controls from scratch for you, and comes with really useful props to customize your experiences, try it out. ✨
## Usage
To start using it, you just need to import it and play with it.
<<< @/.vitepress/theme/components/ScrollControlsDemo.vue{3,14}
::: warning
Is really important that the Perspective camera is set first in the canvas. Otherwise might break.
:::
You can use the `horizontal` prop, to makes the scroll horizontal way.
<<< @/.vitepress/theme/components/ScrollControlsHorizontalDemo.vue{3,14}
With the `pages` prop you can control the length of the scroll, and with the `distance` you can control how much movement is apply to the objects ( you can for example use it with 0 value and use the progress element)
In addition a nice effect could be achieve by using the `smoothScroll` prop like so:
<<< @/.vitepress/theme/components/ScrollControlsPagesDemo.vue{14-18}
By default `ScrollControls` creates a scroll around the canvas and takes the camera as a default for animate, also it comes with a reactive `progress` param that returns a normalized value from 0 (start point) to 1 (end point) you just need to attach it to a v-model.
<<< @/.vitepress/theme/components/ScrollControlsProgressDemo.vue{7,27-30}
If you don't want to use the default camera movement you can set the distance to 0 a just rely on progress to animate (the progress is not affected by the `smoothScroll` )
But it's not all, you can also pass the `htmlScroll` props this will deactivate the custom scroll and use the native html scroll.
```vue{1}
```
::: warning
- If you set the `htmlScroll` you need to set your html to have content that create scroll. so the `pages` prop will not work
- The `htmlScroll` will set the TresCanvas as a fixed background.
:::
### Slots
The elements that you pass as a slot will be affected by the scroll effect, and follow the camera.
<<< @/.vitepress/theme/components/ScrollControlsSlotsDemo.vue{31-43}
## Props
| Prop | Description | Default |
| :--------------- | :------------------------------------------------------- | ------- |
| **pages** | The length of the scroll (not available with htmlScroll) | `4` |
| **distance** | The distance to move the objects | `4` |
| **smoothScroll** | The smooth factor of the scrolling. | `0.1` |
| **horizontal** | Whether the scroll is horizontal or vertical. | `false` |
| **htmlScroll** | Whether to use the native HTML scroll. | `false` |
::: warning
Currently the props are not reactive for this control
:::
================================================
FILE: docs/guide/controls/transform-controls.md
================================================
# Transform Controls
The [Transform Controls](https://threejs.org/docs/#examples/en/controls/TransformControls) 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
## 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{2,6,8}
```
::: warning
If you are using other controls ([OrbitControls](/guide/controls/orbit-controls)) 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

The default mode allows you to move the object around the scene.
```vue
```
### Rotate

The rotate mode allows you to rotate the object around the scene.
```vue
```
### Scale

The scale mode allows you to scale the object around the scene.
```vue
```
## Props
| Prop | Description | Default |
| :------------------ | :-------------------------------------------------------------------------------------------- | ----------- |
| **object** | The instance [Object3D](https://threejs.org/docs/index.html#api/en/core/Object3D) 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. |
================================================
FILE: docs/guide/index.md
================================================
# Cientos

> 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](https://docs.tresjs.org/) 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.
The `cientos` package uses [`three-stdlib`](https://github.com/pmndrs/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 it for you.
It just works. 💯
::: info
This package is not required to use the core library, but it improves DX, especially for complex scenes.
:::
## Installation
::: code-group
```bash [pnpm]
pnpm add @tresjs/cientos
```
```bash [npm]
npm install @tresjs/cientos
```
```bash [yarn]
yarn add @tresjs/cientos
```
:::
## Basic Usage
```ts
import { OrbitControls } from '@tresjs/cientos'
```
Now you can use the `OrbitControls` component in your scene.
```html
```
::: warning
Notice that you don't need to write the prefix `Tres` such as `` to use the component
:::
================================================
FILE: docs/guide/loaders/fbx-model.md
================================================
# Using `FBXModel`
The `FBXModel` component is a wrapper around [`useFBX`](./use-fbx.md) composable and accepts the same options as props.
## Usage
<<< @/.vitepress/theme/components/FBXModelDemo.vue{3,10-15}
## 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
```
## 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` |
================================================
FILE: docs/guide/loaders/gltf-model.md
================================================
# Using `GLTFModel`
The `GLTFModel` component is a wrapper around [`useGLTF`](./use-gltf.md) composable and accepts the same options as props.
## Usage
<<< @/.vitepress/theme/components/GLTFModelDemo.vue{3,10}
## Model reference
You can access the model reference by passing a `ref` to the `model` prop and then using to get the object.
```vue
```
## Props
| Prop | Description | Default |
| :------------ | :-------------------------------------------------------------------------------------------------------------------- | ----------- |
| `path` | Path to the model file. | `undefined` |
| `draco` | Enable [Draco compression](https://threejs.org/docs/index.html?q=drac#examples/en/loaders/DRACOLoader) for the model. | `false` |
| `decoderPath` | Path to a local Draco decoder. | `undefined` |
| `castShadow` | Apply `cast-shadow` to all meshes inside your model. | `false` |
| `receiveShadow` | Apply `receive-shadow` to all meshes inside your model. | `false` |
================================================
FILE: docs/guide/loaders/use-fbx.md
================================================
# useFBX
A composable that allows you to easily load FBX models into your **TresJS** scene.
## Usage
::: code-group
```vue{2,6} [TheModel.vue]
```
```vue [app.vue]
```
:::
## 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` | 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.
================================================
FILE: docs/guide/loaders/use-gltf.md
================================================
# useGLTF
A composable that allows you to easily load glb/glTF models into your **TresJS** scene.
## Usage
::: code-group
```vue{2,6} [TheModel.vue]
```
```vue [app.vue]
```
:::
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) 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** | `GLTF` | The loaded GLTF 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 |
| **progress** | `number` | The progress of the model loading |
| **load** | `() => Promise` | Function to reload the model |
## 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.
================================================
FILE: docs/guide/loaders/use-progress.md
================================================
# 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
Loading... {{ progress }} %
```
:::warning
This component use top level await. Please check the [Suspense API](https://vuejs.org/guide/built-ins/suspense.html#suspense) for more info
:::
================================================
FILE: docs/guide/loaders/use-svg.md
================================================
# useSVG
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{2,6} [TheModel.vue]
```
```vue [app.vue]
```
:::
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 = ``
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
```
#### Custom Animation
```vue
```
### 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). This makes the SVG layers render dependably regardless of perspective.
**Disadvantage**: Scene objects may render out of order.
SVG layers with higher `renderOrder` will be rendered after (i.e., sometimes "on top of") other objects in the scene graph with a lower `renderOrder`. 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) 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), 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). 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
```
### Advanced Usage
#### Conditional Layer Rendering
```vue
```
#### Material Customization per Layer
```vue
```
## UseSVG Component
For simple, declarative SVG rendering without the need for programmatic control, you can use the `SVG` component:
```vue
```
### 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"](#depth-handling)) | `renderOrder` |
## Troubleshooting
::: 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](#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)
* In your `useSVG` options, [change the `depth` option](#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
================================================
FILE: docs/guide/loaders/use-texture.md
================================================
# useTexture
A composable that allows you to load textures using the [THREE.js texture loader](https://threejs.org/docs/#api/en/loaders/TextureLoader) into your **TresJS** scene.
## Usage
```vue [TexturedObject.vue]
```
## 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. |
## Component Usage
```vue [UseTexture.vue]
```
================================================
FILE: docs/guide/loaders/use-textures.md
================================================
# useTextures
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) into your **TresJS** scene.
## Usage
```vue [TexturedObjects.vue]
```
## 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]
```
## 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
================================================
FILE: docs/guide/loaders/use-video-texture.md
================================================
# useVideoTexture
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)
## Usage
::: code-group
```vue [app.vue]
```
```vue{3,8,13} [TheVideoTexture.vue]
```
:::
## 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 `
```
:::
## Usage
<<< @/.vitepress/theme/components/StageDemo.vue
## Props
```ts
interface StageProps {
/** Lighting setup, default: "rembrandt" */
lighting?:
| null | undefined | false
| 'rembrandt'
| 'portrait'
| 'upfront'
| 'soft'
| { main: [x: number, y: number, z: number], fill: [x: number, y: number, z: number] }
/** Controls the ground shadows, default: "contact" */
shadows?: boolean | 'contact' | 'accumulative' | StageShadows
/** Optionally wraps and thereby centers the models using , can also be a camera offset, default: true */
adjustCamera?: boolean | number
/** The default environment, default: "city" */
environment?: string | Partial | null
/** Lighting intensity, `0` removes lights, default: 0.5 */
intensity?: number
/** To adjust alignment, default: undefined */
align?: Partial
}
type StageShadows = Partial &
Partial &
Partial & {
type: 'contact' | 'accumulative'
/** Shadow plane offset, default: 0 */
offset?: number
/** Shadow bias, default: -0.0001 */
bias?: number
/** Shadow normal bias, default: 0 */
normalBias?: number
/** Shadow map size, default: 1024 */
size?: number
}
```
================================================
FILE: docs/guide/staging/stars.md
================================================
# 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 `` component without passing any props,
```vue
...
...
```
But still if you want you can tweak the props to find the best setup for you.
<<< @/.vitepress/theme/components/StarsDemo.vue{4,15-22}
Notice that you can pass a texture as an alphaMap to personalize the star shape
```vue
...
...
```
## 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 |
================================================
FILE: docs/guide/staging/use-environment.md
================================================
# UseEnvironment
`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) to load the cubemap
## Usage
::: warning
`UseEnvironment` needs to be wrapped by a Suspense component
:::
```ts
import { useEnvironment } from '@tresjs/cientos'
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,
})
```
Then you can use the `texture` in your scene:
```vue{3}
```
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. |
| **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. |
================================================
FILE: docs/index.md
================================================
---
# https://vitepress.dev/reference/default-theme-home-page
layout: home
hero:
name: "Cientos"
text: "Ready-made abstractions for TresJS"
tagline: Extending helpers and composables using Three addons.
actions:
- theme: brand
text: Get Started
link: /guide/
- theme: alt
text: Why Tres?
link: https://tresjs.org/guide/#motivation
features:
- icon: 🦾
title: three-stdlib
details: Because the ThreeJS addons repo structure is... daunting
- icon: 🦄
title: Extendable
details: You want to create a fancy shader material component? Submit a PR 🤗
- icon: 💛
title: Community-Driven
details: Benefits from the active and growing Vue TresJS community.
---
================================================
FILE: docs/markdown-examples.md
================================================
# Markdown Extension Examples
This page demonstrates some of the built-in markdown extensions provided by VitePress.
## Syntax Highlighting
VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
**Input**
````
```js{4}
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}
```
````
**Output**
```js{4}
export default {
data () {
return {
msg: 'Highlighted!'
}
}
}
```
## Custom Containers
**Input**
```md
::: info
This is an info box.
:::
::: tip
This is a tip.
:::
::: warning
This is a warning.
:::
::: danger
This is a dangerous warning.
:::
::: details
This is a details block.
:::
```
**Output**
::: info
This is an info box.
:::
::: tip
This is a tip.
:::
::: warning
This is a warning.
:::
::: danger
This is a dangerous warning.
:::
::: details
This is a details block.
:::
## More
Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).
================================================
FILE: docs/package.json
================================================
{
"name": "docs",
"type": "module",
"version": "0.0.0",
"private": true,
"scripts": {
"dev": "vitepress dev",
"build": "vitepress build",
"preview": "vitepress preview"
},
"dependencies": {
"@tresjs/cientos": "workspace:^"
},
"devDependencies": {
"@tresjs/leches": "^0.14.0",
"markdown-it": "^14.0.0",
"unocss": "^0.65.1",
"vite-svg-loader": "^5.1.0"
}
}
================================================
FILE: docs/tsconfig.json
================================================
{
"compilerOptions": {
"target": "esnext",
"jsx": "preserve",
"lib": ["DOM", "ESNext"],
"module": "esnext",
"moduleResolution": "node",
"resolveJsonModule": true,
"types": ["vite/client"],
"strict": true,
"noUnusedLocals": true,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"skipLibCheck": true
},
"exclude": ["dist", "node_modules"]
}
================================================
FILE: docs/vite.config.ts
================================================
import Unocss from 'unocss/vite'
import Components from 'unplugin-vue-components/vite'
import { defineConfig } from 'vite'
import svgLoader from 'vite-svg-loader'
export default defineConfig({
plugins: [
svgLoader(),
Unocss(),
Components({
// allow auto load markdown components under `.vitepress/theme/components`
dirs: ['.vitepress/theme/components'],
extensions: ['vue', 'md'],
// allow auto import and register components used in markdown
include: [/\.vue$/, /\.vue\?vue/, /\.md$/],
dts: 'components.d.ts',
}),
],
})
================================================
FILE: eslint.config.js
================================================
import { tresLintConfig } from '@tresjs/eslint-config'
export default tresLintConfig({
rules: {
// TODO: temporary fix for Error while loading rule 'jsonc/no-useless-escape': Cannot read properties of undefined (reading 'allowRegexCharacters')
'jsonc/no-useless-escape': 'off',
},
})
================================================
FILE: netlify.toml
================================================
[build]
publish = "docs/.vitepress/dist"
command = "pnpm run build && pnpm docs:build"
[build.environment]
NODE_VERSION = "22"
================================================
FILE: package.json
================================================
{
"name": "@tresjs/cientos",
"type": "module",
"version": "5.0.0",
"packageManager": "pnpm@10.17.0",
"description": "Collection of useful helpers and fully functional, ready-made abstractions for Tres",
"author": "Alvaro Saburido (https://github.com/alvarosabu/)",
"license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/Tresjs/cientos.git"
},
"keywords": [
"vue",
"3d",
"threejs",
"three",
"threejs-vue",
"composables"
],
"maintainers": [
"Alvaro Saburido (https://github.com/alvarosabu/)",
"Jaime Torrealba (https://github.com/JaimeTorrealba)",
"Andre Tchen (https://github.com/andretchen0)"
],
"sideEffects": false,
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/trescientos.js"
},
"./core": {
"types": "./dist/core/index.d.ts"
},
"./*": "./*"
},
"main": "./dist/trescientos.js",
"module": "./dist/trescientos.js",
"types": "./dist/index.d.ts",
"files": [
"*.d.ts",
"dist"
],
"publishConfig": {
"access": "public"
},
"scripts": {
"dev": "cd playground/vue && pnpm dev",
"dev:nuxt": "cd playground/nuxt && pnpm dev",
"build": "vite build",
"release": "release-it",
"lint": "eslint .",
"typecheck": "vue-tsc --noEmit",
"lint:fix": "eslint . --fix",
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
"peerDependencies": {
"@tresjs/core": ">=5.0.0",
"three": ">=0.133",
"vue": ">=3.5.17"
},
"dependencies": {
"@vueuse/core": "^13.8.0",
"camera-controls": "^2.9.0",
"stats-gl": "^2.0.1",
"stats.js": "^0.17.0",
"three-custom-shader-material": "^5.4.0",
"three-stdlib": "^2.36.0"
},
"devDependencies": {
"@release-it/conventional-changelog": "^10.0.1",
"@tresjs/core": "5.0.0",
"@tresjs/eslint-config": "^1.4.0",
"@types/node": "^24.3.0",
"@types/three": "^0.180.0",
"@typescript-eslint/eslint-plugin": "^8.41.0",
"@typescript-eslint/parser": "^8.41.0",
"@vitejs/plugin-vue": "^6.0.1",
"eslint": "^9.34.0",
"eslint-plugin-vue": "^10.4.0",
"gsap": "^3.13.0",
"kolorist": "^1.8.0",
"pathe": "^2.0.3",
"release-it": "^19.0.4",
"rollup-plugin-analyzer": "^4.0.0",
"rollup-plugin-visualizer": "^6.0.3",
"three": "^0.180.0",
"typescript": "^5.8.3",
"unocss": "^66.1.2",
"vite": "^7.1.6",
"vite-plugin-banner": "^0.8.1",
"vite-plugin-dts": "4.5.4",
"vite-plugin-glsl": "^1.5.1",
"vite-svg-loader": "^5.1.0",
"vitepress": "1.6.4",
"vue-tsc": "^3.0.7"
}
}
================================================
FILE: playground/vue/.eslintrc-auto-import.json
================================================
{
"globals": {
"Component": true,
"ComponentPublicInstance": true,
"ComputedRef": true,
"DirectiveBinding": true,
"EffectScope": true,
"ExtractDefaultPropTypes": true,
"ExtractPropTypes": true,
"ExtractPublicPropTypes": true,
"InjectionKey": true,
"MaybeRef": true,
"MaybeRefOrGetter": true,
"PropType": true,
"Ref": true,
"ShallowRef": true,
"Slot": true,
"Slots": true,
"VNode": true,
"WritableComputedRef": true,
"computed": true,
"createApp": true,
"customRef": true,
"defineAsyncComponent": true,
"defineComponent": true,
"effectScope": true,
"getCurrentInstance": true,
"getCurrentScope": true,
"getCurrentWatcher": true,
"h": true,
"inject": true,
"isProxy": true,
"isReactive": true,
"isReadonly": true,
"isRef": true,
"isShallow": true,
"markRaw": true,
"nextTick": true,
"onActivated": true,
"onBeforeMount": true,
"onBeforeUnmount": true,
"onBeforeUpdate": true,
"onDeactivated": true,
"onErrorCaptured": true,
"onMounted": true,
"onRenderTracked": true,
"onRenderTriggered": true,
"onScopeDispose": true,
"onServerPrefetch": true,
"onUnmounted": true,
"onUpdated": true,
"onWatcherCleanup": true,
"provide": true,
"reactive": true,
"readonly": true,
"ref": true,
"resolveComponent": true,
"shallowReactive": true,
"shallowReadonly": true,
"shallowRef": true,
"toRaw": true,
"toRef": true,
"toRefs": true,
"toValue": true,
"triggerRef": true,
"unref": true,
"useAttrs": true,
"useCssModule": true,
"useCssVars": true,
"useId": true,
"useModel": true,
"useSlots": true,
"useTemplateRef": true,
"watch": true,
"watchEffect": true,
"watchPostEffect": true,
"watchSyncEffect": true
}
}
================================================
FILE: playground/vue/.eslintrc.json
================================================
{
"extends": "@tresjs/eslint-config-vue",
"rules": {
"no-console": "off",
"vue/attribute-hyphenation": [2, "always", {
"ignore": [
"shadow-mapSize-width",
"shadow-mapSize-height",
"distortionMap",
"material-uniforms-mieCoefficient-value",
"material-uniforms-mieDirectionalG-value",
"material-uniforms-sunPosition-value"
]
}]
}
}
================================================
FILE: playground/vue/.gitignore
================================================
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*
node_modules
dist
dist-ssr
*.local
# Editor directories and files
.vscode/*
!.vscode/extensions.json
.idea
.DS_Store
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?
================================================
FILE: playground/vue/.vscode/extensions.json
================================================
{
"recommendations": ["Vue.volar", "Vue.vscode-typescript-vue-plugin"]
}
================================================
FILE: playground/vue/README.md
================================================
# Vue 3 + TypeScript + Vite
This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `