docs: enable multi language

docs/.vitepress/config/en.ts

@@ -0,0 +1,146 @@
+import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'
+
+export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
+  themeConfig: {
+    editLink: {
+      pattern: 'https://github.com/tresjs/tres/edit/main/packages/docs/:path',
+      text: 'Suggest changes to this page',
+    },
+    sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          // This shows `/guide/index.md` page.
+          { text: 'Introduction', link: '/guide/' },
+          { text: 'Getting Started', link: '/guide/getting-started' },
+          { text: 'Your first Scene', link: '/guide/your-first-scene' },
+          { text: 'Nuxt', link: '/guide/nuxt' },
+          { text: 'Troubleshooting', link: '/guide/troubleshooting' },
+          { text: 'Migrate from v1', link: '/guide/migration-guide' },
+        ],
+      },
+      {
+        text: 'API',
+        items: [
+          { text: 'TresCanvas', link: '/api/tres-canvas' },
+          {
+            text: 'Instances, arguments and props',
+            link: '/api/instances-arguments-and-props',
+          },
+          {
+            text: 'Composables',
+            link: '/api/composables',
+          },
+          {
+            text: 'Events',
+            link: '/api/events',
+          },
+        ],
+      },
+
+      {
+        text: 'Advanced',
+
+        items: [
+          { text: 'Extending', link: '/advanced/extending' },
+          { text: 'primitive', link: '/advanced/primitive' },
+          {
+            text: 'Caveats',
+            link: '/advanced/caveats',
+          },
+        ],
+      },
+      {
+        text: 'Debug',
+        items: [
+          { text: 'Devtools', link: '/debug/devtools' },
+        ],
+      },
+      {
+        text: 'Examples',
+        collapsed: true,
+        items: [
+          { text: 'Orbit Controls', link: '/examples/orbit-controls' },
+          { text: 'Basic Animations', link: '/examples/basic-animations' },
+          { text: 'Groups', link: '/examples/groups' },
+          { text: 'Load Textures', link: '/examples/load-textures' },
+          { text: 'Load Models', link: '/examples/load-models' },
+          { text: 'Load Text', link: '/examples/text-3d' },
+          { text: 'Lights & Shadows', link: '/examples/lights-shadows' },
+          { text: 'Shaders', link: '/examples/shaders' },
+        ],
+      },
+      {
+        text: 'Directives',
+        collapsed: true,
+        items: [
+          { text: 'v-log', link: '/directives/v-log' },
+          { text: 'v-light-helper', link: '/directives/v-light-helper' },
+          { text: 'v-always-look-at', link: '/directives/v-always-look-at' },
+          { text: 'v-distance-to', link: '/directives/v-distance-to' },
+        ],
+      },
+      {
+        text: 'Ecosystem',
+        items: [
+          {
+            text: 'Cientos 💛',
+            link: 'https://cientos.tresjs.org/',
+          },
+          {
+            text: 'Nuxt module',
+            link: 'https://github.com/Tresjs/nuxt',
+          },
+          {
+            text: 'TresLeches 🍰',
+            link: 'https://tresleches.tresjs.org/',
+          },
+          {
+            text: 'Post-processing (Soon)',
+          },
+        ],
+      },
+    ],
+    nav: [
+      { text: 'Guide', link: '/guide/' },
+      { text: 'API', link: '/api/tres-canvas' },
+      /*       { text: 'API', link: '/api/' },
+      { text: 'Config', link: '/config/' }, */
+      { text: 'Resources',
+        items: [
+          { text: 'Team', link: '/team' },
+          { text: 'Releases', link: 'https://github.com/Tresjs/tres/releases' },
+          {
+            text: 'Playground',
+            link: 'https://playground.tresjs.org/',
+          },
+          {
+            text: 'Github',
+            link: 'https://github.com/Tresjs/tres/',
+          },
+          {
+            text: 'Issues',
+            link: 'https://github.com/Tresjs/tres/issues',
+          },
+          {
+            text: 'Ecosystem',
+            items: [
+              {
+                text: 'Cientos 💛',
+                link: 'https://cientos.tresjs.org/',
+              },
+              {
+                text: 'Nuxt module',
+                link: 'https://github.com/Tresjs/nuxt',
+              },
+              {
+                text: 'TresLeches 🍰',
+                link: 'https://tresleches.tresjs.org/',
+              },
+            ],
+          },
+        ],
+      },  
+    ],
+  },
+}

docs/.vitepress/config/index.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitepress'
+import { enConfig } from './en'
+import { sharedConfig } from './shared'
+
+/* import { zhConfig } from './zh' */
+
+export default defineConfig({
+  ...sharedConfig,
+
+  locales: {
+    root: { label: 'English', lang: 'en-US', link: '/', ...enConfig },
+    es: { label: 'Español', lang: 'es-ES', link: '/es/', ...enConfig },
+    /* zh: { label: '简体中文', lang: 'zh-CN', link: '/zh/', ...zhConfig }, */
+  },
+})

docs/.vitepress/config/shared.ts

@@ -0,0 +1,63 @@
+import { defineConfig } from 'vitepress'
+import { resolve } from 'pathe'
+
+export const sharedConfig = defineConfig({
+  title: 'TresJS',
+  description: 'Declarative ThreeJS using Vue Components',
+  head: [
+    ['link', { rel: 'icon', type: 'image/svg', href: '/favicon.svg' }],
+    ['meta', { name: 'theme-color', content: '#82DBC5' }],
+    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+    ['meta', { name: 'twitter:site', content: '@tresjs_dev' }],
+    ['meta', { name: 'twitter:creator', content: '@tresjs_dev' }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:site_name', content: 'TresJS' }],
+    [
+      'meta',
+      {
+        property: 'og:image',
+        content: 'https://repository-images.githubusercontent.com/571314349/10996566-7f70-473b-a8e5-4e56fc0ca850',
+      },
+    ],
+    [
+      'meta',
+      {
+        property: 'twitter:image',
+        content: 'https://repository-images.githubusercontent.com/571314349/10996566-7f70-473b-a8e5-4e56fc0ca850',
+      },
+    ],
+    ['script', { defer: 'true', 'data-domain': 'tresjs.org', src: 'https://plausible.io/js/script.js' }],
+  ],
+  themeConfig: {
+    logo: '/logo.svg',
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/tresjs/tres' },
+      { icon: 'x', link: 'https://twitter.com/tresjs_dev' },
+      { icon: 'discord', link: 'https://discord.gg/UCr96AQmWn' },
+    ],
+  },
+  vite: {
+    optimizeDeps: {
+      exclude: ['vitepress'],
+      include: ['three'],
+    },
+    server: {
+      hmr: {
+        overlay: false,
+      },
+    },
+    resolve: {
+      alias: {
+        '@tresjs/core': resolve(__dirname, '../../../dist/tres.js'),
+      },
+      dedupe: ['@tresjs/cientos', 'three'],
+    },
+  },
+  vue: {
+    template: {
+      compilerOptions: {
+        isCustomElement: tag => tag.startsWith('Tres') && tag !== 'TresCanvas',
+      },
+    },
+  },
+})

docs/es/advanced/caveats.md

@@ -0,0 +1,120 @@
+# Avisos 😱
+
+Nuestro objetivo es proporcionar una forma sencilla de utilizar ThreeJS en VueJS con la mejor experiencia de desarrollo posible. Sin embargo, hay algunas advertencias de las que debes ser consciente.
+
+## ~~HMR y ThreeJS~~
+
+:::info
+
+Esto se ha solucionado en **TresJS** v1.7.0 🎉. Ahora puedes utilizar HMR sin tener que recargar la página 🥹.
+
+:::
+
+La sustitución de módulos en caliente (HMR) es una característica que te permite actualizar tu código sin recargar la página. Esta es una gran característica que hace que el desarrollo sea mucho más rápido. **TresJS** utiliza [Vite](https://vitejs.dev/). Sin embargo, es realmente complicado hacer que funcione correctamente con ThreeJS.
+
+¿Por qué? Porque Tres construye la escena de forma declarativa. Esto significa que crea la instancia y la añade a la escena cuando se monta el componente. La complejidad radica en saber cuándo quitar la instancia de la escena y cuándo añadirla de nuevo.
+
+Aunque se ha implementado un flujo de eliminación mínimo, no es perfecto. Esto significa que a veces tendrás que recargar la página para ver los cambios correctamente, especialmente cuando estás haciendo referencia a instancias utilizando [Template Refs](https://v3.vuejs.org/guide/component-template-refs.html)
+
+```vue
+<script setup lang="ts">
+const boxRef: Ref<TresInstance | null> = ref(null)
+
+onLoop(({ _delta, elapsed }) => {
+  if (boxRef.value) {
+    boxRef.value.rotation.y += 0.01
+    boxRef.value.rotation.z = elapsed * 0.2
+  }
+})
+</script>
+
+<template>
+  <TresMesh
+    ref="boxRef"
+    :scale="1"
+    cast-shadow
+  >
+    <TresBoxGeometry :args="[1, 1, 1]" />
+    <TresMeshStandardMaterial color="teal" />
+  </TresMesh>
+</template>
+```
+
+Si realizas un cambio en el `color` del componente `TresMeshStandardMaterial`, verás que el cambio se aplica pero la rotación ya no funciona. Esto se debe a que la instancia se elimina y se crea de nuevo.
+
+:::tip
+Entonces, como **regla general**, debes recargar la página cuando no veas los cambios que has realizado.
+:::
+
+Dicho esto, estamos trabajando en una mejor solución para esto 😁. Si tienes alguna idea de cómo resolverlo, por favor avísanos.
+
+Puedes seguir la discusión en [HMR Disposal Discussion](https://github.com/Tresjs/tres/issues/23)
+
+## Reactividad
+
+Todos amamos la reactividad 💚. Es una de las características más poderosas de VueJS. Sin embargo, debemos tener cuidado al usar ThreeJS.
+
+La reactividad de Vue se basa en [Proxy](https://developer.mozilla.org/es/docs/Web/JavaScript/Reference/Global_Objects/Proxy). Esto permite que Vue 3 rastree automáticamente los cambios en los objetos de datos y actualice los elementos DOM correspondientes cada vez que los datos cambien.
+
+Dado que estamos renderizando una escena y actualizándola en cada fotograma (60FPS), eso significa que estamos actualizando la escena 60 veces por segundo. Si el objeto a actualizar es reactivo, Vue intentará actualizar ese objeto tantas veces. Esto no es una buena idea 😅 y será perjudicial para el rendimiento.
+
+Aquí tienes una prueba de rendimiento de la diferencia entre usar un objeto Proxy y un objeto plano.
+
+<figure>
+  <img src="/proxy-benchmark.png" alt="Proxy vs Plain" style="width:100%">
+  <figcaption>Fig.1 - Ejecuciones por segundo Objeto Plano vs Proxy. </figcaption>
+</figure>
+
+Fuente: [Proxy vs Plain Object](https://www.measurethat.net/Benchmarks/Show/12503/0/object-vs-proxy-vs-proxy-setter)
+
+Si te ves obligado a usar reactividad, utiliza [shallowRef](https://vuejs.org/api/reactivity-advanced.html#shallowref)
+
+A diferencia de `ref()`, el valor interno de un shallow ref se almacena y se expone tal cual, y no se hace reactividad profunda. Solo el acceso a `.value` es reactivo. Fuente [VueJS Docs](https://vuejs.org/api/reactivity-advanced.html#shallowref)
+
+### Ejemplo
+
+❌ Incorrecto
+
+```vue
+<script setup lang="ts">
+const position = reactive({ x: 0, y: 0, z: 0 })
+
+onLoop(({ _delta, elapsed }) => {
+  position.x = Math.sin(elapsed * 0.1) * 3
+})
+</script>
+
+<template>
+  <TresMesh
+    :position="position"
+    cast-shadow
+  >
+    <TresBoxGeometry :args="[1, 1, 1]" />
+    <TresMeshStandardMaterial color="teal" />
+  </TresMesh>
+</template>
+```
+
+✅ Correcto
+
+```vue
+<script setup lang="ts">
+const position = { x: 0, y: 0, z: 0 }
+const boxRef: ShallowRef<TresInstance | null> = shallowRef(null)
+
+onLoop(({ _delta, elapsed }) => {
+  boxRef.value.position.x = Math.sin(elapsed * 0.1) * 3
+})
+</script>
+
+<template>
+  <TresMesh
+    ref="boxRef"
+    :position="position"
+    cast-shadow
+  >
+    <TresBoxGeometry :args="[1, 1, 1]" />
+    <TresMeshStandardMaterial color="teal" />
+  </TresMesh>
+</template>
+```

docs/es/advanced/extending.md

@@ -0,0 +1,44 @@
+# Extender 🔌
+
+Tres ofrece la funcionalidad básica, pero es fácil agregar elementos de terceros y extenderlos en su catálogo interno.
+
+La mayoría de las experiencias en 3D utilizan `OrbitControls`, que no forma parte de la biblioteca principal. Puedes agregarlo a tu proyecto importándolo desde el módulo `three/addons/controls/OrbitControls`.
+
+```js
+import { OrbitControls } from 'three/addons/controls/OrbitControls'
+```
+
+## Extender un elemento dinámicamente
+
+También puedes agregarlo dinámicamente en tus componentes:
+
+```vue {2,3,4,7,13,15}
+<script setup lang="ts">
+import { extend } from '@tresjs/core'
+import { OrbitControls } from 'three/addons/controls/OrbitControls'
+import { TextGeometry } from 'three/addons/geometries/TextGeometry'
+
+// Añadimos OrbitControls al catalogo interno
+extend({ TextGeometry, OrbitControls })
+</script>
+
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <TresPerspectiveCamera :position="[5, 5, 5]" />
+    <TresOrbitControls
+      v-if="state.renderer"
+      :args="[state.camera, state.renderer?.domElement]"
+    />
+    <TresMesh>
+      <TresTextGeometry
+        :args="['TresJS', { font, ...fontOptions }]"
+        center
+      />
+      <TresMeshMatcapMaterial :matcap="matcapTexture" />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```

docs/es/advanced/primitive.md

@@ -0,0 +1,47 @@
+# Primitives
+
+El componente `<primitive />` es un componente versátil de bajo nivel en TresJS que te permite utilizar directamente cualquier objeto de three.js dentro de tu aplicación Vue sin una abstracción. Actúa como un puente entre el sistema de reactividad de Vue y el grafo de escena de three.js.
+
+## Usage
+
+```html
+<script setup lang="ts">
+  // Importa las clases necesarias de three.js
+  import { Mesh, BoxGeometry, MeshBasicMaterial } from 'three';
+
+  // Crea una geometría de caja y un material básico
+  const geometry = new BoxGeometry(1, 1, 1);
+  const material = new MeshBasicMaterial({ color: 0x00ff00 });
+
+  // Crea un mesh con la geometría y el material
+  const meshWithMaterial = new Mesh(geometry, material);
+</script>
+
+<template>
+  <TresCanvas>
+    <primitive :object="meshWithMaterial" />
+  </TresCanvas>  
+</template>
+```
+
+## Props
+
+`object`: Esta propiedad espera un objeto `Object3D` de three.js o cualquiera de sus clases derivadas. Es el objeto principal que el componente `<primitive />` renderizará. En el ejemplo actualizado, se pasa un objeto `Mesh` con su correspondiente `Material` a esta propiedad.
+
+## Uso con Modelos
+
+El componente `<primitive />` es especialmente útil para renderizar objetos complejos como modelos cargados desde fuentes externas. El siguiente ejemplo muestra cómo cargar un modelo desde un archivo GLTF y renderizarlo utilizando el componente `<primitive />`.
+
+```html
+<script lang="ts" setup>
+import { useGLTF } from '@tresjs/cientos'
+
+const { nodes } = await useGLTF('/models/AkuAku.gltf')
+</script>
+
+<TresCanvas>
+  <Suspense>
+    <primitive :object="nodes.AkuAku" />
+  </Suspense>
+</TresCanvas>
+```

docs/es/api/composables.md

@@ -0,0 +1,236 @@
+# Composables
+
+La API de Composición de Vue 3 [Composition API](https://vuejs.org/guide/extras/composition-api-faq.html#what-is-composition-api) te permite crear lógica reutilizable que se puede compartir entre componentes. También te permite crear hooks personalizados que se pueden utilizar en tus componentes.
+
+**TresJS** aprovecha al máximo esta API para crear un conjunto de funciones componibles que se pueden utilizar para crear animaciones, interactuar con la escena y más. También te permite crear escenas más complejas que podrían no ser posibles utilizando solo los Componentes de Vue (Texturas, Cargadores, etc.).
+
+El núcleo de **TresJS** utiliza estos componibles internamente, por lo que estarías utilizando la misma API que utiliza el núcleo. Por ejemplo, los componentes que necesitan actualizarse en el bucle de renderizado interno utilizan el componible `useRenderLoop` para registrar un callback que se llamará cada vez que el renderizador actualice la escena.
+
+## useRenderLoop
+
+El componible `useRenderLoop` es el núcleo de las animaciones en **TresJS**. Te permite registrar un callback que se llamará en la frecuencia de actualización nativa. Este es el componible más importante en **TresJS**.
+
+```ts
+const { onLoop, resume } = useRenderLoop()
+
+onLoop(({ delta, elapsed, clock, dt }) => {
+  // I will run at every frame ~60FPS (depending of your monitor)
+})
+```
+
+::: warning
+Be mindfull of the performance implications of using this composable. It will run at every frame, so if you have a lot of logic in your callback, it might impact the performance of your app. Specially if you are updating reactive states or references.
+:::
+
+The `onLoop` callback receives an object with the following properties based on the [THREE clock](https://threejs.org/docs/?q=clock#api/en/core/Clock):
+
+- `delta`: The delta time between the current and the last frame. This is the time in seconds since the last frame.
+- `elapsed`: The elapsed time since the start of the render loop.
+
+This composable is based on `useRafFn` from [vueuse](https://vueuse.org/core/useRafFn/). Thanks to [@wheatjs](https://github.com/orgs/Tresjs/people/wheatjs) for the amazing contribution.
+
+### Before and after render
+
+You can also register a callback that will be called before and after the renderer updates the scene. This is useful if you add a profiler to measure the FPS for example.
+
+```ts
+const { onBeforeLoop, onAfterLoop } = useRenderLoop()
+
+onBeforeLoop(({ delta, elapsed }) => {
+  // I will run before the renderer updates the scene
+  fps.begin()
+})
+
+onAfterLoop(({ delta, elapsed }) => {
+  // I will run after the renderer updates the scene
+  fps.end()
+})
+```
+
+### Pause and resume
+
+You can pause and resume the render loop using the exposed `pause` and `resume` methods.
+
+```ts
+const { pause, resume } = useRenderLoop()
+
+// Pause the render loop
+pause()
+
+// Resume the render loop
+resume()
+```
+
+Also you can get the active state of the render loop using the `isActive` property.
+
+```ts
+const { resume, isActive } = useRenderLoop()
+
+console.log(isActive) // false
+
+resume()
+
+console.log(isActive) // true
+```
+
+## useLoader
+
+The `useLoader` composable allows you to load assets using the [THREE.js loaders](https://threejs.org/docs/#manual/en/introduction/Loading-3D-models). It returns a promise with loaded asset.
+
+```ts
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader'
+
+const { scene } = await useLoader(THREE.GLTFLoader, 'path/to/asset.gltf')
+```
+
+Since the `useLoader` composable returns a promise, you can use it with `async/await` or `then/catch`. If you are using it on a component make sure you wrap it with a `Suspense` component. See [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) for more information.
+
+```vue
+<template>
+  <Suspense>
+    <TheComponentUsingLoader />
+  </Suspense>
+</template>
+```
+
+## useTexture
+
+The `useTexture` composable allows you to load textures using the [THREE.js texture loader](https://threejs.org/docs/#api/en/loaders/TextureLoader). It returns a promise with the loaded texture(s).
+
+```ts
+const texture = await useTexture(['path/to/texture.png'])
+```
+
+**useTexture** also accepts an object with the following properties:
+
+- `map`: a basic texture that is applied to the surface of an object
+- `displacementMap`: a texture that is used to add bumps or indentations to the object's surface
+- `normalMap`: a texture that is used to add surface detail to and variations in shading to the object
+- `roughnessMap`: a texture that is used to add roughness or a matte finish to the object's surface
+- `metalnessMap`: a texture that is used to add a metallic effect to the object's surface
+- `aoMap`: a texture that is used to add ambient occlusion (shading in areas where light is blocked by other objects) to the object.
+- `alphaMap`: a texture that is used to add alpha (the black part render as transparent) to the object. It's necessary to set :trasparent="true" on the material to use this map
+- `matcap`: this textures encodes the material color and shading.
+
+In that case it will return an object with the loaded textures.
+
+```ts
+const { map, displacementMap, normalMap, roughnessMap, metalnessMap, aoMap, alphaMap, matcap } = await useTexture({
+  map: 'path/to/albedo.png',
+  displacementMap: 'path/to/height.png',
+  normalMap: 'path/to/normal.png',
+  roughnessMap: 'path/to/roughness.png',
+  metalnessMap: 'path/to/metalness.png',
+  aoMap: 'path/to/ambien-occlusion.png',
+  alphaMap: 'path/to/alpha.png',
+  matcap: 'path/to/matcap.png',
+})
+```
+
+Then you can bind the textures to the material.
+
+```vue
+<template>
+  <TresCanvas>
+    <TresMesh>
+      <TresSphereGeometry />
+      <TresMeshStandardMaterial
+        :map="map"
+        :displacement-map="displacementMap"
+        :normal-map="normalMap"
+        :roughness-map="roughnessMap"
+        :metalness-map="metalnessMap"
+        :ao-map="aoMap"
+        :alpha-map="alphaMap"
+      />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+Similar to above composable, the `useTexture` composable returns a promise, you can use it with `async/await` or `then/catch`. If you are using it on a component make sure you wrap it with a `Suspense` component.
+
+## useSeek
+
+The `useSeek` composable provides utilities to easily traverse and navigate through complex ThreeJS scenes and object children graphs. It exports 4 functions which allow you to find child objects based on specific properties.
+
+```ts
+const { seek, seekByName, seekAll, seekAllByName } = useSeek()
+```
+
+The seek function accepts three parameters:
+
+- `parent`: A ThreeJS scene or Object3D.
+- `property`: The property to be used in the search condition.
+- `value`: The value of the property to match.
+
+The `seek` and `seekByName` function traverses the object and returns the child object with the specified property and value. If no child with the given property and value is found, it returns null and logs a warning.
+
+```ts
+const carRef = ref(null)
+
+watch(carRef, ({ model }) => {
+  if (model) {
+    const car = model.children[0]
+
+    const body = seek(car, 'name', 'Octane_Octane_Body_0')
+    body.color.set(new Color('blue'))
+  }
+})
+```
+
+Similarly, the `seekAll` and `seekAllByName` functions return an array of child objects whose property includes the given value. If no matches are found, then they return an empty array and a warning is logged.
+
+```ts
+const character = ref(null)
+
+watch(character, ({ model }) => {
+  if (model) {
+    const bones = seekAll(character, type, 'Bone')
+  }
+})
+```
+
+## useTresContext
+This composable aims to provide access to the state model which contains multiple useful properties.
+
+```ts
+const { camera, renderer, camera, cameras } = useTresContext()
+
+```
+
+::: warning
+`useTresContext` can be only be used inside of a `TresCanvas` since `TresCanvas` acts as the provider for the context data. Use [the context exposed by TresCanvas](tres-canvas#exposed-public-properties) if you find yourself needing it in parent components of TresCanvas. 
+:::
+
+```vue
+<TresCanvas>
+  <MyModel />
+</TresCanvas>
+```
+
+```vue
+// MyModel.vue
+
+<script lang="ts" setup>
+import { useTresContext } from '@tresjs/core'
+
+const context = useTresContext()
+</script>
+```
+
+### Properties of context
+| Property | Description |
+| --- | --- |
+| **camera** | the currently active camera |
+| **cameras** | the cameras that exist in the scene |
+| **controls** | the controls of your scene |
+| **deregisterCamera** | a method to deregister a camera. This is only required if you manually create a camera. Cameras in the template are deregistered automatically. |
+| **extend** | Extends the component catalogue. See [extending](/advanced/extending) |
+| **raycaster** | the global raycaster used for pointer events |
+| **registerCamera** | a method to register a camera. This is only required if you manually create a camera. Cameras in the template are registered automatically. |
+| **renderer** | the [WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer) of your scene |
+| **scene** | the [scene](https://threejs.org/docs/?q=sce#api/en/scenes/Scene). |
+| **setCameraActive** | a method to set a camera active |
+| **sizes** | contains width, height and aspect ratio of your canvas |
+

docs/es/api/events.md

@@ -0,0 +1,27 @@
+# Events
+
+**TresJS** components emit pointer events when they are interacted with. This is the case for the components that represent three.js classes that derive from [THREE.Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) (like meshes, groups,...).
+
+<StackBlitzEmbed project-id="tresjs-events" />
+
+## Pointer Events
+
+```html
+<TresMesh
+  @click="(intersection, pointerEvent) => console.log('click', intersection, pointerEvent)"
+  @pointer-move="(intersection, pointerEvent) => console.log('pointer-move', intersection, pointerEvent)"
+  @pointer-enter="(intersection, pointerEvent) => console.log('pointer-enter', intersection, pointerEvent)"
+  @pointer-leave="(intersection, pointerEvent) => console.log('pointer-leave', pointerEvent)"
+/>
+```
+
+| Event         | fires when ...                                                                        | Event Handler Parameter Type(s)                                                                                                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| click         | ... the events pointerdown and pointerup fired on the same object one after the other | [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16), [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent) |
+| pointer-move  | ... the pointer is moving above the object                                            | [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16), [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent) |
+| pointer-enter | ... the pointer is entering the object                                                | [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16), [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent) |
+| pointer-leave | ... the pointer is leaves the object                                                  | [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent)                                                                                                                         |
+
+The returned [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16) includes the [Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) that triggered the event. You can access it via `intersection.object`.
+
+By default, objects positioned in front of others with event handlers do not prevent those events from being triggered. This behavior can be achieved by using the prop `blocks-pointer-events`.

docs/es/api/instances-arguments-and-props.md

@@ -0,0 +1,144 @@
+# Instances
+
+The core idea of **Tres** is an _autogenerated catalogue_ of all the ThreeJS elements. This catalogue is generated from the ThreeJS source code, so it's always up to date.
+
+When using ThreeJS, you need to import the elements you want to use. For example, if you want to use a `PerspectiveCamera`, you need to import it from the `three` package:
+
+```js
+import { PerspectiveCamera } from 'three'
+
+const camera = new PerspectiveCamera(45, width / height, 1, 1000)
+```
+
+With **Tres** you don't need to import anything, that's because **Tres** automatically generate a **Vue Component based of the Three Object you want to use in CamelCase with a Tres prefix**. For example, if you want to use a `PerspectiveCamera` you would use `<TresPerspectiveCamera />` component.
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera />
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+This means that you can use the same [documentation](https://threejs.org/docs/) as you would when using plain ThreeJS, but with the power of Vue.
+
+## Declaring objects
+
+If we follow this argument, you should be able to lay out an instance like this: ❌
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera visible :position="new THREE.Vector3(1, 2, 3)" />
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+But with **Tres** this is not needed, you can define properties declaratively like this: ✅
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera visible :position="[1, 2, 3]" />
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+## Arguments
+
+Some ThreeJS objects have arguments, for example, the `PerspectiveCamera` constructor has the following arguments:
+
+- `fov` - Camera frustum vertical field of view.
+- `aspect` - Camera frustum aspect ratio.
+- `near` - Camera frustum near plane.
+- `far` - Camera frustum far plane.
+
+To pass these arguments to the `TresPerspectiveCamera` component, you can use the `args` prop:
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+This is the same as doing this:
+
+```ts
+const camera = new PerspectiveCamera(45, 1, 0.1, 1000)
+```
+
+## Props
+
+You can also pass props to the component, for example, the `TresAmbientLight` has a `intensity` property, so you can pass it to the component like this:
+
+```html
+<TresAmbientLight :intensity="0.5" />
+```
+
+### Set
+
+All properties whose underlying object has a `.set()` method have a shortcut to receive the value as an array. For example, the `TresPerspectiveCamera` has a `position` property, which is a `Vector3` object, so you can pass it to the component like this:
+
+```html
+<TresPerspectiveCamera :position="[1, 2, 3]" />
+```
+
+To specify transformation properties such as position, rotation, and scale, a shorthand is available that allows you to directly indicate the axis you wish to set within the props. A similar shorthand is also available for color property.
+
+<!-- I changed color syntax from vue to html, because vue seems broken and does not color nested components -->
+```html
+<TresMesh :position-x="1" :scale-y="2" :rotation-x="Math.PI * 2">
+  <TresMeshBasicMaterial :color-r="0.7" :color-b="0.3" />
+</TresMesh>
+```
+
+::: warning
+When you set the rotation property in [three.js](https://threejs.org/docs/index.html#api/en/math/Euler), it will use the 'XYZ' order by default.
+It is important to note that when setting the rotation property with the shorthand, the order in which you set the angles matters. For more information on this topic, please refer to  [Euler angles](https://en.wikipedia.org/wiki/Euler_angles)
+:::
+
+```vue
+<TresMesh :rotation-x="1" :rotation-y="2" :rotation-z="Math.PI * 2" />
+
+<TresMesh :rotation-z="Math.PI * 2" :rotation-x="1" :rotation-y="2" />
+
+<!-- Note that the order of the rotation properties matters, and swapping the order can result in different outcomes. -->
+```
+
+### Scalar
+
+Another shortcut you can use is pass a scalar value to a property that expects a `Vector3` object, using the same value for the rest of the Vector:
+
+```html
+<TresPerspectiveCamera :position="5" /> ✅
+```
+
+```html
+<TresPerspectiveCamera :position="[5, 5, 5]" /> ✅
+```
+
+### Colors
+
+You can pass colors to the components using the `color` prop, which accepts a string with the color name or a hex value:
+
+```html
+<TresAmbientLight color="teal" /> ✅
+```
+
+```html
+<TresAmbientLight color="#008080" /> ✅
+```
+
+### Methods
+
+Some underlying properties are actually methods, the `TresPerspectiveCamera` has a `lookAt` method inherit from [Object3d](https://threejs.org/docs/#api/en/core/Object3D.lookAt), so you can pass it the coords to the component like this:
+
+```html
+<TresPerspectiveCamera :look-at="[1, 2, 3]" />
+```

docs/es/api/tres-canvas.md

@@ -0,0 +1,104 @@
+# TresCanvas
+
+The `TresCanvas` component is the main component of Tres. It's the one that creates the ThreeJS `WebGLRenderer`.
+
+```vue{2,5}
+<template>
+  <TresCanvas shadows :output-encoding="SRGBColorSpace">
+    <TresPerspectiveCamera />
+      <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+## Canvas size
+
+The `TresCanvas` component will use the parent element size as the canvas size. If you want to use the window size as the canvas size, you can set the `window-size` prop to `true`.
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+Or you can use CSS to set your canvas size.
+
+```css
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  width: 100%;
+}
+#canvas {
+  height: 100%;
+  width: 100%;
+}
+```
+
+## Presets
+
+Tres comes with a few presets for the `TresCanvas` component. You can use them by setting the `preset` prop.
+
+### Realistic
+
+The `realistic` preset makes easy to setup the renderer for more realistic 3D scenes.
+
+```vue
+<template>
+  <TresCanvas preset="realistic">
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+It's equivalent to:
+
+```ts
+renderer.shadows = true
+renderer.physicallyCorrectLights = true
+renderer.outputColorSpace = SRGBColorSpace
+renderer.toneMapping = ACESFilmicToneMapping
+renderer.toneMappingExposure = 3
+renderer.shadowMap.enabled = true
+renderer.shadowMap.type = PCFSoftShadowMap
+```
+
+## Props
+
+| Prop | Description | Default |
+| ---- | ---- | --- |
+| **alpha** | Controls the default clear alpha value. When set to true, the value is 0. Otherwise it's 1. | false |
+| **antialias** | Whether to perform antialiasing. | `true` |
+| **camera** | A manual camera to be used by the renderer. | |
+| **clearColor** | The color the renderer will use to clear the canvas. | `#000000` |
+| **context** | This can be used to attach the renderer to an existing [RenderingContext](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext) | |
+| **depth** | Whether the drawing buffer has a [depth buffer](https://en.wikipedia.org/wiki/Z-buffering) of at least 16 bits. | `true` |
+| **disableRender** | Disable render on requestAnimationFrame, useful for PostProcessing | `false` |
+| **failIfMajorPerformanceCaveat** | Whether the renderer creation will fail upon low performance is detected. See [WebGL spec](https://registry.khronos.org/webgl/specs/latest/1.0/#5.2) for details. | `false` |
+| **logarithmicDepthBuffer** | Whether to use a logarithmic depth buffer. It may be necessary to use this if dealing with huge differences in scale in a single scene. Note that this setting uses gl_FragDepth if available which disables the [Early Fragment Test](https://www.khronos.org/opengl/wiki/Early_Fragment_Test) optimization and can cause a decrease in performance. | `false` |
+| **outputColorSpace** | Defines the output encoding | `LinearEncoding` |
+| **powerPreference** | Provides a hint to the user agent indicating what configuration of GPU is suitable for this WebGL context. Can be "high-performance", "low-power" or "default". | `default` |
+| **precision** | Shader precision. Can be "highp", "mediump" or "lowp". | "highp" if supported by the device |
+| **premultipliedAlpha** | Whether the renderer will assume that colors have [premultiplied alpha](https://en.wikipedia.org/wiki/Glossary_of_computer_graphics#premultiplied_alpha). | `true` |
+| **preserveDrawingBuffer** | Whether to preserve the buffers until manually cleared or overwritten.. | `false` |
+| **shadows** | Enable shadows in the renderer | `false` |
+| **shadowMapType** | Set the shadow map type | `PCFSoftShadowMap` |
+| **stencil** | Whether the drawing buffer has a [stencil buffer](https://en.wikipedia.org/wiki/Stencil_buffer) of at least 8 bits. | `true` |
+| **toneMapping** | Defines the tone mapping exposure used by the renderer. | `NoToneMapping` |
+| **toneMappingExposure** | Exposure level of tone mapping. | `1` |
+| **useLegacyLights** | Whether to use the legacy lighting mode or not | `true` |
+| **windowSize** | Whether to use the window size as the canvas size or the parent element. | `false` |
+
+### Defaults
+
+Tres tries to be as little opinionated as possible. That's why it doesn't set almost any default value for the `TresCanvas` component. It uses the defaults from [three.js](https://threejs.org/). The only exception is the `antialias` prop. It's set to `true` by default.
+
+## Exposed public properties
+
+| Property | Description |
+| ---- | ---- |
+| context | see [useTresContext](composables#usetrescontext) |

docs/es/debug/devtools.md

@@ -0,0 +1,28 @@
+# Devtools
+
+
+
+One of the most difficult things a developer faces when creating 3D experiences on the browser is debugging. The browser `canvas` is a black box, and it's hard to know what's going on inside. The imperative nature of [ThreeJS](https://threejs.org/) makes it incredibly difficult to debug, having to depend on `console.log` to see what's going on, or third party to fine-tune and inspect the scene.
+
+Don't make me get started with checking the performance of your scene. 😱
+
+![developer debugging 3D](/debug-3D.png)
+
+One of our goals with TresJS is to offer **the best DX (Developer Experience)** when dealing with 3D scenes on the browser. Thanks to the declarative nature of the ecosystem plus the variety of solutions the Vue ecosystem offers such as the Vue Devtools, Nuxt and Vite, we can offer a better tooling for devs to debug their scenes.
+
+## Introducing the Devtools
+
+From <Badge text="^3.7.0" /> we are introducing the TresJS Devtools, a customized inspector tab for the [Official Vue Chrome Devtools](https://devtools.vuejs.org/guide/installation.html) that allows you to inspect your TresJS scenes and components.
+
+![TresJS Devtools](/vue-chrome-devtools.png)
+
+### Features
+
+- **Scene Inspector**: Inspect the current scene and its components using a tree view similar to the Vue Devtools component inspector.
+- **Memory Allocation**: See how much memory is being by the components.
+- **Object Inspector**: Inspect the properties of the selected object in the scene, including its children.
+- **Editable Properties**: And yes, you can edit the properties of the selected object and see the changes in real-time.
+
+![](/devtools-scene-inspector.png)
+
+Enjoy the new Devtools and let us know what you think! 🎉

docs/es/examples/basic-animations.md

@@ -0,0 +1,89 @@
+# Basic Animations
+
+This guide will help you get started with basic animations in TresJS.
+
+We will build a simple scene with a cube. We will then animate the cube to rotate around the Y and Z axis.
+
+<SandboxDemo url="https://play.tresjs.org/#eNqVVF1P2zAU/StW9kAZbVI+hTqKOjo0bRofYrwRHkxy2xoc27KdtlD1v+8mTloHBipSH5rjc889vh9eBLcazHelwmkOQS84MYlmyhIDNleEUzHux4E1cXAaC5YpqS1ZEDOhnMvZDYzIkoy0zMgWRm998yiF6pCKKTVtkhu4AZGC/iOlWkUMLFIeTZRI3Qy90g/MDqWwWnLzls5AWGmKiFgkUhhLHuS8sNL3fLVEzvm2x1kQKar0/aahlqO541ZrQVLglrYJcKoMpGS5TfqnZBELQtiItFyycEp5DtsOJpUDB4ZaWmqZFOEz2ek7NczwPu0FHdXJvpJuuFeyl7FYFs5OItcRrD9+WMgUpxbwi5CTdZFJwoHqTiK51NiwL8d7P86Gh3FQlCSVM0MoVxNKZkzgV8ewF6eAGs1qRxVciV+DNgoSy6YwpBloWp8S0lPSsMI/prvbbZO9Njm8jwOPMJJTPDtAFx5ISz3EdxuwQPcIdsMmPCrR3W63u4ZfWbwAMyEaRshz5cVL90xCObgkJKHGdlwZVpFV7Jmc/wSZgdXP6EyPTXWX4od38VJ5yS6lzii/wCZoRrlvJ6oprjvlp2sPAieR17ugHbhx72RUhY9GCly9cpbi6gA3rldPVxz4u1IcxMHEWmV6UZSkAuNxyNhUhwJsJFQW+fTBfngYdqOUGRsVMLLjoP1G2G3VZ7RdBMof+fIV3MxiZ0CfFBWbeF9xBwchjkOlXINhxooYX3uiYSPdgjdAxcNj9LsDJvPLgM8XPgob19ejD3a7ZYFxs2AeZs3qVjycPg3pJ4RdwEfSSOykkLENRGtqcfmD8Cji7MGXrB8bnElr8LEcsfGriUxkphgHfaWKfW9OZvng/i4xq3NY+UsmkDz9B380c2f5GocF9BTLvW4lriBYd3z+9xLm+H91mMk051Vz3jm8ASN5Xnh0tLNcpGjb45Vuf5ULxsT41pzPLQhTX6ph1D4rKNG7er9Xs+aA+7JwJb9sx/CDKq1vth/urwq+/AdyGHHw" />
+
+## useRenderLoop
+
+The `useRenderLoop` composable is the core of TresJS animations. It allows you to register a callback that will be called every time the renderer updates the scene with the browser's refresh rate.
+
+To see a detailed explanation of how it works, please refer to the [useRenderLoop](/api/composables#userenderloop) documentation.
+
+```ts
+const { onLoop } = useRenderLoop()
+
+onLoop(({ delta, elapsed }) => {
+  // I will run at every frame ~ 60FPS (depending of your monitor)
+})
+```
+
+## Getting the reference to the cube
+
+To animate the cube, we need to get a reference to it. We can do it by passing a [Template Ref](https://vuejs.org/guide/essentials/template-refs.html) using `ref` prop to the `TresMesh` component. This will return the THREE instance.
+
+To improve the performance, we will use a [Shallow Ref](https://v3.vuejs.org/guide/reactivity-fundamentals.html#shallow-reactivity) to store the reference instead of a regular Ref. See why [here](../advanced/caveats.md#reactivity)
+
+```vue
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+
+const boxRef: ShallowRef<TresInstance | null> = shallowRef(null)
+</script>
+
+<template>
+  <TresCanvas>
+    <TresMesh
+      ref="boxRef"
+      :scale="1"
+    >
+      <TresBoxGeometry :args="[1, 1, 1]" />
+      <TresMeshNormalMaterial />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+## Animating the cube
+
+Now that we have a reference to the cube, we can animate it. We will use the `onLoop` callback to update the cube's rotation.
+
+```ts
+onLoop(({ delta, elapsed }) => {
+  if (boxRef.value) {
+    boxRef.value.rotation.y += delta
+    boxRef.value.rotation.z = elapsed * 0.2
+  }
+})
+```
+
+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] += delta
+  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/es/examples/groups.md

@@ -0,0 +1,32 @@
+# 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).
+
+## Usage
+
+```vue{13,22}
+<script setup lang="ts">
+const groupRef = ref()
+const { onLoop } = useRenderLoop()
+
+onLoop(() => {
+  if (groupRef.value) {
+    groupRef.value.rotation.y += 0.01
+  }
+})
+</script>
+<template>
+  <TresCanvas>
+    <TresGroup ref="groupRef" :position="[2,0,0]">
+      <TresMesh>
+        <TresBoxGeometry />
+        <TresMeshBasicMaterial color="red" />
+      </TresMesh>
+      <TresMesh>
+        <TresSphereGeometry />
+        <TresMeshBasicMaterial color="blue" />
+      </TresMesh>
+    </TresGroup>
+  </TresCanvas>
+</template>
+```

docs/es/examples/lights-shadows.md

@@ -0,0 +1,174 @@
+# Light-shadows
+
+This guide will help you get started with simple light and shadows in TresJS.
+
+We will build a simple scene with three meshes and a plane but only two will have shadows.
+<SandboxDemo url="https://play.tresjs.org/#eNqVVt1y2jwQfRUN30WSKdimhLbjL3Qo9GfaadpM4K7uhbAXUGpLGkn8pJm8e1eSDXZCMmRCGGv37NHZ1XrFXWuqQH+QMlivoBW3LnSqmDREg1lJklO+GCQto5PW+4SzQgplyB3RS5rnYnMNc3JP5koU5ASjT/6vQSzrmPI11W2y0nANPAP1XQhZBQwNIm50mArVjPypZsyMBTdK5HrHv4Mz4EboRsSIapZOljQTm0sq22Ry/WU0FrlQE0lTaJMfYio4oEsyvtgxmqUCOEl4wlPBtSGLnAzIXcIJSXOgyhHE5OS/d68/jsb9k7b1YOK4iY6JUStwFprLJY3JnObaGzwEN5veSogfarMIsTJyhRlWAuOHgi3I7BXHzQTQfb9XPRNbewyD2pmcnu3dd0RwW3XMetA8B4/y3tPTMzJ475Nn81PPGaxpvoIzZ6xbAiUMNUzw4Ja8GpAoiLoWgpruHWXCL0LfRNgyuDBQyJwawBUhF/u+IOvOjPEM22uRJy2ywWex6Wj21yMR2+yEsDJbiitQWkJq2BrGtABFSSyFZlYWEv7qt8nbwH/9Ru54LtZoPu/bZ+oCcdm1K45Hjc9R4FZzt+hGUYSrxoaXoJfNPTqv2wQ/kdugqol1RG1ySc0yuPrqvSVNlTye5BcQBRh1i2LUQtuYbpt0reCeZas2rm09FYIjKShGc5LaVsGosjXrUsMq4JF2BXMM8QeJESnVpuN7tZkWqrefR7pHYntAttVcfb1I+vln+3ec9LrWplisvz2Gx2oncglqX+ejZX0ejaLe6NiKpoD991QVO71DzdEpW4OErnkOab/CqXuoRRC8/3+i2BNDeUZV9jiz+Vv791Rmtdw+FDM7Y7+zxdKQmHEDHPO6LV+YxkvxkWENbGY09/Dnumr3rhym9HL8aEDDRVibG612yw/7TkFlcKMFx5vKDaakdOAFFfv5ZW31u8U6ktbSGKnjMEwzjvEZ5GytAg4m5LII6/BhL+gHUZgxbUJrRnTSchO5QexvoZdw+wikf1OnL83NXcwG6B+JTXAE/w47PA9wiJXMlTEomI2pc9tb7xheixsiY/8d6n0FuqiXAW97vEyOrm8NPuxGrsA47WEbFM3qljhsIAXZC4h9wHPUCOxkULAjSCuoTf48eBPmbFanrO467Emj8ZKds8WDjkxFIVkO6qe03d/sTHdHf3O23U8IF7OE9M8B+43eeslX2Cyg1lju/VHiZADj3Z8mP2CLzztnIbJVXh7OE85r0CJfWY0eNlrxDGXXcE7tV/eC4Q+Pqf60dW9umVRDqMFfO876q5pJu17zht+ucA7vjmP8TJX2mfWC3q7g9/8AWlN6bg==" />
+
+## Setting up the scene (optional)
+
+We import all the modules that we need, for comfort we can use the orbit-controls from cientos,
+[check here to know how](/examples/orbit-controls).
+
+Let's put four objects in our scene, one will be the plane that receive shadows, two of them will cast shadows and the last one will not cast any shadow at all.
+
+I'm going to use [MeshToonMaterial](https://threejs.org/docs/index.html?q=toon#api/en/materials/MeshToonMaterial). Simply because we can see the "soft shadow" easily.
+
+```vue
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import { OrbitControls } from '@tresjs/cientos'
+</script>
+
+<template>
+  <TresCanvas
+    clear-color="#111"
+    window-size
+  >
+    <OrbitControls />
+    <TresPerspectiveCamera :position="[5, 7.5, 7.5]" />
+
+    <TresMesh
+      :position="[-2, 2, 0]"
+      :rotation="[0, Math.PI, 0]"
+    >
+      <TresConeGeometry :args="[1, 1.5, 3]" />
+      <TresMeshToonMaterial color="#82DBC5" />
+    </TresMesh>
+    <TresMesh
+      :position="[0, 0, 0]"
+    >
+      <TresBoxGeometry :args="[1.5, 1.5, 1.5]" />
+      <TresMeshToonMaterial color="#4F4F4F" />
+    </TresMesh>
+    <TresMesh
+      :position="[2, -2, 0]"
+    >
+      <TresSphereGeometry />
+      <TresMeshToonMaterial color="#FBB03B" />
+    </TresMesh>
+    <TresMesh
+      :position="[0, -3, 0]"
+      :rotation="[-Math.PI / 2, 0, 0]"
+    >
+      <TresPlaneGeometry :args="[10, 10, 10, 10]" />
+      <TresMeshStandardMaterial color="#f7f7f7" />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+## Lights (explanation)
+
+As you know every instance in [ThreeJs](https://threejs.org/) is available in **TresJs** so are all the light types, we just need to add the `Tres` prefix to use them.
+
+But not all lights can cast shadows, this definition comes directly from ThreeJs and makes sense, for example the purpose of an [ambientLight](https://threejs.org/docs/index.html?q=ambient#api/en/lights/AmbientLight) is to iluminate everysingle side of your scene, so it makes no sense for it to cast shadows, on the contrary, a [DirectionalLight](https://threejs.org/docs/index.html?q=light#api/en/helpers/DirectionalLightHelper) immitating the sun can and should cast shadows.
+
+## Shadows (explanation)
+
+There are also many types of shadows, for example the "soft shadow" is generated automatially when an object receives more light from one side, but in summary a "ThreeJS default shadow" that is directed towards another surface needs to be cast by a mesh and another mesh needs to receive it. As we see in our example, the `Plane` is receiving a shadow but not casting it. Please note that not all materials can cast or receive shadows.
+
+Internally, ThreeJS automatically generates a new mesh with a [ShadowMaterial](https://threejs.org/docs/index.html?q=shado#api/en/materials/ShadowMaterial) which gets updated in each frame, that is why if you apply animations, the shadow also is animated, but also why you have to use shadows carefully, because they could slow your performance down.
+
+::: warning
+The overuse of shadows in this way could drop your performance. However, there are ways to increase your performance, for more information please check out [this video](https://youtu.be/WGNvVGrS0kY?si=q7XyL5eABKUh3gbS&t=1256)
+:::
+
+## Enabling shadows
+
+We could divide this into three steps:
+
+### Activate shadows on the renderer
+
+```vue
+//...
+
+<template>
+  <TresCanvas
+    clear-color="#111"
+    shadows
+    window-size
+  />
+  //...
+</template>
+```
+### Set the light to cast shadows
+
+We can simple put the boolean `cast-shadow`, Vue understand this as a `prop` with `true` value
+
+_The AmbientLight doesn't generate any type of shadow here_
+
+```vue
+//...
+
+<template>
+  <TresAmbientLight :intensity="1" />
+  <TresDirectionalLight
+    cast-shadow
+    :position="[0, 2, 0]"
+    :intensity="1"
+  />
+  
+  //...
+</template>
+```
+### Set the objects to cast or receive shadows
+
+Similarly to the previous step, we set the mesh that we want to cast shadow (our sphere) with the `cast-shadow` prop, and set the object to receive shadow (our plane) with the `receive-shadow` prop.
+
+```vue
+//...
+
+<template>
+  <TresMesh
+    cast-shadow
+    :position="[2, -2, 0]"
+  >
+    <TresSphereGeometry />
+    <TresMeshToonMaterial color="#FBB03B" />
+  </TresMesh>
+  <TresMesh
+    receive-shadow
+    :position="[0, -3, 0]"
+    :rotation="[-Math.PI / 2, 0, 0]"
+  >
+    <TresPlaneGeometry :args="[10, 10, 10, 10]" />
+    <TresMeshStandardMaterial color="#f7f7f7" />
+  </TresMesh>
+  //...
+</template>
+```
+
+Now we have all the necessary steps to add shadows to our scene, and if we apply what we learned in [basic animations](/examples/basic-animations), and we add movement to our cube, you will see the shadow is animated as well 🤩
+
+```vue
+<script setup>
+import { shallowRef } from 'vue'
+import { TresCanvas, useRenderLoop } from '@tresjs/core'
+
+const boxRef = shallowRef()
+
+const { onLoop } = useRenderLoop()
+
+onLoop(() => {
+  if (boxRef.value) {
+    boxRef.value.rotation.y += 0.01
+  }
+})
+</script>
+
+<template>
+  //...
+  <TresMesh
+    ref="boxRef"
+    cast-shadow
+    :position="[0, 0, 0]"
+  >
+    <TresBoxGeometry :args="[1.5, 1.5, 1.5]" />
+    <TresMeshToonMaterial color="#4F4F4F" />
+  </TresMesh>
+  //...
+</template>
+```
+
+_Note that I intentionally did not apply `cast-shadow` to the `Cone` so it doesn't cast any shadow_

docs/es/examples/load-models.md

@@ -0,0 +1,140 @@
+# Load Models
+
+> All models used in this guide are from [Alvaro Saburido](https://sketchfab.com/3d-models/aku-aku-7dfcb6edf10b4098bbb965c56fd3055c).
+
+3D models are available in hundreds of file formats, each with different purposes, assorted features, and varying complexity.
+
+For this guide we are going to focus on loading gLTF (GL Transmission Format) models, which are the most common format for 3D models on the web.
+
+<SandboxDemo url="https://play.tresjs.org/#eNqVVdtu2zgQ/RVC++AsVpacuu12tc7CidsGu+i2Re0+VX2gpbHMhCIJkrLjBvn3DqmLJfeCFPCDNXNmeOZ+H6w0mEulol0FQRLMTKaZssSArdQ/qWClktqSe+JgCyp21JAHstGyJKO5RdmNiTOpYfR3D/tOr5ldSGG15N+BMxBWmoHFFTUsW25pLvf/UxWS5Yfrq4XkUi8VzSAkb+VKCkCVYqLoPNqtBhilonP0sSj44aoS4tAgovgochG6R1ORSWEsKTi5IPepICTjQLV/LiGj317/+eJq+nIUOo3xlExCrK7ASyhXW5qQDeWmFtQQpLY6KEhOI3EIWVlVYT7acJLT8BzIHuNLhuF69Z4J9LhkX9C64fKQillclwsLNbNQKk4t4H9CZr1y7cZrNL5Ig4Kngdc2+vegjYLMsh0saAma1rpEScMskwJNPj0JCf7++pwGjZJLeTum1ukmXjdpdHHrelj9Trys8DFhan5e0qtWh4pPYJ7oS6YdTSkof8OKrW09ZC6FyKQpWcvxJIRpSNyvCwHVTFh8g9kD6s9becfBT0S5dm3qnxvin6RBA53Fxyy7CsRdCYIwqDtyXFIV3RgpcLR8q6WNwqRBUjefk/UnySnSYGutMkkcZ7lA+xw42+lIgI2FKuM+fD6NnkWTOGfGxk6M6DTwLTNwXM/cr/iuLdD98777Rjx8xe6B3ioqHsO9w86fRpPovPHcCqOSOZu+bzfjj/HrcHP0+OwF8v0DTNlPA45+ZeDR+e3B5+cTn2AcIbiLymF2GxyuAA35LziuDX7mGoHjHEr2CKct1AX/NHoec7buu3QecVU8YE9ag5tvw4qTjsxkqRgH/U65kRl2JuVc7v/zsm4FepstZLffkd+Yu5rye2wW0DtM97GUVBdga/Wr5Vu4w/+dspR5xZvi/ED5AYzkleNYw3B15Ei7h/Ns//UDhotzZV7d+bltghoQtbitvfRTuxW6XqsFn33iPN6XY/GTLB0jm0bTXsKHx+f0vBJORYEbxS2D/qnVsOlOnLtZPRU2zyV+UU8hdJ/Xb1avf3hij8funpgMBB4PTCXwkNDOCxpfELqnzLbuzlwEo7bnNN1HBbPbao1qjd4wpTbCnvHbDx+jBqMxcUmZiL13ExfcbuIKYx8Legv5eO1S8I1gXJOAPHJ4d3B/7xOmfuXX/AZxnx3Jh3U8Pbus0hoJXnpjtMRknjWeomssr2uMGt4HRjvKK4hwex/OvLZ3Wb+5rUqzEq/LDkgi1zd4mbCGnkZzGfqH4OErWPcr8A==" />
+
+There are several ways to load models on TresJS:
+
+::: warning
+Please note that the examples above we use top level await, make sure you wrap it with a [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) component. See Suspense for more information. .
+:::
+
+## Using `useLoader`
+
+The `useLoader` composable allows you to pass any type of three.js loader and a URL to load the resource from. It returns a `Promise` with the loaded resource.
+
+For a detailed explanation of how to use `useLoader`, check out the [useLoader](/api/composables#useloader) documentation.
+
+```ts
+import { useLoader } from '@tresjs/core'
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader'
+
+const { scene } = await useLoader(GLTFLoader, '/models/AkuAku.gltf')
+```
+
+Then you can pass the model scene to a TresJS [`primitive`](/advanced/primitive) component to render it:
+
+```html{2}
+<TresCanvas>
+    <primitive :object="scene" />
+</TresCanvas>
+```
+
+> The `<primitive />` component is not a standalone component in the Tres source code. Instead, it's a part of the Tres core functionality. When you use `<primitive>`, it is translated to a `createElement` call, which creates the appropriate three.js object based on the provided "object" prop.
+
+Notice in the example above that we are using the `Suspense` component to wrap the `TresCanvas` component. This is because `useLoader` returns a `Promise` and we need to wait for it to resolve before rendering the scene.
+
+## Using `useGLTF`
+
+A more convenient way of loading models is using the `useGLTF` composable available from the [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package.
+
+```ts
+import { useGLTF } from '@tresjs/cientos'
+
+const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf')
+```
+
+An advantage of using `useGLTF`is that you can pass a `draco` prop to enable [Draco compression](https://threejs.org/docs/index.html?q=drac#examples/en/loaders/DRACOLoader) for the model. This will reduce the size of the model and improve performance.
+
+```ts
+import { useGLTF } from '@tresjs/cientos'
+
+const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf', { draco: true })
+```
+
+Alternatively you can easily select Objects inside the model using `nodes` property
+
+```vue
+<script setup lang="ts">
+import { useGLTF } from '@tresjs/cientos'
+
+const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf', { draco: true })
+</script>
+
+<template>
+  <TresCanvas
+    clear-color="#82DBC5"
+    shadows
+    alpha
+  >
+    <TresPerspectiveCamera :position="[11, 11, 11]" />
+    <OrbitControls />
+    <primitive :object="nodes.MyModel" /> // please note that "MyModel" here is just a placeholder 
+  </TresCanvas>
+</template>
+```
+
+## Using `GLTFModel`
+
+The `GLTFModel` component is a wrapper around `useGLTF` that's available from the [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package.
+
+```vue{2,9}
+<script setup lang="ts">
+import { OrbitControls, GLTFModel } from '@tresjs/cientos'
+</script>
+<template>
+  <TresCanvas clear-color="#82DBC5" shadows alpha>
+    <TresPerspectiveCamera :position="[11, 11, 11]" />
+    <OrbitControls />
+    <Suspense>
+      <GLTFModel path="/models/AkuAku.gltf" draco />
+    </Suspense>
+    <TresDirectionalLight :position="[-4, 8, 4]" :intensity="1.5" cast-shadow />
+  </TresCanvas>
+</template>
+```
+
+This particular approach is more straightforward but gives you less control over the model.
+
+## useFBX
+
+The `useFBX` composable is available from the [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package.
+
+```ts
+import { useFBX } from '@tresjs/cientos'
+
+const model = await useFBX('/models/AkuAku.fbx')
+```
+
+Then is as straightforward as adding the scene to your scene:
+
+```html{2}
+<TresCanvas shadows alpha>
+    <primitive :object="scene" />
+</TresCanvas>
+```
+
+## FBXModel
+
+The `FBXModel` component is a wrapper around `useFBX` that's available from the [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package. It's similar usage to `GLTFModel`:
+
+```vue{2,9}
+<script setup lang="ts">
+import { OrbitControls, FBXModel } from '@tresjs/cientos'
+</script>
+<template>
+  <TresCanvas clear-color="#82DBC5" shadows alpha>
+    <TresPerspectiveCamera :position="[11, 11, 11]" />
+    <OrbitControls />
+      <Suspense>
+        <FBXModel path="/models/AkuAku.fbx" />
+      </Suspense>
+      <TresDirectionalLight :position="[-4, 8, 4]" :intensity="1.5" cast-shadow />
+  </TresCanvas>
+</template>
+```

docs/es/examples/load-textures.md

@@ -0,0 +1,76 @@
+# Load Textures
+
+> All textures used in this example are from [ambientcg](https://ambientcg.com/).
+
+Three-dimensional (3D) textures are images that contain multiple layers of data, allowing them to represent volume or simulate three-dimensional structures. These textures are commonly used in 3D graphics and visual effects to enhance the realism and complexity of scenes and objects.
+
+<SandboxDemo url="https://play.tresjs.org/#eNq9Vm1PGzkQ/itW7gNBJbvhVVWOVBToVb2DgoBvTVU5u5PE4LUt25uQi3K/5X7L/bIb27tZB1qUfqAgRcnj8TPPjMfjWbTuNJj3SiXTElq91rHJNFOWGLClIpyKcX/QsmbQejcQrFBSW3IHj7bUkJ9SzslIy4JsJWkMOqqt31f2C+JcnFExpYYsqx0nFrF7k2ZSr9te6SGzZ1JYLfl3zBkIK43b4f6P0yAXxeEPC4Xi1AL+IuS4cep+EpJxoLqTSS41hvTb273z07PDQSssmgnN5ayypFxNaPg6YwLxjmF/QwCUnIHuKA0j0CAyQKoJG086CvRI6oIi5DidsZeBQtYjSmvY6bsGbRRklk3hjBagK6+E9JQ0zDIpkP/L7g7Z2yGHX2uxuDySU1w5WOlHiHomRHcjUGDMCHWTGBx5bLfb7dZgLQpl3ZbII0xIYoWtnXhkmz4z9lGdM+1ikoLyC8yNXY+m66M5wGhIjwmL25md48IeAhk1thPOovJznDbniMBxGh1ya6cVyqZTUJXcGymwgBdu16BawLrtEY84LK45t4BHZ60yvTTNcoH7c+BsqhMBNhWqSGPzk/3kMOmmOTM2dTBaD1o7z4hDdf4Md9iB9EcxfQWve7EzoA+Kik20r2xPDhI8/Iq5BpOCuT0x90TDRrzO7gQZD9+i3jdgijgNeO9LAxvnNzI/2e36BON1g8ekWM9uZYd1gTX4E8Rhw0vUaNjJoWAbkNamLviD5CjlbBhTOsblQCyxJq3JpBix8ZOKzGShGAd9pdxNWK9MvFdy9qfHrC5hpS+bQPbwHfzePAbJ11gsoKeY7uYoqR6DDcsfbj/j1Y0WC5mXvDqcHyzegJG8dBqD2WkpcpQd2Xm1n/wFY2J8Zz48+ltcBbUm1M4VePRL3SFWtRaArz5x3t4fx9kLWWoi20/2o4Q/fXs2e8YWBJv46oGpnqxoFSuoIt5x328AD1tfSKl++IYNBB68sUQNdbWT9AmdUWYjsrYPBxtWj2zVBafpLBkzOymHaKeRBPNpEywY3/zQAzUYiEkLygQ2QM9j0iGn2UNHy+whvcGP7v7ht72/vp0zg/0xg8JR3Kvxls8t3v8Veom+Q0p/oQAty/FEgDGv7P2m9tO4Fu5d5q/s97N38vGicUuLoeviV1nGS3c5XtP7+ye+ahXL7agsjZrgzHKDRd93pd8WJefxursQpiyw3KWo6ry/XvntYD4QwaDdXhDskpaS5TbpvwsXNU3JJxybcFDQpSDUEpiCnuONwfmG/PPfv0fdP65vSTsHHBxybB9EjshclpoUUjAr9bYjYSPSXslNppSXsF33gSd4oqWlrlckc/KmH/SgytAcnN4XZsRqXrkEM3EZwRaxInfTickodwMezk7xZLI2GeH2W7/nI8gCLEbawy5lqrENZyz/4YadZm6K3N5aKnKq80uUpBnljYn7m3aG+MQgV9NRmjEu/MUXu1ML7iY4TDV2q5HTV5Zz+2ySWv4PY68KvA==" />
+
+There are two ways of loading 3D textures in TresJS:
+
+## Using `useLoader`
+
+The `useLoader` composable allows you to pass any type of three.js loader and a URL to load the resource from. It returns a `Promise` with the loaded resource.
+
+For a detailed explanation of how to use `useLoader`, check out the [useLoader](/api/composables#use-loader) documentation.
+
+```ts
+import { useLoader } from '@tresjs/core'
+import { TextureLoader } from 'three'
+
+const texture = useLoader(TextureLoader, '/Rock035_2K_Color.jpg')
+```
+
+Then you can pass the texture to a material:
+
+```html
+<Suspense>
+  <TresCanvas>
+    <TresMesh>
+      <TresSphereGeometry :args="[1,32,32]" />
+      <TresMeshStandardMaterial :map="texture" />
+    </TresMesh>
+  </TresCanvas>
+</Suspense>
+```
+
+Notice in the example above that we are using the `Suspense` component to wrap the `TresCanvas` component. This is because `useLoader` returns a `Promise` and we need to wait for it to resolve before rendering the scene.
+
+## Using `useTexture`
+
+A more convenient way of loading textures is using the `useTexture` composable. It accepts both an array of URLs or a single object with the texture paths mapped.
+
+To learn more about `useTexture`, check out the [useTexture](/api/composables#use-texture) documentation.
+
+```ts
+import { useTexture } from '@tresjs/core'
+
+const pbrTexture = await useTexture({
+  map: '/textures/black-rock/Rock035_2K_Displacement.jpg',
+  displacementMap: '/textures/black-rock/Rock035_2K_Displacement.jpg',
+  roughnessMap: '/textures/black-rock/Rock035_2K_Roughness.jpg',
+  normalMap: '/textures/black-rock/Rock035_2K_NormalDX.jpg',
+  aoMap: '/textures/black-rock/Rock035_2K_AmbientOcclusion.jpg',
+  metalnessMap: '/textures/black-rock/myMetalnessTexture.jpg',
+  matcap: '/textures/black-rock/myMatcapTexture.jpg',
+  alphaMap: '/textures/black-rock/myAlphaMapTexture.jpg'
+})
+```
+Similar to the previous example, we can pass all the textures to a material via props:
+
+```html
+<Suspense>
+  <TresCanvas>
+    <TresMesh>
+      <TresSphereGeometry :args="[1,32,32]" />
+      <TresMeshStandardMaterial
+        :map="pbrTexture.map"
+        :displacementMap="pbrTexture.displacementMap"
+        :roughnessMap="pbrTexture.roughnessMap"
+        :normalMap="pbrTexture.normalMap"
+        :aoMap="pbrTexture.ambientOcclusionMap"
+      />
+    </TresMesh>
+  </TresCanvas>
+</Suspense>
+```

docs/es/examples/orbit-controls.md

@@ -0,0 +1,103 @@
+# OrbitControls
+
+<SandboxDemo url="https://play.tresjs.org/#eNqVVU1z2zYQ/Ss78nR0KEVSlp1JWaejWk7TdmInY+kW5gCRMAkbBDAAKFnj0X/PAhAlyvlydBJ23z7svl0snwYLTc3fSsWrlg6ywYUpNFMWDLWtAk5E9SYfWJMP/soFa5TUFp7gkhhWzGtSyvU1URHMb99dziSXeq5IQSO4kQspKLoUExVs4U7LBoa21pQO/+zxuKtnRKyI2YOmFm33JimkPsZ+0EtmZ1JYLbmJYEEf7eTq6zBGhZXGRSZJiIFiFwTLDWAUFSVmlYtcoMNYqDi8gadcABScEu3ryGB48vr06nJ2Poycx/haTQZWt9RbCFc1yeCOcBMMAYI1LzaKZs8lcgjZWtViCZ1O2XPdHMgehMuOdUT3Fsu6SEKHsB94sLRRnFiKJ4CLnp6r0ZKJEntXcd87wJ/3f6TaKFpYtqIz0lBNIFPSMMukQPSnswgmEfzxOR9A0oUdSX8wz1skEibcHfh9U7ojHDOnEYwjSJH5ALAYgL4ZZ8UD3AzhSpOq77/DS9FfW6tMliSarOOK2bpdtoZq11fsdlzIJnGVYfuJwbk1SUOYSFysSf5hmsxkSW9p1XKi43sjBdbWXbHPfafONTX1jdQN4deoqmaE7+tFRBIK7ARIningGa6YdupKQfh7VtX2KxFOIzhz8mbMpY+uDTrG8SmaCmLsKAzSQWZH+k6z8l/KFdU7O6ay7zUaLpLeIODR2A13f2vbcJybpSw3YcQboismMkhxkgAUKd1b6I41dQlnME7T37xhzUpb78/bXJzgKAain2ABlqR4qLRsRTkqwpM6SVN3D9LgDPsEB9EgvO9RQ5RvDW4gT5/vHLh4snChs/WXg3McJqMoBcaXlLOVjgW1iVBN0odPJ/F5nCYlMzZxZkTnA//ijojD+vgV7hCB9K/69Dvz8S12TcmDIuIlue+x07M4jcc75s4YN8zF9Lndcn0Jr8NNkfH8Neb7OzVNXwb8BuDLerG+Pfh0nHqBcenQx7g5VneHw8nWtPwF4hDwI2oEjkrasBeQdlBX/Fn8KuFs2ad0jDiaW5xJa3C13LHq2UTinlGMU/1Budd8PJmEc7n+39v2nwgfU9Pi4Rv2e/MYUv6Iw0L1CuU+tBLfKLXB/XZ+gyun52xk2fJdc77jvKVG8tblGGCX+AYx7R7OZ/uff2D4/Bfmrfsqmq6oo0Qtfs289VO3BfezFgyfvXAe79sx+4FKh8om8WQv+PYLbBTQQA==" />
+
+[OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) is a camera controller that allows you to orbit around a target. It's a great way to explore your scene.
+
+However, it is not part of the core of ThreeJS. So to use it you would need to import it from the `three/addons/controls/OrbitControls` module.
+
+This creates a problem because **TresJS** automatically creates a catalog of the core of Three so you can use them as components.
+
+Fortunately, **TresJS** provides a way to extend the catalog of components. You can do it by using the `extend` method from the core library.
+
+For more information about extending your TresJS catalog, refer to the [extending](/advanced/extending.md) section.
+
+## Using OrbitControls
+
+To use `OrbitControls` you need to import it from the `three/addons/controls/OrbitControls` module.
+
+```js
+import { OrbitControls } from 'three/addons/controls/OrbitControls'
+```
+
+Then you need to extend the catalogue of components using the `extend` method.
+
+```js
+import { extend } from '@tresjs/core'
+import { OrbitControls } from 'three/addons/controls/OrbitControls'
+
+extend({ OrbitControls })
+```
+
+Now you can use the `TresOrbitControls` component in your scene.
+
+```vue
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
+    <TresOrbitControls
+      v-if="state.renderer"
+      :args="[state.camera, state.renderer?.domElement]"
+    />
+  </TresCanvas>
+</template>
+```
+
+Since [OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) needs a reference to the camera and the renderer, you need to pass them as arguments.
+
+You can use the [useTres](/api/composables#usetres) composable to get the camera and the renderer.
+
+```ts
+import { useTres } from '@tresjs/core'
+
+const { state } = useTres()
+```
+
+So the final code would be something like this:
+
+```vue
+<script setup lang="ts">
+import { extend, useTres } from '@tresjs/core'
+import { OrbitControls } from 'three/addons/controls/OrbitControls'
+
+extend({ OrbitControls })
+
+const { state } = useTres()
+</script>
+
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
+    <TresOrbitControls
+      v-if="state.renderer"
+      :args="[state.camera, state.renderer?.domElement]"
+    />
+  </TresCanvas>
+</template>
+```
+
+## OrbitControls from `cientos`
+
+Here is where the fancy part begins. ✨  
+The `cientos` package provides a component called `<OrbitControls />` that is a wrapper of the `OrbitControls` from the [`three-stdlib`](https://github.com/pmndrs/three-stdlib) module.
+
+The nicest part? You don't need to extend the catalog or pass any arguments.  
+It just works. 💯
+
+```vue
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
+    <OrbitControls />
+  </TresCanvas>
+</template>
+```

docs/es/examples/shaders.md

@@ -0,0 +1,174 @@
+# Shaders
+
+This guide will help you get started with shaders in TresJS.
+
+We will build a simple scene with a blob. We will then animate the blob to softly distorted it.
+
+::: warning
+_Basic knowledge of how shaders work is necessary_
+:::
+
+<SandboxDemo url="https://play.tresjs.org/#eNqVVltv2zYU/iuE91BntSU7cYrBS4q0QTt0WNcgyfZSFxsjH9tMJVIjKdle4P++j9TFVJMU3oMDndvH71x4mIferSbzJs+jsqDetHdmEi1yywzZImcpl8vzWc+aWe/1TIosV9qyB2ZWPE3V+poWbMcWWmXsBaJf/By4ONRLLktuBqwwdE1yTvo3pfI24sLC5d7EidLd0E/6TthLJa1WqXnsLkhaZToRf1JilT5ufe1KE72YyZlMlDSW3aXqzpE9D5j3ZZGmR0BpnAopFkpnBl4PM8lYcSsymgK95GmBjxHbDbz+TZanwhbz0Chp3bDoj6LxgOHPURPwXtM/Bclk+0zA8WjATivv3Z5PSdrS5mbFUThw+nsma4awJMcBDeTQtbTnBZZFqjhydDn5nEuut0Iuq4jyj7JSKjFnGReyf1TVgDn7hGVqTumVMsIKJcHFyx+51WLDfvQu/by2Dtg4GrmyuuBOXLRlL9EAgHfVDmJPGeKwonnk9G2S0eZJzI3DTJT5BnPbxdw+g+kKFKRZCloHWTqxTbKDX1NZpn8F7rlW92gohH1lAsA6BqWGb+HqjV6jqU27F5ovM4x22PBcUyKMg89oLoosr9qI2EPbB4rvAXypUuUwfavQoIGLibZuTE/bjlV8KjYPTMn6toJteH/71Z2pzP3+A0NdLB8wSnluaM52R+z8dX28WLB+ffciP/ctr442yrglLXgaNXcw8t2qrCBQY7tQkNw5BmdxtaiwliBYQk8BAomxs/3uYUlKXA8Tlz722A/j8XjWc0tgrtaG8TRfcbYWEtLQiH+rcAB0N1DcqB3uFWmTuzaXdMkz0pxNm9HHAZ/HuPrV7wsOmi5UCe3k1H1zHwfRUZhK8MI31oT388J4NBpB6pz3kcyKaVrAXNfM+YdHopkTNBLn1XF15E2+Ik2/kMrI6i3O10vj/I8H7MT/HMPmrCbGDx/m17eDTcMdhNhQ9LQ7MwuHrsK5NB2FsfkMU4ybHH0fu1lPtbK8yXIIUqvo6gOLGcgj58cJX+G1eiLfMZz3vyeSdoe95UYkbd7tvEwmk+fYNmI1aFCcxcEU9ga96nUaZjyP7o2SeFv97M9qA8qA56ACnvXCx9AZZr2VtbmZxnEyl4jHJROljiTZWOZZHLpfnESn0SieC2Njp4b3rOcfng5w9Wz+H+wqAvCvQvha3T3Frol/zVH+A/Bb34tJhPGvkRtllAkXE2K7x/wQXOd3AcTTn8D3JZksLAP+P8EaO7i+gfvFGEsSiFgTtImybnVrP2wUjf10OHAV8D1oOA7nlIkDQBtXl/wkehWn4i6EbNYmZtIarPeFWH4zkYnKcpGS/pS769adTP//0q9eZ3VBLb9kRcnXJ/T3ZlNRvsKwkC5R7n0rcSfJVuZ3N7/TBt+tES9skdbNecZ4TUalheNYub0t5By0Az/P9oO/YHgeb827jSXpXtDHRO02J6/93GyDdtYqxRdfOO/v23H5nSrtMzuJTtqC7/4DVvHLxg==" />
+
+## Setting up the scene (optional)
+
+We import all the modules that we need, for comfort we can use the orbit-controls from cientos,
+[look here to see how](/examples/orbit-controls).
+
+Now, let's put our camera in the `[11,11,11]` position.
+
+Lastly just to help us with the location, let's add a simple plane, rotated in the X axis, with `[10, 10]` units.
+
+```vue
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import { OrbitControls } from '@tresjs/cientos'
+</script>
+
+<template>
+  <TresCanvas
+    clear-color="#111"
+    window-size
+  >
+    <OrbitControls />
+    <TresPerspectiveCamera :position="[11, 11, 11]" />
+
+    <TresMesh :rotation="[-Math.PI / 2, 0, 0]">
+      <TresPlaneGeometry :args="[10, 10]" />
+      <TresMeshBasicMaterial color="#444" />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+## ShaderMaterial
+
+As you know every instance in [ThreeJs](https://threejs.org/) is available in **TresJs**, so is the `ShaderMaterial`, we just need to add the `Tres` prefix to use it.
+
+For our blob, we could use a simple `SphereGeometry` adding some widthSegments and heightSegments to create a smooth effect, and put our blob 4 units in the Y positive axis
+
+```vue
+<TresMesh :position="[0, 4, 0]">
+  <TresSphereGeometry :args="[2, 32, 32]" />
+  <TresShaderMaterial />
+</TresMesh>
+```
+
+The `ShaderMaterial` accepts special properties, like `uniforms` `vertexShader` and `fragmentShader`, so we can create it in our script section and make the bind with our instance.
+
+For this example, our uniforms look like this:
+
+```ts
+import { Vector2 } from 'three'
+
+//...
+const uniforms = {
+  uTime: { value: 0 },
+  uAmplitude: { value: new Vector2(0.1, 0.1) },
+  uFrequency: { value: new Vector2(20, 5) },
+}
+//..
+```
+
+Our fragment shader looks like this:
+
+```ts
+//...
+const fragmentShader = `
+precision mediump float;
+varying vec2 vUv;
+
+void main() {
+    gl_FragColor = vec4(1.0, vUv.y, 0.5, 1.0);
+}
+`
+//..
+```
+
+And lastly our vertexShader:
+
+```ts
+const vertexShader = `
+uniform vec2 uAmplitude;
+uniform vec2 uFrequency;
+uniform float uTime;
+
+varying vec2 vUv;
+
+void main() {
+    vec4 modelPosition = modelMatrix * vec4(position, 1.0);
+    modelPosition.y += sin(modelPosition.x * uFrequency.x - uTime) * uAmplitude.x;
+    modelPosition.x += cos(modelPosition.y * uFrequency.y - uTime) * uAmplitude.y;
+
+    vec4 viewPosition = viewMatrix * modelPosition;
+    gl_Position = projectionMatrix * viewPosition;
+    vUv = uv;
+}
+`
+//..
+```
+
+## Animating the blob
+
+Similar to what we learn in the [Basic animations](/examples/basic-animations) example, we start by referencing our blob, using [Template Ref](https://vuejs.org/guide/essentials/template-refs.html)
+
+```vue
+<script setup lang="ts">
+import { shallowRef } from 'vue'
+import { TresCanvas } from '@tresjs/core'
+import { OrbitControls } from '@tresjs/cientos'
+
+const blobRef = shallowRef(null)
+//...
+</script>
+
+<template>
+  <TresCanvas
+    clear-color="#111"
+    window-size
+  >
+    <OrbitControls />
+    <TresPerspectiveCamera :position="[11, 11, 11]" />
+    <TresMesh
+      ref="blobRef"
+      :position="[0, 4, 0]"
+    >
+      <TresSphereGeometry :args="[2, 32, 32]" />
+      <TresShaderMaterial />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+ Once we have got that, we could use the `onLoop` callback to animate our `uTime`.
+
+ ```ts
+import { TresCanvas, useRenderLoop } from '@tresjs/core'
+ 
+ //...
+ const { onLoop } = useRenderLoop()
+ 
+onLoop(({ elapsed }) => {
+   if (blobRef.value) {
+     blobRef.value.material.uniforms.uTime.value = elapsed
+   }
+})
+ //...
+```
+
+And that it is, we have our basic shader running smoothly.
+
+## Using GLSL vite-pluging (optional)
+
+_This step is completly optional and is out of the scope of the **TresJs** team_
+
+Defining our shader inline is not always the best idea, but if you're using [vite](https://vitejs.dev/) you can put your `GLSL` files in a different file just by using the [vite-plugin-glsl](https://www.npmjs.com/package/vite-plugin-glsl) (check out the link for the official documentation).
+
+And you could have a structure similar to this:
+
+```
+├── src/
+│   ├── myTresJsComponent.vue
+│   ├── shaders/
+│       ├── vertexShader.glsl
+│       ├── fragmentShader.glsl
+```

docs/es/examples/text-3d.md

@@ -0,0 +1,194 @@
+# Text3D
+
+[TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) is one of the ways we can add 3D text in our scene.
+
+<SandboxDemo url="https://play.tresjs.org/#eNqdVlFv2zYQ/iuEgsEbZkuOnXSd5gxe7G5YsbRF7LcqD7RES0wokiApO0Hg/74jKduUkWbp8hCYdx+/O3684+k5Wiqi/5Ay3jQkSqOJzhWVBmliGokY5uVVFhmdRb9nnNZSKIOe0TXWNF9UuBDbGyz7aHH71/VMMKEWEuekjz6JpeAEXJLyEu3QWoka9UylCOn9FvDY0DPMN1gfQFMDtnud5EJ1sZ/VipqZ4EYJ9gKcEm6EDnYsyaNpQXFiF/aAvYxnPBdcG1QydIWeM45QzghWLv0U9c7ej+bXs8te33q0O6JOkVENcRbMZIVTtMZMe4OHwFGXT5Kkp8pYhGiMbCDzvTzpqVwWZI56pV35wL2DU00SfzFwDbAwpJYMGwIrhCaBjJvBivICrqxk7soQ/Dn/F6K0JLmhGzLDNVEYpVJoaqjggP466o/6v95lEUr2m7p6H8yLBmi49pE9uxX64E9OAC74nCobWnDM/qFlZbqxh3006qMLGz2l3MBmap7AcR6PwJRjbQZe5TbKJDkeGAyTJFADlto8MfuzMjUD8VaiePL3XGNVUp6iIciJkMRF4dT2y4rYxFJ0Phz+4AxbWpjqsN5l/AzuwxP9BxahFc4fSiUaXgxyX1dnw6GNAzRwkS7BqB/5Sh3UWMb3WnDoPkeftQ5outQHtLawMawjiypjpE6TJC847C8IoxsVc2ISLuskhE/H8WU8TAqqTWLNgM4iV3YdYt9C38PtdwD9u5C+NXejmC3BDxLzt+R+wE4v4mF83jLvjXFN7Z6Q2z4sb+G1uCkwXr6HfH8mug5lgOeh0eTN+gbw6fnQCQydRx7juqtui4MKVqT4DmK/4TVqAA4KUtM3kO6h9vAX8buE0VVIaRmhNHdQk0bD87im5UlF5qKWlBH1Wdqu7VYmZkxsPzrb4Z10eyqSP7xgv9ePPuUvUCxEbUDu41VCjxLj3R8Wn+BpCZy1KBrWXs43nLdEC9bYHD3sGnoQ0g5wLtu/XYNB+y/1h0f34rSH6iRq4El31q/7x+5Qa95w54RzeHcds1dUOp5sHI8Dwfej6XT2hvMW6sHCGkVenpPhSAXceP7N+biffjU2OcyslvQK4S2mJojzoztyb19UCm/jkpqqWQFEAQVoZmIoCvcUAz/WkLROakw5PMeOwq5sEJ38Ekte2ol699Prk6ydJuP5Xm/UnRSD8z6CaTGEUXFEKLK2nyiw75asQ8ca0gTP/zqD3auTP6nCM1FAVZUNw8r1RBjhMASR+5T5uDiu3dy7Ibq6cSLAf6IoZij1okBenSsIJ6/7WhnPu6Mt2v0LMkc7LA=="/>
+
+However, it is not part of the core of ThreeJS. So to use it you would need to import it from the `three/addons/controls/TextGeometry` module.
+
+This creates a problem because **TresJS** automatically creates a catalog of the core of Three so you can use them as components.
+
+Fortunately, **TresJS** provides a way to extend the catalog of components. You can do it by using the `extend` method from the core library.
+
+For more information about extending your TresJS catalog, refer to the [extending](/advanced/extending.md) section.
+
+## Using TextGeometry
+
+To use `TextGeometry` you need to import it from the `three/addons/geometries/TextGeometry` module.
+
+```js
+import { TextGeometry } from 'three/addons/geometries/TextGeometry'
+```
+
+Then you need to extend the catalogue of components using the `extend` method.
+
+```js
+import { extend } from '@tresjs/core'
+import { TextGeometry } from 'three/addons/geometries/TextGeometry'
+
+extend({ TextGeometry })
+```
+
+[TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) needs a only one required argument the font, you can see an example below.
+
+```js
+const fontPath = 'https://raw.githubusercontent.com/Tresjs/assets/main/fonts/FiraCodeRegular.json'
+
+const loader = new FontLoader()
+
+const font = await new Promise((resolve, reject) => {
+  try {
+    loader.load(fontPath, (font) => {
+      resolve(font)
+    })
+  }
+  catch (error) {
+    reject(console.error('cientos', error))
+  }
+})
+```
+
+Now you can use the `TresTextGeometry` component inside a TresMesh in your scene
+
+```vue
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <TresMesh>
+      <TresTextGeometry
+        :args="['TresJS', { font, ...fontOptions }]"
+        center
+      />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+then as in the example you can pass an object with the desired configurations.
+
+```ts
+const fontOptions = {
+  size: 0.5,
+  height: 0.2,
+  curveSegments: 5,
+  bevelEnabled: true,
+  bevelThickness: 0.05,
+  bevelSize: 0.02,
+  bevelOffset: 0,
+  bevelSegments: 4,
+}
+```
+
+We can also pass a matcapTexture to add final details, using the TresMeshNormalMaterial inside the TresMesh
+
+```ts
+const matcapTexture = await useTexture(['https://raw.githubusercontent.com/Tresjs/assets/main/textures/matcaps/7.png'])
+
+  <TresMesh>
+    <TresTextGeometry :args="['TresJS', { font, ...fontOptions }]" center />
+    <TresMeshNormalMaterial :matcap="matcapTexture" />
+  </TresMesh>
+```
+
+So the final code would be something like this:
+
+```vue
+<script setup lang="ts">
+import { extend } from '@tresjs/core'
+import { TextGeometry } from 'three/addons/geometries/TextGeometry'
+import { FontLoader } from 'three/addons/loaders/FontLoader'
+import { useTexture } from '/@/composables'
+
+extend({ TextGeometry })
+
+const fontPath = 'https://raw.githubusercontent.com/Tresjs/assets/main/fonts/FiraCodeRegular.json'
+
+const fontOptions = {
+  size: 0.5,
+  height: 0.2,
+  curveSegments: 5,
+  bevelEnabled: true,
+  bevelThickness: 0.05,
+  bevelSize: 0.02,
+  bevelOffset: 0,
+  bevelSegments: 4,
+}
+
+const loader = new FontLoader()
+
+const font = await new Promise((resolve, reject) => {
+  try {
+    loader.load(fontPath, (font) => {
+      resolve(font)
+    })
+  }
+  catch (error) {
+    reject(console.error('cientos', error))
+  }
+})
+
+const matcapTexture = await useTexture(['https://raw.githubusercontent.com/Tresjs/assets/main/textures/matcaps/7.png'])
+</script>
+
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <TresMesh>
+      <TresTextGeometry
+        :args="['TresJS', { font, ...fontOptions }]"
+        center
+      />
+      <TresMeshNormalMaterial :matcap="matcapTexture" />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+I know seems like a lot of work, but good news there is a much more simple way
+
+## TextGeometry from `cientos`
+
+The `cientos` package provides a component called `<Text3D />` that is a wrapper of the `TextGeometry` from the [`three-stdlib`](https://github.com/pmndrs/three-stdlib) module.
+
+The nicest part? You don't need to extend the catalog and just pass the font argument.
+It just works. 💯 (if not text is provided, the text will be TresJS)
+
+```vue
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <Text3D :font="fontPath" />
+  </TresCanvas>
+</template>
+```
+
+We can pass the options as props
+
+```html
+<Text3D :font="fontPath" :text="my 3d text" :size="0.8" />
+```
+
+in case the options are not provided the default values are:
+
+```js
+size: 0.5,
+height: 0.2,
+curveSegments: 5,
+bevelEnabled: true,
+bevelThickness: 0.05,
+bevelSize: 0.02,
+bevelOffset: 0,
+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"
+
+```vue
+<Text3D :font="fontPath" :text="my 3d text" center />
+```

docs/es/guide/getting-started.md

@@ -0,0 +1,92 @@
+# Installation
+
+Learn how to install TresJS
+
+::: code-group
+
+```bash [pnpm]
+pnpm add three @tresjs/core
+```
+
+```bash [npm]
+npm install three @tresjs/core
+```
+
+```bash [yarn]
+yarn add three @tresjs/core
+```
+
+:::
+
+> Better use with Vue 3.x and composition API
+
+## Typescript
+
+TresJS is written in Typescript and it's fully typed. If you are using Typescript, you will get the full benefit of the typings. Just make sure you install the types for three.
+
+::: code-group
+
+```bash [npm]
+npm install @types/three -D
+```
+
+```bash [yarn]
+yarn add @types/three -D
+```
+
+```bash [pnpm]
+pnpm add @types/three -D
+```
+
+:::
+
+## Getting started
+
+You can install TresJS as any other Vue plugin
+
+```ts
+import { createApp } from 'vue'
+import App from './App.vue'
+
+import Tres from '@tresjs/core'
+
+export const app = createApp(App)
+
+app.use(Tres)
+app.mount('#app')
+```
+
+Or you can use it directly in your component
+
+```vue
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+</script>
+<template>
+  <TresCanvas>
+    <!-- Your scene here -->
+  </TresCanvas>
+</template>
+```
+
+::: tip
+This is recommended for performance and bundle size reasons, tree-shaking will work better and you will only import the components that you use.
+:::
+
+## Vite
+
+Since v2 is a custom renderer, we need to let the `vue-compiler` of your app know that the components of Tres are ok to be included to avoid the `[Vue warn]: Failed to resolve component` warning.
+
+You just need to add this to your `vite.config.ts` inside of the vue plugin:
+
+```ts
+export default defineConfig({
+  plugins: [vue({
+    template: {
+      compilerOptions: {
+        isCustomElement: tag => tag.startsWith('Tres') && tag !== 'TresCanvas',
+      },
+    },
+  }),
+})
+```

docs/es/guide/index.md

@@ -0,0 +1,114 @@
+# Introduction
+
+<ClientOnly>
+    <div style="aspect-ratio: 16/9; height: auto; margin: 2rem 0; border-radius: 8px; overflow:hidden;">
+      <FirstScene />
+    </div>
+</ClientOnly>
+
+::: code-group
+
+```bash [npm]
+npm install @tresjs/core three 
+```
+
+```bash [yarn]
+yarn add @tresjs/core three 
+```
+
+```bash [pnpm]
+pnpm add @tresjs/core three 
+```
+
+:::
+
+## Typescript
+
+TresJS is written in Typescript and it's fully typed. If you are using Typescript, you will get the full benefit of the typings. Just make sure you install the types for three.
+
+::: code-group
+
+```bash [npm]
+npm install @types/three -D
+```
+
+```bash [yarn]
+yarn add @types/three -D
+```
+
+```bash [pnpm]
+pnpm add @types/three -D
+```
+
+:::
+
+## Vite
+
+If you are using Vite, you have add the following to your `vite.config.ts`:
+
+```ts
+import { templateCompilerOptions } from '@tresjs/core'
+
+export default defineConfig({
+  plugins: [
+    vue({
+      // Other config
+      ...templateCompilerOptions
+    }),
+  ],
+}),
+```
+
+This is required to make the template compiler work with the custom renderer and not throw warnings on the console. For more info check [here](/guide/troubleshooting.html).
+
+## Try it online
+
+### Sandbox
+
+You can try TresJS online using the official [sandbox](https://play.tresjs.org/). Check it out:
+
+<iframe src="https://play.tresjs.org/" class="w-full rounded shadow-lg outline-none border-none aspect-4/3"></iframe>
+
+### StackBlitz
+
+We have a brand new [StackBlitz](https://stackblitz.com/) starter to try TresJS online. Check it out:
+
+![](/stackblitz-starter.png)
+
+<StackBlitzEmbed projectId="tresjs-basic" />
+
+## Playground
+
+We also have a playground where you can try TresJS online. Check it out [here](https://playground.tresjs.org/).
+
+![](/playground.png)
+
+## Motivation
+
+[ThreeJS](https://threejs.org/) is a wonderful library to create awesome **WebGL** 3D websites. Is also a constantly updated library that makes hard for wrapper maintainers like [TroisJS](https://troisjs.github.io/) to keep up with all the enhancements.
+
+React ecosystem has an impresive **custom render** solution called [React-three-fiber](https://docs.pmnd.rs/react-three-fiber) that allows you build your scenes declaratively with re-usable, self-contained components that react to state.
+
+In my search for something similar in the VueJS ecosystem, I found this amazing library called [Lunchbox](https://github.com/breakfast-studio/lunchboxjs) which works with the same concept that R3F, it provides a [custom Vue3 Renderer](https://vuejs.org/api/custom-renderer.html). I'm also contributing to improve this library so it gets as mature and feature-rich as R3F.
+
+The only problem is, mixing compilers renderers in Vue 3 is something the Vue community is still working on - see [here](https://github.com/vuejs/vue-loader/pull/1645) for more information.
+
+```ts
+// Example Vite setup
+import { createApp } from 'vue'
+import { createApp as createLunchboxApp } from 'lunchboxjs'
+import App from './App.vue'
+import LunchboxApp from './LunchboxApp.vue'
+
+// html app
+const app = createApp(App)
+app.mount('#app')
+
+// lunchbox app
+const lunchboxApp = createLunchboxApp(LunchboxApp)
+// assuming there's an element with ID `lunchbox` in your HTML app
+lunchboxApp.mount('#lunchbox')
+```
+
+So I was inspired by both libraries to create a Vue custom renderer for ThreeJS. That's **TresJS v2**.
+

docs/es/guide/migration-guide.md

@@ -0,0 +1,220 @@
+# Migration Guide
+
+This guide is intended to help you migrate from v1 to the newest versions of TresJS 🤩✨.
+
+::: code-group
+
+```bash [pnpm]
+pnpm update @tresjs/core
+```
+
+```bash [npm]
+npm update @tresjs/core
+```
+
+```bash [yarn]
+yarn upgrade @tresjs/core
+```
+
+:::
+
+## What's new?
+
+### Vue Custom Renderer
+
+**TresJS** is now a [Vue Custom Renderer](https://vuejs.org/api/custom-renderer.html#createrenderer) 🎉 that lives inside of a wrapper component `TresCanvas` that is responsible for creating the `WebGLRenderer` and the `Scene` for you and creating a **new Vue App instance** to render the scene.
+
+### Typescript support and Intellisense 🦾
+
+![TresJS Intellisense](/v2-intellisense.gif)
+
+This was probably the most **requested feature for TresJS**. Now Tres components work with Volar and provide type intellisense.
+
+**TresJS** now generates type declaration on build time for all the components based of the catalog from ThreeJS. This means that you can use all the components from ThreeJS and get type intellisense for them.
+
+### Tres Plugin is optional 👍
+
+The `TresPlugin` is now optional. You can use TresJS without it by importing the components directly from `tresjs/core`:
+
+```vue
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+</script>
+
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera
+      :position="cameraPosition"
+      :fov="cameraFov"
+      :aspect="cameraAspect"
+      :near="cameraNear"
+      :far="cameraFar"
+    />
+    <TresMesh :geometry="geometry" :material="material" />
+  </TresCanvas>
+</template>
+```
+
+::: info
+This is recommended for performance and bundle size reasons, tree-shaking will work better and you will only import the components that you use.
+:::
+
+### TresScene no longer needed
+
+The `<TresScene />` component is now deprecated since the scene is now created by the `<TresCanvas />`.
+
+In the beginning, I thought that it would be a good idea to have a separate component for the scene in terms of verbosity and keep it as similar to plain ThreeJS, but it turned out that it was not really useful.
+
+You can now create a scene like this:
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera
+      :position="cameraPosition"
+      :fov="cameraFov"
+      :aspect="cameraAspect"
+      :near="cameraNear"
+      :far="cameraFar"
+    />
+    <TresMesh :geometry="geometry" :material="material" />
+  </TresCanvas>
+</template>
+```
+
+To migrate your code, you can just remove the `<TresScene />` component and move the children to the `<TresCanvas />` component.
+
+### `useCatalog` is now deprecated
+
+The `useCatalog` function is now deprecated. You can now import the catalog directly from `@tresjs/core`
+
+You can read more about it here: [Extending](/advanced/extending.md)
+
+Change this:
+
+```ts {2,5,7}
+// Wrong ❌
+import { useCatalog } from '@tresjs/core'
+import { TextGeometry } from 'three/addons/geometries/TextGeometry'
+
+const { extend } = useCatalog()
+
+extend({ TextGeometry })
+```
+
+To this:
+
+```ts {2,6}
+// Correct ✅
+import { extend } from '@tresjs/core'
+import { TextGeometry } from 'three/addons/geometries/TextGeometry'
+
+// Add the element to the catalogue
+extend({ TextGeometry })
+```
+
+### Model's ref value `getModel` is now deprecated
+
+The `getModel` function is now deprecated. You can now use the `model` property directly.
+
+Change this:
+
+```vue {7,9-12}
+// Wrong ❌
+<script setup lang="ts">
+import { useGLTF } from '@tresjs/cientos'
+
+const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf', { draco: true })
+
+const modelRef = ref()
+
+watch(modelRef, ({ getModel }) => {
+  const model = getModel()
+  model.position.set(0, 0, 0)
+})
+</script>
+<template>
+  <primitive :object="nodes.MyModel" />
+</template>
+```
+
+To this:
+
+```vue {7,9-12}
+// Correct ✅
+<script setup lang="ts">
+import { useGLTF } from '@tresjs/cientos'
+
+const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf', { draco: true })
+
+const modelRef = ref()
+
+watch(modelRef, model => {
+  // Do something with the model
+  model.position.set(0, 0, 0)
+})
+</script>
+<template>
+  <primitive :object="nodes.MyModel" />
+</template>
+```
+
+### Cameras need to be before any control 🎥
+
+The `TresOrbitControls` component needs to be after the camera in the tree. This is because the controls need to know the camera to work.
+
+Change this:
+
+```vue {3,5}
+// Wrong ❌
+<template>
+  <TresCanvas>
+    <TresOrbitControls />
+    <TresPerspectiveCamera />
+  </TresCanvas>
+</template>
+```
+
+To this:
+
+```vue {3,5}
+// Correct ✅
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera />
+    <TresOrbitControls />
+  </TresCanvas>
+</template>
+```
+
+## UseTres is now useTresContext <Badge type="warning" text="^3.0.0" />
+
+For v3 we reworked the whole state logic to make it more flexible and easier to use for plugin authors and ecosystem packages. Instead of using a store like in v2, we now use a context provider based on `provide/inject`.
+
+The `useTres` function is now an alias of the `useTresContext` function to avoid breaking demos and experiments out there, but consider using `useTresContext` from now on. 
+
+Instead of a big reactive object, you will now get the `scene` and `renderer` refs, between other properties, directly.
+
+Change this:
+
+```ts {2}
+// Wrong ❌
+import { useTres } from '@tresjs/core'
+
+const { state, setState } = useTres()
+
+console.log(state.scene)
+```
+
+To this:
+
+```ts {2}
+// Correct ✅
+import { useTresContext } from '@tresjs/core'
+
+const { scene, renderer } = useTresContext()
+
+console.log(scene.value)
+```
+
+For more detailed information about the new context provider system, you can read the [API DOCS](/api/composables.md) section.

docs/es/guide/nuxt.md

@@ -0,0 +1,58 @@
+# Nuxt module `@tresjs/nuxt`
+
+![TresJS Nuxt Module](/nuxt-stones.png)
+
+<a href="https://www.npmjs.com/package/@tresjs/nuxt"><img src="https://img.shields.io/npm/v/@tresjs/nuxt/latest?color=%2382DBCA" alt="npm package"></a>
+
+A official Nuxt module for TresJS is here 🎉. 
+
+Repository is [here](https://github.com/Tresjs/nuxt)
+
+## Installation
+
+::: code-group
+
+```bash [pnpm]
+pnpm add three @tresjs/nuxt 
+```
+
+```bash [npm]
+npm install three @tresjs/nuxt 
+```
+
+```bash [yarn]
+yarn add three @tresjs/nuxt 
+```
+
+:::
+
+## Features
+
+- 🤓 Auto-import components and composables from the [TresJS ecosystem](https://github.com/orgs/Tresjs/repositories)
+- `TresCanvas` client only, you don't need to add `.client` to the component name or `<ClientOnly />`
+- Automatically configures vue compiler to support TresJS components, see [why](/guide/troubleshooting.html#failed-resolve-component-trescomponent-%F0%9F%A4%94)?
+- All the DX Magic that comes with Nuxt ✨
+
+## Usage
+
+ Add `@tresjs/nuxt` to the `modules` section of `nuxt.config.ts`
+
+```js
+export default defineNuxtConfig({
+  modules: ["@tresjs/nuxt"],
+});
+```
+
+That's it! You can now use `@tresjs/nuxt` in your Nuxt app ✨
+
+If you want to use the any package from the TresJS ecosystem, you can install the packages you want to use and they will be auto-imported by the module 🧙🏼‍♂️.
+
+| Package                     | Version                                                                                            |
+| --------------------------- | :------------------------------------------------------------------------------------------------- |
+| [Cientos](https://github.com/Tresjs/cientos) | ![cientos version](https://img.shields.io/npm/v/@tresjs/cientos/latest.svg?label=%20&color=%23f19b00) |
+| [Post-processing](https://github.com/Tresjs/post-processing) | ![post-processing version](https://img.shields.io/npm/v/@tresjs/post-processing/latest.svg?label=%20&color=ff69b4) |
+
+```bash
+# Using pnpm
+pnpm add @tresjs/cientos @tresjs/post-processing
+```

docs/es/guide/troubleshooting.md

@@ -0,0 +1,91 @@
+# The hilarious guide of common issues and how to solve them
+
+![Troubleshooting](https://media.giphy.com/media/LHZyixOnHwDDy/giphy.gif)
+
+Welcome to **TresJS v2 troubleshooting guide**. Where 3D stands for _"Dazzlingly Delightful Difficulties"_! We know 3D can be as complex as a tangled ball of yarn 🧶 or as unpredictable as a cat on a keyboard 🐈 ⌨️ , but fear not!
+
+This guide is intended to help you solve the most common issues that you might encounter when using TresJS v2.
+
+## I can't see my 3D scene 😭!
+
+You followed the [Getting started guide](/guide/getting-started.md) but you still can see your scene rendered.
+
+These are the most common reasons why you might not be able to see your scene:
+
+### Check the height of your canvas 📏
+
+Another common issue is that the `TresCanvas` component is creating by default a `canvas` element takes the `width` and `height` of the parent element. If the parent element has no height, the canvas will have no height either.
+
+![No height found](/canvas-height.png)
+
+You will also see this error in the console:
+
+![Canvas height warning](/canvas-height-warning.png)
+
+A easy way to fix this is to set the height of the parent element to `100%`:
+
+```css
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  width: 100%;
+}
+#app {
+  height: 100%;
+  width: 100%;
+  background-color: #000;
+}
+```
+
+Or you can set the `window-size` prop of the `TresCanvas` component:
+
+```vue
+<TresCanvas window-size>
+  <TresPerspectiveCamera />
+  <TresOrbitControls />
+</TresCanvas>
+```
+
+## Failed resolve component: TresComponent... 🤔
+
+![](/failed-to-resolve-component.png)
+
+Since **TresJS v2** is using a Vue Custom Renderer inside of the main Vue App instance, the core Vue renderer that acts as parent is not going to recognize the components inside of `TresCanvas` component. Even if it doesn't affect the rendering, it will show a warning in the console.
+
+![](/failed-to-resolve-component.png)
+
+At this moment, there is no native Vue support to define the renderer used on the `<template />` but there is a quick workaround to remove the warnings
+
+Got to your `vite.config.ts` and add the following configuration to the `@vitejs/plugin-vue`:
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { templateCompilerOptions } from '@tresjs/core'
+
+export default defineConfig({
+  plugins: [
+    vue({
+      // Other config
+      ...templateCompilerOptions,
+    }),
+  ],
+})
+```
+
+This will remove the warning from the console.
+
+# Help Us Make TresJS Purr-fect! 😼
+
+We know that even the best cat nappers occasionally make mistakes, and we need you help to make TresJS even better! If you find a bug, please open a ticket at [the
+repo](https://github.com/Tresjs/playground) and **please provide a reproduction link**.
+
+::: warning
+Tickets without a reproduction link will be closed.
+:::
+
+Our team of coding cat lovers
+will jump into action to squash those pesky bugs and improve TresJS for everyone. Together, let's make TresJS the cat's
+meow of 3D rendering in Vue!

docs/es/guide/your-first-scene.md

@@ -0,0 +1,173 @@
+# Your first scene
+
+This guide will help you to create your first Tres scene. 🍩
+
+<ClientOnly>
+<div style="aspect-ratio: 16/9; height: auto; margin: 2rem 0; border-radius: 8px; overflow:hidden;">
+  <DonutExample />
+</div>
+</ClientOnly>
+
+## Setting up the experience Canvas
+
+Before we can create a Scene, we need somewhere to display it. Using plain [ThreeJS](https://threejs.org/docs/index.html#manual/en/introduction/Creating-a-scene) we would need to create a `canvas` HTML element to mount the `WebglRenderer` and initialize the `scene`
+
+With **TresJS** you only need to import the default component `<TresCanvas />` and add it to the template of your Vue component.
+
+```vue
+<script lang="ts" setup>
+import { TresCanvas } from '@tresjs/core'
+</script>
+
+<template>
+  <TresCanvas window-size>
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+::: warning
+It's important that all components related to the scene live between the `<TresCanvas />` component. Otherwise, they will be not rendered.
+:::
+
+The `TresCanvas` component is going to do some setup work behind the scene:
+
+- It creates a [**WebGLRenderer**](https://threejs.org/docs/index.html?q=webglrend#api/en/renderers/WebGLRenderer) that automatically updates every frame.
+- It sets the render loop to be called on every frame based on the browser refresh rate.
+
+## Canvas size
+
+By default, `TresCanvas` component will take the **parent's width and height**, if you are experiencing a blank page make sure the parent element has a proper size.
+
+```vue
+<script lang="ts" setup>
+import { TresCanvas } from '@tresjs/core'
+</script>
+
+<template>
+  <TresCanvas>
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+
+<style>
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  width: 100%;
+}
+#app {
+  height: 100%;
+  width: 100%;
+}
+</style>
+```
+
+If your scene is not gonna be part of a UI, you can also force the canvas to take the width and height of the full window by using the `window-size` prop like this:
+
+```vue
+<script lang="ts" setup>
+import { TresCanvas } from '@tresjs/core'
+</script>
+
+<template>
+  <TresCanvas window-size>
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+## Creating a scene
+
+We need 4 core elements to create a 3D experience:
+
+- A [**Scene**](https://threejs.org/docs/index.html?q=scene#api/en/scenes/Scene) to hold the camera and the object(s) together.
+- A [**Renderer**](https://threejs.org/docs/index.html?q=renderer#api/en/renderers/WebGLRenderer) to render the scene into the DOM.
+- A [**Camera**](https://threejs.org/docs/index.html?q=camera#api/en/cameras/Camera)
+- An [**Object**](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D)
+
+With **TresJS** you only need to add the `<TresCanvas />` component to the template of your Vue component and it will automatically create a `Renderer` (`canvas` DOM Element) and `Scene` for you.
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+Then you can add a [**PerspectiveCamera**](https://threejs.org/docs/index.html?q=perspectivecamera#api/en/cameras/PerspectiveCamera) using the `<TresPerspectiveCamera />` component.
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <TresPerspectiveCamera />
+  </TresCanvas>
+</template>
+```
+
+::: warning
+A common issue is that the camera default position is the origin of the scene (0,0,0), TresJS will automatically set the position of your camera to `[3,3,3]` if the prop `position`. If no camera is defined in you scene, a perspective camera is added automatically.`
+:::
+
+## Adding a 🍩
+
+That scene looks a little empty, let's add a basic object. If we were using plain **ThreeJS** we would need to create a [**Mesh**](https://threejs.org/docs/index.html?q=mesh#api/en/objects/Mesh) object and attach to it a [**Material**](https://threejs.org/docs/index.html?q=material#api/en/materials/Material) and a [**Geometry**](https://threejs.org/docs/index.html?q=geometry#api/en/core/BufferGeometry) like this:
+
+```ts
+const geometry = new THREE.TorusGeometry(1, 0.5, 16, 32)
+const material = new THREE.MeshBasicMaterial({ color: 'orange' })
+const donut = new THREE.Mesh(geometry, material)
+scene.add(donut)
+```
+
+A **Mesh** is a basic scene object in three.js, and it's used to hold the geometry and the material needed to represent a shape in 3D space.
+
+Now let's see how we can easily achieve the same with **TresJS**. To do that we are going to use `<TresMesh />` component, and between the default slots, we are going to pass a `<TresTorusGeometry />` and a `<TresMeshBasicMaterial />`.
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <TresPerspectiveCamera />
+    <TresMesh>
+      <TresTorusGeometry :args="[1, 0.5, 16, 32]" />
+      <TresMeshBasicMaterial color="orange" />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+::: info
+Notice that we don't need to import anything, that's because **TresJS** automatically generate a **Vue Component based on the Three Object you want to use in CamelCase with a Tres prefix**. For example, if you want to use an `AmbientLight` you would use `<TresAmbientLight />` component.
+:::
+
+
+
+```vue
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+</script>
+
+<template>
+  <TresCanvas
+    clear-color="#82DBC5"
+    window-size
+  >
+    <TresPerspectiveCamera
+      :position="[3, 3, 3]"
+      :look-at="[0, 0, 0]"
+    />
+    <TresMesh>
+      <TresTorusGeometry :args="[1, 0.5, 16, 32]" />
+      <TresMeshBasicMaterial color="orange" />
+    </TresMesh>
+    <TresAmbientLight :intensity="1" />
+  </TresCanvas>
+</template>
+```
+
+From here onwards you can start adding more objects to your scene and start playing with the properties of the components to see how they affect the scene.
+
+<SandboxDemo url="https://play.tresjs.org/#eNqVVMtu2kAU/ZWRu8iiYIcQoojSikCjqlXTRi27OIuJfYGBeWlmzKOIf+8d2zhD2kZU8oI5955z3+yiiQF7o3W8KiDqRwObGaYdseAKTTiVs/dp5GwafUglE1oZR3bEU8ZUrqglezI1SpCzoUNsYZNMGTh7l8pBUgkhDR8OhObUAb4IGQT0jAM17UxxZTDOm+uLj6NxL43ImslcrduW/ao4NesejNWQObaCMRVgaGUjpK+VZY4piSoP3Rbx32MaNeapWqHlEqUbiCu1bFPnCect4r+GkIQx78DO63eNTJQp7CdQApzZkj41M+tVOigR91qkc4XBL1Cs0QmURtSy7A5bYRjl5FC4MthoCBiD5EXoUuBGPDGQ7iubzR3pM+lAYtVbFOg03IpZtReBQRL0PmpF1Qzbgup4YZXEie88K60NOOg+KRGPhUP1hjSaO6dtP0myXCI/B85WJpbgEqlFEroPu3EvPk9yZl3iYfROo9Yfwr4cVQY9VbtioPxVKF/Dx1HcGuhSU3lK7o3v8DI+jzu18gGMBfOcUHtu4CRd7zdExd415vsWrAjbgDdXWDi5v4H7sIO7hop4J7CJxXF3az87pwby/xCuCK9Jo2M7B8FOED24+uIv46uEs6dQ0ivuU7nHnXQ2U3LKZi82MlNCMw7mu/aHfbyZlHO1/lJizhTQ5JfNIVv+BV/YTZXyPS4LmBW2+3mUeMDgKvPtz2+wwd+NUai84PVw/mH8AVbxwudYuY0KmWPagV+Z7efywJicTeztprzcuqijRN1WQ4k+HP46ml2rgMeycaV/OY7xK116rqwbd5uG738DogXwDg==" />

docs/es/index.md

@@ -0,0 +1,35 @@
+---
+layout: home
+
+title: TresJS
+titleTemplate: La solución para 3D en VueJS
+
+hero:
+  name: TresJS
+  text: Lleva Three al ecosistema Vue
+  tagline: Crea increíbles experiencias 3D con el framework que amas.
+  image:
+    src: /hero.png
+    alt: Tresjs
+  actions:
+    - theme: brand
+      text: Empezar
+      link: /guia/
+    - theme: alt
+      text: ¿Por qué Tres?
+      link: /guia/#motivacion
+
+features:
+  - icon: 💡
+    title: Declarativo
+    details: Construye escenas 3D como si fueran componentes de Vue.
+  - icon: ⚡️
+    title: Potenciado por Vite
+    details: Reemplazo de módulo en caliente (HMR) que se mantiene rápido independientemente del tamaño de la aplicación.
+  - icon: 🥰
+    title: Siempre actualizado
+    details: Trae todas las características actualizadas de ThreeJS de inmediato.
+  - icon: 🌳
+    title: Ecosistema
+    details: Amplía la funcionalidad principal con paquetes como `cientos` y `postprocessing`. O agrega los tuyos propios.
+---