Update XR , Start and Input doc (#2275)

* feat: update doc
galacean · Aug 2, 2024 · 4e5803d · 4e5803d
1 parent 9290f47
commit 4e5803d
Show file tree

Hide file tree

Showing 41 changed files with 1,087 additions and 432 deletions.
diff --git a/docs/zh/_meta.json b/docs/zh/_meta.json
@@ -54,7 +54,7 @@
     }
   },
   "input": {
-    "title": "输入",
+    "title": "交互",
     "theme": {
       "collapse": true
     }
@@ -71,6 +71,12 @@
       "collapse": true
     }
   },
+  "miniProgram": {
+    "title": "小程序",
+    "theme": {
+      "collapse": true
+    }
+  },
   "art": {
     "title": "美术",
     "theme": {

diff --git a/docs/zh/core/engine.md b/docs/zh/core/engine.md
@@ -5,7 +5,7 @@ type: 核心
 label: Core
 ---
 
-`Engine` 在 Galacean Engine 中扮演着总控制器的角色，主要包含了**画布**、**渲染控制**和**引擎子系统管理**等三大功能：
+`Engine` 在 Galacean Engine 中扮演着总控制器的角色，主要包含了**画布**、**渲染控制**和**引擎子系统管理**等功能：
 
 - **[画布](/docs/core/canvas)**：主画布相关的操作，如修改画布宽高等。
 - **渲染控制**： 控制渲染的执行/暂停/继续、垂直同步等功能。
@@ -25,46 +25,60 @@ label: Core
 const engine = await WebGLEngine.create({ canvas: "canvas" });
 ```
 
-> `WebGLEngine.create` 不仅承担着实例化引擎的职责，还负责渲染上下文的配置和某些子系统的初始化。
+`WebGLEngine.create` 不仅承担着实例化引擎的职责，还负责渲染上下文的配置和某些子系统的初始化，下方是创建引擎时传入配置的类型说明：
 
-### 渲染上下文
+```mermaid
+---
+title: WebGLEngineConfiguration Interface
+---
+classDiagram
+    EngineConfiguration <|-- WebGLEngineConfiguration
+    class EngineConfiguration {
+       <<interface>>
+       +IPhysics physics
+       +IXRDevice xrDevice
+       +ColorSpace colorSpace
+       +IShaderLab shaderLab
+       +IInputOptions input
+    }
+
+    class WebGLEngineConfiguration{
+        <<interface>>
+        +HTMLCanvasElement | OffscreenCanvas | string canvas
+        +WebGLGraphicDeviceOptions graphicDeviceOptions
+    }
+```
 
-开发者可以在 [导出界面](/docs/assets-build) 设置上下文的渲染配置。
+编辑器导出的项目通常自动设置了编辑器配置的相关选项，比如开发者可以在 [导出界面](/docs/assets-build) 设置上下文的渲染配置：
 
 <img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*WZHzRYIpUzQAAAAAAAAAAAAADhuCAQ/original" style="zoom:50%;" />
 
-您也可以通过脚本设置 [WebGLEngine](${api}rhi-webgl/WebGLEngine) 的第三个参数 [WebGLGraphicDeviceOptions](${api}rhi-webgl/WebGLGraphicDeviceOptions) 来进行管理，拿**画布透明**来举例，引擎默认是将画布的透明通道开启的，即画布会和背后的网页元素混合，如果需要关闭透明，可以这样设置：
+又或者在编辑器的项目设置界面选择物理后端与 XR 后端：
+
+<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*iBDlTbGGuroAAAAAAAAAAAAADhuCAQ/original" style="zoom:50%;" />
+
+您也可以修改代码变更引擎配置，拿**画布透明**来举例，引擎默认是将画布的透明通道开启的，即画布会和背后的网页元素混合，如果需要关闭透明，可以这样设置：
 
 ```typescript
 const engine = await WebGLEngine.create({
   canvas: htmlCanvas,
-  graphicDeviceOptions: { alpha: false },
+  graphicDeviceOptions: { alpha: false }
 });
 ```
 
 类似的，可以用 `webGLMode` 控制 WebGL1/2，除 `webGLMode` 外的属性将透传给上下文，详情可参考 [getContext 参数释义](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext#parameters)。
 
-### 物理系统
-
-可参考 [物理系统](/docs/physics-overall) 文档
-
-### 交互系统
-
-可参考 [交互系统](/docs/input) 文档
-
-### XR 系统
-
-可参考 [XR 系统](/docs/xr-overall) 文档
+更多相关配置信息，可参考[物理系统](/docs/physics-overall)、[交互系统](/docs/input)、[XR 系统](/docs/xr-overall)。
 
 ## 属性
 
-| 属性名称                                             | 属性释义                                                                                                                                                                                                                                        |
-| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [time](/apis/core/#Engine-time)                       | 引擎时间相关的信息。                                                                                                                                                                                                                            |
-| [vSyncCount](/apis/core/#Engine-vSyncCount)           | 引擎默认开启[垂直同步](https://baike.baidu.com/item/%E5%9E%82%E7%9B%B4%E5%90%8C%E6%AD%A5/7263524?fromtitle=V-Sync&fromid=691778)且刷新率 `vSyncCount` 为`1`，即与屏幕刷新率保持一致。如果 `vSyncCount` 设置为`2`，则每刷新 2 帧，引擎更新一次。 |
-| [resourceManager](/apis/core/#Engine-resourceManager) | 资源管理                                                                                                                                                                                                                                        |
-| [sceneManager](/apis/core/#Engine-sceneManager)       | 场景管理。_Engine_ 是总控制器，_Scene_ 作为场景单元，可以方便大型场景的实体管理；_Camera_ 作为组件挂载在 _Scene_ 中的某一实体下，和现实中的摄像机一样，可以选择拍摄 _Scene_ 中的任何实体 ，最后渲染到屏幕上的一块区域或者离屏渲染。             |
-| [inputManager](/apis/core/#Engine-inputManager)       | 交互管理                                                                                                                                                                                                                                        |
+| 属性名称 | 属性释义 |
+| --- | --- |
+| [time](/apis/core/#Engine-time) | 引擎时间相关信息，详情可参考[时间](/docs/core/time/) |
+| [vSyncCount](/apis/core/#Engine-vSyncCount) | 垂直同步刷新率，引擎默认开启[垂直同步](https://baike.baidu.com/item/%E5%9E%82%E7%9B%B4%E5%90%8C%E6%AD%A5/7263524?fromtitle=V-Sync&fromid=691778)且刷新率 `vSyncCount` 为`1` （与屏幕刷新率保持一致）。若 `vSyncCount` 设置为`2`，则屏幕每刷新 2 帧，引擎更新 1 次。 |
+| [resourceManager](/apis/core/#Engine-resourceManager) | 资源管理器，一般通过它进行资产的[加载](/docs/assets/load/)和[释放](/docs/assets/gc/) |
+| [sceneManager](/apis/core/#Engine-sceneManager) | 场景管理器。Galacean 支持多场景同时渲染，通过场景管理器可以方便地管理当前场景的增删改查，详情可参考[场景](/docs/core/scene/) |
+| [inputManager](/apis/core/#Engine-inputManager) | 交互管理器，一般通过它获取键盘，触控与滚轮信息，详情可参考[交互](/docs/input/input/) |
 
 ### 刷新率
 
@@ -86,8 +100,8 @@ engine.targetFrameRate = 120;
 
 ## 方法
 
-| 方法名称                             | 方法释义           |
-| ------------------------------------ | ------------------ |
+| 方法名称                              | 方法释义           |
+| ------------------------------------- | ------------------ |
 | [run](/apis/core/#Engine-run)         | 执行引擎渲染帧循环 |
 | [pause](/apis/core/#Engine-pause)     | 暂停引擎渲染帧循环 |
 | [resume](/apis/core/#Engine-resume)   | 恢复引擎渲渲染循环 |

diff --git a/docs/zh/graphics/2D/2d.md b/docs/zh/graphics/2D/2d.md
@@ -19,10 +19,11 @@ Galacean 是 3D/2D 的互动解决方案，您可以在**编辑器主页**的**
 
 接下来让我们来深入了解以下内容：
 
-- [精灵](/docs/graphics-2d-sprite)
-- [精灵渲染器](/docs/graphics-2d-spriteRenderer)
-- [精灵遮罩](/docs/graphics-2d-spriteMask)
-- [文字渲染器](/docs/graphics-2d-text)
-- [精灵图集](/docs/graphics-2d-spriteAtlas)
-- [Lottie](/docs/graphics-2d-lottie)
+- [精灵](/docs/graphics/2D/sprite/)
+- [精灵渲染器](/docs/graphics/2D/spriteRenderer/)
+- [精灵遮罩](/docs/graphics/2D/spriteMask/)
+- [文字渲染器](/docs/graphics/2D/text/)
+- [精灵图集](/docs/graphics/2D/spriteAtlas/)
+- [Lottie](/docs/graphics/2D/lottie/)
 - [Spine](/docs/graphics/2D/spine/overview)
+
diff --git a/docs/zh/graphics/2D/lottie.md b/docs/zh/graphics/2D/lottie.md
@@ -144,6 +144,12 @@ engine.resourceManager.load({
 
 <playground src="lottie-3d-rotation.ts"></playground>
 
+### 版本依赖
+| 引擎版本 |  Lottie 版本 |
+| :--- | :--- |
+| 1.2.x | 1.1.0-beta.0 |
+| 1.3.x | 1.1.0-beta.0 |
+
 ## 性能方面的建议
 
 - 动画简单化。创建动画时需时刻记着保持 json 文件的精简，比如尽量不使用占用空间最多的路径关键帧动画。诸如自动跟踪描绘、颤动之类的技术会使得 json 文件变得非常大且耗性能。
@@ -163,10 +169,4 @@ engine.resourceManager.load({
 - 删除那些关闭了和无用的属性。
 - 只导出 1x 图。
 - 为了防止 lottie 导出的兼容性问题，请尽量使用英文版本 AE ，图层需简洁，命名清晰
-- 避免大面积矢量部分，以及大面积粒子效果
-
-### Lottie 使用版本说明
-| 引擎版本 |  Lottie 版本 |
-| :--- | :--- |
-| 1.2.x | 1.1.0-beta.0 |
-| 1.3.x | 1.1.0-beta.0 |
+- 避免大面积矢量部分，以及大面积粒子效果
diff --git a/docs/zh/graphics/2D/sprite.md b/docs/zh/graphics/2D/sprite.md
@@ -6,7 +6,7 @@ group: 2D
 label: Graphics/2D
 ---
 
-[Sprite](/apis/core/#Sprite) 是 2D 项目中最重要的资产，他从 [Texture2D](/docs/graphics-texture-2d) 中获取图形源数据，通过设置 [region](/apis/core/#Sprite-region)，[pivot](/apis/core/#Sprite-pivot) 等属性定制期望的渲染结果，若将其赋予[SpriteRenderer](/apis/core/#SpriteRenderer)，挂载了精灵渲染器的节点就可以在三维空间中展示 2D 图片，若将其赋予[SpriteMask](/docs/graphics-2d-spriteMask)，挂载了精灵遮罩的节点就可以对相应的 2D 元素实现遮罩效果，接下来就让我们深入了解精灵的属性和用法。
+[Sprite](/apis/core/#Sprite) 是 2D 项目中最重要的资产，他从 [Texture2D](/docs/graphics/texture/2d/) 中获取图形源数据，通过设置 [region](/apis/core/#Sprite-region)，[pivot](/apis/core/#Sprite-pivot) 等属性定制期望的渲染结果，若将其赋予[SpriteRenderer](/apis/core/#SpriteRenderer)，挂载了精灵渲染器的节点就可以在三维空间中展示 2D 图片，若将其赋予[SpriteMask](/docs/graphics/2D/spriteMask/)，挂载了精灵遮罩的节点就可以对相应的 2D 元素实现遮罩效果，接下来就让我们深入了解精灵的属性和用法。
 
 ## 属性
 
@@ -33,13 +33,13 @@ pivot 代表精灵中心在 region 中的位置，如下：
 
 #### 上传精灵
 
-在 **[资产面板](/docs/assets-interface)** 空白处依次 **右键** → **Upload** → **Sprite** → **选中对应图片** 即可上传精灵资产，上传成功后当前资产列表会同步添加一份名为 `图片名.png` 的纹理资产和一份 `图片名-spr.png` 的精灵资产
+在 **[资产面板](/docs/assets/interface/)** 空白处依次 **右键** → **Upload** → **Sprite** → **选中对应图片** 即可上传精灵资产，上传成功后当前资产列表会同步添加一份名为 `图片名.png` 的纹理资产和一份 `图片名-spr.png` 的精灵资产
 
 <img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*bRghQqoN1GAAAAAAAAAAAAAADhuCAQ/original" alt="avatar"  />
 
 #### 创建空白精灵
 
-在 **[资产面板](/docs/assets-interface)** 空白处依次 **右键** → **Create** → **Sprite** 即可创建一份空白的精灵资产。
+在 **[资产面板](/docs/assets/interface/)** 空白处依次 **右键** → **Create** → **Sprite** 即可创建一份空白的精灵资产。
 
 <img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*Gv96TrKvRkEAAAAAAAAAAAAADhuCAQ/original" alt="avatar"  />
 

diff --git a/docs/zh/graphics/2D/spriteAtlas.md b/docs/zh/graphics/2D/spriteAtlas.md
@@ -20,7 +20,7 @@ label: Graphics/2D
 
 ### 创建精灵图集
 
-在 **[资产面板](/docs/assets-interface)** 内右键，选择`功能列表`中的`创建`，并选中`精灵图集`，此时，一个空白的精灵图集资产就创建成功了。
+在 **[资产面板](/docs/assets/interface/)** 内右键，选择`功能列表`中的`创建`，并选中`精灵图集`，此时，一个空白的精灵图集资产就创建成功了。
 
 <img src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*W-HZSrvAiG8AAAAAAAAAAAAADjCHAQ/original" alt="buildBox" style="zoom: 67%;" />
 
@@ -72,23 +72,27 @@ label: Graphics/2D
 
 | 设置名称           | 释义                                     |
 | ------------------ | ---------------------------------------- |
-| 纹理最大宽度       | 打包得到纹理的最大限制宽度               |
-| 纹理最大高度       | 打包得到纹理的最大限制高度               |
+| 纹理最大宽度       | 打包得到纹理的最大限制宽度(1，2048]      |
+| 纹理最大高度       | 打包得到纹理的最大限制高度(1，2048]      |
 | 边缘填充           | 打包精灵的边缘填充宽度                   |
 | 允许旋转（未启用） | 是否通过旋转提高图集打包的空间利用率     |
 | 空白裁减（未启用） | 是否通过空白裁减提高图集打包的空间利用率 |
 
+若打包遇到如下警告，说明图集结果的尺寸超过了纹理最大宽度和最大高度，此时可通过调整`纹理最大宽度`与`纹理最大高度`或**重新编排**打包的散图解决。
+
+<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*dE71RKXvGAAAAAAAAAAAAAAADhuCAQ/original" style="zoom:50%;" />
+
 #### 导出设置
 
 <img src="https://gw.alipayobjects.com/zos/OasisHub/1f4302b8-d485-4d3e-b508-36b570f5a883/image-20231208165430415.png" alt="image-20231208165430415" style="zoom:50%;" />
 
-| 属性                                                            | 值                                                                                                                                                                                         |
-| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 循环模式 U（[wrapModeU](/apis/core/#Texture-wrapModeU)）         | 截取模式（[Clamp](/apis/core/#TextureWrapMode-Clamp)）、 重复模式（[Repeat](/apis/core/#TextureWrapMode-Repeat)）、镜像重复模式（[Mirror](/apis/core/#TextureWrapMode-Mirror)）               |
-| 循环模式 V（[wrapModeV](/apis/core/#Texture-wrapModeV)）         | 截取模式（[Clamp](/apis/core/#TextureWrapMode-Clamp)）、重复模式（[Repeat](/apis/core/#TextureWrapMode-Repeat)）、 镜像重复模式（[Mirror](/apis/core/#TextureWrapMode-Mirror)）               |
-| 过滤模式（[filterMode](/apis/core/#Texture-filterMode)）         | 点过滤（[Point](/apis/core/#TextureFilterMode-Point)）、双线性过滤（[Bilinear](/apis/core/#TextureFilterMode-Bilinear)）、 三线性过滤（[Trilinear](/apis/core/#TextureFilterMode-Trilinear)） |
-| 各向异性过滤等级（[anisoLevel](/apis/core/#Texture-anisoLevel)） | 向向异性等级，1 ~ 16                                                                                                                                                                       |
-| 纹理映射([Mipmap](/apis/core/#Texture-generateMipmaps)）         | true , false                                                                                                                                                                               |
+| 属性 | 值 |
+| --- | --- |
+| 循环模式 U（[wrapModeU](/apis/core/#Texture-wrapModeU)） | 截取模式（[Clamp](/apis/core/#TextureWrapMode-Clamp)）、 重复模式（[Repeat](/apis/core/#TextureWrapMode-Repeat)）、镜像重复模式（[Mirror](/apis/core/#TextureWrapMode-Mirror)） |
+| 循环模式 V（[wrapModeV](/apis/core/#Texture-wrapModeV)） | 截取模式（[Clamp](/apis/core/#TextureWrapMode-Clamp)）、重复模式（[Repeat](/apis/core/#TextureWrapMode-Repeat)）、 镜像重复模式（[Mirror](/apis/core/#TextureWrapMode-Mirror)） |
+| 过滤模式（[filterMode](/apis/core/#Texture-filterMode)） | 点过滤（[Point](/apis/core/#TextureFilterMode-Point)）、双线性过滤（[Bilinear](/apis/core/#TextureFilterMode-Bilinear)）、 三线性过滤（[Trilinear](/apis/core/#TextureFilterMode-Trilinear)） |
+| 各向异性过滤等级（[anisoLevel](/apis/core/#Texture-anisoLevel)） | 向向异性等级，1 ~ 16 |
+| 纹理映射([Mipmap](/apis/core/#Texture-generateMipmaps)） | true , false |
 
 ### 最佳实践
 
@@ -144,7 +148,7 @@ galacean-tool-atlas p inputPath -o outputName
 engine.resourceManager
   .load<SpriteAtlas>({
     url: "https://*cdnDir*/*atlasName*.atlas",
-    type: AssetType.SpriteAtlas,
+    type: AssetType.SpriteAtlas
   })
   .then((atlas) => {
     // Get all sprites.

diff --git a/docs/zh/graphics/2D/spriteMask.md b/docs/zh/graphics/2D/spriteMask.md
@@ -6,11 +6,11 @@ group: 2D
 label: Graphics/2D
 ---
 
-精灵遮罩组件用于对 3D/2D 场景中的[精灵](/docs/graphics-2d-spriteRenderer)和[文本](/docs/graphics-2d-text)实现遮罩效果。
+精灵遮罩组件用于对 3D/2D 场景中的[精灵渲染器](/docs/graphics/2D/spriteRenderer/)和[文字渲染器](/docs/graphics/2D/text/)实现遮罩效果。
 
 <playground src="sprite-mask.ts"></playground>
 
-通过 [SpriteMask](/apis/core/#SpriteMask) 提供的参数来控制和 [精灵](/docs/graphics-2d-sprite) 发生作用。
+通过 [SpriteMask](/apis/core/#SpriteMask) 提供的参数来控制和 [精灵](/docs/graphics/2D/sprite/) 发生作用。
 
 | 参数            | 类型   | 说明                                                                                             |
 | :-------------- | :----- | :----------------------------------------------------------------------------------------------- |

diff --git a/docs/zh/graphics/2D/spriteRenderer.md b/docs/zh/graphics/2D/spriteRenderer.md
@@ -87,10 +87,10 @@ spriteRenderer.sprite = sprite;
 
 ### 遮罩
 
-请参考[精灵遮罩](/docs/graphics-2d-spriteMask)文档。
+请参考[精灵遮罩](/docs/graphics/2D/spriteMask/)文档。
 
 ## 自定义材质
 
-请参考[自定义着色器](/docs/graphics-shader-custom)文档。
+请参考[自定义着色器](/docs/graphics/shader/custom/)文档。
 
 <playground src="sprite-material-blur.ts"></playground>
diff --git a/docs/zh/graphics/camera/camera.md b/docs/zh/graphics/camera/camera.md
@@ -50,7 +50,7 @@ Galacean 中的局部坐标与世界坐标遵循`右手坐标系`，因此相机
 
 介绍了相机的基本概念，接下来让我们上手：
 
-- 在场景中添加[相机组件](/docs/graphics-camera-component)
-- 通过[相机控件](/docs/graphics-camera-control)来更方便地操控[相机组件](/docs/graphics-camera-component)
-- 在场景中使用[多相机](graphics-camera-multiCamera)
-- 获取[相机深度纹理](graphics-camera-depthTexture)
+- 在场景中添加[相机组件](/docs/graphics/camera/component/)
+- 通过[相机控件](/docs/graphics/camera/control/)来更方便地操控[相机组件](/docs/graphics/camera/component/)
+- 在场景中使用[多相机](/docs/graphics/camera/multiCamera/)
+- 获取[相机纹理](/docs/graphics/camera/texture/)