ammo.js

演示

概述

示例代码让你了解API:

https://github.com/kripken/ammo.js/blob/master/examples/webgl_demo/worker.js#L6 与 https://github.com/kripken/ammo.js/blob/master/examples/webgl_demo/ammo.html#L14 交互

ammo.js 是使用 Emscripten 将 Bullet 物理引擎直接移植到 JavaScript 的结果。源代码直接翻译成 JavaScript，无需人工重写，因此功能应与原始 Bullet 完全相同。

'ammo' 代表 "通过编译 C++ 的 bullet 来避免自己制作 js 物理引擎"；)

ammo.js 采用 zlib 许可证，与 Bullet 一样。

讨论在 Mozilla 服务器 (irc.mozilla.org) 的 #emscripten IRC 频道进行。

使用说明

builds/ammo.js 包含一个预构建版本的 ammo.js。这可能是你想要的。

你也可以自己构建 ammo.js。

用法

最直接的方法是如果你想用 C++ 编写代码，并在网络上运行。如果是这样，你可以使用 emscripten 正常构建你的 C++ 代码，并使用

https://emscripten.org/docs/compiling/Building-Projects.html

来构建和链接 Bullet，或者你可以直接从 emscripten-ports 使用 Bullet，使用 -s USE_BULLET=1。在这两种情况下，你不需要 ammo.js，只需要纯 Bullet。

另一方面，如果你想用 JavaScript 编写代码，你可以使用 ammo.js 中自动生成的绑定代码。完整示例见

examples/hello_world.js

这是从 Bullet 翻译成 JavaScript 的 HelloWorld.cpp。该目录中的其他示例也可能有用。特别是查看 WebGL 演示代码

examples/webgl_demo/ammo.html

绑定 API

ammo.js 从 Bullet 源代码自动生成其 API，所以基本上应该是相同的。但是有一些区别和需要注意的事项：

参见 https://github.com/kripken/emscripten/wiki/WebIDL-Binder 了解我们在这里使用的绑定工具的描述，其中包括如何使用包装对象的说明。
所有 ammo.js 元素都应通过 Ammo.* 访问。例如， Ammo.btVector3 等，如示例代码所示。
结构体和类的成员变量可以通过带有 |get_| 或 |set_| 前缀的 setter 和 getter 函数访问。例如，

rayCallback.get_m_rayToWorld()

将从 ClosestRayResultCallback 获取 m_rayToWorld。原生 JavaScript getters 和 setters 可以提供稍微更好的 API，但它们的性能可能有问题。
返回或获取 float& 或 btScalar& 的函数被转换为 float。原因是 float& 基本上是语法更好的 float* 在 C++ 中，但从 JavaScript 中你需要每次调用这样的函数时都写入堆，使用起来非常丑陋。有了这个改变，你可以做 |new btVector3(5, 6, 7)|，它会按预期工作。如果你发现需要 float& 方法的情况，请提交问题。
并非所有类都被暴露，因为只有 ammo.idl 中描述的内容被包装。请提交包含你需要的额外内容的拉取请求并添加。
有对绑定操作符函数的实验性支持。以下可能有效：

操作符 JS 中的名称
= op_set
+ op_add
- op_sub
* op_mul
/ op_div
[] op_get
== op_eq

操作符	JS 中的名称
`=`	`op_set`
`+`	`op_add`
`-`	`op_sub`
`*`	`op_mul`
`/`	`op_div`
`[]`	`op_get`
`==`	`op_eq`

构建

要自己构建 ammo.js，你需要 Emscripten 和 cmake。有关设置Emscripten的更多信息，请参阅入门指南。

要配置并将ammo构建到builds目录中，请运行以下命令：

$ cmake -B builds
$ cmake --build builds

在cmake配置过程中还可以指定一些关键选项，例如：

$ cmake -B builds -DCLOSURE=1                # 使用closure编译
$ cmake -B builds -DTOTAL_MEMORY=268435456   # 分配256MB堆内存
$ cmake -B builds -DALLOW_MEMORY_GROWTH=1    # 启用可调整大小的堆

在Windows上，你可以使用cmake的mingw生成器进行构建：

> cmake -B builds -G 'MinGW Makefiles'
> cmake --build builds

请注意，如果你没有通过emsdk安装emscripten，可以使用-DEMSCRIPTEN_ROOT配置其位置。

使用Docker构建

ammo.js也可以使用Docker构建。这提供了许多优势（保持本地环境清洁、可移植性等）。要做到这一点，你只需安装Docker并运行：

$ docker-compose build        # 创建Docker镜像
$ docker-compose up           # 创建Docker容器并构建ammo.js
$ docker-compose run builder  # 在任何修改后重新构建ammojs目标

如果你想向cmake添加参数，需要编辑docker-compose.yml文件。

减小构建大小

可以通过以下几种方式减小ammo.js构建的大小：

从ammo.idl中移除不需要的接口。一些很好的例子是btIDebugDraw和DebugDrawer，这两个只有在需要可视化调试渲染时才需要。
从make.py中的-s EXPORTED_RUNTIME_METHODS=[]参数中移除方法。例如，只有在需要从DebugDrawer获取可打印的错误消息时才需要UTF8ToString。

测试

你可以使用npm test运行自动测试，这将使用ava对JavaScript和WebAssembly构建进行测试：

$ npm run test-js      # --> AMMO_PATH=builds/ammo.js ava
$ npm run test-wasm    # --> AMMO_PATH=builds/ammo.wasm.js ava

也可以直接运行ava以获得更多选项：

$ npx ava --verbose
$ npx ava --node-arguments inspect

当未定义AMMO_PATH时，默认测试builds/ammo.js。

运行示例

http-server作为开发依赖项包含在内，是运行示例的简单方法。确保从仓库根目录提供所有内容，以便示例能够在builds目录中找到ammo：

$ npx http-server -p 3000 .

故障排除

创建对象时很容易忘记写|new|，例如：

var vec = Ammo.btVector3(1,2,3); // 这是错误的！需要'new'！

这可能导致如下错误消息：

Cannot read property 'a' of undefined Cannot read property 'ptr' of undefined

这是JavaScript令人烦恼的一个方面，很遗憾。

报告问题

如果你在ammo.js中发现bug并提交问题，请包含一个能重现问题的脚本。这样更容易调试，我们也可以将该脚本包含在我们的自动测试中。

发布流程

只有在完成以下步骤后，才应将新构建推送到builds/ammo.js：

启用closure配置：cmake -B builds -DCLOSURE=1
构建asm.js和wasm库：cmake --build builds
确保它们通过所有自动测试：npm test
运行examples/webgl_demo中的WebGL演示，确保它看起来正常，使用类似firefox examples/webgl_demo/ammo.html的命令（Chrome需要一个Web服务器，因为它不喜欢file://的URL）