Iteration Plan: Milestone 0.8 - Document

[cptbtptpbcptdtptp]

更新（在现有文档上对内容的迭代）

• 快速入门
  • 0. 安装 Oasis Engine @GuoLei1990
    • 更新 Toolkit 相关内容
  • 1. 初始化画布 @eyworldwide feat: canvas #422
    • 检查画布 clientWidth 与 clientHeight (为空时投影矩阵有误)
    • 更新画布需要做的处理（resizeByClientSize）
  • 3. 加载一个 3D 模型 @zhuxudong
    • 补充一下当前支持的格式（glTF文件，glb文件）
  • 5. 第一个游戏 @cptbtptpbcptdtptp
    • 优化屏幕适配与碰撞部分逻辑
• 核心
  • 引擎 @GuoLei1990
    • 把设置帧率单独拉出来作为一个二级标题
    • 将几个状态阶段细致说一下（new，run，pause，resume，destroy）
  • 场景 @gz65555 Fix/scene #424
    • 激活，合并与加载场景为一个二级标签
    • 场景的 background 设置为一个二级标签，内含纯色，天空盒等
    • 增加一张图说明 Engine 与 Scene， Scene 与 Root 的关系
    • 补充下取 Scene 的正确姿势 (engine.SceneManager ? this.scene?)
  • 实体与组件 @JujieX
    • 优化顺序，可以考虑先写实体的增删改查，在写组件的增删改查，然后实体与组件的关系（如何从组件内获取实体，从实体内获取组件）
    • 写清楚实体与组件的 active，enable 和 destroy，包括主动与被动的情况下（主动即开发者调用 enable， 被动可能是开发者remove了这个 Entity）
    • 可以考虑增加如何写自定义组件
  • 脚本 @luzhuang
    • 更新脚本生命周期大图
  • 变换 @johanzhu
    • 增加对世界坐标的一些简单说明（右手坐标系，相机朝向等）
  • 克隆 @GuoLei1990
    • 是否需要补充 _cloneTo 方法的说明？
• 图形
  • 相机组件 @cptbtptpbcptdtptp
    • 开篇先介绍透视投影和正交投影的使用和属性含义
    • 相机的朝向和 lookat 函数
    • 相机的渲染剔除（cullMask 和 Layer，需要描述 Layer 在层级中的影响关系和先后顺序）
    • 单相机多次渲染 和 多相机渲染（单相机多次渲染主要讲onBeginRender 与 renderTarget，多相机主要讲CameraClearFlags，以及两者的性能差异）
  • 相机控件 @cptbtptpbcptdtptp
    • 修复 playground bug
  • 自定义材质 @zhuxudong
    • 可以把较多部分的内容移至材质总览（如内置shader变量，宏开关，渲染状态，渲染队列）
    • 可以将渲染状态和渲染队列说得更清楚一些
  • 纹理总览 @zhuxudong
    • UV 坐标
    • 纹理重复模式可能带来的问题（白边）
    • 一些设置对性能的影响（主要是内存）
    • 简单描述下纹理格式（R8G8B8A8 等）
  • 离屏渲染纹理 @zhuxudong
    • 增加离屏渲染深度纹理
  • 纹理压缩 @zhuxudong
    • 直接搞表格和示例，让他们可以一眼明白支持的压缩纹理类型，并且可以直接拷贝代码（只需换下URL）
  • 精灵渲染器 @singlecoder
    • 参考坐标系与SpriteRender 在三维空间的位姿（平行于父节点的 XoY 平面，让开发者基本有个概念）
    • 补充说明包围盒以及渲染顺序
  • 精灵资源 @singlecoder
    • Region 与 Pivot 的参考坐标原点
    • Texture2D 与 Sprite 的关系，Sprite 的销毁
  • 精灵图集 @cptbtptpbcptdtptp
    • 加载远端与本地图集资源
  • 文字渲染器 @singlecoder
    • 多写些原子化的 playground 让开发者拷贝。
    • 列举文字目前支持的能力与不支持的能力表格
• 动画

  • 动画组件 @luzhuang Feat/animator #425

    • 重点突出一些案例如：
      • 播放速度控制（倒放，停止，继续等等）
      • Once 和 Loop
      • 从指定开始帧播到指定结束帧
      • 过渡混合
      • 指定跳转的某一帧
      • 事件派发（现在还是有些冗余）
    • 对概念的介绍可以更直白一些，同时没有表现出动画层级结构中一对多的关系。

  • Spine @johanzhu

    • 特点与适用场景（让开发者知道什么情况下选 Spine）
    • 重点突出一些案例如：
      • 播放速度控制（倒放，停止，继续等等）
      • Once 和 Loop
      • 从指定开始帧播到指定结束帧
      • 过渡混合
      • 指定跳转的某一帧
      • 事件派发

  • Lottie @eyworldwide TODO：lottie 引擎还未适配，文档也延迟修改。

    • 重点突出一些案例如：
      • 播放速度控制（倒放，停止，继续等等）
      • Once 和 Loop
      • 从指定开始帧播到指定结束帧
      • 过渡混合
      • 指定跳转的某一帧
      • 事件派发

  • 粒子动画 @eyworldwide TODO：粒子待重构，文档先不动

    • 2D 粒子与 3D 粒子在三维空间的大致位置（开发者大致有个感觉）
• 物理
  • 物理总览 @yangfengzzz
    • 让开发者知道什么时候选 lite 什么时候选 physX（额外包大小，不同能力，性能，表现效果，wasm的平台适配等）
  • 物理管理器 @yangfengzzz
    • 浏览器失焦后的追帧（maxSumTimeStep）
  • 碰撞器组件 @yangfengzzz
    • 增加给 MeshRenderer 添加包围盒的示例（通过包围盒）
• 交互
  • 鼠标与触控 @cptbtptpbcptdtptp
    • 兼容性与 PolyFill
• 资源
  • 资源管理与加载 @gz65555 Doc: resource manager #428
    • 加载了 A 其他地方如何获取这个资源
  • glTF @zhuxudong
    • 补充一下当前支持的格式（glTF文件，glb文件）
    • 可以补充下 glTF 资源的压缩策略以及这些策略的平台兼容
    • 如何处理相对路径的 glTF

[cptbtptpbcptdtptp]

新增（补充内容）

• 相机取景与屏幕适配 @cptbtptpbcptdtptp
• Oasis 内的坐标（三维空间坐标，viewpoint坐标，二维精灵坐标，UV坐标等等）@cptbtptpbcptdtptp
• 渲染顺序相关 @singlecoder

[cptbtptpbcptdtptp]

在写文档的时候，大家可以参考一下：

1. 使用总分结构，先描述这是个什么东西，然后分别描述他的属性，用法，效果等。
2. 描述如何增，删，改， 查，例如
   • 实体与组件的创建，移除，激活，销毁，隐藏，查询
   • 资产的加载，使用，卸载，查询
3. 是否清楚说明属性的设置效果（使用表格）
4. 是否清楚说明状态的含义（使用表格）
5. 是否说明操作时可能抛出的错误，如加载失败开发者是否可以从 Error 中获取更多信息
6. 如果是渲染效果相关的，可以多展示效果图
7. 增加对比，如 ModelMesh 和 BufferMesh 的对比，Spine 和 Lottie 的对比，方便开发者选型。
8. 可以考虑在结尾增加 QA 内容。
9. 在使用中文名词和英文名词时，尽量与业内规范并且在文档内统一。

[yangfengzzz]

Engine-toolkit 的文档要怎么整合进去？

[cptbtptpbcptdtptp]

toolkit 需要新增一个目录，我加一下