【文档】一些建议或者意见

[llint]

说说我的看法：

首先，对于PuerTS的思想我非常认同，代码质量还没有来得及没有仔细看，仅仅从使用者的角度提一些意见。

1. PuerTS的文档对于初次使用者非常的不友好，现有的文档里面并没有从使用者的角度基于几种典型的用例一步一步的引导；现有文档安装部分还行，但是使用手册只讲了一些功能性和实现方面的问题，完全没有从用户的角度，怎样从零开始使用PuerTS，就算有一些，也是零散的分布在文档和demo的说明中 - 从使用的易用性来讲，PuerTS相比UnLua还是有比较大的差距

2. 比如使用C++代码创建JS虚拟机，是否是使用PuerTS唯一的方式？但是从 https://github.com/chexiongsheng/BlockBreakerStarter/ 这个示例看来其实可以不用手动创建虚拟机；然而，这个示例的说明也非常的晦涩，比如这个示例包括官方文档本身也没有说明，TypeScript目录下的TS_xxx.ts文件们和Content/Blueprints/TypeScript下的TS_xxx.uasset资源的对应方式 - 基于我自己的测试，这些资源应该是基于TS_xxx.ts文件自动生成的（我在本地删除了对应的BP - TS_xxx.uasset，重新打开编辑器，这些资源会自动生成）；然而，这些生成的蓝图的EventGraph又是可以编辑的 - 而没有任何文档说明如果对生成的蓝图进行编辑会造成什么样的影响 - 以UnLua的思维模式，一个蓝图会显示的绑定到一个Lua脚本，Lua脚本里面可以override蓝图里面的方法（当然不能在蓝图生成新的变量等等，这个是PuerTS的黑魔法），而PuerTS里面生成的蓝图资源和原始的ts脚本并没有一个非常明确的对应关系 - 目前的感觉是生成的蓝图和原始的ts脚本是有对应关系的 - 是通过Content/Blueprints/TypeScript/TS_xxx.uasset这个路径来对应根目录下的TypeScript/TS_xxx.ts文件的吗（或者是Content/Javascript/TS_xxx.js对应的）？文档里面无从得知。我试验过将TS_Player.uasset蓝图里面的EventBeginPlay节点删掉，发现脚本里面相应的ReceiveBeginPlay的逻辑不会再被调用 - 但是，但是，既然这个蓝图是基于TS/JS脚本生成的，那么这个蓝图的逻辑就不应该被修改，否则任何人都可以开始修改这个蓝图，最终导致脚本和蓝图不同步 - 这个现在看来是一个比较大的问题。

该方案适合C++调用ts脚本，类似于UnLua里面的脚本覆盖蓝图方法来实现将逻辑无缝的切换到脚本使用 - 当然目前看来从ts脚本里面调用UE的方法这个方式是支持得比较完善的

3. 上面的是使用用例之一（无论其本身的问题 - 如果有问题，那么文档也应该清晰的标明）；然后就是我看到的实例里面的第二个用例：手动创建虚拟机，然后直接加载一个ts文件，执行里面的逻辑，主要在： https://github.com/chexiongsheng/puerts_unreal_demo 详细的就不多说了，在示例的说明里面，总是看得到“怎么跑这个demo”，然后blahblah的描述一番，好像我只要能跑这个demo就行了，但是根本没有描述，比如他的使用场景是什么，比如自己创建JsEnv并且加载一个脚本的使用场景是什么 - 就是文档有意无意的忽略了一些重要的细节，说了很多功能，但是有省略掉了很多 - 就好像一切都应该是不言自明的 - 不要忘记，作为PuerTS开发者，你的开发环境，上下文很多东西对于用户来讲都是不知道的 - 你一个demo扔出来，说明文档里面只有怎么跑是完全不够的 - 使用者根本没有你的上下文，很多东西是怎么来的根本不清楚 - 可以学习一下国外的软件是怎么写step by step guide的。

4. 现在已经是UE5的时代了，而所有的示例还是基于UE4，虽然可以自己本地做一些修改，但是官方应该做一个UE5的分支，降低使用者的门槛

上面举的例子不是要作者来这里解答我的疑问，而重点是你的文档写得真的很不好 - 而实际使用体验也并没有非常丝滑 - 并不是你的文档或者说明里面描述得这么轻松（对，你的文档里面透露出一种举重若轻的轻松的感觉，觉得一切都很简单，你拿着跑就行了，其实实际情况不是这样的）

写了这么多，也是因为对puerts还是抱着期望的，希望作者能够采纳我的意见（我承认有点吐槽，因为使用下来的感受确实不太好），希望你们越做越好

[WenzhiShao]

2333作者说，我兼职写个东西，你们要求还挺多，笑死。

[chexiongsheng]

https://github.com/Tencent/puerts/issues/1781