本文介绍的插件 duktape-unity 可以使你在 Unity3D 中使用 javascript/typescript 来写脚本. 这里说的脚本是指可以在包括iOS上动态执行的脚本. 目前主流的选择是 lua 和 ILRuntime(C#), 都是很成熟的方案. typescript 或许可以是介于两者之间的一种选择, 即有动态脚本语言的特性, 又有强类型的辅助.
概况
duktape-unity 的使用方法与 slua/ulua 等是类似的, 通过生成绑定代码并对部分值类型进行特定优化来提高交互效率. 并针对 js 的使用习惯, 做了一些 js 风格的封装, 例如事件/委托的封装, 有两种方式在 js 中将 js 函数注册到 C# 事件/委托上 (这里均以 ts 为例):
// 方法一, 直接注册 js 函数
UnityEngine.Application.lowMemory.on(() => {
console.log("low memory");
});
// 方法二, 构造一个 Delegate 对象进行注册, 这种方式 Delegate 对象本身就是一个 Dispatcher, 可以自己再 on/off 多个响应者
let delegate = new DuktapeJS.Delegate0();
delegate.on(this, () => {
console.log("low memory")
});
delegate.on(this, () => {
// ...
});
UnityEngine.Application.lowMemory.on(delegate);
而且, 得益于自动生成的 d.ts 声明的帮助, 写脚本时是有类型验证的.
集成
Assets/Duktape 是插件主要代码, 直接放到工程目录（可以是子目录）中即可. Assets/DuktapeExtra 是插件辅助代码, 可选, 目前主要作用是将 js stacktrack 转换到 typescript stacktrack, 在调试过程中有较大帮助.
接着, 在项目根目录编辑生成绑定代码的配置文件 ./duktape.json：
{
"outDir": "Assets/Generated", // 生成csharp绑定代码的目录
"typescriptDir": "Assets/Generated", // 生成 d.ts 声明的目录
// rootpath of ts/js project
"workspace": "",
"logPath": "Temp/duktape.log", // 生成csharp绑定代码过程中产生的日志文件
// auto, cr, lf, crlf
"newLineStyle": "auto", // 生成代码的换行符
// 隐式生成 （在下列模块中定义的类型中未明确禁止生成的类都将生成绑定）
"implicitAssemblies": [
"UnityEngine",
"UnityEngine.CoreModule",
"UnityEngine.UI",
"UnityEngine.UIModule",
"UnityEngine.TextRenderingModule",
"UnityEngine.AnimationModule"
],
// 显式生成 （在下列模块中定义的类型必须明确指定需要生成绑定的类型）
"explicitAssemblies": [
"Assembly-CSharp"
],
// 禁止生成绑定的类型全名前缀
"typePrefixBlacklist": [
"JetBrains.",
"Unity.Collections.",
"Unity.Jobs.",
"Unity.Profiling.",
"UnityEditor.",
"UnityEditorInternal.",
"UnityEngineInternal.",
"UnityEditor.Experimental.",
"UnityEngine.Experimental.",
"Unity.IO.LowLevel.",
"Unity.Burst.",
// more types ...
"UnityEngine.Assertions."
],
// 生成绑定代码所在的命名空间
"ns": "DuktapeJS",
// 生成的绑定代码中使用的缩进符
"tab": " "
}
然后执行菜单 Duktape/Generate Bindings 生成绑定代码.
generate_bindings.png
编写 C# 调用 js 的启动代码:
// Launcher.cs
public class Launcher : MonoBehaviour, IDuktapeListener
{
public bool debuggerSupport;
public string entryScript = "main";
private DuktapeVM _vm;
public void OnBinded(DuktapeVM vm, int numRegs) { }
public void OnBindingError(DuktapeVM vm, Type type) { }
public void OnProgress(DuktapeVM vm, int step, int total) { }
public void OnTypesBinding(DuktapeVM vm) { }
public void OnLoaded(DuktapeVM vm)
{
_vm.AddSearchPath("Assets/Scripts/out");
if (debuggerSupport)
{
DuktapeDebugger.CreateDebugger(_vm);
}
_vm.EvalMain(entryScript);
}
void Awake()
{
_vm = new DuktapeVM();
_vm.Initialize(this);
}
}
接着, 就可以开始愉快的用 typescript 写脚本了. 上一步生成绑定代码时, 会自动生成 C# 类对应的 d.ts 申明文件, 因此写脚本的体验接近 C#, 定义跳转/引用查询/重命名等功能一应俱全.
// main.ts
import { MyBridge } from "./app";
console.log("hello, world!");
(function () {
let go = new UnityEngine.GameObject("_jsgo");
let bridge = go.AddComponent(DuktapeJS.Bridge);
bridge.SetBridge(new MyBridge());
})();
完成 ts 脚本的编写, 用 tsc 编译出 js 结果就可以运行了. 这步可以利用 tsc watch 实时监听脚本的修改并自动完成编译, 增量编译的速度极快, 几乎无感.
tsc_watch.png
运行项目, 就可以看到脚本中调用 console.log 产生的日志输出:
console_log.png
调试
到这, 经常用日志调试法调试的伙伴们要崩溃了, 这日志根本看不出来是从哪一行代码产生的啊, 这可怎么调试. 有办法, 只需要在脚本中调用
enableStacktrace(true);
那么所有脚本产生的日志输出就会自动带上脚本调用栈. 如图所示:
console_log_with_stacktrace.png
当然日志调试法不是万能的, 更多时候还是需要进行断点调试. 首先在代码中调用
DuktapeDebugger.CreateDebugger(vm) 即可启动调试服务.
在 vscode 端需要安装插件 Duktape Debugger (HaroldBrenes), vscode 插件管理器中目前版本为 0.5.6, 可以用于 js 脚本的调试, 对 ts 存在一些bug, 可以使用笔者修改过的版本 duk-debug-0.5.6.vsix 在插件管理器中手工安装即可.
在 vscode 中正确配置 launch.json 后, 即可进行远程调试. 首先要启动游戏, 然后启动 Attach 调试, 调试是可以反复多次的, 游戏运行过程中仍然可以再次 Attach.
addbreakpoint_and_launch.png
命中断点后, 就可以安逸查看各个变量值的情况了.
breakpoint.png
有一点需要注意的, 因为脚本是在主线程执行的, 所以调试过程在没有打开 Run in background 选项的情况下可能无法流畅进行, 建议开启该选项再进行断点调试.
run_in_background.png
基于 duktape-unity 在 Unity 项目中使用 typescript 作为脚本的基本流程就是这样. 代码在这里:
https://github.com/ialex32x/duktape-framework
上述代码 Unity 2018.3.5+可以运行, 更低版本没有测试过.
后续有时间会继续更新代码, 演示 websocket, protobuf, 热更新, 界面框架等的使用方法.
目前项目还不成熟, 如果您对使用 typescript/javascript 写脚本感兴趣, 不妨尝试一下, 给个星星. 有问题建议, 欢迎拍砖, issue. 期待您的关注 :)
网友评论