docs: Chinese translation

docs/.vitepress/config.ts → docs/.vitepress/config/en.ts

@@ -1,32 +1,7 @@
-import Unocss from 'unocss/vite'
-import svgLoader from 'vite-svg-loader'
-import { defineConfig } from 'vitepress'
-import { version } from '../../packages/tres/package.json'
-import { version as cientosVersion } from '../../packages/cientos/package.json'
+import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'
 
-export default defineConfig({
-  locales: {
-    root: {
-      label: 'English',
-      lang: 'en',
-    },
-    es: {
-      label: 'Spanish',
-      lang: 'es',
-      link: '/es/guide',
-    },
-    zh: {
-      label: '简体中文',
-      lang: 'zh-CN',
-      link: '/zh/guide'
-    }
-  },
-
-  title: 'TresJS',
-  description: 'Declarative ThreeJS using Vue Components',
-  head: [['link', { rel: 'icon', type: 'image/svg', href: '/favicon.svg' }]],
+export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
   themeConfig: {
-    logo: '/logo.svg',
     sidebar: [
       {
         text: 'Guide',
@@ -162,12 +137,5 @@ export default defineConfig({
         ],
       }, */
     ],
-    socialLinks: [
-      /*  { icon: 'github', link: 'https://github.com/tresjs/tres' }, */
-      { icon: 'twitter', link: 'https://twitter.com/alvarosabu' },
-    ],
-  },
-  vite: {
-    plugins: [svgLoader(), Unocss()],
   },
-})
+}

docs/.vitepress/config/index.ts

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

docs/.vitepress/config/shared.ts

@@ -0,0 +1,19 @@
+import Unocss from 'unocss/vite'
+import svgLoader from 'vite-svg-loader'
+import { defineConfig } from 'vitepress'
+
+export const sharedConfig = defineConfig({
+  title: 'TresJS',
+  description: 'Declarative ThreeJS using Vue Components',
+  head: [['link', { rel: 'icon', type: 'image/svg', href: '/favicon.svg' }]],
+  themeConfig: {
+    logo: '/logo.svg',
+    socialLinks: [
+      /*  { icon: 'github', link: 'https://github.com/tresjs/tres' }, */
+      { icon: 'twitter', link: 'https://twitter.com/alvarosabu' },
+    ],
+  },
+  vite: {
+    plugins: [svgLoader(), Unocss()],
+  },
+})

docs/.vitepress/config/zh.ts

@@ -0,0 +1,130 @@
+import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'
+
+export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
+  themeConfig: {
+    sidebar: [
+      {
+        text: '指南',
+        items: [
+          // This shows `/guide/index.md` page.
+          { text: '简介', link: '/zh/guide/' },
+          { text: '快速开始', link: '/zh/guide/getting-started' },
+          { text: '您的第一个场景', link: '/zh/guide/your-first-scene' },
+        ],
+      },
+      {
+        text: 'API',
+        items: [
+          { text: '渲染器', link: '/zh/api/renderer' },
+          {
+            text: '实例, 参数 和 Props',
+            link: '/zh/api/instances-arguments-and-props',
+          },
+          {
+            text: '组合式 API',
+            link: '/zh/api/composables',
+          },
+          {
+            text: '事件',
+            link: '/zh/api/events',
+          },
+        ],
+      },
+      {
+        text: '示例',
+        items: [
+          { text: 'Orbit Controls', link: '/zh/examples/orbit-controls' },
+          { text: '基础动画', link: '/zh/examples/basic-animations' },
+          { text: '分组', link: '/zh/examples/groups' },
+          { text: '加载纹理', link: '/zh/examples/load-textures' },
+          { text: '加载模型', link: '/zh/examples/load-models' },
+          { text: '加载文本', link: '/zh/examples/text-3d' },
+        ],
+      },
+      {
+        text: '进阶',
+
+        items: [
+          { text: '扩展', link: '/zh/advanced/extending' },
+          {
+            text: '注意事项',
+            link: '/zh/advanced/caveats',
+          },
+        ],
+      },
+      {
+        text: 'Cientos 💛',
+        collapsible: true,
+        items: [
+          { text: '简介', link: '/zh/cientos/' },
+          {
+            text: 'Abstractions',
+            items: [
+              { text: 'Text3D', link: '/zh/cientos/abstractions/text-3d' },
+              {
+                text: 'useAnimations',
+                link: '/zh/cientos/abstractions/use-animations',
+              },
+              {
+                text: '环境',
+                link: '/zh/cientos/abstractions/environment',
+              },
+              {
+                text: 'useEnvironment',
+                link: '/zh/cientos/abstractions/use-environment',
+              },
+            ],
+          },
+          {
+            text: '控制器',
+            items: [
+              {
+                text: 'OrbitControls',
+                link: '/zh/cientos/controls/orbit-controls',
+              },
+              {
+                text: 'TransformControls',
+                link: '/zh/cientos/controls/transform-controls',
+              },
+            ],
+          },
+          {
+            text: '加载器',
+            items: [
+              { text: 'useGLTF', link: '/zh/cientos/loaders/use-gltf' },
+              { text: 'GLTFModel', link: '/zh/cientos/loaders/gltf-model' },
+              { text: 'useFBX', link: '/zh/cientos/loaders/use-fbx' },
+              { text: 'FBXModel', link: '/zh/cientos/loaders/fbx-model' },
+            ],
+          },
+          {
+            text: '几何',
+            items: [
+              { text: 'Box', link: '/zh/cientos/shapes/box' },
+              { text: 'Circle', link: '/zh/cientos/shapes/circle' },
+              { text: 'Cone', link: '/zh/cientos/shapes/cone' },
+              { text: 'Dodecahedron', link: '/zh/cientos/shapes/dodecahedron' },
+              { text: 'Icosahedron', link: '/zh/cientos/shapes/icosahedron' },
+              { text: 'Octahedron', link: '/zh/cientos/shapes/octahedron' },
+              { text: 'Plane', link: '/zh/cientos/shapes/plane' },
+              { text: 'Ring', link: '/zh/cientos/shapes/ring' },
+              { text: 'Sphere', link: '/zh/cientos/shapes/sphere' },
+              { text: 'Tetrahedron', link: '/zh/cientos/shapes/tetrahedron' },
+              { text: 'Torus', link: '/zh/cientos/shapes/torus' },
+              { text: 'TorusKnot', link: '/zh/cientos/shapes/torus-knot' },
+              { text: 'Tube', link: '/zh/cientos/shapes/tube' },
+            ],
+          },
+          {
+            text: '其他',
+            items: [{ text: 'useTweakpane', link: '/zh/cientos/misc/use-tweakpane' }],
+          },
+        ],
+      },
+    ],
+    nav: [
+      { text: '指南', link: '/zh/guide/' },
+      { text: 'API', link: '/zh/api/renderer' },
+    ],
+  },
+}

docs/zh/advanced/caveats.md

@@ -0,0 +1,109 @@
+# 注意事项 😱
+
+我们的目标是在 VueJS 中提供一种简单的使用 ThreeJS 的方式，并提供最佳的开发体验。所以，下面有一些需要注意的事项。
+
+## ~~HMR and ThreeJS~~
+
+:::info
+
+**TresJS** v1.7.0 🎉 已修复该 bug，您现在可以使用 HMR，不需要刷新页面了 🥹。
+
+:::
+
+热模块替换（HMR）是一种功能，它允许您在不重新加载页面的情况下更新代码。它极大的提高了开发效率。**TresJS** 基于 [Vite](https://vitejs.dev/) 构建。然而，让它与 ThreeJS 正确配合起来确实有些棘手。
+
+为什么呢？因为 Tres 采用声明式的方式构建场景。这意味着在 Vue 组件挂载后才创建实例并添加到场景中。困难之处在于需要找到将实例从场景中删除以及再次添加它的时机。
+
+虽然实现了最简单的效果，但并不完美。这意味着有时您需要重新刷新页面才能正确看到更改，特别是当您使用 [模板引用](https://v3.vuejs.org/guide/component-template-refs.html)来引用一个实例的时候。
+
+```vue
+<script setup lang="ts">
+const boxRef: Ref<TresInstance | null> = ref(null);
+
+onLoop(({ _delta, elapsed }) => {
+  if (boxRef.value) {
+    boxRef.value.rotation.y += 0.01;
+    boxRef.value.rotation.z = elapsed * 0.2;
+  }
+});
+</script>
+
+<template>
+  <TresMesh ref="boxRef" :scale="1" cast-shadow>
+    <TresBoxGeometry :args="[1, 1, 1]" />
+    <TresMeshStandardMaterial color="teal" />
+  </TresMesh>
+</template>
+```
+
+您如果修改 `TresMeshStandardMaterial` 组件的 `color`，您能立即看到颜色的改变。但是，您会发现立方体的旋转动画并未生效。这是由于立方体实例被销毁并重新创建了。
+
+:::tip
+当您修改了代码却未看到变化时，通常情况下应该请刷新页面。
+:::
+
+话虽如此，我们正在致力于找到更好的解决方案 😁。如果您有任何解决方法，请告诉我们。
+
+您可以参与我们的[关于 HMR 的讨论](https://github.com/Tresjs/tres/issues/23)
+
+## 响应式
+
+我们爱响应式 💚。这是 VueJS 最重要的特性之一。然而，在使用 ThreeJS 时，我们需要对此保持谨慎。
+
+Vue 的响应式系统基于 [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)。Vue3 通过这种方式自动跟踪数据对象的变化，并在数据更改时更新相应的 DOM 元素。
+
+由于在每一帧（60FPS）中会渲染场景并更新它，这意味着每秒会更新场景 60 次。如果更新的对象是响应式的，Vue 将尝试更新该对象同样多次。这不是个好主意 😅，会对性能造成影响。
+
+下图是使用 Proxy 对象和普通对象 的 benchmark
+
+<figure>
+  <img src="/proxy-benchmark.png" alt="Proxy vs Plain" style="width:100%">
+  <figcaption>Fig.1 - 每秒执行次数：普通对象 vs Proxy </figcaption>
+</figure>
+
+来源: [Proxy vs Plain Object](https://www.measurethat.net/Benchmarks/Show/12503/0/object-vs-proxy-vs-proxy-setter)
+
+若您必须使用响应式，请使用 [shallowRef](https://vuejs.org/api/reactivity-advanced.html#shallowref)
+
+不同于 `ref()`，
+
+和 `ref()` 不同，浅层 ref 的内部值将会原样存储和暴露，并且不会被深层递归地转为响应式。只有对 .value 的访问是响应式的， 详见 [VueJS 官方文档](https://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,64 @@
+# 扩展 🔌
+
+Tres 提供了基础的功能，但很容易添加第三方元素并将其扩展到其内部目录中。
+
+## 添加第三方元素
+
+大多数 3D 效果都会使用非 Three 核心模块中的 `OrbitControls` 。在 TresJS 中添加它，只需要引入该模块并在安装插件的时候作为 `extends` 的属性值即可:
+
+```js
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
+
+app.use(plugin, {
+  extends: {
+    OrbitControls,
+  },
+});
+```
+
+TresJS 自动将 `<TresOrbitControls>` 添加到目录中，然后您可以直接在模板中使用:
+
+```vue
+<template>
+  <TresCanvas shadows alpha>
+    <TresPerspectiveCamera :position="[5, 5, 5]" />
+    <TresScene>
+      <TresOrbitControls
+        v-if="state.renderer"
+        :args="[state.camera, state.renderer?.domElement]"
+      />
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+## 动态扩展元素 <Badge type="tip" text="^1.1.0" />
+
+你同样可以在某个组件中动态添加第三方元素:
+
+```vue{2,3,5,8,17,19}
+<script setup lang="ts">
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls'
+import { TextGeometry } from 'three/examples/jsm/geometries/TextGeometry'
+
+const { extend } = useCatalogue()
+
+// Add the element to the catalogue
+extend({ TextGeometry, OrbitControls })
+
+/* Rest of the code */
+</script>
+
+<template>
+  <TresCanvas shadows alpha>
+    <TresPerspectiveCamera :position="[5, 5, 5]" />
+    <TresScene>
+      <TresOrbitControls v-if="state.renderer" :args="[state.camera, state.renderer?.domElement]" />
+      <TresMesh>
+        <TresTextGeometry :args="['TresJS', { font, ...fontOptions }]" center />
+        <TresMeshMatcapMaterial :matcap="matcapTexture" />
+      </TresMesh>
+    </TresScene>
+  </TresCanvas>
+</template>
+```

docs/zh/api/composables.md

@@ -0,0 +1,186 @@
+# 组合式 API {#Composables}
+
+Vue3 的[组合式 API](https://vuejs.org/guide/extras/composition-api-faq.html#what-is-composition-api) 允许您创建可以在多个组件之间共享的可重用的逻辑，还允许您创建自定义钩子，在组件中使用。
+
+**TresJS** 利用组合式 API 创造了一系列组合式的函数，可以用于创建动画、场景交互等等。同时，它还可以用于创建更复杂的场景，可能仅使用 Vue 组件（纹理、加载器等）无法实现。
+
+这些组合式的函数已经被用于 **TresJS** 的核心包中，因此，您可以放心的使用。例如，需要在内部渲染循环中更新的组件使用 `useRenderLoop` 组合式函数注册一个回调函数，这样每次渲染器更新场景时都会调用该回调函数。
+
+## useRenderLoop {#useRenderLoop}
+
+`useRenderLoop` 是 **TresJS** 动画的核心。它允许您注册一个回调函数，在本地刷新率下被调用。这是 **TresJS** 中最重要的组合式函数。
+
+```ts
+const { onLoop, resume } = useRenderLoop();
+
+onLoop(({ delta, elapsed, clock, dt }) => {
+  // I will run at every frame ~ 60FPS (depending of your monitor)
+});
+```
+
+::: warning
+请留意使用这个组合式函数的性能影响。它会在每一帧运行，如果回调函数中有很多逻辑，可能会影响您应用的性能。特别是如果您正在更新响应式的状态或引用
+:::
+
+`onLoop` 回调函数接收的参数是一个基于 [THREE clock](https://threejs.org/docs/?q=clock#api/en/core/Clock) 的对象， 包含以下属性：
+
+- `delta`: delta 属性代表当前帧与上一帧之间的时间差，单位为秒
+- `elapsed`: 保存渲染循环运行的总时长
+
+`useRenderLoop` 的实现依赖于 [vueuse](https://vueuse.org/core/useRafFn/) 中的 `useRafFn`。感谢 [@wheatjs](https://github.com/orgs/Tresjs/people/wheatjs) 的贡献。
+
+### 渲染前和渲染后 {#Before and after render}
+
+在渲染器更新场景之前或之后都可以注册对应的回调函数。这对于测试 FPS 性能时很有用。
+
+```ts
+const { onBeforeLoop, onAfterLoop } = useRenderLoop();
+
+onBeforeLoop(({ delta, elapsed }) => {
+  // I will run before the renderer updates the scene
+  fps.begin();
+});
+
+onAfterLoop(({ delta, elapsed }) => {
+  // I will run after the renderer updates the scene
+  fps.end();
+});
+```
+
+### 暂停和恢复 {#Pause and resume}
+
+使用暴露出来的 `pause` 和 `resume` 方法可以暂停和恢复渲染循环。
+
+```ts
+const { pause, resume } = useRenderLoop();
+
+// Pause the render loop
+pause();
+
+// Resume the render loop
+resume();
+```
+
+使用 `isActive` 属性获取渲染循环的活动状态。
+
+```ts
+const { resume, isActive } = useRenderLoop();
+
+console.log(isActive); // false
+
+resume();
+
+console.log(isActive); // true
+```
+
+## useLoader {#useLoader}
+
+`useLoader` 组合式函数允许使用 [THREE.js loaders](https://threejs.org/docs/#manual/en/introduction/Loading-3D-models) 加载资源。它返回一个带有已加载资源的 Promise。
+
+```ts
+import { GLTFLoader } from "three/examples/jsm/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`: 用于向物体添加环境光遮蔽（在其他物体阻挡光线的区域添加阴影）的纹理
+
+下面展示了如何加载纹理。
+
+```ts
+const { map, displacementMap, normalMap, roughnessMap, metalnessMap, aoMap } =
+  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",
+  });
+```
+
+将纹理添加到材质上面。
+
+```vue
+<template>
+  <TresMesh>
+    <TresMeshSphereGeometry />
+    <TresMeshStandardMaterial
+      :map="map"
+      :displacementMap="displacementMap"
+      :normalMap="normalMap"
+      :roughnessMap="roughnessMap"
+      :metalnessMap="metalnessMap"
+      :aoMap="aoMap"
+    />
+  </TresMesh>
+</template>
+```
+
+与 `useLoader` 一样，使用 `useTexture` 时，可以使用 `async/await` 和 `then/catch`。采用此方式记得将组件包装在 `Suspense` 组件中。
+
+# useCatalogue {#useCatalogue}
+
+`useCatalogue` 组合式函数允许您扩展内部组件，它返回一个函数，您可以使用它来注册新的组件。
+
+这对于想要使用不属于 ThreeJS 核心的对象（如 [OrbitControls](https://threejs.org/docs/#examples/en/controls/OrbitControls) ）或第三方功能（如物理引擎）特别有用。
+
+```ts
+import { useCatalogue } from "@tresjs/core";
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
+
+const { extend } = useCatalogue();
+
+extend({ OrbitControls });
+```
+
+然后您就可以像下面这样使用新组件了。需要注意一点，新组件的前缀是 `Tres`，这样做是为了避免与 HTML 元素重名。
+
+```vue
+<template>
+  <TresCanvas shadows alpha>
+    <TresScene>
+      <TresOrbitControls
+        v-if="state.renderer"
+        :args="[state.camera, state.renderer?.domElement]"
+      />
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+# useTres <Badge type="warning" text="^1.7.0" /> {#useTres}
+
+`useTres` 组合式函数的目标是提供访问 **Tres** 的状态的入口。该状态包含默认的渲染器、相机、场景和其他有用的属性。
+
+```ts
+const { state } = useTres();
+
+console.log(state.camera); // THREE.PerspectiveCamera
+console.log(state.renderer); // THREE.WebGLRenderer
+```

docs/zh/api/events.md

@@ -0,0 +1,31 @@
+# 事件 <Badge type="warning" text="^1.6.0" /> {#Events}
+
+**TresJS** 中的网格对象与 `raycaster` 或者 `pointer` 交互时会触发鼠标事件
+
+<StackBlitzEmbed project-id="tresjs-events" />
+
+## 鼠标事件 {#Pointer Events}
+
+```html
+<TresMesh
+  @click="(ev) => console.log('click', ev)"
+  @pointer-move="(ev) => console.log('click', ev)"
+  @pointer-enter="(ev) => console.log('click', ev)"
+  @pointer-leave="(ev) => console.log('click', ev)"
+/>
+```
+
+## 事件数据 {#Event Data}
+
+事件数据是 `TresEvent` 对象，它包括的属性如下:
+
+```ts
+({
+  object: Object3D, // The mesh object that emitted the event
+  distance: number, // The distance between the camera and the mesh
+  point: Vector3, // The intersection point between the ray and the mesh
+  uv: Vector2, // The uv coordinates of the intersection point
+  face: Face3, // The face of the mesh that was intersected
+  faceIndex: number, // The index of the face that was intersected
+});
+```

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

@@ -0,0 +1,122 @@
+# 实例 {#Instances}
+
+**Tres** 的核心功能是自动生成所有 ThreeJS 元素的目录。这个目录是从 ThreeJS 的源代码中生成的，因此它始终是最新的。
+
+当使用 ThreeJS 的时候，常常需要先引入您想要使用的元素。例如，要使用 `PerspectiveCamera` ，需要先从 `three` 包中引入：
+
+```js
+import { PerspectiveCamera } from "three";
+
+const camera = new PerspectiveCamera(45, width / height, 1, 1000);
+```
+
+使用 **Tres** 时，您不需要导入任何东西，因为 **Tres** 会自动基于您想使用的 ThreeJS 对象生成一个前缀为 **Tres** 且满足驼峰式命名的 Vue 组件。举个例子，`<TresPerspectiveCamera />` 组件对应的就是 `PerspectiveCamera` 对象。
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera />
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+这样您可以只专注 ThreeJS 的[文档](https://threejs.org/docs/)，同时享受 Vue 带来的强大功能。
+
+## 声明对象 {#Declaring objects}
+
+如果您需要传参，您可能会写成下面这样：❌
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera visible :position="new THREE.Vector3(1, 2, 3)" />
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+在 **Tres** 中不需要写成那样，可以采用下面的方式声明：✅
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera visible :position="[1, 2, 3]" />
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+## 参数 {#Arguments}
+
+ThreeJS 中的对象初始化时都能传特定的参数，比如，`PerspectiveCamera` 的构造函数有如下参数：
+
+- `fov` - 相机视锥体的垂直视角
+- `aspect` - 相机视锥体的宽高比
+- `near` - 相机视锥体的近平面
+- `far` - 相机视锥体的远平面
+
+您可以通过 `args` 属性将上面的参数传递给 `TresPerspectiveCamera` 组件:
+
+```vue
+<template>
+  <TresCanvas>
+    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+等价于：
+
+```ts
+const camera = new PerspectiveCamera(45, 1, 0.1, 1000);
+```
+
+## Props {#Props}
+
+每个组件还能够传入对应的 Props。例如， `TresAmbientLight` 带有 `intensity` 属性，像这样传入具体值：
+
+```html
+<TresAmbientLight :intensity="0.5" />
+```
+
+### Set {#Set}
+
+所有具有 `.set()` 方法的基础对象的属性都有一个将值写为数组形式的简写。例如：`TresPerspectiveCamera` 的属性 `position`，它是一个 `Vector3` 对象，可以采用下面的方式传值：
+
+```html
+<TresPerspectiveCamera :position="[1, 2, 3]" />
+```
+
+### 标量 {#Scalar}
+
+还有一种简写方式，对于属性值是 `Vector3` 类型的属性，可以传一个标量来表示使用该标量填充 Vector 的其余部分。
+
+```html
+<TresPerspectiveCamera :position="5" /> ✅
+```
+
+```html
+<TresPerspectiveCamera :position="[5, 5, 5]" /> ✅
+```
+
+### 颜色值 {#Colors}
+
+对于 `color` 属性，可以使用字符串形式的颜色值或者 16 进制的颜色值:
+
+```html
+<TresAmbientLight color="teal" /> ✅
+```
+
+```html
+<TresAmbientLight color="#008080" /> ✅
+```
+
+### 方法 {#Methods}
+
+一些底层属性实际上是方法，`TresPerspectiveCamera` 从 [Object3d](https://threejs.org/docs/#api/en/core/Object3D.lookAt) 继承了一个 `lookAt` 方法，因此您可以像这样将坐标传递给组件：
+
+```html
+<TresPerspectiveCamera :look-at="[1, 2, 3]" />
+```

docs/zh/api/renderer.md

@@ -0,0 +1,61 @@
+# 渲染器 {#Renderer}
+
+渲染器 `Renderer` 组件是 Tres 的主要组件。它创建了 ThreeJS 的 `WebGLRenderer` 并定义了 Tres 场景。
+
+```vue{2,7}
+<template>
+  <TresCanvas shadows :output-encoding="sRGBEncoding">
+    <TresPerspectiveCamera />
+    <TresScene>
+      <!-- Your scene goes here -->
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+## 预设 <Badge warning text="v1.7.0+" /> {#Presets}
+
+Tres 自带一些渲染器 `Renderer` 组件的预设。您可以通过设置 `preset` 属性来使用它们。
+
+### Realistic
+
+预设值 `realistic` 使得设置用于渲染真实 3D 场景的渲染器变得更加容易。
+
+```vue
+<template>
+  <TresCanvas preset="realistic">
+    <!-- Your scene goes here -->
+  </TresCanvas>
+</template>
+```
+
+上面等价于：
+
+```ts
+renderer.shadows: true,
+renderer.physicallyCorrectLights: true,
+renderer.outputEncoding: sRGBEncoding,
+renderer.toneMapping: ACESFilmicToneMapping,
+renderer.toneMappingExposure: 3,
+renderer.shadowMap.enabled: true,
+renderer.shadowMap.type: PCFSoftShadowMap
+```
+
+## Props {#Props}
+
+| Prop                        | Description                                                                                                                                                     | Default            |
+| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| **shadows**                 | Enable shadows in the Renderer                                                                                                                                  | `false`            |
+| **shadowMapType**           | Set the shadow map type                                                                                                                                         | `PCFSoftShadowMap` |
+| **physicallyCorrectLights** | Whether to use physically correct lighting mode. See the [lights / physical example](https://threejs.org/examples/#webgl_lights_physical).                      | `false`            |
+| **outputEncoding**          | Defines the output encoding                                                                                                                                     | `LinearEncoding`   |
+| **toneMapping**             | Defines the tone mapping exposure used by the renderer.                                                                                                         | `NoToneMapping`    |
+| **context**                 | This can be used to attach the renderer to an existing [RenderingContext](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext)               |                    |
+| **powerPreference**         | Provides a hint to the user agent indicating what configuration of GPU is suitable for this WebGL context. Can be "high-performance", "low-power" or "default". | `default`          |
+| **preserveDrawingBuffer**   | Whether to preserve the buffers until manually cleared or overwritten..                                                                                         | `false`            |
+| **clearColor**              | The color the renderer will use to clear the canvas.                                                                                                            | `#000000`          |
+| **windowSize**              | Whether to use the window size as the canvas size or the parent element.                                                                                        | `false`            |
+
+## 默认值 {#Defaults}
+
+Tres 希望留给用户更大的自由度，这也是为什么 Tres 几乎不为渲染器 `Renderer` 组件设置任何默认值。您需要设置要使用的 props。不过有个例外是 `antialias` 属性被默认设置为 true。

docs/zh/cientos/abstractions/environment.md

@@ -0,0 +1,67 @@
+# 环境 <Badge type="warning" text="^1.7.0" />
+
+![Environment](/cientos/environment.png)
+
+`Environment` 组件会自动设置全局 cubemap，影响默认的 `scene.environment` 和可选的 `scene.background`。
+
+底层使用 [useEnvironment](/cientos/abstractions/use-environment) 组合式函数加载 cubemap。
+
+## 用法
+
+```html
+<Environment
+  :files="[
+    '/px.jpg',
+    '/nx.jpg',
+    '/py.jpg',
+    '/ny.jpg',
+    '/pz.jpg',
+    '/nz.jpg'
+]"
+/>
+```
+
+直接使用 `.hdr` 文件:
+
+```html
+<Environment files="/sunset.hdr" />
+```
+
+![Environment](/cientos/envmaps.png)
+
+## 纹理引用
+
+通过 `<Environment />` 组件添加 `ref` 和调用 `getTexture()` 方法能够获取到对应的数据。
+
+```vue{4,6,9,14,17}
+<script setup lang="ts">
+import { Environment } from '@tresjs/cientos'
+
+let envMap = null
+
+const environmentTexture = shallowRef()
+
+watch(environmentTexture, ({ getTexture }) => {
+  envMap = getTexture()
+})
+</script>
+
+<template>
+  <Environment ref="environmentTexture" />
+  <TresMesh>
+    <TresSphereGeometry />
+    <TresMeshStandardMaterial :env-map="envMap" />
+  </TresMesh>
+</template>
+```
+
+## Props
+
+| Prop         | Description                                                          | Default                                                                        |
+| :----------- | :------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `files`      | Array of 6 urls to images, one for each side of the CubeTexture.     | `undefined`                                                                    |
+| `path`       | Path to the environment map files.                                   | `undefined`                                                                    |
+| `encoding`   | Encoding of the environment map.                                     | `sRGBEncoding` for an array of files and `LinearEncoding` for a single texture |
+| `background` | If `true`, the environment map will be used as the scene background. | `false`                                                                        |
+| `blur`       | Blur factor between 0 and 1. (only works with three 0.146 and up)    | 0                                                                              |
+| `preset`     | Preset environment map.                                              | `undefined`                                                                    |

docs/zh/cientos/abstractions/text-3d.md

@@ -0,0 +1,56 @@
+# Text3D <Badge type="warning" text="^1.1.0" />
+
+`<Text3D />` 组件用于渲染 3D 文本。它是 [TextGeometry](https://threejs.org/docs/#api/en/geometries/TextGeometry) 的包装器。
+
+<StackBlitzEmbed projectId="tresjs-text3d-cientos" />
+
+## 用法
+
+`<Text3D />` 组件 需要传入 `font` 属性，该属性值是字体 JSON 文件的 URL。TextGeometry 使用 `typeface`.json 生成字体，您可以在 [此处](http://gero3.github.io/facetype.js/) 生成您自己的字体。
+
+```vue
+<template>
+  <TresCanvas>
+    <TresScene>
+      <Text3D text="TresJS" font="/fonts/FiraCodeRegular.json">
+        <TresMeshNormalMaterial />
+      </Text3D>
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+请注意：由于 `<Text3D />` 本质上是一个 `Mesh` 组件，需要材质数据，因此它的子组件中需要一个 `<TresMeshNormalMaterial />` 组件。几何数据默认会自动创建。你也可以像这样通过插槽或 prop 传递文本:
+
+```vue
+<template>
+  <TresCanvas>
+    <TresScene>
+      <Text3D font="/fonts/FiraCodeRegular.json">
+        TresJS
+        <TresMeshNormalMaterial />
+      </Text3D>
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+## Props [[1]](#1)
+
+| Prop               | Description                                                            | Default |
+| :----------------- | :--------------------------------------------------------------------- | ------- |
+| **font**           | The font data or font name to use for the text.                        |         |
+| **text**           | The text to display.                                                   |         |
+| **size**           | The size of the text.                                                  | 0.5     |
+| **height**         | The height of the text.                                                | 0.2     |
+| **curveSegments**  | The number of curve segments to use when generating the text geometry. | 5       |
+| **bevelEnabled**   | A flag indicating whether beveling should be enabled for the text.     | true    |
+| **bevelThickness** | The thickness of the beveled edge on the text.                         | 0.05    |
+| **bevelSize**      | The size of the beveled edge on the text.                              | 0.02    |
+| **bevelOffset**    | The offset of the beveled edge on the text.                            | 0       |
+| **bevelSegments**  | The number of bevel segments to use when generating the text geometry. | 4       |
+
+## 参考
+
+<a id="1">[1]</a>
+这张表格是由 [ChatGPT](https://chat.openai.com/chat) 根据 Vue 组件 props 生成的。

docs/zh/cientos/abstractions/use-animations.md

@@ -0,0 +1,23 @@
+# useAnimations <Badge type="warning" text="^1.5.0" />
+
+`useAnimation` 组合式函数返回一个 `shallowReactive` 对象，该对象包含所有基于提供的动画的模型操作。 它是 [AnimationMixer](https://threejs.org/docs/#api/en/animation/AnimationMixer) 的包装器。
+
+<StackBlitzEmbed projectId="tresjs-use-animations" />
+
+## 用法
+
+```ts
+import { useAnimations } from "@tresjs/cientos";
+
+const { scene: model, animations } = await useGLTF(
+  "/models/ugly-naked-bunny.gltf"
+);
+
+// Animations [ { name: 'Greeting'}, { name: 'Idle' } ]
+
+const { actions, mixer } = useAnimations(animations, model);
+
+let currentAction = actions.Greeting;
+
+currentAction.play();
+```

docs/zh/cientos/abstractions/use-environment.md

@@ -0,0 +1,44 @@
+# UseEnvironment <Badge type="warning" text="^1.7.0" />
+
+`useEnvironment` 组合式函数自动设置全局 cubemap，影响默认的 `scene.environment` 和可选的 `scene.background`。
+
+它使用 [CubeTextureLoader](https://threejs.org/docs/#api/en/loaders/CubeTextureLoader) 加载 cubemap。
+
+## 用法
+
+```ts
+import { useEnvironment } from "@tresjs/cientos";
+
+const texture = await useEnvironment({
+  files: [
+    "/textures/environmentMaps/0/px.jpg",
+    "/textures/environmentMaps/0/nx.jpg",
+    "/textures/environmentMaps/0/py.jpg",
+    "/textures/environmentMaps/0/ny.jpg",
+    "/textures/environmentMaps/0/pz.jpg",
+    "/textures/environmentMaps/0/nz.jpg",
+  ],
+  path: "",
+  encoding: sRGBEncoding,
+});
+```
+
+场景中添加 `texture`
+
+```html{3}
+<TresMesh>
+  <TresSphereGeometry />
+  <TresMeshStandardMaterial :map="texture" />
+</TresMesh>
+```
+
+## 选项
+
+| Name           | Type       | Default                                                                        | Description                                                       |
+| :------------- | ---------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
+| **files**      | `Array`    | `undefined`                                                                    | Array of 6 urls to images, one for each side of the CubeTexture.  |
+| **path**       | `boolean`  | `false`                                                                        | Path to the environment map files.                                |
+| **encoding**   | `Encoding` | `sRGBEncoding` for an array of files and `LinearEncoding` for a single texture | Encoding of the environment map.                                  |
+| **background** | `boolean`  | `false`                                                                        | If `true` the texture will be used as the scene background.       |
+| **blur**       | `number`   | `0`                                                                            | Blur factor between 0 and 1. (only works with three 0.146 and up) |
+| **preset**     | `string`   | `undefined`                                                                    | Preset environment map.                                           |

docs/zh/cientos/controls/orbit-controls.md

@@ -0,0 +1,29 @@
+# OrbitControls
+
+[OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) 是一个相机控制器，它允许您围绕一个目标旋转。这是探索场景的好方法。
+
+然而，它不在 ThreeJS 的核心包中。需要从 `three/examples/jsm/controls/OrbitControls` 导入。
+
+`cientos` 包提供了名为 `<OrbitControls />` 的组件。它实际上是 [`three-stdlib`](https://github.com/pmndrs/three-stdlib) 模块中 `OrbitControls` 包装器。 ✨
+
+The nicest part? You don't need to extend the catalog or pass any arguments.  
+It just works. 💯
+
+```vue{3}
+<template>
+  <TresCanvas shadows alpha>
+    <OrbitControls />
+    <TresScene> ... </TresScene>
+  </TresCanvas>
+</template>
+```
+
+## Props
+
+| Prop              | Description                                                                                                      | Default     |
+| :---------------- | :--------------------------------------------------------------------------------------------------------------- | ----------- |
+| **makeDefault**   | If `true`, the controls will be set as the default controls for the scene.                                       | `false`     |
+| **camera**        | The camera to control.                                                                                           | `undefined` |
+| **domElement**    | The dom element to listen to.                                                                                    | `undefined` |
+| **target**        | The target to orbit around.                                                                                      | `undefined` |
+| **enableDamping** | If `true`, the controls will use damping (inertia), which can be used to give a sense of weight to the controls. | `false`     |

docs/zh/cientos/controls/transform-controls.md

@@ -0,0 +1,101 @@
+# 变换控制器
+
+[变换控制器](https://threejs.org/docs/#examples/en/controls/TransformControls) 是一组三个小工具，可以用来在场景中平移、旋转和缩放对象。它采用了类似于 Blender 等 DCC 工具的交互模型
+
+<StackBlitzEmbed projectId="tresjs-transform-controls" />
+
+## 用法
+
+要使用变换控制器，只需将 `TransformControls` 添加到场景中。您还可以将想要控制的实例对象的 `templateRef` 作为 prop 传递给它。
+
+```vue{2,6,8}
+<script setup>
+const boxRef = shallowRef()
+</script>
+<template>
+  <TresCanvas>
+    <OrbitControls make-default />
+    <TresScene>
+        <TransformControls :object="boxRef" />
+        <TresMesh ref="boxRef" :position="[0, 4, 0]" cast-shadow>
+            <TresBoxGeometry :args="[1.5, 1.5, 1.5]" />
+            <TresMeshToonMaterial color="#4F4F4F" />
+        </TresMesh>
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+::: warning
+如果您使用其他控制器 ([OrbitControls](/cientos/controls/orbit-controls))，在拖动时它们会相互干扰。为了避免这种情况，您可以将 **OrbitControls** 的 `makeDefault` 属性设置为 `true`。
+:::
+
+## 模式
+
+变换控制器可以在三种不同的模式下使用:
+
+### 平移
+
+![Translate](/cientos/transform-controls-translate.png)
+
+默认模式可以在场景中移动物体。
+
+```html
+<TransformControls mode="translate" :object="sphereRef" />
+```
+
+### 旋转
+
+![Rotate](/cientos/transform-controls-rotate.png)
+
+旋转模式可以在场景中旋转物体。
+
+```html
+<TransformControls mode="rotate" :object="boxRef" />
+```
+
+### 缩放
+
+![Scale](/cientos/transform-controls-scale.png)
+
+缩放模式可以在场景中缩放物体。
+
+```html
+<TransformControls mode="scale" :object="sphereRef" />
+```
+
+## Props
+
+| Prop                | Description                                                                                   | Default     |
+| :------------------ | :-------------------------------------------------------------------------------------------- | ----------- |
+|  **object**         | The instance [Object3D](https://threejs.org/docs/index.html#api/en/core/Object3D) to control. | `null`      |
+| **mode**            | The mode of the controls. Can be `translate`, `rotate` or `scale`.                            | `translate` |
+| **enabled**         | If `true`, the controls will be enabled.                                                      | `true`      |
+| **axis**            | The axis to use for the controls. Can be `X`, `Y`, `Z`, `XY`, `YZ`, `XZ`, `XYZ`.              | `XYZ`       |
+| **space**           | The space to use for the controls. Can be `local` or `world`.                                 | `local`     |
+| **size**            | The size of the controls.                                                                     | `1`         |
+| **translationSnap** | The distance to snap to when translating. (World units)                                       | `null`      |
+| **rotationSnap**    | The angle to snap to when rotating. (Radians)                                                 | `null`      |
+| **scaleSnap**       | The scale to snap to when scaling.                                                            | `null`      |
+| **showX**           | If `true`, the X-axis helper will be shown.                                                   | `true`      |
+| **showY**           | If `true`, the Y-axis helper will be shown.                                                   | `true`      |
+| **showZ**           | If `true`, the Z-axis helper will be shown.                                                   | `true`      |
+
+## Events
+
+| Event            | Description                                                    |
+| :--------------- | :------------------------------------------------------------- |
+| **dragging**     | Fired when the user starts or stops dragging the controls.     |
+| **change**       | Fired when the user changes the controls.                      |
+| **mouseDown**    | Fired when the user clicks on the controls.                    |
+| **mouseUp**      | Fired when the user releases the mouse button on the controls. |
+| **objectChange** | Fired when the user changes the object.                        |
+
+<style scoped>
+img {
+    aspect-ratio: 16/9;
+    object-fit: cover;
+    object-position: top;
+    border-radius: 8px;
+}
+</style>

docs/zh/cientos/index.md

@@ -0,0 +1,44 @@
+<script setup>
+  import cientos from '../node_modules/@tresjs/cientos/package.json'
+</script>
+
+# Cientos <Badge :text="`v${cientos.version}`" type="warning" vertical="middle" />
+
+![Cientos banner](/cientos-banner.png)
+
+> Cientos (西班牙语中的 "hundreds", 发音 `/θjentos/`) 提供了非 [core](/guide/index.md) 包的一些实用工具和组件。包名使用了西班牙语中的单词，意思是“乘以 100”，用来表示这个包具有容纳惊人抽象概念的潜力。
+
+`cientos` 底层使用 [`three-stdlib`](https://github.com/pmndrs/three-stdlib) 模块代替 `three/examples/jsm` 模块。这样您不需要使用 [useCatalogue](/api/composables#useCatalogue) 提供的 `extend` 方法来扩展组件。`cientos` 会为您处理这些琐事。
+
+成功. 💯
+
+::: info
+当使用核心库开发的时候，并不一定需要 `cientos` 包。 `cientos` 只是提高您的开发体验，特别是开发复杂场景的时候。
+:::
+
+## 安装
+
+```bash
+npm install @tresjs/cientos -D
+```
+
+## 基础用法
+
+```ts
+import { OrbitControls } from "@tresjs/cientos";
+```
+
+场景中使用 `OrbitControls` 组件。
+
+```html
+<template>
+  <TresCanvas shadows alpha>
+    <OrbitControls />
+    <TresScene> ... </TresScene>
+  </TresCanvas>
+</template>
+```
+
+::: warning
+注意 `OrbitControls` 组件不带有 `Tres` 前缀。
+:::

docs/zh/cientos/loaders/fbx-model.md

@@ -0,0 +1,27 @@
+# Using `FBXModel`
+
+`FBXModel` 是 [`useFBX`](./use-fbx.md) 组合式函数对应的组件，它接受与 props 相同的选项。
+
+```vue{2,10}
+<script setup lang="ts">
+import { OrbitControls, FBXModel } from '@tresjs/cientos'
+</script>
+<template>
+  <Suspense>
+    <TresCanvas clear-color="#82DBC5" shadows alpha>
+      <TresPerspectiveCamera :position="[11, 11, 11]" />
+      <OrbitControls />
+      <TresScene>
+        <FBXModel path="/models/AkuAku.fbx" />
+        <TresDirectionalLight :position="[-4, 8, 4]" :intensity="1.5" cast-shadow />
+      </TresScene>
+    </TresCanvas>
+  </Suspense>
+</template>
+```
+
+## Props
+
+| Prop   | Description             | Default     |
+| :----- | :---------------------- | ----------- |
+| `path` | Path to the model file. | `undefined` |

docs/zh/cientos/loaders/gltf-model.md

@@ -0,0 +1,52 @@
+# 使用 `GLTFModel`
+
+`GLTFModel` 是 [`useGLTF`](./use-gltf.md) 组合式函数对应的组件，它接受与 props 相同的选项。
+
+```vue{2,10}
+<script setup lang="ts">
+import { OrbitControls, GLTFModel } from '@tresjs/cientos'
+</script>
+<template>
+  <Suspense>
+    <TresCanvas clear-color="#82DBC5" shadows alpha>
+      <TresPerspectiveCamera :position="[11, 11, 11]" />
+      <OrbitControls />
+      <TresScene>
+        <GLTFModel path="/models/AkuAku.gltf" draco />
+        <TresDirectionalLight :position="[-4, 8, 4]" :intensity="1.5" cast-shadow />
+      </TresScene>
+    </TresCanvas>
+  </Suspense>
+</template>
+```
+
+## 模型引用
+
+你可以通过将 `ref` 传递给 `model` prop，然后使用 `getModel()` 方法获取模型引用。
+
+```vue{3,6}
+<script setup lang="ts">
+import { OrbitControls, GLTFModel } from '@tresjs/cientos'
+
+const modelRef = shallowRef<THREE.Object3D>()
+
+watch(modelRef, ({getModel}) => {
+  const model = getModel()
+
+  model.traverse((child) => {
+    if (child.isMesh) {
+      child.castShadow = true
+      child.receiveShadow = true
+    }
+  })
+})
+</script>
+```
+
+## Props
+
+| Prop          | Description                                                                                                           | Default     |
+| :------------ | :-------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `path`        | Path to the model file.                                                                                               | `undefined` |
+| `draco`       | Enable [Draco compression](https://threejs.org/docs/index.html?q=drac#examples/en/loaders/DRACOLoader) for the model. | `false`     |
+| `decoderPath` | Path to a local Draco decoder.                                                                                        | `undefined` |

docs/zh/cientos/loaders/use-fbx.md

@@ -0,0 +1,23 @@
+# useFBX
+
+一个组合式函数，让您可以轻松地将 glTF 模型加载到 **TresJS** 场景中。
+
+## 用法
+
+```ts
+import { useFBX } from "@tresjs/cientos";
+
+const model = await useFBX("/models/AkuAku.fbx");
+```
+
+Then is as straightforward as adding the scene to your scene:
+
+```html{4}
+<Suspense>
+  <TresCanvas shadows alpha>
+    <TresScene>
+      <TresMesh v-bind="scene" />
+    </TresScene>
+  </TresCanvas>
+</Suspense>
+```

docs/zh/cientos/loaders/use-gltf.md

@@ -0,0 +1,38 @@
+# useGLTF
+
+一个组合式函数，让您可以轻松地将 glTF 模型加载到 **TresJS** 场景中。
+
+## 用法
+
+```ts
+import { useGLTF } from "@tresjs/cientos";
+
+const { scene } = await useGLTF("/models/AkuAku.gltf");
+```
+
+将数据直接添加到场景中:
+
+```html{4}
+<Suspense>
+  <TresCanvas shadows alpha>
+    <TresScene>
+      <TresMesh v-bind="scene" />
+    </TresScene>
+  </TresCanvas>
+</Suspense>
+```
+
+使用 `useGLTF` 的好处是你可以传递 `draco` 属性以启用对模型的 [Draco 压缩](https://threejs.org/docs/index.html?q=drac#examples/en/loaders/DRACOLoader)。这将减小模型的大小并提高性能。
+
+```ts
+import { useGLTF } from "@tresjs/cientos";
+
+const { scene } = await useGLTF("/models/AkuAku.gltf", { draco: true });
+```
+
+## Options
+
+| Name            | Type      | Default     | Description                          |
+| :-------------- | --------- | ----------- | ------------------------------------ |
+| **draco**       | `boolean` | `false`     | Whether to enable Draco compression. |
+| **decoderPath** | `string`  | `undefined` | Local path to the Draco decoder.     |

docs/zh/cientos/misc/use-tweakpane.md

@@ -0,0 +1,40 @@
+# useTweakPane
+
+[TweakPane](https://cocopon.github.io/tweakpane/) 是一个用来创建动态修改属性值交互的 Javascript 库。它是一个很好的工具，用于微调参数和监控你的 three.js 应用程序上的值变化。
+
+**TresJS** 提供 `useTweakPane` 组合式函数用于创建 Tweakpane 面板。默认情况下，面板会创建在画布的右上角，并包含一个 FPS 图形监视器，用于监控你的场景的性能。
+
+::: info
+您可以通过传递 selector 选项给 useTweakPane 函数来改变面板的容器。
+:::
+
+## 基础用法
+
+```ts
+import { useTweakPane } from "@tresjs/cientos";
+
+const { pane } = useTweakPane();
+
+const experiment = reactive({
+  clearColor: "#000000",
+  alpha: true,
+  shadow: true,
+});
+
+pane.addInput(experiment, "clearColor", {
+  label: "Clear Color",
+  colorMode: "hex",
+});
+
+pane.addInput(experiment, "alpha");
+```
+
+最终效果:
+
+![](/use-tweakpane.png)
+
+## 选项
+
+| Name         | Type     | Default     | Description                                                    |
+| :----------- | -------- | ----------- | -------------------------------------------------------------- |
+| **selector** | `string` | `undefined` | The selector of the container where the panel will be created. |

docs/zh/cientos/shapes/box.md

@@ -0,0 +1,29 @@
+# 立方体 <Badge type="warning" text="^1.6.0" />
+
+![](/cientos/box.png)
+
+`cientos` 包提供了一个 `<Box />` 组件，作为 `BoxGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象。
+
+```typescript
+args: [
+  width: number,
+  height: number,
+  depth: number,
+  widthSegments: number,
+  heightSegments: number,
+  depthSegments: number
+]
+```
+
+参考: [BoxGeometry](https://threejs.org/docs/?q=box#api/en/geometries/BoxGeometry)
+
+## 用法
+
+```html
+<Box :args="[1, 1, 1]" color="orange" />
+
+// Box with a custom material transformations
+<Box ref="boxRef" :args="[1, 1, 1]" :position="[0, 4, 0]">
+  <TresMeshToonMaterial color="orange" />
+</Box>
+```

docs/zh/cientos/shapes/circle.md

@@ -0,0 +1,22 @@
+# 圆形 <Badge type="warning" text="^1.6.0" />
+
+![](/cientos/circle.png)
+
+`cientos` 包提供了一个 `<Circle />` 组件，作为 `CircleGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象。
+
+```typescript
+args: [radius: number, segments: number, thetaStart: number, thetaLength: number]
+```
+
+参考: [CircleGeometry](https://threejs.org/docs/?q=circle#api/en/geometries/CircleGeometry)
+
+## 用法
+
+```html
+<Circle :args="[1, 32]" color="lightsalmon" />
+
+// Circle with a custom material transformations
+<Circle ref="circleRef" :args="[1, 32]" :position="[0, 0, 0]">
+  <TresMeshToonMaterial color="lightsalmon" />
+</Circle>
+```

docs/zh/cientos/shapes/cone.md

@@ -0,0 +1,30 @@
+# 圆锥 <Badge type="warning" text="^1.6.0" />
+
+![](/cientos/cone.png)
+
+`cientos` 包提供了一个 `<Cone />` 组件，作为 `ConeGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象。
+
+```typescript
+args: [
+  radius: number,
+  height: number,
+  radialSegments: number,
+  heightSegments: number,
+  openEnded: boolean,
+  thetaStart: number,
+  thetaLength: number
+]
+```
+
+参考: [ConeGeometry](https://threejs.org/docs/?q=cone#api/en/geometries/ConeGeometry)
+
+## 用法
+
+```html
+<Cone :args="[1, 1, 8]" color="orange" />
+
+// Cone with a custom material transformations
+<Cone ref="coneRef" :args="[1, 1, 8]" :position="[0, 4, 0]">
+  <TresMeshToonMaterial color="orange" />
+</Cone>
+```

docs/zh/cientos/shapes/dodecahedron.md

@@ -0,0 +1,22 @@
+# 十二面几何体 <Badge type="warning" text="^1.6.0" />
+
+![](/cientos/dodecahedron.png)
+
+`cientos` 包提供了一个 `<Dodecahedron />` 组件，作为 `DodecahedronGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象。
+
+```typescript
+args: [radius: number, detail: number]
+```
+
+参考: [DodecahedronGeometry](https://threejs.org/docs/?q=dode#api/en/geometries/DodecahedronGeometry)
+
+## 用法
+
+```html
+<Dodecahedron :args="[1, 0]" color="deeppink" />
+
+// Dodecahedron with a custom material transformations
+<Dodecahedron ref="dodecahedronRef" :args="[1, 0]" :position="[2, 4, 0]">
+  <TresMeshToonMaterial color="deeppink" />
+</Dodecahedron>
+```

docs/zh/cientos/shapes/icosahedron.md

@@ -0,0 +1,22 @@
+# 二十面几何体 <Badge type="warning" text="^1.6.0" />
+
+![](/cientos/icosahedron.png)
+
+`cientos` 包提供了一个 `<Icosahedron />` 组件，作为 `IcosahedronGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象。
+
+```typescript
+args: [radius: number, detail: number]
+```
+
+参考: [IcosahedronGeometry](https://threejs.org/docs/?q=ico#api/en/geometries/IcosahedronGeometry)
+
+## 用法
+
+```html
+<Icosahedron :args="[1, 0]" color="red" />
+
+// Icosahedron with a custom material transformations
+<Icosahedron ref="icosahedronRef" :args="[1, 0]" :position="[2, 4, 0]">
+  <TresMeshToonMaterial color="red" />
+</Icosahedron>
+```

docs/zh/cientos/shapes/octahedron.md

@@ -0,0 +1,22 @@
+# 八面几何体 <Badge type="warning" text="^1.6.0" />
+
+![](/cientos/octahedron.png)
+
+`cientos` 包提供了一个 `<Octahedron />` 组件，作为 `OctahedronGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象。
+
+```typescript
+args: [radius: number, detail: number]
+```
+
+参考: [OctahedronGeometry](https://threejs.org/docs/?q=octa#api/en/geometries/OctahedronGeometry)
+
+## 用法
+
+```html
+<Octahedron :args="[1, 0]" color="red" />
+
+// Octahedron with a custom material transformations
+<Octahedron ref="icosahedronRef" :args="[1, 0]" :position="[2, 4, 0]">
+  <TresMeshToonMaterial color="red" />
+</Octahedron>
+```

docs/zh/cientos/shapes/plane.md

@@ -0,0 +1,26 @@
+# 平面 <Badge type="warning" text="^1.5.0" />
+
+![](/cientos/plane.png)
+
+`cientos` 包提供了一个 `<Plane />` 组件，作为 `PlaneGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象。
+
+```typescript
+args: [width: number, height: number, widthSegments: number, heightSegments: number]
+```
+
+参考: [PlaneGeometry](https://threejs.org/docs/?q=plane#api/en/geometries/PlaneGeometry)
+
+::: info
+A convenient default rotation is applied to the _x-axis_ of the plane (`-Math.PI / 2`), so that it is facing up (along the Y axis).
+:::
+
+## 用法
+
+```html
+<Plane :args="[1, 1]" color="teal" />
+
+// Plane with a custom material transformations
+<Plane ref="planeRef" :args="[8, 8]" :position="[0, 4, 0]">
+  <TresMeshToonMaterial color="teal" />
+</Plane>
+```

docs/zh/cientos/shapes/ring.md

@@ -0,0 +1,29 @@
+# 圆环 <Badge type="warning" text="^1.6.0" />
+
+![](/cientos/ring.png)
+
+`cientos` 包提供了一个 `<Ring />` 组件，作为 `RingGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象
+
+```typescript
+args: [
+  innerRadius: number,
+  outerRadius: number,
+  thetaSegments: number,
+  phiSegments: number,
+  thetaStart: number,
+  thetaLength: number
+]
+```
+
+参考: [RingGeometry](https://threejs.org/docs/?q=ring#api/en/geometries/RingGeometry)
+
+## 用法
+
+```html
+<Ring :args="[0.5, 1, 32]" color="purple" />
+
+// Ring with a custom material transformations
+<Ring ref="ringRef" :args="[0.5, 1, 32]" :position="[2, 4, 0]">
+  <TresMeshToonMaterial color="purple" />
+</Ring>
+```

docs/zh/cientos/shapes/sphere.md

@@ -0,0 +1,30 @@
+# 球体 <Badge type="warning" text="^1.6.0" />
+
+![](/cientos/sphere.png)
+
+`cientos` 包提供了一个 `<Sphere />` 组件，作为 `SphereGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象
+
+```typescript
+args: [
+  radius: number,
+  widthSegments: number,
+  heightSegments: number,
+  phiStart: number,
+  phiLength: number,
+  thetaStart: number,
+  thetaLength: number
+]
+```
+
+参考: [SphereGeometry](https://threejs.org/docs/?q=sphere#api/en/geometries/SphereGeometry)
+
+## 用法
+
+```html
+<Sphere :args="[1, 1, 1]" color="pink" />
+
+// Sphere with a custom material transformations
+<Sphere ref="planeRef" :args="[1, 1, 1]" :position="[2, 4, 0]">
+  <TresMeshToonMaterial color="pink" />
+</Sphere>
+```

docs/zh/cientos/shapes/tetrahedron.md

@@ -0,0 +1,22 @@
+# 四面几何体 <Badge type="warning" text="^1.6.0" />
+
+![](/cientos/tetrahedron.png)
+
+`cientos` 包提供了一个 `<Tetrahedron />` 组件，作为 `TetrahedronGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象
+
+```typescript
+args: [radius: number, detail: number]
+```
+
+参考: [TetrahedronGeometry](https://threejs.org/docs/?q=tetr#api/en/geometries/TetrahedronGeometry)
+
+## 用法
+
+```html
+<Tetrahedron :args="[1, 0]" color="yellow" />
+
+// Tetrahedron with a custom material transformations
+<Tetrahedron ref="tetrahedronRef" :args="[1, 0]" :position="[2, 4, 0]">
+  <TresMeshToonMaterial color="yellow" />
+</Tetrahedron>
+```

docs/zh/cientos/shapes/torus-knot.md

@@ -0,0 +1,29 @@
+# 圆环缓冲扭结几何体 <Badge type="warning" text="^1.6.0" />
+
+![](/cientos/torus-knot.png)
+
+`cientos` 包提供了一个 `<TorusKnot />` 组件，作为 `TorusKnotGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象
+
+```typescript
+args: [
+  radius: number,
+  tube: number,
+  tubularSegments: number,
+  radialSegments: number,
+  p: number,
+  q: number
+]
+```
+
+参考: [TorusKnotGeometry](https://threejs.org/docs/?q=torus#api/en/geometries/TorusKnotGeometry)
+
+## 用法
+
+```html
+<TorusKnot :args="[0.6, 0.2, 64, 8]" color="lime" />
+
+// TorusKnot with a custom material transformations
+<TorusKnot ref="torusKnotRef" :args="[0.6, 0.2, 64, 8]" :position="[-2, 6, 2]">
+  <TresMeshToonMaterial color="lime" />
+</TorusKnot>
+```

docs/zh/cientos/shapes/torus.md

@@ -0,0 +1,28 @@
+# 圆环 <Badge type="warning" text="^1.6.0" />
+
+![](/cientos/torus.png)
+
+`cientos` 包提供了一个 `<Torus />` 组件，作为 `TorusGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象
+
+```typescript
+args: [
+  radius: number,
+  tube: number,
+  radialSegments: number,
+  tubularSegments: number,
+  arc: number
+]
+```
+
+参考: [TorusGeometry](https://threejs.org/docs/?q=torus#api/en/geometries/TorusGeometry)
+
+## 用法
+
+```html
+<Torus :args="[2, 0.4, 42, 100]" color="cyan" />
+
+// Torus with a custom material transformations
+<Torus ref="torusRef" :args="[0.75, 0.4, 16, 80]" :position="[-2, 6, 0]">
+  <TresMeshToonMaterial color="cyan" />
+</Torus>
+```

docs/zh/cientos/shapes/tube.md

@@ -0,0 +1,50 @@
+# 管道 <Badge type="warning" text="^1.6.0" />
+
+![](/cientos/tube.png)
+
+`cientos` 包提供了一个 `<Tube />` 组件，作为 `TubeGeometry` 和 `MeshBasicMaterial` 的快捷方式，同时会创建 `Mesh` 对象
+
+```typescript
+<script>
+export default {
+  setup() {
+    const tubePath = ref(new CubicBezierCurve3(
+          new Vector3(-1, 0, 0),
+          new Vector3(-0.5, -1, 0),
+          new Vector3(0.5, 1, 0),
+          new Vector3(1, 0, 0),
+          ));
+
+    return {
+      tubePath
+    }
+  },
+}
+</script>
+```
+
+```typescript
+type CurveType = QuadraticBezierCurve3 | CubicBezierCurve3 | CatmullRomCurve3 | LineCurve3
+
+args: [
+  path: CurveType,
+  tubularSegments: number,
+  radius: number,
+  radialSegments: number,
+  closed: boolean
+]
+```
+
+参考: [TubeGeometry](https://threejs.org/docs/?q=tube#api/en/geometries/TubeGeometry)
+
+## 用法
+
+```html
+// TubeGeometry needs a curve path to be construct
+<Tube :args="[tubePath, 20, 0.2, 8, false]" color="lightblue" />
+
+// Tube with a custom material transformations
+<Tube ref="tubeRef" :args="[tubePath, 20, 0.2, 8, false]" :position="[0, 4, 0]">
+  <TresMeshToonMaterial color="lightblue" />
+</Tube>
+```

docs/zh/examples/basic-animations.md

@@ -0,0 +1,58 @@
+# 基础动画
+
+This guide will help you get started with basic animations in TresJS.
+
+本节展示 **TresJS** 的基础动画。
+
+我们会创建一个简单的场景，场景中有一个绕着 Y 和 Z 轴不停旋转的立方体。
+
+<StackBlitzEmbed projectId="tresjs-basic-animations" />
+
+## useRenderLoop 函数
+
+TresJS 动画的核心是 `useRenderLoop` 组合式函数。它允许您注册一个回答函数，并且在浏览器刷新的每一帧中调用该回调函数。
+
+要查看详细的说明，请参考 [useRenderLoop](/api/composables#userenderloop) 文档。
+
+```ts
+const { onLoop, resume } = useRenderLoop();
+
+resume();
+onLoop(({ _delta, elapsed }) => {
+  // I will run at every frame ~ 60FPS (depending of your monitor)
+});
+```
+
+## 立方体 Ref
+
+想要给立方体添加动画，首先需要获取立方体的实例。通过在 `TresMesh` 组件上添加 [模版引用](https://vuejs.org/guide/essentials/template-refs.html)，获取对应的立方体实例。
+
+出于对性能的考虑，使用 [Shallow Ref](https://v3.vuejs.org/guide/reactivity-fundamentals.html#shallow-reactivity) 代替 Ref 存储实例。详见 [这里](../advanced/caveats.md#reactivity)。
+
+```vue
+<script setup lang="ts">
+const boxRef: ShallowRef<TresInstance | null> = shallowRef(null);
+</script>
+
+<template>
+  <TresMesh ref="boxRef" :scale="1" cast-shadow>
+    <TresBoxGeometry :args="[1, 1, 1]" />
+    <TresMeshStandardMaterial v-bind="pbrTexture" />
+  </TresMesh>
+</template>
+```
+
+## 给立方体添加动画
+
+现在已经获取到立方体的实例，接着使用 `onLoop` 回调函数来让立方体旋转起来。
+
+```ts
+onLoop(({ _delta, elapsed }) => {
+  if (boxRef.value) {
+    boxRef.value.rotation.y += 0.01;
+    boxRef.value.rotation.z = elapsed * 0.2;
+  }
+});
+```
+
+也可以使用 [THREE clock](https://threejs.org/docs/?q=clock#api/en/core/Clock) 内部的 `delta` 和 `elapsed` 为立方体创建动画。

docs/zh/examples/groups.md

@@ -0,0 +1,32 @@
+# 分组 <Badge type="warning" text="^1.5.0" /> {#Group}
+
+`<TresGroup>` 是 [THREE.Group](https://threejs.org/docs/#api/en/objects/Group) 的一个实例。**THREE.Group** 和 [THREE.Object3D](https://threejs.org/docs/#api/en/objects/Object3D) 几乎相同，但它允许**将场景中的多个对象组合在一起**，以便将它们作为一个整体进行操作（变换、旋转等）
+
+<StackBlitzEmbed projectId="tresjs-groups" />
+
+## Usage
+
+```vue{12,21}
+<script setup lang="ts">
+const groupRef = ref()
+const { onLoop } = useRenderLoop()
+
+onLoop(() => {
+  if (groupRef.value) {
+    groupRef.value.rotation.y += 0.01
+  }
+})
+</script>
+<template>
+  <TresGroup ref="groupRef" :position="[2,0,0]">
+    <TresMesh>
+      <TresBoxGeometry />
+      <TresMeshBasicMaterial color="red" />
+    </TresMesh>
+    <TresMesh>
+      <TresSphereGeometry />
+      <TresMeshBasicMaterial color="blue" />
+    </TresMesh>
+  </TresGroup>
+</template>
+```

docs/zh/examples/load-models.md

@@ -0,0 +1,124 @@
+# 加载模型 {#Load Models}
+
+> 本节中使用的所有模型均来自 [Alvaro Saburido](https://sketchfab.com/3d-models/aku-aku-7dfcb6edf10b4098bbb965c56fd3055c)。
+
+3D 模型有丰富的文件格式，每种格式都有不同的目的、各种功能和不同的复杂性。
+
+本节我们将重点介绍如何加载网络上最常见的 3D 模型格式 —— glTF（图形语言传输格式）。
+
+<StackBlitzEmbed projectId="tresjs-gltf-load-model" />
+
+下面是几种加载模型的方法：
+
+## 使用 `useLoader`
+
+`useLoader` 组合式函数接收任意类型的 Three.js 的加载器和资源的路径。它返回一个带有已加载资源的 Promise。
+
+关于 `useLoader` 的使用细节，请查看 [useLoader](/api/composables#use-loader) 文档。
+
+```ts
+import { useLoader } from "@tresjs/core";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader";
+
+const { scene } = await useLoader(GLTFLoader, "/models/AkuAku.gltf");
+```
+
+将模型数据传给 `TresMesh` 组件:
+
+```html{4}
+<Suspense>
+  <TresCanvas>
+    <TresScene>
+      <TresMesh v-bind="scene" />
+    </TresScene>
+  </TresCanvas>
+</Suspense>
+```
+
+注意在上面的示例中，我们使用了 `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 } = await useGLTF("/models/AkuAku.gltf");
+```
+
+使用 `useGLTF` 的好处是你可以传递 `draco` 属性以启用对模型的 [Draco 压缩](https://threejs.org/docs/index.html?q=drac#examples/en/loaders/DRACOLoader)。这将减小模型的大小并提高性能。
+
+```ts
+import { useGLTF } from "@tresjs/cientos";
+
+const { scene } = await useGLTF("/models/AkuAku.gltf", { draco: true });
+```
+
+## 使用 `GLTFModel`
+
+`GLTFModel` 组件是 [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) 包中 `useGLTF` 的包装器。
+
+```vue{2,10}
+<script setup lang="ts">
+import { OrbitControls, GLTFModel } from '@tresjs/cientos'
+</script>
+<template>
+  <Suspense>
+    <TresCanvas clear-color="#82DBC5" shadows alpha>
+      <TresPerspectiveCamera :position="[11, 11, 11]" />
+      <OrbitControls />
+      <TresScene>
+        <GLTFModel path="/models/AkuAku.gltf" draco />
+        <TresDirectionalLight :position="[-4, 8, 4]" :intensity="1.5" cast-shadow />
+      </TresScene>
+    </TresCanvas>
+  </Suspense>
+</template>
+```
+
+这种特定的方法更加简单直接，不过您只有很少的模型控制权。
+
+## useFBX
+
+[@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) 包提供了 `useFBX`。
+
+```ts
+import { useFBX } from "@tresjs/cientos";
+
+const model = await useFBX("/models/AkuAku.fbx");
+```
+
+直接添加到场景中：
+
+```html{4}
+<Suspense>
+  <TresCanvas shadows alpha>
+    <TresScene>
+      <TresMesh v-bind="scene" />
+    </TresScene>
+  </TresCanvas>
+</Suspense>
+```
+
+## FBXModel
+
+`FBXModel` 组件是 [@tresjs/cientos](https://github.com/Tresjs/tres/tree/main/packages/cientos) 包中 `useFBX` 的包装器。 用法与 `GLTFModel` 类似:
+
+```vue{2,10}
+<script setup lang="ts">
+import { OrbitControls, FBXModel } from '@tresjs/cientos'
+</script>
+<template>
+  <Suspense>
+    <TresCanvas clear-color="#82DBC5" shadows alpha>
+      <TresPerspectiveCamera :position="[11, 11, 11]" />
+      <OrbitControls />
+      <TresScene>
+        <FBXModel path="/models/AkuAku.fbx" />
+        <TresDirectionalLight :position="[-4, 8, 4]" :intensity="1.5" cast-shadow />
+      </TresScene>
+    </TresCanvas>
+  </Suspense>
+</template>
+```

docs/zh/examples/load-textures.md

@@ -0,0 +1,78 @@
+# 加载纹理
+
+> 本节中使用的所有纹理均来自 [ambientcg](https://ambientcg.com/)。
+
+三维纹理是包含多层数据的图像，使它们能够表示体积或模拟三维结构。这些纹理通常用于 3D 图形和视觉效果中，以增强场景和对象的逼真度和复杂性。
+
+<StackBlitzEmbed projectId="tresjs-load-textures" />
+
+下面展示了 TresJS 中两种加载 3D 纹理的方式：
+
+## 使用 `useLoader`
+
+`useLoader` 组合式函数接收任意类型的 Three.js 的加载器和资料的路径。它返回一个带有已加载资源的 Promise。
+
+关于 `useLoader` 的使用细节，请查看 [useLoader](/api/composables#use-loader) 文档。
+
+```ts
+import { useLoader } from "@tresjs/core";
+import { TextureLoader } from "three/examples/jsm/loaders/TextureLoader";
+
+const texture = useLoader(TextureLoader, "/Rock035_2K_Color.jpg");
+```
+
+将纹理传入材质中：
+
+```html
+<Suspense>
+  <TresCanvas>
+    <TresScene>
+      <TresMesh>
+        <TresSphereGeometry :args="[1,32,32]" />
+        <TresMeshStandardMaterial :map="texture" />
+      </TresMesh>
+    </TresScene>
+  </TresCanvas>
+</Suspense>
+```
+
+注意在上面的示例中，我们使用了 `Suspense` 组件来包裹 `TresCanvas` 组件。这是因为 `useLoader` 返回一个 Promise，我们需要等待它完成资源加载后再渲染场景。
+
+## 使用 `useTexture`
+
+这里还有一个更加简便的方式，使用 `useTexture` 加载纹理。它接受一个 URL 数组或一个包含纹理路径映射的对象。
+
+关于 `useTexture` 的更多信息，请查看 [useTexture](/api/composables#use-texture) 文档。
+
+```ts
+import { useTexture } from "@tresjs/core";
+
+const pbrTexture = await useTexture({
+  map: "/textures/black-rock/Rock035_2K_Displacement.jpg",
+  displacementMap: "/textures/black-rock/Rock035_2K_Displacement.jpg",
+  roughnessMap: "/textures/black-rock/Rock035_2K_Roughness.jpg",
+  normalMap: "/textures/black-rock/Rock035_2K_NormalDX.jpg",
+  ambientOcclusion: "/textures/black-rock/Rock035_2K_AmbientOcclusion.jpg",
+});
+```
+
+与前面的例子类似，我们可以通过 props 将纹理信息传递给材质:
+
+```html
+<Suspense>
+  <TresCanvas>
+    <TresScene>
+      <TresMesh>
+        <TresSphereGeometry :args="[1,32,32]" />
+        <TresMeshStandardMaterial
+          :map="pbrTexture.map"
+          :displacementMap="pbrTexture.displacementMap"
+          :roughnessMap="pbrTexture.roughnessMap"
+          :normalMap="pbrTexture.normalMap"
+          :ambientOcclusionMap="pbrTexture.ambientOcclusionMap"
+        />
+      </TresMesh>
+    </TresScene>
+  </TresCanvas>
+</Suspense>
+```

docs/zh/examples/orbit-controls.md

@@ -0,0 +1,97 @@
+# OrbitControls {#OrbitControls}
+
+<StackBlitzEmbed projectId="tresjs-orbit-controls" />
+
+[OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) 是一个相机控制器，它允许您围绕一个目标旋转。这是探索场景的好方法。
+
+然而，它不在 ThreeJS 的核心包中。需要从 `three/examples/jsm/controls/OrbitControls` 导入。
+
+由于 **TresJS** 只会自动将 Three 核心包中的内容自动注册为 Vue 组件供您使用，因此，上面的对象就会带来使用上的问题。
+
+幸运的是，**TresJS** 提供了一种扩展组件的方法。您可以使用 [useCatalogue](/api/composables#usecatalog) 暴露出来的 `extend` 方法来扩展。
+
+## 使用 OrbitControls {#Using OrbitControls}
+
+首先从 `three/examples/jsm/controls/OrbitControls` 导入这个模块。
+
+```js
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
+```
+
+接着使用 [useCatalogue](/api/composables#usecatalog) 暴露出来的 `extend` 方法扩展并注册组件。
+
+```js
+import { useCatalogue } from "@tresjs/core";
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
+
+const { extend } = useCatalogue();
+
+extend({ OrbitControls });
+```
+
+最后在场景中使用 `TresOrbitControls` 组件。
+
+```vue
+<template>
+  <TresCanvas shadows alpha>
+    <TresScene>
+      <TresOrbitControls
+        v-if="state.renderer"
+        :args="[state.camera, state.renderer?.domElement]"
+      />
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+[OrbitControls](https://threejs.org/docs/index.html?q=orbit#examples/en/controls/OrbitControls) 创建时需要参入相应的相机和渲染器，您可以将它们作为参数传入。
+
+使用 [useThree](/api/composables#usethree) 组合式函数获取相机和渲染器。
+
+```ts
+import { useThree } from "@tresjs/core";
+
+const { state } = useTres();
+```
+
+完整的代码:
+
+```vue
+<script setup lang="ts">
+import { useCatalogue } from "@tresjs/core";
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
+
+const { extend } = useCatalogue();
+extend({ OrbitControls });
+
+const { state } = useThree();
+</script>
+<template>
+  <TresCanvas shadows alpha>
+    <TresScene>
+      <TresOrbitControls
+        v-if="state.renderer"
+        :args="[state.camera, state.renderer?.domElement]"
+      />
+      ...
+    </TresScene>
+  </TresCanvas>
+</template>
+```
+
+## `cientos` 中的 OrbitControls
+
+这是奇妙之旅的起点。✨
+
+`cientos` 包提供了一个名为 `<OrbitControls />` 的组件，它包装了 [`three-stdlib`](https://github.com/pmndrs/three-stdlib) 模块中的 `OrbitControls`。
+
+你不需要自己去扩展组件或者传入任何参数。挺酷的吧？💯
+
+```vue
+<template>
+  <TresCanvas shadows alpha>
+    <OrbitControls />
+    <TresScene> ... </TresScene>
+  </TresCanvas>
+</template>
+```

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

@@ -0,0 +1,183 @@
+# Text3D
+
+[TextGeometry](https://threejs.org/docs/index.html?q=text#examples/en/geometries/TextGeometry) 是给场景中添加 3D 文本的一种方式。
+
+<StackBlitzEmbed projectId="tresjs-text3d-cientos" />
+
+然而，它不在 ThreeJS 的核心包中。需要从 `three/examples/jsm/controls/TextGeometry` 导入。
+
+由于 **TresJS** 只会自动将 Three 核心包中的内容自动注册为 Vue 组件供您使用，因此，上面的对象就会带来使用上的问题。
+
+幸运的是，**TresJS** 提供了一种扩展组件的方法。您可以使用 [useCatalogue](/api/composables#usecatalog) 暴露出来的 `extend` 方法来扩展。
+
+更多细节信息请查看 [extending](/advanced/extending.md)。
+
+## 使用 TextGeometry
+
+首先从 `three/examples/jsm/geometries/TextGeometry` 导入这个模块。
+
+```js
+import { TextGeometry } from "three/examples/jsm/geometries/TextGeometry";
+```
+
+接着使用 [useCatalogue](/api/composables#usecatalog) 暴露出来的 `extend` 方法扩展并注册组件。
+
+```js
+import { useCatalogue } from "@tresjs/core";
+import { TextGeometry } from "three/examples/jsm/geometries/TextGeometry";
+
+const { extend } = useCatalogue();
+
+extend({ TextGeometry: 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>
+    <TresScene>
+      <TresMesh>
+        <TresTextGeometry :args="['TresJS', { font, ...fontOptions }]" center />
+      </TresMesh>
+    </TresScene>
+  </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,
+};
+```
+
+我们还可以通过在 `TresMesh` 中使用 `TresMeshNormalMaterial` 传递 `matcapTexture` 来丰富细节。
+
+```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 { TextGeometry } from "three/examples/jsm/geometries/TextGeometry";
+import { FontLoader } from "three/examples/jsm/loaders/FontLoader";
+import { useCatalogue, useTexture } from "/@/core";
+const { extend } = useCatalogue();
+
+extend({ TextGeometry: 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>
+  <TresMesh>
+    <TresTextGeometry :args="['TresJS', { font, ...fontOptions }]" center />
+    <TresMeshNormalMaterial :matcap="matcapTexture" />
+  </TresMesh>
+</template>
+```
+
+上面的方式的确很麻烦，好消息是有一种更简单的方法。
+
+## `cientos` 中的 TextGeometry
+
+`cientos` 包提供了一个名为 `<Text3D />` 的组件，它包装了 [`three-stdlib`](https://github.com/pmndrs/three-stdlib) 模块中的 `TextGeometry`。
+
+你不需要自己去扩展组件只需要传入字体参数（若不传，文本内容默认为 TresJS）。挺酷的吧？💯
+
+```vue
+<template>
+  <TresCanvas shadows alpha>
+    <TresScene>
+      <Text3D :font="fontPath" />
+    </TresScene>
+  </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" 将其居中。
+
+```js
+<Text3D :font="fontPath" :text="my 3d text" center  />
+```

docs/zh/index.md

@@ -0,0 +1,35 @@
+---
+layout: home
+
+title: TresJS
+titleTemplate: The solution for 3D on VueJS
+
+hero:
+  name: TresJS
+  text: 为 Vue 的生态带来 Three
+  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` 这类包扩展核心功能，当然也支持您自己的包。
+---