更新文档，更新英文文档，翻译更地道

focus-creative-games · Apr 12, 2024 · 6ba8f30 · 6ba8f30
1 parent 0b47d92
commit 6ba8f30
Show file tree

Hide file tree

Showing 30 changed files with 602 additions and 397 deletions.
diff --git a/docs/business/basicoptimization.md b/docs/business/basicoptimization.md
@@ -1,12 +1,28 @@
-# 解释执行优化
+# 标准解释优化
 
-目前仅可使用标准解释执行优化技术，[离线指令优化](./advancedoptimization)技术还在开发中。
+:::tip
 
-## 标准指令优化技术
+标准解释优化技术仅在商业化版本上可用。
 
-标准指令优化技术为运行时优化技术。对常见的代码范式进行谨慎可靠的优化，大幅提升了变量访问、数值计算、对象访问等常见指令的性能，像一些特殊代码如typeof指令的性能，提升了1000%以上。
+:::
+
+标准解释优化使用多种技术大幅提升了解释执行的性能，基础指令（如变量访问、数值计算）受益极大。
+
+以数值计算指令为例，使用标准解释优化技术后性能有了质的飞跃，是原来的**280%-735%**！像一些特殊代码如typeof指令的性能，提升了1000%以上。
+
+
+## 实现
+
+标准解释优化使用了以下技术提升了解释性能。
+
+- 指令分发优化
+- 指令合并
+- 无用指令消除
+- 特殊instinct指令
+
+
+## 性能报告
 
-**商业版**大幅提升了数值计算性能，其性能是社区版本的 **280%-735%**。
 
 以下是OnePlus 9R ArmV8 实机测试报告，测试代码附录最后。
 
@@ -32,3 +48,19 @@ AOT版本性能是社区版本的`4.1 - 90`倍，是商业化版本的`1.30 - 12
 AOT版本性能是是商业化版本的`1.30 - 12.9`倍。
 
 ![data](/img/benchmark/numeric_dialog_business_div_aot.jpg)
+
+
+## 开启和关闭标准指令优化
+
+默认已经**开启**标准优化，此设置为全局设置，对所有程序集包括补充元数据程序集都生效。
+
+可以通过 `RuntimeApi.EnableTransformOptimization`函数主动开启或者关闭这个特性。
+
+```csharp
+
+    /// 禁用标准指令优化
+    void DisableCodeOptimization()
+    {
+        RuntimeApi.EnbleTransformOptimization(false);
+    }
+```
diff --git a/docs/business/differentialhybridexecution.md b/docs/business/differentialhybridexecution.md
@@ -23,10 +23,10 @@ DHE只包含在**旗舰版**中，具体请见[旗舰版介绍](../business/ulti
 
 ## 未支持特性
 
-- 加载DHE热更新代码前不能执行DHE对应的AOT assembly中的任何代码。意味着DHE不支持像mscorlib这种基础库的差分混合，但支持传统热更新assembly的差分热更新。
-- 由于第一条的限制，不支持在DHE程序集中使用`[InitializeOnLoadMethod]`、`Script Execution Order settings`。
-- 不支持DHE脚本挂载在随包资源中，包括Resources。（这条限制将来会放松或者去掉）
-- 不能在DHE程序集中通过热更新新增extern函数。
+- 加载DHE热更新代码前不能执行DHE对应的AOT assembly中的任何代码。意味着DHE不支持像mscorlib这种基础库的差分混合，但支持传统热更新assembly的差分热更新
+- 由于第一条的限制，不支持在DHE程序集中使用`[InitializeOnLoadMethod]`、`Script Execution Order settings`
+- 不支持DHE脚本挂载在随包资源中，包括Resources
+- 不能在DHE程序集中通过热更新新增extern函数
 
 ## dhao文件
 

diff --git a/docs/business/dots.md b/docs/business/dots.md
@@ -1,5 +1,10 @@
 # DOTS支持
 
+:::tip
+
+**商业化客户需要联系我们获取com.unity.entities package代码**，替换项目中对应的package。
+
+:::
 
 商业化版本修改了DOTS运行时代码及hybridclr运行时代码，支持绝大多数DOTS特性。
 

diff --git a/docs/business/fullgenericsharing.md b/docs/business/fullgenericsharing.md
@@ -4,7 +4,7 @@
 加载补充元数据不仅导致内存占用明显增加，还增加了启动时间。对于微信小游戏这些对包体和内存要求严苛的场合，这是一个影响较大的问题。
 另外，被补充的泛型函数以解释方式执行，还降低了运行性能。
 
-HybridCLR支持`full genric sharing`后，不再需要补充元数据，简化了工作流，以原生方式运行AOT泛型，性能大幅提升，彻底解决了补充元数据的以上缺点。
+HybridCLR支持`full genric sharing`后，不再需要补充元数据，简化了工作流，较好地解决了补充元数据的以上缺点。
 
 ## 支持的版本
 
@@ -18,8 +18,14 @@ HybridCLR支持`full genric sharing`后，不再需要补充元数据，简化
 
 ## 设置
 
-- 2021.3.x LTS版本。当Build Settings中`Il2Cpp Code Generation`选项为为 `faster(smaller) build` 时开启
-`full generic sharing` 机制。启用此选项后，泛型函数的所有泛型实例（无论泛型参数是值类型还是class类型）完全共享一份代码。
-- 2022.3.x LTS版本。强制支持`full generic sharing`，即使Build Settings中使用`faster runtime`选项也会开启此机制。与`faster(smaller) build`区别
-在于：`faster runtime`对于AOT中已经实例化的泛型函数，会使用单独的泛型函数实现，不走完全泛型共享的版本，提升了泛型函数的执行性能；
-`faster(smaller) build`选项则迫使同个函数的所有泛型函数都使用一份代码，此时与2021版本的含义相同。
+:::warning
+
+ `faster (smaller build)`会对泛型函数性能有较大影响（15%甚至更高），因此建议不要开启这个选项。
+
+ 如果是2021版本并且没有内存压力的情况下，建议仍然使用补充元技术来解决泛型问题。
+
+:::
+
+- 2020版本不支持完全泛型共享
+- 2021版本需要设置 IL2CPP Code Generation选项为`faster(smaller build)`
+- 2022版本默认开启完全泛型共享，无法关闭。如果设置 IL2CPP Code Generation选项为`faster(smaller build)`则能进一步减少包体。
diff --git a/docs/business/intro.md b/docs/business/intro.md
@@ -27,7 +27,8 @@
 |[完全泛型共享](./fullgenericsharing)||✔|✔|✔|
 |[DOTS](./dots)||✔|✔|✔|
 |[元数据优化](./metadataoptimization.md)||✔|✔|✔|
-|[解释性能优化](./basicoptimization)||✔|✔|✔|
+|[标准解释性能优化](./basicoptimization)||✔|✔|✔|
+|[离线指令优化](./advancedoptimization)||✔|✔|✔|
 |[代码加固](./basicencryption)||✔|✔|✔|
 |[热重载](./reload/hotreloadassembly)||||✔|
 |[访问控制机制](./accesspolicy)||||✔|

diff --git a/docs/business/pro/intro.md b/docs/business/pro/intro.md
@@ -1,17 +1,16 @@
 # 介绍
 
-专业版本提供了一些社区版本所不支持的高级特性，适合对内存和包体要求较高或者有**一定性能压力**的场合，如WebGL游戏。
-
-## 支持的版本
-
-支持所有 Unity 2019-2022 LTS版本。
+专业版提供了一些社区版本所不支持的高级特性，适合对内存和包体要求较高或者有**一定性能压力**的场合，如WebGL游戏。
 
 ## 优势
 
-- 支持Unity 2021起的il2cpp的`full generic sharing`技术，值类型也可以泛型共享了，以原生方式执行AOT泛型函数，极大提升了泛型函数的执行性能。不再需要对AOT进行补充元数据，简化了工作流，并且有效降低包体大小，明显降低了内存占用。对WebGL等包体和内存要求严苛的平台尤其有用
-- 优化加载及运行过程中元数据分配，内存占用更小
-- **包含标准指令优化**。对常见的代码范式进行谨慎可靠的优化，大幅提升了变量访问（50%-100%）、数值计算（100-300%）、对象访问（50-200%）等常见指令的性能，像一些特殊代码如typeof指令的性能，提升了1000%以上
-- 支持标准代码加固。对IL指令进行预处理，使其无法被ILSpy这样的反编译工具直接破解
-- 更敏捷的维护支持，随时获得最新的代码（社区版本出于维护成本考虑，只会定期发布版本）
+- 支持[完全泛型共享](../fullgenericsharing)技术，不再需要补充元数据了
+- 包含[元数据优化](../metadataoptimization)技术，显著优化了元数据内存
+- 包含 **[标准解释优化](../basicencryption)**，极大提升了解释性能。以数值计算指令为例，使用标准解释优化技术后性能有了质的飞跃，是原来的**280%-735%**！像一些特殊代码如typeof指令的性能，提升了1000%以上。
+- 支持代码加密，更安全
+- 支持[DOTS](../dots)技术
+- 包含一年技术支持
 
+## 支持的版本
 
+支持所有 Unity 2019-2022 LTS版本。
diff --git a/docs/business/pro/quickstart.md b/docs/business/pro/quickstart.md
@@ -12,14 +12,11 @@
 
 ![installer](/img/hybridclr/ultimate-installer.jpg)
 
-## 开启完全泛型共享
-
-- 2020版本不支持完全泛型共享
-- 2021版本需要设置 IL2CPP Code Generation选项为`faster(smaller)`
-- 2022版本默认开启完全泛型共享，无法关闭。如果设置 IL2CPP Code Generation选项为`faster(smaller)`则能进一步减少包体。
-
-## 开启和关闭标准指令优化
-
-默认已经开启标准优化。可以通过 `RuntimeApi.EnableTransformOptimization`函数主动控制开启或者关闭这个特性。
+## 使用
 
+- 开启完全泛型共享参见 [完全泛型共享](../fullgenericsharing)
+- 代码加密参见 [代码加固](../basicencryption)
+- 元数据优化参见 [元数据优化](../metadataoptimization)
+- DOTS使用参见 [DOTS](../dots)
+- 其他用法与社区版本完全相同
 
diff --git a/docs/business/reload/hotreloadassembly.md b/docs/business/reload/hotreloadassembly.md
@@ -26,4 +26,20 @@
 - 2022的Jobs会缓存类型相关信息，需要自行小幅[修改UnityEngine.CoreModule.dll](./modifydll.md)的代码。 低于2022的版本不需要修改
 - LitJson之类的反序列化库会缓存反射信息，需要在热重载后清理掉库中缓存的反射信息，具体操作跟库的实现相关
 
+## 解决被卸载对象的引用问题
+
+热重载技术要求在未卸载的程序集或者全局内存中不能持有已卸载的程序集U的元数据。包括但不限于：
+
+- 被卸载程序集的类型的实例
+- 泛型类或者函数的泛型参数中包含被卸载程序集的类型
+- 被卸载程序集相关的反射信息，如Assembly、Type、MethodInfo、PropertyInfo等等
+- 指向被卸载程序集中某函数的delegate
+- 被卸载程序集中定义的异步Task
+- 其他
+
+实际工程可能很复杂，开发者找出所有非法引用是很困难和不切实际的。我们已经实现了非法引用检查，在调用`RuntimeApi.UnloadAssembly`时
+会打印出所有非法引用的日志。开发者根据打印的日志清除所有非法引用即可。
+
+由于非法引用检查会遍历所有存活对象，比较耗时，因此只在Il2Cpp编译选项为Debug时开启了此检查，而Release模式下关闭了检查。可以使用
+`RuntimeApi.EnableLiveObjectValidation(true)`强行在Release编译模式下开启这个检查。
 
diff --git a/docs/business/reload/intro.md b/docs/business/reload/intro.md
@@ -2,16 +2,14 @@
 
 热重载特别版提供独创的`热重载技术`的支持。可以运行中完全卸载或者重新加载一个assembly，尤其适用于小游戏合集类型的游戏。
 
-## 支持的版本
+## 优势
 
-支持所有 Unity 2019-2022 LTS版本。
+- 包含[专业版](../pro/intro)的所有功能
+- 支持[热重载技术](./hotreloadassembly)
+- 支持[访问控制机制](../accesspolicy)，**限定热更新assembly中能访问的函数的集合**。适合UGC游戏中创建沙盒环境，避免恶意玩家代码造成破坏。
+- 包含两年技术支持
 
-## 优势
 
-- 包含专业版的所有功能
-- 支持卸载单独的assembly，卸载100%以上内存
-- 支持重新加载assembly，支持MonoBehaviour及ScriptableObject的热重载。
-- **TODO**。支持**限定热更新assembly中能访问的函数的集合**，适合UGC游戏中创建沙盒环境，避免恶意玩家代码造成破坏。
-- 更敏捷的维护支持，随时获得最新的代码（社区版本出于维护成本考虑，只会定期发布版本）。
-- 附含两年的技术支持，快速解决使用过程中遇到的各种问题
+## 支持的版本
 
+支持所有 Unity 2019-2022 LTS版本。
diff --git a/docs/business/reload/quickstart.md b/docs/business/reload/quickstart.md
@@ -9,20 +9,9 @@
 - 解压 `hybridclr.zip`
 - 将`hybridclr.zip`解压后的hybridclr目录放到`il2cpp-{version}.zip`解压后的libil2cpp目录下
 - 打开 `HybridCLR/Installer`，开启`从本地复制libil2cpp`选项，选中刚才解压的libil2cpp目录，进行安装
-- **Unity 2022+版本需要使用修改版本的 UnityEngine.CoreModule.dll**, 详细见[修改dll](modifydll.md)
 
 ![installer](/img/hybridclr/ultimate-installer.jpg)
 
-## 开启完全泛型共享
-
-- 2020版本不支持完全泛型共享
-- 2021版本需要设置 IL2CPP Code Generation选项为`faster(smaller)`
-- 2022版本默认开启完全泛型共享，无法关闭。如果设置 IL2CPP Code Generation选项为`faster(smaller)`则能进一步减少包体。
-
-
-## 开启和关闭标准指令优化
-
-默认已经开启标准优化。可以通过 `RuntimeApi.EnableTransformOptimization`函数主动控制开启或者关闭这个特性。
 
 ## 代码中使用
 
@@ -54,4 +43,5 @@
 
 - async或者协程很容易隐式地在其他线程保持了对卸载程序集代码的引用，卸载前请务必清理所有异步或者协程函数
 - UI的OnClick或者各种回调事件很容易导致保持了对卸载程序集的引用，一定要清理干净
-- 注册到全局的事件或者其他加高，容易意外保持了对卸载程序集的引用，一定要清理干净
+- 注册到全局的事件或者其他加高，容易意外保持了对卸载程序集的引用，一定要清理干净
+- 根据`RuntimeApi.UnloadAssembly`中打印的非法引用的日志，清理掉代码中的非法引用
diff --git a/docs/business/ultimate/freetrial.md b/docs/business/ultimate/freetrial.md
@@ -12,7 +12,7 @@
 
 ## 支持的版本
 
-只支持以下特定的Unity版本。邻近的小版本如果在构建时没有出现编译错误则**也可使用**。
+只支持以下特定的Unity版本。
 
 - ~~2019.4.40f1~~ 待支持
 - ~~2020.3.48f1~~ 待支持 

diff --git a/docs/business/ultimate/intro.md b/docs/business/ultimate/intro.md
@@ -8,30 +8,17 @@
 
 ## 优势
 
-- 包含独创的 [Differential Hybrid Execution(DHE)](../differentialhybridexecution) 技术，未变化部分代码性能与原生完全相同，相较社区版本纯解释方式提升惊人的**3-30**倍甚至更高，整体**几乎达到**原生性能水平
-- 支持Unity 2021起的il2cpp的`full generic sharing`技术，值类型也可以泛型共享了，以原生方式执行AOT泛型函数，极大提升了泛型函数的执行性能。不再需要对AOT进行补充元数据，简化了工作流，并且有效降低包体大小，明显降低了内存占用。对WebGL等包体和内存要求严苛的平台尤其有用
-- 支持标准指令优化。对常见的代码范式进行谨慎可靠的优化，大幅提升了变量访问（50%-100%）、数值计算（100-300%）、对象访问（50-200%）等常见指令的性能，像一些特殊代码如typeof指令的性能，提升了1000%以上
-- 支持标准代码加固。进行多重加密，使dll无法被ILSpy这样的工具反编译
-- 优化了元数据分配，占用内存更少
-- 提前将原始IL指令转换为寄存器指令，天然抗反编译破解，更安全
-- 优化加载及运行过程中元数据分配，更节省内存
-- 更敏捷的维护支持，随时获得最新的代码（社区版本出于维护成本考虑，只会定期发布版本）
-- 原生代码已全部在包体中，被各大AppStore拒审的风险大幅降低
-- 附含两年的技术支持，快速解决使用过程中遇到的各种问题
+- 包含[专业版](../pro/intro)的所有功能
+- 包含独创的 [DHE](../differentialhybridexecution) 技术，未变化部分代码性能与原生完全相同，相较社区版本纯解释方式提升惊人的**3-30**倍甚至更高，整体**几乎达到**原生性能水平
+- 含两年的技术支持
 
 
-## 实践效果
+## 可预测的效果
 
-:::tip
 DHE技术的效果是可预测的。不需要实际运行DHE也可以基本知道最终效果。
-:::
 
-没有发生热更新前，性能与原生完全相同。发生热更新后，以函数为粒度，变化的函数变成以解释方式执行，并且可以自由选择
-使用无优化或`标准指令优化`或`高级指令优化`的方式去执行它们。生成dhao文件时，也会将所有变化函数打印出来。DHE的效果
-是可提前观测的。
-
-以接入的某个非常火的SLG游戏为例：在重度战斗的场景下，原生帧率为44；接入社区版本后，帧率降到20多；接入DHE后，未热更新前，帧率甚至略高于原生（测试波动引起）；
-接入DHE并且做了一定改动热更新后，帧率降到42。这与理论估计是完全相符的。
+没有发生热更新前，性能与原生完全相同。发生热更新后，以函数为粒度，变化的函数变成以解释方式执行。生成dhao文件时，也会将所有变化函数打印出来。
+因此开发者可以提前估计热更新行为影响了哪些函数的性能。
 
 
 ## 与injectfix之类方案的区别