[建议] 不要让用户感知到 JSB 的存在

[Geequlim]

建议将GDScript提供的全局变量、全局函数、以及JS绑定添加的功能都通过 godot 模块对外暴露

import { signal, seconds } from "jsb.core";

• 这种写法明显感觉到割裂，让人觉得JS并非 godot 支持的，而是通过外挂支持的。
• 给开发者带来不必要的心智负担，我需要的功能应该从哪个模块引入？
• 应当只提对外提供唯一个模块 godot

[ialex32x]

十分感谢大佬提议🤝.
godot-jsb 这个模块是内部模块, 其中遗留了 callable 和 to_array_buffer 这两个对外暴露的函数, 确实应该直接合并到 godot 模块中去更合适一些.

提供分离的 jsb.core 的初衷是覆盖 GDScript 语言层面独有的部分 (主要是 annotation, seconds 除外, 这个其实是多余的, 应由用户自行实现), 以及 GDScript 没有提供的极少量常用功能 (例如模仿C++宏的 GLOBAL_GET 等, 这部分实际也可以由用户自行实现). 没有全放进 godot 模块主要是几方面原因:

• 不是 godot 原生等价物, 可能产生命名/行为冲突 (出现breaking changes时已应用的项目调整起来会相对隐蔽和麻烦一些, 而选择隔离的话兼容工作可以在 jsb.core 中完成)
• C++层面会相对变得有侵入性一些, 需要做额外的非 godot 原生逻辑
• 依赖 VSCode 等工具, 大部分情况只需要知道名字, 不需要手工引入模块名

我再考虑考虑, 看能不能在已暴露部分不产生 breaking changes 的情况下尽量将常用部分融合到 godot 模块中去.

[Geequlim]

我看了一下你的使用文档，这边给到以下建议

1. 不应让用户感知到 callable 的存在，而是在C++绑定层实现转换。

class MyClass extends Node {
   
   handle_onclick = (index: number) => {
        console.log('on click event')
   }

    foo() {
        // subscribe
        this.onclick.connect(this.handle_onclick, 0);

        // unsubscribe
        this.onclick.disconnect(this.handle_onclick);
    }
}

2. 关于 Packed Array 类型，不建议对 PackedByteArray 自动转换为 ArrayBuffer 因为引擎内部有COW优化，会导致我们通过引擎提供的api操作二进制数据时会多很多拷贝操作。只需要提供从ArrayBuffer构造这类数据和将这类数据生成ArrayBuffer的接口即可满足开发者的需求。

• 增加构造函数重载 constructor(buffer: ArrayBuffer) 实现 ArrayBuffer 到 PackedArray 转换
• 增加 buffer 属性 get buffer() 或 to_array_buffer(): ArrayBuffer 方法，实现 PackedArray 到 ArrayBuffer 转换

const buffer = new ArrayBuffer();
... // 使用 js 的 api 操作 buffer

const bytes = new PackedByteArray(buffer); // 将准备好的数据给引擎使用

... // 使用引擎的 api操作 bytes

// 将操作结果拿出来给js使用
const ret = bytes.to_array_buffer();
// 或者
const ret = bytes.buffer;

3. 关于 signal 这块好像 4.0 是有较多改变的，我没有看最新的实现代码。从开发者（使用者）的角度，更希望他们是原生的 js 函数，或ts的模板类。

readonly login_confirm: Signal<string, string>; // 登陆传递用户名和密码, 通过TS实现约定类型让IDE检查传入的回调函数参数类型是否匹配

...

const handler = this.login_confirm.connect((name: string, password: string)=>{
    // 处理登陆逻辑
});

...

this.login_confirm.disconnect(handler)

[ialex32x]

1 的问题个人觉得两种方式各有优缺点, 隐藏细节之后需要介入绑定重载(带this, 和不带this两种情况, 以及原生的 callable 参数的情况), 耦合dts生成逻辑也会更深一些. 我先按照建议的方式尝试.

2 可能文档没表达清楚, 并不存在 ArrayBuffer 与 PackedByteArray 的双向自动转换, 只是为了使用者便利, 在使用者强行将 JS ArrayBuffer 传参给 接受 PackedByteArray 参数的函数时, 提供可选的自动转换, 反方向是没有自动转换的, 需要明确调用 to_array_buffer. 也就是这里的转换辅助仅仅是方便原本 JS 生态与 godot 接口交互, 并不妨碍用户只使用 PackedByteArray 或者只使用ArrayBuffer. 目前, to_array_buffer 已采纳建议, 直接作为 PackedByteArray 的成员函数进行绑定导出, 原 free function 的方式已标记为 deprecated 若干版本后将被移除.

3 这个目前是做了ts声明优化的, 类似于您提到的 code snippet, 在 GodotJS 中, signal 是可以按强类型声明的, connect/disconnect, 以及被注册的方法, 都是支持参数类型检查的 (当然, 该检查仅仅是 ts 编译器检查, 并非真实存在的强类型)