教TS/JS小白学习Puerts(一)——把Puerts集成到Unity工程里

• 作者自己的博客原文
• 使用Puerts需要用到的JS/TS/Node.js知识
  • ts和js的关系：Puerts说简单点就是一个在c#运行时执行的js运行环境。ts是js的扩展语法，而且ts并不能直接执行（暂时不能），实际执行的其实是由ts生成的js代码。typescript中文官方学习资料
  • Node.js：Node.js是一个电脑命令行环境下执行js的运行环境，在我理解Node.js和js语言的关系类似于.net和c#的关系。为了将ts生成为js，你需要在开发电脑上安装Node.js。Node.js中文网地址。下载长期支持版即可。
  • npm包管理器：npm全名Node Package Manager，安装完Node.js之后电脑中就有npm命令了。npm install命令可以从npm网站上下载并安装常用的js依赖包。npm run命令可以执行在package.json中配置快捷命令。npm命令官方文档 package.json官方文档
• 先写一个Hello World

  • Puerts运行原理是在运行时将js文件的内容作为字符串传给JsEnv对象。所以我们应将ts文件存放在Unity工程的Assets文件夹以外，以避免Unity为ts生成.meta，而将ts生成的js文件生成在Assets文件夹内，以供Unity运行时加载。

  • 我们先在Assets文件夹的同级创建一个TsProj文件夹，在命令行中运行cd到这个文件夹，并运行npm init命令，并一直回车到命令运行结束，这会创建一个package.json文件。
    
    

  • 接下来安装依赖，运行命令npm install typescript @types/node webpack-cli，这会创建一个node_modules文件夹，里面存放着typescript，@types/node，webpack-cli这三个依赖包以及他们各自的依赖包，其中typescript依赖包中包含一个tsc可执行文件，即是将ts生成js的命令文件。其他依赖包稍后用到再解释。此时打开package.json，会看到里面多了dependencies字段，里面罗列了刚刚安装的依赖包和版本信息。
    
    另外同级还会出现一个自动生成的package-lock.json文件，这个文件是用于锁定本次安装所有依赖包的具体版本号，必须保留。如果使用git，也必须一同提交。

  • 下一步我们手动创建一个名为tsconfig.json的文本文件，其中书写如下内容

    {
        "compilerOptions": {
            "target": "esnext",
            "module": "CommonJS",
            "sourceMap": true,
            "noImplicitAny": true,
            "typeRoots": [
                "node_modules/@types"
            ],
            "moduleResolution": "node",
            "outDir": "../Assets/Resources"
        }
    }
    

    这个文件会告诉tsc命令如何生成js文件，如outDir指定了生成路径等等。tsconfig.json官方中文文档
    这里我们把js文件的生成路径选在Assets/Resources文件夹，这是为了在本文例子中方便Unity加载到代码，实际项目中我们为了热更新，更多时候把js代码生成在Assets/StreamingAssets或其他位置等待打包成AssetBundle，这个我将在后面文章中详细说明。

  • 然后我们手动编辑一下package.json文件，在scripts字段中加入如下内容

    ...
    "scripts": {
        "dev": "tsc --watch",
        "build": "tsc"
    },
    ...
    

    这里的dev和build就是定义了两个npm run快捷指令。比如当你命令行中，在TsProj文件夹下运行npm run dev，即等同于运行tsc --watch，即使你的电脑系统全局环境中不存在tsc这个命令，npm也会自动去当前文件夹的node_modules/.bin文件夹下去寻找tsc可执行文件。
    而这个tsc --watch命令的作用即是把当前文件夹下的所有ts文件按照tsconfig.json中指定的规则生成为js文件。--watch的意思是实时监控当前文件夹的文件变化，并立刻重新生成变化的文件。这个机制就非常适合写代码的时候开启，边写边生成，实时生效。这也是为什么我们使用dev这个快捷词来代表这条命令。
    npm build对应的实际命令是tsc，即只生成js而不监听变化。

  • 准备工作就绪，现在可以开始写ts代码了，创建index.cts文件，书写如下内容：

    console.log("hello world");
    

    index这个词在ts/js语言习惯中常用来代表程序的入口

    为什么后缀要用*.cts而非*.ts？
    因为*.ts生成的js文件名是*.js，又因为此范例中使用Puerts的默认Loader只能将js文件生成在Unity的Assets/Resources文件夹下，并使用Resources.Load函数加载文本资源，又因为Resources.Load不能识别后缀为*.js的文本资源。所以使用*.cts生成出来的js文件名是*.cjs，是为了方便Resources.Load函数识别。同时，在Node.js的命名标准中，.cjs代表使用常规js语法编写的js代码，.mjs代表使用新的es6语法编写的模块化js代码。所以使用*.cts/.cjs正好符合标准又符合此处的需要。
    后续文章中我会介绍如何在Puerts中使用自定义loader加载文本资源，那时就可以使用看起来正常一点的.ts和*.js了

  • 下面生成js，在命令行中执行npm run dev，此时命令行窗口进入持续监听状态，所以在后续开发过程中不要关闭这个窗口。如果需要运行其他命令就再开一个新窗口。
    

  • 此时查看Assets/Resources文件夹，应当已经出现了index.cjs文件，和index.cjs.map文件，.map文件是用于记录开发环境下js代码与ts代码中符号和行号映射关系的，一般是程序报错的时候才会用到。

  • ts这边的配置和代码生成工作都完成了，下一步开始回到Unity这边。将Puerts插件引入Unity工程的Assets/Plugins文件夹。我这里使用的是github上直接下载的1.4.0 release的v8版。

  • 在Unity中打开一个空场景，在主相机上挂一个Test.cs脚本作为程序入口，在其中书写如下代码

    using System.Collections;
    using System.Collections.Generic;
    using UnityEngine;
    using Puerts;
    public class Test : MonoBehaviour
    {
        private JsEnv _jsEnv;
        void Start()
        {
            _jsEnv = new JsEnv();
            _jsEnv.ExecuteModule("index.cjs"); 
        }
    }
    

  • 此时查看Unity控制台输出
    

• 下集预告
  Hello world只是验证插件的可行性，想要将Puerts投入到商业项目的开发流程或生产环境中还需要定制很多方面的功能，例如实现ts文本资源的打包和热更新、ts与c#的互调传值、生成提示文件和绑定代码、Inspector面板拖拽赋值等等。下一篇我们从ts和c#互调开始慢慢道来。