docs: polish tranlation

docs/.vitepress/config/index.ts

@@ -1,7 +1,8 @@
-import { defineConfig } from 'vitepress'
-import { enConfig } from './en'
-import { esConfig } from './es'
-import { sharedConfig } from './shared'
+import { defineConfig } from "vitepress";
+import { enConfig } from "./en";
+import { esConfig } from "./es";
+import { plConfig } from "./es";
+import { sharedConfig } from "./shared";
 
 /* import { zhConfig } from './zh' */
 
@@ -9,8 +10,9 @@ export default defineConfig({
   ...sharedConfig,
 
   locales: {
-    root: { label: 'English', lang: 'en-US', link: '/', ...enConfig },
-    es: { label: 'Español', lang: 'es-ES', link: '/es/', ...esConfig },
+    root: { label: "English", lang: "en-US", link: "/", ...enConfig },
+    es: { label: "Español", lang: "es-ES", link: "/es/", ...esConfig },
+    pl: { label: "Polish", lang: "pl-PL", link: "/pl/", ...plConfig },
     /* zh: { label: '简体中文', lang: 'zh-CN', link: '/zh/', ...zhConfig }, */
   },
-})
+});

docs/.vitepress/config/pl.ts

@@ -0,0 +1,153 @@
+import type { DefaultTheme, LocaleSpecificConfig } from "vitepress";
+
+export const plConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
+  themeConfig: {
+    editLink: {
+      pattern: "https://github.com/tresjs/tres/edit/main/packages/docs/:path",
+      text: "Zaproponuj zmiany na tej stronie",
+    },
+    sidebar: [
+      {
+        text: "Przewodnik",
+        items: [
+          // Esto muestra la página `/guide/index.md`.
+          { text: "Wstęp", link: "/pl/guide/" },
+          { text: "Pierwsze kroki", link: "/pl/guide/getting-started" },
+          { text: "Twoja pierwsza scena", link: "/pl/guide/your-first-scene" },
+          { text: "Nuxt", link: "/pl/guide/nuxt" },
+          {
+            text: "Rozwiązywanie problemów",
+            link: "/pl/guide/troubleshooting",
+          },
+          { text: "Migracja z v1", link: "/pl/guide/migration-guide" },
+        ],
+      },
+      {
+        text: "API",
+        items: [
+          { text: "TresCanvas", link: "/pl/api/tres-canvas" },
+          {
+            text: "Instancje, argumenty i właściwości",
+            link: "/pl/api/instances-arguments-and-props",
+          },
+          {
+            text: "Komponowalne",
+            link: "/pl/api/composables",
+          },
+          {
+            text: "Wydarzenia",
+            link: "/pl/api/events",
+          },
+        ],
+      },
+
+      {
+        text: "Zaawansowany",
+
+        items: [
+          { text: "Rozszerzanie", link: "/pl/advanced/extending" },
+          { text: "Prymitywny", link: "/pl/advanced/primitive" },
+          {
+            text: "Zastrzeżenia",
+            link: "/pl/advanced/caveats",
+          },
+        ],
+      },
+      {
+        text: "Znajdowanie",
+        items: [
+          { text: "Narzędzia deweloperskie", link: "/pl/debug/devtools" },
+        ],
+      },
+      {
+        text: "Przykłady",
+        collapsed: true,
+        items: [
+          { text: "Sterowanie orbitą", link: "/pl/examples/orbit-controls" },
+          {
+            text: "Podstawowe animacje",
+            link: "/pl/examples/basic-animations",
+          },
+          { text: "Grupy", link: "/pl/examples/groups" },
+          { text: "Ładowanie tekstur", link: "/pl/examples/load-textures" },
+          { text: "Ładowanie modelu", link: "/pl/examples/load-models" },
+          { text: "Ładowanie tekstu", link: "/pl/examples/text-3d" },
+          { text: "Światła i cienie", link: "/pl/examples/lights-shadows" },
+          { text: "Shadery", link: "/pl/examples/shaders" },
+        ],
+      },
+      {
+        text: "Dyrektywy",
+        collapsed: true,
+        items: [
+          { text: "v-log", link: "/pl/directives/v-log" },
+          { text: "v-light-helper", link: "/pl/directives/v-light-helper" },
+          { text: "v-always-look-at", link: "/pl/directives/v-always-look-at" },
+          { text: "v-distance-to", link: "/pl/directives/v-distance-to" },
+        ],
+      },
+      {
+        text: "Ekosystem",
+        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 (wkrótce)",
+          },
+        ],
+      },
+    ],
+    nav: [
+      { text: "Przewodnik", link: "/pl/guide/" },
+      { text: "API", link: "/pl/api/tres-canvas" },
+      /*       { text: 'API', link: '/pl/api/' },
+      { text: 'Konfiguracja', link: '/pl/config/' }, */
+      {
+        text: "Zasoby",
+        items: [
+          { text: "Zespół", link: "/pl/team" },
+          { text: "Wydania", link: "https://github.com/Tresjs/tres/releases" },
+          {
+            text: "Plac zabaw",
+            link: "https://playground.tresjs.org/",
+          },
+          {
+            text: "Github",
+            link: "https://github.com/Tresjs/tres/",
+          },
+          {
+            text: "Problemy",
+            link: "https://github.com/Tresjs/tres/issues",
+          },
+          {
+            text: "Ekosystem",
+            items: [
+              {
+                text: "Cientos 💛",
+                link: "https://cientos.tresjs.org/",
+              },
+              {
+                text: "Módulo Nuxt",
+                link: "https://github.com/Tresjs/nuxt",
+              },
+              {
+                text: "TresLeches 🍰",
+                link: "https://tresleches.tresjs.org/",
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+};

docs/guide/index.md

@@ -9,15 +9,15 @@
 ::: code-group
 
 ```bash [npm]
-npm install @tresjs/core three 
+npm install @tresjs/core three
 ```
 
 ```bash [yarn]
-yarn add @tresjs/core three 
+yarn add @tresjs/core three
 ```
 
 ```bash [pnpm]
-pnpm add @tresjs/core three 
+pnpm add @tresjs/core three
 ```
 
 :::
@@ -59,7 +59,7 @@ export default defineConfig({
 }),
 ```
 
-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).
+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](/es/guide/troubleshooting.html).
 
 ## Try it online
 
@@ -95,20 +95,19 @@ The only problem is, mixing compilers renderers in Vue 3 is something the Vue co
 
 ```ts
 // Example Vite setup
-import { createApp } from 'vue'
-import { createApp as createLunchboxApp } from 'lunchboxjs'
-import App from './App.vue'
-import LunchboxApp from './LunchboxApp.vue'
+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')
+const app = createApp(App);
+app.mount("#app");
 
 // lunchbox app
-const lunchboxApp = createLunchboxApp(LunchboxApp)
+const lunchboxApp = createLunchboxApp(LunchboxApp);
 // assuming there's an element with ID `lunchbox` in your HTML app
-lunchboxApp.mount('#lunchbox')
+lunchboxApp.mount("#lunchbox");
 ```
 
 So I was inspired by both libraries to create a Vue custom renderer for ThreeJS. That's **TresJS v2**.
-

docs/pl/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/pl/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/pl/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/pl/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 composables 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 composables 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 composable `useRenderLoop` para registrar un callback que se llamará cada vez que el renderizador actualice la escena.
+
+## useRenderLoop
+
+El composable `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 composable 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
+Ten en cuenta las implicaciones de rendimiento al usar este composable. Se ejecutará en cada fotograma, por lo que si tienes mucha lógica en tu callback, podría afectar el rendimiento de tu aplicación. Especialmente si estás actualizando estados o referencias reactivas.
+:::
+
+El callback `onLoop` recibe un objeto con las siguientes propiedades basadas en el [reloj de THREE](https://threejs.org/docs/?q=clock#api/en/core/Clock):
+
+- `delta`: El tiempo transcurrido entre el fotograma actual y el último fotograma. Este es el tiempo en segundos desde el último fotograma.
+- `elapsed`: El tiempo transcurrido desde el inicio del bucle de renderizado.
+
+Este composable se basa en `useRafFn` de [vueuse](https://vueuse.org/core/useRafFn/). Gracias a [@wheatjs](https://github.com/orgs/Tresjs/people/wheatjs) por la increíble contribución.
+
+### Antes y después de renderizar
+
+También puedes registrar un callback que se llamará antes y después de que el renderizador actualice la escena. Esto es útil si agregas un perfilador para medir los FPS, por ejemplo.
+
+```ts
+const { onBeforeLoop, onAfterLoop } = useRenderLoop()
+
+onBeforeLoop(({ delta, elapsed }) => {
+  // Se ejecutara antes del renderizado de la escena
+  fps.begin()
+})
+
+onAfterLoop(({ delta, elapsed }) => {
+  // Se ejecutara después del renderizado de la escena
+  fps.end()
+})
+```
+
+### Pausar y reanudar
+
+Puedes pausar y reanudar el bucle de renderizado utilizando los métodos `pause` y `resume` expuestos.
+
+```ts
+const { pause, resume } = useRenderLoop()
+
+// Pausa el bucle de renderizado
+pause()
+
+// Reanuda el bucle de renderizado
+resume()
+```
+
+También puedes obtener el estado activo del bucle de renderizado utilizando la propiedad `isActive`.
+
+```ts
+const { resume, isActive } = useRenderLoop()
+
+console.log(isActive) // false
+
+resume()
+
+console.log(isActive) // true
+```
+
+## useLoader
+
+El composable `useLoader` te permite cargar recursos utilizando los [cargadores de THREE.js](https://threejs.org/docs/#manual/en/introduction/Loading-3D-models). Retorna una promesa con el recurso cargado.
+
+```ts
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader'
+
+const { scene } = await useLoader(THREE.GLTFLoader, 'path/to/asset.gltf')
+```
+
+Dado que el composable `useLoader` devuelve una promesa, puedes usarlo con `async/await` o `then/catch`. Si lo estás utilizando en un componente, asegúrate de envolverlo con un componente `Suspense`. Consulta [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) para obtener más información.
+
+```vue
+<template>
+  <Suspense>
+    <TheComponentUsingLoader />
+  </Suspense>
+</template>
+```
+
+## useTexture
+
+El composable `useTexture` te permite cargar texturas utilizando el [cargador de texturas de THREE.js](https://threejs.org/docs/#api/en/loaders/TextureLoader). Retorna una promesa con la(s) textura(s) cargada(s).
+
+```ts
+const texture = await useTexture(['path/to/texture.png'])
+```
+
+**useTexture** también acepta un objeto con las siguientes propiedades:
+
+- `map`: una textura básica que se aplica a la superficie de un objeto
+- `displacementMap`: una textura que se utiliza para agregar protuberancias o indentaciones a la superficie del objeto
+- `normalMap`: una textura que se utiliza para agregar detalles de superficie y variaciones en el sombreado al objeto
+- `roughnessMap`: una textura que se utiliza para agregar rugosidad o un acabado mate a la superficie del objeto
+- `metalnessMap`: una textura que se utiliza para agregar un efecto metálico a la superficie del objeto
+- `aoMap`: una textura que se utiliza para agregar oclusión ambiental (sombreado en áreas donde la luz es bloqueada por otros objetos) al objeto.
+- `alphaMap`: una textura que se utiliza para agregar transparencia (la parte negra se renderiza como transparente) al objeto. Es necesario establecer :transparent="true" en el material para usar este mapa.
+- `matcap`: esta textura codifica el color y el sombreado del material.
+
+En ese caso, devolverá un objeto con las texturas cargadas.
+
+```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',
+})
+```
+
+Luego puedes vincular las texturas al 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 al composable anterior, el composable `useTexture` devuelve una promesa, puedes usarlo con `async/await` o `then/catch`. Si lo estás utilizando en un componente, asegúrate de envolverlo con un componente `Suspense`.
+
+## useSeek
+
+El composable `useSeek` proporciona utilidades para recorrer y navegar fácilmente a través de escenas y gráficos de objetos complejos de ThreeJS. Exporta 4 funciones que te permiten encontrar objetos secundarios basados en propiedades específicas.
+
+```ts
+const { seek, seekByName, seekAll, seekAllByName } = useSeek()
+```
+
+La función `seek` acepta tres parámetros:
+
+- `parent`: Una escena ThreeJS u Object3D.
+- `property`: La propiedad que se utilizará en la condición de búsqueda.
+- `value`: El valor de la propiedad a coincidir.
+
+La función `seek` y `seekByName` recorren el objeto y devuelven el objeto hijo con la propiedad y valor especificados. Si no se encuentra ningún hijo con la propiedad y valor dados, devuelve null y registra una advertencia.
+
+```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'))
+  }
+})
+```
+
+De manera similar, las funciones `seekAll` y `seekAllByName` devuelven un array de objetos secundarios cuya propiedad incluye el valor dado. Si no se encuentran coincidencias, devuelven un array vacío y se registra una advertencia.
+
+```ts
+const character = ref(null)
+
+watch(character, ({ model }) => {
+  if (model) {
+    const bones = seekAll(character, type, 'Bone')
+  }
+})
+```
+
+## useTresContext
+Este composable tiene como objetivo proporcionar acceso al modelo de estado que contiene múltiples propiedades útiles.
+
+```ts
+const { camera, renderer, camera, cameras } = useTresContext()
+
+```
+
+::: warning
+`useTresContext` solo puede ser utilizado dentro de un `TresCanvas`, ya que `TresCanvas` actúa como el proveedor de los datos de contexto. Utiliza [el contexto expuesto por TresCanvas](tres-canvas#propiedades-públicas-expuestas) si necesitas acceder a él en componentes superiores a TresCanvas.
+:::
+
+```vue
+<TresCanvas>
+  <MyModel />
+</TresCanvas>
+```
+
+```vue
+// MyModel.vue
+
+<script lang="ts" setup>
+import { useTresContext } from '@tresjs/core'
+
+const context = useTresContext()
+</script>
+```
+
+### Propiedades del contexto
+| Propiedad | Descripción |
+| --- | --- |
+| **camera** | la cámara actualmente activa |
+| **cameras** | las cámaras que existen en la escena |
+| **controls** | los controles de tu escena |
+| **deregisterCamera** | un método para cancelar el registro de una cámara. Esto solo es necesario si creas una cámara manualmente. Las cámaras en la plantilla se registran automáticamente. |
+| **extend** | Extiende el catálogo de componentes. Ver [extending](/advanced/extending) |
+| **raycaster** | el raycaster global utilizado para eventos de puntero |
+| **registerCamera** | un método para registrar una cámara. Esto solo es necesario si creas una cámara manualmente. Las cámaras en la plantilla se registran automáticamente. |
+| **renderer** | el [WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer) de tu escena |
+| **scene** | la [escena](https://threejs.org/docs/?q=sce#api/en/scenes/Scene) |
+| **setCameraActive** | un método para establecer una cámara activa |
+| **sizes** | contiene el ancho, alto y relación de aspecto de tu lienzo |
+

docs/pl/api/events.md

@@ -0,0 +1,27 @@
+# Events
+
+**TresJS** los componentes emiten eventos de puntero cuando se interactúa con ellos. Esto es válido para los componentes que representan clases de three.js que derivan de [THREE.Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) (como mallas, grupos, ...).
+
+<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         | se dispara cuando ...                                                                 | Tipo(s) de parámetro del controlador de eventos                                                                                                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| click         | ... los eventos pointerdown y pointerup se disparan en el mismo objeto uno tras otro | [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16), [PointerEvent](https://developer.mozilla.org/es/docs/Web/API/PointerEvent) |
+| pointer-move  | ... el puntero se mueve sobre el objeto                                               | [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16), [PointerEvent](https://developer.mozilla.org/es/docs/Web/API/PointerEvent) |
+| pointer-enter | ... el puntero entra en el objeto                                                     | [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16), [PointerEvent](https://developer.mozilla.org/es/docs/Web/API/PointerEvent) |
+| pointer-leave | ... el puntero sale del objeto                                                        | [PointerEvent](https://developer.mozilla.org/es/docs/Web/API/PointerEvent)                                                                                                                         |
+
+La [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16) devuelta incluye el [Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) que desencadenó el evento. Puedes acceder a él a través de `intersection.object`.
+
+De forma predeterminada, los objetos posicionados delante de otros con controladores de eventos no evitan que se disparen esos eventos. Este comportamiento se puede lograr utilizando la propiedad `blocks-pointer-events`.

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

@@ -0,0 +1,150 @@
+# Instancias
+
+La idea principal de **Tres** es un _catálogo autogenerado_ de todos los elementos de ThreeJS. Este catálogo se genera a partir del código fuente de ThreeJS, por lo que siempre está actualizado.
+
+Cuando usas ThreeJS, necesitas importar los elementos que deseas utilizar. Por ejemplo, si quieres usar una `PerspectiveCamera`, necesitas importarla desde el paquete `three`:
+
+```js
+import { PerspectiveCamera } from 'three'
+
+const camera = new PerspectiveCamera(45, width / height, 1, 1000)
+```
+
+Con **Tres** no necesitas importar nada, esto se debe a que **Tres** genera automáticamente un **Componente Vue basado en el objeto Three que deseas usar en CamelCase con un prefijo Tres**. Por ejemplo, si quieres usar una `PerspectiveCamera`, puedes usar el componente `<TresPerspectiveCamera />`.
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera />
+    <!-- Tu escena vive aqui -->
+  </TresCanvas>
+</template>
+```
+
+Esto significa que puedes utilizar la misma [documentación](https://threejs.org/docs/) que usarías al utilizar ThreeJS básico, pero con el poder de Vue.
+
+## Declarando objetos
+
+Si seguimos este argumento, deberías poder definir una instancia de esta manera: ❌
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera
+      visible
+      :position="new THREE.Vector3(1, 2, 3)"
+    />
+    <!-- Tu escena vive aqui -->
+  </TresCanvas>
+</template>
+```
+
+Pero con **Tres** esto no es necesario, puedes definir las propiedades de forma declarativa de la siguiente manera: ✅
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera
+      visible
+      :position="[1, 2, 3]"
+    />
+    <!-- Tu escena vive aqui -->
+  </TresCanvas>
+</template>
+```
+
+## Argumentos
+
+Algunos objetos de ThreeJS tienen argumentos, por ejemplo, el constructor `PerspectiveCamera` tiene los siguientes argumentos:
+
+- `fov` - Campo de visión vertical de la cámara.
+- `aspect` - Relación de aspecto del frustum de la cámara.
+- `near` - Plano cercano del frustum de la cámara.
+- `far` - Plano lejano del frustum de la cámara.
+
+Para pasar estos argumentos al componente `TresPerspectiveCamera`, puedes usar la propiedad `args`:
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
+    <!-- Tu escena vive aqui -->
+  </TresCanvas>
+</template>
+```
+
+Esto es lo mismo que hacer esto:
+
+```ts
+const camera = new PerspectiveCamera(45, 1, 0.1, 1000)
+```
+
+## Propiedades
+
+También puedes pasar propiedades al componente, por ejemplo, el `TresAmbientLight` tiene una propiedad `intensity`, por lo que puedes pasarla al componente de la siguiente manera:
+
+```html
+<TresAmbientLight :intensity="0.5" />
+```
+
+### Establecer
+
+Todas las propiedades cuyo objeto subyacente tiene un método `.set()` tienen un atajo para recibir el valor como un array. Por ejemplo, el `TresPerspectiveCamera` tiene una propiedad `position`, que es un objeto `Vector3`, por lo que puedes pasarlo al componente de esta manera:
+
+```html
+<TresPerspectiveCamera :position="[1, 2, 3]" />
+```
+
+Para especificar propiedades de transformación como posición, rotación y escala, hay una forma abreviada disponible que te permite indicar directamente el eje que deseas establecer dentro de las propiedades. Una forma abreviada similar también está disponible para la propiedad de color.
+
+<!-- Cambié la sintaxis de color de Vue a HTML, porque Vue parece estar roto y no colorea los componentes anidados -->
+```html
+<TresMesh :position-x="1" :scale-y="2" :rotation-x="Math.PI * 2">
+  <TresMeshBasicMaterial :color-r="0.7" :color-b="0.3" />
+</TresMesh>
+```
+
+::: warning
+Cuando estableces la propiedad de rotación en [three.js](https://threejs.org/docs/index.html#api/en/math/Euler), se utilizará el orden 'XYZ' de forma predeterminada.
+Es importante tener en cuenta que al establecer la propiedad de rotación con la forma abreviada, el orden en el que estableces los ángulos importa. Para obtener más información sobre este tema, consulta [Ángulos de Euler](https://es.wikipedia.org/wiki/%C3%81ngulos_de_Euler)
+:::
+
+```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" />
+
+<!-- Ten en cuenta que el orden de las propiedades de rotación importa y cambiar el orden puede dar lugar a resultados diferentes. -->
+```
+
+### Escalar
+
+Otro atajo que puedes usar es pasar un valor escalar a una propiedad que espera un objeto `Vector3`, usando el mismo valor para el resto del vector:
+
+```html
+<TresPerspectiveCamera :position="5" /> ✅
+```
+
+```html
+<TresPerspectiveCamera :position="[5, 5, 5]" /> ✅
+```
+
+### Colores
+
+Puedes pasar colores a los componentes usando la propiedad `color`, la cual acepta un string con el nombre del color o un valor hexadecimal:
+
+```html
+<TresAmbientLight color="teal" /> ✅
+```
+
+```html
+<TresAmbientLight color="#008080" /> ✅
+```
+
+### Métodos
+
+Algunas propiedades subyacentes son en realidad métodos, el `TresPerspectiveCamera` tiene un método `lookAt` heredado de [Object3d](https://threejs.org/docs/#api/en/core/Object3D.lookAt), por lo que puedes pasarle las coordenadas al componente de esta manera:
+
+```html
+<TresPerspectiveCamera :look-at="[1, 2, 3]" />
+```

docs/pl/api/tres-canvas.md

@@ -0,0 +1,105 @@
+# TresCanvas
+
+El componente `TresCanvas` es el componente principal de Tres. Es el que crea el `WebGLRenderer` de ThreeJS.
+
+```vue{2,5}
+<template>
+  <TresCanvas shadows :output-encoding="SRGBColorSpace">
+    <TresPerspectiveCamera />
+      <!-- Tu escena vive aqui -->
+  </TresCanvas>
+</template>
+```
+
+## Tamaño del lienzo
+
+El componente `TresCanvas` utilizará el tamaño del elemento padre como tamaño del lienzo. Si deseas utilizar el tamaño de la ventana como tamaño del lienzo, puedes establecer la propiedad `window-size` en `true`.
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <!-- Tu escena vive aqui -->
+  </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 viene con algunos presets para el componente `TresCanvas`. Puedes usarlos estableciendo la propiedad `preset`.
+
+### Realista
+
+El preset `realista` facilita la configuración del renderizador para escenas 3D más realistas.
+
+```vue
+<template>
+  <TresCanvas preset="realistic">
+    <!-- Tu escena vive aqui -->
+  </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 | Descripción | Valor por defecto |
+| ---- | ---- | --- |
+| **alpha** | Controla el valor alfa predeterminado. Cuando se establece en true, el valor es 0. De lo contrario, es 1. | false |
+| **antialias** | Indica si se debe realizar el antialiasing. | `true` |
+| **camera** | Una cámara manual que se utilizará por el renderizador. | |
+| **clearColor** | El color que el renderizador utilizará para borrar el lienzo. | `#000000` |
+| **context** | Esto se puede usar para adjuntar el renderizador a un [RenderingContext](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext) existente. | |
+| **depth** | Indica si el búfer de dibujo tiene un [búfer de profundidad](https://en.wikipedia.org/wiki/Z-buffering) de al menos 16 bits. | `true` |
+| **disableRender** | Desactiva el renderizado en requestAnimationFrame, útil para PostProcessing. | `false` |
+| **failIfMajorPerformanceCaveat** | Indica si la creación del renderizador fallará si se detecta un bajo rendimiento. Consulta la [especificación de WebGL](https://registry.khronos.org/webgl/specs/latest/1.0/#5.2) para más detalles. | `false` |
+| **logarithmicDepthBuffer** | Indica si se debe utilizar un búfer de profundidad logarítmico. Puede ser necesario utilizar esto si se manejan diferencias enormes de escala en una sola escena. Ten en cuenta que esta configuración utiliza gl_FragDepth si está disponible, lo cual deshabilita la optimización [Early Fragment Test](https://www.khronos.org/opengl/wiki/Early_Fragment_Test) y puede causar una disminución en el rendimiento. | `false` |
+| **outputColorSpace** | Define la codificación de salida. | `LinearEncoding` |
+| **powerPreference** | Proporciona una sugerencia al agente de usuario que indica qué configuración de GPU es adecuada para este contexto WebGL. Puede ser "high-performance", "low-power" o "default". | `default` |
+| **precision** | Precisión del shader. Puede ser "highp", "mediump" o "lowp". | "highp" si es compatible con el dispositivo |
+| **premultipliedAlpha** | Indica si el renderizador asumirá que los colores tienen [alfa premultiplicado](https://en.wikipedia.org/wiki/Glossary_of_computer_graphics#premultiplied_alpha). | `true` |
+| **preserveDrawingBuffer** | Indica si se deben preservar los búferes hasta que se borren o se sobrescriban manualmente. | `false` |
+| **shadows** | Habilita las sombras en el renderizador. | `false` |
+| **shadowMapType** | Establece el tipo de mapa de sombras. | `PCFSoftShadowMap` |
+| **stencil** | Indica si el búfer de dibujo tiene un [búfer de stencil](https://en.wikipedia.org/wiki/Stencil_buffer) de al menos 8 bits. | `true` |
+| **toneMapping** | Define la exposición de mapeo de tonos utilizada por el renderizador. | `NoToneMapping` |
+| **toneMappingExposure** | Nivel de exposición del mapeo de tonos. | `1` |
+| **useLegacyLights** | Indica si se debe utilizar el modo de iluminación heredado o no. | `true` |
+| **windowSize** | Indica si se debe utilizar el tamaño de la ventana como el tamaño del lienzo o el elemento padre. | `false` |
+
+### Valores predeterminados
+
+Tres intenta ser lo menos opinado posible. Es por eso que no establece casi ningún valor predeterminado para el componente `TresCanvas`. Utiliza los valores predeterminados de [three.js](https://threejs.org/). La única excepción es la propiedad `antialias`, que se establece en `true` de forma predeterminada.
+
+## Propiedades públicas expuestas
+
+| Propiedad | Descripción |
+| ---- | ---- |
+| context | ver [useTresContext](composables#usetrescontext) |
+

docs/pl/debug/devtools.md

@@ -0,0 +1,26 @@
+# Herramientas de desarrollo
+
+Una de las cosas más difíciles a las que se enfrenta un desarrollador al crear experiencias 3D en el navegador es la depuración. El `canvas` del navegador es una caja negra y es difícil saber qué está sucediendo en su interior. La naturaleza imperativa de [ThreeJS](https://threejs.org/) hace que sea increíblemente difícil depurar, teniendo que depender de `console.log` para ver qué está sucediendo, o de terceros para ajustar y inspeccionar la escena.
+
+No me hagas empezar con la comprobación del rendimiento de tu escena. 😱
+
+![desarrollador depurando 3D](/debug-3D.png)
+
+Uno de nuestros objetivos con TresJS es ofrecer **la mejor experiencia de desarrollo (DX, por sus siglas en inglés)** al trabajar con escenas 3D en el navegador. Gracias a la naturaleza declarativa del ecosistema y a la variedad de soluciones que ofrece el ecosistema de Vue, como Vue Devtools, Nuxt y Vite, podemos ofrecer mejores herramientas para que los desarrolladores depuren sus escenas.
+
+## Presentando las Herramientas de Desarrollo
+
+A partir de la versión <Badge text="^3.7.0" />, estamos introduciendo las Herramientas de Desarrollo de TresJS, una pestaña de inspector personalizada para las [Herramientas de Desarrollo de Chrome oficiales de Vue](https://devtools.vuejs.org/guide/installation.html) que te permite inspeccionar tus escenas y componentes de TresJS.
+
+![Herramientas de Desarrollo de TresJS](/vue-chrome-devtools.png)
+
+### Características
+
+- **Inspector de Escena**: Inspecciona la escena actual y sus componentes utilizando una vista en árbol similar al inspector de componentes de Vue Devtools.
+- **Asignación de Memoria**: Muestra cuánta memoria está utilizando cada componente.
+- **Inspector de Objetos**: Inspecciona las propiedades del objeto seleccionado en la escena, incluidos sus hijos.
+- **Propiedades Editables**: Y sí, puedes editar las propiedades del objeto seleccionado y ver los cambios en tiempo real.
+
+![](/devtools-scene-inspector.png)
+
+¡Disfruta de las nuevas Herramientas de Desarrollo y dinos qué opinas! 🎉

docs/pl/examples/basic-animations.md

@@ -0,0 +1,89 @@
+# Basic Animations
+
+Esta guía te ayudará a comenzar con animaciones básicas en TresJS.
+
+Construiremos una escena simple con un cubo. Luego animaremos el cubo para que rote alrededor del eje Y y Z.
+
+<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
+
+El composable `useRenderLoop` es el núcleo de las animaciones en TresJS. Te permite registrar una función de devolución de llamada que se ejecutará cada vez que el renderizador actualice la escena con la frecuencia de actualización del navegador.
+
+Para obtener una explicación detallada de cómo funciona, consulta la documentación de [useRenderLoop](/api/composables#userenderloop).
+
+```ts
+const { onLoop } = useRenderLoop()
+
+onLoop(({ delta, elapsed }) => {
+  // Se ejecutará en cada fotograma ~ 60FPS (dependiendo de tu monitor)
+})
+```
+
+## Obteniendo la referencia al cubo
+
+Para animar el cubo, necesitamos obtener una referencia a él. Podemos hacerlo pasando una [Referencia de Plantilla](https://vuejs.org/guide/essentials/template-refs.html) utilizando la propiedad `ref` en el componente `TresMesh`. Esto nos devolverá la instancia de THREE.
+
+Para mejorar el rendimiento, utilizaremos una [Referencia Superficial](https://v3.vuejs.org/guide/reactivity-fundamentals.html#shallow-reactivity) para almacenar la referencia en lugar de una referencia regular. Puedes ver por qué [aquí](../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>
+```
+
+## Animando el cubo
+
+Ahora que tenemos una referencia al cubo, podemos animarlo. Utilizaremos la devolución de llamada `onLoop` para actualizar la rotación del cubo.
+
+```ts
+onLoop(({ delta, elapsed }) => {
+  if (boxRef.value) {
+    boxRef.value.rotation.y += delta
+    boxRef.value.rotation.z = elapsed * 0.2
+  }
+})
+```
+
+También puedes usar el `delta` del [reloj interno de THREE](https://threejs.org/docs/?q=clock#api/en/core/Clock) o el `elapsed` para animar el cubo.
+
+## ¿Pero por qué no usar la reactividad?
+
+Es posible que te preguntes por qué no estamos usando la reactividad para animar el cubo. La respuesta es simple: rendimiento.
+
+```vue
+// Esto es una mala 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>
+```
+
+Podemos sentirnos tentados a usar la reactividad para animar el cubo. Pero sería una mala idea.
+La razón es que [la reactividad de Vue se basa en Proxies](https://vuejs.org/guide/extras/reactivity-in-depth.html#how-reactivity-works-in-vue) y no está diseñada para ser utilizada en un bucle de renderizado que se actualiza 60 o más veces por segundo.
+
+La página incrustada a continuación muestra la [prueba de rendimiento de un proxy frente a un objeto regular](https://measurethat.net/Benchmarks/Show/12503/0/object-vs-proxy-vs-proxy-setter). Como puedes ver, el proxy es 5 veces más lento que el objeto regular.
+
+<EmbedExperiment src="https://measurethat.net/Embed?id=399142" />
+
+Puedes leer más sobre esto en la sección de [Caveats](../advanced/caveats.md#reactivity).

docs/pl/examples/groups.md

@@ -0,0 +1,32 @@
+# Grupo
+
+Un `<TresGroup>` es una instancia de la clase [THREE.Group](https://threejs.org/docs/#api/en/objects/Group) que es casi lo mismo que un [THREE.Object3D](https://threejs.org/docs/#api/en/objects/Object3D) pero te permite **agrupar varios objetos en la escena** para que puedan ser manipulados como una unidad única (transformación, rotación, etc).
+
+## Uso
+
+```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/pl/examples/lights-shadows.md

@@ -0,0 +1,175 @@
+# Luces y sombras
+
+Esta guía te ayudará a comenzar con luces y sombras simples en TresJS.
+
+Construiremos una escena simple con tres mallas y un plano, pero solo dos tendrán sombras.
+
+<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==" />
+
+## Configurando la escena (opcional)
+
+Importamos todos los módulos que necesitamos, para mayor comodidad podemos usar orbit-controls de cientos,
+[ver aquí para saber cómo](/examples/orbit-controls).
+
+Coloquemos cuatro objetos en nuestra escena, uno será el plano que recibirá sombras, dos de ellos proyectarán sombras y el último no proyectará ninguna sombra en absoluto.
+
+Voy a usar [MeshToonMaterial](https://threejs.org/docs/index.html?q=toon#api/en/materials/MeshToonMaterial). Simplemente porque podemos ver fácilmente el "sobreado suave".
+
+```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>
+```
+
+## Luces (explicación)
+
+Como sabes, cada instancia en [ThreeJs](https://threejs.org/) está disponible en **TresJs**, por lo que todos los tipos de luces también están disponibles, solo necesitamos agregar el prefijo `Tres` para usarlos.
+
+Pero no todas las luces pueden generar sombras, esta definición proviene directamente de ThreeJs y tiene sentido. Por ejemplo, el propósito de una [ambientLight](https://threejs.org/docs/index.html?q=ambient#api/en/lights/AmbientLight) es iluminar todos los lados de tu escena, por lo que no tiene sentido que genere sombras. En cambio, una [DirectionalLight](https://threejs.org/docs/index.html?q=light#api/en/helpers/DirectionalLightHelper) que imita al sol puede y debe generar sombras.
+
+## Sombras (explicación)
+
+También existen muchos tipos de sombras, por ejemplo, la "sombra suave" se genera automáticamente cuando un objeto recibe más luz de un lado, pero en resumen, una "sombra predeterminada de ThreeJS" que se dirige hacia otra superficie debe ser proyectada por una malla y otra malla debe recibirla. Como vemos en nuestro ejemplo, el `Plano` está recibiendo una sombra pero no la está proyectando. Ten en cuenta que no todos los materiales pueden proyectar o recibir sombras.
+
+Internamente, ThreeJS genera automáticamente una nueva malla con un [ShadowMaterial](https://threejs.org/docs/index.html?q=shado#api/en/materials/ShadowMaterial) que se actualiza en cada fotograma, por eso si aplicas animaciones, la sombra también se anima, pero también es por eso que debes usar las sombras con cuidado, ya que pueden ralentizar el rendimiento.
+
+::: warning
+El uso excesivo de sombras de esta manera puede afectar el rendimiento. Sin embargo, existen formas de mejorar el rendimiento. Para obtener más información, consulta [este video](https://youtu.be/WGNvVGrS0kY?si=q7XyL5eABKUh3gbS&t=1256)
+:::
+
+## Habilitando las sombras
+
+Podemos dividir esto en tres pasos:
+
+### Activar las sombras en el renderizador
+
+```vue
+//...
+
+<template>
+  <TresCanvas
+    clear-color="#111"
+    shadows
+    window-size
+  />
+  //...
+</template>
+```
+### Configurar la luz para proyectar sombras
+
+Podemos simplemente agregar el booleano `cast-shadow`, Vue lo interpreta como una `prop` con valor `true`.
+
+_La luz ambiental no genera ningún tipo de sombra aquí_
+
+```vue
+//...
+
+<template>
+  <TresAmbientLight :intensity="1" />
+  <TresDirectionalLight
+    cast-shadow
+    :position="[0, 2, 0]"
+    :intensity="1"
+  />
+  
+  //...
+</template>
+```
+### Establecer los objetos para proyectar o recibir sombras
+
+De manera similar al paso anterior, configuramos la malla que queremos que proyecte sombra (nuestra esfera) con la propiedad `cast-shadow`, y configuramos el objeto para recibir sombra (nuestro plano) con la propiedad `receive-shadow`.
+
+```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>
+```
+
+Ahora tenemos todos los pasos necesarios para agregar sombras a nuestra escena, y si aplicamos lo que aprendimos en [animaciones básicas](/examples/basic-animations), y agregamos movimiento a nuestro cubo, verás que la sombra también se anima 🤩
+
+```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>
+```
+
+_Nota que intencionalmente no apliqué `cast-shadow` al `Cone` para que no proyecte ninguna sombra_

docs/pl/examples/load-models.md

@@ -0,0 +1,140 @@
+# Cargar Modelos
+
+> Todos los modelos utilizados en esta guía son de [Alvaro Saburido](https://sketchfab.com/3d-models/aku-aku-7dfcb6edf10b4098bbb965c56fd3055c).
+
+Los modelos 3D están disponibles en cientos de formatos de archivo, cada uno con diferentes propósitos, características variadas y complejidad variable.
+
+Para esta guía, nos vamos a centrar en cargar modelos gLTF (GL Transmission Format), que son el formato más común para modelos 3D en la 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==" />
+
+Hay varias formas de cargar modelos en TresJS:
+
+::: warning
+Por favor, ten en cuenta que en los ejemplos anteriores utilizamos el await de nivel superior, asegúrate de envolverlo con un componente [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense). Consulta Suspense para obtener más información.
+:::
+
+## Usando `useLoader`
+
+El composable `useLoader` te permite pasar cualquier tipo de cargador de three.js y una URL para cargar el recurso. Devuelve una `Promise` con el recurso cargado.
+
+Para obtener una explicación detallada de cómo usar `useLoader`, consulta la documentación de [useLoader](/api/composables#useloader).
+
+```ts
+import { useLoader } from '@tresjs/core'
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader'
+
+const { scene } = await useLoader(GLTFLoader, '/models/AkuAku.gltf')
+```
+
+Luego puedes pasar la escena del modelo a un componente [`primitive`](/advanced/primitive) de TresJS para renderizarlo:
+
+```html{2}
+<TresCanvas>
+    <primitive :object="scene" />
+</TresCanvas>
+```
+
+> El componente `<primitive />` no es un componente independiente en el código fuente de Tres. En su lugar, es parte de la funcionalidad principal de Tres. Cuando usas `<primitive>`, se traduce a una llamada a `createElement`, que crea el objeto three.js adecuado según la propiedad "object" proporcionada.
+
+Observa en el ejemplo anterior que estamos utilizando el componente `Suspense` para envolver el componente `TresCanvas`. Esto se debe a que `useLoader` devuelve una `Promise` y necesitamos esperar a que se resuelva antes de renderizar la escena.
+
+## Usando `useGLTF`
+
+Una forma más conveniente de cargar modelos es utilizando el composable `useGLTF` disponible en el paquete [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos).
+
+```ts
+import { useGLTF } from '@tresjs/cientos'
+
+const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf')
+```
+
+Una ventaja de usar `useGLTF` es que puedes pasar una propiedad `draco` para habilitar la [compresión Draco](https://threejs.org/docs/index.html?q=drac#examples/en/loaders/DRACOLoader) para el modelo. Esto reducirá el tamaño del modelo y mejorará el rendimiento.
+
+```ts
+import { useGLTF } from '@tresjs/cientos'
+
+const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf', { draco: true })
+```
+
+Alternativamente, puedes seleccionar fácilmente objetos dentro del modelo utilizando la propiedad `nodes`.
+
+```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>
+```
+
+## Usando `GLTFModel`
+
+El componente `GLTFModel` es un envoltorio alrededor de `useGLTF` que está disponible en el paquete [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos).
+
+```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>
+```
+
+Este enfoque en particular es más sencillo pero te brinda menos control sobre el modelo.
+
+## useFBX
+
+El composable `useFBX` está disponible en el paquete [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos).
+
+```ts
+import { useFBX } from '@tresjs/cientos'
+
+const model = await useFBX('/models/AkuAku.fbx')
+```
+
+Entonces, es tan sencillo como agregar la escena a tu escena:
+
+```html{2}
+<TresCanvas shadows alpha>
+    <primitive :object="scene" />
+</TresCanvas>
+```
+
+## FBXModel
+
+El componente `FBXModel` es un envoltorio alrededor de `useFBX` que está disponible en el paquete [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos). Su uso es similar al de `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/pl/examples/load-textures.md

@@ -0,0 +1,78 @@
+# Cargar Texturas
+
+> Todas las texturas utilizadas en este ejemplo son de [ambientcg](https://ambientcg.com/).
+
+Las texturas tridimensionales (3D) son imágenes que contienen múltiples capas de datos, lo que les permite representar volumen o simular estructuras tridimensionales. Estas texturas se utilizan comúnmente en gráficos 3D y efectos visuales para mejorar el realismo y la complejidad de escenas y objetos.
+
+<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==" />
+
+Hay dos formas de cargar texturas 3D en TresJS:
+
+## Usando `useLoader`
+
+El composable `useLoader` te permite pasar cualquier tipo de cargador de three.js y una URL para cargar el recurso. Retorna una `Promise` con el recurso cargado.
+
+Para obtener una explicación detallada de cómo usar `useLoader`, consulta la documentación de [useLoader](/api/composables#use-loader).
+
+```ts
+import { useLoader } from '@tresjs/core'
+import { TextureLoader } from 'three'
+
+const texture = useLoader(TextureLoader, '/Rock035_2K_Color.jpg')
+```
+
+Luego puedes pasar la textura a un material:
+
+```html
+<Suspense>
+  <TresCanvas>
+    <TresMesh>
+      <TresSphereGeometry :args="[1,32,32]" />
+      <TresMeshStandardMaterial :map="texture" />
+    </TresMesh>
+  </TresCanvas>
+</Suspense>
+```
+
+Observa en el ejemplo anterior que estamos utilizando el componente `Suspense` para envolver el componente `TresCanvas`. Esto se debe a que `useLoader` devuelve una `Promise` y necesitamos esperar a que se resuelva antes de renderizar la escena.
+
+## Usando `useTexture`
+
+Una forma más conveniente de cargar texturas es utilizando el composable `useTexture`. Acepta tanto un array de URLs como un objeto único con los caminos de las texturas mapeadas.
+
+Para obtener más información sobre `useTexture`, consulta la documentación de [useTexture](/api/composables#use-texture).
+
+```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:
+
+Al igual que en el ejemplo anterior, podemos pasar todas las texturas a un material a través de 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/pl/examples/orbit-controls.md

@@ -0,0 +1,104 @@
+# 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) es un controlador de cámara que te permite orbitar alrededor de un objetivo. Es una excelente manera de explorar tu escena.
+
+Sin embargo, no forma parte del núcleo de ThreeJS. Por lo tanto, para usarlo, necesitarías importarlo desde el módulo `three/addons/controls/OrbitControls`.
+
+Esto crea un problema porque **TresJS** crea automáticamente un catálogo del núcleo de Three para que puedas usarlos como componentes.
+
+Afortunadamente, **TresJS** proporciona una forma de ampliar el catálogo de componentes. Puedes hacerlo utilizando el método `extend` de la biblioteca principal.
+
+Para obtener más información sobre cómo ampliar tu catálogo de TresJS, consulta la sección de [extensión](/advanced/extending.md).
+
+## Uso de OrbitControls
+
+Para usar `OrbitControls`, debes importarlo desde el módulo `three/addons/controls/OrbitControls`.
+
+```js
+import { OrbitControls } from 'three/addons/controls/OrbitControls'
+```
+
+Luego, necesitas ampliar el catálogo de componentes utilizando el método `extend`.
+
+```js
+import { extend } from '@tresjs/core'
+import { OrbitControls } from 'three/addons/controls/OrbitControls'
+
+extend({ OrbitControls })
+```
+
+Ahora puedes usar el componente `TresOrbitControls` en tu escena.
+
+```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>
+```
+
+Dado que [OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) necesita una referencia a la cámara y al renderizador, debes pasarlos como argumentos.
+
+Puedes usar el composable [useTres](/api/composables#usetres) para obtener la cámara y el renderizador.
+
+
+```ts
+import { useTres } from '@tresjs/core'
+
+const { state } = useTres()
+```
+
+Entonces, el código final sería algo como esto:
+
+```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 de `cientos`
+
+Aquí es donde comienza la parte interesante. ✨  
+El paquete `cientos` proporciona un componente llamado `<OrbitControls />` que es un envoltorio de los `OrbitControls` del módulo [`three-stdlib`](https://github.com/pmndrs/three-stdlib).
+
+¿Lo mejor? No necesitas ampliar el catálogo ni pasar ningún argumento.  
+Simplemente funciona. 💯
+
+```vue
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
+    <OrbitControls />
+  </TresCanvas>
+</template>
+```

docs/pl/examples/shaders.md

@@ -0,0 +1,174 @@
+# Shaders
+
+Esta guía te ayudará a comenzar con los shaders en TresJS.
+
+Construiremos una escena simple con un blob. Luego alo animaremos para distorsionarlo suavemente.
+
+::: warning
+_Es necesario tener conocimientos básicos sobre cómo funcionan los shaders_
+:::
+
+<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==" />
+
+## Configurando la escena (opcional)
+
+Importamos todos los módulos que necesitamos. Para mayor comodidad, podemos usar los orbit-controls de cientos.
+[Consulta aquí para ver cómo](/examples/orbit-controls).
+
+Ahora, coloquemos nuestra cámara en la posición `[11,11,11]`.
+
+Por último, para ayudarnos con la ubicación, agreguemos un plano simple, rotado en el eje X, con una medida de `[10, 10]` unidades.
+
+```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
+
+Como sabes, cada instancia en [ThreeJs](https://threejs.org/) está disponible en **TresJs**, por lo que también podemos usar el `ShaderMaterial`, solo necesitamos agregar el prefijo `Tres` para utilizarlo.
+
+Para nuestro blob, podríamos usar una simple `SphereGeometry` agregando algunos `widthSegments` y `heightSegments` para crear un efecto suave, y colocar nuestro blob 4 unidades en el eje Y positivo.
+
+```vue
+<TresMesh :position="[0, 4, 0]">
+  <TresSphereGeometry :args="[2, 32, 32]" />
+  <TresShaderMaterial />
+</TresMesh>
+```
+
+El `ShaderMaterial` acepta propiedades especiales, como `uniforms`, `vertexShader` y `fragmentShader`, por lo que podemos crearlo en nuestra sección de script y hacer la conexión con nuestra instancia.
+
+Para este ejemplo, nuestros uniforms se ven así:
+
+```ts
+import { Vector2 } from 'three'
+
+//...
+const uniforms = {
+  uTime: { value: 0 },
+  uAmplitude: { value: new Vector2(0.1, 0.1) },
+  uFrequency: { value: new Vector2(20, 5) },
+}
+//..
+```
+
+Nuestro fragment shader se ve así:
+
+```ts
+//...
+const fragmentShader = `
+precision mediump float;
+varying vec2 vUv;
+
+void main() {
+    gl_FragColor = vec4(1.0, vUv.y, 0.5, 1.0);
+}
+`
+//..
+```
+
+Y finalmente nuestro `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;
+}
+`
+//..
+```
+
+## Animando el blob
+
+Similar a lo que aprendimos en el ejemplo de [Animaciones básicas](/examples/basic-animations), comenzamos haciendo referencia a nuestro blob utilizando [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>
+```
+Una vez que hayamos hecho eso, podemos usar el callback `onLoop` para animar nuestro `uTime`.
+
+ ```ts
+import { TresCanvas, useRenderLoop } from '@tresjs/core'
+ 
+ //...
+ const { onLoop } = useRenderLoop()
+ 
+onLoop(({ elapsed }) => {
+   if (blobRef.value) {
+     blobRef.value.material.uniforms.uTime.value = elapsed
+   }
+})
+ //...
+```
+
+Y eso es todo, tenemos nuestro shader básico funcionando sin problemas.
+
+## Usando GLSL vite-plugin (opcional)
+
+_Este paso es completamente opcional y está fuera del alcance del equipo de **TresJs**_
+
+Definir nuestro shader en línea no siempre es la mejor idea, pero si estás utilizando [vite](https://vitejs.dev/), puedes colocar tus archivos `GLSL` en un archivo diferente utilizando el [vite-plugin-glsl](https://www.npmjs.com/package/vite-plugin-glsl) (consulta el enlace para obtener la documentación oficial).
+
+Y podrías tener una estructura similar a esta:
+
+```
+├── src/
+│   ├── myTresJsComponent.vue
+│   ├── shaders/
+│       ├── vertexShader.glsl
+│       ├── fragmentShader.glsl
+```

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

@@ -0,0 +1,194 @@
+# Texto3D
+
+[TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) es una de las formas en las que podemos agregar texto en 3D a nuestra escena.
+
+<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=="/>
+
+Sin embargo, no forma parte del núcleo de ThreeJS. Por lo tanto, para usarlo, tendrías que importarlo desde el módulo `three/addons/controls/TextGeometry`.
+
+Esto crea un problema porque **TresJS** crea automáticamente un catálogo del núcleo de Three para que puedas usarlos como componentes.
+
+Afortunadamente, **TresJS** proporciona una forma de ampliar el catálogo de componentes. Puedes hacerlo utilizando el método `extend` de la biblioteca principal.
+
+Para obtener más información sobre cómo ampliar tu catálogo de TresJS, consulta la sección de [extending](/advanced/extending.md).
+
+## Usando TextGeometry
+
+Para usar `TextGeometry`, debes importarlo desde el módulo `three/addons/geometries/TextGeometry`.
+
+```js
+import { TextGeometry } from 'three/addons/geometries/TextGeometry'
+```
+
+Luego, debes ampliar el catálogo de componentes utilizando el método `extend`.
+
+```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) necesita solo un argumento requerido, la fuente. Puedes ver un ejemplo a continuación.
+
+```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))
+  }
+})
+```
+
+Ahora puedes usar el componente `TresTextGeometry` dentro de un TresMesh en tu escena.
+
+```vue
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <TresMesh>
+      <TresTextGeometry
+        :args="['TresJS', { font, ...fontOptions }]"
+        center
+      />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+luego, como en el ejemplo, puedes pasar un objeto con las configuraciones deseadas.
+
+```ts
+const fontOptions = {
+  size: 0.5,
+  height: 0.2,
+  curveSegments: 5,
+  bevelEnabled: true,
+  bevelThickness: 0.05,
+  bevelSize: 0.02,
+  bevelOffset: 0,
+  bevelSegments: 4,
+}
+```
+
+También podemos pasar una matcapTexture para agregar detalles finales, utilizando TresMeshNormalMaterial dentro de 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>
+```
+
+Entonces, el código final sería algo como esto:
+
+```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>
+```
+
+Sé que parece mucho trabajo, pero tengo buenas noticias, hay una forma mucho más sencilla.
+
+## TextGeometry de `cientos`
+
+El paquete `cientos` proporciona un componente llamado `<Text3D />` que es un envoltorio de `TextGeometry` del módulo [`three-stdlib`](https://github.com/pmndrs/three-stdlib).
+
+¿Lo mejor? No necesitas extender el catálogo, solo pasa el argumento de la fuente.
+Simplemente funciona. 💯 (si no se proporciona un texto, el texto será TresJS)
+
+```vue
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <Text3D :font="fontPath" />
+  </TresCanvas>
+</template>
+```
+
+Podemos pasar las opciones como props
+
+```html
+<Text3D :font="fontPath" :text="my 3d text" :size="0.8" />
+```
+
+en caso de que no se proporcionen las opciones, los valores predeterminados son:
+
+```js
+size: 0.5,
+height: 0.2,
+curveSegments: 5,
+bevelEnabled: true,
+bevelThickness: 0.05,
+bevelSize: 0.02,
+bevelOffset: 0,
+bevelSegments: 4,
+```
+
+De forma predeterminada, el texto en ThreeJS comienza en la posición inicial de la malla, por lo que si es [0,0,0], el texto comenzará allí, pero podemos centrarlo simplemente pasando la bandera "center".
+
+```vue
+<Text3D :font="fontPath" :text="my 3d text" center />
+```

docs/pl/guide/getting-started.md

@@ -0,0 +1,93 @@
+# Instalacja
+
+Dowiedz się, jak zainstalować TresJS
+
+::: code-group
+
+```bash [pnpm]
+pnpm add three @tresjs/core
+```
+
+```bash [npm]
+npm install three @tresjs/core
+```
+
+```bash [yarn]
+yarn add three @tresjs/core
+```
+
+:::
+
+> Zalecane do użytku z Vue 3.x i Composition API
+
+## Typescript
+
+TresJS zostało napisane w TypeScript i jest w pełni otypowane. Jeśli korzystasz z TypeScript, będziesz czerpać pełne korzyści z typowań. Upewnij się tylko, że zainstalujesz typy dla Three.
+
+::: code-group
+
+```bash [npm]
+npm install @types/three -D
+```
+
+```bash [yarn]
+yarn add @types/three -D
+```
+
+```bash [pnpm]
+pnpm add @types/three -D
+```
+
+:::
+
+## Rozpoczęcie
+
+Możesz zainstalować TresJS tak samo, jak każdy inny plugin Vue
+
+```ts
+import { createApp } from "vue";
+import Tres from "@tresjs/core";
+import App from "./App.vue";
+
+export const app = createApp(App);
+
+app.use(Tres);
+app.mount("#app");
+```
+
+Możesz również używać go bezpośrednio w swoim komponencie
+
+```vue
+<script setup lang="ts">
+import { TresCanvas } from "@tresjs/core";
+</script>
+
+<template>
+  <TresCanvas>
+    <!-- Your scene here -->
+  </TresCanvas>
+</template>
+```
+
+::: tip
+Jest to zalecane ze względów wydajności i rozmiaru paczki. Działa to lepiej przy tree-shaking, importujesz tylko te komponenty, których używasz.
+:::
+
+## Vite
+
+Ponieważ v2 to niestandardowy renderer, musimy poinformować `vue-compiler` twojej aplikacji, że komponenty Tres są dołączane, aby uniknąć ostrzeżenia `[Vue warn]: Failed to resolve component`.
+
+Wystarczy dodać to do swojego pliku `vite.config.ts` wewnątrz pluginu Vue:
+
+```ts
+import { templateCompilerOptions } from "@tresjs/core";
+
+export default defineConfig({
+  plugins: [
+    vue({
+      // Other config
+      ...templateCompilerOptions,
+    }),
+  ],
+});
+```

docs/pl/guide/index.md

@@ -0,0 +1,113 @@
+# Wstęp
+
+<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 jest napisane w języku TypeScript i jest w pełni otypowane. Jeśli używasz TypeScript, będziesz korzystać z pełnych korzyści z typowań. Po prostu upewnij się, że zainstalujesz typy dla 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
+
+Jeśli używasz Vite, musisz dodać następujący kod do swojego pliku `vite.config.ts`:
+
+```ts
+import { templateCompilerOptions } from '@tresjs/core'
+
+export default defineConfig({
+  plugins: [
+    vue({
+      // Other config
+      ...templateCompilerOptions
+    }),
+  ],
+}),
+```
+
+To jest wymagane, aby kompilator szablonów działał z niestandardowym renderem i nie generował ostrzeżeń na konsoli. Aby uzyskać więcej informacji, sprawdź [tutaj](/pl/guide/troubleshooting.html).
+
+## Wypróbuj to online
+
+### Sandbox
+
+Możesz wypróbować TresJS online za pomocą oficjalnego [sandbox](https://play.tresjs.org/). Sprawdź to:
+
+<iframe src="https://play.tresjs.org/" class="w-full rounded shadow-lg outline-none border-none aspect-4/3"></iframe>
+
+### StackBlitz
+
+Mamy zupełnie nowy starter w [StackBlitz](https://stackblitz.com/) by wypróbować TresJS online. Sprawdź to:
+
+![](/stackblitz-starter.png)
+
+<StackBlitzEmbed projectId="tresjs-basic" />
+
+## Playground
+
+Mamy także plac zabaw, gdzie możesz wypróbować TresJS online. Sprawdź to [aquí](https://playground.tresjs.org/).
+
+![](/playground.png)
+
+## Motivación
+
+[ThreeJS](https://threejs.org/) to wspaniała biblioteka do tworzenia niesamowitych witryn 3D przy użyciu WebGL. Jest to także stale aktualizowana biblioteka, co sprawia, że utrudnia utrzymanie wrapperów, takich jak [TroisJS](https://troisjs.github.io/).
+
+W ekosystemie React mamy imponujące rozwiązanie custom render o nazwie **custom render** o nazwie [React-three-fiber](https://docs.pmnd.rs/react-three-fiber) które pozwala budować sceny deklaratywnie za pomocą komponentów wielokrotnego użytku, samodzielnych, reagujących na stan.
+
+W poszukiwaniu czegoś podobnego w ekosystemie VueJS natrafiłem na niesamowitą bibliotekę o nazwie [Lunchbox](https://github.com/breakfast-studio/lunchboxjs) która działa według tego samego konceptu co R3F. Oferuje [własny renderer Vue3](https://vuejs.org/api/custom-renderer.html). Przyczyniam się również do poprawy tej biblioteki, aby była równie dojrzała i bogata w funkcje co R3F.
+
+EJedynym problemem jest to, że mieszanie renderów kompilatorów w Vue 3 to coś, nad czym społeczność Vue wciąż pracuje - zobacz [tutaj](https://github.com/vuejs/vue-loader/pull/1645) po więcej informacji.
+
+```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");
+```
+
+Tak więc zainspirowany obiema bibliotekami, postanowiłem stworzyć własny renderer Vue dla ThreeJS. Oto **TresJS v2**.

docs/pl/guide/migration-guide.md

@@ -0,0 +1,226 @@
+# Guía de Migración
+
+Esta guía tiene como objetivo ayudarte a migrar de la versión 1 a las versiones más recientes de TresJS 🤩✨.
+
+::: code-group
+
+```bash [pnpm]
+pnpm update @tresjs/core
+```
+
+```bash [npm]
+npm update @tresjs/core
+```
+
+```bash [yarn]
+yarn upgrade @tresjs/core
+```
+
+:::
+
+## Novedades
+
+### Vue Custom Renderer
+
+**TresJS** es ahora un [Vue Custom Renderer](https://vuejs.org/api/custom-renderer.html#createrenderer) 🎉 que se encuentra dentro de un componente envolvente `TresCanvas` que se encarga de crear el `WebGLRenderer` y la `Scene` por ti, y crear una **nueva instancia de la aplicación Vue** para renderizar la escena.
+
+### Soporte de TypeScript e Intellisense 🦾
+
+![TresJS Intellisense](/v2-intellisense.gif)
+
+Esta fue probablemente la característica más **solicitada para TresJS**. Ahora los componentes de Tres funcionan con Volar y proporcionan intellisense de tipos.
+
+**TresJS** ahora genera declaraciones de tipos en tiempo de compilación para todos los componentes basados en el catálogo de ThreeJS. Esto significa que puedes usar todos los componentes de ThreeJS y obtener intellisense de tipos para ellos.
+
+### El plugin de Tres es opcional 👍
+
+El `TresPlugin` ahora es opcional. Puedes usar TresJS sin él importando los componentes directamente desde `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
+Esto es recomendado por razones de rendimiento y tamaño del paquete, el tree-shaking funcionará mejor y solo importarás los componentes que uses.
+:::
+
+### TresScene ya no es necesario
+
+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>
+```
+
+Para migrar tu código, simplemente puedes eliminar el componente `<TresScene />` y mover los hijos al componente `<TresCanvas />`.
+
+### `useCatalog` ahora está obsoleto
+
+La función `useCatalog` ahora está obsoleta. Ahora puedes importar el catálogo directamente desde `@tresjs/core`.
+
+Puedes leer más al respecto aquí: [Extending](/advanced/extending.md)
+
+Cambia esto:
+
+```ts {2,5,7}
+import { useCatalog } from '@tresjs/core'
+import { TextGeometry } from 'three/addons/geometries/TextGeometry'
+
+const { extend } = useCatalog()
+
+extend({ TextGeometry })
+```
+
+Por esto:
+
+```ts {2,6}
+// Correcto ✅
+import { extend } from '@tresjs/core'
+import { TextGeometry } from 'three/addons/geometries/TextGeometry'
+
+extend({ TextGeometry })
+```
+
+### El valor de referencia del modelo `getModel` ahora está obsoleto
+
+La función `getModel` ahora está obsoleta. Ahora puedes usar directamente la propiedad `model`.
+
+Cambia esto:
+
+```vue {7,9-12}
+// Incorrecto ❌
+<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}
+// Correcto ✅
+<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>
+```
+
+### Las cámaras deben estar antes de cualquier control 🎥
+
+El componente `TresOrbitControls` debe estar después de la cámara en el árbol. Esto se debe a que los controles necesitan conocer la cámara para funcionar.
+
+Cambia esto:
+
+```vue {3,5}
+// Incorrecto ❌
+<template>
+  <TresCanvas>
+    <TresOrbitControls />
+    <TresPerspectiveCamera />
+  </TresCanvas>
+</template>
+```
+
+Por esto:
+
+```vue {3,5}
+// Correcto ✅
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera />
+    <TresOrbitControls />
+  </TresCanvas>
+</template>
+```
+
+## UseTres ahora es useTresContext <Badge type="warning" text="^3.0.0" />
+
+Para la versión 3, reestructuramos toda la lógica de estado para que sea más flexible y fácil de usar para los autores de complementos y paquetes del ecosistema. En lugar de usar una tienda como en la versión 2, ahora usamos un proveedor de contexto basado en `provide/inject`.
+
+La función `useTres` ahora es un alias de la función `useTresContext` para evitar romper demos y experimentos existentes, pero considera usar `useTresContext` a partir de ahora.
+
+En lugar de obtener un objeto reactivo grande, ahora obtendrás directamente las referencias `scene` y `renderer`, entre otras propiedades.
+
+Cambia esto:
+
+```ts {2}
+// Incorrecto ❌
+import { useTres } from '@tresjs/core'
+
+const { state, setState } = useTres()
+
+console.log(state.scene)
+```
+
+Por esto:
+
+```ts {2}
+// Correcto ✅
+import { useTresContext } from '@tresjs/core'
+
+const { scene, renderer } = useTresContext()
+
+console.log(scene.value)
+```
+
+Para obtener información más detallada sobre el nuevo sistema de proveedor de contexto, puedes leer la sección [API DOCS](/api/composables.md).

docs/pl/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>
+
+¡Aquí está el módulo oficial de Nuxt para TresJS! 🎉.
+
+El repositorio está [aquí](https://github.com/Tresjs/nuxt)
+
+## Instalación
+
+::: code-group
+
+```bash [pnpm]
+pnpm add three @tresjs/nuxt 
+```
+
+```bash [npm]
+npm install three @tresjs/nuxt 
+```
+
+```bash [yarn]
+yarn add three @tresjs/nuxt 
+```
+
+:::
+
+## Características
+
+- 🤓 Importación automática de componentes y composables del [ecosistema de TresJS](https://github.com/orgs/Tresjs/repositories)
+- `TresCanvas` esta disponible solo en el cliente, no es necesario agregar `.client` al nombre del componente o `<ClientOnly />`
+- Configura automáticamente el compilador de Vue para admitir componentes de TresJS, consulta [por qué](/guide/troubleshooting.html#failed-resolve-component-trescomponent-%F0%9F%A4%94)?
+- Toda la magia de DX que viene con Nuxt ✨
+
+## Uso
+
+Agrega `@tresjs/nuxt` a la sección `modules` de `nuxt.config.ts`
+
+```js
+export default defineNuxtConfig({
+  modules: ['@tresjs/nuxt'],
+})
+```
+
+¡Eso es todo! Ahora puedes usar `@tresjs/nuxt` en tu aplicación Nuxt ✨
+
+Si deseas utilizar cualquier paquete del ecosistema de TresJS, puedes instalar los paquetes que desees utilizar y serán importados automáticamente por el módulo 🧙🏼‍♂️.
+
+| 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
+# Usando pnpm
+pnpm add @tresjs/cientos @tresjs/post-processing
+```

docs/pl/guide/troubleshooting.md

@@ -0,0 +1,88 @@
+# La divertida guía de problemas comunes y cómo solucionarlos
+
+![Solución de problemas](https://media.giphy.com/media/LHZyixOnHwDDy/giphy.gif)
+
+Bienvenido a la guía de solución de problemas de **TresJS v2**. ¡Donde 3D significa _"Dificultades Deslumbrantemente Deliciosas"_! Sabemos que el 3D puede ser tan complejo como una bola de lana enredada 🧶 o tan impredecible como un gato en un teclado 🐈 ⌨️, ¡pero no temas!
+
+Esta guía está destinada a ayudarte a resolver los problemas más comunes que puedes encontrar al usar TresJS v2.
+
+## ¡No puedo ver mi escena 3D 😭!
+
+Has seguido la [guía de inicio](/guide/getting-started.md) pero aún no puedes ver tu escena renderizada.
+
+Estas son las razones más comunes por las que es posible que no puedas ver tu escena:
+
+### Verifica la altura de tu lienzo 📏
+
+Otro problema común es que el componente `TresCanvas` crea por defecto un elemento `canvas` que toma el `width` y `height` del elemento padre. Si el elemento padre no tiene altura, el lienzo tampoco la tendrá.
+
+![No se encontró altura](/canvas-height.png)
+
+También verás este error en la consola:
+
+![Advertencia de altura del lienzo](/canvas-height-warning.png)
+
+Una forma sencilla de solucionar esto es establecer la altura del elemento padre en `100%`:
+
+```css
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  width: 100%;
+}
+#app {
+  height: 100%;
+  width: 100%;
+  background-color: #000;
+}
+```
+
+O también puedes establecer la propiedad `window-size` del componente `TresCanvas`:
+
+```vue
+<TresCanvas window-size>
+  <TresPerspectiveCamera />
+  <TresOrbitControls />
+</TresCanvas>
+```
+
+## Error al resolver el componente: TresComponent...
+
+![](/failed-to-resolve-component.png)
+
+Dado que **TresJS v2** utiliza un Renderizador Personalizado de Vue dentro de la instancia principal de la aplicación Vue, el renderizador principal de Vue que actúa como padre no reconocerá los componentes dentro del componente `TresCanvas`. Aunque no afecta la representación, mostrará una advertencia en la consola.
+
+![](/failed-to-resolve-component.png)
+
+En este momento, no hay soporte nativo de Vue para definir el renderizador utilizado en la etiqueta `<template />`, pero hay una solución rápida para eliminar las advertencias.
+
+Ve a tu archivo `vite.config.ts` y agrega la siguiente configuración al `@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,
+    }),
+  ],
+})
+```
+
+Esto eliminará la advertencia de la consola.
+
+# ¡Ayúdanos a hacer que TresJS sea purr-fecto! 😼
+
+Sabemos que incluso los mejores gatos dormilones ocasionalmente cometen errores, ¡y necesitamos tu ayuda para hacer que TresJS sea aún mejor! Si encuentras un error, por favor abre un ticket en [el repositorio](https://github.com/Tresjs/playground) y **por favor proporciona un enlace de reproducción**.
+
+::: warning
+Los tickets sin un enlace de reproducción serán cerrados.
+:::
+
+Nuestro equipo de amantes de los gatos programadores se pondrá en acción para eliminar esos molestos errores y mejorar TresJS para todos. ¡Juntos, hagamos que TresJS sea el maullido del renderizado 3D en Vue!

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

@@ -0,0 +1,165 @@
+# Twoja pierwsza scena
+
+Ten przewodnik pomoże Ci stworzyć twoją pierwszą scenę w Tres. 🍩
+
+<ClientOnly>
+<div style="aspect-ratio: 16/9; height: auto; margin: 2rem 0; border-radius: 8px; overflow:hidden;">
+  <DonutExample />
+</div>
+</ClientOnly>
+
+## Configurando el Canvas
+
+Zanim będziemy mogli stworzyć scenę, potrzebujemy miejsca do jej wyświetlenia. Korzystając z czystego [ThreeJS](https://threejs.org/docs/index.html#manual/en/introduction/Creating-a-scene), musielibyśmy stworzyć element HTML `canvas` aby zamontować `WebglRenderer` i zainicjować `scene`.
+
+Z **TresJS**, wystarczy zaimportować domyślny komponent `<TresCanvas />` i dodać go do szablonu swojego komponentu Vue.
+
+```vue
+<script lang="ts" setup>
+import { TresCanvas } from "@tresjs/core";
+</script>
+
+<template>
+  <TresCanvas window-size>
+    <!-- Tu escena vive aqui -->
+  </TresCanvas>
+</template>
+```
+
+::: warning
+Jest ważne, aby wszystkie komponenty związane z sceną znajdowały się między komponentem `<TresCanvas />`. W przeciwnym razie nie zostaną one wyrenderowane.
+:::
+
+Komponent `TresCanvas` wykonuje pewne prace konfiguracyjne za kulisami:
+
+- Tworzy [**WebGLRenderer**](https://threejs.org/docs/index.html?q=webglrend#api/en/renderers/WebGLRenderer) który automatycznie aktualizuje się w każdej klatce.
+- Ustawia pętlę renderowania, aby była wywoływana w każdej klatce, zgodnie z odświeżaniem przeglądarki.
+
+## Rozmiar płutna
+
+Domyślnie komponent `TresCanvas` przyjmuje **szerokość i wysokość rodzica**. Jeśli doświadczasz pustej strony, upewnij się, że element nadrzędny ma odpowiedni rozmiar.
+
+```vue
+<script lang="ts" setup>
+import { TresCanvas } from "@tresjs/core";
+</script>
+
+<template>
+  <TresCanvas>
+    <!-- Twoja scena znajduje się tutaj -->
+  </TresCanvas>
+</template>
+
+<style>
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  width: 100%;
+}
+#app {
+  height: 100%;
+  width: 100%;
+}
+</style>
+```
+
+Jeśli twoja scena nie będzie częścią interfejsu użytkownika, możesz również wymusić, aby płutno zajmowało szerokość i wysokość całego okna, używając właściwości `window-size` na przykład:
+
+```vue
+<script lang="ts" setup>
+import { TresCanvas } from "@tresjs/core";
+</script>
+
+<template>
+  <TresCanvas window-size>
+    <!-- Tu escena vive aqui -->
+  </TresCanvas>
+</template>
+```
+
+## Tworzenie sceny
+
+Potrzebujemy 4 głównych elementów, aby stworzyć doświadczenie w 3D:
+
+- [**Scena**](https://threejs.org/docs/index.html?q=scene#api/en/scenes/Scene) do zawierania kamery i obiektów razem.
+- [**Renderer**](https://threejs.org/docs/index.html?q=renderer#api/en/renderers/WebGLRenderer) do renderowania sceny w DOM.
+- [**Kamera**](https://threejs.org/docs/index.html?q=camera#api/en/cameras/Camera)
+- [**Obiekt**](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D)
+
+Z **TresJS**, wystarczy dodać komponent `<TresCanvas />` do szablonu swojego komponentu Vue, a automatycznie utworzy dla Ciebie `Renderer` (element DOM `canvas`) i `Scenę`.
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <!-- Tu escena vive aqui -->
+  </TresCanvas>
+</template>
+```
+
+Następnie możesz dodać [**PerspectiveCamera**](https://threejs.org/docs/index.html?q=perspectivecamera#api/en/cameras/PerspectiveCamera) używając komponentu `<TresPerspectiveCamera />`.
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <TresPerspectiveCamera />
+  </TresCanvas>
+</template>
+```
+
+::: warning
+Częstym problemem jest to, że domyślna pozycja kamery to początek sceny (0,0,0). TresJS automatycznie ustawia pozycję kamery na `[3,3,3]` przy użyciu właściwości `position`. Jeśli nie zdefiniujesz kamery w swojej scenie, automatycznie dodawana jest kamera perspektywiczna.
+:::
+
+## Dodawanie 🍩
+
+Ta scena wydaje się trochę pusta, dodajmy podstawowy obiekt. Gdybyśmy używali czystego ThreeJS, musielibyśmy stworzyć obiekt **ThreeJS** puro, necesitaríamos crear un objeto [**Mesh**](https://threejs.org/docs/index.html?q=mesh#api/en/objects/Mesh)i dołączyć do niego [**Material**](https://threejs.org/docs/index.html?q=material#api/en/materials/Material) oraz [**Geometry**](https://threejs.org/docs/index.html?q=geometry#api/en/core/BufferGeometry) w ten sposób:
+
+```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);
+```
+
+**Mesh** to podstawowy obiekt sceny w three.js i służy do przechowywania geometrii oraz materiału potrzebnego do przedstawienia kształtu w przestrzeni 3D.
+
+Teraz zobaczmy, jak łatwo możemy osiągnąć to samo przy użyciu **TresJS**. Aby to zrobić, skorzystamy z komponentu `<TresMesh />` a między domyślnymi slotami przekażemy `<TresTorusGeometry />` oraz `<TresMeshBasicMaterial />`.
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <TresPerspectiveCamera />
+    <TresMesh>
+      <TresTorusGeometry :args="[1, 0.5, 16, 32]" />
+      <TresMeshBasicMaterial color="orange" />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+::: info
+Zauważ, że nie musisz nic importować, ponieważ **TresJS** automatycznie generuje **Komponent Vue na podstawie obiektu Three o nazwie CamelCase z prefiksem Tres**. Na przykład, jeśli chcesz użyć `AmbientLight`, użyjesz komponentu `<TresAmbientLight />`.
+:::
+
+```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>
+```
+
+Od tego momentu możesz zacząć dodawać więcej obiektów do swojej sceny i zacząć eksperymentować z właściwościami komponentów, aby zobaczyć, jak wpływają na scenę.
+
+<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/pl/index.md

@@ -0,0 +1,35 @@
+---
+layout: home
+
+title: TresJS
+titleTemplate: Rozwiązanie dla 3D na VueJS
+
+hero:
+  name: TresJS
+  text: Przenieś Three do ekosystemu Vue
+  tagline: Twórz niesamowite doświadczenia w 3D przy użyciu ulubionego frameworka.
+  image:
+    src: /hero.png
+    alt: Tresjs
+  actions:
+    - theme: brand
+      text: Rozpocznij
+      link: /pl/guide/
+    - theme: alt
+      text: Dlaczego Tres?
+      link: /pl/guide/#motivation
+
+features:
+  - icon: 💡
+    title: Deklaratywny
+    details: Buduj scenę 3D tak, jakby była składnikiem Vue.
+  - icon: ⚡️
+    title: Napędzane przez Vite
+    details: Hot Module Replacement (HMR), które pozostaje szybkie bez względu na rozmiar aplikacji.
+  - icon: 🥰
+    title: Utrzymujemy na bieżąco
+    details: Natychmiast udostępniamy wszystkie zaktualizowane funkcje ThreeJS.
+  - icon: 🌳
+    title: Ekosystem
+    details: Rozszerz podstawową funkcjonalność za pomocą pakietów takich jak cientos i postprocessing. Lub dodaj własne.
+---