Merge branch 'main' into v4

docs/.vitepress/config.ts

@@ -1,203 +0,0 @@
-import { defineConfig } from 'vitepress'
-import { resolve } from 'pathe'
-
-export default defineConfig({
-  title: 'TresJS',
-  description: 'Declarative ThreeJS using Vue Components',
-  head: [
-    ['link', { rel: 'icon', type: 'image/svg', href: '/favicon.svg' }],
-    ['meta', { name: 'theme-color', content: '#82DBC5' }],
-    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
-    ['meta', { name: 'twitter:site', content: '@tresjs_dev' }],
-    ['meta', { name: 'twitter:creator', content: '@tresjs_dev' }],
-    ['meta', { property: 'og:type', content: 'website' }],
-    ['meta', { property: 'og:site_name', content: 'TresJS' }],
-    [
-      'meta',
-      {
-        property: 'og:image',
-        content: 'https://repository-images.githubusercontent.com/571314349/10996566-7f70-473b-a8e5-4e56fc0ca850',
-      },
-    ],
-    [
-      'meta',
-      {
-        property: 'twitter:image',
-        content: 'https://repository-images.githubusercontent.com/571314349/10996566-7f70-473b-a8e5-4e56fc0ca850',
-      },
-    ],
-    ['script', { defer: 'true', 'data-site': 'OWBUVCJK', src: 'https://cdn.usefathom.com/script.js' }],
-  ],
-  themeConfig: {
-    logo: '/logo.svg',
-    search: {
-      provider: 'local',
-    },
-    sidebar: [
-      {
-        text: 'Guide',
-        items: [
-          // This shows `/guide/index.md` page.
-          { text: 'Introduction', link: '/guide/' },
-          { text: 'Getting Started', link: '/guide/getting-started' },
-          { text: 'Your first Scene', link: '/guide/your-first-scene' },
-          { text: 'Nuxt', link: '/guide/nuxt' },
-          { text: 'Troubleshooting', link: '/guide/troubleshooting' },
-          { text: 'Migrate from v1', link: '/guide/migration-guide' },
-        ],
-      },
-      {
-        text: 'API',
-        items: [
-          { text: 'TresCanvas', link: '/api/tres-canvas' },
-          {
-            text: 'Instances, arguments and props',
-            link: '/api/instances-arguments-and-props',
-          },
-          {
-            text: 'Composables',
-            link: '/api/composables',
-          },
-          {
-            text: 'Events',
-            link: '/api/events',
-          },
-        ],
-      },
-
-      {
-        text: 'Advanced',
-
-        items: [
-          { text: 'Extending', link: '/advanced/extending' },
-          { text: 'primitive', link: '/advanced/primitive' },
-          { text: 'Performance', link: '/advanced/performance' },
-          {
-            text: 'Caveats',
-            link: '/advanced/caveats',
-          },
-        ],
-      },
-      {
-        text: 'Debug',
-        items: [
-          { text: 'Devtools', link: '/debug/devtools' },
-        ],
-      },
-      {
-        text: 'Examples',
-        collapsed: true,
-        items: [
-          { text: 'Orbit Controls', link: '/examples/orbit-controls' },
-          { text: 'Basic Animations', link: '/examples/basic-animations' },
-          { text: 'Groups', link: '/examples/groups' },
-          { text: 'Load Textures', link: '/examples/load-textures' },
-          { text: 'Load Models', link: '/examples/load-models' },
-          { text: 'Load Text', link: '/examples/text-3d' },
-          { text: 'Lights & Shadows', link: '/examples/lights-shadows' },
-          { text: 'Shaders', link: '/examples/shaders' },
-        ],
-      },
-      {
-        text: 'Directives',
-        collapsed: true,
-        items: [
-          { text: 'v-log', link: '/directives/v-log' },
-          { text: 'v-light-helper', link: '/directives/v-light-helper' },
-          { text: 'v-always-look-at', link: '/directives/v-always-look-at' },
-          { text: 'v-distance-to', link: '/directives/v-distance-to' },
-        ],
-      },
-      {
-        text: 'Ecosystem',
-        items: [
-          {
-            text: 'Cientos 💛',
-            link: 'https://cientos.tresjs.org/',
-          },
-          {
-            text: 'Nuxt module',
-            link: 'https://github.com/Tresjs/nuxt',
-          },
-          {
-            text: 'TresLeches 🍰',
-            link: 'https://tresleches.tresjs.org/',
-          },
-          {
-            text: 'Post-processing (Soon)',
-          },
-        ],
-      },
-    ],
-    nav: [
-      { text: 'Guide', link: '/guide/' },
-      { text: 'API', link: '/api/tres-canvas' },
-      /*       { text: 'API', link: '/api/' },
-      { text: 'Config', link: '/config/' }, */
-      { text: 'Resources',
-        items: [
-          { text: 'Team', link: '/team' },
-          { text: 'Releases', link: 'https://github.com/Tresjs/tres/releases' },
-          {
-            text: 'Playground',
-            link: 'https://playground.tresjs.org/',
-          },
-          {
-            text: 'Github',
-            link: 'https://github.com/Tresjs/tres/',
-          },
-          {
-            text: 'Issues',
-            link: 'https://github.com/Tresjs/tres/issues',
-          },
-          {
-            text: 'Ecosystem',
-            items: [
-              {
-                text: 'Cientos 💛',
-                link: 'https://cientos.tresjs.org/',
-              },
-              {
-                text: 'Nuxt module',
-                link: 'https://github.com/Tresjs/nuxt',
-              },
-              {
-                text: 'TresLeches 🍰',
-                link: 'https://tresleches.tresjs.org/',
-              },
-            ],
-          },
-        ],
-      },  
-    ],
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/tresjs/tres' },
-      { icon: 'x', link: 'https://twitter.com/tresjs_dev' },
-      { icon: 'discord', link: 'https://discord.gg/UCr96AQmWn' },
-    ],
-  },
-  vite: {
-    optimizeDeps: {
-      exclude: ['vitepress'],
-      include: ['three'],
-    },
-    server: {
-      hmr: {
-        overlay: false,
-      },
-    },
-    resolve: {
-      alias: {
-        '@tresjs/core': resolve(__dirname, '../../dist/tres.js'),
-      },
-      dedupe: ['@tresjs/cientos', 'three'],
-    },
-  },
-  vue: {
-    template: {
-      compilerOptions: {
-        isCustomElement: tag => tag.startsWith('Tres') && tag !== 'TresCanvas',
-      },
-    },
-  },
-})

docs/.vitepress/config/de.ts

@@ -56,17 +56,17 @@ export const deConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
         ],
       },
       {
-        text: 'Beispiele',
-        collapsed: true,
+        text: 'Kochbuch 🍳🧑‍🍳',
+        link: '/de/cookbook/',
         items: [
-          { text: 'Orbit-Controls', link: '/de/examples/orbit-controls' },
-          { text: 'Einfache Animationen', link: '/de/examples/basic-animations' },
-          { text: 'Gruppen', link: '/de/examples/groups' },
-          { text: 'Texturen laden', link: '/de/examples/load-textures' },
-          { text: 'Modelle laden', link: '/de/examples/load-models' },
-          { text: 'Text laden', link: '/de/examples/text-3d' },
-          { text: 'Lichter und Schatten', link: '/de/examples/lights-shadows' },
-          { text: 'Shaders', link: '/de/examples/shaders' },
+          { text: 'Orbit-Controls', link: '/de/cookbook/orbit-controls' },
+          { text: 'Einfache Animationen', link: '/de/cookbook/basic-animations' },
+          { text: 'Gruppen', link: '/de/cookbook/groups' },
+          { text: 'Texturen laden', link: '/de/cookbook/load-textures' },
+          { text: 'Modelle laden', link: '/de/cookbook/load-models' },
+          { text: 'Text laden', link: '/de/cookbook/text-3d' },
+          { text: 'Lichter und Schatten', link: '/de/cookbook/lights-shadows' },
+          { text: 'Shaders', link: '/de/cookbook/shaders' },
         ],
       },
       {
@@ -112,7 +112,7 @@ export const deConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
           { text: 'Versionen', link: 'https://github.com/Tresjs/tres/releases' },
           {
             text: 'Spielplatz',
-            link: 'https://playground.tresjs.org/',
+            link: 'https://play.tresjs.org/',
           },
           {
             text: 'Github',
@@ -142,5 +142,35 @@ export const deConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
         ],
       },
     ],
+    search: {
+      provider: 'local',
+      options: {
+        locales: {
+          de: {
+            translations: {
+              button: {
+                buttonText: 'Suchen',
+                buttonAriaLabel: 'Suchen',
+              },
+              modal: {
+                displayDetails: 'Detaillierte Liste anzeigen',
+                resetButtonTitle: 'Suche zurücksetzen',
+                backButtonTitle: 'Suche schließen',
+                noResultsText: 'Keine Ergebnisse für',
+                footer: {
+                  selectText: 'zur Auswahl',
+                  selectKeyAriaLabel: 'enter',
+                  navigateText: 'zum Navigieren',
+                  navigateUpKeyAriaLabel: 'Pfeil nach oben',
+                  navigateDownKeyAriaLabel: 'Pfeil nach unten',
+                  closeText: 'zum Schließen',
+                  closeKeyAriaLabel: 'escape',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
   },
 }

docs/.vitepress/config/en.ts

@@ -43,7 +43,7 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
 
         items: [
           { text: 'Extending', link: '/advanced/extending' },
-          { text: 'primitive', link: '/advanced/primitive' },
+          { text: 'Primitive', link: '/advanced/primitive' },
           {
             text: 'Caveats',
             link: '/advanced/caveats',
@@ -57,17 +57,17 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
         ],
       },
       {
-        text: 'Examples',
-        collapsed: true,
+        text: 'Cookbook 🍳🧑‍🍳',
+        link: '/cookbook/',
         items: [
-          { text: 'Orbit Controls', link: '/examples/orbit-controls' },
-          { text: 'Basic Animations', link: '/examples/basic-animations' },
-          { text: 'Groups', link: '/examples/groups' },
-          { text: 'Load Textures', link: '/examples/load-textures' },
-          { text: 'Load Models', link: '/examples/load-models' },
-          { text: 'Load Text', link: '/examples/text-3d' },
-          { text: 'Lights & Shadows', link: '/examples/lights-shadows' },
-          { text: 'Shaders', link: '/examples/shaders' },
+          { text: 'Orbit Controls', link: '/cookbook/orbit-controls' },
+          { text: 'Basic Animations', link: '/cookbook/basic-animations' },
+          { text: 'Groups', link: '/cookbook/groups' },
+          { text: 'Load Textures', link: '/cookbook/load-textures' },
+          { text: 'Load Models', link: '/cookbook/load-models' },
+          { text: 'Load Text', link: '/cookbook/text-3d' },
+          { text: 'Lights & Shadows', link: '/cookbook/lights-shadows' },
+          { text: 'Shaders', link: '/cookbook/shaders' },
         ],
       },
       {
@@ -112,7 +112,7 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
           { text: 'Releases', link: 'https://github.com/Tresjs/tres/releases' },
           {
             text: 'Playground',
-            link: 'https://playground.tresjs.org/',
+            link: 'https://play.tresjs.org/',
           },
           {
             text: 'Github',
@@ -140,7 +140,7 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
             ],
           },
         ],
-      },  
+      },
     ],
   },
-}
+}

docs/.vitepress/config/es.ts

@@ -43,7 +43,7 @@ export const esConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
 
         items: [
           { text: 'Extender', link: '/es/advanced/extending' },
-          { text: 'primitive', link: '/es/advanced/primitive' },
+          { text: 'Primitive', link: '/es/advanced/primitive' },
           {
             text: 'Advertencias',
             link: '/es/advanced/caveats',
@@ -57,17 +57,17 @@ export const esConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
         ],
       },
       {
-        text: 'Ejemplos',
-        collapsed: true,
+        text: 'Recetario 🍳🧑‍🍳',
+        link: '/es/cookbook/',
         items: [
-          { text: 'Controles de órbita', link: '/es/examples/orbit-controls' },
-          { text: 'Animaciones básicas', link: '/es/examples/basic-animations' },
-          { text: 'Grupos', link: '/es/examples/groups' },
-          { text: 'Cargar texturas', link: '/es/examples/load-textures' },
-          { text: 'Cargar modelos', link: '/es/examples/load-models' },
-          { text: 'Cargar texto', link: '/es/examples/text-3d' },
-          { text: 'Luces y sombras', link: '/es/examples/lights-shadows' },
-          { text: 'Shaders', link: '/es/examples/shaders' },
+          { text: 'Controles de órbita', link: '/es/cookbook/orbit-controls' },
+          { text: 'Animaciones básicas', link: '/es/cookbook/basic-animations' },
+          { text: 'Grupos', link: '/es/cookbook/groups' },
+          { text: 'Cargar texturas', link: '/es/cookbook/load-textures' },
+          { text: 'Cargar modelos', link: '/es/cookbook/load-models' },
+          { text: 'Cargar texto', link: '/es/cookbook/text-3d' },
+          { text: 'Luces y sombras', link: '/es/cookbook/lights-shadows' },
+          { text: 'Shaders', link: '/es/cookbook/shaders' },
         ],
       },
       {
@@ -112,7 +112,7 @@ export const esConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
           { text: 'Versiones', link: 'https://github.com/Tresjs/tres/releases' },
           {
             text: 'Playground',
-            link: 'https://playground.tresjs.org/',
+            link: 'https://play.tresjs.org/',
           },
           {
             text: 'Github',
@@ -140,7 +140,37 @@ export const esConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
             ],
           },
         ],
-      },  
+      },
     ],
+    search: {
+      provider: 'local',
+      options: {
+        locales: {
+          es: {
+            translations: {
+              button: {
+                buttonText: 'Buscar',
+                buttonAriaLabel: 'Buscar',
+              },
+              modal: {
+                displayDetails: 'Mostrar lista detallada',
+                resetButtonTitle: 'Restablecer búsqueda',
+                backButtonTitle: 'Cerrar búsqueda',
+                noResultsText: 'Sin resultados para',
+                footer: {
+                  selectText: 'para seleccionar',
+                  selectKeyAriaLabel: 'entrar',
+                  navigateText: 'para navegar',
+                  navigateUpKeyAriaLabel: 'flecha arriba',
+                  navigateDownKeyAriaLabel: 'flecha abajo',
+                  closeText: 'para cerrar',
+                  closeKeyAriaLabel: 'escape',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
   },
-}
+}

docs/.vitepress/config/index.ts

@@ -3,8 +3,7 @@ import { enConfig } from './en'
 import { esConfig } from './es'
 import { deConfig } from './de'
 import { sharedConfig } from './shared'
-
-/* import { zhConfig } from './zh' */
+import { zhConfig } from './zh' 
 
 export default defineConfig({
   ...sharedConfig,
@@ -13,6 +12,6 @@ export default defineConfig({
     root: { label: 'English', lang: 'en-US', link: '/', ...enConfig },
     es: { label: 'Español', lang: 'es-ES', link: '/es/', ...esConfig },
     de: { label: 'Deutsch', lang: 'de-DE', link: '/de/', ...deConfig },
-    /* zh: { label: '简体中文', lang: 'zh-CN', link: '/zh/', ...zhConfig }, */
+    zh: { label: '简体中文', lang: 'zh-CN', link: '/zh/', ...zhConfig }, 
   },
-})
+})

docs/.vitepress/config/shared.ts

@@ -30,6 +30,37 @@ export const sharedConfig = defineConfig({
   ],
   themeConfig: {
     logo: '/logo.svg',
+    search: {
+      provider: 'local',
+      options: {
+        locales: {
+          root: {
+            translations: {
+              button: {
+                buttonText: 'Search',
+                buttonAriaLabel: 'Search',
+              },
+              modal: {
+                displayDetails: 'Display detailed list',
+                resetButtonTitle: 'Reset search',
+                backButtonTitle: 'Close search',
+                noResultsText: 'No results for',
+                footer: {
+                  selectText: 'to select',
+                  selectKeyAriaLabel: 'enter',
+                  navigateText: 'to navigate',
+                  navigateUpKeyAriaLabel: 'up arrow',
+                  navigateDownKeyAriaLabel: 'down arrow',
+                  closeText: 'to close',
+                  closeKeyAriaLabel: 'escape',
+                },
+              },
+            },
+          },
+          
+        },
+      },
+    },
     socialLinks: [
       { icon: 'github', link: 'https://github.com/tresjs/tres' },
       { icon: 'x', link: 'https://twitter.com/tresjs_dev' },
@@ -39,7 +70,7 @@ export const sharedConfig = defineConfig({
   vite: {
     optimizeDeps: {
       exclude: ['vitepress'],
-      include: ['three'],
+      include: ['@tresjs/cientos', '@stackblitz/sdk', '@vueuse/core', 'three'],
     },
     server: {
       hmr: {
@@ -60,4 +91,4 @@ export const sharedConfig = defineConfig({
       },
     },
   },
-})
+})

docs/.vitepress/config/zh.ts

@@ -0,0 +1,186 @@
+import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'
+
+export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
+  themeConfig: {
+    editLink: {
+      pattern: 'https://github.com/tresjs/tres/edit/main/packages/docs/:path',
+      text: '对本页内容给出建议',
+    },
+    sidebar: [
+      {
+        text: '使用指南',
+        items: [
+          { text: '简介', link: '/zh/guide/' },
+          { text: '入门指南', link: '/zh/guide/getting-started' },
+          { text: '你的第一个场景', link: '/zh/guide/your-first-scene' },
+          { text: 'Nuxt', link: '/zh/guide/nuxt' },
+          { text: '故障排除', link: '/zh/guide/troubleshooting' },
+          { text: '从 v1 迁移', link: '/zh/guide/migration-guide' },
+        ],
+      },
+      {
+        text: 'API',
+        items: [
+          { text: 'TresCanvas', link: '/zh/api/tres-canvas' },
+          {
+            text: '实例, 参数和 props',
+            link: '/zh/api/instances-arguments-and-props',
+          },
+          {
+            text: '组合式函数',
+            link: '/zh/api/composables',
+          },
+          {
+            text: '事件',
+            link: '/zh/api/events',
+          },
+        ],
+      },
+
+      {
+        text: '进阶',
+
+        items: [
+          { text: '扩展', link: '/zh/advanced/extending' },
+          { text: '原语', link: '/zh/advanced/primitive' },
+          {
+            text: '注意事项',
+            link: '/zh/advanced/caveats',
+          },
+        ],
+      },
+      {
+        text: 'Debug',
+        items: [
+          { text: 'Devtools', link: '/zh/debug/devtools' },
+        ],
+      },
+      {
+        text: '专题手册 🍳🧑‍🍳',
+        link: '/zh/cookbook/',
+        items: [
+          { text: '轨道控制器', link: '/zh/cookbook/orbit-controls' },
+          { text: '基础动画', link: '/zh/cookbook/basic-animations' },
+          { text: '组', link: '/zh/cookbook/groups' },
+          { text: '加载纹理', link: '/zh/cookbook/load-textures' },
+          { text: '加载模型', link: '/zh/cookbook/load-models' },
+          { text: '加载文本', link: '/zh/cookbook/text-3d' },
+          { text: '光照和阴影', link: '/zh/cookbook/lights-shadows' },
+          { text: '着色器', link: '/zh/cookbook/shaders' },
+        ],
+      },
+      {
+        text: '指令',
+        collapsed: true,
+        items: [
+          { text: 'v-log', link: '/zh/directives/v-log' },
+          { text: 'v-light-helper', link: '/zh/directives/v-light-helper' },
+          { text: 'v-always-look-at', link: '/zh/directives/v-always-look-at' },
+          { text: 'v-distance-to', link: '/zh/directives/v-distance-to' },
+        ],
+      },
+      {
+        text: '生态系统',
+        items: [
+          {
+            text: 'Cientos 💛',
+            link: 'https://cientos.tresjs.org/',
+          },
+          {
+            text: 'Nuxt module',
+            link: 'https://github.com/Tresjs/nuxt',
+          },
+          {
+            text: 'TresLeches 🍰',
+            link: 'https://tresleches.tresjs.org/',
+          },
+          {
+            text: 'Post-processing (Soon)',
+          },
+        ],
+      },
+    ],
+    nav: [
+      { text: '使用指南', link: '/zh/guide/' },
+      { text: 'API', link: '/zh/api/tres-canvas' },
+      /*       { text: 'API', link: '/api/' },
+      { text: 'Config', link: '/config/' }, */
+      {
+        text: '资源',
+        items: [
+          { text: '团队', link: '/zh/team' },
+          { text: '版本发布', link: 'https://github.com/Tresjs/tres/releases' },
+          {
+            text: '演练场',
+            link: 'https://play.tresjs.org/',
+          },
+          {
+            text: 'Github',
+            link: 'https://github.com/Tresjs/tres/',
+          },
+          {
+            text: '议题',
+            link: 'https://github.com/Tresjs/tres/issues',
+          },
+          {
+            text: '生态系统',
+            items: [
+              {
+                text: 'Cientos 💛',
+                link: 'https://cientos.tresjs.org/',
+              },
+              {
+                text: 'Nuxt 模块',
+                link: 'https://github.com/Tresjs/nuxt',
+              },
+              {
+                text: 'TresLeches 🍰',
+                link: 'https://tresleches.tresjs.org/',
+              },
+            ],
+          },
+        ],
+      },
+    ],
+    search: {
+      provider: 'local',
+      options: {
+        locales: {
+          zh: {
+            translations: {
+              button: {
+                buttonText: '搜索',
+                buttonAriaLabel: '搜索',
+              },
+              modal: {
+                displayDetails: '显示详细列表',
+                resetButtonTitle: '重制搜索',
+                backButtonTitle: '关闭搜索',
+                noResultsText: '没有找到相关结果',
+                footer: {
+                  selectText: '选择',
+                  selectKeyAriaLabel: 'enter',
+                  navigateText: '切换',
+                  navigateUpKeyAriaLabel: '上方向键',
+                  navigateDownKeyAriaLabel: '下方向键',
+                  closeText: '关闭',
+                  closeKeyAriaLabel: 'esc',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    darkModeSwitchLabel: '外观',
+    sidebarMenuLabel: '菜单',
+    returnToTopLabel: '返回顶部',
+    langMenuLabel: '更改语言',
+    lastUpdatedText: '最近更新',
+    outlineTitle: '此页面上',
+    docFooter: {
+      next: '下一页',
+      prev: '上一页',
+    },
+  },
+}

docs/.vitepress/theme/components/Cookbook.vue

@@ -0,0 +1,41 @@
+<script setup>
+import { computed } from 'vue'
+import { useData } from 'vitepress'
+import { data as recipes } from '../recipes.data.ts'
+
+const { lang } = useData()
+
+const filteredRecipes = computed(() => recipes.filter(recipe => recipe.lang === lang.value.split('-')[0]))
+</script>
+
+<template>
+  <ul class="grid grid-cols-1 sm:grid-cols-2 gap-8 -mx-4 pt-8">
+    <li
+      v-for="recipe of filteredRecipes"
+      :key="recipe.title"
+      class="list-none important-m-0"
+    >
+      <a
+        :href="recipe.url"
+      >
+        <img
+          :src="recipe.thumbnail"
+          :alt="recipe.title"
+          class="aspect-video object-cover rounded-lg"
+        >
+    
+        <h3>
+          {{ recipe.title }}
+          <span
+            v-for="n in recipe.difficulty"
+            :key="n"
+            aria-label="chili"
+            role="img"
+            class="text-sm"
+          >🌶️</span>
+        
+        </h3></a>
+      <p>{{ recipe.excerpt }}</p>
+    </li>
+  </ul>
+</template>

docs/.vitepress/theme/index.ts

@@ -1,7 +1,7 @@
-import 'uno.css'
+import type { Theme } from 'vitepress'
+import VPTheme from 'vitepress/theme'
 
-// .vitepress/theme/index.ts
-import Theme from 'vitepress/theme'
+import 'uno.css'
 import './custom.css'
 
 import TresLayout from './TresLayout.vue'
@@ -18,11 +18,10 @@ import TresLayout from './TresLayout.vue'
 }) */
 
 export default {
-  ...Theme,
+  ...VPTheme,
 
-  enhanceApp(ctx) {
-    Theme.enhanceApp(ctx)
-    /* ctx.app.use(plausible) */
-  },
+  /* enhanceApp(ctx) {
+    ctx.app.use(plausible)
+  }, */
   Layout: TresLayout,
-}
+} satisfies Theme

docs/.vitepress/theme/recipes.data.ts

@@ -0,0 +1,28 @@
+import { createContentLoader } from 'vitepress'
+
+export interface Recipe {
+  title: string
+  url: string
+  excerpt: string | undefined
+  thumbnail?: string
+  difficulty?: number
+}
+
+declare const data: Recipe[]
+export { data }
+
+export default createContentLoader('/**/cookbook/*.md', {
+  excerpt: true,
+  transform(raw): Recipe[] {
+    return raw
+      .map(({ url, frontmatter, excerpt }) => ({
+        title: frontmatter.title,
+        url,
+        lang: url.split('/')[1].length === 2 ? url.split('/')[1] : 'en',
+        thumbnail: frontmatter.thumbnail,
+        difficulty: frontmatter.difficulty,
+        excerpt: frontmatter.excerpt || frontmatter.description || excerpt,
+      })).filter(recipe => recipe.title)
+      .sort((a, b) => b.title - a.title)
+  },
+})

docs/advanced/caveats.md

@@ -36,13 +36,13 @@ onLoop(({ _delta, elapsed }) => {
 </template>
 ```
 
-If you make a change on the `color` of the `TresMeshStandardMaterial` component, you will see that the change is applied but the rotation is not working anymore. This is because the instance is disposed and created again.
+If you change the `color` attribute of the `TresMeshStandardMaterial` component, you will see that the change is applied but the rotation is not working anymore. This is because the instance is disposed and created again.
 
 :::tip
-So as **rule of thumb** you should reload the page whenever you don't see the changes you made.
+So as **rule of thumb** you should reload the page whenever you don't see your changes reflected.
 :::
 
-That being said we are working on a better solution for this 😁. If you have any idea how to solve this, please let us know.
+That being said we are working on a better solution for this 😁. If you have any idea on how to solve this, please let us know.
 
 You can follow the discussion in [HMR Disposal Discussion](https://github.com/Tresjs/tres/issues/23)
 
@@ -52,7 +52,7 @@ We all love reactivity 💚. It is one of the most powerful features of VueJS. H
 
 Vue reactivity is based on [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy). This allows Vue 3 to automatically track changes to data objects and update the corresponding DOM elements whenever the data changes.
 
-Since we are rendering an scene and updating it in every frame (60FPS), that means that we are updating the scene 60 times per second. If the object to be updated is reactive, Vue will try to update the that objectthat many times. This is not a good idea 😅 and will be detrimental for performance.
+Since we are rendering a scene and updating it in every frame, for example with a rate of 60FPS this means that we are updating the scene 60 times per second. If the object to be updated is reactive, Vue will try to update set object 60 times. This is not a good idea 😅 and will be detrimental for performance.
 
 Here is a benchmark of the difference between using a Proxy object and a plain object.
 

docs/api/composables.md

@@ -222,10 +222,10 @@ const context = useTresContext()
 ### Properties of context
 | Property | Description |
 | --- | --- |
-| **camera** | the currently active camera |
-| **cameras** | the cameras that exist in the scene |
-| **controls** | the controls of your scene |
-| **deregisterCamera** | a method to deregister a camera. This is only required if you manually create a camera. Cameras in the template are deregistered automatically. |
+| **camera** | The currently active camera |
+| **cameras** | The cameras that exist in the scene |
+| **controls** | The controls of your scene |
+| **deregisterCamera** | A method to deregister a camera. This is only required if you manually create a camera. Cameras in the template are deregistered automatically. |
 | **extend** | Extends the component catalogue. See [extending](/advanced/extending) |
 | **raycaster** | the global raycaster used for pointer events |
 | **registerCamera** | a method to register a camera. This is only required if you manually create a camera. Cameras in the template are registered automatically. |

docs/api/tres-canvas.md

@@ -45,7 +45,7 @@ Tres comes with a few presets for the `TresCanvas` component. You can use them b
 
 ### Realistic
 
-The `realistic` preset makes easy to setup the renderer for more realistic 3D scenes.
+The `realistic` preset makes it easy to setup the renderer for more realistic 3D scenes.
 
 ```vue
 <template>

docs/components.d.ts

@@ -8,6 +8,7 @@ export {}
 declare module 'vue' {
   export interface GlobalComponents {
     BlenderCube: typeof import('./.vitepress/theme/components/BlenderCube.vue')['default']
+    Cookbook: typeof import('./.vitepress/theme/components/Cookbook.vue')['default']
     DonutExample: typeof import('./.vitepress/theme/components/DonutExample.vue')['default']
     EmbedExperiment: typeof import('./.vitepress/theme/components/EmbedExperiment.vue')['default']
     ExtendExample: typeof import('./.vitepress/theme/components/ExtendExample.vue')['default']

docs/examples/basic-animations.md → docs/cookbook/basic-animations.md

@@ -1,3 +1,11 @@
+---
+title: Basic Animations
+description: How to use a the useRenderLoop composable to animate your objects.
+author: alvarosabu
+thumbnail: /recipes/animations.png
+difficulty: 0
+---
+
 # Basic Animations
 
 This guide will help you get started with basic animations in TresJS.

docs/examples/groups.md → docs/cookbook/groups.md

@@ -1,3 +1,11 @@
+---
+title: Groups
+description: Learn how to group multiple objects in the scene.
+author: alvarosabu
+thumbnail: /recipes/groups.png
+difficulty: 0
+---
+
 # Group
 
 A `<TresGroup>` is an instance of the [THREE.Group](https://threejs.org/docs/#api/en/objects/Group) class which is almost the same as a [THREE.Object3D](https://threejs.org/docs/#api/en/objects/Object3D) but allows you to **group together multiple objects in the scene** so that they can be manipulated as a single unit (transform, rotation, etc).

docs/cookbook/index.md

@@ -0,0 +1,5 @@
+# Cookbook 🍳🧑‍🍳
+
+Discover guided recipes to help you get started with the basics of using Tres. Each recipe is designed to help you understand the core concepts of Tres and how to use them in your projects.
+
+<Cookbook />

docs/examples/lights-shadows.md → docs/cookbook/lights-shadows.md

@@ -1,3 +1,11 @@
+---
+title: Lights and Shadows
+description: Learn how to add lights and shadows to your scene.
+author: alvarosabu
+thumbnail: /recipes/lights-and-shadows.png
+difficulty: 0
+---
+
 # Light-shadows
 
 This guide will help you get started with simple light and shadows in TresJS.
@@ -8,7 +16,7 @@ We will build a simple scene with three meshes and a plane but only two will hav
 ## Setting up the scene (optional)
 
 We import all the modules that we need, for comfort we can use the orbit-controls from cientos,
-[check here to know how](/examples/orbit-controls).
+[check here to know how](/cookbook/orbit-controls).
 
 Let's put four objects in our scene, one will be the plane that receive shadows, two of them will cast shadows and the last one will not cast any shadow at all.
 
@@ -94,7 +102,7 @@ We could divide this into three steps:
 ```
 ### Set the light to cast shadows
 
-We can simple put the boolean `cast-shadow`, Vue understand this as a `prop` with `true` value
+We can simply add the boolean `cast-shadow`, Vue understands this as a `prop` with a value of `true`.
 
 _The AmbientLight doesn't generate any type of shadow here_
 
@@ -139,7 +147,7 @@ Similarly to the previous step, we set the mesh that we want to cast shadow (our
 </template>
 ```
 
-Now we have all the necessary steps to add shadows to our scene, and if we apply what we learned in [basic animations](/examples/basic-animations), and we add movement to our cube, you will see the shadow is animated as well 🤩
+Now we have all the necessary steps to add shadows to our scene, and if we apply what we learned in [basic animations](/cookbook/basic-animations), and we add movement to our cube, you will see the shadow is animated as well. 🤩
 
 ```vue
 <script setup>

docs/examples/load-models.md → docs/cookbook/load-models.md

@@ -1,3 +1,11 @@
+---
+title: Load Models
+description: Load 3D models into your Tres scenes.
+author: alvarosabu
+thumbnail: /recipes/gltf-model.png
+difficulty: 1
+---
+
 # Load Models
 
 > All models used in this guide are from [Alvaro Saburido](https://sketchfab.com/3d-models/aku-aku-7dfcb6edf10b4098bbb965c56fd3055c).
@@ -11,7 +19,7 @@ For this guide we are going to focus on loading gLTF (GL Transmission Format) mo
 There are several ways to load models on TresJS:
 
 ::: warning
-Please note that the examples above we use top level await, make sure you wrap it with a [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) component. See Suspense for more information. .
+Please note that in the examples above we use top level `await`s. Make sure to wrap such code with a [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) component. See Suspense for more information.
 :::
 
 ## Using `useLoader`
@@ -31,7 +39,7 @@ Then you can pass the model scene to a TresJS [`primitive`](/advanced/primitive)
 
 ```html{2}
 <TresCanvas>
-    <primitive :object="scene" />
+  <primitive :object="scene" />
 </TresCanvas>
 ```
 
@@ -57,7 +65,7 @@ import { useGLTF } from '@tresjs/cientos'
 const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf', { draco: true })
 ```
 
-Alternatively you can easily select Objects inside the model using `nodes` property
+Alternatively you can easily select objects inside the model using the `nodes` property.
 
 ```vue
 <script setup lang="ts">
@@ -81,7 +89,7 @@ const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gl
 
 ## Using `GLTFModel`
 
-The `GLTFModel` component is a wrapper around `useGLTF` that's available from the [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package.
+The `GLTFModel` component is a wrapper around the `useGLTF` composable, which is available from the [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package.
 
 ```vue{2,9}
 <script setup lang="ts">
@@ -121,7 +129,7 @@ Then is as straightforward as adding the scene to your scene:
 
 ## FBXModel
 
-The `FBXModel` component is a wrapper around `useFBX` that's available from the [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package. It's similar usage to `GLTFModel`:
+The `FBXModel` component is a wrapper around the `useFBX` composable, which is available from the [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) package. It's similar in usage to `GLTFModel`:
 
 ```vue{2,9}
 <script setup lang="ts">

docs/examples/load-textures.md → docs/cookbook/load-textures.md

@@ -1,3 +1,11 @@
+---
+title: Load Textures
+description: Add texture maps to your TresJS objects.
+author: alvarosabu
+thumbnail: /recipes/load-textures.png
+difficulty: 1
+---
+
 # Load Textures
 
 > All textures used in this example are from [ambientcg](https://ambientcg.com/).

docs/examples/orbit-controls.md → docs/cookbook/orbit-controls.md

@@ -1,3 +1,11 @@
+---
+title: OrbitControls
+description: How to use OrbitControls to interact with the scene.
+author: alvarosabu
+thumbnail: /recipes/orbit-controls.png
+difficulty: 1
+---
+
 # 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==" />
@@ -31,41 +39,56 @@ extend({ OrbitControls })
 
 Now you can use the `TresOrbitControls` component in your scene.
 
-```vue
+::: code-group
+
+```vue [OrbitControls.vue]
 <template>
-  <TresCanvas
-    shadows
-    alpha
-  >
-    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
-    <TresOrbitControls
-      v-if="state.renderer"
-      :args="[state.camera, state.renderer?.domElement]"
-    />
-  </TresCanvas>
+  <TresOrbitControls
+    v-if="renderer"
+    :args="[camera, renderer?.domElement]"
+  />
 </template>
 ```
+:::
 
-Since [OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) needs a reference to the camera and the renderer, you need to pass them as arguments.
+Since [OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) needs a reference to the camera and the renderer. You need to pass those as arguments. You can use the [useTresContext](/api/composables#usetrescontext) composable to get the camera and the renderer.
 
-You can use the [useTres](/api/composables#usetres) composable to get the camera and the renderer.
+::: warning
+`useTresContext` can be only be used inside of a `TresCanvas` since `TresCanvas` acts as the provider for the context data. Thats why we created a subcomponent called `OrbitControls.vue`. See more about [context](/api/composables#usetrescontext).
+:::
 
 ```ts
-import { useTres } from '@tresjs/core'
+import { useTresContext } from '@tresjs/core'
 
-const { state } = useTres()
+const { camera, renderer } = useTresContext()
 ```
 
 So the final code would be something like this:
 
-```vue
+::: code-group
+
+```vue [OrbitControls.vue]
 <script setup lang="ts">
-import { extend, useTres } from '@tresjs/core'
+import { extend, useTresContext } from '@tresjs/core'
 import { OrbitControls } from 'three/addons/controls/OrbitControls'
 
 extend({ OrbitControls })
 
-const { state } = useTres()
+const { camera, renderer } = useTresContext()
+</script>
+
+<template>
+  <TresOrbitControls
+    v-if="renderer"
+    :args="[camera, renderer?.domElement]"
+  />
+</template>
+```
+
+```vue [App.vue] {3,12}
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import OrbitControls from './OrbitControls.vue'
 </script>
 
 <template>
@@ -74,23 +97,28 @@ const { state } = useTres()
     alpha
   >
     <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
-    <TresOrbitControls
-      v-if="state.renderer"
-      :args="[state.camera, state.renderer?.domElement]"
-    />
+    <OrbitControls />
+    <TresGridHelper :args="[10, 10]" />
   </TresCanvas>
 </template>
 ```
+:::
+
 
 ## OrbitControls from `cientos`
 
 Here is where the fancy part begins. ✨  
-The `cientos` package provides a component called `<OrbitControls />` that is a wrapper of the `OrbitControls` from the [`three-stdlib`](https://github.com/pmndrs/three-stdlib) module.
+The `cientos` package provides a component called `<OrbitControls />` which is a wrapper of the `OrbitControls` from the [`three-stdlib`](https://github.com/pmndrs/three-stdlib) module.
 
 The nicest part? You don't need to extend the catalog or pass any arguments.  
 It just works. 💯
 
-```vue
+```vue {3,12}
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import { OrbitControls } from '@tresjs/cientos'
+</script>
+
 <template>
   <TresCanvas
     shadows

docs/examples/shaders.md → docs/cookbook/shaders.md

@@ -12,8 +12,8 @@ _Basic knowledge of how shaders work is necessary_
 
 ## Setting up the scene (optional)
 
-We import all the modules that we need, for comfort we can use the orbit-controls from cientos,
-[look here to see how](/examples/orbit-controls).
+We import all the modules that we need. To make it more convenient we will import and use the orbit-controls from cientos,
+[look here to see how](/cookbook/orbit-controls).
 
 Now, let's put our camera in the `[11,11,11]` position.
 
@@ -110,7 +110,7 @@ void main() {
 
 ## Animating the blob
 
-Similar to what we learn in the [Basic animations](/examples/basic-animations) example, we start by referencing our blob, using [Template Ref](https://vuejs.org/guide/essentials/template-refs.html)
+Similar to what we learn in the [Basic animations](/cookbook/basic-animations) example, we start by referencing our blob, using [Template Ref](https://vuejs.org/guide/essentials/template-refs.html)
 
 ```vue
 <script setup lang="ts">
@@ -134,7 +134,7 @@ const blobRef = shallowRef(null)
       :position="[0, 4, 0]"
     >
       <TresSphereGeometry :args="[2, 32, 32]" />
-      <TresShaderMaterial />
+      <TresShaderMaterial :vertexShader="vertexShader" :fragmentShader="fragmentShader" :uniforms="uniforms"/>
     </TresMesh>
   </TresCanvas>
 </template>
@@ -155,7 +155,7 @@ onLoop(({ elapsed }) => {
  //...
 ```
 
-And that it is, we have our basic shader running smoothly.
+And that's it, we have our basic shader running smoothly. 🎉
 
 ## Using GLSL vite-pluging (optional)
 
@@ -171,4 +171,4 @@ And you could have a structure similar to this:
 │   ├── shaders/
 │       ├── vertexShader.glsl
 │       ├── fragmentShader.glsl
-```
+```

docs/examples/text-3d.md → docs/cookbook/text-3d.md

@@ -1,3 +1,11 @@
+---
+title: Text 3D
+description: Add 3D text with ease
+author: alvarosabu
+thumbnail: /recipes/text-3d.png
+difficulty: 1
+---
+
 # Text3D
 
 [TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) is one of the ways we can add 3D text in our scene.
@@ -29,7 +37,7 @@ import { TextGeometry } from 'three/addons/geometries/TextGeometry'
 extend({ TextGeometry })
 ```
 
-[TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) needs a only one required argument the font, you can see an example below.
+[TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) requires only one argument - the font. You can find an example below.
 
 ```js
 const fontPath = 'https://raw.githubusercontent.com/Tresjs/assets/main/fonts/FiraCodeRegular.json'
@@ -48,7 +56,7 @@ const font = await new Promise((resolve, reject) => {
 })
 ```
 
-Now you can use the `TresTextGeometry` component inside a TresMesh in your scene
+Next you can use the `TresTextGeometry` component inside a TresMesh in your scene
 
 ```vue
 <template>
@@ -81,7 +89,7 @@ const fontOptions = {
 }
 ```
 
-We can also pass a matcapTexture to add final details, using the TresMeshNormalMaterial inside the TresMesh
+We can also pass a matcapTexture to add final details, using the TresMeshNormalMaterial inside the TresMesh.
 
 ```ts
 const matcapTexture = await useTexture(['https://raw.githubusercontent.com/Tresjs/assets/main/textures/matcaps/7.png'])
@@ -92,7 +100,7 @@ const matcapTexture = await useTexture(['https://raw.githubusercontent.com/Tresj
   </TresMesh>
 ```
 
-So the final code would be something like this:
+So the final code would look something like this:
 
 ```vue
 <script setup lang="ts">
@@ -148,11 +156,11 @@ const matcapTexture = await useTexture(['https://raw.githubusercontent.com/Tresj
 </template>
 ```
 
-I know seems like a lot of work, but good news there is a much more simple way
+We know this seems like a lot of work, but good news is, there is a much more simple way
 
 ## TextGeometry from `cientos`
 
-The `cientos` package provides a component called `<Text3D />` that is a wrapper of the `TextGeometry` from the [`three-stdlib`](https://github.com/pmndrs/three-stdlib) module.
+The `cientos` package provides a component called `<Text3D />`, which is a wrapper of the `TextGeometry` from the [`three-stdlib`](https://github.com/pmndrs/three-stdlib) module.
 
 The nicest part? You don't need to extend the catalog and just pass the font argument.
 It just works. 💯 (if not text is provided, the text will be TresJS)
@@ -174,7 +182,7 @@ We can pass the options as props
 <Text3D :font="fontPath" :text="my 3d text" :size="0.8" />
 ```
 
-in case the options are not provided the default values are:
+in case the options are not provided, the default values will be:
 
 ```js
 size: 0.5,
@@ -187,7 +195,7 @@ bevelOffset: 0,
 bevelSegments: 4,
 ```
 
-By default text in ThreeJS starts at the mesh initial position, so it's [0,0,0] the text will start there but we can center it by just passing the flag "center"
+By default text in ThreeJS starts at the mesh initial position, so it's [0,0,0] and the text will start there but we can center it by just passing the flag "center"
 
 ```vue
 <Text3D :font="fontPath" :text="my 3d text" center />

docs/de/examples/basic-animations.md → docs/de/cookbook/basic-animations.md

@@ -1,3 +1,11 @@
+---
+title: Einfache Animationen
+description: Wie man das useRenderLoop Composable verwendet, um Objekte zu animieren.
+author: alvarosabu
+thumbnail: /recipes/animations.png
+difficulty: 0
+---
+
 # Einfache Animationen
 
 Diese Anleitung wird dir helfen, mit grundlegenden Animationen in TresJS zu beginnen.

docs/de/examples/groups.md → docs/de/cookbook/groups.md

@@ -1,3 +1,11 @@
+---
+title: Gruppen
+description: Erfahre, wie man mehrere Objekte in der Szene gruppieren kann.
+author: alvarosabu
+thumbnail: /recipes/groups.png
+difficulty: 0
+---
+
 # Gruppen
 
 Eine `<TresGroup>` ist eine Instanz der Klasse [THREE.Group](https://threejs.org/docs/#api/en/objects/Group), die fast das Gleiche wie ein [THREE.Object3D](https://threejs.org/docs/#api/en/objects/Object3D) ist. Sie ermöglicht es dir, **mehrere Objekte in der Szene zu gruppieren**, sodass sie gebündelt manipuliert werden können (Transformation, Rotation, etc...)."

docs/de/cookbook/index.md

@@ -0,0 +1,5 @@
+# Kochbuch (Cookbook) 🍳🧑‍🍳
+
+In diesem "Kochbuch" findest du erlesene Rezepte, um den Einstieg in die Grundlagen von Tres zu erleichtern. Jedes Rezept ist darauf ausgelegt, Kernkonzepte von Tres zu vermitteln und zu zeigen, wie die Anwendung aussieht.
+
+<Cookbook />

docs/de/examples/lights-shadows.md → docs/de/cookbook/lights-shadows.md

@@ -1,3 +1,11 @@
+---
+title: Licht und Schatten
+description: Erfahre, wie man Lichter und Schatten zu einer Szene hinzufügen kann.
+author: alvarosabu
+thumbnail: /recipes/lights-and-shadows.png
+difficulty: 0
+---
+
 # Licht und Schatten
 
 Diese Anleitung wird dir helfen, mit einfachen Lichtern und Schatten in TresJS zu beginnen.
@@ -8,7 +16,7 @@ Wir werden eine einfache Szene mit drei Meshes und einer Ebene erstellen, aber n
 
 ## Einrichten der Szene (optional)
 
-Wir importieren alle Module, die wir benötigen. Zusätzlich können wir Orbit-Controls von Cientos verwenden um unsere Szene besser zu beobachten, [siehe hier wie das geht](/de/examples/orbit-controls).
+Wir importieren alle Module, die wir benötigen. Zusätzlich können wir Orbit-Controls von Cientos verwenden um unsere Szene besser zu beobachten, [siehe hier wie das geht](/de/cookbook/orbit-controls).
 
 Das erste Objekt unserer Szene wird die Ebene sein, die Schatten empfängt. Zwei weitere Objekte werden Schatten werfen und das letzte wird überhaupt keinen Schatten werfen.
 
@@ -142,7 +150,7 @@ _Umgebungslicht erzeugt hier keine Art von Schatten_
 </template>
 ```
 
-Jetzt haben wir alle notwendigen Schritte, um Schatten zu unserer Szene hinzuzufügen abgeschlossen. Wenn wir nun das, was wir in [grundlegenden Animationen](/de/examples/basic-animations) gelernt haben, anwenden und unseren Würfel bewegen, wirst du sehen, dass der Schatten auch animiert wird 🤩
+Jetzt haben wir alle notwendigen Schritte, um Schatten zu unserer Szene hinzuzufügen abgeschlossen. Wenn wir nun das, was wir in [grundlegenden Animationen](/de/cookbook/basic-animations) gelernt haben, anwenden und unseren Würfel bewegen, wirst du sehen, dass der Schatten auch animiert wird 🤩
 
 ```vue
 <script setup>

docs/de/examples/load-models.md → docs/de/cookbook/load-models.md

@@ -1,3 +1,11 @@
+---
+title: Modelle laden
+description: Lade 3D-Modelle in deine Tres-Szenen.
+author: alvarosabu
+thumbnail: /recipes/gltf-model.png
+difficulty: 1
+---
+
 # Modelle laden
 
 > Alle Modelle, die in dieser Anleitung verwendet werden, stammen von [Alvaro Saburido](https://sketchfab.com/3d-models/aku-aku-7dfcb6edf10b4098bbb965c56fd3055c).

docs/de/examples/load-textures.md → docs/de/cookbook/load-textures.md

@@ -1,3 +1,11 @@
+---
+title: Texturen laden
+description: Füge Texture-Maps zu deinen TresJS-Objekten hinzu.
+author: alvarosabu
+thumbnail: /recipes/load-textures.png
+difficulty: 1
+---
+
 # Texturen laden
 
 > Alle Texturen in diesem Beispiel stammen von [ambientcg](https://ambientcg.com/).

docs/de/examples/orbit-controls.md → docs/de/cookbook/orbit-controls.md

@@ -1,3 +1,11 @@
+---
+title: OrbitControls
+description: Wie man OrbitControls verwendet, um mit der Szene zu interagieren.
+author: alvarosabu
+thumbnail: /recipes/orbit-controls.png
+difficulty: 1
+---
+
 # 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==" />
@@ -30,24 +38,22 @@ extend({ OrbitControls })
 
 Jetzt kannst du die Komponente `TresOrbitControls` in deiner Szene verwenden.
 
-```vue{7-10}
+::: code-group
+
+```vue [OrbitControls.vue]
 <template>
-  <TresCanvas
-    shadows
-    alpha
-  >
-    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
-    <TresOrbitControls
-      v-if="state.renderer"
-      :args="[state.camera, state.renderer?.domElement]"
-    />
-  </TresCanvas>
+  <TresOrbitControls
+    v-if="renderer"
+    :args="[camera, renderer?.domElement]"
+  />
 </template>
 ```
 
-Da [OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) eine Referenz zur Kamera und zum Renderer benötigt, musst du diese als Argumente übergeben.
+Da [OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) eine Referenz zur Kamera und zum Renderer benötigen, musst du diese als Argumente übergeben. Du kannst das Composable [useTresContext](/de/api/composables#usetrescontext) verwenden, um die Kamera und den Renderer zu erhalten.
 
-Du kannst das Composable [useTres](/de/api/composables#usetrescontext) verwenden, um die Kamera und den Renderer zu erhalten.
+::: warning
+`useTresContext` kann nur innerhalb eines `TresCanvas` verwendet werden, da `TresCanvas` die Kontext-Daten bereitstellt. Deshalb haben wir eine Unterkomponente namens `OrbitControls.vue` implementiert. Erfahre mehr über [context](/de/api/composables#usetrescontext).
+:::
 
 ```ts
 import { useTres } from '@tresjs/core'
@@ -57,14 +63,30 @@ const { state } = useTres()
 
 Dann würde der finale Code etwa so aussehen:
 
-```vue
+::: code-group
+
+```vue [OrbitControls.vue]
 <script setup lang="ts">
-import { extend, useTres } from '@tresjs/core'
+import { extend, useTresContext } from '@tresjs/core'
 import { OrbitControls } from 'three/addons/controls/OrbitControls'
 
 extend({ OrbitControls })
 
-const { state } = useTres()
+const { camera, renderer } = useTresContext()
+</script>
+
+<template>
+  <TresOrbitControls
+    v-if="renderer"
+    :args="[camera, renderer?.domElement]"
+  />
+</template>
+```
+
+```vue [App.vue] {3,12}
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import OrbitControls from './OrbitControls.vue'
 </script>
 
 <template>
@@ -73,13 +95,13 @@ const { state } = useTres()
     alpha
   >
     <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
-    <TresOrbitControls
-      v-if="state.renderer"
-      :args="[state.camera, state.renderer?.domElement]"
-    />
+    <OrbitControls />
+    <TresGridHelper :args="[10, 10]" />
   </TresCanvas>
 </template>
 ```
+:::
+
 
 ## OrbitControls von `cientos`
 
@@ -89,7 +111,12 @@ Das Paket `cientos` bietet eine Komponente namens `<OrbitControls />`, die ein W
 Das Beste daran? Du musst den Katalog nicht erweitern oder irgendwelche Argumente übergeben.
 Es funktioniert einfach. 💯
 
-```vue
+```vue {3,12}
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import { OrbitControls } from '@tresjs/cientos'
+</script>
+
 <template>
   <TresCanvas
     shadows

docs/de/examples/shaders.md → docs/de/cookbook/shaders.md

@@ -1,3 +1,11 @@
+---
+title: Shaders
+description: Shaders bieten eine Welt voller Möglichkeiten.
+author: alvarosabu
+thumbnail: /recipes/shaders.png
+difficulty: 2
+---
+
 # Shaders
 
 Diese Anleitung wird dir helfen, deine ersten Schritte mit Shadern in TresJS zu machen.
@@ -12,7 +20,7 @@ _Es sind Grundkenntnisse über Shader erforderlich_
 
 ## Einrichten der Szene (optional)
 
-Wir importieren alle Module, die wir benötigen. Zusätzlich können wir die Orbit-Controls von Cientos verwenden.  [Siehe hier, wie das geht](/de/examples/orbit-controls).
+Wir importieren alle Module, die wir benötigen. Zusätzlich können wir die Orbit-Controls von Cientos verwenden.  [Siehe hier, wie das geht](/de/cookbook/orbit-controls).
 
 Nun positionieren wir unsere Kamera an der Position `[11,11,11]`.
 
@@ -109,7 +117,7 @@ void main() {
 
 ## Animieren des Blobs
 
-Ähnlich wie wir im Beispiel [Grundlegende Animationen](/de/examples/basic-animations) gelernt haben, beginnen wir, indem wir unseren Blob mit einer [Template-Ref](https://vuejs.org/guide/essentials/template-refs.html) referenzieren.
+Ähnlich wie wir im Beispiel [Grundlegende Animationen](/de/cookbook/basic-animations) gelernt haben, beginnen wir, indem wir unseren Blob mit einer [Template-Ref](https://vuejs.org/guide/essentials/template-refs.html) referenzieren.
 <!-- TODO: Ich bin verwirrt - text und code stimmen nicht überein -->
 
 ```vue

docs/de/examples/text-3d.md → docs/de/cookbook/text-3d.md

@@ -1,3 +1,11 @@
+---
+title: Text 3D
+description: Füge mühelos 3D-Text hinzu
+author: alvarosabu
+thumbnail: /recipes/text-3d.png
+difficulty: 1
+---
+
 # Text laden
 
 [TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) ist eine der Möglichkeiten, wie wir 3D-Text zu unserer Szene hinzufügen können.

docs/de/guide/index.md

@@ -64,9 +64,9 @@ Das ist notwendig, damit der Templatecompiler mit dem benutzerdefinierten Render
 
 ## Probiere es online aus
 
-### Sandbox
+### Playground
 
-Du kannst TresJS online mit der offiziellen [Sandbox](https://play.tresjs.org/) ausprobieren:
+Du kannst TresJS online mit der offiziellen [Playground](https://play.tresjs.org/) ausprobieren:
 
 <iframe src="https://play.tresjs.org/" class="w-full rounded shadow-lg outline-none border-none aspect-4/3"></iframe>
 
@@ -76,13 +76,12 @@ Wir haben einen neuen [StackBlitz](https://stackblitz.com/) Startpunkt, um TresJ
 
 ![](/stackblitz-starter.png)
 
-<StackBlitzEmbed projectId="tresjs-basic" />
 
-## Playground
+## Labs
 
-Wir haben auch einen Playground, wo du TresJS online testen kannst. Probiere es [hier](https://playground.tresjs.org/) aus.
+Wir haben auch ein Showroom-Labor mit Beispielen, die mit TresJS erstellt wurden. Probiere es [hier](https://playground.tresjs.org/) aus.
 
-![](/playground.png)
+![](/tresjs-lab.png)
 
 ## Motivation
 

docs/de/guide/nuxt.md

@@ -30,7 +30,7 @@ yarn add three @tresjs/nuxt
 
 - 🤓 Automatischer Import von Komponenten und Composables aus dem [TresJS-Ökosystem](https://github.com/orgs/Tresjs/repositories)
 - `TresCanvas` ist nur auf dem Client verfügbar, daher ist es nicht notwendig, `.client` zum Namen der Komponente hinzuzufügen oder `<ClientOnly />` zu verwenden
-- Konfiguriert automatisch den Vue-Compiler, um TresJS-Komponenten zu unterstützen, siehe [warum](/de/guide/troubleshooting.html#fehler-beim-auflosen-des-komponenten-trescomponent)?
+- Konfiguriert automatisch den Vue-Compiler, um TresJS-Komponenten zu unterstützen, siehe [warum](/de/guide/troubleshooting)
 - All die DX-Magie, die mit Nuxt kommt ✨
 
 ## Verwendung

docs/debug/devtools.md

@@ -19,7 +19,7 @@ From <Badge text="^3.7.0" /> we are introducing the TresJS Devtools, a customize
 ### Features
 
 - **Scene Inspector**: Inspect the current scene and its components using a tree view similar to the Vue Devtools component inspector.
-- **Memory Allocation**: See how much memory is being by the components.
+- **Memory Allocation**: See how much memory is being consumed by the components.
 - **Object Inspector**: Inspect the properties of the selected object in the scene, including its children.
 - **Editable Properties**: And yes, you can edit the properties of the selected object and see the changes in real-time.
 

docs/directives/v-always-look-at.md

@@ -18,13 +18,13 @@ import { Box, vAlwaysLookAt } from '@tresjs/cientos'
   </TresCanvas>
 </template>
 ```
-No matter where the Box move will always look-at the position [0,0,0]
+No matter where the `Box` move will always look-at the position [0,0,0]
 
 ### Why not use the in built method look-at?
 
 You could ask, this is fine but I can use the `:look-at` method directly in the component, why should I need this?
 
-The answers is that with the method `:look-at` you will indicated to look at that position just once, when the instance is mounted, then if the object changes this will not get updated
+The answers is that with the method `:look-at` you will indicate to look at that position just once, when the instance is mounted, then if the object changes this will not get updated.
 
 ### You can look at other instance too!
 

docs/directives/v-light-helper.md

@@ -1,6 +1,6 @@
 # v-light-helper 🔆
 
-With the new directive v-light-helper provided by **TresJS**, you can add fast the respective helper to your lights with just one line of code 😍.
+With the new directive v-light-helper provided by **TresJS**, you can quickly add the respective helper to your lights with just one line of code 😍.
 
 The following lights are supported:
 - DirectionalLight

docs/directives/v-log.md

@@ -27,7 +27,7 @@ watch(sphereRef, (value) => {
 </template>
 ```
 
-And is A LOT of code just for a simple log right?
+Don't you think this is A LOT of code just for a simple log?
 
 ## Usage
 
@@ -50,4 +50,4 @@ import { OrbitControls, Sphere, vLog } from '@tresjs/cientos'
 </template>
 ```
 
-Note that you can pass a modifier with the name of a property, for example `v-log:material`, and will log directly the `material` property 😍
+Note that you can pass a modifier with the name of a property, for example `v-log:material`, and it will directly log the `material` property 😍

docs/es/examples/basic-animations.md → docs/es/cookbook/basic-animations.md

@@ -1,4 +1,12 @@
-# Basic Animations
+---
+title: Animaciones básicas
+description: Cómo usar el composable useRenderLoop para animar tus objetos.
+author: alvarosabu
+thumbnail: /recipes/animations.png
+difficulty: 0
+---
+
+# Animaciones básicas
 
 Esta guía te ayudará a comenzar con animaciones básicas en TresJS.
 

docs/es/examples/groups.md → docs/es/cookbook/groups.md

@@ -1,4 +1,12 @@
-# Grupo
+---
+title: Grupos
+description: Aprende cómo agrupar varios objetos en la escena.
+author: alvarosabu
+thumbnail: /recipes/groups.png
+difficulty: 0
+---
+
+# Grupos
 
 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).
 

docs/es/cookbook/index.md

@@ -0,0 +1,5 @@
+# Recetario (Cookbook) 🍳🧑‍🍳
+
+Descubre recetas guiadas para ayudarte a comenzar con los conceptos básicos de usar Tres. Cada receta está diseñada para ayudarte a comprender los conceptos fundamentales de Tres y cómo utilizarlos en tus proyectos.
+
+<Cookbook />

docs/es/examples/lights-shadows.md → docs/es/cookbook/lights-shadows.md

@@ -1,3 +1,11 @@
+---
+title: Luces y sombras
+description: Aprende cómo agregar luces y sombras a tu escena.
+author: alvarosabu
+thumbnail: /recipes/lights-and-shadows.png
+difficulty: 0
+---
+
 # Luces y sombras
 
 Esta guía te ayudará a comenzar con luces y sombras simples en TresJS.
@@ -9,7 +17,7 @@ Construiremos una escena simple con tres mallas y un plano, pero solo dos tendr
 ## 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).
+[ver aquí para saber cómo](/cookbook/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.
 
@@ -140,7 +148,7 @@ De manera similar al paso anterior, configuramos la malla que queremos que proye
 </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 🤩
+Ahora tenemos todos los pasos necesarios para agregar sombras a nuestra escena, y si aplicamos lo que aprendimos en [animaciones básicas](/cookbook/basic-animations), y agregamos movimiento a nuestro cubo, verás que la sombra también se anima 🤩
 
 ```vue
 <script setup>

docs/es/examples/load-models.md → docs/es/cookbook/load-models.md

@@ -1,3 +1,11 @@
+---
+title: Cargar Modelos
+description: Carga modelos 3D en tus escenas de Tres.
+author: alvarosabu
+thumbnail: /recipes/gltf-model.png
+difficulty: 1
+---
+
 # Cargar Modelos
 
 > Todos los modelos utilizados en esta guía son de [Alvaro Saburido](https://sketchfab.com/3d-models/aku-aku-7dfcb6edf10b4098bbb965c56fd3055c).

docs/es/examples/load-textures.md → docs/es/cookbook/load-textures.md

@@ -1,3 +1,11 @@
+---
+title: Cargar Texturas
+description: Agrega mapas de texturas a tus objetos en TresJS.
+author: alvarosabu
+thumbnail: /recipes/load-textures.png
+difficulty: 1
+---
+
 # Cargar Texturas
 
 > Todas las texturas utilizadas en este ejemplo son de [ambientcg](https://ambientcg.com/).

docs/es/examples/orbit-controls.md → docs/es/cookbook/orbit-controls.md

@@ -1,3 +1,11 @@
+---
+title: OrbitControls
+descripción: Cómo usar OrbitControls para interactuar con la escena.
+author: alvarosabu
+thumbnail: /recipes/orbit-controls.png
+difficulty: 1
+---
+
 # 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==" />
@@ -31,42 +39,56 @@ extend({ OrbitControls })
 
 Ahora puedes usar el componente `TresOrbitControls` en tu escena.
 
-```vue
+::: code-group
+
+```vue [OrbitControls.vue]
 <template>
-  <TresCanvas
-    shadows
-    alpha
-  >
-    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
-    <TresOrbitControls
-      v-if="state.renderer"
-      :args="[state.camera, state.renderer?.domElement]"
-    />
-  </TresCanvas>
+  <TresOrbitControls
+    v-if="renderer"
+    :args="[camera, renderer?.domElement]"
+  />
 </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.
+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 [useTresContext](/es/api/composables#usetrescontext) para obtener la cámara y el renderizador.
 
+::: warning
+`useTresContext` solo puede ser utilizado dentro de un `TresCanvas` ya que `TresCanvas` actúa como proveedor de los datos de contexto. Es por eso que creamos un subcomponente llamado `OrbitControls.vue`. Obtén más información sobre [contexto](/api/composables#usetrescontext).
+:::
 
 ```ts
-import { useTres } from '@tresjs/core'
+import { useTresContext } from '@tresjs/core'
 
-const { state } = useTres()
+const { camera, renderer } = useTresContext()
 ```
 
-Entonces, el código final sería algo como esto:
+So the final code would be something like this:
 
-```vue
+::: code-group
+
+```vue [OrbitControls.vue]
 <script setup lang="ts">
-import { extend, useTres } from '@tresjs/core'
+import { extend, useTresContext } from '@tresjs/core'
 import { OrbitControls } from 'three/addons/controls/OrbitControls'
 
 extend({ OrbitControls })
 
-const { state } = useTres()
+const { camera, renderer } = useTresContext()
+</script>
+
+<template>
+  <TresOrbitControls
+    v-if="renderer"
+    :args="[camera, renderer?.domElement]"
+  />
+</template>
+```
+
+```vue [App.vue] {3,12}
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import OrbitControls from './OrbitControls.vue'
 </script>
 
 <template>
@@ -75,13 +97,13 @@ const { state } = useTres()
     alpha
   >
     <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
-    <TresOrbitControls
-      v-if="state.renderer"
-      :args="[state.camera, state.renderer?.domElement]"
-    />
+    <OrbitControls />
+    <TresGridHelper :args="[10, 10]" />
   </TresCanvas>
 </template>
 ```
+:::
+
 
 ## OrbitControls de `cientos`
 
@@ -91,7 +113,12 @@ El paquete `cientos` proporciona un componente llamado `<OrbitControls />` que e
 ¿Lo mejor? No necesitas ampliar el catálogo ni pasar ningún argumento.  
 Simplemente funciona. 💯
 
-```vue
+```vue {3,12}
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import { OrbitControls } from '@tresjs/cientos'
+</script>
+
 <template>
   <TresCanvas
     shadows

docs/es/examples/shaders.md → docs/es/cookbook/shaders.md

@@ -1,3 +1,11 @@
+---
+title: Shaders
+description: Shaders abren un mundo de posibilidades.
+author: alvarosabu
+thumbnail: /recipes/shaders.png
+difficulty: 2
+---
+
 # Shaders
 
 Esta guía te ayudará a comenzar con los shaders en TresJS.
@@ -13,7 +21,7 @@ _Es necesario tener conocimientos básicos sobre cómo funcionan los shaders_
 ## 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).
+[Consulta aquí para ver cómo](/cookbook/orbit-controls).
 
 Ahora, coloquemos nuestra cámara en la posición `[11,11,11]`.
 
@@ -110,7 +118,7 @@ void main() {
 
 ## 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)
+Similar a lo que aprendimos en el ejemplo de [Animaciones básicas](/cookbook/basic-animations), comenzamos haciendo referencia a nuestro blob utilizando [Template Ref](https://vuejs.org/guide/essentials/template-refs.html)
 
 ```vue
 <script setup lang="ts">

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

@@ -1,4 +1,12 @@
-# Texto3D
+---
+title: Texto 3D
+description: Añade texto en 3D a tu escena.
+author: alvarosabu
+thumbnail: /recipes/text-3d.png
+difficulty: 1
+---
+
+# Text3D
 
 [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.
 

docs/es/directives/v-always-look-at.md

@@ -0,0 +1,61 @@
+# v-always-look-at 👀
+
+Con la nueva directiva v-always-look-at proporcionada por **TresJS**, puedes agregar fácilmente un comando [Object3D](https://tresjs.org/docs/index.html?q=object#api/en /core/Object3D) para mirar siempre una posición específica, esto podría pasarse como Vector3 o Array.
+
+## Uso
+
+```vue{3,9}
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import { Box, vAlwaysLookAt } from '@tresjs/cientos'
+</script>
+<template>
+    <TresCanvas >
+      <TresPerspectiveCamera :position="[0, 2, 5]" />
+      <Box
+        v-always-look-at="new Vector3(0, 0, 0)"
+      />
+  </TresCanvas>
+</template>
+```
+No importa dónde se mueva la caja, siempre se observará la posición [0,0,0]
+
+### ¿Por qué no utilizar el método integrado de revisión?
+
+Podrías preguntar, esto está bien, pero puedo usar el método `:look-at` directamente en el componente, ¿por qué debería necesitar esto?
+
+La respuesta es que con el método `:look-at` se te indicará mirar esa posición solo una vez, cuando la instancia esté montada, luego si el objeto cambia esto no se actualizará.
+
+### ¡Puedes observar otra instancia también!
+
+Otra ventaja es que puedes observar una instancia en movimiento, por ejemplo con la cámara, así:
+
+```vue{4,6,20,23}
+<script setup lang="ts">
+import { shallowRef } from 'vue'
+import { TresCanvas, useRenderLoop } from '@tresjs/core'
+import { Box, vAlwaysLookAt } from '@tresjs/cientos'
+
+const sphereRef = shallowRef()
+
+const { onLoop } = useRenderLoop()
+
+// here we update the position of the sphere and the camera will always follow the object
+onLoop(({ elapsed }) => {
+  if (sphereRef.value) {
+    sphereRef.value.value.position.y = Math.sin(elapsed) * 1.5
+  }
+})
+</script>
+<template>
+    <TresCanvas >
+      <TresPerspectiveCamera :position="[0, 2, 5]"
+        v-always-look-at="sphereRef"
+      />
+      <Sphere
+        ref="sphereRef"
+        :scale="0.5"
+      />
+  </TresCanvas>
+</template>
+```

docs/es/directives/v-distance-to.md

@@ -0,0 +1,36 @@
+# v-distance-to
+
+¿Has intentado calcular la distancia entre dos Object3D?
+
+Con la nueva directiva `v-distance-to` es más fácil que nunca, solo debes indicar el objeto objetivo para realizar la medida y el resultado aparecerá en tu consola.
+
+Además, se creará una flecha para indicar qué objetos estás midiendo.
+
+```vue{2,8,13}
+<script setup lang="ts">
+import { OrbitControls, Sphere, vLog } from '@tresjs/cientos'
+</script>
+<template>
+  <TresCanvas v-bind="gl">
+    <TresPerspectiveCamera :position="[0, 2, 5]" />
+    <Sphere
+      ref="sphere1Ref"
+      :position="[-2, slider, 0]"
+      :scale="0.5"
+    />
+    <Sphere
+      v-distance-to="sphere1Ref"
+      :position="[2, 0, 0]"
+      :scale="0.5"
+    />
+    <TresGridHelper :args="[10, 10]" />
+    <OrbitControls />
+  </TresCanvas>
+</template>
+```
+
+El uso de `v-distance-to` es reactivo, por lo que funciona perfectamente con @tres/leches 🍰.
+
+::: warning
+`v-distance-to` no medirá un objeto en movimiento dentro del renderLoop.
+:::

docs/es/directives/v-light-helper.md

@@ -0,0 +1,34 @@
+# v-light-helper 🔆
+
+Con la nueva directiva v-light-helper proporcionada por **TresJS**, puedes agregar rápidamente el ayudante respectivo a tus luces con solo una línea de código 😍.
+
+Se admiten las siguientes luces:
+- DirectionalLight
+- PointLight
+- SpotLight
+- HemisphereLight
+
+## Uso
+
+```vue{2,8,11,14,17}
+<script setup lang="ts">
+import { OrbitControls, Sphere, vLightHelper } from '@tresjs/cientos'
+</script>
+<template>
+  <TresCanvas >
+    <TresPerspectiveCamera :position="[0, 2, 5]" />
+    <TresDirectionalLight
+      v-light-helper
+    />
+    <TresPointLight
+      v-light-helper
+    />
+    <TresSpotLight
+      v-light-helper
+    />
+    <TresHemisphereLight
+      v-light-helper
+    />
+  </TresCanvas>
+</template>
+```

docs/es/directives/v-log.md

@@ -0,0 +1,53 @@
+# v-log
+
+### Problema
+
+Cuando tenga que registrar su instancia, debe usar la referencia de la plantilla y luego registrarla:
+
+```vue
+<script setup lang="ts">
+import { shallowRef, watch } from 'vue'
+
+const sphereRef = shallowRef()
+
+watch(sphereRef, (value) => {
+  console.log(value) // Really for a log?!!! 😫
+})
+</script>
+
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera :position="[0, 2, 5]" />
+    <Sphere
+      ref="sphereRef"
+      :scale="0.5"
+    />
+    <OrbitControls />
+  </TresCanvas>
+</template>
+```
+
+¿Y hay MUCHO código solo para un simple registro, verdad?
+
+## Uso
+
+Con la nueva directiva v-log proporcionada por **TresJS**, puedes hacer esto simplemente agregando `v-log` a la instancia.
+
+```vue{2,10,12}
+<script setup lang="ts">
+import { OrbitControls, Sphere, vLog } from '@tresjs/cientos'
+</script>
+<template>
+    <TresCanvas >
+    <TresPerspectiveCamera :position="[0, 2, 5]" />
+    <Sphere
+      ref="sphereRef"
+      :scale="0.5"
+      v-log:material  <!-- will print just the material 🎉 -->
+    />
+    <OrbitControls v-log />
+  </TresCanvas>
+</template>
+```
+
+Tenga en cuenta que puede pasar un modificador con el nombre de una propiedad, por ejemplo `v-log:material`, y registrará directamente la propiedad `material` 😍

docs/es/guide/index.md

@@ -63,9 +63,9 @@ Esto es necesario para que el compilador de plantillas funcione con el renderiza
 
 ## Pruébalo en línea
 
-### Sandbox
+### Playground
 
-Puedes probar TresJS en línea utilizando el [sandbox](https://play.tresjs.org/) oficial. ¡Échale un vistazo:
+Puedes probar TresJS en línea utilizando el [playground](https://play.tresjs.org/) oficial. ¡Échale un vistazo:
 
 <iframe src="https://play.tresjs.org/" class="w-full rounded shadow-lg outline-none border-none aspect-4/3"></iframe>
 
@@ -75,13 +75,11 @@ Tenemos un nuevo inicio de [StackBlitz](https://stackblitz.com/) para probar Tre
 
 ![](/stackblitz-starter.png)
 
-<StackBlitzEmbed projectId="tresjs-basic" />
+## Laboratorio
 
-## Playground
+También tenemos un laboratorio de ejemplos hechos con TresJS. Échale un vistazo [aquí](https://labs.tresjs.org/).
 
-También tenemos un playground donde puedes probar TresJS en línea. Échale un vistazo [aquí](https://playground.tresjs.org/).
-
-![](/playground.png)
+![](/tresjs-lab.png)
 
 ## Motivación
 

docs/es/guide/nuxt.md

@@ -30,7 +30,7 @@ yarn add three @tresjs/nuxt
 
 - 🤓 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)?
+- Configura automáticamente el compilador de Vue para admitir componentes de TresJS, consulta [por qué](/guide/troubleshooting)
 - Toda la magia de DX que viene con Nuxt ✨
 
 ## Uso

docs/guide/getting-started.md

@@ -77,7 +77,7 @@ This is recommended for performance and bundle size reasons, tree-shaking will w
 
 Since v2 is a custom renderer, we need to let the `vue-compiler` of your app know that the components of Tres are ok to be included to avoid the `[Vue warn]: Failed to resolve component` warning.
 
-You just need to add this to your `vite.config.ts` inside of the vue plugin:
+You just need to import and add the `templateCompilerOptions` from TresJS to your `vite.config.ts` inside of the vue plugin:
 
 ```ts
 import { templateCompilerOptions } from '@tresjs/core'

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
 ```
 
 :::
@@ -44,7 +44,7 @@ pnpm add @types/three -D
 
 ## Vite
 
-If you are using Vite, you have add the following to your `vite.config.ts`:
+If you are using Vite, you just need to import and add the `templateCompilerOptions` from TresJS to your `vite.config.ts` inside of the vue plugin:
 
 ```ts
 import { templateCompilerOptions } from '@tresjs/core'
@@ -59,13 +59,13 @@ 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 so it does not throw warnings on the console. For more info check [here](/guide/troubleshooting.html).
 
 ## Try it online
 
-### Sandbox
+### Playground
 
-You can try TresJS online using the official [sandbox](https://play.tresjs.org/). Check it out:
+You can try TresJS online using the official [playground](https://play.tresjs.org/). Check it out:
 
 <iframe src="https://play.tresjs.org/" class="w-full rounded shadow-lg outline-none border-none aspect-4/3"></iframe>
 
@@ -75,23 +75,22 @@ We have a brand new [StackBlitz](https://stackblitz.com/) starter to try TresJS
 
 ![](/stackblitz-starter.png)
 
-<StackBlitzEmbed projectId="tresjs-basic" />
 
-## Playground
+## Labs
 
-We also have a playground where you can try TresJS online. Check it out [here](https://playground.tresjs.org/).
+We also have a showcase lab of examples made with TresJS. Check it out [here](https://playground.tresjs.org/).
 
-![](/playground.png)
+![](/tresjs-lab.png)
 
 ## Motivation
 
-[ThreeJS](https://threejs.org/) is a wonderful library to create awesome **WebGL** 3D websites. Is also a constantly updated library that makes hard for wrapper maintainers like [TroisJS](https://troisjs.github.io/) to keep up with all the enhancements.
+[ThreeJS](https://threejs.org/) is a wonderful library to create awesome **WebGL** 3D websites. It's also a library, which is constantly updated, which makes it hard for wrapper maintainers like [TroisJS](https://troisjs.github.io/) to keep up with all the enhancements.
 
-React ecosystem has an impresive **custom render** solution called [React-three-fiber](https://docs.pmnd.rs/react-three-fiber) that allows you build your scenes declaratively with re-usable, self-contained components that react to state.
+The React ecosystem has an impressive **custom render** solution called [React-three-fiber](https://docs.pmnd.rs/react-three-fiber) that allows you build your scenes declaratively with re-usable, self-contained components that react to state.
 
-In my search for something similar in the VueJS ecosystem, I found this amazing library called [Lunchbox](https://github.com/breakfast-studio/lunchboxjs) which works with the same concept that R3F, it provides a [custom Vue3 Renderer](https://vuejs.org/api/custom-renderer.html). I'm also contributing to improve this library so it gets as mature and feature-rich as R3F.
+In my search for something similar in the VueJS ecosystem, I found this amazing library called [Lunchbox](https://github.com/breakfast-studio/lunchboxjs), which works with the same concept as R3F, it provides a [custom Vue3 Renderer](https://vuejs.org/api/custom-renderer.html). I'm also contributing to improve this library so it gets as mature and feature-rich as R3F.
 
-The only problem is, mixing compilers renderers in Vue 3 is something the Vue community is still working on - see [here](https://github.com/vuejs/vue-loader/pull/1645) for more information.
+The only issue with this is, mixing compilers renderers in Vue 3 is something the Vue community is still working on - see [here](https://github.com/vuejs/vue-loader/pull/1645) for more information.
 
 ```ts
 // Example Vite setup
@@ -111,4 +110,3 @@ lunchboxApp.mount('#lunchbox')
 ```
 
 So I was inspired by both libraries to create a Vue custom renderer for ThreeJS. That's **TresJS v2**.
-

docs/guide/migration-guide.md

@@ -22,7 +22,7 @@ yarn upgrade @tresjs/core
 
 ### Vue Custom Renderer
 
-**TresJS** is now a [Vue Custom Renderer](https://vuejs.org/api/custom-renderer.html#createrenderer) 🎉 that lives inside of a wrapper component `TresCanvas` that is responsible for creating the `WebGLRenderer` and the `Scene` for you and creating a **new Vue App instance** to render the scene.
+**TresJS** is now a [Vue Custom Renderer](https://vuejs.org/api/custom-renderer.html#createrenderer) 🎉 that lives inside of a wrapper component called `TresCanvas` that is responsible for creating the `WebGLRenderer` and the `Scene` for you and creating a **new Vue App instance** to render the scene.
 
 ### Typescript support and Intellisense 🦾
 

docs/guide/nuxt.md

@@ -30,7 +30,7 @@ yarn add three @tresjs/nuxt
 
 - 🤓 Auto-import components and composables from the [TresJS ecosystem](https://github.com/orgs/Tresjs/repositories)
 - `TresCanvas` client only, you don't need to add `.client` to the component name or `<ClientOnly />`
-- Automatically configures vue compiler to support TresJS components, see [why](/guide/troubleshooting.html#failed-resolve-component-trescomponent-%F0%9F%A4%94)?
+- Automatically configures vue compiler to support TresJS components, see [why](/guide/troubleshooting)
 - All the DX Magic that comes with Nuxt ✨
 
 ## Usage

docs/guide/troubleshooting.md

@@ -8,13 +8,13 @@ This guide is intended to help you solve the most common issues that you might e
 
 ## I can't see my 3D scene 😭!
 
-You followed the [Getting started guide](/guide/getting-started.md) but you still can see your scene rendered.
+You followed the [Getting started guide](/guide/getting-started.md) but you still can't see your scene rendered.
 
 These are the most common reasons why you might not be able to see your scene:
 
 ### Check the height of your canvas 📏
 
-Another common issue is that the `TresCanvas` component is creating by default a `canvas` element takes the `width` and `height` of the parent element. If the parent element has no height, the canvas will have no height either.
+Another common issue is that the `TresCanvas` component is creating by default a `canvas` element that takes the `width` and `height` of the parent element. If the parent element has no height, the canvas will have no height either.
 
 ![No height found](/canvas-height.png)
 

docs/guide/your-first-scene.md

@@ -10,7 +10,7 @@ This guide will help you to create your first Tres scene. 🍩
 
 ## Setting up the experience Canvas
 
-Before we can create a Scene, we need somewhere to display it. Using plain [ThreeJS](https://threejs.org/docs/index.html#manual/en/introduction/Creating-a-scene) we would need to create a `canvas` HTML element to mount the `WebglRenderer` and initialize the `scene`
+Before we can create a ThreeJS `Scene`, we need a space to display it. Using plain [ThreeJS](https://threejs.org/docs/index.html#manual/en/introduction/Creating-a-scene) we would need to create a `canvas` HTML element to mount the `WebglRenderer` and initialize the `Scene`.
 
 With **TresJS** you only need to import the default component `<TresCanvas />` and add it to the template of your Vue component.
 
@@ -30,7 +30,7 @@ import { TresCanvas } from '@tresjs/core'
 It's important that all components related to the scene live between the `<TresCanvas />` component. Otherwise, they will be not rendered.
 :::
 
-The `TresCanvas` component is going to do some setup work behind the scene:
+The `TresCanvas` component is going to do some setup work behind the scenes:
 
 - It creates a [**WebGLRenderer**](https://threejs.org/docs/index.html?q=webglrend#api/en/renderers/WebGLRenderer) that automatically updates every frame.
 - It sets the render loop to be called on every frame based on the browser refresh rate.
@@ -109,7 +109,7 @@ Then you can add a [**PerspectiveCamera**](https://threejs.org/docs/index.html?q
 ```
 
 ::: warning
-A common issue is that the camera default position is the origin of the scene (0,0,0), TresJS will automatically set the position of your camera to `[3,3,3]` if the prop `position`. If no camera is defined in you scene, a perspective camera is added automatically.`
+A common issue is that the camera default position is the origin of the scene (0,0,0). TresJS will automatically set the position of your camera to `[3,3,3]` if the prop `position` is not set by you. If no camera is defined in you scene, a perspective camera is added automatically.
 :::
 
 ## Adding a 🍩
@@ -125,7 +125,7 @@ scene.add(donut)
 
 A **Mesh** is a basic scene object in three.js, and it's used to hold the geometry and the material needed to represent a shape in 3D space.
 
-Now let's see how we can easily achieve the same with **TresJS**. To do that we are going to use `<TresMesh />` component, and between the default slots, we are going to pass a `<TresTorusGeometry />` and a `<TresMeshBasicMaterial />`.
+Now let's see how we can easily achieve the same with **TresJS**. To do that we are going to use the `<TresMesh />` component, and between the default slots, we are going to pass a `<TresTorusGeometry />` and a `<TresMeshBasicMaterial />` component.
 
 ```vue
 <template>
@@ -140,11 +140,9 @@ Now let's see how we can easily achieve the same with **TresJS**. To do that we
 ```
 
 ::: info
-Notice that we don't need to import anything, that's because **TresJS** automatically generate a **Vue Component based on the Three Object you want to use in CamelCase with a Tres prefix**. For example, if you want to use an `AmbientLight` you would use `<TresAmbientLight />` component.
+Notice that we don't need to import anything, that's because **TresJS** automatically generate a **Vue Component based on the three objects you want to use in CamelCase with a Tres prefix**. For example, if you want to use an `AmbientLight` you would use the `<TresAmbientLight />` component.
 :::
 
-
-
 ```vue
 <script setup lang="ts">
 import { TresCanvas } from '@tresjs/core'

docs/tsconfig.json

@@ -11,7 +11,7 @@
     "moduleResolution": "node",
     "resolveJsonModule": true,
     "forceConsistentCasingInFileNames": true,
-    "types": ["vite/client"]
+    "types": ["vite/client", "vitepress"]
   },
   "exclude": [
     "dist",

docs/vite.config.ts

@@ -2,7 +2,6 @@ import { defineConfig } from 'vite'
 import Unocss from 'unocss/vite'
 import svgLoader from 'vite-svg-loader'
 import Components from 'unplugin-vue-components/vite'
-import { templateCompilerOptions } from '@tresjs/core'
 
 export default defineConfig({
   plugins: [
@@ -17,7 +16,4 @@ export default defineConfig({
       dts: 'components.d.ts',
     }),
   ],
-  vue: {
-    ...templateCompilerOptions,
-  },
 })

docs/zh/advanced/caveats.md

@@ -0,0 +1,108 @@
+# 注意事项 😱
+
+我们的目标是提供一种在 VueJS 中使用 ThreeJS 的简单方法，并尽可能提供最佳的开发人员体验。但是，您仍有一些注意事项应该了解。
+
+## ~~HMR 和 ThreeJS~~
+
+:::info
+
+这一问题已在 **TresJS** v1.7.0 🎉 中得到修复。现在您可以使用 HMR 而无需重新加载页面。
+
+:::
+
+热模块替换（HMR）是一项无需重新加载页面即可更新代码的功能。这是一项伟大的功能，能大大加快开发速度。**TresJS**使用[Vite](https://vitejs.dev/)。然而，要让它在 ThreeJS 中正常工作确实非常棘手。
+
+为什么呢？因为 Tres 是以声明的方式构建场景的。这意味着它创建了实例，并在安装组件时将其添加到场景中。复杂之处在于何时从场景中移除实例，何时再次添加。
+
+虽然实现了最低限度的处置工作流程，但它并不完美。这意味着有时您必须重新加载页面才能正确看到变化，特别是当您使用 [模板引用](https://cn.vuejs.org/guide/essentials/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>
+```
+
+如果对 `TresMeshStandardMaterial` 组件的 `color` 进行更改，你会发现更改被应用了，但旋转却失效了。这是因为该实例已被弃置并重新创建。
+
+:::tip
+因此，**根据经验**，每当您没有看到所做的更改时，您应该重新加载页面。
+:::
+
+尽管如此，我们仍在努力寻找更好的解决方案😁。如果您有任何解决方法，请让我们知道。
+
+您可以在 [HMR 处理讨论](https://github.com/Tresjs/tres/issues/23) 中关注讨论。
+
+## 响应性
+
+我们都喜欢响应性💚。它是 VueJS 最强大的功能之一。不过，在使用 ThreeJS 时，我们需要注意这一点。
+
+Vue 的反应性基于 [Proxy](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Proxy)。这使得 Vue 3 可以自动跟踪数据对象的变化，并在数据发生变化时更新相应的 DOM 元素。
+
+由于我们正在渲染一个场景并在每一帧中更新（60FPS），这意味着我们每秒要更新场景 60 次。如果要更新的对象是反应式的，Vue 就会尝试更新该对象这么多次。这不是一个好主意😅，会对性能造成损害。
+
+下面是使用 Proxy 对象和普通对象的区别基准。
+
+<figure>
+  <img src="/proxy-benchmark.png" alt="Proxy vs Plain" style="width:100%">
+  <figcaption>图 1 - 计划对象与代理的每秒执行次数。 </figcaption>
+</figure>
+
+来源：[Proxy vs Plain Object](https://www.measurethat.net/Benchmarks/Show/12503/0/object-vs-proxy-vs-proxy-setter)
+
+如果您不得不使用反应性，请使用 [shallowRef](https://cn.vuejs.org/api/reactivity-advanced.html#shallowref)
+
+和 ref() 不同，浅层 ref 的内部值将会原样存储和暴露，并且不会被深层递归地转为响应式。只有对 .value 的访问是响应式的。来源 [VueJS 文档](https://cn.vuejs.org/api/reactivity-advanced.html#shallowref)
+
+### 范例
+
+❌ 错误的
+
+```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>
+```
+
+✅ 正确的
+
+```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/zh/advanced/extending.md

@@ -0,0 +1,35 @@
+# 扩展 🔌
+
+Tres 提供基本功能，但可以轻松添加第三方元素并将其扩展到内部目录中。
+
+大部分 3D 体验使用的是 `OrbitControls`，但是它不是核心库的一部分。您可以从 `three/addons/controls/OrbitControls` 模块中导入，将其添加到您的项目中。
+
+```js
+import { OrbitControls } from 'three/addons/controls/OrbitControls'
+```
+
+## 动态扩展元素
+
+或者也可以在组件中动态添加：
+
+```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'
+
+// Add the element to the catalogue
+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/zh/advanced/primitive.md

@@ -0,0 +1,47 @@
+# Primitives
+
+`<primitive />` 组件是 TresJS 中一种通用的底层组件，它允许您在 Vue 应用程序中直接使用任何 three.js 对象，而无需进行抽象。它是 Vue 响应式系统和 three.js 场景画面之间的桥梁。
+
+## 使用方法
+
+```html
+<script setup lang="ts">
+  // Import necessary three.js classes
+  import { Mesh, BoxGeometry, MeshBasicMaterial } from 'three';
+
+  // Create a box geometry and a basic material
+  const geometry = new BoxGeometry(1, 1, 1);
+  const material = new MeshBasicMaterial({ color: 0x00ff00 });
+
+  // Create a mesh with the geometry and material
+  const meshWithMaterial = new Mesh(geometry, material);
+</script>
+
+<template>
+  <TresCanvas>
+    <primitive :object="meshWithMaterial" />
+  </TresCanvas>  
+</template>
+```
+
+## Props
+
+`object`：这个 prop 接受一个 three.js Object3D 或其任何派生类。它是 `<primitive />` 组件将呈现的主要对象。在更新的示例中，一个被附加了 `Material` 的 `Mesh` 对象被传递给此 prop。
+
+## 与模型一起使用
+
+对于呈现复杂对象（如从外部加载的模型），`<primitive />` 组件尤其有用。下面的示例展示了如何从 GLTF 文件加载模型，并使用 `<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/zh/api/composables.md

@@ -0,0 +1,244 @@
+# 组合式函数
+
+Vue 3的[Composition API](https://vuejs.org/guide/extras/composition-api-faq.html#what-is-composition-api) 允许您创建可在组件之间共享的可重用逻辑。它还允许您创建可在组件中使用的自定义钩子。
+
+**TresJS** 充分利用这个API创建了一组组合式函数，可用于创建动画、与场景交互等。它还允许您创建更复杂的场景，不仅使用Vue组件（纹理、加载器等）实现。
+
+**TresJS** 核心在内部使用这些组合式函数，因此可以使用与核心相同API。例如，需要在内部渲染循环中更新的组件使用 `useRenderLoop` 来注册一个回调函数，每当渲染器更新场景时都会调用该函数。
+
+## useRenderLoop
+
+`useRenderLoop` 是 **TresJS** 动画的核心。它可以注册一个回调函数，该函数将在原生刷新率下被调用。这是 **TresJS** 中最重要的组合式函数。
+
+```ts
+const { onLoop, resume } = useRenderLoop()
+
+onLoop(({ delta, elapsed, clock }) => {
+  // 它将在每一帧运行 ~60FPS (取决于您的显示器)
+})
+```
+
+::: warning
+
+请注意使用此组合式函数的性能影响。它将在每一帧运行，因此如果在回调中有大量逻辑，可能会影响应用程序的性能。特别是如果您正在更新响应式状态或引用。
+:::
+
+`onLoop` 回调接收一个基于[THREE clock](https://threejs.org/docs/?q=clock#api/en/core/Clock)的对象，该对象具有以下属性：
+
+
+- `delta`: 当前帧与上一帧之间的时间差。这是自上一帧以来的时间（以秒为单位）。
+- `elapsed`: 自渲染循环开始以来的时间。
+
+这个组合式函数基于 [vueuse](https://vueuse.org/core/useRafFn/) 中的 `useRafFn` 。感谢 [@wheatjs](https://github.com/orgs/Tresjs/people/wheatjs) 的出色贡献
+
+### 渲染前后
+
+您还可以注册一个在渲染器更新场景之前和之后调用的回调函数。例如，添加了性能分析工具以测量FPS，将非常有用。
+
+```ts
+const { onBeforeLoop, onAfterLoop } = useRenderLoop()
+
+onBeforeLoop(({ delta, elapsed }) => {
+  // 在渲染器更新场景之前运行
+  fps.begin()
+})
+
+onAfterLoop(({ delta, elapsed }) => {
+  // 在渲染器更新场景之后运行
+  fps.end()
+})
+```
+
+### 暂停和恢复
+
+您可以使用 `pause` 和 `resume` 方法来暂停和恢复循环渲染。
+
+```ts
+const { pause, resume } = useRenderLoop()
+
+// 暂停循环渲染
+pause()
+
+// 恢复循环渲染
+resume()
+```
+
+您还可以使用 `isActive` 属性获取循环渲染的活动状态。
+
+```ts
+const { resume, isActive } = useRenderLoop()
+
+console.log(isActive) // false
+
+resume()
+
+console.log(isActive) // true
+```
+
+## useLoader
+
+`useLoader` 组合式函数可以使用 [THREE.js loaders](https://threejs.org/docs/#manual/en/introduction/Loading-3D-models) 加载器加载资源。它返回一个带有加载后资源的Promise。
+
+
+```ts
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader'
+
+const { scene } = await useLoader(THREE.GLTFLoader, 'path/to/asset.gltf')
+```
+
+由于 `useLoader` 组合式函数返回一个Promise，您可以使用 `async/await` 或 `then/catch`。如果您在组件上使用它，请确保将其包装在 `Suspense` 组件中。有关更多信息，请参阅[Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense)。
+
+```vue
+<template>
+  <Suspense>
+    <TheComponentUsingLoader />
+  </Suspense>
+</template>
+```
+
+## useTexture
+
+
+`useTexture` 组合式函数可以使用 [THREE.js texture loader](https://threejs.org/docs/#api/en/loaders/TextureLoader) 纹理加载器加载纹理。它返回一个带有已加载纹理的Promise。
+
+```ts
+const texture = await useTexture(['path/to/texture.png'])
+```
+
+**useTexture** 还可以传入一个包含以下属性的对象：
+
+- `map`: 用于物体表面的基本纹理
+- `displacementMap`: 用于在物体表面添加凹凸或凹痕的纹理
+- `normalMap`: 用于在物体上添加表面细节和阴影变化的纹理
+- `roughnessMap`: 用于在物体表面添加粗糙度或哑光效果的纹理
+- `metalnessMap`: 用于在物体表面添加金属效果的纹理
+- `aoMap`: 用于在物体上添加环境遮蔽（在光被其他物体挡住的区域中添加阴影）的纹理
+- `alphaMap`: 用于向物体添加 alpha（黑色部分渲染为透明）的纹理。在材质上使用这个映射，需要设置 `:transparent="true"`
+- `matcap`: 材质颜色和阴影的纹理编码
+
+在这种情况下，它将返回一个包含已加载纹理的对象。
+
+```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',
+})
+```
+
+然后，可以将纹理绑定到材质上。
+
+```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>
+```
+
+与上述类似，`useTexture` 组合式函数返回一个Promise，您可以使用 `async/await` 或 `then/catch`。如果您在组件上使用它，请确保将其包装在 `Suspense` 组件中。
+
+## useSeek
+
+`useSeek` 组合式函数提供了一些实用工具，可轻松遍历和浏览复杂的ThreeJS场景和对象子图。它导出了4个函数，允许您根据特定属性查找子对象。
+
+
+```ts
+const { seek, seekByName, seekAll, seekAllByName } = useSeek()
+```
+
+`useSeek` 函数接受三个参数：
+
+- `parent`: 一个 ThreeJS 场景或 Object3D
+- `property`: 用于搜索条件的属性
+- `value`: 匹配的属性值
+
+`seek` 和 `seekByName` 函数遍历对象并返回具有指定属性和值的子对象。如果找不到具有给定属性和值的子对象，则返回 null 并抛出警告。
+
+```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'))
+  }
+})
+```
+
+类似地，`seekAll` 和 `seekAllByName` 函数返回一个包含具有指定属性和值的子对象的数组。如果没有找到匹配项，则返回一个空数组，并抛出警告。
+
+```ts
+const character = ref(null)
+
+watch(character, ({ model }) => {
+  if (model) {
+    const bones = seekAll(character, type, 'Bone')
+  }
+})
+```
+
+## useTresContext
+
+
+这个组合式函数提供对包含多个有用属性的状态模型的访问。
+
+
+```ts
+const { camera, renderer, camera, cameras } = useTresContext()
+
+```
+
+::: warning
+`useTresContext` 只能在 `TresCanvas` 内部使用，因为 `TresCanvas` 充当上下文数据的提供者。如果在TresCanvas的父组件中需要上下文，请使用[TresCanvas暴露的上下文](tres-canvas#exposed-public-properties)。
+:::
+
+```vue
+<TresCanvas>
+  <MyModel />
+</TresCanvas>
+```
+
+```vue
+// MyModel.vue
+
+<script lang="ts" setup>
+import { useTresContext } from '@tresjs/core'
+
+const context = useTresContext()
+</script>
+```
+
+### 上下文的属性
+| 属性 | 描述 |
+| --- | --- |
+| **camera** | 当前激活的相机 |
+| **cameras** | 场景中存在的相机|
+| **controls** | 场景控件 |
+| **deregisterCamera** | 用于取消注册相机的方法。仅在手动创建相机时需要。`template` 中的相机会自动取消注册。 |
+| **extend** | 扩展组件目录。请查看 [extending](/advanced/extending) |
+| **raycaster** | 用于鼠标事件的全局光线投射器 |
+| **registerCamera** | 用于注册相机的方法。只有在手动创建相机时才需要。在 `template` 中，相机会自动注册。 |
+| **renderer** | 场景中的 [WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer) |
+| **scene** | [场景](https://threejs.org/docs/?q=sce#api/en/scenes/Scene) |
+| **setCameraActive** | 设置当前激活的相机 |
+| **sizes** | 画布的宽度、高度和宽高比 |
+

docs/zh/api/events.md

@@ -0,0 +1,29 @@
+# 事件
+
+**TresJS** 组件在交互时会触发鼠标事件。适用于继承自 [THREE.Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) 的 three.js 类的组件（例如网格、组等）。
+
+
+<StackBlitzEmbed project-id="tresjs-events" />
+
+## 鼠标事件
+
+```html
+<TresMesh
+  @click="(intersection, pointerEvent) => console.log('单击', intersection, pointerEvent)"
+  @pointer-move="(intersection, pointerEvent) => console.log('移动', intersection, pointerEvent)"
+  @pointer-enter="(intersection, pointerEvent) => console.log('移入', intersection, pointerEvent)"
+  @pointer-leave="(intersection, pointerEvent) => console.log('移出', pointerEvent)"
+/>
+```
+
+
+| 事件         | 在 ... 触发                                                                       | 事件参数类型                                                                                                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| click         | ... 在同一对象上依次触发的 `pointerdown` 和 `pointerup` 事件 | [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16), [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent) |
+| pointer-move  | ... 鼠标在对象上方移动                                            | [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16), [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent) |
+| pointer-enter | ... 鼠标移入对象                                                | [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16), [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent) |
+| pointer-leave | ... 鼠标移出对象                                                  | [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent)                                                                                                                         |
+
+返回的 [Intersection](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/three/src/core/Raycaster.d.ts#L16) 包括触发事件的 [Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) 。您可以通过`intersection.object` 访问它。
+
+默认情况下，不会阻止事件冒泡。可以通过使用`blocks-pointer-events` 属性来实现此行为。

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

@@ -0,0 +1,152 @@
+# 实例
+
+**Tres** 的核心理念是一个自动生成的ThreeJS元素目录。这个目录是从ThreeJS 源代码生成的，因此始终保持最新。
+
+在使用 ThreeJS 时，您需要导入要使用的元素。例如，如果您想使用`PerspectiveCamera` ，您需要从 `three` 包中导入它：
+
+```js
+import { PerspectiveCamera } from 'three'
+
+const camera = new PerspectiveCamera(45, width / height, 1, 1000)
+```
+使用 **Tres** 时，您无需导入任何内容，这是因为 **Tres** 会自动生成一个 **基于您想要使用的Three对象的Vue组件，使用驼峰命名法并加上Tres前缀** 。例如，如果您想要使用 `PerspectiveCamera` ，您将使用 `<TresPerspectiveCamera />` 组件。
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera />
+    <!-- 这里是场景 -->
+  </TresCanvas>
+</template>
+```
+这意味着您可以使用与使用普通的ThreeJS相同的[文档](https://threejs.org/docs/)，但同时又能利用Vue的强大功能。
+
+
+## 声明对象
+
+如果我们遵循这个观念，你应该能够布置一个像这样实例： ❌
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera
+      visible
+      :position="new THREE.Vector3(1, 2, 3)"
+    />
+    <!-- 这里是场景 -->
+  </TresCanvas>
+</template>
+```
+但是使用 **Tres**，这是不需要的，您可以像这样声明性地定义属性： ✅
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera
+      visible
+      :position="[1, 2, 3]"
+    />
+    <!-- 这里是场景 -->
+  </TresCanvas>
+</template>
+```
+
+## 参数
+
+ThreeJS对象的一些参数，例如，`PerspectiveCamera` 构造函数有以下参数：
+
+- `fov` - 相机截锥体的垂直视场角。
+- `aspect` - 相机截锥体的宽高比。
+- `near` - 相机截锥体的近裁剪面。
+- `far` - 相机截锥体的远裁剪面。
+
+
+要将这些参数传递给 `TresPerspectiveCamera` 组件，您可以使用 `args` prop：
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
+    <!-- 这里是场景 -->
+  </TresCanvas>
+</template>
+```
+
+与执行以下操作是等效的：
+
+```ts
+const camera = new PerspectiveCamera(45, 1, 0.1, 1000)
+```
+
+## props
+
+您还可以通过 props 的方式传递给组件，例如，`TresAmbientLight` 有一个 `intensity` 属性，您可以通过以下方式将其传递给组件：
+
+```html
+<TresAmbientLight :intensity="0.5" />
+```
+
+### 设置
+
+所有底层对象具有 `.set()` 方法的属性都有一个快捷方式，可以将值作为数组接收。例如，`TresPerspectiveCamera` 有一个 `position` 属性，是一个 `Vector3` 对象，因此可以通过以下方式将其传递给组件：
+
+```html
+<TresPerspectiveCamera :position="[1, 2, 3]" />
+```
+
+要指定位置、旋转和缩放等转换属性，可以使用一种简写方法，允许您在props中直接指定要设置的轴。颜色属性也有类似的简写。
+
+<!-- 尝试将颜色的语法从Vue更改为HTML，但Vue似乎有问题，无法对嵌套组件进行着色。 -->
+```html
+<TresMesh :position-x="1" :scale-y="2" :rotation-x="Math.PI * 2">
+  <TresMeshBasicMaterial :color-r="0.7" :color-b="0.3" />
+</TresMesh>
+```
+
+::: warning
+
+
+在 [three.js](https://threejs.org/docs/index.html#api/en/math/Euler) 中设置旋转属性时，默认会使用'XYZ'顺序。
+值得注意的是，使用简写设置旋转属性时，设置角度的顺序是重要的。关于该主题的更多信息，请参阅 [Euler angles](https://en.wikipedia.org/wiki/Euler_angles)。
+
+:::
+
+```vue
+<TresMesh :rotation-x="1" :rotation-y="2" :rotation-z="Math.PI * 2" />
+
+<TresMesh :rotation-z="Math.PI * 2" :rotation-x="1" :rotation-y="2" />
+
+<!-- 请注意！旋转属性的顺序是重要的，交换顺序可能导致不同的结果。 -->
+```
+
+### 标量
+
+您还可以使用另一种快捷方式，将标量值传递给 `Vector3` 对象的属性，对于该矢量的其余部分使用相同的值：
+
+```html
+<TresPerspectiveCamera :position="5" /> ✅
+```
+
+```html
+<TresPerspectiveCamera :position="[5, 5, 5]" /> ✅
+```
+
+### 颜色
+
+您可以通过使用 `color` 属性将颜色传给组件，该属性接受包含颜色名称或十六进制值：
+
+```html
+<TresAmbientLight color="teal" /> ✅
+```
+
+```html
+<TresAmbientLight color="#008080" /> ✅
+```
+
+### 方法
+
+底层的一些属性实际上是方法，例如，`TresPerspectiveCamera` 具有从[Object3d](https://threejs.org/docs/#api/en/core/Object3D.lookAt)继承的 `lookAt` 方法，因此您可以将坐标传递给组件，如下所示：
+
+```html
+<TresPerspectiveCamera :look-at="[1, 2, 3]" />
+```

docs/zh/api/tres-canvas.md

@@ -0,0 +1,104 @@
+# TresCanvas
+
+`TresCanvas` 组件是Tres的主要组件。它负责创建ThreeJS `WebGLRenderer`。
+
+```vue{2,5}
+<template>
+  <TresCanvas shadows :output-encoding="SRGBColorSpace">
+    <TresPerspectiveCamera />
+      <!-- 这里是您的场景 -->
+  </TresCanvas>
+</template>
+```
+
+## 画布尺寸
+
+`TresCanvas` 组件将使用父元素的尺寸作为画布的大小。 如果您想使用窗口大小作为画布的大小，可以将 `window-size` 属性设置为 `true`.
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <!-- 这里是您的场景 -->
+  </TresCanvas>
+</template>
+```
+
+或者您可以使用CSS来设置画布的尺寸。
+
+```css
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  width: 100%;
+}
+#canvas {
+  height: 100%;
+  width: 100%;
+}
+```
+
+## 预设配置
+
+Tres 为 `TresCanvas` 组件提供了一些预设配置。您可以通过设置 `preset` 属性来使用它们。
+
+### Realistic
+
+`realistic` 预设可以更容易更逼真的为3D场景设置渲染器。
+
+```vue
+<template>
+  <TresCanvas preset="realistic">
+    <!-- 这里是您的场景 -->
+  </TresCanvas>
+</template>
+```
+
+这相当于：
+
+```ts
+renderer.shadows = true
+renderer.physicallyCorrectLights = true
+renderer.outputColorSpace = SRGBColorSpace
+renderer.toneMapping = ACESFilmicToneMapping
+renderer.toneMappingExposure = 3
+renderer.shadowMap.enabled = true
+renderer.shadowMap.type = PCFSoftShadowMap
+```
+
+## 配置项
+
+| 配置 | 描述 | 默认值 |
+| ---- | ---- | --- |
+| **alpha** | 控制默认清除 alpha 值。设置为 true 时，该值为 0，否则为 1。 | `false` |
+| **antialias** | 是否进行抗锯齿处理。 | `true` |
+| **camera** | 由渲染器指定相机。 | |
+| **clearColor** | 清除画布后渲染器显示颜色。 | `#000000` |
+| **context** | 将渲染器附加到现有的 [RenderingContext](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext) | |
+| **depth** | 绘图缓冲区是否至少具有16位的[深度缓冲区](https://en.wikipedia.org/wiki/Z-buffering) 。 | `true` |
+| **disableRender** | 禁用 `requestAnimationFrame` 上的渲染，这对于后期处理非常有用。 | `false` |
+| **failIfMajorPerformanceCaveat** | 在性能较低时，是否检测渲染器创建失败。详细信息请参阅[WebGL](https://registry.khronos.org/webgl/specs/latest/1.0/#5.2)规范。 | `false` |
+| **logarithmicDepthBuffer** | 是否使用深度缓冲区。如果在单个场景中处理巨大的比例差异，可能需要使用此选项。请注意，如果使用，此设置将使用gl_FragDepth，这将禁用[Early Fragment Test](https://www.khronos.org/opengl/wiki/Early_Fragment_Test)优化，可能会导致性能下降。 | `false` |
+| **outputColorSpace** | 定义输出编码 | `LinearEncoding` |
+| **powerPreference** | 用户代理适合此WebGL上下文的GPU配置。可选"high-performance"（高性能）, "low-power"（低功耗）或 "default"（默认）。 | `default` |
+| **precision** | 着色器精度。可选"highp"（高精度）, "mediump"（中精度）或 "lowp"（低精度）。 | "highp" 需要设备支持 |
+| **premultipliedAlpha** | 渲染器是否假定颜色具有 [premultiplied alpha](https://en.wikipedia.org/wiki/Glossary_of_computer_graphics#premultiplied_alpha). | `true` |
+| **preserveDrawingBuffer** | 是否保留缓冲区直到手动清除或覆盖。 | `false` |
+| **shadows** | 渲染器是否启用阴影。 | `false` |
+| **shadowMapType** | 设置阴影映射类型 | `PCFSoftShadowMap` |
+| **stencil** | 绘图缓冲区是否至少具有8位的 [模板缓冲区](https://en.wikipedia.org/wiki/Stencil_buffer) 。 | `true` |
+| **toneMapping** | 定义渲染器使用的色调映射曝光。 | `NoToneMapping` |
+| **toneMappingExposure** | 色调映射的曝光级别。 | `1` |
+| **useLegacyLights** | 是否使用传统照明模式 | `true` |
+| **windowSize** | 是否使用窗口大小作为画布大小，否则使用父元素大小。 | `false` |
+
+### 默认值
+Tres尽量少做主观判断。这就是为什么它几乎不设置 `TresCanvas` 组件的任何默认值的原因。它使用[three.js](https://threejs.org/)的默认值。唯一的例外是 `antialias` 属性，默认设置为 `true`。
+
+
+## 公共属性
+
+| 属性 | 描述 |
+| ---- | ---- |
+| context | 详情查看 [useTresContext](composables#usetrescontext) |

docs/zh/cookbook/basic-animations.md

@@ -0,0 +1,98 @@
+---
+title: 基础动画
+description: 如何使用 useRenderLoop 组合函数来为您的对象添加动画。
+author: alvarosabu
+thumbnail: /recipes/animations.png
+difficulty: 0
+---
+
+# 基础动画
+
+本指南将帮助您开始使用 TresJS 进行基本的动画。
+
+我们将创建一个简单的场景，其中包含一个立方体。然后，我们将立方体添加动画，使其围绕 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
+
+`useRenderLoop` 组合式函数构成了 TresJS 动画的核心。它允许您注册一个回调函数，该函数将在渲染器以浏览器的刷新率更新场景时每次调用。
+
+要查看其工作原理的详细说明，请参考 [useRenderLoop](/api/composables#userenderloop)  文档。
+
+```ts
+const { onLoop } = useRenderLoop()
+
+onLoop(({ delta, elapsed }) => {
+  // 将在每一帧运行 ~ 60FPS（取决于您的显示器）
+})
+```
+
+## 获取立方体的引用
+
+要为立方体设置动画，我们需要获取它的引用。我们可以通过使用 [模板引用](https://cn.vuejs.org/guide/essentials/template-refs.html) 将 ref 属性传递给 `TresMesh` 组件来实现。这将返回 THREE 实例。
+
+为了提高性能，我们将使用 [Shallow Ref](https://v3.vuejs.org/guide/reactivity-fundamentals.html#shallow-reactivity) 来存储引用，而不是常规引用。原因请参阅此处[here](../advanced/caveats.md#reactivity)
+
+```vue
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+
+const boxRef: ShallowRef<TresInstance | null> = shallowRef(null)
+</script>
+
+<template>
+  <TresCanvas>
+    <TresMesh
+      ref="boxRef"
+      :scale="1"
+    >
+      <TresBoxGeometry :args="[1, 1, 1]" />
+      <TresMeshNormalMaterial />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+## 使立方体动起来
+
+现在我们已经获得了立方体的引用，就可以对其进行动画处理了。我们将使用 `onLoop` 回调更新立方体的旋转。
+
+```ts
+onLoop(({ delta, elapsed }) => {
+  if (boxRef.value) {
+    boxRef.value.rotation.y += delta
+    boxRef.value.rotation.z = elapsed * 0.2
+  }
+})
+```
+
+你也可以使用内部[THREE clock](https://threejs.org/docs/?q=clock#api/en/core/Clock)的 `delta` 或 `elapsed` 来为立方体制作动画。
+
+## 为什么不使用响应式系统？
+
+你可能想知道为什么我们不使用响应式系统来为立方体制作动画。答案很简单，性能。
+
+```vue
+// This is a bad idea ❌
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+
+const boxRotation = reactive([0, 0, 0])
+
+onLoop(({ delta, elapsed }) => {
+  boxRotation[1] += delta
+  boxRotation[2] = elapsed * 0.2
+})
+</script>
+```
+
+我们可能会忍不住使用响应式系统来为立方体制作动画。但这并不是一个好主意。
+
+原因是 Vue 的响应式系统基于代理: https://vuejs.org/guide/extras/reactivity-in-depth.html#how-reactivity-works-in-vue，它并不适合用于每秒更新 60 次或更多的渲染循环中。
+
+下面的嵌入页面展示了一个[代理 vs 普通对象的基准测试](https://measurethat.net/Benchmarks/Show/12503/0/object-vs-proxy-vs-proxy-setter) 。正如你所看到的，代理比普通对象慢 5 倍。
+
+<EmbedExperiment src="https://measurethat.net/Embed?id=399142" />
+
+你可以在 [注意事项](../advanced/caveats.md#reactivity) 部分了解更多关于这个方面的内容。

docs/zh/cookbook/groups.md

@@ -0,0 +1,40 @@
+---
+title: 组
+description: 学习如何在场景中对多个对象进行分组。
+author: alvarosabu
+thumbnail: /recipes/groups.png
+difficulty: 0
+---
+
+# 组
+
+`<TresGroup>` 是一个 [THREE.Group](https://threejs.org/docs/#api/zh/objects/Group) 类的实例，它与 [THREE.Object3D](https://threejs.org/docs/#api/zh/objects/Object3D) 非常相似，但允许您将 场景中的多个对象分组在一起，以便将它们作为一个整体进行操作（变换、旋转等）。
+
+## 使用方法
+
+```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/zh/cookbook/index.md

@@ -0,0 +1,5 @@
+# 专题手册 🍳🧑‍🍳
+
+探索指导专题手册，帮助您开始使用 Tres 的基础知识。每个专题都旨在帮助您理解 Tres 的核心概念以及如何在项目中使用它们。
+
+<Cookbook />

docs/zh/cookbook/lights-shadows.md

@@ -0,0 +1,184 @@
+---
+title: 光照和阴影
+description: 学习如何向场景中添加光照和阴影。
+author: alvarosabu
+thumbnail: /recipes/lights-and-shadows.png
+difficulty: 0
+---
+
+# 光照和阴影
+
+本指南将帮助你开始在 TresJS 中使用简单的光照和阴影。
+
+我们将构建一个包含三个网格和一个平面的简单场景，但只有两个网格会有阴影。
+
+<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==" />
+
+## 设置场景（可选）
+
+我们导入所有需要的模块，为了方便，我们可以使用 cientos 中的轨道控制器，[点击此处了解如何使用](/zh/cookbook/orbit-controls)。
+
+让我们在场景中放置四个对象，一个将是接收阴影的平面，其中两个将投射阴影，最后一个根本不会投射任何阴影。
+
+我将使用 [MeshToonMaterial](https://threejs.org/docs/index.html?q=toon#api/en/materials/MeshToonMaterial)。仅仅是因为我们可以轻松地看到“柔和的阴影”。
+
+```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>
+```
+
+## 光照（说明）
+
+如你所知，[ThreeJs](https://threejs.org/) 中的每个实例在 **TresJs** 中都是可用的，所有类型的灯光也是如此，我们只需要添加 `Tres` 前缀即可使用它们。
+
+但并非所有灯光都能投射阴影，这个设定直接来自 ThreeJs 并且合乎情理，例如，[ambientLight](https://threejs.org/docs/index.html?q=ambient#api/en/lights/AmbientLight) 的目的是照亮场景的每一面，因此让它投射阴影毫无意义，相反，模仿太阳的 [DirectionalLight](https://threejs.org/docs/index.html?q=light#api/en/helpers/DirectionalLightHelper) 可以且应该投射阴影。
+
+## 阴影（说明）
+
+阴影也有很多类型，例如，“柔和阴影”会在物体从一侧接收到更多光线时自动生成，但总的来说，需要投射到另一个表面的“ThreeJS 默认阴影”需要由一个网格投射，另一个网格需要接收它。正如我们在示例中看到的，`Plane` 正在接收阴影，但不会投射阴影。请注意，并非所有材质都能投射或接收阴影。
+
+在内部，ThreeJS 会自动生成一个带有 [ShadowMaterial](https://threejs.org/docs/index.html?q=shado#api/en/materials/ShadowMaterial) 的新网格，该网格会在每一帧中更新，这就是为什么如果你应用动画，阴影也会被动画化，但也正是为什么你必须谨慎使用阴影，因为它们可能会降低你的性能。
+
+::: warning
+过度使用阴影可能会降低你的性能。但是，有一些方法可以提高你的性能，有关更多信息，请查看 [此视频](https://youtu.be/WGNvVGrS0kY?si=q7XyL5eABKUh3gbS&t=1256)。
+:::
+
+## 启用阴影
+
+我们可以将此分为三个步骤：
+
+### 在渲染器上激活阴影
+
+```vue
+//...
+
+<template>
+  <TresCanvas
+    clear-color="#111"
+    shadows
+    window-size
+  />
+  //...
+</template>
+```
+
+### 设置光线以投射阴影
+
+我们可以简单地放置布尔值 `cast-shadow`，Vue 将其理解为具有 `true` 值的 `prop`
+
+_AmbientLight 在这里不会生成任何类型的阴影_
+
+```vue
+//...
+
+<template>
+  <TresAmbientLight :intensity="1" />
+  <TresDirectionalLight
+    cast-shadow
+    :position="[0, 2, 0]"
+    :intensity="1"
+  />
+  
+  //...
+</template>
+```
+
+### 设置对象以投射或接收阴影
+
+与上一步类似，我们使用 `cast-shadow` prop 设置我们要投射阴影的网格（我们的球体），并使用 `receive-shadow` prop 设置要接收阴影的对象（我们的平面）。
+
+```vue
+//...
+
+<template>
+  <TresMesh
+    cast-shadow
+    :position="[2, -2, 0]"
+  >
+    <TresSphereGeometry />
+    <TresMeshToonMaterial color="#FBB03B" />
+  </TresMesh>
+  <TresMesh
+    receive-shadow
+    :position="[0, -3, 0]"
+    :rotation="[-Math.PI / 2, 0, 0]"
+  >
+    <TresPlaneGeometry :args="[10, 10, 10, 10]" />
+    <TresMeshStandardMaterial color="#f7f7f7" />
+  </TresMesh>
+  //...
+</template>
+```
+
+现在，我们已经完成了向场景添加阴影所需的所有必要步骤，如果我们应用我们在 [基本动画](/zh/cookbook/basic-animations) 中学到的知识，并为我们的立方体添加运动，你将看到阴影也会随之动画化 🤩
+
+```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>
+```
+
+_请注意，我特意没有对 `Cone` 应用 `cast-shadow`，因此它不会投射任何阴影_

docs/zh/cookbook/load-models.md

@@ -0,0 +1,148 @@
+---
+title: 加载模型
+description: 将3D模型加载到您的Tres场景中。
+author: alvarosabu
+thumbnail: /recipes/gltf-model.png
+difficulty: 1
+---
+
+# 加载模型
+
+> 本指南中使用的所有模型均来自 [Alvaro Saburido](https://sketchfab.com/3d-models/aku-aku-7dfcb6edf10b4098bbb965c56fd3055c)。
+
+3D 模型有数百种文件格式，每种格式都有不同的用途、不同的功能和不同的复杂性。
+
+在本指南中，我们将重点介绍加载 gLTF（GL 传输格式）模型，这是 Web 上最常见的 3D 模型格式。
+
+<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==" />
+
+在 TresJS 中加载模型有多种方法：
+
+::: warning
+请注意，在上面的示例中，我们使用顶级 await，请确保用 [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) 组件包装它。有关更多信息，请参阅 Suspense。
+:::
+
+## 使用 `useLoader`
+
+`useLoader` 组合式函数允许你传递任何类型的 three.js 加载器和一个用于加载资源的 URL。它返回一个包含已加载资源的 `Promise`。
+
+有关如何使用 `useLoader` 的详细说明，请查看 [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')
+```
+
+然后，你可以将模型场景传递给 TresJS [`primitive`](/advanced/primitive) 组件以渲染它：
+
+```html{2}
+<TresCanvas>
+    <primitive :object="scene" />
+</TresCanvas>
+```
+
+> `<primitive />` 组件不是 Tres 源代码中的独立组件。相反，它是 Tres 核心功能的一部分。当你使用 `<primitive>` 时，它会被转换为 `createElement` 调用，该调用会根据提供的“object”道具创建适当的 three.js 对象。
+
+请注意，在上面的示例中，我们使用 `Suspense` 组件包装 `TresCanvas` 组件。这是因为 `useLoader` 返回一个 `Promise`，我们需要等到它解析后才能渲染场景。
+
+## 使用 `useGLTF`
+
+一种更方便的加载模型的方式是使用 [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) 包中提供的 `useGLTF` 组合式函数。
+
+```ts
+import { useGLTF } from '@tresjs/cientos'
+
+const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf')
+```
+
+使用 `useGLTF` 的一个优点是，你可以传递一个 `draco` 道具来启用模型的 [Draco 压缩](https://threejs.org/docs/index.html#examples/zh/loaders/DRACOLoader)。这将减小模型的大小并提高性能。
+
+```ts
+import { useGLTF } from '@tresjs/cientos'
+
+const { scene, nodes, animations, materials } = await useGLTF('/models/AkuAku.gltf', { draco: true })
+```
+
+或者，你可以使用 `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" /> // 请注意，这里的 "MyModel" 只是一个占位符
+  </TresCanvas>
+</template>
+```
+
+## 使用 `GLTFModel`
+
+`GLTFModel` 组件是 `useGLTF` 的包装器，可从 [@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>
+```
+
+这种特殊的方法更直接，但它让你对模型的控制更少。
+
+## useFBX
+
+`useFBX` 组合式函数可从 [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) 包中获得。
+
+```ts
+import { useFBX } from '@tresjs/cientos'
+
+const model = await useFBX('/models/AkuAku.fbx')
+```
+
+然后，将场景添加到你的场景中非常简单：
+
+```html{2}
+<TresCanvas shadows alpha>
+    <primitive :object="scene" />
+</TresCanvas>
+```
+
+## FBXModel
+
+`FBXModel` 组件是 `useFBX` 的包装器，可从 [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) 包中获得。它的用法类似于 `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/zh/cookbook/load-textures.md

@@ -0,0 +1,85 @@
+---
+title: 加载纹理
+description: 将纹理贴图添加到你的TresJS对象。
+author: alvarosabu
+thumbnail: /recipes/load-textures.png
+difficulty: 1
+---
+
+# 加载纹理
+
+> 本示例中使用的所有纹理均来自 [ambientcg](https://ambientcg.com/).
+
+三维 (3D) 纹理是包含多个数据层的图像，可以表示体积或模拟三维结构。 这些纹理通常用于 3D 图形和视觉特效中，以增强场景和物体的真实感和复杂性。
+
+<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==" />
+
+在 TresJS 中加载 3D 纹理有两种方法：
+
+## 使用 `useLoader`
+
+组合式函数 `useLoader` 允许您传递任何类型的 three.js 加载器和加载资源的 URL。它会返回一个包含已加载资源的 `Promise`。
+
+有关如何使用 `useLoader` 的详细说明，请查看 [useLoader](/zh/api/composables#use-loader) 文档。
+```ts
+import { useLoader } from '@tresjs/core'
+import { TextureLoader } from 'three'
+
+const texture = useLoader(TextureLoader, '/Rock035_2K_Color.jpg')
+```
+
+然后就可以将纹理传递给材质：
+
+```html
+<Suspense>
+  <TresCanvas>
+    <TresMesh>
+      <TresSphereGeometry :args="[1,32,32]" />
+      <TresMeshStandardMaterial :map="texture" />
+    </TresMesh>
+  </TresCanvas>
+</Suspense>
+```
+
+请注意在上面的示例中，我们使用 `Suspense` 组件包装 `TresCanvas` 组件。这是因为 `useLoader` 返回一个 `Promise，我们需要等待它解析后才能渲染场景。`
+
+## 使用 `useTexture`
+
+一种更方便的加载纹理的方式是使用 `useTexture` 组合式函数。它接受一个 URL 数组或一个具有映射纹理路径的单个对象。
+
+要了解有关 `useTexture` 的更多信息，请查看 [useTexture](/zh/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'
+})
+```
+
+
+与前面的示例类似，我们可以通过 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/zh/cookbook/orbit-controls.md

@@ -0,0 +1,115 @@
+---
+title: OrbitControls 轨道控制器
+description: 如何使用 OrbitControls 轨道控制器与场景进行交互。
+author: alvarosabu
+thumbnail: /recipes/orbit-controls.png
+difficulty: 1
+---
+
+# 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#examples/zh/controls/OrbitControls)是一种摄像机控制器，可让您围绕目标运行。这是探索场景的绝佳方式。
+
+然而，它并不是 ThreeJS 的核心部分。因此，要使用它，您需要从 `three/addons/controls/OrbitControls` 模块导入它。
+
+这会产生一个问题，因为 **TresJS** 仅会为 ThreeJS 核心对象自动创建组件目录，以便您可以将它们作为组件使用。
+
+幸运的是，**TresJS** 提供了一种扩展组件目录的方法。您可以使用核心库中的 `extend` 方法来实现。
+
+有关扩展您的 TresJS 目录的更多信息，请参考 [扩展](/zh/advanced/extending.md) 部分。
+
+## 使用轨道控制器
+
+要使用 `OrbitControls` 你需要从 `three/addons/controls/OrbitControls` 模块导入它。
+
+```js
+import { OrbitControls } from 'three/addons/controls/OrbitControls'
+```
+
+接下来，你需要使用 `extend` 方法扩展组件目录。
+
+```js
+import { extend } from '@tresjs/core'
+import { OrbitControls } from 'three/addons/controls/OrbitControls'
+
+extend({ OrbitControls })
+```
+
+现在，你可以在你的场景中使用 `TresOrbitControls` 组件了。
+
+```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>
+```
+
+由于 [轨道控制器（OrbitControls）](https://threejs.org/docs/index.html#examples/zh/controls/OrbitControls) 需要相机和渲染器的引用，因此你需要将它们作为参数传递。
+
+你可以使用 [useTres](/zh/api/composables#usetres) 组合式函数获取相机和渲染器。
+
+```ts
+import { useTres } from '@tresjs/core'
+
+const { state } = useTres()
+```
+
+因此，最终代码如下所示：
+
+```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>
+```
+
+## 使用 `cientos` 的 OrbitControls
+
+现在进入精彩的部分了！ ✨
+
+`cientos` 包提供了一个名为 `<OrbitControls />` 的组件，它是 [`three-stdlib`](https://github.com/pmndrs/three-stdlib) 模块中 `OrbitControls` 的封装。
+
+最棒的是？ 您不需要扩展目录或传递任何参数。
+
+它直接可用！💯
+
+
+```vue
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
+    <OrbitControls />
+  </TresCanvas>
+</template>
+```

docs/zh/cookbook/shaders.md

@@ -0,0 +1,173 @@
+# 着色器
+
+本指南将帮助你开始在 TresJS 中使用着色器。
+
+我们将构建一个带有 blob 的简单场景。然后，我们将对 blob 进行动画处理，使其柔和地扭曲。
+
+::: warning
+_需要了解着色器工作原理的基本知识_
+:::
+
+<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==" />
+
+## 设置场景（可选）
+
+我们导入所需的所有模块，为了方便，我们可以使用 cientos 中的轨道控件，[点击此处查看方法](/zh/cookbook/orbit-controls)。
+
+现在，我们将相机放在 `[11,11,11]` 位置。
+
+最后，为了帮助我们确定位置，我们添加一个简单的平面，绕 X 轴旋转，单位为 `[10, 10]`。
+
+```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
+
+如你所知，[ThreeJs](https://threejs.org/) 中的每个实例都可以在 **TresJs** 中使用，`ShaderMaterial` 也是如此，我们只需要添加 `Tres` 前缀即可使用它。
+
+对于我们的 blob ，我们可以使用简单的 `SphereGeometry`，添加一些 `widthSegments` 和 `heightSegments` 来创建平滑效果，并将 blob 放在 Y 轴正方向的 4 个单位处
+
+```vue
+<TresMesh :position="[0, 4, 0]">
+  <TresSphereGeometry :args="[2, 32, 32]" />
+  <TresShaderMaterial />
+</TresMesh>
+```
+
+`ShaderMaterial` 接受特殊属性，如 `uniforms` `vertexShader` 和 `fragmentShader`，因此我们可以在脚本部分创建它，并与我们的实例进行绑定。
+
+对于此示例，我们的 uniforms 如下所示：
+
+```ts
+import { Vector2 } from 'three'
+
+//...
+const uniforms = {
+  uTime: { value: 0 },
+  uAmplitude: { value: new Vector2(0.1, 0.1) },
+  uFrequency: { value: new Vector2(20, 5) },
+}
+//..
+```
+
+我们的片段着色器如下所示：
+
+```ts
+//...
+const fragmentShader = `
+precision mediump float;
+varying vec2 vUv;
+
+void main() {
+    gl_FragColor = vec4(1.0, vUv.y, 0.5, 1.0);
+}
+`
+//..
+```
+
+最后是我们的顶点着色器：
+
+```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;
+}
+`
+//..
+```
+
+## 为 blob 添加动画
+
+类似于我们在 [基本动画](/zh/cookbook/basic-animations) 示例中学习到的，我们首先使用 [模板引用](https://cn.vuejs.org/guide/essentials/template-refs.html) 引用 blob 
+
+```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>
+```
+ 获得引用后，我们可以使用 `onLoop` 回调为 `uTime` 添加动画。
+
+ ```ts
+import { TresCanvas, useRenderLoop } from '@tresjs/core'
+ 
+ //...
+ const { onLoop } = useRenderLoop()
+ 
+onLoop(({ elapsed }) => {
+   if (blobRef.value) {
+     blobRef.value.material.uniforms.uTime.value = elapsed
+   }
+})
+ //...
+```
+
+就这样，我们的基本着色器顺利运行。
+
+## 使用 GLSL vite 插件（可选）
+
+_此步骤完全是可选的，并且超出了 **TresJs** 团队的范围_
+
+将着色器定义为内联形式并不总是最好的主意，但是如果你正在使用 [vite](https://vitejs.dev/)，你可以通过使用 [vite-plugin-glsl](https://www.npmjs.com/package/vite-plugin-glsl) 将你的 `GLSL` 文件放在另一个文件中（查看链接以获取官方文档）。
+
+你可以拥有类似于这样的结构：
+
+```
+├── src/
+│   ├── myTresJsComponent.vue
+│   ├── shaders/
+│       ├── vertexShader.glsl
+│       ├── fragmentShader.glsl
+```

docs/zh/cookbook/text-3d.md

@@ -0,0 +1,202 @@
+---
+title: 3D 文本
+description: 轻松添加3D文本
+author: alvarosabu
+thumbnail: /recipes/text-3d.png
+difficulty: 1
+---
+
+# 3D 文本
+
+[TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) 是我们在场景中添加 3D 文本的一种方式。
+
+<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=="/>
+
+然而，它不是 ThreeJS 内核的一部分。因此，要使用它，你需要从 `three/addons/controls/TextGeometry` 模块中导入它。
+
+这会产生一个问题，因为 **TresJS** 会自动创建 Three 内核的目录，以便你可以将它们用作组件。
+
+幸运的是，**TresJS** 提供了一种扩展组件目录的方法。你可以使用核心库中的 `extend` 方法来做到这一点。
+
+有关扩展 TresJS 目录的更多信息，请参阅 [extending](/advanced/extending.md) 部分。
+
+## 使用 TextGeometry
+
+要使用 `TextGeometry`，你需要从 `three/addons/geometries/TextGeometry` 模块中导入它。
+
+```js
+import { TextGeometry } from 'three/addons/geometries/TextGeometry'
+```
+
+然后，你需要使用 `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) 只需要一个必填参数，即字体，你可以在下面看到一个示例。
+
+```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))
+  }
+})
+```
+
+现在，你可以在场景中的 TresMesh 内使用 `TresTextGeometry` 组件
+
+```vue
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <TresMesh>
+      <TresTextGeometry
+        :args="['TresJS', { font, ...fontOptions }]"
+        center
+      />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+然后，正如示例中所示，你可以传递一个包含所需配置的对象。
+
+```ts
+const fontOptions = {
+  size: 0.5,
+  height: 0.2,
+  curveSegments: 5,
+  bevelEnabled: true,
+  bevelThickness: 0.05,
+  bevelSize: 0.02,
+  bevelOffset: 0,
+  bevelSegments: 4,
+}
+```
+
+我们还可以传递一个 matcapTexture 来添加最终细节，在 TresMesh 内使用 TresMeshNormalMaterial
+
+```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>
+```
+
+因此，最终代码如下所示：
+
+```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>
+```
+
+我知道这看起来工作量很大，但好消息是，还有一种更简单的方法
+
+## 来自 `cientos` 的 TextGeometry
+
+`cientos` 包提供了一个名为 `<Text3D />` 的组件，它是 [`three-stdlib`](https://github.com/pmndrs/three-stdlib) 模块中的 `TextGeometry` 的包装器。
+
+最棒的部分？你无需扩展目录，只需传递字体参数即可。
+它就能正常工作。💯（如果没有提供文本，则文本将为 TresJS）
+
+```vue
+<template>
+  <TresCanvas
+    shadows
+    alpha
+  >
+    <Text3D :font="fontPath" />
+  </TresCanvas>
+</template>
+```
+
+我们可以将选项作为 props 传递
+
+```html
+<Text3D :font="fontPath" :text="my 3d text" :size="0.8" />
+```
+
+如果未提供选项，则默认值为：
+
+```js
+size: 0.5,
+height: 0.2,
+curveSegments: 5,
+bevelEnabled: true,
+bevelThickness: 0.05,
+bevelSize: 0.02,
+bevelOffset: 0,
+bevelSegments: 4,
+```
+
+默认情况下，ThreeJS 中的文本从网格初始位置开始，因此为 [0,0,0]，文本将从那里开始，但我们只需传递标志“center”即可将其居中
+
+```vue
+<Text3D :font="fontPath" :text="my 3d text" center />
+```

docs/zh/debug/devtools.md

@@ -0,0 +1,26 @@
+# 开发工具
+
+开发人员在浏览器上创建 3D 体验时面临的最困难的事情之一就是调试。浏览器“画布”是一个黑匣子，很难知道里面发生了什么。[ThreeJS](https://threejs.org/) 的命令式特性使其难以调试，必须依赖 `console.log` 来查看发生了什么，或者依赖第三方来微调和检查场景。
+
+别让我来检查你场景的性能。😱
+
+![开发人员调试 3D](/debug-3D.png)
+
+TresJS 的目标之一是在浏览器上处理 3D 场景时提供**最佳 DX（开发人员体验）**。由于生态系统的声明式特性以及 Vue 生态系统提供的各种解决方案，例如 Vue Devtools、Nuxt 和 Vite，我们可以为开发人员提供更好的工具来调试他们的场景。
+
+## 介绍开发工具
+
+从 <Badge text="^3.7.0" /> 开始，我们引入了 TresJS Devtools，这是 [官方 Vue Chrome Devtools](https://devtools.vuejs.org/guide/installation.html) 的一个自定义检查器选项卡，允许你检查你的 TresJS 场景和组件。
+
+![TresJS Devtools](/vue-chrome-devtools.png)
+
+### 特性
+
+- **场景检查器**：使用类似于 Vue Devtools 组件检查器的树视图检查当前场景及其组件。
+- **内存分配**：查看组件占用了多少内存。
+- **对象检查器**：检查场景中选定对象及其子对象的属性。
+- **可编辑属性**：是的，你可以编辑选定对象及其子对象的属性，并实时查看更改。
+
+![](/devtools-scene-inspector.png)
+
+尽情享受新的 Devtools，并告诉我们你的想法！🎉

docs/zh/directives/v-always-look-at.md

@@ -0,0 +1,61 @@
+# v-always-look-at 👀
+
+使用 **TresJS** 提供的新指令 `v-always-look-at`，您可以轻松地使 [Object3D](https://threejs.org/docs/index.html?q=object#api/en/core/Object3D) 始终朝向特定位置，可以传入 Vector3 对象或数组。
+
+## 推荐使用
+
+```vue{3,9}
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+import { Box, vAlwaysLookAt } from '@tresjs/cientos'
+</script>
+<template>
+    <TresCanvas >
+      <TresPerspectiveCamera :position="[0, 2, 5]" />
+      <Box
+        v-always-look-at="new Vector3(0, 0, 0)"
+      />
+  </TresCanvas>
+</template>
+```
+无论 Box 移动到何处，它都将始终朝向位置 [0,0,0]。
+
+### 为什么不使用内置的 look-at 方法呢？
+
+您可能会问，我可以直接在组件中使用 `:look-at` 方法，为什么我需要这个呢？
+
+答案是使用 `:look-at` 方法时，您只会在实例挂载时指示其一次性朝向该位置，然后如果对象更改，它将不会更新。
+
+### 您还可以查看其他实例！
+
+另一个优势是您可以查看一个在移动中的实例，例如使用相机，如下所示：
+
+```vue{4,6,20,23}
+<script setup lang="ts">
+import { shallowRef } from 'vue'
+import { TresCanvas, useRenderLoop } from '@tresjs/core'
+import { Box, vAlwaysLookAt } from '@tresjs/cientos'
+
+const sphereRef = shallowRef()
+
+const { onLoop } = useRenderLoop()
+
+// 在这里，我们更新了球体的位置，相机将始终跟随该对象
+onLoop(({ elapsed }) => {
+  if (sphereRef.value) {
+    sphereRef.value.value.position.y = Math.sin(elapsed) * 1.5
+  }
+})
+</script>
+<template>
+    <TresCanvas >
+      <TresPerspectiveCamera :position="[0, 2, 5]"
+        v-always-look-at="sphereRef"
+      />
+      <Sphere
+        ref="sphereRef"
+        :scale="0.5"
+      />
+  </TresCanvas>
+</template>
+```

docs/zh/directives/v-distance-to.md

@@ -0,0 +1,36 @@
+# v-distance-to
+
+你有尝试过计算两个Object3Ds之间的距离吗？
+
+有了新的指令 `v-distance-to` ，比之前更容易了，你只需指定目标对象进行测量，结果将打印在控制台中。
+
+此外，将创建一个箭头来指示你正在测量的对象。
+
+```vue{2,8,13}
+<script setup lang="ts">
+import { OrbitControls, Sphere, vLog } from '@tresjs/cientos'
+</script>
+<template>
+  <TresCanvas v-bind="gl">
+    <TresPerspectiveCamera :position="[0, 2, 5]" />
+    <Sphere
+      ref="sphere1Ref"
+      :position="[-2, slider, 0]"
+      :scale="0.5"
+    />
+    <Sphere
+      v-distance-to="sphere1Ref"
+      :position="[2, 0, 0]"
+      :scale="0.5"
+    />
+    <TresGridHelper :args="[10, 10]" />
+    <OrbitControls />
+  </TresCanvas>
+</template>
+```
+
+`v-distance-to`是响应式的，因此它与 @tres/leches 完美配合🍰.
+
+::: warning
+`v-distance-to` 不会在renderLoop中测量运动中的对象。
+:::

docs/zh/directives/v-light-helper.md

@@ -0,0 +1,34 @@
+# v-light-helper 🔆
+
+使用 **TresJS** 提供的新指令 v-light-helper，您只需一行代码即可快速为灯光添加相应的辅助工具😍。
+
+支持以下灯光类型：
+- DirectionalLight 方向光
+- PointLight 点光源
+- SpotLight 聚光灯
+- HemisphereLight 半球光
+
+## 推荐使用
+
+```vue{2,8,11,14,17}
+<script setup lang="ts">
+import { OrbitControls, Sphere, vLightHelper } from '@tresjs/cientos'
+</script>
+<template>
+  <TresCanvas >
+    <TresPerspectiveCamera :position="[0, 2, 5]" />
+    <TresDirectionalLight
+      v-light-helper
+    />
+    <TresPointLight
+      v-light-helper
+    />
+    <TresSpotLight
+      v-light-helper
+    />
+    <TresHemisphereLight
+      v-light-helper
+    />
+  </TresCanvas>
+</template>
+```

docs/zh/directives/v-log.md

@@ -0,0 +1,51 @@
+# v-log
+
+### 实际场景
+当你需要记录实例时，你需要使用 `ref` 引用，然后将它们记录下来：
+
+```vue
+<script setup lang="ts">
+import { shallowRef, watch } from 'vue'
+
+const sphereRef = shallowRef()
+
+watch(sphereRef, (value) => {
+  console.log(value) // 只是为了记录log?!!! 😫
+})
+</script>
+
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera :position="[0, 2, 5]" />
+    <Sphere
+      ref="sphereRef"
+      :scale="0.5"
+    />
+    <OrbitControls />
+  </TresCanvas>
+</template>
+```
+为了简单的日志而添加了大量的代码？
+
+## 推荐使用
+
+通过 **TresJS** 提供的新指令 `v-log` ，您可以通过将其添加到实例中来记录日志。
+
+```vue{2,10,12}
+<script setup lang="ts">
+import { OrbitControls, Sphere, vLog } from '@tresjs/cientos'
+</script>
+<template>
+    <TresCanvas >
+    <TresPerspectiveCamera :position="[0, 2, 5]" />
+    <Sphere
+      ref="sphereRef"
+      :scale="0.5"
+      v-log:material  <!-- 仅打印材质 🎉 -->
+    />
+    <OrbitControls v-log />
+  </TresCanvas>
+</template>
+```
+
+请注意，可以配置一个修饰符，使用属性的名称，例如 `v-log:material`，将直接记录 material 属性。😍

docs/zh/guide/getting-started.md

@@ -0,0 +1,93 @@
+# 安装
+
+了解如何安装 TresJS
+
+::: code-group
+
+```bash [pnpm]
+pnpm add three @tresjs/core
+```
+
+```bash [npm]
+npm install three @tresjs/core
+```
+
+```bash [yarn]
+yarn add three @tresjs/core
+```
+
+:::
+
+> 最好与 Vue 3.x 和组合式 API 一起使用
+
+## Typescript
+
+TresJS 是用 Typescript 编写的，是完全类型化的。如果您使用的是 Typescript，您就能充分享受类型的好处。 只需要保证你安装了 three 的类型定义。
+
+::: code-group
+
+```bash [npm]
+npm install @types/three -D
+```
+
+```bash [yarn]
+yarn add @types/three -D
+```
+
+```bash [pnpm]
+pnpm add @types/three -D
+```
+
+:::
+
+## 开始
+
+你可以像其他的 Vue 插件一样安装 TresJS
+
+```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')
+```
+
+或者你可以直接在你的组件中使用
+
+```vue
+<script setup lang="ts">
+import { TresCanvas } from '@tresjs/core'
+</script>
+
+<template>
+  <TresCanvas>
+    <!-- Your scene here -->
+  </TresCanvas>
+</template>
+```
+
+::: tip
+出于性能和捆绑包大小的考虑，建议采用这种方法，树摇的效果会更好，而且您只需导入您使用的组件。
+:::
+
+## Vite
+
+由于 v2 是自定义渲染器，我们需要让应用程序的 `vue-compiler` 知道 Tres 的组件是被包含在内的，以避免出现 `[Vue warn]: Failed to resolve component` 警告。
+
+您只需将此添加到 vue 插件中的 `vite.config.ts`：
+
+```ts
+import { templateCompilerOptions } from '@tresjs/core'
+
+export default defineConfig({
+  plugins: [
+    vue({
+      // Other config
+      ...templateCompilerOptions
+    }),
+  ]
+})
+```

docs/zh/guide/index.md

@@ -0,0 +1,114 @@
+# 简介
+
+<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 是用 Typescript 编写的，是完全类型化的。如果您使用的是 Typescript，您就能充分享受类型的好处。 只需要保证你安装了 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
+
+如果你使用 Vite，你需要在你的 `vite.config.ts` 中添加下面的配置:
+
+```ts
+import { templateCompilerOptions } from '@tresjs/core'
+
+export default defineConfig({
+  plugins: [
+    vue({
+      // Other config
+      ...templateCompilerOptions
+    }),
+  ],
+}),
+```
+
+要使模板编译器能与自定义渲染器一起工作，并且不会在控制台上发出警告，这样做是必须的。获得更多信息，请点击[此处](/guide/troubleshooting.html)。
+
+## 线上尝试
+
+### 演练场
+
+你可以在官方[演练场](https://play.tresjs.org/)中线上尝试 TresJS。尝试一下：
+
+<iframe src="https://play.tresjs.org/" class="w-full rounded shadow-lg outline-none border-none aspect-4/3"></iframe>
+
+### StackBlitz
+
+我们现在有一个全新的[StackBlitz](https://stackblitz.com/)模板供线上尝试 TresJS。尝试一下：
+
+![](/stackblitz-starter.png)
+
+<StackBlitzEmbed projectId="tresjs-basic" />
+
+## 实验室
+
+我们同时也拥有一个使用 TresJS 制作的实例展示实验室。点击[这里](https://lab.tresjs.org/)来查看。
+
+![](/tresjs-lab.png)
+
+## 动机
+
+ThreeJS 在创建超棒 **WebGL** 3D 网站方面是一个奇妙的库。同时他也是一个保持不断更新的库，一些对其封装的维护者，如 [TroisJS](https://troisjs.github.io/)，往往很难跟上其所有的更新。
+
+React 生态系统中有一个令人印象深刻的使用**自定义渲染器**的解决方案叫 [React-three-fiber](https://docs.pmnd.rs/react-three-fiber)，它能让你使用一些可重用，独立的对状态做出反应的组件进行声明式的构建你的场景。
+
+我在 VueJS 生态系统中寻找类似的东西时，发现了这个名为 [Lunchbox](https://github.com/breakfast-studio/lunchboxjs) 的神奇库，它的工作原理与 R3F 相同，提供了一个[自定义的 Vue3 渲染器](https://cn.vuejs.org/api/custom-renderer.html)。我也在不断改进这个库，让它变得像 R3F 一样成熟、功能丰富。
+
+同时唯一的问题是，混合编译不同的渲染器是 Vue 社区仍在努力解决的问题 —— 更多信息参阅[此处](https://github.com/vuejs/vue-loader/pull/1645)。
+
+```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')
+```
+
+因此，我受到这两个库的启发，为 ThreeJS 创建了一个 Vue 自定义渲染器。这就是 **TresJS v2**。
+

docs/zh/guide/migration-guide.md

@@ -0,0 +1,220 @@
+# 迁移指南
+
+本指南旨在帮助您从 v1 迁移到最新版本的 TresJS 🤩✨ 。
+
+::: code-group
+
+```bash [pnpm]
+pnpm update @tresjs/core
+```
+
+```bash [npm]
+npm update @tresjs/core
+```
+
+```bash [yarn]
+yarn upgrade @tresjs/core
+```
+
+:::
+
+## 有什么变化?
+
+### Vue 自定义渲染器
+
+**TresJS** 现在是一个位于一个包装组件中的 [Vue 自定义渲染器](https://vuejs.org/api/custom-renderer.html#createrenderer)，该组件 `TresCanvas` 负责为您创建 `WebGLRenderer` 和 `Scene` 创建一个 **新的 Vue App实例** 来渲染场景。
+
+### Typescript 支持以及智能提示 🦾
+
+![TresJS Intellisense](/v2-intellisense.gif)
+
+这可能是 TresJS **最需要的功能**。现在，Tres 组件可与 Volar 配合使用，并提供类型智能提示。
+
+**TresJS** 现在在构建时为基于 ThreeJS 对象清单的所有组件生成类型声明。这意味着您可以使用 ThreeJS 中的所有组件并为它们获取类型智能提示。
+
+### Tres 插件现在是可选项👍
+
+`TresPlugin` 现在是可选的。您可以在没有它的情况下使用 TresJS，方法是直接从 `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
+出于性能和捆绑包大小的考虑，建议采用这种方法，树摇的效果会更好，而且您只需导入您使用的组件。
+:::
+
+### 不再需要 TresScene
+
+ `<TresScene />`  组件现已弃用，因为场景现在由 `<TresCanvas />`创建.
+
+一开始，我认为为场景创建一个单独的组件，在语义方面保持与普通 ThreeJS 相似是个好主意，但事实证明这并没有什么用处。
+
+现在您可以创建这样一个场景：
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera
+      :position="cameraPosition"
+      :fov="cameraFov"
+      :aspect="cameraAspect"
+      :near="cameraNear"
+      :far="cameraFar"
+    />
+    <TresMesh :geometry="geometry" :material="material" />
+  </TresCanvas>
+</template>
+```
+
+要迁移代码，只需移除 `<TresScene />` 组件并将子组件移至 `<TresCanvas />` 组件内即可。
+
+### `useCatalog` 现已废弃
+
+`useCatalog`函数现已废弃。现在可以直接从 `@tresjs/core` 中导入目录。
+
+您可以在此处阅读有关它的更多信息：[Extending](/zh/advanced/extending.md)
+
+将如下代码：
+
+```ts {2,5,7}
+// 错误的 ❌
+import { useCatalog } from '@tresjs/core'
+import { TextGeometry } from 'three/addons/geometries/TextGeometry'
+
+const { extend } = useCatalog()
+
+extend({ TextGeometry })
+```
+
+转换成：
+
+```ts {2,6}
+// 正确的 ✅
+import { extend } from '@tresjs/core'
+import { TextGeometry } from 'three/addons/geometries/TextGeometry'
+
+// 将元素添加到目录中
+extend({ TextGeometry })
+```
+
+### 模型的`getModel`实例方法现已废弃
+
+`getModel`方法现已废弃. 你可以直接访问`model`的属性.
+
+将如下代码：
+
+```vue {7,9-12}
+// 错误的 ❌
+<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>
+```
+
+转换成：
+
+```vue {7,9-12}
+// 正确的 ✅
+<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>
+```
+
+### 相机需要放置于任何控制器之前 🎥
+
+`TresOrbitControls`组件在组件树内需要处于相机之后。这是因为控制器需要知道相机才能工作。
+
+将如下代码：
+
+```vue {3,5}
+// 错误的 ❌
+<template>
+  <TresCanvas>
+    <TresOrbitControls />
+    <TresPerspectiveCamera />
+  </TresCanvas>
+</template>
+```
+
+转换成：
+
+```vue {3,5}
+// 正确的 ✅
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera />
+    <TresOrbitControls />
+  </TresCanvas>
+</template>
+```
+
+## UseTres 现在变成了 useTresContext <Badge type="warning" text="^3.0.0" />
+
+对于 v3，我们重新设计了整个状态逻辑，使其更灵活、更易于用于插件作者和生态系统包。我们现在不再像 v2 那样使用存储，而是使用基于 `provide/inject`。
+
+`useTres` 函数现在是 `useTresContext` 函数的别名，以避免破坏演示和实验，但从现在起请考虑使用 `useTresContext`。
+
+您现在可以直接获取 `scene` 和 `renderer`的引用以及其他属性，而不是一个大的 reactive 对象。
+
+将如下代码：
+
+```ts {2}
+// 错误的 ❌
+import { useTres } from '@tresjs/core'
+
+const { state, setState } = useTres()
+
+console.log(state.scene)
+```
+
+转换成：
+
+```ts {2}
+// 正确的 ✅
+import { useTresContext } from '@tresjs/core'
+
+const { scene, renderer } = useTresContext()
+
+console.log(scene.value)
+```
+
+有关新上下文对象提供系统的更多详细信息，请阅读 [API 文档](/zh/api/composables.md) 部分。

docs/zh/guide/nuxt.md

@@ -0,0 +1,58 @@
+# Nuxt 模块 `@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>
+
+这里是 TresJS 的官方 Nuxt 模块🎉。
+
+仓库在[这里](https://github.com/Tresjs/nuxt)
+
+## 安装
+
+::: code-group
+
+```bash [pnpm]
+pnpm add three @tresjs/nuxt 
+```
+
+```bash [npm]
+npm install three @tresjs/nuxt 
+```
+
+```bash [yarn]
+yarn add three @tresjs/nuxt 
+```
+
+:::
+
+## 特性
+
+- 🤓 从 [TresJS 生态系统](https://github.com/orgs/Tresjs/repositories)自动导入组件和组合式函数
+- `TresCanvas` 仅在客户端渲染，您无需为组件文件名添加 `.client` 或是使用 `<ClientOnly />`
+- 自动配置 vue 编译器支持 TresJS 组件，了解[为什么](/guide/troubleshooting.html#failed-resolve-component-trescomponent-%F0%9F%A4%94)？
+- Nuxt 所有附带的开发体验魔法
+
+## 使用方式
+
+将 `@tresjs/nuxt` 添加到 `nuxt.config.ts` 的 `module` 部分
+
+```js
+export default defineNuxtConfig({
+  modules: ["@tresjs/nuxt"],
+});
+```
+
+就这样！你现在可以在你的 Nuxt 应用中开始使用 `@tresjs/nuxt` ✨
+
+如果你想使用TresJS生态系统中的任何包，你可以安装你想使用的包，它们将由模块自动导入🧙🏼。
+
+| 包名                     | 版本                                                                                            |
+| --------------------------- | :------------------------------------------------------------------------------------------------- |
+| [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
+# 使用 pnpm
+pnpm add @tresjs/cientos @tresjs/post-processing
+```

docs/zh/guide/troubleshooting.md

@@ -0,0 +1,88 @@
+# 常见问题及解决方法的趣味指南
+
+![Troubleshooting](https://media.giphy.com/media/LHZyixOnHwDDy/giphy.gif)
+
+欢迎使用 **TresJS v2 故障排除指南**。其中 3D 代表 _"Dazzlingly Delightful Difficulties"_！我们知道 3D 可以像缠结的毛线球🧶一样复杂，也可以像键盘上的猫🐈 ⌨️一样不可预测，但不要害怕！
+
+本指南旨在帮助您解决使用 TresJS v2 时可能遇到的最常见问题。
+
+## 我看不到我的3D场景 😭!
+
+您遵循了[入门指南](/zh/guide/getting-started.md)，但仍不能看到渲染的场景。
+
+以下是您可能无法看到场景的最常见原因：
+
+### 检查画布的高度📏
+
+另一个常见问题是 `TresCanvas` 组件默认创建一个`canvas`画布元素，该元素采用父元素的宽和高。如果父元素没有高度，则画布也没有高度。
+
+![No height found](/canvas-height.png)
+
+您还将在控制台中看到以下错误：
+
+![Canvas height warning](/canvas-height-warning.png)
+
+将父元素的高设置为 `100%` 是一种最简单修复此问题的的方法：
+
+```css
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  width: 100%;
+}
+#app {
+  height: 100%;
+  width: 100%;
+  background-color: #000;
+}
+```
+
+或者你可以设置组件 `TresCanvas` 的 `window-size` prop：
+
+```vue
+<TresCanvas window-size>
+  <TresPerspectiveCamera />
+  <TresOrbitControls />
+</TresCanvas>
+```
+
+## Failed resolve component: TresComponent... 🤔
+
+![](/failed-to-resolve-component.png)
+
+由于 **TresJS v2** 在主 Vue App 实例中使用了 Vue 自定义渲染器，因此作为父级的核心 Vue 渲染器不会识别组件内部的 `TresCanvas` 组件。即使不影响渲染，也会在控制台中显示警告。
+
+![](/failed-to-resolve-component.png)
+
+目前，没有原生的 Vue 支持来定义 `<template />` 中使用的渲染器，但有一个快速的解决方法可以删除警告
+
+在你的 `vite.config.ts` 中将以下配置添加到 `@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,
+    }),
+  ],
+})
+```
+
+这将从控制台中删除警告。
+
+# 帮助我们让 TresJS 更完美! 😼
+
+我们知道，即使是最好的猫咪午睡者偶尔也会犯错误，我们需要您的帮助才能使 TresJS 变得更好！如果您发现错误，请在 repo 中打开工单并**请提供重现链接**。
+
+::: warning
+没有提供重现链接的工单将被关闭
+:::
+
+我们的编码猫爱好者团队将采取行动，消除那些讨厌的错误，并为每个人改进 TresJS。让我们一起让 TresJS 成为 Vue 中 做 3D 渲染最好的的猫咪！

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

@@ -0,0 +1,171 @@
+# 你的第一个场景
+
+本指南将帮助您创建第一个 Tres 场景。 🍩
+
+<ClientOnly>
+<div style="aspect-ratio: 16/9; height: auto; margin: 2rem 0; border-radius: 8px; overflow:hidden;">
+  <DonutExample />
+</div>
+</ClientOnly>
+
+## 设置体验画布
+
+在我们创建场景前，我们需要一个什么来展示它。使用原始的 [ThreeJS](https://threejs.org/docs/index.html#manual/en/introduction/Creating-a-scene) 我们会需要创建一个 `canvas` HTML 元素来挂载 `WebglRenderer` 并初始化一个场景。
+
+通过 **TresJS** 你仅仅需要导入默认组件 `<TresCanvas />` 并把它添加到你的 Vue 组件的模板部分即可。
+
+```vue
+<script lang="ts" setup>
+import { TresCanvas } from '@tresjs/core'
+</script>
+
+<template>
+  <TresCanvas window-size>
+    <!-- 这里是您的场景 -->
+  </TresCanvas>
+</template>
+```
+
+::: warning
+重要的一点是所有依赖于场景的组件必须存在于 `<TresCanvas />`组件内。否则，他们不会被渲染。
+:::
+
+这个 `TresCanvas` 组件会在场景幕后做一些设置的工作:
+
+- 它创建一个 [**WebGLRenderer**](https://threejs.org/docs/index.html#api/zh/renderers/WebGLRenderer) 用于自动更新每一帧。
+- 它根据浏览器刷新率设置要在每一帧上调用的渲染循环。
+
+## 画布尺寸
+
+默认的情况下，`TresCanvas` 组件会跟随**父元素的宽高**，如果出现空白页，请确保父元素的大小合适。
+
+```vue
+<script lang="ts" setup>
+import { TresCanvas } from '@tresjs/core'
+</script>
+
+<template>
+  <TresCanvas>
+    <!-- 这里是您的场景 -->
+  </TresCanvas>
+</template>
+
+<style>
+html,
+body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  width: 100%;
+}
+#app {
+  height: 100%;
+  width: 100%;
+}
+</style>
+```
+
+如果您的场景不是用户界面的一部分，您也可以通过像这样的使用 `window-size` prop 来强制画布使用整个窗口的宽度和高度:
+
+```vue
+<script lang="ts" setup>
+import { TresCanvas } from '@tresjs/core'
+</script>
+
+<template>
+  <TresCanvas window-size>
+    <!-- 这里是您的场景 -->
+  </TresCanvas>
+</template>
+```
+
+## 创建一个场景
+
+我们只需要 4 个核心元素来创建 3D 体验:
+
+- 一个将摄像机和对象固定在一起的[**场景**](https://threejs.org/docs/index.html?q=scene#api/zh/scenes/Scene)。
+- 一个用于将场景渲染到 DOM 中的[**渲染器**](https://threejs.org/docs/index.html?q=renderer#api/zh/renderers/WebGLRenderer)。
+- 一个[**相机**](https://threejs.org/docs/index.html?q=camera#api/zh/cameras/Camera)
+- 一个[**对象**](https://threejs.org/docs/index.html?q=object#api/zh/core/Object3D)
+
+使用 **TresJS** 时，您只需将 `<TresCanvas />` 组件添加到 Vue 组件的模板中，它就会自动为您创建`Renderer`（`canvas` 作为 DOM 元素）和`Scene`。
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <!-- 这里是您的场景 -->
+  </TresCanvas>
+</template>
+```
+
+然后，您可以使用 `<TresPerspectiveCamera />` 组件来添加一个 [**透视相机**](https://threejs.org/docs/index.html#api/zh/cameras/PerspectiveCamera)
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <TresPerspectiveCamera />
+  </TresCanvas>
+</template>
+```
+
+::: warning
+一个常见的问题是相机默认位置是场景的原点（0,0,0），如果 prop `position` 为空， TresJS 会自动将相机的位置设置为 `[3,3,3]`。如果场景中未定义摄像机，则会自动添加透视摄像机。
+:::
+
+## 添加一个🍩
+
+那个场景看起来有点空，让我们添加一个基本对象。如果我们使用普通的 **ThreeJS**，我们需要创建一个 [**网格**](https://threejs.org/docs/index.html#api/zh/objects/Mesh) 对象，并在其上附加一个 [**材质**](https://threejs.org/docs/index.html#api/zh/materials/Material) 和一个 [**几何体**](https://threejs.org/docs/index.html#api/zh/core/BufferGeometry)，如下所示:
+
+```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)
+```
+
+**网格**是 three.js 中的基本场景对象，用于保存在 3D 空间中表示形状所需的几何体和材质。
+
+现在让我们看看如何使用 TresJS 轻松实现相同的事情。为此，我们将使用 `<TresMesh />` 组件，在默认插槽之间，我们将传递一个 `<TresTorusGeometry />` 和一个`<TresMeshBasicMaterial />`。
+
+```vue
+<template>
+  <TresCanvas window-size>
+    <TresPerspectiveCamera />
+    <TresMesh>
+      <TresTorusGeometry :args="[1, 0.5, 16, 32]" />
+      <TresMeshBasicMaterial color="orange" />
+    </TresMesh>
+  </TresCanvas>
+</template>
+```
+
+::: info
+请注意，我们不需要导入任何东西，这是因为 **TresJS** 会为**您使用的 CamelCase 的带有 Tres 前缀的 Three 对象自动生成一个 Vue 组件**。例如，如果要使用 `<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>
+```
+
+从这里开始，您可以开始向场景中添加更多对象，并调整组件的属性来查看它们如何影响场景。
+
+<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/zh/index.md

@@ -0,0 +1,35 @@
+---
+layout: home
+
+title: TresJS
+titleTemplate: VueJS 的 3D 解决方案
+
+hero:
+  name: TresJS
+  text: 将 Three 带到了 Vue 生态系统中
+  tagline: 用你喜欢的框架创建超棒的 3D 体验。
+  image:
+    src: /hero.png
+    alt: Tresjs
+  actions:
+    - theme: brand
+      text: 入门指南
+      link: /zh/guide/
+    - theme: alt
+      text: 为什么是 Tres ?
+      link: /zh/guide/#motivation
+
+features:
+  - icon: 💡
+    title: 声明式
+    details: 像使用 Vue 组件一样构建 3D 场景。
+  - icon: ⚡️
+    title: 由 Vite 驱动
+    details: 无论你的应用大小，模块热替换 (HMR) 总能保持快速运行。
+  - icon: 🥰
+    title: 不断更新
+    details: 为您带来 ThreeJS 所有最新的更新特性
+  - icon: 🌳
+    title: 生态系统
+    details: 使用像 `cientos` 或是 `postprocessing` 的包来扩展核心功能。或者你也可以添加你自己的。
+---

docs/zh/team.md

@@ -0,0 +1,35 @@
+---
+layout: page
+title: 认识团队
+description: TresJS 生态系统由一个国际化的团队负责开发和维护。
+---
+
+<script setup>
+import {
+  VPTeamPage,
+  VPTeamPageTitle,
+  VPTeamPageSection,
+  VPTeamMembers
+} from 'vitepress/theme'
+import { core } from '../_data/team'
+</script>
+
+<VPTeamPage>
+  <VPTeamPageTitle>
+    <template #title>认识团队</template>
+    <template #lead>
+      TresJS 生态系统由一个国际化的团队负责开发和维护。
+    </template>
+  </VPTeamPageTitle>
+  <VPTeamMembers :members="core" />
+  <!-- <VPTeamPageSection>
+    <template #title>Team Emeriti</template>
+    <template #lead>
+      Here we honor some no-longer-active team members who have made valuable
+      contributions in the past.
+    </template>
+    <template #members>
+      <VPTeamMembers size="small" :members="emeriti" />
+    </template>
+  </VPTeamPageSection> -->
+</VPTeamPage>