@01/ammo.js 中文文档教程
ammo.js
Demos
Overview
让您了解 API 的示例代码：
- https://github.com/kripken/ammo.js/blob/master/examples/webgldemo/worker.js#L6 which interacts with https://github.com/kripken/ammo.js/blob/master/examples/webgldemo/ammo.html#L14
ammo.js 是 Bullet physics 的直接端口 engine 到 JavaScript，使用 Emscripten。 来源 代码直接翻译成 JavaScript，无需人工重写，因此 功能应与原始 Bullet 相同。
注意：ammo.js 刚刚更新为一种新的移植方法。 如果你发现 您需要的不支持的 Bullet API 的某些部分，请参阅 https://github.com/kripken/ammo.js/issues/60
'ammo' 代表“通过编译子弹避免制作我自己的 js 物理引擎” 来自 C++" ;)
ammo.js 是 zlib 许可的，就像 Bullet 一样。
讨论在 Mozilla 服务器上的#emscripten 上的 IRC 上进行 (irc.mozilla.org)
Instructions
builds/ammo.js 包含 ammo.js 的预构建版本。 这可能就是你想要的。
您也可以自己构建 ammo.js，如下所示：
获取 Emscripten
http://emscripten.org
并进行设置。 请参阅
http://kripken.github.io/emscripten-site/docs/getting_started/
运行构建脚本，
python make.py应该生成 builds/ammo.js。
可选地，运行自动测试，
python test.py
Usage
最直接的事情是如果你想用 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 的 HelloWorld.cpp，翻译成 JavaScript。 其他例子 在该目录中也可能有用。 特别是看到 WebGL 中的演示代码
examples/webgl_demo/ammo.html
Bindings API
ammo.js 从 Bullet 源代码自动生成其 API，因此它应该 基本相同。 然而，有一些差异和事情 要注意：
参见 https://github.com/kripken/emscripten/wiki/WebIDL-Binder 有关我们在此处使用的绑定工具的说明，其中包括 有关如何使用包装对象的说明。
应通过
Ammo.*访问所有 ammo.js 元素。 例如，Ammo.btVector3等，如您在示例代码中所见。可以通过访问结构和类的成员变量 setter 和 getter 函数，以
|get_|或|set_|为前缀。 例如，rayCallback.get_m_rayToWorld()将从
ClosestRayResultCallback获取m_rayToWorld。 本国的 JavaScript getters 和 setters 可以在这里提供稍微好一点的 API， 然而，它们的性能可能存在问题。返回或获取
float&或btScalar&的函数被转换为 漂浮。 原因是float&基本上是语法更好的float*在 C++ 中，但在 JavaScript 中，您需要每隔 当你调用这样的函数时，使用起来非常难看。 有了这个改变， 你可以执行|new btVector3(5, 6, 7)|它会按预期工作。 如果 您会发现需要 float& 的情况 方法，请提出问题。并非所有类都公开，因为只有 ammo.idl 中描述的是 包裹。 请提交带有您需要的额外内容的拉取请求 并添加。
有对绑定运算符函数的实验性支持。 下列 可能有效：
Operator Name in JS =op_set+op_add-op_sub*op_mul/op_div[]op_get==op_eq
Reducing Build Size
可以通过多种方式减少 ammo.js 构建的大小：
从 ammo.idl 中删除不需要的接口。
btIDebugDraw和DebugDrawer是这方面的一些很好的例子，只有在需要可视化调试渲染时才需要它们。从 make.py 中的
-s EXPORTED_RUNTIME_METHODS=[]参数中删除方法。 例如，UTF8ToString仅在需要从DebugDrawer中打印错误消息时才需要。
Troubleshooting
很容易忘记写 |new| 创建对象时，对于 示例
var vec = Ammo.btVector3(1,2,3); // 这是错误的！ 需要“新”！这可能会导致如下错误消息：
无法读取未定义的属性“a”Cannot read property 'ptr' of undefined遗憾的是，这是 JavaScript 的一个令人讨厌的方面。
Reporting Issues
如果您在 ammo.js 中发现错误并提出问题，请包含一个脚本 重现问题。 这样更容易调试，我们可以 然后将该脚本包含在我们的自动测试中。
Release Process
在 builds/ammo.js 中推送新构建应该只在 以下步骤：
使用生成 asm.js 的 python make.py 闭包构建 build, 和 python make.py 闭包 wasm 生成 wasm 建造。
确保它通过所有自动测试使用 python test.py (build-name) 注意使用的是SpiderMonkey 默认情况下，SPIDERMONKEY_ENGINE 定义在 ~/.emscripten 中， 有关详细信息，请参阅脚本内容。
在 examples/webgldemo 中运行 WebGL 演示并确保它看起来像 好的，使用类似 firefox examples/webgldemo/ammo.html 的东西 （chrome 需要一个网络服务器，因为它不喜欢 file:// urls）
Upstream Version
Bullet 2.82 使用 来自 2.83 的光线投射修复
ammo.js
Demos
Overview
Example code to give you an idea of the API:
- https://github.com/kripken/ammo.js/blob/master/examples/webgldemo/worker.js#L6 which interacts with https://github.com/kripken/ammo.js/blob/master/examples/webgldemo/ammo.html#L14
ammo.js is a direct port of the Bullet physics engine to JavaScript, using Emscripten. The source code is translated directly to JavaScript, without human rewriting, so functionality should be identical to the original Bullet.
Note: ammo.js has just been updated to a new porting approach. If you find some part of the Bullet API that is not supported that you need, please see https://github.com/kripken/ammo.js/issues/60
'ammo' stands for "Avoided Making My Own js physics engine by compiling bullet from C++" ;)
ammo.js is zlib licensed, just like Bullet.
Discussion takes place on IRC at #emscripten on Mozilla's server (irc.mozilla.org)
Instructions
builds/ammo.js contains a prebuilt version of ammo.js. This is probably what you want.
You can also build ammo.js yourself, as follows:
Get Emscripten
http://emscripten.org
and set it up. See
http://kripken.github.io/emscripten-site/docs/getting_started/
Run the build script,
python make.pywhich should generate builds/ammo.js.
Optionally, run the automatic tests,
python test.py
Usage
The most straightforward thing is if you want to write your code in C++, and run that on the web. If so, then you can build your C++ code with emscripten normally and either build and link Bullet using
https://emscripten.org/docs/compiling/Building-Projects.html
or you can use Bullet directly from emscripten-ports, with -s USE_BULLET=1. In both cases, you don't need ammo.js, just plain Bullet.
If, on the other hand, you want to write code in JavaScript, you can use the autogenerated binding code in ammo.js. A complete example appears in
examples/hello_world.js
That is HelloWorld.cpp from Bullet, translated to JavaScript. Other examples in that directory might be useful as well. In particular see the WebGL demo code in
examples/webgl_demo/ammo.html
Bindings API
ammo.js autogenerates its API from the Bullet source code, so it should be basically identical. There are however some differences and things to be aware of:
See https://github.com/kripken/emscripten/wiki/WebIDL-Binder for a description of the bindings tool we use here, which includes instructions for how to use the wrapped objects.
All ammo.js elements should be accessed through
Ammo.*. For example,Ammo.btVector3, etc., as you can see in the example code.Member variables of structs and classes can be accessed through setter and getter functions, that are prefixed with
|get_|or|set_|. For example,rayCallback.get_m_rayToWorld()will get
m_rayToWorldfrom say aClosestRayResultCallback. Native JavaScript getters and setters could give a slightly nicer API here, however their performance is potentially problematic.Functions returning or getting
float&orbtScalar&are converted to float. The reason is thatfloat&is basicallyfloat*with nicer syntax in C++, but from JavaScript you would need to write to the heap every time you call such a function, making usage very ugly. With this change, you can do|new btVector3(5, 6, 7)|and it will work as expected. If you find a case where you need the float& method, please file an issue.Not all classes are exposed, as only what is described in ammo.idl is wrapped. Please submit pull requests with extra stuff that you need and add.
There is experimental support for binding operator functions. The following might work:
Operator Name in JS =op_set+op_add-op_sub*op_mul/op_div[]op_get==op_eq
Reducing Build Size
The size of the ammo.js builds can be reduced in several ways:
Removing uneeded interfaces from ammo.idl. Some good examples of this are
btIDebugDrawandDebugDrawer, which are both only needed if visual debug rendering is desired.Removing methods from the
-s EXPORTED_RUNTIME_METHODS=[]argument in make.py. For example,UTF8ToStringis only needed if printable error messages are desired fromDebugDrawer.
Troubleshooting
It's easy to forget to write |new| when creating an object, for example
var vec = Ammo.btVector3(1,2,3); // This is wrong! Need 'new'!This can lead to error messages like the following:
Cannot read property 'a' of undefinedCannot read property 'ptr' of undefinedThis is an annoying aspect of JavaScript, sadly.
Reporting Issues
If you find a bug in ammo.js and file an issue, please include a script that reproduces the problem. That way it is easier to debug, and we can then include that script in our automatic tests.
Release Process
Pushing a new build in builds/ammo.js should be done only after the following steps:
Build using python make.py closure which generates the asm.js build, and python make.py closure wasm which generates the wasm build.
Make sure it passes all automatic tests using python test.py (build-name) Note that it uses SpiderMonkey by default, and SPIDERMONKEY_ENGINE is defined in ~/.emscripten, see the script contents for details.
Run the WebGL demo in examples/webgldemo and make sure it looks ok, using something like firefox examples/webgldemo/ammo.html (chrome will need a webserver as it doesn't like file:// urls)
Upstream Version
Bullet 2.82 patched with raycast fix from 2.83
