docs: examples updated

apps/playground/src/App.vue

@@ -1,18 +1,47 @@
 <script setup lang="ts">
 import { TresCanvas } from '@tresjs/core'
 import { OrbitControls } from '@tresjs/cientos'
+import { BasicShadowMap, NoToneMapping, sRGBEncoding } from 'three'
+import { reactive, ref } from 'vue'
+
+const gl = {
+  clearColor: '#82DBC5',
+  shadows: true,
+  alpha: false,
+  shadowMapType: BasicShadowMap,
+  outputEncoding: sRGBEncoding,
+  toneMapping: NoToneMapping,
+}
+
+const groupRef = ref(null)
+
+const groupRotation = reactive([0, 0, Math.PI / 2])
+
+setInterval(() => {
+  if (groupRef.value) {
+    groupRef.value.rotation.z += Math.PI / 4
+  }
+  /*  groupRotation[2] += Math.PI / 4 */
+}, 1000)
 </script>
 
 <template>
-  <TresCanvas>
+  <TresCanvas v-bind="gl">
     <TresPerspectiveCamera :args="[45, 1, 0.1, 2000]" :position="[3, 3, 4]" />
     <OrbitControls />
-    <TresAmbientLight :args="[0xffffff, 0.5]" />
-    <TresDirectionalLight :args="[0xffffff, 0.5]" />
-    <TresMesh>
-      <TresBoxGeometry :args="[1, 1, 1]" />
-      <TresMeshToonMaterial :color="'teal'" />
-    </TresMesh>
+    <TresAmbientLight :args="[0xffffff, 1]" />
+    <TresDirectionalLight :args="[0xffffff, 1.2]" />
+    <TresGroup ref="groupRef" :rotation="groupRotation">
+      <TresMesh>
+        <TresBoxGeometry :args="[1, 1, 1]" />
+        <TresMeshToonMaterial :color="'teal'" />
+      </TresMesh>
+      <TresMesh :position="[2, 0, 0]">
+        <TresSphereGeometry :args="[0.5, 32, 32]" />
+        <TresMeshToonMaterial :color="'orange'" />
+      </TresMesh>
+    </TresGroup>
+    <TresGridHelper :args="[10, 10]" />
   </TresCanvas>
 </template>
 

docs/.vitepress/theme/index.ts

@@ -2,9 +2,11 @@ import 'uno.css'
 // .vitepress/theme/index.ts
 import DefaultTheme from 'vitepress/theme'
 import './config.css'
-import EmbedExperiment from './components/EmbedExperiment.vue'
+import FirstScene from './components/FirstScene.vue'
 
 import StackBlitzEmbed from './components/StackBlitzEmbed.vue'
+import EmbedExperiment from './components/EmbedExperiment.vue'
+
 import TresLayout from './TresLayout.vue'
 
 export default {
@@ -12,6 +14,7 @@ export default {
 
   enhanceApp(ctx) {
     DefaultTheme.enhanceApp(ctx)
+    ctx.app.component('FirstScene', FirstScene)
     ctx.app.component('StackBlitzEmbed', StackBlitzEmbed)
     ctx.app.component('EmbedExperiment', EmbedExperiment)
   },

docs/examples/basic-animations.md

@@ -29,14 +29,17 @@ To improve the performance, we will use a [Shallow Ref](https://v3.vuejs.org/gui
 
 ```vue
 <script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
 const boxRef: ShallowRef<TresInstance | null> = shallowRef(null)
 </script>
 
 <template>
-  <TresMesh ref="boxRef" :scale="1" cast-shadow>
-    <TresBoxGeometry :args="[1, 1, 1]" />
-    <TresMeshStandardMaterial v-bind="pbrTexture" />
-  </TresMesh>
+  <TresCanvas>
+    <TresMesh ref="boxRef" :scale="1" cast-shadow>
+      <TresBoxGeometry :args="[1, 1, 1]" />
+      <TresMeshStandardMaterial v-bind="pbrTexture" />
+    </TresMesh>
+  </TresCanvas>
 </template>
 ```
 
@@ -54,3 +57,30 @@ onLoop(({ _delta, elapsed }) => {
 ```
 
 You can also use the `delta` from the internal [THREE clock](https://threejs.org/docs/?q=clock#api/en/core/Clock) or the `elapsed` to animate the cube.
+
+## But why not using reactivity?
+
+You might be wondering why we are not using reactivity to animate the cube. The answer is simple, performance.
+
+```vue
+// This is a bad idea ❌
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+
+const boxRotation = reactive([0, 0, 0])
+
+onLoop(({ _delta, elapsed }) => {
+  boxRotation[1] += 0.01
+  boxRotation[2] = elapsed * 0.2
+})
+</script>
+```
+
+We can be tempted to use reactivity to animate the cube. But it would be a bad idea.
+The reason is that [Vue's reactivity is based on Proxies](https://vuejs.org/guide/extras/reactivity-in-depth.html#how-reactivity-works-in-vue) and it's not designed to be used in a render loop that updates 60 or more times per second.
+
+The embedded page below shows the [benchmark of a proxy vs a regular object](https://measurethat.net/Benchmarks/Show/12503/0/object-vs-proxy-vs-proxy-setter). As you can see, the proxy is 5 times slower than the regular object.
+
+<EmbedExperiment src="https://measurethat.net/Embed?id=399142" />
+
+You can read more about this in the [Caveats](../advanced/caveats.md#reactivity) section.

docs/examples/groups.md

@@ -1,4 +1,4 @@
-# Group <Badge type="warning" text="^1.5.0" />
+# Group
 
 A `<TresGroup>` is an instance of the [THREE.Group](https://threejs.org/docs/#api/en/objects/Group) class which is almost the same as a [THREE.Object3D](https://threejs.org/docs/#api/en/objects/Object3D) but allows you to **group together multiple objects in the scene** so that they can be manipulated as a single unit (transform, rotation, etc).
 
@@ -6,7 +6,7 @@ A `<TresGroup>` is an instance of the [THREE.Group](https://threejs.org/docs/#ap
 
 ## Usage
 
-```vue{12,21}
+```vue{13,22}
 <script setup lang="ts">
 const groupRef = ref()
 const { onLoop } = useRenderLoop()
@@ -18,15 +18,17 @@ onLoop(() => {
 })
 </script>
 <template>
-  <TresGroup ref="groupRef" :position="[2,0,0]">
-    <TresMesh>
-      <TresBoxGeometry />
-      <TresMeshBasicMaterial color="red" />
-    </TresMesh>
-    <TresMesh>
-      <TresSphereGeometry />
-      <TresMeshBasicMaterial color="blue" />
-    </TresMesh>
-  </TresGroup>
+  <TresCanvas>
+    <TresGroup ref="groupRef" :position="[2,0,0]">
+      <TresMesh>
+        <TresBoxGeometry />
+        <TresMeshBasicMaterial color="red" />
+      </TresMesh>
+      <TresMesh>
+        <TresSphereGeometry />
+        <TresMeshBasicMaterial color="blue" />
+      </TresMesh>
+    </TresGroup>
+  </TresCanvas>
 </template>
 ```

docs/examples/load-models.md

@@ -25,12 +25,10 @@ const { scene } = await useLoader(GLTFLoader, '/models/AkuAku.gltf')
 
 Then you can pass the model scene to a `TresMesh` component:
 
-```html{4}
+```html{3}
 <Suspense>
   <TresCanvas>
-    <TresScene>
       <TresMesh v-bind="scene" />
-    </TresScene>
   </TresCanvas>
 </Suspense>
 ```
@@ -59,21 +57,19 @@ const { scene } = await useGLTF('/models/AkuAku.gltf', { draco: true })
 
 The `GLTFModel` component is a wrapper around `useGLTF` that's available from [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package.
 
-```vue{2,10}
+```vue{2,9}
 <script setup lang="ts">
 import { OrbitControls, GLTFModel } from '@tresjs/cientos'
 </script>
 <template>
-  <Suspense>
-    <TresCanvas clear-color="#82DBC5" shadows alpha>
-      <TresPerspectiveCamera :position="[11, 11, 11]" />
-      <OrbitControls />
-      <TresScene>
-        <GLTFModel path="/models/AkuAku.gltf" draco />
-        <TresDirectionalLight :position="[-4, 8, 4]" :intensity="1.5" cast-shadow />
-      </TresScene>
-    </TresCanvas>
-  </Suspense>
+  <TresCanvas clear-color="#82DBC5" shadows alpha>
+    <TresPerspectiveCamera :position="[11, 11, 11]" />
+    <OrbitControls />
+    <Suspense>
+      <GLTFModel path="/models/AkuAku.gltf" draco />
+      <TresDirectionalLight :position="[-4, 8, 4]" :intensity="1.5" cast-shadow />
+    </Suspense>
+  </TresCanvas>
 </template>
 ```
 
@@ -91,12 +87,10 @@ const model = await useFBX('/models/AkuAku.fbx')
 
 Then is as straightforward as adding the scene to your scene:
 
-```html{4}
+```html{3}
 <Suspense>
   <TresCanvas shadows alpha>
-    <TresScene>
       <TresMesh v-bind="scene" />
-    </TresScene>
   </TresCanvas>
 </Suspense>
 ```
@@ -105,20 +99,18 @@ Then is as straightforward as adding the scene to your scene:
 
 The `FBXModel` component is a wrapper around `useFBX` that's available from [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package. It's similar usage to `GLTFModel`:
 
-```vue{2,10}
+```vue{2,9}
 <script setup lang="ts">
 import { OrbitControls, FBXModel } from '@tresjs/cientos'
 </script>
 <template>
-  <Suspense>
     <TresCanvas clear-color="#82DBC5" shadows alpha>
       <TresPerspectiveCamera :position="[11, 11, 11]" />
       <OrbitControls />
-      <TresScene>
-        <FBXModel path="/models/AkuAku.fbx" />
+        <Suspense>
+          <FBXModel path="/models/AkuAku.fbx" />
+        </Suspense>
         <TresDirectionalLight :position="[-4, 8, 4]" :intensity="1.5" cast-shadow />
-      </TresScene>
     </TresCanvas>
-  </Suspense>
 </template>
 ```

docs/examples/orbit-controls.md

@@ -36,9 +36,7 @@ Now you can use the `TresOrbitControls` component in your scene.
 ```vue
 <template>
   <TresCanvas shadows alpha>
-    <TresScene>
-      <TresOrbitControls v-if="state.renderer" :args="[state.camera, state.renderer?.domElement]" />
-    </TresScene>
+    <TresOrbitControls v-if="state.renderer" :args="[state.camera, state.renderer?.domElement]" />
   </TresCanvas>
 </template>
 ```
@@ -67,10 +65,7 @@ const { state } = useThree()
 </script>
 <template>
   <TresCanvas shadows alpha>
-    <TresScene>
-      <TresOrbitControls v-if="state.renderer" :args="[state.camera, state.renderer?.domElement]" />
-      ...
-    </TresScene>
+    <TresOrbitControls v-if="state.renderer" :args="[state.camera, state.renderer?.domElement]" />
   </TresCanvas>
 </template>
 ```
@@ -87,7 +82,6 @@ It just works. 💯
 <template>
   <TresCanvas shadows alpha>
     <OrbitControls />
-    <TresScene> ... </TresScene>
   </TresCanvas>
 </template>
 ```

docs/examples/text-3d.md

@@ -54,11 +54,9 @@ Now you can use the `TresTextGeometry` component inside a TresMesh in your scene
 ```vue
 <template>
   <TresCanvas shadows alpha>
-    <TresScene>
-      <TresMesh>
-        <TresTextGeometry :args="['TresJS', { font, ...fontOptions }]" center />
-      </TresMesh>
-    </TresScene>
+    <TresMesh>
+      <TresTextGeometry :args="['TresJS', { font, ...fontOptions }]" center />
+    </TresMesh>
   </TresCanvas>
 </template>
 ```
@@ -128,10 +126,12 @@ const font = await new Promise((resolve, reject) => {
 const matcapTexture = await useTexture(['https://raw.githubusercontent.com/Tresjs/assets/main/textures/matcaps/7.png'])
 </script>
 <template>
-  <TresMesh>
-    <TresTextGeometry :args="['TresJS', { font, ...fontOptions }]" center />
-    <TresMeshNormalMaterial :matcap="matcapTexture" />
-  </TresMesh>
+  <TresCanvas shadows alpha>
+    <TresMesh>
+      <TresTextGeometry :args="['TresJS', { font, ...fontOptions }]" center />
+      <TresMeshNormalMaterial :matcap="matcapTexture" />
+    </TresMesh>
+  </TresCanvas>
 </template>
 ```
 
@@ -147,9 +147,7 @@ It just works. 💯 (if not text is provided, the text will be TresJS)
 ```vue
 <template>
   <TresCanvas shadows alpha>
-    <TresScene>
-      <Text3D :font="fontPath" />
-    </TresScene>
+    <Text3D :font="fontPath" />
   </TresCanvas>
 </template>
 ```
@@ -175,6 +173,6 @@ bevelSegments: 4,
 
 By default text in ThreeJS starts at the mesh initial position, so it's [0,0,0] the text will start there but we can center it by just passing the flag "center"
 
-```js
-<Text3D :font="fontPath" :text="my 3d text" center  />
+```vue
+<Text3D :font="fontPath" :text="my 3d text" center />
 ```