From ce325ea6264050420dfe70f95dd460e4edece57a Mon Sep 17 00:00:00 2001 From: SmallMain Date: Wed, 8 Jun 2022 20:34:57 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 70 ++++----- .../installation-engine-plugin.md | 4 + .../installation-guide/installation-intro.mdx | 5 +- .../installation-guide/installation-manual.md | 43 ++++-- docs/docs/intro.md | 65 ++++---- docs/docs/update-log.md | 6 + docs/docs/user-guide/_category_.json | 4 +- docs/docs/user-guide/congratulations.md | 21 --- docs/docs/user-guide/create-a-blog-post.md | 34 ---- docs/docs/user-guide/create-a-document.md | 55 ------- docs/docs/user-guide/create-a-page.md | 43 ------ docs/docs/user-guide/deploy-your-site.md | 31 ---- .../dynamic-batcher/_category_.json | 9 ++ .../dynamic-batcher/dynamic-batcher-intro.mdx | 23 +++ .../dynamic-batcher/dynamic-batcher-manual.md | 25 +++ .../dynamic-batcher-settings.md | 49 ++++++ docs/docs/user-guide/markdown-features.mdx | 146 ------------------ .../user-guide/multi-render/_category_.json | 9 ++ .../user-guide/multi-render/multi-material.md | 6 + .../multi-render/multi-render-intro.mdx | 34 ++++ docs/docs/user-guide/user-guide-intro.mdx | 14 ++ docs/src/pages/index.tsx | 18 +-- 22 files changed, 288 insertions(+), 426 deletions(-) create mode 100644 docs/docs/update-log.md delete mode 100644 docs/docs/user-guide/congratulations.md delete mode 100644 docs/docs/user-guide/create-a-blog-post.md delete mode 100644 docs/docs/user-guide/create-a-document.md delete mode 100644 docs/docs/user-guide/create-a-page.md delete mode 100644 docs/docs/user-guide/deploy-your-site.md create mode 100644 docs/docs/user-guide/dynamic-batcher/_category_.json create mode 100644 docs/docs/user-guide/dynamic-batcher/dynamic-batcher-intro.mdx create mode 100644 docs/docs/user-guide/dynamic-batcher/dynamic-batcher-manual.md create mode 100644 docs/docs/user-guide/dynamic-batcher/dynamic-batcher-settings.md delete mode 100644 docs/docs/user-guide/markdown-features.mdx create mode 100644 docs/docs/user-guide/multi-render/_category_.json create mode 100644 docs/docs/user-guide/multi-render/multi-material.md create mode 100644 docs/docs/user-guide/multi-render/multi-render-intro.mdx create mode 100644 docs/docs/user-guide/user-guide-intro.mdx diff --git a/README.md b/README.md index 01482117..36e1333a 100644 --- a/README.md +++ b/README.md @@ -2,64 +2,63 @@ ![logo](/docs/static/img/logo2.png) -这是一个对 Cocos Creator 引擎进行特性增强、修复与优化的**开源非官方服务包**。 +这是一个对 Cocos Creator 引擎进行特性增强、修复与优化的**开源非官方服务包（Service Pack）**。 -我们尽量以最符合引擎架构设计的方式加入新的特性、修复引擎已知问题以及性能优化。 +该项目尽量以最符合原始架构设计的方式为引擎加入新的特性、修复已知问题以及优化性能。 > 项目的起源 > >2021 年 2 月，Cocos 发布 Cocos Creator 3.0，并在 3.x 发布之后不会再继续开发 2.x 版本的新特性，所有维护工作也会在 2023 年完全停止。 > ->但是 2.x 在一些方面还并不完善，所以我们发布了这个非官方的引擎“魔改”合集。 +>但是 2.x 在一些方面还并不完善，所以这个非官方的引擎“魔改”合集的开源项目应运而生。 > >相似的事情发生在 2014 年 4 月，官方停止了对 Windows XP 的维护，之后 Harkaz 发布了一个非官方服务包 Service Pack 4 (SP4)。 > ->受到 Windows XP 的启发，我们将这个非官方的引擎“魔改”合集取名为 Service Pack。 +>受到 Windows XP 命名的启发，这个非官方的引擎“魔改”合集取名为 Service Pack。 > ->我们暂时只专注于 Cocos Creator 2.x 版本的适配，Cocos Creator 3.x 正在蒸蒸日上，其引擎架构还在不断地迭代（不稳定），对其进行修改的维护工作会很大。 +>Service Pack 暂时只适配 Cocos Creator 2.x 版本，Cocos Creator 3.x 正在蒸蒸日上，其引擎架构还在不断地迭代（不稳定），若对其进行修改，之后的维护工作会非常大。 -- [全部改动](#全部改动) +- [重要特性](#重要特性) - [使用方法](#使用方法) - - [引擎扩展](#引擎扩展) - - [Git Patch](#git-patch) - - [直接动手](#直接动手) - [更新日志](#更新日志) + - [v1.0](#v10) - [贡献指南](#贡献指南) - [常见问题](#常见问题) - [为什么要直接修改引擎？](#为什么要直接修改引擎) -## 全部改动 +## 重要特性 -服务包对引擎的所有改动都是开源的，并且每个改动都会附上一篇原理说明的文档，当你发现问题时请进行反馈，或者直接默默地帅气地提交一个 PR，帮助我们一起完善这个项目。 +- **支持多纹理渲染**（多纹理材质、多纹理合批） +- **支持高 DPI 文本渲染**（Label、RichText 组件） +- **重构动态合图**（支持自动多纹理合批、优化算法、复用废弃空间等特性） +- **重构 Label 组件的 CHAR 缓存模式**（支持自动多纹理合批、多图集、复用废弃空间等特性） +- **Spine 组件支持与其它组件合批、合入动态图集与 SpriteFrame 换装** -- 待补充。 +> 提示 +> 服务包对引擎的所有改动都是开源的，并且每个改动都会附上一篇原理说明的文档，当你发现问题时请进行反馈，或者直接默默地帅气地提交一个 PR，帮助我们一起完善这个项目。 ## 使用方法 -我们推荐两种方式来使用这个服务包： +服务包通过自定义引擎的方式来修改引擎代码，你可以： -### 引擎扩展 +- 通过我们发布的引擎扩展一键安装 +- 下载源码包，使用里面的 Git Patch 文件进行安装 -待补充。 - -### Git Patch - -待补充。 - -### 直接动手 - -阅读源码和原理文章来自行提取你想要的部分。 +具体教程可以参考 [安装指南](https://smallmain.github.io/cocos-service-pack/docs/installation-guide/installation-intro)。 ## 更新日志 -待补充。 +### v1.0 +- 待补充 + +所有更新日志请移步 [此处](https://smallmain.github.io/cocos-service-pack/docs/update-log)。 ## 贡献指南 @@ -68,29 +67,26 @@ - 如果你有问题或者好的想法，请建立 `Issues` 或进入 `Discussions` 。 - 如果你有新的代码提交，请建立 `Pull requests`。 -原则上我们接受任何增强与修改，但是**任何修改都必须兼容引擎原有的特性，不允许删除引擎原有的特性**，并且请认真思考功能的设计。 +原则上允许对引擎的任何增强与修改，但是**任何修改都必须兼容引擎原有的特性，不允许删除引擎原有的特性**，并且请认真思考代码设计。 ## 常见问题 ### 为什么要直接修改引擎？ -直接修改引擎可能是大部分人认为的下下策，我们能听到的声音有： +直接修改引擎可能是大部分人认为的下下策，比如我们常听到的一些声音： -- 可以通过 “修改对象的原型” 等一些编程技巧做成一个插件脚本 -- 为什么要改？不改，因为 xxxx 原则说过，不要动旧的代码，我们造新的！ -- 我都没接触过自定义引擎呢，不知道该怎么用 -- 如果我本来就改过引擎，不就很麻烦了吗？ +- 通过 “修改对象的原型” 等一些编程技巧做成一个插件脚本 +- 没接触过自定义引擎，不知道该怎么用，感觉很可怕 +- 我已经修改过引擎的某些部分了，不能直接安装 以上问题我们都思考过， -首先，现在引擎的 2.x 版本已经停止了更新（仅做一些维护工作），也就是说我们的修改基本不会遇到在下个版本需要完全重构的情况。 +首先，现在引擎的 2.x 版本已经停止了更新（仅做一些维护工作），也就是说修改引擎不会遇到在官方新版本发布后需要用大量时间去适配的情况。 -其次，服务包中的大部分改动虽然可以做成一个插件脚本，但是原生平台就无法兼容，并且包体会增大，可维护性也不见得会提升。 +其次，即使服务包中的所有改动都能做成一个插件脚本，但是无法兼容原生平台，并且一般都需要大量拷贝代码，包体会增大，可维护性可能会大幅降低。 -最后，造新的或多或少会增加学习和使用的成本，并且我们希望它是 “原生” 的使用体验。 +最后，我们希望它接近 “原生” 的使用体验，就像引擎本来就有的功能一样，对于没有接触过自定义引擎的人，我们提供的引擎扩展可以一键安装。 -对于没有接触过自定义引擎的人，我们提供的引擎扩展可以一键帮助你设置好自定义引擎。 +对于已经修改过引擎的人，由于服务包提供的是 Git Patch，所以可以让你在已有修改的基础上轻松应用上服务包的改动，甚至你可以只应用你想要的特性。 -对于已经修改过引擎的人，我们提供 Git Patch 可以让你在已有修改的基础上轻松应用我们的更改，可能会产生一些冲突，但我相信你能解决。 - -**最后的最后，希望这个项目能够在你想学习相关知识或者做类似修改时可以帮助到你，享受吧！** +**最后的最后，希望这个项目能帮助到你的学习或工作，enjoy！** diff --git a/docs/docs/installation-guide/installation-engine-plugin.md b/docs/docs/installation-guide/installation-engine-plugin.md index a367ad74..f195c517 100644 --- a/docs/docs/installation-guide/installation-engine-plugin.md +++ b/docs/docs/installation-guide/installation-engine-plugin.md @@ -1 +1,5 @@ +--- +sidebar_position: 1 +--- + # 使用引擎扩展安装 diff --git a/docs/docs/installation-guide/installation-intro.mdx b/docs/docs/installation-guide/installation-intro.mdx index 8a122dd9..7aae45f1 100644 --- a/docs/docs/installation-guide/installation-intro.mdx +++ b/docs/docs/installation-guide/installation-intro.mdx @@ -1,5 +1,4 @@ --- -sidebar_position: 1 hide_title: true title: 安装指南 --- @@ -8,10 +7,10 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; 服务包对引擎的改动主要使用 [自定义引擎](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/engine-customization.html) 的方式实现。 -但由于没有找到方法添加内置资源，所以除此之外还需要您手动往项目里添加一些资源文件。 +由于没有找到方法添加内置资源，所以除此之外还需要你手动往项目里添加一些资源文件。 对于使用 TypeScript 的项目我们还提供 `creator-sp.d.ts` 类型提示文件。 -以下是我们提供的两种安装方法，**推荐使用引擎扩展一键安装**： +以下是我们提供的两种安装方法： diff --git a/docs/docs/installation-guide/installation-manual.md b/docs/docs/installation-guide/installation-manual.md index 66077ed4..58f847c3 100644 --- a/docs/docs/installation-guide/installation-manual.md +++ b/docs/docs/installation-guide/installation-manual.md @@ -1,19 +1,26 @@ +--- +sidebar_position: 2 +--- + # 手动安装 :::caution 提示 -手动安装需要掌握一定的 [Git](https://git-scm.com/doc) 和 [自定义引擎](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/engine-customization.html) 知识，建议使用我们发布的 [引擎扩展](./installation-engine-plugin) 一键安装。 +手动安装需要掌握一定的 [Git](https://git-scm.com/doc) 和 [自定义引擎](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/engine-customization.html) 知识，推荐使用我们发布的 [引擎扩展](./installation-engine-plugin) 一键安装。 ::: ## 引擎要求 -请将 Cocos Creator 至少升级到 **v2.4.x** 版本。 -推荐直接升级到最新版本，2.x 版本只会进行维护性更新，所以不用担心其稳定性问题。 +**请将 Cocos Creator 至少升级到 v2.4.x 版本，服务包不保证对 v2.4 版本以下的兼容性。** + +**强烈推荐直接升级到最新引擎版本**，官方只会对 2.x 版本只会进行维护性更新，所以不用担心其稳定性问题。 + +**并且每次服务包的更新只会发布引擎最新版本的压缩包。** ## 标准安装 -当您项目所使用的引擎版本与服务包适配的引擎版本一致，并且您自己未对引擎有任何改动时，可参照以下步骤安装： +当你的项目所使用的引擎版本与服务包适配的引擎版本一致，并且自己未对引擎有任何改动时，可参考以下步骤安装： ### 1.替换自定义引擎 @@ -31,12 +38,12 @@ **替换 jsb-adapter：**这一步只需要替换目录即可，但请一定不要忘记！ -并且如果您**不需要支持原生平台，可以只配置 JavaScript 引擎**，不需要配置 Cocos2d-x 和 jsb-adapter。 +并且如果你的项目**不需要支持原生平台，可以只定制 JavaScript 引擎**，无需定制 Cocos2d-x 和 jsb-adapter。 ::: ### 2.往项目放入资源 -由于我们无法为引擎新增内置资源，所以需要您手动操作这一步，将压缩包内 `project` 目录的 `sp` 目录拷贝到项目的 `assets` 目录中，并设置 `sp` 目录为 **Asset Bundle**。 +由于我们无法为引擎新增内置资源，所以需要你手动操作这一步，将压缩包内 `project` 目录的 `sp` 目录拷贝到项目的 `assets` 目录中，并设置 `sp` 目录为 **Asset Bundle**。 ![assetbundlesettings](assets/assetbundle-settings.png) @@ -52,24 +59,34 @@ ### 3.TypeScript 类型提示（可选） -如果您的项目使用 TypeScript，请将压缩包内 `project` 目录的 `creator-sp.d.ts` 拷贝到项目根目录中，更新 API 接口类型提示。 +如果你的项目使用 TypeScript，请将压缩包内 `project` 目录的 `creator-sp.d.ts` 拷贝到项目根目录中，更新引擎 API 接口类型提示。 ![dts](assets/dts.png) 部分 IDE 可能需要重启才会生效。 +## 补丁安装 + +如果你无法升级到引擎的最新版本，或者本身已对引擎有过修改，我们提供 Git Patch 让你能在已有修改的基础上应用我们对引擎的改动。 + +接下来我们不会说的很细致，你需要有一定的动手能力。 + +在压缩包内的 `patch` 目录放着最新的 Git Patch 文件，在引擎目录应用补丁就等同于应用了我们对引擎的所有改动，这时候你就可以按照官方的自定义引擎文档去使用了。 + +Git Patch 存储了我们所有的提交信息，所以你可以只挑选你想要的改动进行应用。 + +如果你使用的不是引擎最新版本，你依然可以将 Git Patch 应用在 2.4.x 版本的引擎上进行适配，可能会发生冲突或者不兼容的情况，不过差别应该不是很大，可以自行完成适配工作。 + +完成自定义引擎的工作后，请别忘了还要将资源放入项目哦（可参考标准安装的[第 2、3 步](#2往项目放入资源)进行操作）。 + ## 下载链接 ### Service Pack v1.0 +适配 **Cocos Creator v2.4.9** 版本，请确认你项目的引擎版本一致。 + [下载压缩包](http://www.baidu.com) -:::note - -**Service Pack v1.0** 适配 **Cocos Creator v2.4.9** 版本，请确认您项目的引擎版本一致。 - -::: - ### 历史版本 [存档页面](test) diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 3cdd3ff8..529c5c91 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -6,47 +6,51 @@ hide_title: true ![logo](/img/logo2.png) -这是一个对 Cocos Creator 引擎进行特性增强、修复与优化的**开源非官方服务包**。 +这是一个对 Cocos Creator 引擎进行特性增强、修复与优化的**开源非官方服务包（Service Pack）**。 -我们尽量以最符合引擎架构设计的方式加入新的特性、修复引擎已知问题以及性能优化。 +该项目尽量以最符合原始架构设计的方式为引擎加入新的特性、修复已知问题以及优化性能。 :::info 项目的起源 2021 年 2 月，Cocos 发布 Cocos Creator 3.0，并在 3.x 发布之后不会再继续开发 2.x 版本的新特性，所有维护工作也会在 2023 年完全停止。 -但是 2.x 在一些方面还并不完善，所以我们发布了这个非官方的引擎“魔改”合集。 +但是 2.x 在一些方面还并不完善，所以这个非官方的引擎“魔改”合集的开源项目应运而生。 相似的事情发生在 2014 年 4 月，官方停止了对 Windows XP 的维护，之后 Harkaz 发布了一个非官方服务包 Service Pack 4 (SP4)。 -受到 Windows XP 的启发，我们将这个非官方的引擎“魔改”合集取名为 Service Pack。 +受到 Windows XP 命名的启发，这个非官方的引擎“魔改”合集取名为 Service Pack。 -我们暂时只专注于 Cocos Creator 2.x 版本的适配，Cocos Creator 3.x 正在蒸蒸日上，其引擎架构还在不断地迭代（不稳定），对其进行修改的维护工作会很大。 +Service Pack 暂时只适配 Cocos Creator 2.x 版本，Cocos Creator 3.x 正在蒸蒸日上，其引擎架构还在不断地迭代（不稳定），若对其进行修改，之后的维护工作会非常大。 ::: -## 全部改动 +## 重要特性 + +- **支持多纹理渲染**（多纹理材质、多纹理合批） +- **支持高 DPI 文本渲染**（Label、RichText 组件） +- **重构动态合图**（支持自动多纹理合批、优化算法、复用废弃空间等特性） +- **重构 Label 组件的 CHAR 缓存模式**（支持自动多纹理合批、多图集、复用废弃空间等特性） +- **Spine 组件支持与其它组件合批、合入动态图集与 SpriteFrame 换装** + +:::note 提示 服务包对引擎的所有改动都是开源的，并且每个改动都会附上一篇原理说明的文档，当你发现问题时请进行反馈，或者直接默默地帅气地提交一个 PR，帮助我们一起完善这个项目。 -- 待补充。 +::: ## 使用方法 -我们推荐两种方式来使用这个服务包： +服务包通过自定义引擎的方式来修改引擎代码，你可以： -### 引擎扩展 +- 通过我们发布的引擎扩展一键安装 +- 下载源码包，使用里面的 Git Patch 文件进行安装 -待补充。 - -### Git Patch - -待补充。 - -### 直接动手 - -阅读源码和原理文章来自行提取你想要的部分。 +具体教程可以参考 [安装指南](./installation-guide/installation-intro)。 ## 更新日志 -待补充。 +### v1.0 +- 待补充 + +所有更新日志请移步 [此处](./update-log)。 ## 贡献指南 @@ -55,29 +59,26 @@ hide_title: true - 如果你有问题或者好的想法，请建立 `Issues` 或进入 `Discussions` 。 - 如果你有新的代码提交，请建立 `Pull requests`。 -原则上我们接受任何增强与修改，但是**任何修改都必须兼容引擎原有的特性，不允许删除引擎原有的特性**，并且请认真思考功能的设计。 +原则上允许对引擎的任何增强与修改，但是**任何修改都必须兼容引擎原有的特性，不允许删除引擎原有的特性**，并且请认真思考代码设计。 ## 常见问题 ### 为什么要直接修改引擎？ -直接修改引擎可能是大部分人认为的下下策，我们能听到的声音有： +直接修改引擎可能是大部分人认为的下下策，比如我们常听到的一些声音： -- 可以通过 “修改对象的原型” 等一些编程技巧做成一个插件脚本 -- 为什么要改？不改，因为 xxxx 原则说过，不要动旧的代码，我们造新的！ -- 我都没接触过自定义引擎呢，不知道该怎么用 -- 如果我本来就改过引擎，不就很麻烦了吗？ +- 通过 “修改对象的原型” 等一些编程技巧做成一个插件脚本 +- 没接触过自定义引擎，不知道该怎么用，感觉很可怕 +- 我已经修改过引擎的某些部分了，不能直接安装 以上问题我们都思考过， -首先，现在引擎的 2.x 版本已经停止了更新（仅做一些维护工作），也就是说我们的修改基本不会遇到在下个版本需要完全重构的情况。 +首先，现在引擎的 2.x 版本已经停止了更新（仅做一些维护工作），也就是说修改引擎不会遇到在官方新版本发布后需要用大量时间去适配的情况。 -其次，服务包中的大部分改动虽然可以做成一个插件脚本，但是原生平台就无法兼容，并且包体会增大，可维护性也不见得会提升。 +其次，即使服务包中的所有改动都能做成一个插件脚本，但是无法兼容原生平台，并且一般都需要大量拷贝代码，包体会增大，可维护性可能会大幅降低。 -最后，造新的或多或少会增加学习和使用的成本，并且我们希望它是 “原生” 的使用体验。 +最后，我们希望它接近 “原生” 的使用体验，就像引擎本来就有的功能一样，对于没有接触过自定义引擎的人，我们提供的引擎扩展可以一键安装。 -对于没有接触过自定义引擎的人，我们提供的引擎扩展可以一键帮助你设置好自定义引擎。 +对于已经修改过引擎的人，由于服务包提供的是 Git Patch，所以可以让你在已有修改的基础上轻松应用上服务包的改动，甚至你可以只应用你想要的特性。 -对于已经修改过引擎的人，我们提供 Git Patch 可以让你在已有修改的基础上轻松应用我们的更改，可能会产生一些冲突，但我相信你能解决。 - -**最后的最后，希望这个项目能够在你想学习相关知识或者做类似修改时可以帮助到你，享受吧！** +**最后的最后，希望这个项目能帮助到你的学习或工作，enjoy！** diff --git a/docs/docs/update-log.md b/docs/docs/update-log.md new file mode 100644 index 00000000..5a48dbf6 --- /dev/null +++ b/docs/docs/update-log.md @@ -0,0 +1,6 @@ +--- +sidebar_position: 4 +title: 更新日志 +--- + +## v1.0 diff --git a/docs/docs/user-guide/_category_.json b/docs/docs/user-guide/_category_.json index b65ca9c4..ddd7d88c 100644 --- a/docs/docs/user-guide/_category_.json +++ b/docs/docs/user-guide/_category_.json @@ -3,7 +3,7 @@ "position": 3, "collapsed": false, "link": { - "type": "generated-index", - "description": "5 minutes to learn the most important Docusaurus concepts." + "type": "doc", + "id": "user-guide-intro" } } diff --git a/docs/docs/user-guide/congratulations.md b/docs/docs/user-guide/congratulations.md deleted file mode 100644 index 9ef99bba..00000000 --- a/docs/docs/user-guide/congratulations.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_position: 6 ---- - -# Congratulations! - -You have just learned the **basics of Docusaurus** and made some changes to the **initial template**. - -Docusaurus has **much more to offer**! - -Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**. - -Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610) - -## What's next? - -- Read the [official documentation](https://docusaurus.io/). -- Add a custom [Design and Layout](https://docusaurus.io/docs/styling-layout) -- Add a [search bar](https://docusaurus.io/docs/search) -- Find inspirations in the [Docusaurus showcase](https://docusaurus.io/showcase) -- Get involved in the [Docusaurus Community](https://docusaurus.io/community/support) diff --git a/docs/docs/user-guide/create-a-blog-post.md b/docs/docs/user-guide/create-a-blog-post.md deleted file mode 100644 index 0d50aaf3..00000000 --- a/docs/docs/user-guide/create-a-blog-post.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Create a Blog Post - -Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed... - -## Create your first Post - -Create a file at `blog/2021-02-28-greetings.md`: - -```md title="blog/2021-02-28-greetings.md" ---- -slug: greetings -title: Greetings! -authors: - - name: Joel Marcey - title: Co-creator of Docusaurus 1 - url: https://github.com/JoelMarcey - image_url: https://github.com/JoelMarcey.png - - name: Sébastien Lorber - title: Docusaurus maintainer - url: https://sebastienlorber.com - image_url: https://github.com/slorber.png -tags: [greetings] ---- - -Congratulations, you have made your first post! - -Feel free to play around and edit this post as much you like. -``` - -A new blog post is now available at `http://localhost:3000/blog/greetings`. diff --git a/docs/docs/user-guide/create-a-document.md b/docs/docs/user-guide/create-a-document.md deleted file mode 100644 index a9bb9a41..00000000 --- a/docs/docs/user-guide/create-a-document.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Create a Document - -Documents are **groups of pages** connected through: - -- a **sidebar** -- **previous/next navigation** -- **versioning** - -## Create your first Doc - -Create a markdown file at `docs/hello.md`: - -```md title="docs/hello.md" -# Hello - -This is my **first Docusaurus document**! -``` - -A new document is now available at `http://localhost:3000/docs/hello`. - -## Configure the Sidebar - -Docusaurus automatically **creates a sidebar** from the `docs` folder. - -Add metadata to customize the sidebar label and position: - -```md title="docs/hello.md" {1-4} ---- -sidebar_label: 'Hi!' -sidebar_position: 3 ---- - -# Hello - -This is my **first Docusaurus document**! -``` - -It is also possible to create your sidebar explicitly in `sidebars.js`: - -```js title="sidebars.js" -module.exports = { - tutorialSidebar: [ - { - type: 'category', - label: 'Tutorial', - // highlight-next-line - items: ['hello'], - }, - ], -}; -``` diff --git a/docs/docs/user-guide/create-a-page.md b/docs/docs/user-guide/create-a-page.md deleted file mode 100644 index e112b005..00000000 --- a/docs/docs/user-guide/create-a-page.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Create a Page - -Add **Markdown or React** files to `src/pages` to create a **standalone page**: - -- `src/pages/index.js` -> `localhost:3000/` -- `src/pages/foo.md` -> `localhost:3000/foo` -- `src/pages/foo/bar.js` -> `localhost:3000/foo/bar` - -## Create your first React Page - -Create a file at `src/pages/my-react-page.js`: - -```jsx title="src/pages/my-react-page.js" -import React from 'react'; -import Layout from '@theme/Layout'; - -export default function MyReactPage() { - return ( - -

My React page

-

This is a React page

- - ); -} -``` - -A new page is now available at `http://localhost:3000/my-react-page`. - -## Create your first Markdown Page - -Create a file at `src/pages/my-markdown-page.md`: - -```mdx title="src/pages/my-markdown-page.md" -# My Markdown page - -This is a Markdown page -``` - -A new page is now available at `http://localhost:3000/my-markdown-page`. diff --git a/docs/docs/user-guide/deploy-your-site.md b/docs/docs/user-guide/deploy-your-site.md deleted file mode 100644 index 492eae02..00000000 --- a/docs/docs/user-guide/deploy-your-site.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -sidebar_position: 5 ---- - -# Deploy your site - -Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**). - -It builds your site as simple **static HTML, JavaScript and CSS files**. - -## Build your site - -Build your site **for production**: - -```bash -npm run build -``` - -The static files are generated in the `build` folder. - -## Deploy your site - -Test your production build locally: - -```bash -npm run serve -``` - -The `build` folder is now served at `http://localhost:3000/`. - -You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**). diff --git a/docs/docs/user-guide/dynamic-batcher/_category_.json b/docs/docs/user-guide/dynamic-batcher/_category_.json new file mode 100644 index 00000000..f6f6c7c8 --- /dev/null +++ b/docs/docs/user-guide/dynamic-batcher/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "动态合图", + "position": 2, + "collapsed": true, + "link": { + "type": "doc", + "id": "dynamic-batcher-intro" + } +} diff --git a/docs/docs/user-guide/dynamic-batcher/dynamic-batcher-intro.mdx b/docs/docs/user-guide/dynamic-batcher/dynamic-batcher-intro.mdx new file mode 100644 index 00000000..ec6ebcf8 --- /dev/null +++ b/docs/docs/user-guide/dynamic-batcher/dynamic-batcher-intro.mdx @@ -0,0 +1,23 @@ +--- +hide_title: true +title: 动态合图 +--- +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + +我们基本重构了动态合图系统，在原有的功能基础上，增加了以下重要特性： + +- **完全开放所有接口**，以方便如果你想手动规划或控制动态图集 +- **增加默认是否参与动态合图的全局设置，并支持设置单个组件是否参与动态合图** +- **支持自动加入多纹理合批** +- **优化图集装箱算法**（使用 Guillotine） +- **支持复用废弃的空间** +- **所有图集作为一个整体进行管理**（不再出现纹理被加入到两张图集的情况） + +:::tip 提示 + +你可以阅读官方文档来了解怎么使用 [动态合图](https://docs.cocos.com/creator/2.4/manual/zh/advanced-topics/dynamic-atlas.html)，由于动态合图的使用本来就是自动的，所以如果没有特殊需求则**不需要阅读后面的内容**。 + +::: + + diff --git a/docs/docs/user-guide/dynamic-batcher/dynamic-batcher-manual.md b/docs/docs/user-guide/dynamic-batcher/dynamic-batcher-manual.md new file mode 100644 index 00000000..16025b99 --- /dev/null +++ b/docs/docs/user-guide/dynamic-batcher/dynamic-batcher-manual.md @@ -0,0 +1,25 @@ +--- +sidebar_position: 2 +--- + +# 手动管理合图 + +我们在保留原来所有接口的基础上重构了动态合图，除了通过 `maxFrameSize` `insertSpriteFrame` 等原有的接口来手动管理合图之外，还新增了以下方法： + +## 控制图集 + +### 添加 SpriteFrame + +你可以通过该接口添加 SpriteFrame 的 Texture 到图集中，内部也是使用该接口。 + +``` +cc.dynamicAtlasManager.insertSpriteFrame(spriteFrame); +``` + +### 删除 SpriteFrame + +`cc.dynamicAtlasManager.deleteSpriteFrame(spriteFrame)` + +### 删除 Texture + +`cc.dynamicAtlasManager.deleteTexture(texture)` diff --git a/docs/docs/user-guide/dynamic-batcher/dynamic-batcher-settings.md b/docs/docs/user-guide/dynamic-batcher/dynamic-batcher-settings.md new file mode 100644 index 00000000..17e575b0 --- /dev/null +++ b/docs/docs/user-guide/dynamic-batcher/dynamic-batcher-settings.md @@ -0,0 +1,49 @@ +--- +sidebar_position: 1 +--- + +# 新增的合图设置 + +## 全局设置 + +### 是否参与动态合图 + +`cc.sp.allowDynamicAtlas` + +控制所有组件默认情况下是否会参与动态合图，默认为开启状态。 + +### 自动多纹理合批 + +`cc.dynamicAtlasManager.autoMultiBatch` + +控制图集纹理是否会自动添加到多纹理合批管理器，默认为开启状态，如果关闭也就**失去了自动进行多个图集纹理合批的特性**（当然关闭后你依然可以手动添加）。 + +### 在场景切换时清空所有图集 + +`cc.dynamicAtlasManager.autoResetBeforeSceneLoad` + +控制在场景切换时是否会清空所有的动态图集，默认为开启状态。 + +:::tip 提示 + +在引擎原来的设计中，该机制不可被关闭，由于旧动态合图不支持复用废弃的空间，图集终究会被用完，所以引擎加入了这个治标不治本的功能。 + +但现在，我们认为该机制可以关闭，你只需要管理好纹理资源的释放即可，纹理资源释放的同时会释放使用的动态图集空间。 + +::: + +## 组件的单独设置 + +### 是否参与动态合图 + +`cc.Component.allowDynamicAtlas` + +控制该组件是否会参与动态合图，类型是 `cc.RenderComponent.EnableType` 枚举，默认为 `GLOBAL`。 + +:::tip cc.RenderComponent.EnableType + +- `GLOBAL` 使用全局设置 +- `ENABLE` 开启 +- `DISABLE` 关闭 + +::: diff --git a/docs/docs/user-guide/markdown-features.mdx b/docs/docs/user-guide/markdown-features.mdx deleted file mode 100644 index 6b3aaaaa..00000000 --- a/docs/docs/user-guide/markdown-features.mdx +++ /dev/null @@ -1,146 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Markdown Features - -Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**. - -## Front Matter - -Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/): - -```text title="my-doc.md" -// highlight-start ---- -id: my-doc-id -title: My document title -description: My document description -slug: /my-custom-url ---- -// highlight-end - -## Markdown heading - -Markdown text with [links](./hello.md) -``` - -## Links - -Regular Markdown links are supported, using url paths or relative file paths. - -```md -Let's see how to [Create a page](/create-a-page). -``` - -```md -Let's see how to [Create a page](./create-a-page.md). -``` - -**Result:** Let's see how to [Create a page](./create-a-page.md). - -## Images - -Regular Markdown images are supported. - -You can use absolute paths to reference images in the static directory (`static/img/docusaurus.png`): - -```md -![Docusaurus logo](/img/docusaurus.png) -``` - -![Docusaurus logo](/img/docusaurus.png) - -You can reference images relative to the current file as well, as shown in [the extra guides](../tutorial-extras/manage-docs-versions.md). - -## Code Blocks - -Markdown code blocks are supported with Syntax highlighting. - - ```jsx title="src/components/HelloDocusaurus.js" - function HelloDocusaurus() { - return ( -

Hello, Docusaurus!

- ) - } - ``` - -```jsx title="src/components/HelloDocusaurus.js" -function HelloDocusaurus() { - return

Hello, Docusaurus!

; -} -``` - -## Admonitions - -Docusaurus has a special syntax to create admonitions and callouts: - - :::tip My tip - - Use this awesome feature option - - ::: - - :::danger Take care - - This action is dangerous - - ::: - -:::tip My tip - -Use this awesome feature option - -::: - -:::danger Take care - -This action is dangerous - -::: - -## MDX and React Components - -[MDX](https://mdxjs.com/) can make your documentation more **interactive** and allows using any **React components inside Markdown**: - -```jsx -export const Highlight = ({children, color}) => ( - { - alert(`You clicked the color ${color} with label ${children}`) - }}> - {children} - -); - -This is Docusaurus green ! - -This is Facebook blue ! -``` - -export const Highlight = ({children, color}) => ( - { - alert(`You clicked the color ${color} with label ${children}`); - }}> - {children} - -); - -This is Docusaurus green ! - -This is Facebook blue ! diff --git a/docs/docs/user-guide/multi-render/_category_.json b/docs/docs/user-guide/multi-render/_category_.json new file mode 100644 index 00000000..3582acce --- /dev/null +++ b/docs/docs/user-guide/multi-render/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "多纹理渲染", + "position": 1, + "collapsed": true, + "link": { + "type": "doc", + "id": "multi-render-intro" + } +} diff --git a/docs/docs/user-guide/multi-render/multi-material.md b/docs/docs/user-guide/multi-render/multi-material.md new file mode 100644 index 00000000..ad91a3f2 --- /dev/null +++ b/docs/docs/user-guide/multi-render/multi-material.md @@ -0,0 +1,6 @@ +--- +sidebar_position: 1 +--- + +# 多纹理材质 + diff --git a/docs/docs/user-guide/multi-render/multi-render-intro.mdx b/docs/docs/user-guide/multi-render/multi-render-intro.mdx new file mode 100644 index 00000000..4fdc2bc5 --- /dev/null +++ b/docs/docs/user-guide/multi-render/multi-render-intro.mdx @@ -0,0 +1,34 @@ +--- +hide_title: true +title: 多纹理渲染 +--- +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + +我们在引擎中**内置两种多纹理 Effect 着色器资源**（分别是 8 纹理插槽与 16 纹理插槽）。 + +并增加**原生支持多纹理材质**的能力，也就是说你无需编写任何代码即可在支持的渲染组件中直接使用多纹理材质。 + +:::info 支持的渲染组件 + +cc.Sprite、cc.Label、cc.RichText、cc.MotionSteak、Spine 组件。 + +::: + +:::caution 不支持的渲染组件 + +cc.ParticleSystem 与 TiledMap 组件，这两个组件引擎的实现会强制打断合批，所以暂不支持。 + +cc.Label 使用 TTF 字体文件并使用 Char 缓存模式时，引擎内部会使用原生实现的 TTF 渲染器，由于该原生渲染器可以禁用，并且可能导致不同平台渲染效果不一致的问题，所以结合我们的人力较少的原因，暂未去进行适配，服务包会默认禁用，在实际使用上没有差别，但欢迎提交 PR 帮助我们适配该渲染器。 + +::: + +在这个基础上，我们增加了一个**多纹理合批管理器**，一般情况下你并不会接触到它，但是它是我们开发**动态合图的自动多纹理合批**的基础。 + +:::tip 无需关注 + +**如果你并不是要（一般情况下也不需要）手动使用多纹理材质或者多纹理合批管理器，请跳过本节文档**，阅读其它内容。 + +::: + + diff --git a/docs/docs/user-guide/user-guide-intro.mdx b/docs/docs/user-guide/user-guide-intro.mdx new file mode 100644 index 00000000..9a994a14 --- /dev/null +++ b/docs/docs/user-guide/user-guide-intro.mdx @@ -0,0 +1,14 @@ +--- +hide_title: true +title: 使用指南 +--- +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + +:::caution 注意 + +在几乎所有平台上引擎都是使用 WebGL 渲染模式，所以服务包的大部分特性都未支持引擎的 Canvas 渲染模式，部分特性在 3D 节点下不生效。 + +::: + + diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx index d5828d26..f31f6380 100644 --- a/docs/src/pages/index.tsx +++ b/docs/src/pages/index.tsx @@ -20,23 +20,23 @@ function HomepageHeader() {

2D 渲染 - 支持多纹理材质，新增多纹理合批管理器与静态合批组件 + 支持多纹理渲染（多纹理材质、多纹理合批） +

+

+ 2D 渲染 + 支持高 DPI 文本渲染

动态图集 - 完全重构，进行了多方面提升，并支持自动多纹理合批 + 完全重构，支持自动多纹理合批、优化算法、复用废弃空间等特性

Label 组件 - 支持高 DPI 渲染，BITMAP 与 CHAR 缓存模式的实用性提升 -

-

- RichText 组件 - 支持使用自定义材质 + 重构 Char 缓存模式，支持自动多纹理合批、多图集、复用废弃空间等特性

Spine 组件 - 支持 Region 换装，支持参与动态合图 + 支持与其它组件合批、合入动态图集与 SpriteFrame 换装

@@ -72,7 +72,7 @@ export default function Home(): JSX.Element { description="Description will go into a meta tag in ">
- + {/* */}
);