docs: chinese translations (#550)

* chore: copy all unnecessary file to zh dir

* docs(i18n): chinese translate of guide part

* docs(i18n): chinese translation of migration guide

* docs(i18n): fix some link related i18n

* docs(i18n): chinese translate of advanced part

* doc: Chinese translation of api and directives  (#1)

* doc(i18n): chinese translation of examples part

* doc(i18n): chinese translation of devtools

* doc: fix some chinese translation issues

* doc: fix composable description

* docs: fix some chinese tranaltion issues

* docs(i18n): keep up to cookbook section

* fix(docs): team data path

* fix(docs): some dead link in content

* docs(i18): some update translations for chinese

* docs: kept up with #589

* docs: wrong url for lab

---------

Co-authored-by: X-smart <xchaigl@gmail.com>

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/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/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>