docs: use component list for sidebar

docs/.vitepress/config.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'pathe'
 import { defineConfig } from 'vitepress'
+import components from '../component-list/components'
 
 const whitelist = ['TresCanvas', 'TresLeches', 'TresScene']
 
@@ -53,117 +54,7 @@ export default defineConfig({
       { text: 'Examples', link: 'https://lab.tresjs.org/' },
     ],
 
-    sidebar: [
-      {
-        text: 'Guide',
-        items: [
-          { text: 'Introduction', link: '/guide/' },
-          { text: 'Migration from v3', link: '/guide/migrating-from-v3' },
-        ],
-      },
-      {
-        text: 'Abstractions',
-        items: [
-          { 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: 'AnimatedSprite', link: '/guide/abstractions/animated-sprite' },
-        ],
-      },
-      {
-        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: 'Loaders',
-        items: [
-          { text: 'useProgress', link: '/guide/loaders/use-progress' },
-          { text: 'useGLTF', link: '/guide/loaders/use-gltf' },
-          { text: 'GLTFModel', link: '/guide/loaders/gltf-model' },
-          { text: 'useFBX', link: '/guide/loaders/use-fbx' },
-          { text: 'FBXModel', link: '/guide/loaders/fbx-model' },
-          { text: 'useVideoTexture', link: '/guide/loaders/use-video-texture' },
-          { text: 'SVG', link: '/guide/loaders/svg' },
-        ],
-      },
-      {
-        text: 'Materials',
-        collapsed: true,
-        items: [
-          { text: 'WobbleMaterial', link: '/guide/materials/wobble-material' },
-          { text: 'MeshGlassMaterial', link: '/guide/materials/glass-material' },
-          { text: 'CustomShaderMaterial', link: '/guide/materials/custom-shader-material' },
-          { text: 'MeshReflectionMaterial', link: '/guide/materials/mesh-reflection-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: '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: 'Ring', link: '/guide/shapes/ring' },
-          { text: 'RoundedBox', link: '/guide/shapes/rounded-box' },
-          { 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: '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: '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' },
-        ],
-      },
-    ],
-
+    sidebar: components,
     socialLinks: [
       { icon: 'github', link: 'https://github.com/tresjs/cientos' },
       { icon: 'twitter', link: 'https://twitter.com/tresjs_dev' },

docs/.vitepress/theme/components/BillboardDemo.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+import { Billboard, Box, OrbitControls } from '@tresjs/cientos'
+import { TresCanvas } from '@tresjs/core'
+import { Vector3 } from 'three'
+
+const COUNT = 5 * 5
+const positions = Array.from({ length: COUNT }).fill(0).map((_, i) => {
+  return new Vector3(
+    i % 5 - 2,
+    Math.floor(i / 5) - 2,
+    0,
+  )
+})
+</script>
+
+<template>
+  <TresCanvas clear-color="#333333">
+    <OrbitControls />
+    <TresPerspectiveCamera :position="[0, 0, 10]" />
+    <Billboard v-for="position, i of positions" :key="i" :position="position">
+      <Box :scale="[0.5, 0.5, 0.001]">
+        <TresMeshNormalMaterial />
+      </Box>
+    </Billboard>
+  </TresCanvas>
+</template>

docs/component-list/components.ts

@@ -11,12 +11,11 @@ export default [
       { 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: 'useSurfaceSampler', link: '/guide/abstractions/use-surface-sampler' },
       { text: 'Sampler', link: '/guide/abstractions/sampler' },
       { text: 'PositionalAudio', link: '/guide/abstractions/positional-audio' },
+      { text: 'AnimatedSprite', link: '/guide/abstractions/animated-sprite' },
+      { text: 'Billboard', link: '/guide/abstractions/billboard' },
     ],
   },
   {
@@ -25,10 +24,7 @@ export default [
       { 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: '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' },
@@ -48,21 +44,18 @@ export default [
   },
   {
     text: 'Materials',
+    collapsed: true,
     items: [
       { 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: 'CustomShaderMaterial', link: '/guide/materials/custom-shader-material' },
+      { text: 'MeshReflectionMaterial', link: '/guide/materials/mesh-reflection-material' },
+      { text: 'HolographicMaterial', link: '/guide/materials/holographic-material' },
     ],
   },
   {
     text: 'Shapes',
+    collapsed: true,
     items: [
       { text: 'Box', link: '/guide/shapes/box' },
       { text: 'CatmullRomCurve3', link: '/guide/shapes/catmullromcurve3' },
@@ -102,6 +95,7 @@ export default [
   },
   {
     text: 'Misc',
+    collapsed: true,
     items: [
       { text: 'Stats', link: '/guide/misc/stats' },
       { text: 'Html', link: '/guide/misc/html-component' },
@@ -112,6 +106,7 @@ export default [
   },
   {
     text: 'Directives',
+    collapsed: true,
     items: [
       { text: 'v-log', link: '/guide/directives/v-log' },
       { text: 'v-light-helper', link: '/guide/directives/v-light-helper' },

docs/guide/abstractions/billboard.md

@@ -0,0 +1,20 @@
+# Billboard
+
+<DocsDemo>
+  <BillboardDemo />
+</DocsDemo>
+
+Adds a `THREE.Group` that faces the camera.
+
+## Usage
+
+<<< @/.vitepress/theme/components/BillboardDemo.vue
+
+## Props
+
+| Prop             | Description                                          | Default       |
+| :--------------- | :--------------------------------------------------- | ------------- |
+| `autoUpdate`     | Whether the `<Billboard />` should face the camera automatically on every frame.       | `true`  |
+| `lockX`          | Whether to lock the x-axis.                          | `false` |
+| `lockY`          | Whether to lock the y-axis.                          | `false` |
+| `lockZ`          | Whether to lock the z-axis.                          | `false` |

playground/vue/src/pages/abstractions/BillboardDemo.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import { Billboard, Box, OrbitControls } from '@tresjs/cientos'
+import { TresCanvas } from '@tresjs/core'
+import { Vector3 } from 'three'
+import '@tresjs/leches/styles'
+
+const COUNT = 5 * 5
+const positions = Array.from({ length: COUNT }).fill(0).map((_, i) => {
+  return new Vector3(
+    i % 5 - 2,
+    Math.floor(i / 5) - 2,
+    0,
+  )
+})
+</script>
+
+<template>
+  <TresCanvas clear-color="#333333">
+    <OrbitControls />
+    <TresPerspectiveCamera :position="[0, 0, 10]" />
+    <Billboard v-for="position, i of positions" :key="i" :position="position">
+      <Box :scale="[0.5, 0.5, 0.001]">
+        <TresMeshNormalMaterial />
+      </Box>
+    </Billboard>
+  </TresCanvas>
+</template>

playground/vue/src/router/routes/abstractions.ts

@@ -59,4 +59,9 @@ export const abstractionsRoutes = [
     name: 'AnimatedSprite',
     component: () => import('../../pages/abstractions/AnimatedSpriteDemo.vue'),
   },
+  {
+    path: '/abstractions/billboard',
+    name: 'Billboard',
+    component: () => import('../../pages/abstractions/BillboardDemo.vue'),
+  },
 ]

src/core/abstractions/Billboard.vue

@@ -0,0 +1,75 @@
+<script setup lang="ts">
+import type { Camera } from 'three'
+import { Euler, Group, Quaternion } from 'three'
+import { shallowRef } from 'vue'
+import { useLoop, useTres } from '@tresjs/core'
+
+export interface BillboardProps {
+  /**
+   * Whether the Billboard should face the camera automatically on every frame.
+   */
+  autoUpdate?: boolean
+  /**
+   * Whether to lock the x-axis.
+   */
+  lockX?: boolean
+  /**
+   * Whether to lock the y-axis.
+   */
+  lockY?: boolean
+  /**
+   * Whether to lock the z-axis.
+   */
+  lockZ?: boolean
+}
+
+const props = withDefaults(defineProps<BillboardProps>(), {
+  autoUpdate: true,
+  lockX: false,
+  lockY: false,
+  lockZ: false,
+})
+
+const outerRef = shallowRef(new Group())
+const innerRef = shallowRef(new Group())
+const q = new Quaternion()
+const r = new Euler()
+
+function update(camera?: Camera) {
+  if (!outerRef.value) { return }
+
+  if (!camera) {
+    const t = useTres()
+    camera = t.camera.value
+    if (!camera) { return }
+  }
+
+  // NOTE: Save current rotation in case we're locking an axis
+  innerRef.value.rotation.copy(r)
+
+  // NOTE: Face the camera
+  outerRef.value.updateMatrix()
+  outerRef.value.updateWorldMatrix(false, false)
+  outerRef.value.getWorldQuaternion(q)
+  camera.getWorldQuaternion(innerRef.value.quaternion).premultiply(q.invert())
+
+  // NOTE: Overwrite locked axes
+  if (props.lockX) { innerRef.value.rotation.x = r.x }
+  if (props.lockY) { innerRef.value.rotation.y = r.y }
+  if (props.lockZ) { innerRef.value.rotation.z = r.z }
+}
+
+useLoop().onBeforeRender(({ camera }) => {
+  if (props.autoUpdate) { update(camera) }
+})
+
+defineExpose({ instance: outerRef, update })
+</script>
+
+<template>
+  <TresGroup ref="outerRef">
+    <TresGroup ref="innerRef">
+      <slot></slot>
+    </TresGroup>
+  </TresGroup>
+</template>

src/core/abstractions/index.ts

@@ -1,4 +1,5 @@
 import AnimatedSprite from './AnimatedSprite/component.vue'
+import Billboard from './Billboard.vue'
 import { GlobalAudio } from './GlobalAudio'
 import Lensflare from './Lensflare/component.vue'
 import Levioso from './Levioso.vue'
@@ -15,6 +16,7 @@ export * from './useFBO/'
 export * from './useSurfaceSampler'
 export {
   AnimatedSprite,
+  Billboard,
   Fbo,
   GlobalAudio,
   Lensflare,