UNPKG

5.24 kBMarkdownView Raw
1ammo.js
2=======
3
4
5**Demo: http://kripken.github.com/ammo.js/examples/new/ammo.html**
6
7**Example code to give you an idea of the API: https://github.com/kripken/ammo.js/blob/master/examples/webgl_demo/ammo.html#L14**
8
9ammo.js is a direct port of the [Bullet physics engine](http://bulletphysics.org/) to JavaScript, using Emscripten. The source code is translated directly to JavaScript, without human rewriting, so functionality should be identical to the original Bullet.
10
11**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**
12
13'ammo' stands for "Avoided Making My Own js physics engine by compiling bullet from C++" ;)
14
15ammo.js is zlib licensed, just like Bullet.
16
17Discussion takes place on IRC at #emscripten on Mozilla's server (irc.mozilla.org)
18
19
20Instructions
21------------
22
23`builds/ammo.js` contains a prebuilt version of ammo.js. This is probably what you want.
24
25You can also build ammo.js yourself, as follows:
26
27 * Get Emscripten
28
29 http://emscripten.org
30
31 and set it up. See
32
33 https://github.com/kripken/emscripten/wiki/Getting-started
34
35 * Run the build script,
36
37 `python make.py`
38
39 which should generate builds/ammo.js.
40
41 * Optionally, run the automatic tests,
42
43 `python test.py`
44
45
46Usage
47-----
48
49The most straightforward thing is if you want to write your code in C++, and
50run that on the web. If so, then compile your code into LLVM, link it with
51bullet, and compile that to JavaScript using emscripten. (The easiest way to
52link it is to add your .bc file to the llvm-link command in make.py.)
53
54If, on the other hand, you want to write code in JavaScript, you can use the
55autogenerated binding code. A complete example appears in
56
57 `examples/hello_world.js`
58
59That is HelloWorld.cpp from Bullet, translated to JavaScript. Other examples
60in that directory might be useful as well. In particular see the WebGL
61demo code in
62
63 `examples/webgl_demo/ammo.html`
64
65
66Bindings API
67============
68
69ammo.js autogenerates its API from the Bullet source code, so it should
70be basically identical. There are however some differences and things
71to be aware of:
72
73 * See https://github.com/kripken/emscripten/wiki/WebIDL-Binder
74 for a description of the bindings tool we use here, which includes
75 instructions for how to use the wrapped objects.
76
77 * All ammo.js elements should be accessed through `Ammo.*`. For example,
78 `Ammo.btVector3`, etc., as you can see in the example code.
79
80 * Member variables of structs and classes can be accessed through
81 setter and getter functions, that are prefixed with `|get_|` or `|set_|`.
82 For example,
83
84 `rayCallback.get_m_rayToWorld()`
85
86 will get `m_rayToWorld` from say a `ClosestRayResultCallback`. Native
87 JavaScript getters and setters could give a slightly nicer API here,
88 however their performance is potentially problematic.
89
90 * Functions returning or getting `float&` or `btScalar&` are converted to
91 float. The reason is that `float&` is basically `float*` with nicer syntax
92 in C++, but from JavaScript you would need to write to the heap every
93 time you call such a function, making usage very ugly. With this change,
94 you can do `|new btVector3(5, 6, 7)|` and it will work as expected. If
95 you find a case where you need the float& method, please file an issue.
96
97 * Not all classes are exposed, as only what is described in ammo.idl is
98 wrapped. Please submit pull requests with extra stuff that you need
99 and add.
100
101 * There is experimental support for binding operator functions. The following
102 might work:
103
104 | Operator | Name in JS |
105 |---|---|
106 | `=` | `op_set` |
107 | `+` | `op_add` |
108 | `-` | `op_sub` |
109 | `*` | `op_mul` |
110 | `/` | `op_div` |
111 | `[]` | `op_get` |
112 | `==` | `op_eq` |
113
114
115Troubleshooting
116===============
117
118 * It's easy to forget to write |new| when creating an object, for
119 example
120
121 `var vec = Ammo.btVector3(1,2,3); // This is wrong! Need 'new'!`
122
123 This can lead to error messages like the following:
124
125 `Cannot read property 'a' of undefined`
126 `Cannot read property 'ptr' of undefined`
127
128 This is an annoying aspect of JavaScript, sadly.
129
130
131Reporting Issues
132================
133
134If you find a bug in ammo.js and file an issue, please include a script
135that reproduces the problem. That way it is easier to debug, and we can
136then include that script in our automatic tests.
137
138
139Release Process
140===============
141
142Pushing a new build in `builds/ammo.js` should be done only after the
143following steps:
144
145 * Build a safe build and make sure it passes all automatic tests. Safe
146 builds contain a lot of runtime assertions that can catch potential
147 bugs (similar to the sort of things valgrind can catch).
148
149 * Build a fast build and make sure it passes all automatic tests.
150
151 * Run closure compiler on that fast build and make sure it passes
152 all automatic tests.
153
154 * Make sure that the stress test benchmark did not regress
155 compared to the old build.
156
157 * Run the WebGL demo in examples/webgl_demo and make sure it looks
158 ok.
159
160
161Upstream Version
162================
163
164Bullet 2.82
165