TroisJS: Three.js for Vue 3

Common errors

• Error: Cannot find module 'troisjs'

  cause The `troisjs` package has not been installed or correctly linked in your project.
  fix Run `npm install troisjs three vue` or `yarn add troisjs three vue` to install the package and its core peer dependencies.

• [Vue warn]: Failed to resolve component: <component-name>

  cause TroisJS components (e.g., <Renderer>, <Box>) are not globally registered or locally imported in your Vue application.
  fix Ensure you have called `app.use(TroisJSVuePlugin)` during your Vue application initialization, or explicitly import and register the component locally within your Vue SFCs if not using the plugin.

• TypeError: Cannot read properties of null (reading 'scene')

  cause Attempting to access properties of a TroisJS component's underlying Three.js object (e.g., `renderer.scene`) before the component has fully mounted and initialized.
  fix Use Vue's lifecycle hooks like `onMounted` or `nextTick` to ensure the component is rendered and its internal Three.js objects are available before attempting to interact with them programmatically. Use `ref` and optional chaining (`?.`) for safer access.

Warnings

• breaking Version 0.3.0 introduced TypeScript support. While not explicitly listed as a breaking change in the changelog for this specific transition, users migrating from pre-0.3.0 JavaScript versions to 0.3.0+ TypeScript projects might encounter type-related issues or require adjustments to their codebase to conform to new type definitions and stricter API contracts.
  Fix: Review the type definitions and adjust component props or API calls to match the new TypeScript interfaces. Ensure your project's TypeScript configuration is set up correctly for Vue components.
• gotcha Event handling for pointer interactions (e.g., click, hover) on 3D objects sometimes fails to register correctly, particularly with complex GLTF models or specific camera setups.
  Fix: Update to TroisJS version 0.3.2 or newer, as specific bug fixes for Raycaster issues (e.g., with GltfModel clicks) were implemented in that release. Ensure your scene setup aligns with the library's recommended practices for raycasting.
• gotcha When using `ShaderMaterial` with custom textures, issues might arise where the texture is not correctly applied or rendered.
  Fix: Upgrade to TroisJS version 0.3.1 or later, which includes a bug fix addressing texture application for `ShaderMaterial`.

Install

• npm install troisjs npm
• yarn add troisjs yarn
• pnpm add troisjs pnpm

Imports

• TroisJSVuePlugin
  wrong:

  import TroisJSVuePlugin from 'troisjs'

  correct:

  import { TroisJSVuePlugin } from 'troisjs'

  This named export is the primary way to register all TroisJS components globally with your Vue 3 application via `app.use()`.
• Renderer
  wrong:

  import Renderer from 'troisjs'

  correct:

  import { Renderer } from 'troisjs'

  While components are typically registered via `TroisJSVuePlugin`, you can also import them individually as named exports for local component registration or specific use cases, benefiting from tree-shaking. Other components like `Camera`, `Scene`, `Box`, `PointLight`, etc., follow the same named import pattern.
• useRenderer

  import { useRenderer } from 'troisjs'

  This composition API hook allows access to the Three.js renderer instance within a Vue component, useful for imperative Three.js operations.

Quickstart

This quickstart demonstrates a basic TroisJS setup using Vue 3's `createApp` and `script setup` composition API. It initializes a 3D scene with a camera, light, and a rotating box, showing how to register TroisJS components globally via `TroisJSVuePlugin` and access Three.js objects for animation.

import { createApp } from 'vue'
import { TroisJSVuePlugin } from 'troisjs'
import { ref, onMounted } from 'vue'

const app = createApp({
  template: `
    <renderer ref="rendererRef" antialias orbit-ctrl resize="window">
      <camera :position="{ z: 10 }"></camera>
      <scene>
        <point-light :position="{ y: 50, z: 50 }"></point-light>
        <box ref="boxRef" :rotation="{ y: rotation.y, z: rotation.z }">
          <lambert-material></lambert-material>
        </box>
      </scene>
    </renderer>
  `,
  setup() {
    const rendererRef = ref(null)
    const boxRef = ref(null)
    const rotation = ref({ y: Math.PI / 4, z: Math.PI / 4 })

    onMounted(() => {
      // Access the Three.js scene, camera, etc. via rendererRef.value.scene, etc.
      if (rendererRef.value && boxRef.value) {
        console.log('Renderer and Box components mounted.')
        // Example: animate box rotation
        rendererRef.value.onBeforeRender(() => {
          rotation.value.y += 0.01
          rotation.value.z += 0.005
        })
      }
    })

    return { rendererRef, boxRef, rotation }
  }
})

app.use(TroisJSVuePlugin).mount('#app')