TroisJS

https://troisjs.github.io/
Admin
TroisJS is a Vue 3 framework for creating 3D WebGL content using Three.js with ViteJS for fast...
Tokens:10,972
Snippets:127
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies with Yarn

Source: https://troisjs.github.io/guide/install

Use this command to install project dependencies using Yarn after downloading the starter app.

```bash
cd troisjs (or troisjs-ts)
yarn
yarn dev
```

--------------------------------

### Install Dependencies with npm

Source: https://troisjs.github.io/guide/install

Use this command to install project dependencies using npm after downloading the starter app.

```bash
cd troisjs (or troisjs-ts)
npm install
npm run dev
```

--------------------------------

### Install TroisJS in Existing VueJS 3 Project

Source: https://troisjs.github.io/guide/install

Install TroisJS and Three.js for an existing Vue.js 3 project using npm or yarn.

```bash
npm install three@0.134 troisjs
```

```bash
yarn add three@0.134 troisjs
```

--------------------------------

### Shader Uniform Texture Access

Source: https://troisjs.github.io/guide/materials/shader-material.html

Example of how to access the passed texture within a fragment shader.

```glsl
uniform sampler2D myCustomTexture;

void main(){
  gl_FragColor = texture2D(myCustomTexture, /* your UV vec2 */);
}
```

--------------------------------

### Use SubSurfaceMaterial

Source: https://troisjs.github.io/guide/materials/sub-surface-material

Basic usage of the SubSurfaceMaterial within a TroisJS Box component. No specific setup is required beyond importing the component.

```vue
<Box>
  <SubSurfaceMaterial />
</Box>

```

--------------------------------

### Vue Component without TroisJS Plugin

Source: https://troisjs.github.io/guide/install

Example of a Vue.js component using TroisJS without the plugin, manually importing components. It renders a scene with a camera, light, and a box.

```vue
<template>
  <Renderer>
    <Camera :position="{ z: 10 }" />
    <Scene>
      <PointLight :position="{ y: 50, z: 50 }" />
      <Box>
        <LambertMaterial />
      </Box>
    </Scene>
  </Renderer>
</template>

<script>
import { Box, Camera, LambertMaterial, PointLight, Renderer, Scene } from 'troisjs';
export default {
  components: { Box, Camera, LambertMaterial, PointLight, Renderer, Scene },
};
</script>
```

--------------------------------

### Add Postprocessing Effects with EffectComposer

Source: https://troisjs.github.io/guide/postprocessing

Use EffectComposer to easily add post-processing effects to your TroisJS scene. This example includes UnrealBloomPass and HalftonePass.

```html
<template>
  <Renderer>
    <Camera :position="{ z: 10 }" />
    <Scene>
      <PointLight :position="{ z: 50 }" />
      <Box :size="1">
        <LambertMaterial />
      </Box>
    </Scene>
    <EffectComposer>
      <RenderPass />
      <UnrealBloomPass :strength="1" />
      <HalftonePass :radius="1" :scatter="0" />
    </EffectComposer>
  </Renderer>
</template>

```

--------------------------------

### Get ThreeJS Scene Instance

Source: https://troisjs.github.io/guide/core/scene.html

After setting a ref on the Scene component, you can retrieve the ThreeJS scene instance using `this.$refs.scene.scene` in your component's script.

```javascript
const scene = this.$refs.scene.scene;

```

--------------------------------

### Modifying OrbitControls Properties

Source: https://troisjs.github.io/guide/core/renderer.html

Apply Three.js OrbitControls properties and methods directly to the accessed OrbitControls instance. For example, disabling panning.

```javascript
orbitCtrl.enablePan = false
```

--------------------------------

### Initialize TroisJS Development Environment

Source: https://troisjs.github.io/guide/dev

Use these commands to clone the repository and launch the local development server.

```bash
git clone https://github.com/troisjs/trois
cd trois
yarn
yarn dev
```

--------------------------------

### Create a PointLight

Source: https://troisjs.github.io/guide/lights

Basic implementation of a PointLight component with color and intensity properties.

```html
<PointLight color="#ffffff" :intensity="0.5" />
```

--------------------------------

### Initialize VRButton

Source: https://troisjs.github.io/guide/extras/vrbutton

Call the init method within the mounted lifecycle hook, passing the renderer instance.

```javascript
this.$refs.vrbutton.init(this.$refs.renderer.renderer)
```

--------------------------------

### Initialize TroisJS with DOM Template

Source: https://troisjs.github.io/guide/cdn.html

Use kebab-case and explicit closing tags when defining components directly in the DOM.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>TroisJS</title>
  <style>
    html, body { margin:0; }
    canvas { display: block; }
  </style>
</head>
<body>

  <div id="app">
    <renderer ref="renderer" antialias orbit-ctrl resize="window">
      <camera :position="{ z: 10 }"></camera>
      <scene>
        <point-light :position="{ y: 50, z: 50 }"></point-light>
        <box ref="box" :rotation="{ y: Math.PI / 4, z: Math.PI / 4 }">
          <lambert-material></lambert-material>
        </box>
      </scene>
    </renderer>
  </div>

  <script type="module">
    import { createApp } from 'https://unpkg.com/troisjs@0.3.3/build/trois.module.cdn.min.js';
    createApp({
      mounted() {
        const renderer = this.$refs.renderer
        const box = this.$refs.box.mesh
        renderer.onBeforeRender(() => {
          box.rotation.x += 0.01
        })
      }
    }).mount('#app')
  </script>

</body>
</html>
```

--------------------------------

### Initialize Instance Matrix

Source: https://troisjs.github.io/guide/meshes/instanced

Access the mesh reference and update instance matrices within the component script.

```javascript
const imesh = this.$refs.imesh.mesh;
const dummy = new Object3D();
const { randFloat: rnd, randFloatSpread: rndFS } = MathUtils;
for (let i = 0; i < 500; i++) {
  dummy.position.set(rndFS(200), rndFS(200), rndFS(200));
  const scale = rnd(0.2, 1);
  dummy.scale.set(scale, scale, scale);
  dummy.updateMatrix();
  imesh.setMatrixAt(i, dummy.matrix);
}
imesh.instanceMatrix.needsUpdate = true;
```

--------------------------------

### Initialize a basic TroisJS scene

Source: https://troisjs.github.io/guide/core

Use this structure to define the core components of a 3D scene in a Vue template.

```html
<template>
  <Renderer>
    <Camera :position="{ z: 100 }" />
    <Scene>     
      <Box :size="10">
        <BasicMaterial />
      </Box>
    </Scene>
  </Renderer>
</template>
```

--------------------------------

### Create a Basic PhongMaterial

Source: https://troisjs.github.io/guide/materials

Use this snippet to create a simple PhongMaterial with a specified color for a Box component.

```html
<Box>
  <PhongMaterial color="#ffffff" />
</Box>

```

--------------------------------

### Initialize TroisJS with PascalCase Template

Source: https://troisjs.github.io/guide/cdn.html

PascalCase can be used when defining components within a string template.

```html
<div id="app"></div>

<script type="module">
  import { createApp } from 'https://unpkg.com/troisjs@0.3.3/build/trois.module.cdn.min.js';
  createApp({
    template: `
      <Renderer ref="renderer" antialias orbit-ctrl resize="window">
        <Camera :position="{ z: 10 }" />
        <Scene>
          <PointLight :position="{ y: 50, z: 50 }" />
          <Box ref="box" :rotation="{ y: Math.PI / 4, z: Math.PI / 4 }">
            <LambertMaterial />
          </Box>
        </Scene>
      </Renderer>
    `,
    mounted() {
      const renderer = this.$refs.renderer
      const box = this.$refs.box.mesh
      renderer.onBeforeRender(() => {
        box.rotation.x += 0.01
      })
    }
  }).mount('#app')
</script>
```

--------------------------------

### Material Components Overview

Source: https://troisjs.github.io/guide/materials

List of available material components in TroisJS.

```APIDOC
## Material Components

### Description
TroisJS provides several material components that wrap ThreeJS materials for use in Vue components.

### Available Materials
- BasicMaterial
- LambertMaterial
- MatcapMaterial
- PhongMaterial
- PhysicalMaterial
- ShaderMaterial
- StandardMaterial
- SubSurfaceMaterial
- ToonMaterial
```

--------------------------------

### Create a Box with StandardMaterial

Source: https://troisjs.github.io/guide/materials/standard-material

This snippet demonstrates how to create a Box component and apply a StandardMaterial with a white color to it. Ensure the Box component is a child of a scene or another suitable container.

```vue
<Box>
  <StandardMaterial color="#ffffff" />
</Box>
```

--------------------------------

### Import VRButton Component

Source: https://troisjs.github.io/guide/extras/vrbutton

Import the VRButton component from the TroisJS library.

```javascript
import VRButton from 'troisjs/src/components/misc/VRButton.vue'
```

--------------------------------

### Accessing ThreeJS Camera

Source: https://troisjs.github.io/guide/core/camera.html

How to access the underlying ThreeJS camera instance using a ref.

```APIDOC
## Accessing ThreeJS Camera

### Description
To interact with the underlying ThreeJS camera instance, set a ref on the Camera component.

### Usage Example
```html
<Camera ref="camera" />
```

### Accessing in Script
```javascript
const scene = this.$ref.camera.camera;
```
```

--------------------------------

### Load GLTF and FBX Models

Source: https://troisjs.github.io/guide/models

Use GltfModel and FbxModel components to load 3D assets. Both components support identical props and event listeners for loading status.

```html
<GltfModel
    src="/path/to/your/model.gltf"
    @load="onReady"
    @progress="onProgress"
    @error="onError"
/>

<!-- FBX Model has the same props and events but loads FBX files -->
<FbxModel
    src="/path/to/your/model.fbx"
    @load="onReady"
    @progress="onProgress"
    @error="onError"
/>
```

--------------------------------

### Access ThreeJS Light Instance

Source: https://troisjs.github.io/guide/lights

Use a ref to reference the light component and access the underlying ThreeJS object.

```html
<PointLight ref="light" />
```

```javascript
const light = this.$ref.light.light;
```

--------------------------------

### MatcapMaterial Component

Source: https://troisjs.github.io/guide/materials/matcap-material

Documentation for the MatcapMaterial component, including its props and usage.

```APIDOC
## MatcapMaterial

### Description
Creates a THREE.MeshMatcapMaterial with baked lighting and color that can cast, but not receive, shadows.

### Props
- **name** (String) - Optional - Name of matcap from the repository to use. Overrides `src` if set.
- **src** (String) - Optional - URL for matcap image.

### Usage Example
<Box>
  <MatcapMaterial name="392307_B3AE7D_6D5618_847C42" />
</Box>
```

--------------------------------

### Box Mesh with Common Props

Source: https://troisjs.github.io/guide/meshes

Configure a Box mesh using common properties such as position, rotation, scale, and shadow casting/receiving. Ensure BasicMaterial is included.

```html
<Box
  :position="{ x: 0, y: 0, z: 0 }"
  :rotation="{ x: 0, y: 0, z: 0 }"
  :scale="{ x: 1, y: 1, z: 1 }"
  :cast-shadow="false"
  :receive-shadow="false"
>
  <BasicMaterial />
</Box>
```

--------------------------------

### Accessing Three.js Renderer and OrbitControls

Source: https://troisjs.github.io/guide/core/renderer.html

Instructions on how to access the underlying Three.js renderer and OrbitControls instance.

```APIDOC
## Access Three.js Renderer and OrbitControls

### Accessing the Renderer

Set a `ref` on the Renderer component in your template:

```html
<Renderer ref="renderer">
  ...
</Renderer>
```

Then, access the Three.js renderer instance in your script:

```javascript
const renderer = this.$refs.renderer.renderer;
```

### Accessing OrbitControls

The `three` object on the renderer instance provides access to various Three.js functionalities, including `cameraCtrl` which manages OrbitControls.

```javascript
const orbitCtrl = this.$refs.renderer.three.cameraCtrl;
```

#### OrbitControls Events

Attach event listeners to `orbitCtrl` in the `mounted()` hook:

```javascript
orbitCtrl.addEventListener('change', () => {
  // Called when the camera has been transformed by the controls.
});
orbitCtrl.addEventListener('start', () => {
  // Called when an interaction was initiated.
});
orbitCtrl.addEventListener('end', () => {
  // Called when an interaction has finished.
});
```

#### OrbitControls Properties and Methods

Apply Three.js OrbitControls properties and methods directly:

```javascript
orbitCtrl.enablePan = false;
```
```

--------------------------------

### SubSurfaceMaterial Customization with Uniform Prop

Source: https://troisjs.github.io/guide/materials/sub-surface-material

Shows how to customize the SubSurfaceMaterial using the `uniform` prop to override default property values.

```APIDOC
## SubSurfaceMaterial with Uniform Prop

### Description

You can use the `uniform` prop to customize this material, e.g., by changing the `thicknessColor`.

### Method

N/A (Component Usage)

### Endpoint

N/A (Component Usage)

### Parameters

#### Path Parameters

N/A

#### Query Parameters

N/A

#### Request Body

N/A

### Request Example

```html
<Box>
  <SubSurfaceMaterial :uniform="{ thicknessColor: '#ffffff' }" />
</Box>
```

### Response

N/A

#### Success Response (200)

N/A

#### Response Example

N/A
```

--------------------------------

### Create a BasicMaterial in TroisJS

Source: https://troisjs.github.io/guide/materials/basic-material

Use this component within a mesh to apply a material that does not react to light sources.

```html
<Box>
  <BasicMaterial color="#ffffff" />
</Box>
```

--------------------------------

### Camera Component Props

Source: https://troisjs.github.io/guide/core/camera.html

Documentation for the props available on the Camera component.

```APIDOC
## Camera Component Props

### Description
The Camera component is based on THREE.PerspectiveCamera. It allows configuration of the camera frustum and positioning.

### Parameters
#### Props
- **aspect** (Number) - Optional - Camera frustum aspect ratio. Default: 1
- **far** (Number) - Optional - Camera frustum far plane. Default: 2000
- **fov** (Number) - Optional - Camera frustum vertical field of view. Default: 50
- **near** (Number) - Optional - Camera frustum near plane. Default: 0.1
- **position** (Object) - Optional - Camera position. Default: { x: 0, y: 0, z: 0 }
- **lookAt** (Object) - Optional - Camera target.
```

--------------------------------

### Configure Refraction on CubeTexture

Source: https://troisjs.github.io/guide/textures/texture.html

Enable refraction on a CubeTexture by adding the refraction attribute and setting the refraction-ratio.

```html
<BasicMaterial>
  <CubeTexture path="/cube_texture/" refraction :refraction-ratio="0.95" />
</BasicMaterial>
```

--------------------------------

### Enable Shadows in TroisJS Renderer

Source: https://troisjs.github.io/guide/shadows.html

Configure shadows by setting the `shadow` prop on the Renderer. Ensure lights have `cast-shadow` and meshes have `cast-shadow` or `receive-shadow`.

```html
<Renderer shadow>
  <Camera :position="{ z: 100 }" />
  <Scene>
    <PointLight :position="{ y: 50, z: 50 }" cast-shadow :shadow-map-size="{ width: 512, height: 512 }" />
    <Box :size="10" :rotation="{ x: 1, z: 1 }" cast-shadow>
      <LambertMaterial />
    </Box>
    <Plane :width="100" :height="100" :position="{ z: -20 }" receive-shadow>
      <LambertMaterial />
    </Plane>
  </Scene>
</Renderer>

```

--------------------------------

### SubSurfaceMaterial Usage

Source: https://troisjs.github.io/guide/materials/sub-surface-material

Demonstrates the basic usage of the SubSurfaceMaterial within a TroisJS component.

```APIDOC
## SubSurfaceMaterial

### Description

Sub surface scattering based on a specific method.
This material is an implementation of the shader material using the shader in `three/examples/jsm/shaders/SubsurfaceScatteringShader.js`.

### Method

N/A (Component Usage)

### Endpoint

N/A (Component Usage)

### Parameters

#### Path Parameters

N/A

#### Query Parameters

N/A

#### Request Body

N/A

### Request Example

```html
<Box>
  <SubSurfaceMaterial />
</Box>
```

### Response

N/A

#### Success Response (200)

N/A

#### Response Example

N/A
```

--------------------------------

### Load Cube Texture into BasicMaterial

Source: https://troisjs.github.io/guide/textures/cube-texture

Use the CubeTexture component within a BasicMaterial to apply a cube texture. Ensure the parent Box component is set up correctly.

```html
<Box>
  <BasicMaterial>
    <CubeTexture/>
  </BasicMaterial>
</Box>

```

--------------------------------

### Apply CubeTexture to BasicMaterial

Source: https://troisjs.github.io/guide/textures/texture.html

Use the CubeTexture component to apply environment maps to materials by providing the directory path.

```html
<BasicMaterial>
  <CubeTexture path="/cube_texture/" />
</BasicMaterial>
```

--------------------------------

### Accessing ThreeJS Material

Source: https://troisjs.github.io/guide/materials

How to access the underlying ThreeJS material instance via refs.

```APIDOC
## Accessing ThreeJS Material

### Description
To access the raw ThreeJS material instance, use a ref on the component.

### Example
<PhongMaterial ref="material" />

### Accessing in Script
const material = this.$ref.material.material;
```

--------------------------------

### Material Props

Source: https://troisjs.github.io/guide/materials

Configuration of material properties using component props.

```APIDOC
## Material Props

### Parameters
- **color** (String, Number) - Optional - Color of the material. Default: #ffffff
- **props** (Object) - Optional - Additional properties to apply to the material. Default: {}

### Request Example
<Box>
  <PhongMaterial color="#ffffff" :props="{ transparent: true, opacity: 0.5 }" />
</Box>
```

--------------------------------

### Customize PhongMaterial Props

Source: https://troisjs.github.io/guide/materials

Customize PhongMaterial properties like transparency and opacity using the 'props' attribute. Ensure the material is configured for transparency.

```html
<Box>
  <PhongMaterial color="#ffffff" :props="{ transparent: true, opacity: 0.5 }" />
</Box>

```

--------------------------------

### Basic MatcapMaterial Usage

Source: https://troisjs.github.io/guide/materials/matcap-material

Apply a matcap texture to a Box component using the name property.

```html
<Box>
  <MatcapMaterial name="392307_B3AE7D_6D5618_847C42" />
</Box>
```

--------------------------------

### Create a Box Mesh in TroisJS

Source: https://troisjs.github.io/guide/meshes

Use the Box component to create a mesh with specified size and position. Requires a BasicMaterial child.

```html
<Box :size="1" :position="{ x: 10, y: 0, z: 0 }">
  <BasicMaterial />
</Box>
```

--------------------------------

### Create a Mesh with Geometry

Source: https://troisjs.github.io/guide/meshes/geometries

Define a mesh by nesting a geometry component and a material component within the Mesh tag.

```html
<Mesh>
  <BoxGeometry />
  <BasicMaterial />
</Mesh>
```

--------------------------------

### Add VRButton to Template

Source: https://troisjs.github.io/guide/extras/vrbutton

Include the VRButton component in the HTML template with a ref attribute.

```html
<VRButton ref="vrbutton" />
```

--------------------------------

### Renderer Props

Source: https://troisjs.github.io/guide/core/renderer.html

Configuration options for the TroisJS Renderer component, including props inherited from THREE.WebGLRenderer and custom props.

```APIDOC
## Renderer Props

### Props from `THREE.WebGLRenderer`

| Name | Description | Type | Default |
|---|---|---|---|
| `alpha` | Whether the canvas contains an alpha (transparency) buffer or not. | Boolean | false |
| `antialias` | Whether to perform antialiasing. | Boolean | false |
| `autoClear` | Defines whether the renderer should automatically clear its output before rendering a frame. | Boolean | true |

### Custom Props

| Name | Description | Type | Default |
|---|---|---|---|
| `orbitCtrl` | Enable/disable OrbitControls. If value is an Object, it will be used to configure [OrbitControls](#access-threejs-orbitcontrols). | Boolean, Object | false |
| `pointer` | Listen for pointer events to track mouse or touch positions (2D and 3D). Use `renderer.three.pointer` to get: `position`, `positionN`, `positionV3`. | Boolean, Object | false |
| `resize` | Resize canvas on window resize. `false`: disabled, `true`: parent size, `'window'`: window size. To directly set the size, call `this.$refs.renderer.three.setSize(width, height)`. | Boolean, String | false |
| `shadow` | Use shadow or not. | Boolean | false |
| `width` | Fixed width | Number | |
| `height` | Fixed height | Number | |
```

--------------------------------

### OrbitControls Event Listeners

Source: https://troisjs.github.io/guide/core/renderer.html

Add event listeners to the OrbitControls instance in the `mounted()` section of your App to react to camera control changes.

```javascript
orbitCtrl.addEventListener('change', () => {
      // Do something when the camera has been transformed by the controls.
    })

orbitCtrl.addEventListener('start', () => {
      // Do something when an interaction was initiated.
    })

orbitCtrl.addEventListener('end', () => {
      // Do something when an interaction has finished.
    })
```

--------------------------------

### Apply Map and Normal Map to PhongMaterial

Source: https://troisjs.github.io/guide/textures/texture.html

Use the Texture component to apply image maps to materials. Specify the name prop to map to specific material properties like normalMap.

```html
<PhongMaterial>
  <Texture src="map.jpg" />
  <Texture src="normal-map.jpg" name="normalMap" />
</PhongMaterial>
```

--------------------------------

### TroisJS Lights API

Source: https://troisjs.github.io/guide/lights

This section details the available light types in TroisJS and their common properties.

```APIDOC
## Lights (wip)

You can easily create the following lights:
  * `AmbientLight`
  * `DirectionalLight`
  * `HemisphereLight`
  * `PointLight`
  * `RectAreaLight`
  * `SpotLight`

### Example Usage

```html
<PointLight color="#ffffff" :intensity="0.5" />
```

### Common Props (see Light.ts)

| Name | Description | Type | Default |
|---|---|---|---|
| `castShadow` | Casting shadow | Boolean | false |
| `color` | Light color | String, Number | #ffffff |
| `intensity` | Light intensity | Number | 1 |
| `position` | Light position | Object | { x: 0, y: 0, z: 0 } |
| `shadowMapSize` | Shadow map size | Object | { width: 512, height: 512 } |

### Access ThreeJS Light

You should set a _ref_ on your light:

```html
<PointLight ref="light" />
```

You can then access ThreeJS light in your component script:

```javascript
const light = this.$ref.light.light;
```
```

--------------------------------

### Custom Render Function

Source: https://troisjs.github.io/guide/core/renderer.html

How to implement a custom render function for the TroisJS Renderer.

```APIDOC
## Custom Render Function

You can override the default render loop by providing a custom `renderFn`.

### Example

```javascript
const renderer = this.$refs.renderer
renderer.onInit(() => {
  renderer.renderFn = () => {
    // Custom rendering logic here
  }
})
```
```

--------------------------------

### Usage of PhongMaterial in TroisJS

Source: https://troisjs.github.io/guide/materials/phong-material

Wraps a PhongMaterial component within a Box to apply a shiny surface with specular highlights.

```html
<Box>
  <PhongMaterial color="#ffffff" />
</Box>
```

--------------------------------

### Implement ToonMaterial in a Box

Source: https://troisjs.github.io/guide/materials/toon-material

Use this component to apply a toon-style material to a mesh, such as a Box.

```html
<Box>
  <ToonMaterial />
</Box>
```

--------------------------------

### Custom Render Function

Source: https://troisjs.github.io/guide/core/renderer.html

Assign a custom render function to the renderer instance within the onInit lifecycle hook. This allows for custom rendering logic.

```javascript
const renderer = this.$refs.renderer
renderer.onInit(() => {
  renderer.renderFn = () => {
    // do what you want
  }
})
```

--------------------------------

### Customize SubSurfaceMaterial with Uniform Prop

Source: https://troisjs.github.io/guide/materials/sub-surface-material

Customizes the SubSurfaceMaterial by passing a 'uniform' prop with specific properties like 'thicknessColor'. This allows for fine-tuning the material's appearance.

```vue
<Box>
  <SubSurfaceMaterial :uniform="{ thicknessColor: '#ffffff' }" />
</Box>

```

--------------------------------

### Declare InstancedMesh in Template

Source: https://troisjs.github.io/guide/meshes/instanced

Define an InstancedMesh component with a specified count and child geometry and material.

```html
<InstancedMesh ref="imesh" :count="500">
  <SphereGeometry :radius="5" />
  <PhongMaterial color="#ffffff" />
</InstancedMesh>
```

--------------------------------

### Mesh Events

Source: https://troisjs.github.io/guide/meshes/events

Handle pointer and click events directly on individual meshes using specific props.

```APIDOC
## Mesh Events
You can use the following props to handle events on a _Mesh_ or _InstancedMesh_ :

Name| Description| Event type| Parameters  
---|---|---|---
`onPointerEnter`| When the pointer enters a mesh| `pointerenter`| `{ type, over: true, component, intersect }`  
`onPointerOver`| When the pointer enters or leaves a mesh| `pointerover`| `{ type, over, component, intersect? }`  
`onPointerMove`| When the pointer moves over a mesh| `pointermove`| `{ type, component, intersect }`  
`onPointerLeave`| When the pointer leaves a mesh| `pointerleave`| `{ type, over: false, component }`  
`onClick`| When the pointer clicks on a mesh| `click`| `{ type, component, intersect }`  

### Request Example
```html
<template>
  <Renderer antialias resize="window">
    <Camera :position="{ z: 10 }" />
    <Scene>
      <PointLight :position="{ y: 10, z: 10 }" />
      <Box
        @pointerEnter="onPointerEvent"
        @pointerOver="onPointerOver"
        @pointerMove="onPointerEvent"
        @pointerLeave="onPointerEvent"
        @click="onPointerEvent"
      >
        <LambertMaterial />
      </Box>
    </Scene>
  </Renderer>
</template>

<script>
export default {
  methods: {
    onPointerEvent(event) {
      console.log(event);
    },
    onPointerOver(event) {
      event.component.mesh.material.color.set(event.over ? 0xff0000 : 0xffffff);
    },
  },
};
</script>
```
```

--------------------------------

### Create PhysicalMaterial

Source: https://troisjs.github.io/guide/materials/physical-material

Use this component to create a THREE.MeshPhysicalMaterial. It is applied to a Box mesh.

```vue
<Box>
  <PhysicalMaterial color="#ffffff" />
</Box>
```

--------------------------------

### Use Raycaster Component

Source: https://troisjs.github.io/guide/meshes/events

Manage pointer events globally for all scene meshes using the Raycaster component.

```vue
<template>
  <Renderer antialias resize="window">
    <Camera :position="{ z: 10 }" />
    <Raycaster
      @pointerEnter="onPointerEvent"
      @pointerOver="onPointerOver"
      @pointerMove="onPointerEvent"
      @pointerLeave="onPointerEvent"
      @click="onPointerEvent"
    />
    <Scene>
      <PointLight :position="{ y: 10, z: 10 }" />
      <Box v-for="i in 5" :position="{ x: -6 + i * 2 }">
        <LambertMaterial />
      </Box>
    </Scene>
  </Renderer>
</template>

<script>
export default {
  methods: {
    onPointerEvent(event) {
      console.log(event);
    },
    onPointerOver(event) {
      event.component.mesh.material.color.set(event.over ? 0xff0000 : 0xffffff);
    },
  },
};
</script>
```

--------------------------------

### Using LambertMaterial in TroisJS

Source: https://troisjs.github.io/guide/materials/lambert-material

This snippet demonstrates how to use the LambertMaterial component within a Box primitive in TroisJS. Ensure the LambertMaterial is a child of the mesh component.

```vue
<Box>
  <LambertMaterial />
</Box>
```

--------------------------------

### Basic ShaderMaterial Usage

Source: https://troisjs.github.io/guide/materials/shader-material.html

Defines a basic ShaderMaterial within a Box component using the props attribute.

```html
<Box>
  <ShaderMaterial :props="{ uniforms: {}, vertexShader: '...', fragmentShader: '...' }" />
</Box>
```

--------------------------------

### Raycaster Component

Source: https://troisjs.github.io/guide/meshes/events

Utilize the Raycaster component for global pointer event handling across all scene meshes.

```APIDOC
## Raycaster Component
If you need to easily handle pointer events on all your scene's meshes, you can use `Raycaster` component :

### Request Example
```html
<template>
  <Renderer antialias resize="window">
    <Camera :position="{ z: 10 }" />
    <Raycaster
      @pointerEnter="onPointerEvent"
      @pointerOver="onPointerOver"
      @pointerMove="onPointerEvent"
      @pointerLeave="onPointerEvent"
      @click="onPointerEvent"
    />
    <Scene>
      <PointLight :position="{ y: 10, z: 10 }" />
      <Box v-for="i in 5" :position="{ x: -6 + i * 2 }">
        <LambertMaterial />
      </Box>
    </Scene>
  </Renderer>
</template>

<script>
export default {
  methods: {
    onPointerEvent(event) {
      console.log(event);
    },
    onPointerOver(event) {
      event.component.mesh.material.color.set(event.over ? 0xff0000 : 0xffffff);
    },
  },
};
</script>
```
```

--------------------------------

### Create a Mesh Group in TroisJS

Source: https://troisjs.github.io/guide/meshes/groups

Use the Group component to wrap multiple mesh elements for better organizational clarity.

```html
<Group>
  <!-- <Box ref="box1"/> -->
  <!-- <Box ref="box2"/> -->
  <!-- <GltfModel ref="model1"/> -->
</Group>
```

--------------------------------

### Access ThreeJS Material Instance

Source: https://troisjs.github.io/guide/materials

Assign a ref to a PhongMaterial to access its underlying Three.js material instance within your component's script.

```html
<PhongMaterial ref="material" />

```

--------------------------------

### Implement Stats Component in TroisJS

Source: https://troisjs.github.io/guide/extras

Use the Stats component to monitor renderer performance. It can be used with default settings or configured manually by disabling auto-setup.

```vue
<template>
  <!-- ... -->
  <Renderer>
    <!-- default options, no more setup needed -->
    <!-- must be child of a Renderer -->
    <Stats/>

    <!-- prevent default setup and handle manually -->
    <Stats no-setup @created="doSomething"/>
  </Render>
  <!-- ... -->
</template>

<script>
import Stats from 'troisjs/src/components/misc/Stats'

export default {
  components: { Stats },
  methods: {
    doSomething(stats){
      // do something with `stats` (optional)
    }
  }
}
</script>
```

--------------------------------

### Execute code before render with onBeforeRender

Source: https://troisjs.github.io/guide/core/raf

Use the onBeforeRender hook to perform per-frame updates on ThreeJS objects. Access the renderer and mesh components via Vue refs.

```vue
<template>
  <Renderer ref="renderer">
    <Camera :position="{ z: 10 }" />
    <Scene>
      <PointLight :position="{ y: 50, z: 50 }" />
      <Box ref="box" :rotation="{ y: Math.PI / 4, z: Math.PI / 4 }">
        <LambertMaterial />
      </Box>
    </Scene>
  </Renderer>
</template>

<script>
export default {
  mounted() {
    const renderer = this.$refs.renderer;
    const box = this.$refs.box.mesh;
    renderer.onBeforeRender(() => {
      box.rotation.x += 0.01;
    });
  },
};
</script>
```

--------------------------------

### Apply Texture to ShaderMaterial

Source: https://troisjs.github.io/guide/textures/texture.html

Use the uniform prop to define the uniform name for the texture within a ShaderMaterial.

```html
<ShaderMaterial :fragmentShader="...">
  <!-- uniform prop is required - will be uniform name in texture -->
  <Texture src="/my/texture/src.png" uniform="myCustomTexture"/>
</ShaderMaterial>
```

--------------------------------

### SubSurfaceMaterial Properties

Source: https://troisjs.github.io/guide/materials/sub-surface-material

Lists and describes the available properties for customizing the SubSurfaceMaterial.

```APIDOC
## SubSurfaceMaterial Properties

### Description

Properties available for customizing the `SubSurfaceMaterial`.

### Method

N/A (Component Usage)

### Endpoint

N/A (Component Usage)

### Parameters

#### Path Parameters

N/A

#### Query Parameters

N/A

#### Request Body

N/A

### Request Example

N/A

### Response

N/A

#### Success Response (200)

N/A

#### Response Example

N/A

### Properties Table

Name| Description| Type| Default
---|---|---|---
`diffuse`| Material color.| String| #ffffff
`thicknessColor`| Thickness color.| String| #ffffff
`thicknessDistortion`| Thickness distortion.| Number| `0.4`
`thicknessAmbient`| Ambient thickness.| Number| `0.01`
`thicknessAttenuation`| Thickness attenuation.| Number| `0.7`
`thicknessPower`| Thickness power.| Number| `2`
`thicknessScale`| Thickness scale| Number| `4`
`transparent`| Whether or not the material is transparent.| Boolean| `false`
`opacity`| Material opacity.| Number| `1`
`vertexColors`| Use vertex colors on material.| Boolean| `false`
```

--------------------------------

### Configure Intersect Recursive

Source: https://troisjs.github.io/guide/meshes/events

Enable recursive intersection checking for complex objects like GLTF models.

```vue
<Raycaster intersect-recursive />
```

```vue
<Renderer :pointer="{ intersectRecursive: true }">
  <Camera :position="{ z: 1 }" />
  <Scene>
    <GltfModel @click="onClick" src="..." />
  </Scene>
</Renderer>
```

```vue
<Renderer>
  <Camera :position="{ z: 1 }" />
  <Scene>
    <Raycaster intersect-recursive @click="onClick" />
    <GltfModel src="..." />
  </Scene>
</Renderer>
```

--------------------------------

### Register TroisJS Vue Plugin

Source: https://troisjs.github.io/guide/install

Use this code to register the TroisJS Vue plugin globally in your Vue.js application.

```javascript
import { TroisJSVuePlugin } from 'troisjs';
app.use(TroisJSVuePlugin);
```

--------------------------------

### Accessing Three.js Renderer Instance

Source: https://troisjs.github.io/guide/core/renderer.html

Access the Three.js renderer instance via the ref assigned to the Renderer component. The actual renderer is available at `this.$ref.renderer.renderer`.

```javascript
const renderer = this.$ref.renderer.renderer;
```

--------------------------------

### intersectRecursive Configuration

Source: https://troisjs.github.io/guide/meshes/events

Enable recursive intersection checking for raycasting to include descendants.

```APIDOC
### intersectRecursive
If present (=`true`), it also checks all descendants. Otherwise it only checks intersection with the object.
Default is `false`.

```html
<Raycaster intersect-recursive />
```

Starting in v0.3.2 GLTF-models accept raycasting events as well. To make use of this **you have to** set `intersectRecursive` to `true` depending on your implementation:
  1. `Mesh` based events (each mesh reports needs its own interaction events)

```html
<Renderer :pointer="{ intersectRecursive: true }">
  <Camera :position="{ z: 1 }" />
  <Scene>
    <GltfModel @click="onClick" src="..." />
  </Scene>
</Renderer>
```

  2. `Raycaster` based implementation (one event fires no matter which object reports a collision)

```html
<Renderer>
  <Camera :position="{ z: 1 }" />
  <Scene>
    <Raycaster intersect-recursive @click="onClick" />
    <GltfModel src="..." />
  </Scene>
</Renderer>
```
```

--------------------------------

### intersectMode Configuration

Source: https://troisjs.github.io/guide/meshes/events

Configure the intersection detection mode for raycasting, either on pointer move or every frame.

```APIDOC
### intersectMode
By default, raycasting will be made on pointer move, but it can be useful to do the same on every frame.
If using mesh events, you should set `pointer` prop on `Renderer` :

```html
<Renderer :pointer="{ intersectMode: 'frame' }">
  ...
</Renderer>
```

If using `Raycaster` component, you should set `intersect-mode` prop :

```html
<Raycaster intersect-mode="frame" />
```
```

--------------------------------

### Accessing Three.js Renderer

Source: https://troisjs.github.io/guide/core/renderer.html

Set a ref on the Renderer component to access the underlying Three.js WebGLRenderer instance in your component's script.

```html
<Renderer ref="renderer">
  ...
</Renderer>
```

--------------------------------

### Renderer Events API

Source: https://troisjs.github.io/guide/core/renderer.html

API for adding and removing event listeners on the Renderer component.

```APIDOC
## Renderer Events API (v0.3)

### Adding/Removing Event Listeners

Use the following functions to manage event listeners:

- `onInit(callback)`: Add an `init` listener.
- `onMounted(callback)`: Add a `mounted` listener.
- `onResize(callback)`: Add a `resize` listener.
- `onBeforeRender(callback)`: Add a `beforerender` listener.
- `offBeforeRender(callback)`: Remove a `beforerender` listener.
- `onAfterRender(callback)`: Add an `afterrender` listener.
- `offAfterRender(callback)`: Remove an `afterrender` listener.

Alternatively, use the generic methods:

- `addListener(type, callback)`: Add an event listener.
- `removeListener(type, callback)`: Remove an event listener.

### Event Payloads

- `onInit`: `{ type: 'init', renderer }`
- `onMounted`: `{ type: 'mounted', renderer }`
- `onResize`: `{ type: 'init', renderer, size }`
- `onBeforeRender`: `{ type: 'beforerender', renderer, time }`
- `onAfterRender`: `{ type: 'afterrender', renderer, time }`
```

--------------------------------

### Access ThreeJS Camera Object

Source: https://troisjs.github.io/guide/core/camera.html

After setting a ref on the Camera component, you can access the ThreeJS camera instance via `this.$ref.camera.camera` in your component's script.

```javascript
const scene = this.$ref.camera.camera;
```

--------------------------------

### Handle Mesh Events

Source: https://troisjs.github.io/guide/meshes/events

Attach pointer events directly to a Box component using Vue event listeners.

```vue
<template>
  <Renderer antialias resize="window">
    <Camera :position="{ z: 10 }" />
    <Scene>
      <PointLight :position="{ y: 10, z: 10 }" />
      <Box
        @pointerEnter="onPointerEvent"
        @pointerOver="onPointerOver"
        @pointerMove="onPointerEvent"
        @pointerLeave="onPointerEvent"
        @click="onPointerEvent"
      >
        <LambertMaterial />
      </Box>
    </Scene>
  </Renderer>
</template>

<script>
export default {
  methods: {
    onPointerEvent(event) {
      console.log(event);
    },
    onPointerOver(event) {
      event.component.mesh.material.color.set(event.over ? 0xff0000 : 0xffffff);
    },
  },
};
</script>
```

--------------------------------

### Set Ref on Camera Component

Source: https://troisjs.github.io/guide/core/camera.html

To access the ThreeJS camera object, you need to set a ref on the Camera component in your Vue template.

```html
<Camera ref="camera" />
```

--------------------------------

### Adding Textures to ShaderMaterial

Source: https://troisjs.github.io/guide/materials/shader-material.html

Passes a texture to the shader by nesting a Texture component with a specified uniform name.

```html
<ShaderMaterial :props="{ fragmentShader: '...' }">
  <Texture src="/my/texture/src.png" uniform="myCustomTexture"/>
</ShaderMaterial>
```

--------------------------------

### Retrieve ThreeJS Material in Script

Source: https://troisjs.github.io/guide/materials

Access the Three.js material instance from a ref in your component's script to manipulate it directly.

```javascript
const material = this.$ref.material.material;

```

--------------------------------

### CubeTexture Component

Source: https://troisjs.github.io/guide/textures/cube-texture

The CubeTexture component is used to load and apply cube textures to materials in TroisJS. It can be used within a BasicMaterial or other compatible materials.

```APIDOC
## CubeTexture Component

### Description
Loads a cube texture into a parent Material. See Texture for more info.

### Usage Example
```html
<Box>
  <BasicMaterial>
    <CubeTexture/>
  </BasicMaterial>
</Box>
```

### Props

#### Path Parameter
- **path** (String) - Optional - Path to cube texture.

#### URLs Parameter
- **urls** (Array) - Optional - URLs to load. Defaults to `['px.jpg', 'nx.jpg', 'py.jpg', 'ny.jpg', 'pz.jpg', 'nz.jpg']`.

#### onLoad Prop
- **onLoad** (Function) - Optional - Function to fire when all textures have loaded.

#### onProgress Prop
- **onProgress** (Function) - Optional - Function to fire on load progress.

#### onError Prop
- **onError** (Function) - Optional - Function to fire on load error.

#### Name Prop
- **name** (String) - Optional - Texture name. Defaults to `'envMap'`.

#### Refraction Prop
- **refraction** (Boolean) - Optional - Whether this material uses refraction mapping or reflection mapping. Defaults to `false`.

#### RefractionRatio Prop
- **refractionRatio** (Number) - Optional - The refraction ratio of the material. Defaults to `0.98`.
```

--------------------------------

### Access ThreeJS Scene via Ref

Source: https://troisjs.github.io/guide/core/scene.html

To access the ThreeJS scene, set a ref on the Scene component. This allows you to interact with the underlying Three.js scene object in your component's script.

```html
<Scene ref="scene">
  ...
</Scene>

```

--------------------------------

### Accessing Three.js OrbitControls

Source: https://troisjs.github.io/guide/core/renderer.html

Access the Three.js OrbitControls instance, which is managed by the renderer's `cameraCtrl` property. This allows for direct manipulation of camera controls.

```javascript
const orbitCtrl = this.$ref.renderer.three.cameraCtrl;
```

--------------------------------

### Access ThreeJS Mesh via Ref

Source: https://troisjs.github.io/guide/meshes

Assign a ref to a mesh component to access the underlying ThreeJS mesh object in your component's script. Use $ref to retrieve the mesh.

```html
<Box ref="box" />
```

```javascript
const mesh = this.$ref.box.mesh;
```

--------------------------------

### Adjust Model Material Properties

Source: https://troisjs.github.io/guide/models

Traverse the loaded model object to modify material properties such as metalness, which can resolve issues with ambient light rendering.

```vue
<template>
    <!-- ... -->
        <GltfModel src="..." @load="onReady"/>
    <!-- ... -->
</template>

<script>
export default {
    methods: {
        onReady(model){
            model.traverse(o => {
                if (o.isMesh){
                    // handle both multiple and single materials
                    const asArray = Array.isArray(o.material) ? o.material : [o.material]
                    // 0 works for matte materials - change as needed
                    asArray.forEach(mat => mat.metalness = 0)
                }
            })
        }
    }
}
</script>
```

--------------------------------

### Configure Intersect Mode

Source: https://troisjs.github.io/guide/meshes/events

Set the intersection mode to frame-based updates for Renderer or Raycaster components.

```vue
<Renderer :pointer="{ intersectMode: 'frame' }">
  ...
</Renderer>
```

```vue
<Raycaster intersect-mode="frame" />
```
Tokens:
Raw