From 84a79e65eedf407ce44eee6d46ac457112e3b79d Mon Sep 17 00:00:00 2001
From: andretchen0 <petermoldovia@yahoo.ca>
Date: Wed, 20 Nov 2024 21:50:21 -0600
Subject: [PATCH 1/3] feat(Billboard): add component, playground, docs

---
 docs/.vitepress/config.ts                     |  1 +
 .../theme/components/BillboardDemo.vue        | 26 +++++++
 docs/component-list/components.ts             |  1 +
 docs/guide/abstractions/billboard.md          | 20 +++++
 .../src/pages/abstractions/BillboardDemo.vue  | 27 +++++++
 .../vue/src/router/routes/abstractions.ts     |  5 ++
 src/core/abstractions/Billboard.vue           | 75 +++++++++++++++++++
 src/core/abstractions/index.ts                |  2 +
 src/core/staging/ContactShadows.vue           |  6 +-
 9 files changed, 160 insertions(+), 3 deletions(-)
 create mode 100644 docs/.vitepress/theme/components/BillboardDemo.vue
 create mode 100644 docs/guide/abstractions/billboard.md
 create mode 100644 playground/vue/src/pages/abstractions/BillboardDemo.vue
 create mode 100644 src/core/abstractions/Billboard.vue

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index a0c7f91ab..ab4c9c720 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -76,6 +76,7 @@ export default defineConfig({
           { text: 'useSurfaceSampler', link: '/guide/abstractions/use-surface-sampler' },
           { text: 'Sampler', link: '/guide/abstractions/sampler' },
           { text: 'AnimatedSprite', link: '/guide/abstractions/animated-sprite' },
+          { text: 'Billboard', link: '/guide/abstractions/billboard' },
         ],
       },
       {
diff --git a/docs/.vitepress/theme/components/BillboardDemo.vue b/docs/.vitepress/theme/components/BillboardDemo.vue
new file mode 100644
index 000000000..079a88f29
--- /dev/null
+++ b/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>
diff --git a/docs/component-list/components.ts b/docs/component-list/components.ts
index ebc3cc8b7..9b8b1e7a2 100644
--- a/docs/component-list/components.ts
+++ b/docs/component-list/components.ts
@@ -17,6 +17,7 @@ export default [
       },
       { text: 'Sampler', link: '/guide/abstractions/sampler' },
       { text: 'PositionalAudio', link: '/guide/abstractions/positional-audio' },
+      { text: 'Billboard', link: '/guide/abstractions/billboard' },
     ],
   },
   {
diff --git a/docs/guide/abstractions/billboard.md b/docs/guide/abstractions/billboard.md
new file mode 100644
index 000000000..420bbd309
--- /dev/null
+++ b/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` |
diff --git a/playground/vue/src/pages/abstractions/BillboardDemo.vue b/playground/vue/src/pages/abstractions/BillboardDemo.vue
new file mode 100644
index 000000000..5e4717669
--- /dev/null
+++ b/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>
diff --git a/playground/vue/src/router/routes/abstractions.ts b/playground/vue/src/router/routes/abstractions.ts
index 1c10a6f80..574fbdbef 100644
--- a/playground/vue/src/router/routes/abstractions.ts
+++ b/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'),
+  },
 ]
diff --git a/src/core/abstractions/Billboard.vue b/src/core/abstractions/Billboard.vue
new file mode 100644
index 000000000..ed17120d1
--- /dev/null
+++ b/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>
diff --git a/src/core/abstractions/index.ts b/src/core/abstractions/index.ts
index fc1e0bc52..61379fb9d 100644
--- a/src/core/abstractions/index.ts
+++ b/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,
diff --git a/src/core/staging/ContactShadows.vue b/src/core/staging/ContactShadows.vue
index c1c9e2012..1723ee933 100644
--- a/src/core/staging/ContactShadows.vue
+++ b/src/core/staging/ContactShadows.vue
@@ -312,9 +312,9 @@ function setColors(ps: typeof props, pool: ReturnType<typeof init>) {
     const { r, g, b } = tint
     shader.fragmentShader = /* glsl */`
     ${shader.fragmentShader.replace(
-        'gl_FragColor = vec4( vec3( 1.0 - fragCoordZ ), opacity );',
-        `gl_FragColor = vec4( ${r}, ${g}, ${b}, ( 1.0 - fragCoordZ ) * opacity);`,
-      )}
+      'gl_FragColor = vec4( vec3( 1.0 - fragCoordZ ), opacity );',
+      `gl_FragColor = vec4( ${r}, ${g}, ${b}, ( 1.0 - fragCoordZ ) * opacity);`,
+    )}
     `
   }
 }

From f563795f3c182daf7766dc73d65d23fce814425a Mon Sep 17 00:00:00 2001
From: andretchen0 <petermoldovia@yahoo.ca>
Date: Thu, 21 Nov 2024 00:04:10 -0600
Subject: [PATCH 2/3] docs: refactor sidebar to use component-list

---
 docs/.vitepress/config.ts         | 114 +-----------------------------
 docs/component-list/components.ts |  22 ++----
 2 files changed, 8 insertions(+), 128 deletions(-)

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index ab4c9c720..0492d96be 100644
--- a/docs/.vitepress/config.ts
+++ b/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,118 +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: '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: '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' },
diff --git a/docs/component-list/components.ts b/docs/component-list/components.ts
index 9b8b1e7a2..58767dd09 100644
--- a/docs/component-list/components.ts
+++ b/docs/component-list/components.ts
@@ -11,12 +11,10 @@ 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' },
     ],
   },
@@ -26,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' },
@@ -52,14 +47,9 @@ export default [
     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' },
     ],
   },
   {

From bf9ed759dba4da1e919032e7141c728f8835531d Mon Sep 17 00:00:00 2001
From: andretchen0 <petermoldovia@yahoo.ca>
Date: Thu, 21 Nov 2024 00:16:43 -0600
Subject: [PATCH 3/3] docs: add collapsed to component-list

---
 docs/component-list/components.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/component-list/components.ts b/docs/component-list/components.ts
index 58767dd09..a72793ebf 100644
--- a/docs/component-list/components.ts
+++ b/docs/component-list/components.ts
@@ -44,6 +44,7 @@ export default [
   },
   {
     text: 'Materials',
+    collapsed: true,
     items: [
       { text: 'WobbleMaterial', link: '/guide/materials/wobble-material' },
       { text: 'MeshGlassMaterial', link: '/guide/materials/glass-material' },
@@ -54,6 +55,7 @@ export default [
   },
   {
     text: 'Shapes',
+    collapsed: true,
     items: [
       { text: 'Box', link: '/guide/shapes/box' },
       { text: 'CatmullRomCurve3', link: '/guide/shapes/catmullromcurve3' },
@@ -93,6 +95,7 @@ export default [
   },
   {
     text: 'Misc',
+    collapsed: true,
     items: [
       { text: 'Stats', link: '/guide/misc/stats' },
       { text: 'Html', link: '/guide/misc/html-component' },
@@ -103,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' },