Compare commits
719 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 11e53383c7 | |||
| 4c82aabc5d | |||
|
|
93dd64df0f | ||
|
|
6ede4f3d2d | ||
|
|
86c9079d69 | ||
|
|
7791ea1f1b | ||
|
|
9415379691 | ||
|
|
4fc10a7fee | ||
|
|
c96feaccea | ||
|
|
0bba3b2911 | ||
|
|
f6d90c2703 | ||
|
|
83e5f622be | ||
|
|
18a00bdcf6 | ||
|
|
cdbf302d41 | ||
|
|
3b561c1880 | ||
|
|
724e410c8f | ||
|
|
cbec05b7e8 | ||
|
|
9343ffc8ec | ||
|
|
be9b789942 | ||
|
|
3aee543586 | ||
|
|
23e89ec1f7 | ||
|
|
d12d0cc9df | ||
|
|
54cfa2d206 | ||
|
|
37414c7dad | ||
|
|
97e4fcd011 | ||
|
|
75ece37751 | ||
|
|
0dcc98b053 | ||
|
|
e1a271755d | ||
|
|
3446820c88 | ||
|
|
1999deb142 | ||
|
|
02600898af | ||
|
|
ffc8cb316d | ||
|
|
f628eabc36 | ||
|
|
6cfb385214 | ||
|
|
8416d7b516 | ||
|
|
1c50a3f381 | ||
|
|
ce1c486efa | ||
|
|
56193e788c | ||
|
|
bb9bb873fc | ||
|
|
7c400fa896 | ||
|
|
97bb79eb94 | ||
|
|
4b06bb31bd | ||
|
|
f0127f4fe6 | ||
|
|
5b611d70fb | ||
|
|
3b496b846c | ||
|
|
0b31620212 | ||
|
|
922ff97583 | ||
|
|
bee0e1609a | ||
|
|
fe31a9101e | ||
|
|
97b1a8387d | ||
|
|
fbd0021e30 | ||
|
|
50ce8a971a | ||
|
|
bdbac53347 | ||
|
|
a1753d5a1d | ||
|
|
a7a62dddd8 | ||
|
|
cc7fde175f | ||
|
|
e2c850a5d4 | ||
|
|
22541bc6e6 | ||
|
|
9604296ed3 | ||
|
|
c11f0493f6 | ||
|
|
7d09b35cea | ||
|
|
fa2112ffc1 | ||
|
|
3cf402108c | ||
|
|
c08580cd36 | ||
|
|
92ce0d1080 | ||
|
|
71f4e5c286 | ||
|
|
0e58a85d1a | ||
|
|
b4d7ffa0ee | ||
|
|
cbaf2299c4 | ||
|
|
e5048fe80d | ||
|
|
514a34b23f | ||
|
|
d87394b2e4 | ||
|
|
9930e2174d | ||
|
|
a4fbc31180 | ||
|
|
733e30b659 | ||
|
|
b6883d0723 | ||
|
|
0e0bef9c1e | ||
|
|
55a9b170d2 | ||
|
|
50ff5fd0f9 | ||
|
|
4cd1883c2f | ||
|
|
56f0d71814 | ||
|
|
404ebd14e2 | ||
|
|
a9f23fa414 | ||
|
|
9e20146bc5 | ||
|
|
fb79f188fa | ||
|
|
4b6d6ec0ab | ||
|
|
363f566ce3 | ||
|
|
11d3966c1a | ||
|
|
8ef74eca53 | ||
|
|
ca98be96ae | ||
|
|
0d2efe6ae0 | ||
|
|
293c0c6d1d | ||
|
|
fe829184b3 | ||
|
|
09cf743d5e | ||
|
|
3d9286bd81 | ||
|
|
e8e3ff9b3c | ||
|
|
fc913b1f22 | ||
|
|
7caf1509c2 | ||
|
|
f089bb0c66 | ||
|
|
34e256609a | ||
|
|
2b0dd3d0e9 | ||
|
|
4fc3e0325d | ||
|
|
c2c482fd8b | ||
|
|
6de9126f75 | ||
|
|
af22d7c3d1 | ||
|
|
282c3fac45 | ||
|
|
041726a83f | ||
|
|
b205657281 | ||
|
|
3e1f0bc74e | ||
|
|
0a2556722b | ||
|
|
ba52e0c9ff | ||
|
|
eade1934a0 | ||
|
|
1ea2ddd477 | ||
|
|
4de71d9038 | ||
|
|
1bbdadc890 | ||
|
|
dc63010b82 | ||
|
|
4830ce50cf | ||
|
|
3c6390079f | ||
|
|
a714319f6c | ||
|
|
80803cbca4 | ||
|
|
820f6105d7 | ||
|
|
3efc9234ff | ||
|
|
1aa9fb300a | ||
|
|
fcfec569be | ||
|
|
6b3113eb57 | ||
|
|
7f82dc49f3 | ||
|
|
83e71a3339 | ||
|
|
b42b76f4bc | ||
|
|
6ab76c7b21 | ||
|
|
71cb8243bf | ||
|
|
4a54360b54 | ||
|
|
ae249043ed | ||
|
|
f190017c19 | ||
|
|
25074e5ff3 | ||
|
|
2edd8a14ed | ||
|
|
ee8785ff30 | ||
|
|
549e597d11 | ||
|
|
cb7052f1c1 | ||
|
|
57d8126998 | ||
|
|
33eabb680c | ||
|
|
a29feef14f | ||
|
|
cfc9102453 | ||
|
|
9d86ecc65b | ||
|
|
5b96d954b7 | ||
|
|
d43d2c1919 | ||
|
|
e957136800 | ||
|
|
a69b20475a | ||
|
|
a971fb7908 | ||
|
|
ce047fa2e9 | ||
|
|
edd5883795 | ||
|
|
80a5693796 | ||
|
|
48f873e6ea | ||
|
|
c7e93407f5 | ||
|
|
5dafb74b72 | ||
|
|
1d77eb8e90 | ||
|
|
2b297519d9 | ||
|
|
46aea292e5 | ||
|
|
277f60eb13 | ||
|
|
6090cc44a7 | ||
|
|
b7ce8be80e | ||
|
|
9bc1bc03dc | ||
|
|
652eb41563 | ||
|
|
e942302745 | ||
|
|
322bdaf42b | ||
|
|
500bb9c71e | ||
|
|
3aa18f07b6 | ||
|
|
2ca89b0ad2 | ||
|
|
849f0e7f9b | ||
|
|
1a4b19d3ee | ||
|
|
c2877d248c | ||
|
|
0d4e72564a | ||
|
|
a904b1fdb3 | ||
|
|
05352bd7b6 | ||
|
|
bbcdc54da4 | ||
|
|
65eaf4d858 | ||
|
|
c76525ba24 | ||
|
|
5ed20efedb | ||
|
|
09b41946e3 | ||
|
|
bfd859669b | ||
|
|
c7e33ee2d1 | ||
|
|
af01b2921d | ||
|
|
3ccbd84dc4 | ||
|
|
39a983b7c5 | ||
|
|
cbfba8ccc8 | ||
|
|
499075d715 | ||
|
|
c8e7407241 | ||
|
|
f41da62e94 | ||
|
|
836cdb0d5f | ||
|
|
2d69c7727b | ||
|
|
298d7dd6d4 | ||
|
|
9ae39ce602 | ||
|
|
26b6185f95 | ||
|
|
29d2462eb3 | ||
|
|
1702647e06 | ||
|
|
889236ea3c | ||
|
|
361199edae | ||
|
|
04e9f70561 | ||
|
|
83eb157c73 | ||
|
|
83e3e33295 | ||
|
|
3b262124ce | ||
|
|
3fef1b9423 | ||
|
|
8c9c84220c | ||
|
|
0015f7f50e | ||
|
|
158e5eb65c | ||
|
|
8c61838d08 | ||
|
|
22549b433a | ||
|
|
16995c4e4e | ||
|
|
f305373809 | ||
|
|
1229528e05 | ||
|
|
4c759066ea | ||
|
|
94b4d42dc4 | ||
|
|
ac608af813 | ||
|
|
159a3f9c4c | ||
|
|
95e155c282 | ||
|
|
c10131b107 | ||
|
|
35717114ea | ||
|
|
dcb32dd60c | ||
|
|
52bd011de0 | ||
|
|
e12acfe42b | ||
|
|
df092ddfeb | ||
|
|
57b4379809 | ||
|
|
fd16eba95c | ||
|
|
cb32abaff6 | ||
|
|
4604db1dfb | ||
|
|
6d2fb83af3 | ||
|
|
23e8d7b3fc | ||
|
|
a96bb35b8d | ||
|
|
116b5bc6c7 | ||
|
|
b10aace4d7 | ||
|
|
1685b7f367 | ||
|
|
a4b5ce2b11 | ||
|
|
cb9fb5f27a | ||
|
|
cb585d699d | ||
|
|
238fa1e8c1 | ||
|
|
cb9ec02f44 | ||
|
|
97c029dff8 | ||
|
|
01dce1c8f4 | ||
|
|
e12818409a | ||
|
|
d88d1498d5 | ||
|
|
2ddac881d4 | ||
|
|
7fd9c8605e | ||
|
|
59c714c3ca | ||
|
|
b1d7cd786c | ||
|
|
3d92e64398 | ||
|
|
c255e2aa41 | ||
|
|
acc3bd8330 | ||
|
|
00c08cf986 | ||
|
|
25bb24cb04 | ||
|
|
1523746162 | ||
|
|
641bcd930f | ||
|
|
f39e62ec1c | ||
|
|
2597dc1897 | ||
|
|
ba823df7fc | ||
|
|
3f89cb77bc | ||
|
|
d28ef22c51 | ||
|
|
eb47c5c1e4 | ||
|
|
5a917f0bb1 | ||
|
|
a7b3fc766b | ||
|
|
96eb5fb546 | ||
|
|
cc121fb192 | ||
|
|
cc2ddee17a | ||
|
|
9a212b0832 | ||
|
|
8127f05df5 | ||
|
|
357956f66b | ||
|
|
b78eb45745 | ||
|
|
c1149fc65e | ||
|
|
132bda2371 | ||
|
|
1b3d313372 | ||
|
|
c3bc2986f3 | ||
|
|
6a5d3be431 | ||
|
|
3ede11b420 | ||
|
|
2a3930dc0b | ||
|
|
63e787bb7c | ||
|
|
696ed13eef | ||
|
|
cfcb332665 | ||
|
|
3aab68f578 | ||
|
|
bdc1c848d2 | ||
|
|
799dc7326c | ||
|
|
7e469c4d4b | ||
|
|
9b7f55c676 | ||
|
|
2696078864 | ||
|
|
6d0bbc5143 | ||
|
|
8644019fd2 | ||
|
|
fa1988a4a5 | ||
|
|
e7d79dd36d | ||
|
|
a360a037df | ||
|
|
74bc4e8f74 | ||
|
|
4b5d9d79b9 | ||
|
|
d3141c289f | ||
|
|
61b7585bc2 | ||
|
|
ea7accf940 | ||
|
|
6813d89e66 | ||
|
|
d188285ad9 | ||
|
|
67a2978edb | ||
|
|
73978694e2 | ||
|
|
373abafdf5 | ||
|
|
32313e917f | ||
|
|
3ba5d1bda7 | ||
|
|
830815a22b | ||
|
|
3fb115bad9 | ||
|
|
cfee322b90 | ||
|
|
2500d559cf | ||
|
|
ea06f27da2 | ||
|
|
97ac52a6f2 | ||
|
|
e4f52f319e | ||
|
|
02901c554f | ||
|
|
4964479bf2 | ||
|
|
c32a1e228d | ||
|
|
56445ed2e6 | ||
|
|
fc8a1c4eaf | ||
|
|
bf71dd7e5e | ||
|
|
564c486002 | ||
|
|
98cc48f9d8 | ||
|
|
5e476a7abb | ||
|
|
9515e4c72c | ||
|
|
c028854af2 | ||
|
|
f9a12c1879 | ||
|
|
f14921dffb | ||
|
|
1cc26433a0 | ||
|
|
abfd3390ea | ||
|
|
e188b6c5b2 | ||
|
|
86608052ca | ||
|
|
775b338630 | ||
|
|
81614c1600 | ||
|
|
22141d72ec | ||
|
|
6b71ae175d | ||
|
|
ec47900ed8 | ||
|
|
ec1ef8cd99 | ||
|
|
09a54dbd20 | ||
|
|
1064476440 | ||
|
|
c285ddd875 | ||
|
|
5917d6bdfb | ||
|
|
f9b134cf97 | ||
|
|
69ba8b2a89 | ||
|
|
e572856b6a | ||
|
|
32a96540b4 | ||
|
|
4afb814435 | ||
|
|
047cd23a85 | ||
|
|
211b04e2da | ||
|
|
feaa5a6128 | ||
|
|
48de6c1faa | ||
|
|
2e3b2cbf22 | ||
|
|
900191d9da | ||
|
|
3b8b172e40 | ||
|
|
a54383ee8b | ||
|
|
380783dd3f | ||
|
|
9b687ecb6d | ||
|
|
ec0f326856 | ||
|
|
dec239dd02 | ||
|
|
df27e76fa0 | ||
|
|
eb3465b5d2 | ||
|
|
4951c667b7 | ||
|
|
e1cc75327c | ||
|
|
fb058eec8d | ||
|
|
e117b2fd6c | ||
|
|
14dda6d63c | ||
|
|
f90dd8c74a | ||
|
|
bee82201a5 | ||
|
|
016289f614 | ||
|
|
c72e7bde61 | ||
|
|
f63462302b | ||
|
|
152002a8ae | ||
|
|
ed0360436d | ||
|
|
72e4e7ad40 | ||
|
|
19e4dc0d53 | ||
|
|
cff5250417 | ||
|
|
7b07c36dff | ||
|
|
e96af44c8e | ||
|
|
238d47b285 | ||
|
|
8ef09a649f | ||
|
|
4df04f0e36 | ||
|
|
43ddb9d320 | ||
|
|
2dd37b969f | ||
|
|
0199983f58 | ||
|
|
a1d7030f6e | ||
|
|
c5bd8c9571 | ||
|
|
d2b9c86c84 | ||
|
|
0713e6bd4f | ||
|
|
db55b9e20e | ||
|
|
9fc64b8c10 | ||
|
|
c86b574640 | ||
|
|
70aee9feff | ||
|
|
6e9af37223 | ||
|
|
838eba9d8f | ||
|
|
f5777884f5 | ||
|
|
c40d9190d7 | ||
|
|
dadf0629af | ||
|
|
6322496688 | ||
|
|
4b7564b44f | ||
|
|
f82bcf4cee | ||
|
|
8e9e020119 | ||
|
|
6d99866214 | ||
|
|
038d4250bc | ||
|
|
be43ac39b2 | ||
|
|
2a79ae0d55 | ||
|
|
11afb0278c | ||
|
|
8cbb48dfae | ||
|
|
e66588e8c3 | ||
|
|
c879d3aead | ||
|
|
4697668f95 | ||
|
|
9a1fbe4d34 | ||
|
|
9b2a46bed7 | ||
|
|
39a42f0c12 | ||
|
|
046ec8fcd3 | ||
|
|
6a2d470783 | ||
|
|
2f82b369fd | ||
|
|
4d56b067a8 | ||
|
|
f836481831 | ||
|
|
0ae0b81577 | ||
|
|
8e41dbfcba | ||
|
|
840c1cb518 | ||
|
|
cd2eb8789e | ||
|
|
51c4a32fd6 | ||
|
|
cb87a7d819 | ||
|
|
30c613ca88 | ||
|
|
8cf27e4086 | ||
|
|
a16abb792e | ||
|
|
860d974f46 | ||
|
|
6c6a7b2336 | ||
|
|
71b02fb93c | ||
|
|
aa08a1d756 | ||
|
|
f196c29310 | ||
|
|
35874c7c49 | ||
|
|
7f3bccddc6 | ||
|
|
308acbbec8 | ||
|
|
97375ac799 | ||
|
|
1e4de69e7c | ||
|
|
32eddf9a64 | ||
|
|
4adc465210 | ||
|
|
a652ce0b0c | ||
|
|
5cda122a4d | ||
|
|
db284f6275 | ||
|
|
13cb1d8893 | ||
|
|
ca53731cb9 | ||
|
|
00c41f2682 | ||
|
|
c2a64b6287 | ||
|
|
6769248934 | ||
|
|
cc95a18614 | ||
|
|
51afad07f4 | ||
|
|
91baefc564 | ||
|
|
90a5e123d2 | ||
|
|
6f05a200a1 | ||
|
|
ba791af25f | ||
|
|
6aaac1e78f | ||
|
|
93f56b4ed9 | ||
|
|
d871cf9b4c | ||
|
|
79c650c447 | ||
|
|
d2a0f98d9b | ||
|
|
9161f6ad2c | ||
|
|
c85903f9e7 | ||
|
|
16e2d42e63 | ||
|
|
8897dc7b08 | ||
|
|
8eb489d02a | ||
|
|
15e64fb683 | ||
|
|
0a06264241 | ||
|
|
f8b58eb8b6 | ||
|
|
ace4a6b395 | ||
|
|
42fb50c4ff | ||
|
|
76785dfc7c | ||
|
|
3c40ee73e4 | ||
|
|
fa4c5c66bb | ||
|
|
a60e94df7c | ||
|
|
f0944c57d6 | ||
|
|
cacd54d6e3 | ||
|
|
c5911d64b4 | ||
|
|
c077949339 | ||
|
|
c5e7033c1f | ||
|
|
a48c0845e6 | ||
|
|
19f0201ff0 | ||
|
|
2ceb43bd93 | ||
|
|
eca0c235dc | ||
|
|
8d7cec72d4 | ||
|
|
91a8d68878 | ||
|
|
034fdfe873 | ||
|
|
111ef00f3f | ||
|
|
d1f34521ab | ||
|
|
430751f805 | ||
|
|
0eee4ae4cf | ||
|
|
03a799ab36 | ||
|
|
2b7c063634 | ||
|
|
a9c1fae8e7 | ||
|
|
36fbd54230 | ||
|
|
37fd66be29 | ||
|
|
d323220d6d | ||
|
|
81d31c8556 | ||
|
|
b9ef0bd90b | ||
|
|
620a43a4ff | ||
|
|
77be420712 | ||
|
|
497e1ccdbd | ||
|
|
20b4b37772 | ||
|
|
4b32aad224 | ||
|
|
827e2f76e2 | ||
|
|
375e38df61 | ||
|
|
b266364dc9 | ||
|
|
144cd9ff6a | ||
|
|
8a36b71cd8 | ||
|
|
0e23b431df | ||
|
|
b205570e17 | ||
|
|
271ac53625 | ||
|
|
4512543341 | ||
|
|
a3389a9d58 | ||
|
|
e5c485cf9c | ||
|
|
ee5fb21894 | ||
|
|
3c48b63784 | ||
|
|
dbb0850f3d | ||
|
|
f99fe30095 | ||
|
|
d992bafef9 | ||
|
|
6b6fd4642c | ||
|
|
feab827ca8 | ||
|
|
645907bde3 | ||
|
|
255fc6238a | ||
|
|
1df41ade60 | ||
|
|
581bee9b54 | ||
|
|
50636b1f5e | ||
|
|
0975654fe9 | ||
|
|
b226669b97 | ||
|
|
832df9be48 | ||
|
|
fdc2ea8b4e | ||
|
|
d93023cd87 | ||
|
|
2481dbc14f | ||
|
|
64dde294b0 | ||
|
|
36d74be4a9 | ||
|
|
243e53b68f | ||
|
|
475e5dd18c | ||
|
|
24652286f8 | ||
|
|
101996a342 | ||
|
|
04fd4c2dc9 | ||
|
|
7a8f602d92 | ||
|
|
979cfb1d4c | ||
|
|
d85bf0b93f | ||
|
|
1ffa8a8706 | ||
|
|
db20ec464f | ||
|
|
5a983837b5 | ||
|
|
76da6d47a2 | ||
|
|
dd67f091a7 | ||
|
|
126ab64434 | ||
|
|
097f930dfe | ||
|
|
5ed174bcb3 | ||
|
|
d9c9fbb94a | ||
|
|
74e250f1e5 | ||
|
|
2c261c80a0 | ||
|
|
3516420ed6 | ||
|
|
b8b500d8c4 | ||
|
|
a2b1e96f7b | ||
|
|
ada179aa2d | ||
|
|
59c32eb882 | ||
|
|
d83ea74014 | ||
|
|
47ebd7dcbc | ||
|
|
5c5ad82094 | ||
|
|
48319046e1 | ||
|
|
e39b12871e | ||
|
|
8faafc8a63 | ||
|
|
678cf2fdb3 | ||
|
|
2efd03ff7a | ||
|
|
acbebcc669 | ||
|
|
fdda494e22 | ||
|
|
0a63c15a3d | ||
|
|
49015d14ad | ||
|
|
6e2a780e92 | ||
|
|
ffe5a98898 | ||
|
|
bf46753cc1 | ||
|
|
6d3d2fd503 | ||
|
|
cdc898fa0e | ||
|
|
cd1dd396b3 | ||
|
|
157be4f284 | ||
|
|
4778d39209 | ||
|
|
ac3c0a1269 | ||
|
|
7e9635dfb3 | ||
|
|
3d0b0ab5e1 | ||
|
|
44aee932e5 | ||
|
|
e48fe1b0df | ||
|
|
d02de0d93e | ||
|
|
81dd4dffab | ||
|
|
67c31012ce | ||
|
|
0bcf9faa53 | ||
|
|
77ebfbc701 | ||
|
|
4d18c9d314 | ||
|
|
2b7baff8de | ||
|
|
75e9680bd8 | ||
|
|
9faa4726e2 | ||
|
|
30fcca3e35 | ||
|
|
0740bba1a9 | ||
|
|
59dd4b64a7 | ||
|
|
728899fd02 | ||
|
|
f8bb7ed6cb | ||
|
|
3977b48a7d | ||
|
|
2e6f95c46a | ||
|
|
8c4424971f | ||
|
|
ad38526c8d | ||
|
|
f5333d6ec0 | ||
|
|
a2211922c4 | ||
|
|
c1b35846ab | ||
|
|
4e408f80fe | ||
|
|
67c5d6487c | ||
|
|
5d5140d32d | ||
|
|
d4bc061c34 | ||
|
|
1d3b5bd3fd | ||
|
|
226b455b1a | ||
|
|
54cff02667 | ||
|
|
da188239f3 | ||
|
|
34eb285783 | ||
|
|
79669d1cd0 | ||
|
|
566c9d87ce | ||
|
|
368884dce4 | ||
|
|
d580cd070e | ||
|
|
0ae2e4d75c | ||
|
|
04a9db3750 | ||
|
|
7e3a4a7720 | ||
|
|
81461f9c9c | ||
|
|
9e517719a4 | ||
|
|
500cfbf776 | ||
|
|
e5059c8fea | ||
|
|
0b8b0b33cc | ||
|
|
7288ac74a5 | ||
|
|
0874fe4988 | ||
|
|
8666047975 | ||
|
|
92d5811f9e | ||
|
|
3fd1656066 | ||
|
|
86b9bf8b24 | ||
|
|
f3ea4a1827 | ||
|
|
6506a95bff | ||
|
|
cf3f262b59 | ||
|
|
4fed5120b0 | ||
|
|
4d67a4d34c | ||
|
|
84c231b545 | ||
|
|
3d55044565 | ||
|
|
6d1921acaa | ||
|
|
217b1b8ace | ||
|
|
e8a54ddc22 | ||
|
|
18ee93b26a | ||
|
|
fb5dbb63a3 | ||
|
|
a2e49ff7f2 | ||
|
|
0b53ba70e5 | ||
|
|
07e2974c1a | ||
|
|
117c3ebc9c | ||
|
|
e24610f26d | ||
|
|
de2a957630 | ||
|
|
1eb2292e1a | ||
|
|
6fe59ab0af | ||
|
|
85576fc587 | ||
|
|
006aea3143 | ||
|
|
516e0105b8 | ||
|
|
4359c19817 | ||
|
|
da2c791073 | ||
|
|
b1b228fd20 | ||
|
|
a2a0869fd4 | ||
|
|
51bbbd5457 | ||
|
|
28c37e66a0 | ||
|
|
63b16af02a | ||
|
|
439619bca6 | ||
|
|
2e1e46ad8c | ||
|
|
d788983cf3 | ||
|
|
fe2f470f99 | ||
|
|
51ccf1acd3 | ||
|
|
e52533f182 | ||
|
|
a15a318472 | ||
|
|
d8b7c2f8ad | ||
|
|
1657183837 | ||
|
|
7ce8044bf8 | ||
|
|
204f1c9f8d | ||
|
|
143ccb15cb | ||
|
|
cc56db8f0d | ||
|
|
cf5e228ba8 | ||
|
|
07b15bf8e6 | ||
|
|
44001b870c | ||
|
|
746b35cf5d | ||
|
|
913501e08e | ||
|
|
0c3b130fac | ||
|
|
7d6cd62b60 | ||
|
|
f5cafb4e19 | ||
|
|
eb0ec99d1c | ||
|
|
b8d8b2982d | ||
|
|
e9d361278c | ||
|
|
50381499b1 | ||
|
|
4141ae3932 | ||
|
|
2d004e341b | ||
|
|
d2519fbf8a | ||
|
|
210e63198f | ||
|
|
a88e91e3df | ||
|
|
482ac94c32 | ||
|
|
bb164a4b8e | ||
|
|
6cf0d1aa19 | ||
|
|
6828bf1529 | ||
|
|
0ce755d04c | ||
|
|
120bbc1d4b | ||
|
|
c79a338588 | ||
|
|
2af71cefe2 | ||
|
|
3a51841745 | ||
|
|
456a472288 | ||
|
|
bc08f99e0f | ||
|
|
15ee2c8870 | ||
|
|
e383900bcd | ||
|
|
f55e95ca80 | ||
|
|
67e98e8b2b | ||
|
|
e43a06c509 | ||
|
|
248753a246 | ||
|
|
9fa76a6a3f | ||
|
|
220a8ad024 | ||
|
|
a1c5aa1038 | ||
|
|
0feb336526 | ||
|
|
94cde42f2d | ||
|
|
8d48f841e5 | ||
|
|
3be4738d27 | ||
|
|
98d7a7376a | ||
|
|
e6df4f3281 | ||
|
|
07b4fe80df | ||
|
|
b6d9bd4719 | ||
|
|
2ef586fc01 | ||
|
|
b4129e2c9e | ||
|
|
89bf16b887 | ||
|
|
e7c3acf352 | ||
|
|
a25a2c4595 | ||
|
|
50660b423b | ||
|
|
677f3f3745 | ||
|
|
d846d0f5fd | ||
|
|
b113320e81 | ||
|
|
dfb882d8b1 | ||
|
|
290c8e7ce4 | ||
|
|
f351db4e29 |
8
.changeset/README.md
Normal file
@ -0,0 +1,8 @@
|
||||
# Changesets
|
||||
|
||||
Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
|
||||
with multi-package repos, or single-package repos to help you version and publish your code. You can
|
||||
find the full documentation for it [in our repository](https://github.com/changesets/changesets)
|
||||
|
||||
We have a quick list of common questions to get you started engaging with this project in
|
||||
[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
|
||||
11
.changeset/config.json
Normal file
@ -0,0 +1,11 @@
|
||||
{
|
||||
"$schema": "https://unpkg.com/@changesets/config@3.0.5/schema.json",
|
||||
"changelog": "@changesets/cli/changelog",
|
||||
"commit": false,
|
||||
"fixed": [],
|
||||
"linked": [],
|
||||
"access": "public",
|
||||
"baseBranch": "master",
|
||||
"updateInternalDependencies": "patch",
|
||||
"ignore": []
|
||||
}
|
||||
50
.github/workflows/deploy-docs.yml
vendored
Normal file
@ -0,0 +1,50 @@
|
||||
name: Deploy docs to github pages
|
||||
|
||||
on:
|
||||
# Runs on pushes targeting the default branch
|
||||
push:
|
||||
branches: ["master", "main"]
|
||||
|
||||
# Allows you to run this workflow manually from the Actions tab
|
||||
workflow_dispatch:
|
||||
|
||||
# Sets the GITHUB_TOKEN permissions to allow deployment to GitHub Pages
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
# Allow one concurrent deployment
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
# Single deploy job since we're just deploying
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v5
|
||||
- name: Set up Node
|
||||
uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: lts/*
|
||||
cache: "npm"
|
||||
- name: Install dependencies
|
||||
run: npm install
|
||||
- name: Build
|
||||
run: npm run typedoc && npm run docs:build
|
||||
- name: Setup Pages
|
||||
uses: actions/configure-pages@v5
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v4
|
||||
with:
|
||||
# Upload dist folder
|
||||
path: "./dist"
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
38
.github/workflows/main.yml
vendored
Normal file
@ -0,0 +1,38 @@
|
||||
name: Build
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ master ]
|
||||
pull_request:
|
||||
branches: [ master ]
|
||||
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '18'
|
||||
|
||||
- name: npm-install
|
||||
run: npm install
|
||||
|
||||
- name: npm-test
|
||||
run: npm run test
|
||||
|
||||
- name: npm-lint
|
||||
run: npm run lint
|
||||
|
||||
- name: npm-build
|
||||
run: npm run build
|
||||
|
||||
- name: npm-test-types
|
||||
run: npm run test:types
|
||||
|
||||
- name: npm-typedoc
|
||||
run: npm run typedoc
|
||||
56
.gitignore
vendored
@ -1,5 +1,51 @@
|
||||
.settings
|
||||
.project
|
||||
node_modules/
|
||||
bower_components/
|
||||
.idea
|
||||
|
||||
dist/docs/
|
||||
|
||||
# typedoc
|
||||
docs/pages/api/
|
||||
|
||||
# vitepress
|
||||
docs/.vitepress/cache/
|
||||
docs/.vitepress/dist/
|
||||
docs/.vitepress/.temp/
|
||||
|
||||
# misc
|
||||
.DS_Store
|
||||
*.pem
|
||||
|
||||
# dependencies
|
||||
node_modules
|
||||
.pnp
|
||||
.pnp.js
|
||||
|
||||
# debug
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
|
||||
# local env files
|
||||
.env*.local
|
||||
.env
|
||||
|
||||
# testing
|
||||
/coverage
|
||||
/.nyc_output
|
||||
|
||||
# production
|
||||
build
|
||||
/docs/dist
|
||||
|
||||
# next.js
|
||||
.next/
|
||||
# out/
|
||||
|
||||
# vercel
|
||||
.vercel
|
||||
|
||||
# ide
|
||||
.idea/
|
||||
.vscode*/
|
||||
|
||||
# typescript
|
||||
*.tsbuildinfo
|
||||
next-env.d.ts
|
||||
|
||||
2
.prettierignore
Normal file
@ -0,0 +1,2 @@
|
||||
/dist/
|
||||
/docs/api/
|
||||
4
.prettierrc.json
Normal file
@ -0,0 +1,4 @@
|
||||
{
|
||||
"printWidth": 120,
|
||||
"quoteProps": "preserve"
|
||||
}
|
||||
77
CHANGELOG.md
Normal file
@ -0,0 +1,77 @@
|
||||
# planck
|
||||
|
||||
## 1.5.0
|
||||
|
||||
### Minor Changes
|
||||
|
||||
- 6ede4f3: Publish add-body, add-fixture, add-joint events
|
||||
|
||||
### Patch Changes
|
||||
|
||||
- 9415379: Add fixedRotation to body serialize
|
||||
- 7791ea1: Remove temp fields from distance-joint serialization
|
||||
- 86c9079: Remove hasVertex0 and hasVertex3 from serialize Edge
|
||||
- 4fc10a7: In polygon and chain \_deserialize use Vec2Value
|
||||
|
||||
## 1.4.3
|
||||
|
||||
### Patch Changes
|
||||
|
||||
- 0bba3b2: Bug fix addVec2
|
||||
|
||||
## 1.4.2
|
||||
|
||||
### Patch Changes
|
||||
|
||||
- 9343ffc: Fix testbed drawing
|
||||
|
||||
## 1.4.1
|
||||
|
||||
### Patch Changes
|
||||
|
||||
- d12d0cc: Fix shape name alias export
|
||||
|
||||
## 1.4.0
|
||||
|
||||
### Minor Changes
|
||||
|
||||
- 0dcc98b: Split TestbedInterface and Testbed class
|
||||
|
||||
### Patch Changes
|
||||
|
||||
- e1a2717: Mark serialize and deserialize functions as @hidden instead of @internal
|
||||
- 3446820: Fix AABB.rayCast
|
||||
|
||||
## 1.3.0
|
||||
|
||||
### Minor Changes
|
||||
|
||||
- bb9bb87: Testbed rendering rewrite
|
||||
- 56193e7: Add DataDriver (experimental for demo use-case)
|
||||
|
||||
### Patch Changes
|
||||
|
||||
- ce1c486: No pointer interaction when mouseForce===0
|
||||
|
||||
## 1.2.0
|
||||
|
||||
### Minor Changes
|
||||
|
||||
- f0127f4: Add world.queueUpdate() to queue and defer updates after current simulation step
|
||||
|
||||
### Patch Changes
|
||||
|
||||
- 97bb79e: Improve world.queueUpdate
|
||||
|
||||
## 1.1.6
|
||||
|
||||
### Patch Changes
|
||||
|
||||
- f31114b: Add static Vec2.normalize
|
||||
- bee0e16: Change clampVec2 arg to Vec2Value
|
||||
|
||||
## 1.1.5
|
||||
|
||||
### Patch Changes
|
||||
|
||||
- fbd0021: Un-hidden style field type
|
||||
14
CHANGES.md
@ -1,8 +1,20 @@
|
||||
## 1.1.0
|
||||
* Vite build migration
|
||||
|
||||
## 1.0.0
|
||||
* Typescript migration
|
||||
* Performance improvements
|
||||
|
||||
## 0.2
|
||||
* TypeScript definitions added
|
||||
* wSet/wAdd/wSub(a, v, b, w) replaced with combine/setCombine/addCombine/subCombine(a, v, b, w)
|
||||
* wSet/wAdd/wSub(a, v) replaced with mul/setMul/addMul/subMul(a, v)
|
||||
* Joints constructors cleanup
|
||||
|
||||
## 0.1
|
||||
* source code directory layout changed, classes moved around!
|
||||
* b2Class renamed to Class
|
||||
* Dumping is removed, Drawing is moved to Stage viewer
|
||||
* Dumping is removed, Drawing is moved to tesbed
|
||||
* GrowableStack replaced with native array, Timer is changed
|
||||
* Math is changed and split
|
||||
* Contact and Collide classes merged, Contact registration/creation is changes
|
||||
|
||||
86
HelloWorld.ts
Normal file
@ -0,0 +1,86 @@
|
||||
/*
|
||||
* Copyright (c) Erin Catto
|
||||
* Licensed under the MIT license
|
||||
*/
|
||||
|
||||
/*
|
||||
* This is a simple example of building and running a simulation
|
||||
* using Planck.js. Here we create a large ground box and a small dynamic
|
||||
* box.
|
||||
* There are no graphics for this example. Planck.js is meant to be used
|
||||
* with your rendering engine in your game engine.
|
||||
*
|
||||
* To run this example simply run `node HelloWorld.js` from command line.
|
||||
*/
|
||||
|
||||
import { Box, World } from "./src";
|
||||
|
||||
// Define the gravity vector.
|
||||
var gravity = { x: 0.0, y: -10.0 };
|
||||
|
||||
// Construct a world object, which will hold and simulate the rigid bodies.
|
||||
var world = new World({
|
||||
gravity: gravity,
|
||||
});
|
||||
|
||||
// Define the ground body.
|
||||
var groundBodyDef = {
|
||||
position: { x: 0.0, y: -10.0 },
|
||||
};
|
||||
|
||||
// Call the body factory which allocates memory for the ground body
|
||||
// from a pool and creates the ground box shape (also from a pool).
|
||||
// The body is also added to the world.
|
||||
var groundBody = world.createBody(groundBodyDef);
|
||||
|
||||
// Define the ground box shape.
|
||||
// The extents are the half-widths of the box.
|
||||
var groundBox = new Box(50.0, 10.0);
|
||||
|
||||
// Add the ground fixture to the ground body.
|
||||
groundBody.createFixture(groundBox, 0.0);
|
||||
|
||||
// Define the dynamic body. We set its position and call the body factory.
|
||||
var body = world.createBody({
|
||||
type: "dynamic",
|
||||
position: { x: 0.0, y: 4.0 },
|
||||
});
|
||||
|
||||
// Define another box shape for our dynamic body.
|
||||
var dynamicBox = new Box(1.0, 1.0);
|
||||
|
||||
// Define the dynamic body fixture.
|
||||
var fixtureDef = {
|
||||
shape: dynamicBox,
|
||||
// Set the box density to be non-zero, so it will be dynamic.
|
||||
density: 1.0,
|
||||
// Override the default friction.
|
||||
friction: 0.3,
|
||||
};
|
||||
|
||||
// Add the shape to the body.
|
||||
body.createFixture(fixtureDef);
|
||||
|
||||
// Prepare for simulation. Typically we use a time step of 1/60 of a
|
||||
// second (60Hz) and 10 iterations. This provides a high quality simulation
|
||||
// in most game scenarios.
|
||||
var timeStep = 1.0 / 60.0;
|
||||
var velocityIterations = 6;
|
||||
var positionIterations = 2;
|
||||
|
||||
// This is our little game loop.
|
||||
for (var i = 0; i < 60; ++i) {
|
||||
// Instruct the world to perform a single step of simulation.
|
||||
// It is generally best to keep the time step and iterations fixed.
|
||||
world.step(timeStep, velocityIterations, positionIterations);
|
||||
|
||||
// Now print the position and angle of the body.
|
||||
var position = body.getPosition();
|
||||
var angle = body.getAngle();
|
||||
|
||||
console.log(position.x.toFixed(2), position.y.toFixed(2), angle.toFixed(2));
|
||||
}
|
||||
|
||||
console.log(Math.abs(position.x) < 0.01);
|
||||
console.log(Math.abs(position.y - 1.01) < 0.01);
|
||||
console.log(Math.abs(angle) < 0.01);
|
||||
32
LICENSE.txt
@ -1,18 +1,20 @@
|
||||
Copyright (c) 2016-2017 Ali Shakiba http://shakiba.me/planck.js
|
||||
Copyright (c) 2006-2013 Erin Catto http://www.gphysics.com
|
||||
The MIT License
|
||||
Copyright (c) Erin Catto, Ali Shakiba
|
||||
|
||||
This software is provided 'as-is', without any express or implied
|
||||
warranty. In no event will the authors be held liable for any damages
|
||||
arising from the use of this software.
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
Permission is granted to anyone to use this software for any purpose,
|
||||
including commercial applications, and to alter it and redistribute it
|
||||
freely, subject to the following restrictions:
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
1. The origin of this software must not be misrepresented; you must not
|
||||
claim that you wrote the original software. If you use this software
|
||||
in a product, an acknowledgment in the product documentation would be
|
||||
appreciated but is not required.
|
||||
2. Altered source versions must be plainly marked as such, and must not be
|
||||
misrepresented as being the original software.
|
||||
3. This notice may not be removed or altered from any source distribution.
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
||||
190
README.md
@ -1,149 +1,65 @@
|
||||
*This project is under active development and is not stable yet.*
|
||||
# planck-deterministic
|
||||
|
||||
# Planck.js<sup>α</sup>
|
||||
A fork of [planck.js](https://github.com/piqnt/planck.js) (MIT, Erin Catto / Ali Shakiba)
|
||||
with a **cross-platform deterministic math kernel**.
|
||||
|
||||
Planck.js is JavaScript rewrite of Box2D physics engine for cross-platform HTML5 game development. **[Check out demos!](http://piqnt.com/planck.js/)**
|
||||
## Why
|
||||
|
||||
[](http://piqnt.com/planck.js/Car)
|
||||
Upstream planck calls the host `Math.sin`, `Math.cos`, `Math.atan2` and `Math.random`.
|
||||
IEEE-754 guarantees `+ - * /` and `sqrt` are correctly rounded, so those are identical
|
||||
everywhere — but ECMAScript explicitly permits an *implementation-dependent approximation*
|
||||
for the transcendental functions, and every engine forwards them to the host libm. Those
|
||||
results differ between ARM64/JavaScriptCore (iOS) and x86-64/V8 (desktop).
|
||||
|
||||
## Motivations
|
||||
`Rot.setAngle` and `Sweep.getTransform` call sin/cos for **every rotating body on every
|
||||
step**. So a simulation shared between a mobile build and a desktop build diverges as soon
|
||||
as anything rotates. That breaks replay portability, server-side replay verification, and
|
||||
any leaderboard built on re-simulating a replay.
|
||||
|
||||
## What changed
|
||||
|
||||
- Added `src/common/DeterministicMath.ts` — `sin`, `cos`, `exp`, `atan`, `atan2`, `sqrt` and
|
||||
a seeded PRNG, built from `+ - * /` and comparisons only. Coefficients and the Cody-Waite
|
||||
range reduction follow fdlibm (Sun, freely distributable), the reference implementation
|
||||
most libms derive from. Accuracy is within a few ulp of the host libm.
|
||||
- Rewired the nine hoisted aliases in `Math.ts`, `Matrix.ts`, `Rot.ts`, `Sweep.ts` and
|
||||
`dynamics/Position.ts` to use it. **No host libm call remains anywhere in `src/`.**
|
||||
- Exported the kernel (`DeterministicMath`, `seedRandom`) so consumers can share the exact
|
||||
same functions the solver uses and seed the PRNG for reproducible replays.
|
||||
|
||||
Every upstream test still passes, plus new determinism tests including a check that a
|
||||
simulated free fall matches the closed-form analytic solution.
|
||||
|
||||
```js
|
||||
import { World, seedRandom, DeterministicMath } from "planck-deterministic";
|
||||
|
||||
seedRandom(12345); // before a run, and before replaying it
|
||||
```
|
||||
|
||||
## Upstream
|
||||
|
||||
This tracks planck.js v1.5.0. Upstream docs and API below.
|
||||
|
||||
---
|
||||
|
||||
# Planck.js
|
||||
|
||||
Planck.js is JavaScript/TypeScript rewrite of Box2D physics engine for cross-platform HTML5 game development.
|
||||
|
||||
#### Motivations
|
||||
|
||||
Key motivations in development of this project are:
|
||||
- Taking advantage of Box2D's efforts and achievements
|
||||
- Developing readable and maintainable JavaScript code
|
||||
- Developing readable and editable code in JavaScript/TypeScript
|
||||
- Providing idiomatic JavaScript/TypeScript API
|
||||
- Optimizing the library for web and mobile platforms
|
||||
- Providing a JavaScript-friendly API
|
||||
|
||||
## Try it
|
||||
#### [Documentation](https://piqnt.com/planck.js/docs/)
|
||||
|
||||
To try Planck.js, simply add `planck-with-testbed.js` script to your HTML code and call `planck.testbed(callback)` with your code in callback. For example:
|
||||
#### [Examples](https://piqnt.com/planck.js/)
|
||||
|
||||
```html
|
||||
<html><body>
|
||||
<script src="https://cdn.jsdelivr.net/planck/0.1/planck-with-testbed.js"></script>
|
||||
<script>
|
||||
planck.testbed(function(testbed) {
|
||||
var world = planck.World();
|
||||
// rest of your code
|
||||
return world; // make sure you return the world
|
||||
});
|
||||
</script>
|
||||
</body></html>
|
||||
```
|
||||
#### [Discord](https://discord.com/invite/znjh6J7)
|
||||
|
||||
Check out [Car example on CodePen](https://codepen.io/ashakiba/pen/yMpvrX?editors=001) to see it in practice.
|
||||
Also see [`example`](./example/) directory for more testbed usage examples.
|
||||
#### [Made with Planck.js](https://github.com/piqnt/planck.js/wiki/)
|
||||
|
||||
|
||||
## Install
|
||||
|
||||
#### Download
|
||||
|
||||
Latest builds are available on [releases page](https://github.com/shakiba/planck.js/releases).
|
||||
|
||||
#### CDN
|
||||
|
||||
Planck.js is [available on jsDelivr](https://www.jsdelivr.com/projects/planck).
|
||||
|
||||
|
||||
#### NPM
|
||||
|
||||
npm install planck-js --save
|
||||
|
||||
#### Bower
|
||||
|
||||
bower install planck-js --save
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
Planck.js does not use any renderer by default. To use or integrate it with a rendering library all you need to do
|
||||
is calling `world.step(hz)` in each frame, and then iterating over world entities to draw or update them.
|
||||
You may also want to listen to world events to remove objects which are removed from the world. For example:
|
||||
|
||||
```html
|
||||
<script src="./path/to/planck.min.js"></script>
|
||||
<script>
|
||||
var world = planck.World();
|
||||
|
||||
window.requestAnimationFrame(function() {
|
||||
// in each frame call word.step(hz) with fixed frequency
|
||||
world.step(1 / 60);
|
||||
// iterate over bodies and fixtures
|
||||
for (var body = world.getBodyList(); body; body = body.getNext()) {
|
||||
for (var fixture = body.getFixtureList(); fixture; fixture = fixture.getNext()) {
|
||||
// draw or update fixture
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
world.on('remove-fixture', function(fixture) {
|
||||
// remove fixture from ui
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
Planck.js public API closely follows Box2D API (see [Resources](#Resources)), with following differences:
|
||||
|
||||
- `b2` prefix is dropped from class names, for example `b2World` is now available as `planck.World`.
|
||||
- Method names are converted from UpperCamelCase to lowerCamelCase.
|
||||
- Definition classes/objects (BodyDef, FixtureDef, etc.) are replaced by inline JavaScript objects (`{}`).
|
||||
- Shapes are made immutable and are not cloned when used to create fixtures.
|
||||
- `World#on(eventName, listenerFn)` and `World#off(eventName, listenerFn)` are added to add and remove event listeners. Currently supported events are:
|
||||
- `'contact-begin'`
|
||||
- `'contact-end'`
|
||||
- `'pre-solve'`
|
||||
- `'post-solve'`
|
||||
- `'joint-removed'`
|
||||
- `'fixture-removed'`
|
||||
- `'body-removed'`
|
||||
|
||||
|
||||
## Resources
|
||||
|
||||
- <a href="http://box2d.org/documentation/" target="_blank">Box2D Manual</a> and <a href="https://github.com/erincatto/Box2D/wiki/FAQ" target="_blank">FAQ</a> are highly recommended to get started.
|
||||
- [iforce2d](https://www.iforce2d.net/b2dtut/) website includes a collection of helpful tutorials and resources to learn Box2D.
|
||||
|
||||
Following technical documents are recommend if you are interested in learning about Box2D/Planck.js's internal details.
|
||||
|
||||
- [Continuous Collision](http://twvideo01.ubm-us.net/o1/vault/gdc2013/slides/824737Catto_Erin_PhysicsForGame.pdf) by Erin Catto
|
||||
- [Solving Rigid Body Contacts](http://www.richardtonge.com/presentations/Tonge-2012-GDC-solvingRigidBodyContacts.pdf) by Richard Tonge
|
||||
|
||||
|
||||
*If you know any other useful resource, please add it or submit an issue about it.*
|
||||
|
||||
## Testbed
|
||||
|
||||
Another way to use testbed and try included examples (in [`example`](./example/) directory) is running testbed with live build locally:
|
||||
|
||||
1. Install `git`, `npm` and `bower`
|
||||
|
||||
1. Clone or download this repository
|
||||
|
||||
1. Install npm and bower dependencies:
|
||||
|
||||
npm install
|
||||
bower install
|
||||
|
||||
1. Run testbed and open it in your web browser (see command-line output for URL to open):
|
||||
|
||||
npm run testbed
|
||||
|
||||
|
||||
## Architecture
|
||||
|
||||
Planck.js includes Box2D algorithms without modification and its internal architecture and public API are very similar to Box2D.
|
||||
However some [changes](./CHANGES.md) and refactoring are made during rewrite to address differences between C++ and JavaScript.
|
||||
|
||||
|
||||
## Credits
|
||||
|
||||
[Box2D](http://box2d.org/) is a popular C++ 2D rigid-body physics engine created by [Erin Catto](https://twitter.com/erin_catto). Box2D is used in several popular games, such as Angry Birds, Limbo and Crayon Physics, as well as game development tools and libraries such as Apple's SpriteKit.
|
||||
|
||||
[Planck.js](https://github.com/shakiba/planck.js) is developed and maintained by Ali Shakiba.
|
||||
|
||||
## License
|
||||
|
||||
Planck.js is [available under the zlib license](./LICENSE.txt).
|
||||
#### [Report Issues](https://github.com/piqnt/planck.js/issues)
|
||||
To speed up resolving issues, please provide [testbed](https://piqnt.com/planck.js/docs/testbed) code to reproduce the issue.
|
||||
|
||||
225
benchmark/benchmark.ts
Normal file
@ -0,0 +1,225 @@
|
||||
export interface TestInterface {
|
||||
name: string;
|
||||
createBoxShape: (hx: number, hy: number) => any;
|
||||
createBoxBody: (shape: any, x: number, y: number, density: number) => any;
|
||||
step: (timeStep: number, velocityIterations: number, positionIterations: number) => void;
|
||||
setup: () => void;
|
||||
teardown: () => void;
|
||||
}
|
||||
|
||||
export interface XY {
|
||||
x: number;
|
||||
y: number;
|
||||
}
|
||||
|
||||
export type TestFactory = (gravity: XY, edgeV1: XY, edgeV2: XY, edgeDensity: number) => TestInterface;
|
||||
|
||||
const PYRAMID_SIZE = 40;
|
||||
const GRAVITY = { x: 0, y: -10 };
|
||||
const DELTA_X = { x: 0.5625, y: 1 };
|
||||
const DELTA_Y = { x: 1.125, y: 0 };
|
||||
const BOX_DENSITY = 5;
|
||||
const GROUND_DENSITY = 0;
|
||||
const TIME_STEP = 1 / 60;
|
||||
const VELOCITY_ITERATIONS = 3;
|
||||
const POSITION_ITERATIONS = 3;
|
||||
const EDGE_V1 = { x: -40, y: 0 };
|
||||
const EDGE_V2 = { x: 40, y: 0 };
|
||||
const START_X = { x: -7, y: 0.75 };
|
||||
const BOX_SIZE = { x: 0.5, y: 0.5 };
|
||||
const WARMUP_ITERATIONS = 64;
|
||||
const BENCH_ITERATIONS = 256;
|
||||
|
||||
function setupWorld(test: TestInterface) {
|
||||
// Setup world
|
||||
const shape = test.createBoxShape(BOX_SIZE.x, BOX_SIZE.y);
|
||||
const x = { ...START_X };
|
||||
|
||||
for (let i = 0; i < PYRAMID_SIZE; ++i) {
|
||||
const y = { ...x };
|
||||
|
||||
for (let j = i; j < PYRAMID_SIZE; ++j) {
|
||||
test.createBoxBody(shape, y.x, y.y, BOX_DENSITY);
|
||||
y.x += DELTA_Y.x;
|
||||
y.y += DELTA_Y.y;
|
||||
}
|
||||
|
||||
x.x += DELTA_X.x;
|
||||
x.y += DELTA_X.y;
|
||||
}
|
||||
}
|
||||
|
||||
export type ProgressFunc = (value: number, max: number) => void;
|
||||
|
||||
async function warmupAsync(test: TestInterface, progress: ProgressFunc): Promise<void> {
|
||||
return new Promise<void>((resolve: (value: void) => void) => {
|
||||
let step = 0;
|
||||
progress(0, WARMUP_ITERATIONS + BENCH_ITERATIONS);
|
||||
const runNext = () => {
|
||||
if (step < WARMUP_ITERATIONS) {
|
||||
test.step(TIME_STEP, VELOCITY_ITERATIONS, POSITION_ITERATIONS);
|
||||
progress(step, WARMUP_ITERATIONS + BENCH_ITERATIONS);
|
||||
step++;
|
||||
window.requestAnimationFrame(runNext);
|
||||
} else {
|
||||
resolve();
|
||||
}
|
||||
};
|
||||
window.requestAnimationFrame(runNext);
|
||||
});
|
||||
}
|
||||
|
||||
async function benchAsync(test: TestInterface, progress: ProgressFunc): Promise<number[]> {
|
||||
return new Promise((resolve: (value: number[]) => void) => {
|
||||
let step = 0;
|
||||
progress(0, WARMUP_ITERATIONS + BENCH_ITERATIONS);
|
||||
const times: number[] = [];
|
||||
const runNext = () => {
|
||||
if (step < BENCH_ITERATIONS) {
|
||||
const begin = performance.now();
|
||||
test.step(TIME_STEP, VELOCITY_ITERATIONS, POSITION_ITERATIONS);
|
||||
times.push(performance.now() - begin);
|
||||
progress(WARMUP_ITERATIONS + step, WARMUP_ITERATIONS + BENCH_ITERATIONS);
|
||||
step++;
|
||||
window.requestAnimationFrame(runNext);
|
||||
} else {
|
||||
resolve(times);
|
||||
}
|
||||
};
|
||||
window.requestAnimationFrame(runNext);
|
||||
});
|
||||
}
|
||||
|
||||
function warmup(test: TestInterface) {
|
||||
for (let i = 0; i < WARMUP_ITERATIONS; i++) {
|
||||
test.step(TIME_STEP, VELOCITY_ITERATIONS, POSITION_ITERATIONS);
|
||||
}
|
||||
}
|
||||
|
||||
function bench(test: TestInterface) {
|
||||
const times: number[] = [];
|
||||
for (let i = 0; i < BENCH_ITERATIONS; i++) {
|
||||
const begin = performance.now();
|
||||
test.step(TIME_STEP, VELOCITY_ITERATIONS, POSITION_ITERATIONS);
|
||||
times.push(performance.now() - begin);
|
||||
}
|
||||
return times.sort();
|
||||
}
|
||||
|
||||
function mean(values: number[]) {
|
||||
let total = 0;
|
||||
for (const value of values) total += value;
|
||||
return total / BENCH_ITERATIONS;
|
||||
}
|
||||
|
||||
// Simple nearest-rank %ile (on sorted array). We should have enough samples to make this reasonable.
|
||||
function percentile(values: number[], pc: number) {
|
||||
const rank = Math.floor((pc * values.length) / 100);
|
||||
return values[rank];
|
||||
}
|
||||
|
||||
export function prepareTests(factories: TestFactory[]) {
|
||||
return factories.map((factory: TestFactory) => factory(GRAVITY, EDGE_V1, EDGE_V2, GROUND_DENSITY));
|
||||
}
|
||||
|
||||
export function runTest(test: TestInterface) {
|
||||
setupWorld(test);
|
||||
|
||||
warmup(test);
|
||||
|
||||
const times = bench(test);
|
||||
return {
|
||||
name: test.name,
|
||||
avg: mean(times),
|
||||
p5: percentile(times, 5),
|
||||
p95: percentile(times, 95),
|
||||
};
|
||||
}
|
||||
|
||||
export async function runTestAsync(test: TestInterface, progress: ProgressFunc) {
|
||||
setupWorld(test);
|
||||
|
||||
await warmupAsync(test, progress);
|
||||
|
||||
const times = await benchAsync(test, progress);
|
||||
return {
|
||||
name: test.name,
|
||||
avg: mean(times),
|
||||
p5: percentile(times, 5),
|
||||
p95: percentile(times, 95),
|
||||
};
|
||||
}
|
||||
|
||||
export type TestResult = ReturnType<typeof runTest>;
|
||||
|
||||
export function runAllTests(factories: TestFactory[]) {
|
||||
const tests = prepareTests(factories);
|
||||
const results: TestResult[] = [];
|
||||
|
||||
console.log("Running Benchmarks:");
|
||||
for (const test of tests) {
|
||||
const result = runTest(test);
|
||||
results.push(result);
|
||||
console.log(` ✓ ${result.name}`);
|
||||
}
|
||||
|
||||
return results.sort((a: TestResult, b: TestResult) => a.avg - b.avg);
|
||||
}
|
||||
|
||||
const noop = () => undefined;
|
||||
|
||||
export async function runAllTestsAsync(factories: TestFactory[]) {
|
||||
const tests = prepareTests(factories);
|
||||
console.log("Running Benchmarks:");
|
||||
const results: TestResult[] = [];
|
||||
for (const test of tests) {
|
||||
// eslint-disable-next-line no-await-in-loop
|
||||
const result = await runTestAsync(test, noop);
|
||||
console.log(` ✓ ${result.name}`);
|
||||
results.push(result);
|
||||
}
|
||||
|
||||
return results.sort((a: TestResult, b: TestResult) => a.avg - b.avg);
|
||||
}
|
||||
|
||||
export function resultsToMarkdown(results: TestResult[]) {
|
||||
const header = ["Name", "avg ms/frame", "5th %ile", "95th %ile", "Ratio"];
|
||||
const rows = results.map((r: TestResult) => [
|
||||
r.name,
|
||||
r.avg.toFixed(2),
|
||||
r.p5.toString(),
|
||||
r.p95.toString(),
|
||||
(r.avg / results[0].avg).toFixed(2),
|
||||
]);
|
||||
const lengths = header.map((label: string, index: number) =>
|
||||
Math.max(label.length, ...rows.map((columns: string[]) => columns[index].length)),
|
||||
);
|
||||
|
||||
function getDashes(length: number) {
|
||||
return "-".repeat(length);
|
||||
}
|
||||
const dashes = `| ${lengths.map(getDashes).join(" | ")} |`;
|
||||
|
||||
const lines: string[] = [];
|
||||
lines.push(`| ${header.map(pad).join(" | ")} |`);
|
||||
lines.push(dashes);
|
||||
|
||||
function pad(value: string, index: number) {
|
||||
const length = lengths[index];
|
||||
if (value.length < length) {
|
||||
if (index > 0) return " ".repeat(length - value.length) + value;
|
||||
return value + " ".repeat(length - value.length);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
for (const row of rows) {
|
||||
lines.push(`| ${row.map(pad).join(" | ")} |`);
|
||||
}
|
||||
return lines.join("\n");
|
||||
}
|
||||
|
||||
export function logResults(results: TestResult[]) {
|
||||
console.log("\nResults:");
|
||||
console.log(resultsToMarkdown(results));
|
||||
}
|
||||
106
benchmark/browser.ts
Normal file
@ -0,0 +1,106 @@
|
||||
import { prepareTests, resultsToMarkdown, runTestAsync, TestResult, TestInterface, TestFactory } from "./benchmark";
|
||||
import { box2dJsFactory } from "./tests/box2d-js";
|
||||
import { planckFactory } from "./tests/planck";
|
||||
|
||||
export const tests: TestFactory[] = [
|
||||
box2dJsFactory,
|
||||
planckFactory,
|
||||
];
|
||||
|
||||
export function getBrowserInfo() {
|
||||
const ua = navigator.userAgent;
|
||||
let M = ua.match(/(opera|chrome|safari|firefox|msie|trident(?=\/))\/?\s*(\d+)/i) ?? [];
|
||||
if (/trident/i.test(M[1])) {
|
||||
const tem = /\brv[ :]+(\d+)/g.exec(ua) ?? [];
|
||||
const version = tem[1] || "";
|
||||
return `IE ${version}`;
|
||||
}
|
||||
if (M[1] === "Chrome") {
|
||||
const tem = ua.match(/\bOPR|Edge\/(\d+)/);
|
||||
if (tem !== null) return `Opera ${tem[1]}`;
|
||||
}
|
||||
M = M[2] ? [M[1], M[2]] : [navigator.appName, navigator.appVersion, "-?"];
|
||||
const tem = ua.match(/version\/(\d+)/i);
|
||||
if (tem !== null) M.splice(1, 1, tem[1]);
|
||||
|
||||
return `${M[0]} ${M[1]}`;
|
||||
}
|
||||
|
||||
const startButton = document.getElementById("start") as HTMLButtonElement;
|
||||
const tbody = document.querySelector("tbody") as HTMLElement;
|
||||
const ratioHead = document.getElementById("ratio") as HTMLElement;
|
||||
const branchName = document.getElementById("branch-name") as HTMLElement;
|
||||
|
||||
branchName.innerHTML = [
|
||||
import.meta.env.VITE_GIT_BRANCH_NAME,
|
||||
import.meta.env.VITE_GIT_COMMIT_HASH.slice(0, 7),
|
||||
import.meta.env.VITE_GIT_COMMIT_DATE.slice(0, 19).replace("T", " "),
|
||||
'\"' + import.meta.env.VITE_GIT_LAST_COMMIT_MESSAGE + '\"',
|
||||
].join("<br />");
|
||||
|
||||
|
||||
|
||||
const testRows = prepareTests(tests).map((test: TestInterface) => {
|
||||
const row = document.createElement("tr");
|
||||
tbody.appendChild(row);
|
||||
const name = document.createElement("td");
|
||||
const avg = document.createElement("td");
|
||||
const p5 = document.createElement("td");
|
||||
const p95 = document.createElement("td");
|
||||
const ratio = document.createElement("td");
|
||||
name.textContent = test.name;
|
||||
row.appendChild(name);
|
||||
row.appendChild(avg);
|
||||
row.appendChild(p5);
|
||||
row.appendChild(p95);
|
||||
row.appendChild(ratio);
|
||||
const progress = document.createElement("progress");
|
||||
return {
|
||||
row,
|
||||
test,
|
||||
begin() {
|
||||
test.setup();
|
||||
ratio.appendChild(progress);
|
||||
progress.value = 0;
|
||||
},
|
||||
progress(value: number, max: number) {
|
||||
progress.value = value;
|
||||
progress.max = max;
|
||||
},
|
||||
end(result: TestResult) {
|
||||
test.teardown();
|
||||
avg.textContent = result.avg.toFixed(2);
|
||||
p5.textContent = result.p5.toString();
|
||||
p95.textContent = result.p95.toString();
|
||||
ratio.textContent = "✓";
|
||||
},
|
||||
final(ratioValue: number) {
|
||||
ratio.textContent = ratioValue.toFixed(2);
|
||||
tbody.appendChild(row);
|
||||
},
|
||||
};
|
||||
});
|
||||
|
||||
type TestResultAndRow = TestResult & { testRow: typeof testRows[0] };
|
||||
|
||||
export async function runAllTestsAsync() {
|
||||
ratioHead.textContent = "";
|
||||
const results: TestResultAndRow[] = [];
|
||||
for (const testRow of testRows) {
|
||||
testRow.begin();
|
||||
// eslint-disable-next-line no-await-in-loop
|
||||
const result = await runTestAsync(testRow.test, testRow.progress);
|
||||
testRow.end(result);
|
||||
results.push({ ...result, testRow });
|
||||
}
|
||||
|
||||
results.sort((a: TestResultAndRow, b: TestResultAndRow) => a.avg - b.avg).forEach((result: TestResultAndRow) => result.testRow.final(result.avg / results[0].avg));
|
||||
startButton.removeAttribute("disabled");
|
||||
ratioHead.textContent = "Ratio";
|
||||
console.log(`Browser: ${getBrowserInfo()}\n${resultsToMarkdown(results)}`);
|
||||
}
|
||||
|
||||
startButton.addEventListener("click", () => {
|
||||
startButton.disabled = true;
|
||||
runAllTestsAsync();
|
||||
});
|
||||
49
benchmark/index.html
Normal file
@ -0,0 +1,49 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Planck.js/Box2D Benchmark</title>
|
||||
<style>
|
||||
th, td {
|
||||
padding: 2px 5px;
|
||||
}
|
||||
table {
|
||||
border-collapse: collapse;
|
||||
margin-top: 5px;
|
||||
}
|
||||
td {
|
||||
border: 1px solid gray;
|
||||
}
|
||||
th:first-child {
|
||||
text-align: left;
|
||||
}
|
||||
progress {
|
||||
width: 200px;
|
||||
}
|
||||
textarea {
|
||||
width: 500px;
|
||||
height: 300px;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h3>Planck.js/Box2D Benchmark</h3>
|
||||
<button id="start">Start</button>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
<th>avg ms/frame</th>
|
||||
<th>5th %ile</th>
|
||||
<th>95th %ile</th>
|
||||
<th id="ratio">Ratio</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody></tbody>
|
||||
</table>
|
||||
<script src="https://kripken.github.io/box2d.js/build/Box2D_v2.3.1_min.js"></script>
|
||||
<script type="module" src="./browser.ts"></script>
|
||||
<br />
|
||||
<br />
|
||||
<span id="branch-name"></span>
|
||||
</body>
|
||||
</html>
|
||||
13
benchmark/node.ts
Normal file
@ -0,0 +1,13 @@
|
||||
import { performance } from "perf_hooks";
|
||||
global.performance = performance as any;
|
||||
|
||||
import { logResults, runAllTests } from "./benchmark";
|
||||
import type { TestFactory } from "./benchmark";
|
||||
import { planckFactory } from "./tests/planck";
|
||||
|
||||
export const tests: TestFactory[] = [
|
||||
planckFactory,
|
||||
];
|
||||
|
||||
const results = runAllTests(tests);
|
||||
logResults(results);
|
||||
42
benchmark/tests/box2d-js.ts
Normal file
@ -0,0 +1,42 @@
|
||||
import "./fixprocess";
|
||||
|
||||
const { b2Body, b2World, b2Vec2, b2EdgeShape, b2PolygonShape, b2_dynamicBody, b2BodyDef } = Box2D;
|
||||
|
||||
import type { TestFactory } from "../benchmark";
|
||||
|
||||
export const box2dJsFactory: TestFactory = (gravity, edgeV1, edgeV2, edgeDensity) => {
|
||||
let world: typeof b2World;
|
||||
let ground: typeof b2Body;
|
||||
let edgeShape: typeof b2EdgeShape;
|
||||
|
||||
return {
|
||||
name: "box2d.js",
|
||||
setup() {
|
||||
world = new b2World(new b2Vec2(gravity.x, gravity.y));
|
||||
ground = world.CreateBody(new b2BodyDef());
|
||||
edgeShape = new b2EdgeShape();
|
||||
edgeShape.Set(new b2Vec2(edgeV1.x, edgeV1.y), new b2Vec2(edgeV2.x, edgeV2.y));
|
||||
ground.CreateFixture(edgeShape as any, edgeDensity);
|
||||
},
|
||||
teardown() {
|
||||
world = null;
|
||||
ground = null;
|
||||
edgeShape = null;
|
||||
},
|
||||
createBoxShape(hx: number, hy: number) {
|
||||
const box = new b2PolygonShape();
|
||||
box.SetAsBox(hx, hy);
|
||||
return box;
|
||||
},
|
||||
createBoxBody(shape: any, x: number, y: number, density: number) {
|
||||
const bd = new b2BodyDef();
|
||||
bd.set_type(b2_dynamicBody);
|
||||
bd.set_position(new b2Vec2(x, y));
|
||||
const body = world.CreateBody(bd);
|
||||
body.CreateFixture(shape, density);
|
||||
},
|
||||
step(timeStep: number, velocityIterations: number, positionIterations: number) {
|
||||
world.Step(timeStep, velocityIterations, positionIterations);
|
||||
},
|
||||
};
|
||||
};
|
||||
19
benchmark/tests/fixprocess.ts
Normal file
@ -0,0 +1,19 @@
|
||||
// box2d.js tries to access process.stdout/err, need to emulate it
|
||||
|
||||
if ("requestAnimationFrame" in globalThis) {
|
||||
// // @ts-ignore
|
||||
// window.process.stdout = {
|
||||
// write(x: string) {
|
||||
// console.log(x);
|
||||
// return true;
|
||||
// },
|
||||
// };
|
||||
|
||||
// // @ts-ignore
|
||||
// globalThis.process.stderr = {
|
||||
// write(x: string) {
|
||||
// console.error(x);
|
||||
// return true;
|
||||
// },
|
||||
// };
|
||||
}
|
||||
39
benchmark/tests/planck.ts
Normal file
@ -0,0 +1,39 @@
|
||||
import { World, Vec2, EdgeShape, BoxShape, Body } from "../../src/index";
|
||||
|
||||
import { TestFactory } from "../benchmark";
|
||||
|
||||
export const planckFactory: TestFactory = (gravity, edgeV1, edgeV2, edgeDensity) => {
|
||||
let world: World | null = null;
|
||||
let ground: Body | null = null;
|
||||
let edgeShape: EdgeShape | null = null;
|
||||
return {
|
||||
name: "planck.js (current)",
|
||||
setup() {
|
||||
world = new World({
|
||||
gravity: new Vec2(gravity.x, gravity.y),
|
||||
});
|
||||
ground = world.createBody({});
|
||||
|
||||
edgeShape = new EdgeShape(new Vec2(edgeV1.x, edgeV1.y), new Vec2(edgeV2.x, edgeV2.y));
|
||||
ground.createFixture(edgeShape as any, edgeDensity);
|
||||
},
|
||||
createBoxShape(hx: number, hy: number) {
|
||||
return new BoxShape(hx, hy);
|
||||
},
|
||||
createBoxBody(shape: any, x: number, y: number, density: number) {
|
||||
const body = world?.createBody({
|
||||
type: "dynamic",
|
||||
position: new Vec2(x, y),
|
||||
});
|
||||
body?.createFixture(shape, density);
|
||||
},
|
||||
step(timeStep: number, velocityIterations: number, positionIterations: number) {
|
||||
world?.step(timeStep, velocityIterations, positionIterations);
|
||||
},
|
||||
teardown() {
|
||||
world = null;
|
||||
ground = null;
|
||||
edgeShape = null;
|
||||
},
|
||||
};
|
||||
};
|
||||
26
bower.json
@ -1,26 +0,0 @@
|
||||
{
|
||||
"name": "planck-js",
|
||||
"description": "2D JavaScript physics engine for cross-platform HTML5 game development",
|
||||
"keywords": [
|
||||
"html5",
|
||||
"javascript",
|
||||
"game",
|
||||
"physics",
|
||||
"engine",
|
||||
"2d",
|
||||
"mobile"
|
||||
],
|
||||
"license": "zlib",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "git://github.com/shakiba/planck.js.git"
|
||||
},
|
||||
"ignore": [
|
||||
"example/",
|
||||
"test/"
|
||||
],
|
||||
"devDependencies": {
|
||||
"stage-js": "^0.8.4",
|
||||
"font-awesome": "font-awsome#~4.5.0"
|
||||
}
|
||||
}
|
||||
4346
dist/planck-with-testbed.d.ts
vendored
Normal file
31940
dist/planck-with-testbed.js
vendored
1
dist/planck-with-testbed.js.map
vendored
Normal file
240
dist/planck-with-testbed.min.js
vendored
1
dist/planck-with-testbed.min.js.map
vendored
Normal file
16987
dist/planck-with-testbed.mjs
vendored
Normal file
1
dist/planck-with-testbed.mjs.map
vendored
Normal file
4346
dist/planck.d.ts
vendored
Normal file
26644
dist/planck.js
vendored
1
dist/planck.js.map
vendored
Normal file
52
dist/planck.min.js
vendored
1
dist/planck.min.js.map
vendored
Normal file
12144
dist/planck.mjs
vendored
Normal file
1
dist/planck.mjs.map
vendored
Normal file
|
Before Width: | Height: | Size: 4.1 KiB |
96
docs/.vitepress/config.ts
Normal file
@ -0,0 +1,96 @@
|
||||
import { defineConfig } from "vitepress";
|
||||
|
||||
// https://vitepress.dev/reference/site-config
|
||||
export default defineConfig({
|
||||
title: "Planck.js Docs",
|
||||
description: "2D Physics Engine for JavaScript",
|
||||
srcDir: "./pages",
|
||||
base: "/planck.js/docs/",
|
||||
outDir: "../dist/docs",
|
||||
themeConfig: {
|
||||
// https://vitepress.dev/reference/default-theme-config
|
||||
search: {
|
||||
provider: "local",
|
||||
},
|
||||
nav: [
|
||||
{ text: "API Reference", link: "/api/" },
|
||||
{ text: "Playground", link: "https://piqnt.com/" },
|
||||
{ text: "GitHub", link: "https://github.com/piqnt/planck.js/" },
|
||||
{ text: "Discord", link: "https://discord.gg/znjh6J7" },
|
||||
],
|
||||
sidebar: [
|
||||
{ link: "/", text: "Introduction" },
|
||||
{
|
||||
text: "Get Started",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ link: "/run-your-code", text: "Run Your Code" },
|
||||
{ link: "/hello-world", text: "Hello World" },
|
||||
{ link: "/core-concepts", text: "Core Concepts" },
|
||||
{ link: "/install", text: "Install" },
|
||||
],
|
||||
},
|
||||
|
||||
{
|
||||
text: "API Conventions",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ link: "/api-conventions/units", text: "Units" },
|
||||
{ link: "/api-conventions/factories-and-definitions", text: "Factories and Definitions" },
|
||||
{ link: "/api-conventions/implicit-destruction", text: "Implicit Destruction" },
|
||||
{ link: "/api-conventions/user-data", text: "User Data" },
|
||||
],
|
||||
},
|
||||
|
||||
{ link: "/world", text: "World" },
|
||||
{ link: "/body", text: "Body" },
|
||||
{ link: "/fixture", text: "Fixture" },
|
||||
|
||||
{
|
||||
text: "Shape",
|
||||
collapsed: true,
|
||||
link: "/shape",
|
||||
items: [
|
||||
{ link: "/shape", text: "Shape" },
|
||||
{ link: "/shape/circle", text: "Circle" },
|
||||
{ link: "/shape/polygon", text: "Polygon" },
|
||||
{ link: "/shape/edge", text: "Edge" },
|
||||
{ link: "/shape/chain", text: "Chain" },
|
||||
],
|
||||
},
|
||||
|
||||
{
|
||||
text: "Joint",
|
||||
collapsed: true,
|
||||
link: "/joint",
|
||||
items: [
|
||||
{ link: "/joint", text: "Joint" },
|
||||
{ link: "/joint/distance-joint", text: "Distance Joint" },
|
||||
{ link: "/joint/friction-joint", text: "Friction Joint" },
|
||||
{ link: "/joint/gear-joint", text: "Gear Joint" },
|
||||
{ link: "/joint/motor-joint", text: "Motor Joint" },
|
||||
{ link: "/joint/prismatic-joint", text: "Prismatic Joint" },
|
||||
{ link: "/joint/pulley", text: "Pulley" },
|
||||
{ link: "/joint/revolute-joint", text: "Revolute Joint" },
|
||||
{ link: "/joint/rope-joint", text: "Rope Joint" },
|
||||
{ link: "/joint/weld-joint", text: "Weld Joint" },
|
||||
{ link: "/joint/wheel-joint", text: "Wheel Joint" },
|
||||
{ link: "/joint/mouse-joint", text: "Mouse Joint" },
|
||||
],
|
||||
},
|
||||
|
||||
{ link: "/contacts", text: "Contacts" },
|
||||
{ link: "/collision", text: "Collision" },
|
||||
|
||||
{ link: "/world/simulation", text: "Simulation" },
|
||||
{ link: "/rendering", text: "Rendering" },
|
||||
|
||||
{ link: "/testbed", text: "Testbed" },
|
||||
|
||||
{ link: "/limitations", text: "Limitations" },
|
||||
{ link: "/api/", text: "API Reference" },
|
||||
{ link: "/references-resources", text: "References & Resources" },
|
||||
{ link: "/credits", text: "Credits & License" },
|
||||
],
|
||||
},
|
||||
});
|
||||
37
docs/pages/api-conventions/factories-and-definitions.md
Normal file
@ -0,0 +1,37 @@
|
||||
|
||||
## Factories and Definitions
|
||||
|
||||
To create a `Body` or a `Joint`, you need to call the factory functions on World:
|
||||
|
||||
```js
|
||||
body = world.createBody(bodyDef);
|
||||
joint = world.createJoint(jointDef);
|
||||
```
|
||||
|
||||
And there are corresponding destruction functions:
|
||||
|
||||
```js
|
||||
world.destroyBody(body)
|
||||
world.destroyJoint(joint)
|
||||
```
|
||||
|
||||
When you create a body or joint, you need to provide a definition. These
|
||||
definitions contain all the information needed to build the body or
|
||||
joint. By using this approach we can prevent construction errors, keep
|
||||
the number of function parameters small, provide sensible defaults, and
|
||||
reduce the number of accessors.
|
||||
|
||||
Since fixtures must be parented to a body, they are created and
|
||||
destroyed using a factory method on `Body`:
|
||||
|
||||
```js
|
||||
let fixture = body.createFixture(fixtureDef);
|
||||
body.destroyFixture(fixture);
|
||||
```
|
||||
|
||||
There is also a shortcut to create a fixture directly from the shape and
|
||||
density.
|
||||
|
||||
```js
|
||||
let fixture = body.createFixture(shape, density);
|
||||
```
|
||||
36
docs/pages/api-conventions/implicit-destruction.md
Normal file
@ -0,0 +1,36 @@
|
||||
|
||||
## Implicit Destruction
|
||||
|
||||
Often when using Planck.js you will create and destroy many bodies, shapes,
|
||||
and joints. Managing these entities is somewhat automated by Planck.js. If
|
||||
you destroy a body then all associated shapes and joints are
|
||||
automatically destroyed. This is called implicit destruction.
|
||||
|
||||
When you destroy a body, all its attached shapes, joints, and contacts
|
||||
are destroyed.
|
||||
Any body connected to one of those joints and/or contacts is woken. This process is usually
|
||||
convenient. However, you must be aware of one crucial issue:
|
||||
|
||||
> **Caution**:
|
||||
> When a body is destroyed, all fixtures and joints attached to the body
|
||||
> are automatically destroyed. You must nullify any references you have to
|
||||
> those shapes and joints. Otherwise, your program will die horribly if
|
||||
> you try to use those fixtures or joints later.
|
||||
|
||||
To help you nullify your references, Planck.js world publishes events
|
||||
(`remove-joint`, `remove-fixture`, `remove-body`) that you can listen
|
||||
to. Then the world object will notify you when an object is
|
||||
going to be implicitly destroyed.
|
||||
|
||||
```js
|
||||
world.on('remove-joint', function(joint) {
|
||||
// remove all references to joint.
|
||||
});
|
||||
world.on('remove-fixture', function(fixture) {
|
||||
// remove all references to fixture.
|
||||
});
|
||||
world.on('remove-body', function(body) {
|
||||
// bodies are not removed implicitly,
|
||||
// but the world publishes this event if a body is removed
|
||||
})
|
||||
```
|
||||
25
docs/pages/api-conventions/units.md
Normal file
@ -0,0 +1,25 @@
|
||||
|
||||
## Units
|
||||
Planck.js works with floating point numbers and tolerances have to be used to make Planck.js perform well.
|
||||
These tolerances have been tuned to work well with meters-kilogram-second (MKS) units.
|
||||
In particular, Planck.js has been tuned to work well with moving shapes between 0.1 and 10 units (meters).
|
||||
So this means objects between soup cans and buses in size should work well. Static shapes may be up to 50 meters long without trouble.
|
||||
|
||||
You should try to get your moving objects in the range 0.1 - 10 meters, with 1 meter being the sweet spot.
|
||||
|
||||
Being a 2D physics engine, it is tempting to use pixels as your units.
|
||||
This could lead to a poor simulation and possibly weird behavior.
|
||||
An object of length 200 pixels would be seen by Planck.js as the size of a 45 story building.
|
||||
|
||||
If you need to use different length units, you have two options:
|
||||
|
||||
- Use some scaling system when you render your environment and actors. It is highly recommended to use this approach to keep your physics code portable. The Planck.js testbed does this by using stage.js viewbox transform.
|
||||
|
||||
- Set Settings.lengthUnitsPerMeter accordingly. For example if a car height which is around 1.6 meter is 80 units (pixels) in in your game, value of lengthUnitsPerMeter should be set to 50 (80 / 1.6).
|
||||
|
||||
Planck.js uses radians for angles.
|
||||
The body rotation is stored in radians and may grow unbounded.
|
||||
Consider normalizing the angle of your bodies if the magnitude of the angle becomes too large (use body.setAngle).
|
||||
|
||||
> **Caution**:
|
||||
> Planck.js uses radians, not degrees.
|
||||
36
docs/pages/api-conventions/user-data.md
Normal file
@ -0,0 +1,36 @@
|
||||
|
||||
## User Data
|
||||
The `Fixture`, `Body`, and `Joint` classes allow you to attach user data.
|
||||
|
||||
This is handy to implement game-logic and rendering.
|
||||
|
||||
For example, it is typical to attach an actor reference to the rigid body
|
||||
on that actor. This sets up a circular reference. If you have the actor,
|
||||
you can get the body. If you have the body, you can get the actor.
|
||||
|
||||
```js
|
||||
let actor = gameCreateActor();
|
||||
actor.body = myWorld.createBody({
|
||||
userData: actor
|
||||
});
|
||||
```
|
||||
|
||||
For fixtures you might consider defining a user data structure that lets
|
||||
you store game specific information, such as material type, effects
|
||||
hooks, sound hooks, etc.
|
||||
|
||||
```js
|
||||
let fixture = body.createFixture({
|
||||
shape: someShape,
|
||||
userData: { materialIndex: 2 },
|
||||
});
|
||||
```
|
||||
|
||||
Keep in mind that user data is optional and you can put anything in it.
|
||||
However, you should be consistent. For example, if you want to store an
|
||||
actor reference on one body, you should keep an actor reference on all
|
||||
bodies. Don't store an actor reference on one body, and a foo reference on
|
||||
another body. Casting an actor reference to a foo reference may lead to a
|
||||
crash.
|
||||
|
||||
User data references are null by default.
|
||||
414
docs/pages/body.md
Normal file
@ -0,0 +1,414 @@
|
||||
|
||||
## Body
|
||||
Bodies have position, angle, and velocity. You can apply forces, torques, and
|
||||
impulses to bodies. Bodies can be `static`, `kinematic`, or `dynamic`. Here
|
||||
are the body type definitions:
|
||||
|
||||
- `static` -
|
||||
A static body does not move under simulation and behaves as if it has
|
||||
infinite mass. Internally, Planck.js stores zero for the mass and the
|
||||
inverse mass. Static bodies can be moved manually by the user. A static
|
||||
body always has zero velocity. Static bodies do not collide with other static
|
||||
or kinematic bodies.
|
||||
|
||||
- `kinematic` -
|
||||
A kinematic body is like a static body, but can have velocity.
|
||||
You can set kinematic body velocity or move it manually.
|
||||
However, their velocity is not changed in collision or when you apply force.
|
||||
Kinematic bodies do not collide with other kinematic or static bodies.
|
||||
When a kinematic body collides with a dynamic body it behaves as if it has infinite mass.
|
||||
|
||||
- `dynamic` -
|
||||
A dynamic body is fully simulated. They can be moved manually by the
|
||||
user, but normally they move according to forces. A dynamic body can
|
||||
collide with all body types. A dynamic body always has finite, non-zero
|
||||
mass. If you try to set the mass of a dynamic body to zero, it will
|
||||
automatically acquire a mass of one kilogram and it won't rotate.
|
||||
|
||||
Bodies are the backbone for fixtures (shapes). Bodies carry fixtures and
|
||||
move them around in the world. Bodies are always rigid bodies in Planck.js.
|
||||
That means that two fixtures attached to the same rigid body never move
|
||||
relative to each other and fixtures attached to the same body don't
|
||||
collide.
|
||||
|
||||
Fixtures have collision geometry and density. Normally, bodies acquire
|
||||
their mass properties from the fixtures. However, you can override the
|
||||
mass properties after a body is constructed.
|
||||
|
||||
You usually keep references to all the bodies you create. This way you can
|
||||
query the body positions to update the positions of your graphical
|
||||
entities. You should also keep body references so you can destroy them
|
||||
when you are done with them.
|
||||
|
||||
## Body Factory
|
||||
Bodies are created and destroyed using a body factory provided by the
|
||||
`World` class. This lets the world create the body and add the body to the
|
||||
world data structure.
|
||||
|
||||
```js
|
||||
let dynamicBody = myWorld.createBody(bodyDef);
|
||||
|
||||
// ... do stuff ...
|
||||
|
||||
myWorld.destroyBody(dynamicBody);
|
||||
```
|
||||
|
||||
> **Caution**:
|
||||
> You should never create a body directly using new. The world won't
|
||||
> know about the body and the body won't be properly initialized.
|
||||
|
||||
Planck.js does not keep a reference to the body definition or any of the
|
||||
data it holds (except user data references). So you can create temporary
|
||||
body definitions and reuse the same body definitions.
|
||||
|
||||
When you destroy a body, the attached fixtures and joints are
|
||||
automatically destroyed. This has important implications for how you
|
||||
manage shape and joint references.
|
||||
|
||||
## Body Definition
|
||||
|
||||
Let's go over some of the key members of the body definition.
|
||||
|
||||
### Body Type
|
||||
As discussed at the beginning of this chapter, there are three different
|
||||
body types: static, kinematic, and dynamic. You should specify the
|
||||
body type at creation because changing the body type later is expensive.
|
||||
|
||||
```js
|
||||
world.createBody({
|
||||
type: 'dynamic'
|
||||
});
|
||||
```
|
||||
|
||||
Default body type is static, static bodies don't move in simulations.
|
||||
|
||||
### Position and Angle
|
||||
The body definition gives you the chance to initialize the position of
|
||||
the body on creation. This has far better performance than creating the
|
||||
body at the world origin and then moving the body.
|
||||
|
||||
> **Caution**:
|
||||
> Do not create a body at the origin and then move it. If you create
|
||||
> several bodies at the origin, then performance will suffer.
|
||||
|
||||
A body has two main points of interest. The first point is the body's
|
||||
origin. Fixtures and joints are attached relative to the body's origin.
|
||||
The second point of interest is the center of mass. The center of mass
|
||||
is determined from mass distribution of the attached shapes or is
|
||||
explicitly set with `MassData`. Much of Planck.js's internal computations
|
||||
use the center of mass position. For example `Body` stores the linear
|
||||
velocity for the center of mass.
|
||||
|
||||
When you are building the body definition, you may not know where the
|
||||
center of mass is located. Therefore you specify the position of the
|
||||
body's origin. You may also specify the body's angle in radians, which
|
||||
is not affected by the position of the center of mass. If you later
|
||||
change the mass properties of the body, then the center of mass may move
|
||||
on the body, but the origin position does not change and the attached
|
||||
shapes and joints do not move.
|
||||
|
||||
```js
|
||||
world.createBody({
|
||||
position: {x: 0, y: 2}, // the body's origin position.
|
||||
angle: 0.25 * Math.PI // the body's angle in radians.
|
||||
})
|
||||
```
|
||||
|
||||
A rigid body is also a frame of reference. You can define fixtures and
|
||||
joints in that frame. Those fixtures and joint anchors never move in the
|
||||
local frame of the body.
|
||||
|
||||
### Damping
|
||||
Damping is used to reduce the world velocity of bodies. Damping is
|
||||
different than friction because friction only occurs with contact.
|
||||
Damping is not a replacement for friction and the two effects should be
|
||||
used together.
|
||||
|
||||
Damping parameters should be between 0 and infinity, with 0 meaning no
|
||||
damping, and infinity meaning full damping. Normally you will use a
|
||||
damping value between 0 and 0.1. I generally do not use linear damping
|
||||
because it makes bodies look like they are floating.
|
||||
|
||||
```js
|
||||
world.createBody({
|
||||
linearDamping: 0,
|
||||
angularDamping: 0.01
|
||||
});
|
||||
```
|
||||
|
||||
Damping is approximated for stability and performance. At small damping
|
||||
values the damping effect is mostly independent of the time step. At
|
||||
larger damping values, the damping effect will vary with the time step.
|
||||
This is not an issue if you use a fixed time step (recommended).
|
||||
|
||||
### Gravity Scale
|
||||
You can use the gravity scale to adjust the gravity on a single body. Be
|
||||
careful though, increased gravity can decrease stability.
|
||||
|
||||
```js
|
||||
// Set the gravity scale to zero so this body will float
|
||||
world.createBody({
|
||||
gravityScale: 0
|
||||
});
|
||||
```
|
||||
|
||||
### Sleep Parameters
|
||||
It is expensive to simulate bodies, so the less we have to simulate the better.
|
||||
When a body comes to rest we would like to stop simulating it.
|
||||
|
||||
When Planck.js determines that a body (or group of bodies) has come to rest,
|
||||
the body enters a sleep state which has very little CPU overhead. If a
|
||||
body is awake and collides with a sleeping body, then the sleeping body
|
||||
wakes up. Bodies will also wake up if a joint or contact attached to
|
||||
them is destroyed. You can also wake a body manually.
|
||||
|
||||
The body definition lets you specify whether a body can sleep and
|
||||
whether a body is created sleeping.
|
||||
|
||||
```js
|
||||
world.createBody({
|
||||
allowSleep: true,
|
||||
awake: true,
|
||||
});
|
||||
```
|
||||
|
||||
### Fixed Rotation
|
||||
You may want a body, such as a character, to have a fixed
|
||||
rotation. Such a body should not rotate, even under load. You can use
|
||||
the fixed rotation setting to achieve this:
|
||||
|
||||
```js
|
||||
world.createBody({
|
||||
fixedRotation: true
|
||||
});
|
||||
```
|
||||
|
||||
The fixed rotation flag causes the rotational inertia and its inverse to
|
||||
be set to zero.
|
||||
|
||||
### Bullets
|
||||
Game simulation usually generates a sequence of images that are played
|
||||
at some frame rate. This is called discrete simulation. In discrete
|
||||
simulation, rigid bodies can move by a large amount in one time step. If
|
||||
a physics engine doesn't account for the large motion, you may see some
|
||||
objects incorrectly pass through each other. This effect is called
|
||||
tunneling.
|
||||
|
||||
By default, Planck.js uses continuous collision detection (CCD) to prevent
|
||||
dynamic bodies from tunneling through static bodies. This is done by
|
||||
sweeping shapes from their old position to their new positions. The
|
||||
engine looks for new collisions during the sweep and computes the time
|
||||
of impact (TOI) for these collisions. Bodies are moved to their first
|
||||
TOI and then the solver performs a sub-step to complete the full time
|
||||
step. There may be additional TOI events within a sub-step.
|
||||
|
||||
Normally CCD is not used between dynamic bodies. This is done to keep
|
||||
performance reasonable. In some game scenarios you need dynamic bodies
|
||||
to use CCD. For example, you may want to shoot a high speed bullet at a
|
||||
stack of dynamic bricks. Without CCD, the bullet might tunnel through
|
||||
the bricks.
|
||||
|
||||
Fast moving objects in Planck.js can be labeled as bullets. Bullets will
|
||||
perform CCD with both static and dynamic bodies. You should decide what
|
||||
bodies should be bullets based on your game design. If you decide a body
|
||||
should be treated as a bullet, use the following setting.
|
||||
|
||||
```js
|
||||
world.createBody({
|
||||
bullet: true,
|
||||
});
|
||||
```
|
||||
|
||||
The bullet flag only affects dynamic bodies.
|
||||
|
||||
### Activation
|
||||
You may wish a body to be created but not participate in collision or
|
||||
dynamics. This state is similar to sleeping except the body will not be
|
||||
woken by other bodies and the body's fixtures will not be placed in the
|
||||
broad-phase. This means the body will not participate in collisions, ray
|
||||
casts, etc.
|
||||
|
||||
You can create a body in an inactive state and later re-activate it.
|
||||
|
||||
```js
|
||||
world.createBody({
|
||||
active: false,
|
||||
});
|
||||
```
|
||||
|
||||
Joints may be connected to inactive bodies. These joints will not be
|
||||
simulated. You should be careful when you activate a body that its
|
||||
joints are not distorted.
|
||||
|
||||
Note that activating a body is almost as expensive as creating the body
|
||||
from scratch. So you should not use activation for streaming worlds. Use
|
||||
creation/destruction for streaming worlds to save memory.
|
||||
|
||||
### User Data
|
||||
User data is an untyped reference. This gives you a hook to link your
|
||||
application objects to bodies.
|
||||
|
||||
```js
|
||||
world.createBody({
|
||||
userData: myActor,
|
||||
});
|
||||
```
|
||||
|
||||
## Using a Body
|
||||
After creating a body, there are many operations you can perform on the
|
||||
body. These include setting mass properties, accessing position and
|
||||
velocity, applying forces, and transforming points and vectors.
|
||||
|
||||
### Mass Data
|
||||
A body has mass (scalar), center of mass (2-vector), and rotational
|
||||
inertia (scalar). For static bodies, the mass and rotational inertia are
|
||||
set to zero. When a body has fixed rotation, its rotational inertia is
|
||||
zero.
|
||||
|
||||
Normally the mass properties of a body are established automatically
|
||||
when fixtures are added to the body. You can also adjust the mass of a
|
||||
body at run-time. This is usually done when you have special game
|
||||
scenarios that require altering the mass.
|
||||
|
||||
```js
|
||||
body.setMassData(massData);
|
||||
```
|
||||
|
||||
After setting a body's mass directly, you may wish to revert to the
|
||||
natural mass dictated by the fixtures. You can do this with:
|
||||
|
||||
```js
|
||||
body.resetMassData();
|
||||
```
|
||||
|
||||
The body's mass data is available through the following functions:
|
||||
|
||||
```js
|
||||
body.getMass(); // number
|
||||
body.getInertia(); // number
|
||||
body.getLocalCenter(); // Vec2
|
||||
body.getMassData(massData);
|
||||
```
|
||||
|
||||
### State Information
|
||||
There are many aspects to the body's state. You can access this state
|
||||
data efficiently through the following functions:
|
||||
|
||||
```js
|
||||
body.setType(bodyType);
|
||||
body.getType(); // string
|
||||
|
||||
body.setBullet(flag);
|
||||
body.isBullet(); // boolean
|
||||
|
||||
body.setSleepingAllowed(flag);
|
||||
body.isSleepingAllowed(); // boolean
|
||||
|
||||
body.setAwake(flag);
|
||||
body.isAwake(); // boolean
|
||||
|
||||
body.setEnabled(flag);
|
||||
body.isEnabled(); // boolean
|
||||
|
||||
body.setFixedRotation(flag);
|
||||
body.isFixedRotation(); // boolean
|
||||
```
|
||||
|
||||
### Position and Velocity
|
||||
You can access the position and rotation of a body. This is common when
|
||||
rendering your associated game actor. You can also set the position and rotation,
|
||||
although this is less common since you will normally use Planck.js to
|
||||
simulate movement.
|
||||
|
||||
```js
|
||||
body.setTransform(position, angle);
|
||||
body.getTransform(); // Transform
|
||||
|
||||
body.setPosition(position);
|
||||
body.getPosition(); // Vec2
|
||||
|
||||
body.setAngle(angle);
|
||||
body.getAngle(); // number
|
||||
```
|
||||
|
||||
You can access the center of mass position in local and world
|
||||
coordinates. Much of the internal simulation in Planck.js uses the center of
|
||||
mass. However, you should normally not need to access it. Instead you
|
||||
will usually work with the body transform. For example, you may have a
|
||||
body that is square. The body origin might be a corner of the square,
|
||||
while the center of mass is located at the center of the square.
|
||||
|
||||
```js
|
||||
body.getWorldCenter(); // Vec2
|
||||
body.getLocalCenter(); // Vec2
|
||||
```
|
||||
|
||||
You can access the linear and angular velocity. The linear velocity is
|
||||
for the center of mass. Therefore, the linear velocity may change if the
|
||||
mass properties change.
|
||||
|
||||
### Forces and Impulses
|
||||
You can apply forces, torques (rotational force), and impulses to a body.
|
||||
When you apply a force or an impulse, you provide a world point where the load is applied.
|
||||
This often results in a torque about the center of mass.
|
||||
|
||||
```js
|
||||
body.applyForce(force, point); // force: Vec2, point: Vec2
|
||||
body.applyTorque(torque);
|
||||
body.applyLinearImpulse(impulse, point); // force: Vec2, point: Vec2
|
||||
body.applyAngularImpulse(impulse);
|
||||
```
|
||||
|
||||
Applying a force, torque, or impulse wakes the body. Sometimes this is
|
||||
undesirable. For example, you may be applying a steady force and want to
|
||||
allow the body to sleep to improve performance. In this case you can use
|
||||
the following code.
|
||||
|
||||
```js
|
||||
if (myBody.isAwake()) {
|
||||
myBody.applyForce(myForce, myPoint);
|
||||
}
|
||||
```
|
||||
|
||||
### Coordinate Transformations
|
||||
The body class has some utility functions to help you transform points
|
||||
and vectors between local and world space.
|
||||
|
||||
A `localPoint` is a coordinate relative to the body's origin.
|
||||
A `worldPoint` is a coordinate relative to the world's origin.
|
||||
|
||||
A `localVector` is a vector between two points relative to the body's origin.
|
||||
A `worldVector` is a vector between two points relative to the world's origin.
|
||||
|
||||
Here "point" means a point's 2D coordinate, "vector" means the vector between two points.
|
||||
In point conversion both position and angle of body are considered, in vector conversion only angle.
|
||||
|
||||
```js
|
||||
body.getWorldPoint(localPoint); // Vec2
|
||||
body.getLocalPoint(worldPoint); // Vec2
|
||||
|
||||
body.getWorldVector(localVector); // Vec2
|
||||
body.getLocalVector(worldVector); // Vec2
|
||||
```
|
||||
|
||||
### Accessing Fixtures, Joints, and Contacts
|
||||
You can iterate over a body's fixtures.
|
||||
|
||||
```js
|
||||
for (let fixture = body.getFixtureList(); fixture; fixture = fixture.getNext()) {
|
||||
// do something with fixture
|
||||
}
|
||||
```
|
||||
|
||||
You can similarly iterate over the body's joint list.
|
||||
|
||||
```js
|
||||
for (var joint = this.getJointList(); joint; joint = joint.getNext()) {
|
||||
// do something with joint
|
||||
}
|
||||
```
|
||||
|
||||
The body also provides a list of associated contacts. You can use this
|
||||
to get information about the current contacts. Be careful, because the
|
||||
contact list may not contain all the contacts that existed during the
|
||||
previous time step.
|
||||
153
docs/pages/collision.md
Normal file
@ -0,0 +1,153 @@
|
||||
|
||||
## Collision
|
||||
The Collision classes include shapes and functions that operate on them.
|
||||
The module also contains a dynamic tree and broad-phase to acceleration
|
||||
collision processing of large systems.
|
||||
|
||||
The collision classes are designed to be usable outside of the dynamic
|
||||
system. For example, you can use the dynamic tree for other aspects of
|
||||
your game besides physics.
|
||||
|
||||
However, the main purpose of Planck.js is to provide a rigid body physics
|
||||
engine, so the using the collision module by itself may feel limited for
|
||||
some applications. Likewise, I will not make a strong effort to document
|
||||
it or polish the APIs.
|
||||
|
||||
### Contact Manifolds
|
||||
Planck.js has functions to compute contact points for overlapping shapes. If
|
||||
we consider circle-circle or circle-polygon, we can only get one contact
|
||||
point and normal. In the case of polygon-polygon we can get two points.
|
||||
These points share the same normal vector so Planck.js groups them into a
|
||||
manifold structure. The contact solver takes advantage of this to
|
||||
improve stacking stability.
|
||||
|
||||

|
||||
|
||||
Normally you don't need to compute contact manifolds directly, however
|
||||
you will likely use the results produced in the simulation.
|
||||
|
||||
The `Manifold` structure holds a normal vector and up to two contact
|
||||
points. The normal and points are held in local coordinates. As a
|
||||
convenience for the contact solver, each point stores the normal and
|
||||
tangential (friction) impulses.
|
||||
|
||||
The data stored in `Manifold` is optimized for internal use. If you need
|
||||
this data, it is usually best to use the `WorldManifold` structure to
|
||||
generate the world coordinates of the contact normal and points. You
|
||||
need to provide a `Manifold` and the shape transforms and radii.
|
||||
|
||||
```js
|
||||
let worldManifold = manifold.getWorldManifold(null, transformA, shapeA.m_radius, transformB, shapeB.m_radius)
|
||||
|
||||
for (let i = 0; i < manifold.pointCount; ++i) {
|
||||
let point = worldManifold.points[i]; // Vec2
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Notice that the world manifold uses the point count from the original
|
||||
manifold.
|
||||
|
||||
During simulation shapes may move and the manifolds may change. Points
|
||||
may be added or removed. You can detect this using `GetPointStates()`.
|
||||
|
||||
```js
|
||||
let state1 = []; // [PointState]
|
||||
let state2 = []; // [PointState]
|
||||
getPointStates(state1, state2, manifold1, manifold2);
|
||||
|
||||
if (state1[0] == PointState.removeState) {
|
||||
// process event
|
||||
}
|
||||
```
|
||||
|
||||
### Distance
|
||||
The `Distance` function can be used to compute the distance between two
|
||||
shapes. The distance function needs both shapes to be converted into a
|
||||
`DistanceProxy`. There is also some caching used to warm start the
|
||||
distance function for repeated calls.
|
||||
|
||||

|
||||
|
||||
### Time of Impact
|
||||
If two shapes are moving fast, they may *tunnel* through each other in a
|
||||
single time step.
|
||||
|
||||

|
||||
|
||||
The `TimeOfImpact` function is used to determine the time when two
|
||||
moving shapes collide. This is called the *time of impact* (TOI). The
|
||||
main purpose of `TimeOfImpact` is for tunnel prevention. In particular,
|
||||
it is designed to prevent moving objects from tunneling outside of
|
||||
static level geometry.
|
||||
|
||||
This function accounts for rotation and translation of both shapes,
|
||||
however if the rotations are large enough, then the function may miss a
|
||||
collision. However the function will still report a non-overlapped time
|
||||
and will capture all translational collisions.
|
||||
|
||||
The time of impact function identities an initial separating axis and
|
||||
ensures the shapes do not cross on that axis. This might miss collisions
|
||||
that are clear at the final positions. While this approach may miss some
|
||||
collisions, it is very fast and adequate for tunnel prevention.
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
It is difficult to put a restriction on the rotation magnitude. There
|
||||
may be cases where collisions are missed for small rotations. Normally,
|
||||
these missed rotational collisions should not harm game play. They tend
|
||||
to be glancing collisions.
|
||||
|
||||
The function requires two shapes (converted to `DistanceProxy`) and two
|
||||
`Sweep` structures. The sweep structure defines the initial and final
|
||||
transforms of the shapes.
|
||||
|
||||
You can use fixed rotations to perform a *shape cast*. In this case, the
|
||||
time of impact function will not miss any collisions.
|
||||
|
||||
## Dynamic Tree
|
||||
The `DynamicTree` class is used by Planck.js to organize large numbers of
|
||||
shapes efficiently. The class does not know about shapes. Instead it
|
||||
operates on axis-aligned bounding boxes (AABBs) with user data pointers.
|
||||
|
||||
The dynamic tree is a hierarchical AABB tree. Each internal node in the
|
||||
tree has two children. A leaf node is a single user AABB. The tree uses
|
||||
rotations to keep the tree balanced, even in the case of degenerate
|
||||
input.
|
||||
|
||||
The tree structure allows for efficient ray casts and region queries.
|
||||
For example, you may have hundreds of shapes in your scene. You could
|
||||
perform a ray cast against the scene in a brute force manner by ray
|
||||
casting each shape. This would be inefficient because it does not take
|
||||
advantage of shapes being spread out. Instead, you can maintain a
|
||||
dynamic tree and perform ray casts against the tree. This traverses the
|
||||
ray through the tree skipping large numbers of shapes.
|
||||
|
||||
A region query uses the tree to find all leaf AABBs that overlap a query
|
||||
AABB. This is faster than a brute force approach because many shapes can
|
||||
be skipped.
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
Normally you will not use the dynamic tree directly. Rather you will go
|
||||
through the `World` class for ray casts and region queries. If you plan
|
||||
to instantiate your own dynamic tree, you can learn how to use it by
|
||||
looking at how Planck.js uses it.
|
||||
|
||||
## Broad-phase
|
||||
Collision processing in a physics step can be divided into narrow-phase
|
||||
and broad-phase. In the narrow-phase we compute contact points between
|
||||
pairs of shapes. Imagine we have N shapes. Using brute force, we would
|
||||
need to perform the narrow-phase for N*N/2 pairs.
|
||||
|
||||
The `BroadPhase` class reduces this load by using a dynamic tree for
|
||||
pair management. This greatly reduces the number of narrow-phase calls.
|
||||
|
||||
Normally you do not interact with the broad-phase directly. Instead,
|
||||
Planck.js creates and manages a broad-phase internally. Also, BroadPhase
|
||||
is designed with Planck.js's simulation loop in mind, so it is likely not
|
||||
suited for other use cases.
|
||||
311
docs/pages/contacts.md
Normal file
@ -0,0 +1,311 @@
|
||||
|
||||
## Contacts
|
||||
Contacts are objects created by Planck.js to manage collision between two
|
||||
fixtures. If the fixture has children, such as a chain shape, then a
|
||||
contact exists for each relevant child. There are different kinds of
|
||||
contacts, derived from Contact, for managing contact between different
|
||||
kinds of fixtures. For example there is a contact class for managing
|
||||
polygon-polygon collision and another contact class for managing
|
||||
circle-circle collision.
|
||||
|
||||
Here is some terminology associated with contacts.
|
||||
|
||||
#### Contact Point
|
||||
A contact point is a point where two shapes touch. Planck.js approximates
|
||||
contact with a small number of points.
|
||||
|
||||
#### Contact Normal
|
||||
A contact normal is a unit vector that points from one shape to another.
|
||||
By convention, the normal points from fixtureA to fixtureB.
|
||||
|
||||
#### Contact Separation
|
||||
Separation is the opposite of penetration. Separation is negative when
|
||||
shapes overlap. It is possible that future versions of Planck.js will create
|
||||
contact points with positive separation, so you may want to check the
|
||||
sign when contact points are reported.
|
||||
|
||||
#### Contact Manifold
|
||||
Contact between two convex polygons may generate up to 2 contact points.
|
||||
Both of these points use the same normal, so they are grouped into a
|
||||
contact manifold, which is an approximation of a continuous region of
|
||||
contact.
|
||||
|
||||
#### Normal Impulse
|
||||
The normal force is the force applied at a contact point to prevent the
|
||||
shapes from penetrating. For convenience, Planck.js works with impulses. The
|
||||
normal impulse is just the normal force multiplied by the time step.
|
||||
|
||||
#### Tangent Impulse
|
||||
The tangent force is generated at a contact point to simulate friction.
|
||||
For convenience, this is stored as an impulse.
|
||||
|
||||
#### Contact Ids
|
||||
Planck.js tries to re-use the contact force results from a time step as the
|
||||
initial guess for the next time step. Planck.js uses contact ids to match
|
||||
contact points across time steps. The ids contain geometric features
|
||||
indices that help to distinguish one contact point from another.
|
||||
|
||||
Contacts are created when two fixture's AABBs overlap. Sometimes
|
||||
collision filtering will prevent the creation of contacts. Contacts are
|
||||
destroyed with the AABBs cease to overlap.
|
||||
|
||||
So you might gather that there may be contacts created for fixtures that
|
||||
are not touching (just their AABBs). Well, this is correct. It's a
|
||||
"chicken or egg" problem. We don't know if we need a contact object
|
||||
until one is created to analyze the collision. We could delete the
|
||||
contact right away if the shapes are not touching, or we can just wait
|
||||
until the AABBs stop overlapping. Planck.js takes the latter approach
|
||||
because it lets the system cache information to improve performance.
|
||||
|
||||
## Contact Class
|
||||
As mentioned before, the contact class is created and destroyed by
|
||||
Planck.js. Contact objects are not created by the user. However, you are
|
||||
able to access the contact class and interact with it.
|
||||
|
||||
You can access the raw contact manifold:
|
||||
|
||||
```js
|
||||
let manifold = contact.getManifold();
|
||||
```
|
||||
|
||||
You can potentially modify the manifold, but this is generally not
|
||||
supported and is for advanced usage.
|
||||
|
||||
There is a helper function to get the `WorldManifold`:
|
||||
|
||||
```js
|
||||
contact.getWorldManifold(worldManifold);
|
||||
```
|
||||
|
||||
This uses the current positions of the bodies to compute world positions
|
||||
of the contact points.
|
||||
|
||||
Sensors do not create manifolds, so for them use:
|
||||
|
||||
```js
|
||||
let touching = sensorContact.isTouching();
|
||||
```
|
||||
|
||||
This function also works for non-sensors.
|
||||
|
||||
You can get the fixtures from a contact. From those you can get the
|
||||
bodies.
|
||||
|
||||
```js
|
||||
let fixtureA = myContact.getFixtureA();
|
||||
let bodyA = fixtureA.getBody();
|
||||
let actorA = bodyA.getUserData();
|
||||
```
|
||||
|
||||
You can disable a contact. This only works inside the
|
||||
`pre-solve` event, discussed below.
|
||||
|
||||
## Accessing Contacts
|
||||
You can get access to contacts in several ways. You can access the
|
||||
contacts directly on the world and body structures. You can also
|
||||
implement a contact listener.
|
||||
|
||||
You can iterate over all contacts in the world:
|
||||
|
||||
```js
|
||||
for (let c = myWorld.getContactList(); c; c = c.getNext()) {
|
||||
// process c
|
||||
}
|
||||
```
|
||||
|
||||
You can also iterate over all the contacts on a body. These are stored
|
||||
in a graph using a contact edge structure.
|
||||
|
||||
```js
|
||||
for (let ce = myBody.getContactList(); ce; ce = ce.next) {
|
||||
let c = ce.contact;
|
||||
// process c
|
||||
}
|
||||
```
|
||||
|
||||
You can also access contacts using the contact listener that is
|
||||
described below.
|
||||
|
||||
> **Caution**:
|
||||
> Accessing contacts off World and Body may miss some transient
|
||||
> contacts that occur in the middle of the time step. Use
|
||||
> ContactListener to get the most accurate results.
|
||||
|
||||
## Contact Events
|
||||
You can receive contact data by adding event listeners to world. The
|
||||
World supports several events: begin-contact, end-contact, pre-solve,
|
||||
and post-solve.
|
||||
|
||||
```js
|
||||
world.on('begin-contact', function(contact) {
|
||||
/* handle begin event */
|
||||
});
|
||||
world.on('end-contact', function(contact) {
|
||||
/* handle end event */
|
||||
});
|
||||
world.on('pre-solve', function(contact, oldManifold) {
|
||||
/* handle pre-solve event */
|
||||
});
|
||||
world.on('post-solve', function(contact, contactImpulse) {
|
||||
/* handle post-solve event */
|
||||
});
|
||||
```
|
||||
|
||||
> **Caution**:
|
||||
> Do not keep a reference to the pointers sent to ContactListener.
|
||||
> Instead make a deep copy of the contact point data into your own buffer.
|
||||
> The example below shows one way of doing this.
|
||||
|
||||
At run-time you can create an instance of the listener and register it
|
||||
with world.on(). You can remove listener using world.off() function.
|
||||
|
||||
### Begin Contact Event
|
||||
This is called when two fixtures begin to overlap. This is called for
|
||||
sensors and non-sensors. This event can only occur inside the time step.
|
||||
|
||||
### End Contact Event
|
||||
This is called when two fixtures cease to overlap. This is called for
|
||||
sensors and non-sensors. This may be called when a body is destroyed, so
|
||||
this event can occur outside the time step.
|
||||
|
||||
### Pre-Solve Event
|
||||
This is called after collision detection, but before collision
|
||||
resolution. This gives you a chance to disable the contact based on the
|
||||
current configuration. For example, you can implement a one-sided
|
||||
platform using this callback and calling Contact.setEnabled(false).
|
||||
The contact will be re-enabled each time through collision processing,
|
||||
so you will need to disable the contact every time-step. The pre-solve
|
||||
event may be fired multiple times per time-step per contact due to
|
||||
continuous collision detection.
|
||||
|
||||
```ts
|
||||
world.on('pre-solve', function(contact: Contact, oldManifold: Manifold) {
|
||||
WorldManifold worldManifold;
|
||||
contact.getWorldManifold(&worldManifold);
|
||||
if (worldManifold.normal.y < -0.5)
|
||||
{
|
||||
contact.setEnabled(false);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
The pre-solve event is also a good place to determine the point state
|
||||
and the approach velocity of collisions.
|
||||
|
||||
```js
|
||||
world.on('pre-solve', function(contact, oldManifold) {
|
||||
let worldManifold = contact.getWorldManifold();
|
||||
|
||||
let state1 = []; // [PointState]
|
||||
let state2 = []; // [PointState]
|
||||
getPointStates(state1, state2, oldManifold, contact.getManifold());
|
||||
|
||||
if (state2[0] === PointState.addState) {
|
||||
let bodyA = contact.getFixtureA().getBody();
|
||||
let bodyB = contact.getFixtureB().getBody();
|
||||
let point = worldManifold.points[0];
|
||||
let vA = bodyA.getLinearVelocityFromWorldPoint(point);
|
||||
let vB = bodyB.getLinearVelocityFromWorldPoint(point);
|
||||
|
||||
let approachVelocity = Vec2.dot(vB -- vA, worldManifold.normal); //[todo]
|
||||
|
||||
if (approachVelocity > 1) {
|
||||
myPlayCollisionSound();
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Post-Solve Event
|
||||
The post solve event is where you can gather collision impulse results.
|
||||
If you don't care about the impulses, you should probably just implement
|
||||
the pre-solve event.
|
||||
|
||||
It is tempting to implement game logic that alters the physics world
|
||||
inside a contact callback. For example, you may have a collision that
|
||||
applies damage and try to destroy the associated actor and its rigid
|
||||
body. However, Planck.js does not allow you to alter the physics world
|
||||
inside a callback because you might destroy objects that Planck.js is
|
||||
currently processing, leading to orphaned pointers.
|
||||
|
||||
The recommended practice for processing contact points is to buffer all
|
||||
contact data that you care about and process it after the time step. You
|
||||
should always process the contact points immediately after the time
|
||||
step; otherwise some other client code might alter the physics world,
|
||||
invalidating the contact buffer. When you process the contact buffer you
|
||||
can alter the physics world, but you still need to be careful that you
|
||||
don't orphan pointers stored in the contact point buffer. The testbed
|
||||
has example contact point processing that is safe from orphaned
|
||||
pointers.
|
||||
|
||||
This code from the CollisionProcessing test shows how to handle orphaned
|
||||
bodies when processing the contact buffer. Here is an excerpt. Be sure
|
||||
to read the comments in the listing. This code assumes that all contact
|
||||
points have been buffered in the ContactPoint array m_points.
|
||||
|
||||
```js
|
||||
// We are going to destroy some bodies according to contact
|
||||
// points. We must buffer the bodies that should be destroyed
|
||||
// because they may belong to multiple contact points.
|
||||
let nuke = [];
|
||||
|
||||
// Traverse the contact results. Destroy bodies that
|
||||
// are touching heavier bodies.
|
||||
for (let i = 0; i < points.length && nuke.length < MAX_NUKE; ++i) {
|
||||
let point = points[i];
|
||||
|
||||
let body1 = point.fixtureA.getBody();
|
||||
let body2 = point.fixtureB.getBody();
|
||||
let mass1 = body1.getMass();
|
||||
let mass2 = body2.getMass();
|
||||
|
||||
if (mass1 > 0.0 && mass2 > 0.0) {
|
||||
if (mass2 > mass1) {
|
||||
nuke.push(body1);
|
||||
} else {
|
||||
nuke.push(body2);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for (let i = 0; i < nuke.length; i++) {
|
||||
let b = nuke[i];
|
||||
world.destroyBody(b);
|
||||
}
|
||||
```
|
||||
|
||||
## Contact Filtering
|
||||
Often in a game you don't want all objects to collide. For example, you
|
||||
may want to create a door that only certain characters can pass through.
|
||||
This is called contact filtering, because some interactions are filtered
|
||||
out.
|
||||
|
||||
Planck.js allows you to achieve custom contact filtering by implementing a
|
||||
ContactFilter class. This class requires you to implement a
|
||||
ShouldCollide function that receives two Shape pointers. Your function
|
||||
returns true if the shapes should collide.
|
||||
|
||||
The default implementation of ShouldCollide uses the filter-data
|
||||
defined in fixtures.
|
||||
|
||||
```js
|
||||
Fixture.prototype.shouldCollide = function(that) {
|
||||
|
||||
if (that.m_filterGroupIndex === this.m_filterGroupIndex && that.m_filterGroupIndex !== 0) {
|
||||
return that.m_filterGroupIndex > 0;
|
||||
}
|
||||
|
||||
var collideA = (that.m_filterMaskBits & this.m_filterCategoryBits) !== 0;
|
||||
var collideB = (that.m_filterCategoryBits & this.m_filterMaskBits) !== 0;
|
||||
var collide = collideA && collideB;
|
||||
return collide;
|
||||
}
|
||||
```
|
||||
|
||||
You can override it with your contact filter.
|
||||
|
||||
```js
|
||||
Fixture.prototype.shouldCollide = function(that) {
|
||||
// should this and that collide?
|
||||
}
|
||||
```
|
||||
51
docs/pages/core-concepts.md
Normal file
@ -0,0 +1,51 @@
|
||||
|
||||
## Core Concepts
|
||||
Planck.js works with several fundamental concepts and objects. We briefly
|
||||
define these objects here and more details are given later in this
|
||||
document.
|
||||
|
||||
### World
|
||||
A physics world is a collection of bodies, fixtures, and constraints that interact together.
|
||||
`World` also manages running simulation.
|
||||
|
||||
### Shape
|
||||
A shape is a 2D geometrical object, such as a circle or polygon.
|
||||
|
||||
### Rigid Body
|
||||
A chunk of matter that is so strong that the distance between any two bits of matter on the chunk is constant.
|
||||
In the following discussion we use body interchangeably with rigid body.
|
||||
|
||||
### Fixture
|
||||
A fixture binds a shape to a body and adds physical properties such as density, friction, and restitution.
|
||||
A fixture puts a shape into the collision system (broad-phase) so that it can collide with other shapes.
|
||||
|
||||
### Constraint
|
||||
A constraint is a physical connection that removes degrees of freedom from bodies.
|
||||
A 2D body has 3 degrees of freedom (two position coordinates and one rotation coordinate).
|
||||
|
||||
If we take a body and pin it to the wall (like a pendulum) we have constrained the body to the wall.
|
||||
At this point the body can only rotate about the pin, so the constraint has removed 2 degrees of freedom.
|
||||
|
||||
### Contact Constraint
|
||||
A special constraint designed to prevent penetration of rigid bodies and to simulate friction and restitution.
|
||||
You do not create contact constraints; they are created automatically when two objects might collide.
|
||||
|
||||
### Joint
|
||||
This is a constraint used to hold two or more bodies together. There are several joint types implemented in the library: revolute, prismatic, distance, and more.
|
||||
Some joints may have limits and motors.
|
||||
|
||||
A joint limit restricts the range of motion of a joint. For example, the human elbow only allows a certain range of angles.
|
||||
|
||||
A joint motor drives the motion of the connected bodies according to the joint's degrees of freedom. For example, you can use a motor to drive the rotation of an elbow.
|
||||
|
||||
### Solver
|
||||
The physics world has a solver that is used to advance time and to resolve contact and joint constraints.
|
||||
The Planck.js solver is a high-performance iterative solver that operates in order N time, where N is the number of constraints.
|
||||
|
||||
### Continuous Collision
|
||||
The solver advances bodies in time using discrete time steps. Without intervention this can lead to tunneling.
|
||||
|
||||

|
||||
|
||||
Planck.js contains specialized algorithms to deal with tunneling. First, the collision algorithms can interpolate the motion of two bodies to find the first time of impact (TOI).
|
||||
Second, there is a sub-stepping solver that moves bodies to their first time of impact and then resolves the collision.
|
||||
12
docs/pages/credits.md
Normal file
@ -0,0 +1,12 @@
|
||||
|
||||
#### Credits
|
||||
|
||||
Box2D is a popular C++ 2D rigid-body physics engine created by Erin Catto. Box2D is used in several popular games, such as Angry Birds, Limbo and Crayon Physics, as well as game development tools and libraries such as Apple's SpriteKit.
|
||||
|
||||
Planck.js is developed and maintained by Ali Shakiba.
|
||||
|
||||
TypeScript definitions for planck.js are developed by Oliver Zell.
|
||||
|
||||
#### License
|
||||
|
||||
Box2D and Planck.js are released under the MIT license. You can use them for all purposes, including commercial applications for no fee.
|
||||
191
docs/pages/fixture.md
Normal file
@ -0,0 +1,191 @@
|
||||
|
||||
## Fixture
|
||||
Shapes only have geometrical coordinates, they don't have physical properties and don't know about the body's transformation, so may be used independently of the physics simulation.
|
||||
The `Fixture` class is used to attach shapes to bodies. A body may have zero or more fixtures. A
|
||||
body with multiple fixtures is sometimes called a *compound body.*
|
||||
|
||||
Fixtures hold the following:
|
||||
- a single shape
|
||||
- broad-phase proxies
|
||||
- density, friction, and restitution
|
||||
- collision filtering flags
|
||||
- back pointer to the parent body
|
||||
- user data
|
||||
- sensor flag
|
||||
|
||||
These are described in the following sections.
|
||||
|
||||
### Fixture Creation
|
||||
Fixtures are created by initializing a fixture definition and then
|
||||
passing the definition to the parent body.
|
||||
|
||||
```js
|
||||
let myFixture = myBody.createFixture({
|
||||
shape: myShape,
|
||||
density: 1,
|
||||
});
|
||||
```
|
||||
|
||||
This creates the fixture and attaches it to the body. You do not need to
|
||||
store the fixture pointer since the fixture will automatically be
|
||||
destroyed when the parent body is destroyed. You can create multiple
|
||||
fixtures on a single body.
|
||||
|
||||
You can destroy a fixture on the parent body. You may do this to model a
|
||||
breakable object. Otherwise you can just leave the fixture alone and let
|
||||
the body destruction take care of destroying the attached fixtures.
|
||||
|
||||
```js
|
||||
myBody.destroyFixture(myFixture);
|
||||
```
|
||||
|
||||
### Density
|
||||
The fixture density is used to compute the mass properties of the parent
|
||||
body. The density can be zero or positive. You should generally use
|
||||
similar densities for all your fixtures. This will improve stacking
|
||||
stability.
|
||||
|
||||
The mass of a body is not adjusted when you set the density. You must
|
||||
call resetMassData for this to occur.
|
||||
|
||||
```js
|
||||
fixture.setDensity(5);
|
||||
body.resetMassData();
|
||||
```
|
||||
|
||||
### Friction
|
||||
Friction is used to make objects slide along each other realistically.
|
||||
Planck.js supports static and dynamic friction, but uses the same parameter
|
||||
for both. Friction is simulated accurately in Planck.js and the friction
|
||||
strength is proportional to the normal force (this is called Coulomb
|
||||
friction). The friction parameter is usually set between 0 and 1, but
|
||||
can be any non-negative value. A friction value of 0 turns off friction
|
||||
and a value of 1 makes the friction strong. When the friction force is
|
||||
computed between two shapes, Planck.js must combine the friction parameters
|
||||
of the two parent fixtures. This is done with the geometric mean:
|
||||
|
||||
```js
|
||||
function mixFriction(friction1, friction2) {
|
||||
return Math.sqrt(friction1 * friction2);
|
||||
}
|
||||
```
|
||||
|
||||
So if one fixture has zero friction then the contact will have zero
|
||||
friction.
|
||||
|
||||
You can override the default mixed friction using
|
||||
`contact.setFriction`. This is usually done in the contact listener
|
||||
callback.
|
||||
|
||||
### Restitution
|
||||
Restitution is used to make objects bounce. The restitution value is
|
||||
usually set to be between 0 and 1. Consider dropping a ball on a table.
|
||||
A value of zero means the ball won't bounce. This is called an
|
||||
inelastic collision. A value of one means the ball's velocity will be
|
||||
exactly reflected. This is called a perfectly elastic collision.
|
||||
Restitution is combined using the following formula.
|
||||
|
||||
```js
|
||||
function mixRestitution(restitution1, restitution2) {
|
||||
return Math.max(restitution1, restitution2);
|
||||
}
|
||||
```
|
||||
|
||||
Restitution is combined this way so that you can have a bouncy super
|
||||
ball without having a bouncy floor.
|
||||
|
||||
You can override the default mixed restitution using
|
||||
`contact.setRestitution`. This is usually done in the contact listener
|
||||
callback.
|
||||
|
||||
When a shape develops multiple contacts, restitution is simulated
|
||||
approximately. This is because Planck.js uses an iterative solver. Planck.js
|
||||
also uses inelastic collisions when the collision velocity is small.
|
||||
This is done to prevent jitter. See `Settings.velocityThreshold`.
|
||||
|
||||
### Filtering
|
||||
Collision filtering allows you to prevent collision between fixtures.
|
||||
For example, say you make a character that rides a bicycle. You want the
|
||||
bicycle to collide with the terrain and the character to collide with
|
||||
the terrain, but you don't want the character to collide with the
|
||||
bicycle (because they must overlap). Planck.js supports such collision
|
||||
filtering using categories and groups.
|
||||
|
||||
Planck.js supports 64 [todo?] collision categories. For each fixture you can specify
|
||||
which category it belongs to. You also specify what other categories
|
||||
this fixture can collide with. For example, you could specify in a
|
||||
multiplayer game that all players don't collide with each other and
|
||||
monsters don't collide with each other, but players and monsters should
|
||||
collide. This is done with masking bits. For example:
|
||||
|
||||
```js
|
||||
let playerFixtureDef = {
|
||||
filterCategoryBits: parseInt('010', 2),
|
||||
filterMaskBits: parseInt('100', 2),
|
||||
};
|
||||
let monsterFixtureDef = {
|
||||
filterCategoryBits: parseInt('100', 2),
|
||||
filterMaskBits: parseInt('010', 2),
|
||||
};
|
||||
```
|
||||
|
||||
Here is the rule for a collision to occur:
|
||||
|
||||
```js
|
||||
let catA = fixtureA.filterCategoryBits;
|
||||
let maskA = fixtureA.filterMaskBits;
|
||||
let catB = fixtureB.filterCategoryBits;
|
||||
let maskB = fixtureB.filterMaskBits;
|
||||
|
||||
if ((catA & maskB) !== 0 && (catB & maskA) !== 0) {
|
||||
// fixtures can collide
|
||||
}
|
||||
```
|
||||
|
||||
Collision groups let you specify an integral group index. You can have
|
||||
all fixtures with the same group index always collide (positive index)
|
||||
or never collide (negative index). Group indices are usually used for
|
||||
things that are somehow related, like the parts of a bicycle. In the
|
||||
following example, `fixture1` and `fixture2` always collide, but `fixture3`
|
||||
and `fixture4` never collide.
|
||||
|
||||
```js
|
||||
fixture1Def.filterGroupIndex = 2;
|
||||
fixture2Def.filterGroupIndex = 2;
|
||||
fixture3Def.filterGroupIndex = -8;
|
||||
fixture4Def.filterGroupIndex = -8;
|
||||
```
|
||||
|
||||
Collisions between fixtures of different group indices are filtered
|
||||
according to the category and mask bits. In other words, group filtering
|
||||
has higher precedence than category filtering.
|
||||
|
||||
Note that additional collision filtering occurs in Planck.js. Here is a
|
||||
list:
|
||||
- A fixture on a static body can only collide with a dynamic body.
|
||||
- A fixture on a kinematic body can only collide with a dynamic body.
|
||||
- Fixtures on the same body never collide with each other.
|
||||
- You can optionally enable/disable collision between fixtures on bodies connected by a joint.
|
||||
|
||||
Sometimes you might need to change collision filtering after a fixture
|
||||
has already been created. You can get and set the Filter structure on
|
||||
an existing fixture using fixture.getFilterData and
|
||||
fixture.setFilterData. Note that changing the filter data will not
|
||||
add or remove contacts until the next time step (see the World class).
|
||||
|
||||
### Sensors
|
||||
Sometimes game logic needs to know when two fixtures overlap yet there
|
||||
should be no collision response. This is done by using sensors. A sensor
|
||||
is a fixture that detects collision but does not produce a response.
|
||||
|
||||
You can flag any fixture as being a sensor. Sensors may be static,
|
||||
kinematic, or dynamic. Remember that you may have multiple fixtures per
|
||||
body and you can have any mix of sensors and solid fixtures. Also,
|
||||
sensors only form contacts when at least one body is dynamic, so you
|
||||
will not get a contact for kinematic versus kinematic, kinematic versus
|
||||
static, or static versus static.
|
||||
|
||||
Sensors do not generate contact points. There are two ways to get the
|
||||
state of a sensor:
|
||||
1. `contact.isTouching()`
|
||||
2. `begin-contact` and `end-contact` events
|
||||
104
docs/pages/hello-world.md
Normal file
@ -0,0 +1,104 @@
|
||||
|
||||
## Hello World
|
||||
|
||||
In this section we will walk through a simple example to set up the physics world, and create a platform and a small box.
|
||||
|
||||
### Creating a World
|
||||
Every Planck.js program begins with the creation of a World object.
|
||||
World is the physics hub that manages objects, their physical interactions, and runs simulation.
|
||||
|
||||
To create a world we simply create an object from the `World` class, and optionally pass gravity.
|
||||
|
||||
```js
|
||||
let world = new World({
|
||||
gravity: {x: 0, y: -10},
|
||||
});
|
||||
```
|
||||
|
||||
Now that we have our physics world set up, let's start adding some stuff to it.
|
||||
|
||||
### Creating a platform
|
||||
|
||||
We will create a platform using the following steps:
|
||||
|
||||
1. Use the world object to create the body with position.
|
||||
1. Create a fixture on the body with a shape.
|
||||
|
||||
For step 1, we pass body properties to the world object to create the platform body.
|
||||
With the body properties we specify the type and initial position of the platform:
|
||||
|
||||
```js
|
||||
let platform = world.createBody({
|
||||
type: "static",
|
||||
position: {x: 0, y: -10},
|
||||
angle: Math.PI * 0.1
|
||||
});
|
||||
```
|
||||
|
||||
Bodies are "static" by default. Static bodies don't collide with other static bodies and are immovable.
|
||||
|
||||
For step 2, we need to create a `Shape` and add it to body as `Fixture`.
|
||||
|
||||
```js
|
||||
platform.createFixture({
|
||||
shape: new Edge({x: -50, y: 0}, {x: +50, y: 0}),
|
||||
});
|
||||
```
|
||||
|
||||
Shapes only have geometrical properties (such as vertices or radius), and do not have physical properties.
|
||||
A fixture is used to add a shape to a body, and adds physical properties (such as density, friction, etc.) to a body.
|
||||
A body can have any number of shapes fixed together.
|
||||
|
||||
`Shape`'s geometrical coordinates are local to the body. A fixture does not have location and angle. So when a body moves, all fixtures/shapes in the body move with the body. However we don't move a shape around on the body.
|
||||
|
||||
Planck.js is a rigid body engine and many of the assumptions made in Planck.js are based on the rigid body model.
|
||||
A body with morphing shapes is not a rigid body, and if this is violated many things will break.
|
||||
So moving or modifying a shape that is on a body is not supported.
|
||||
|
||||
Every fixture must have a parent body, even fixtures that are static.
|
||||
However, you can attach all static fixtures to a single static body.
|
||||
|
||||
A static body has zero mass by definition, so we don't need to specify density in this case.
|
||||
Later we will see how to use a fixture's properties to customize its physical behavior.
|
||||
|
||||
### Creating a dynamic box
|
||||
Creating a dynamic box is similar to the platform. The main difference, besides dimensions, is that for a dynamic body we need to specify mass properties.
|
||||
|
||||
First we create the body using `createBody`. By default bodies are static, so we should set the body's `type` at construction time to make the body dynamic.
|
||||
|
||||
```js
|
||||
let body = world.createBody({
|
||||
type: "dynamic",
|
||||
position: {x: 0, y: 4}
|
||||
});
|
||||
```
|
||||
|
||||
> **Caution**:
|
||||
> You must set the body `type` to `dynamic` if you want the body to move in response to forces.
|
||||
|
||||
Next we create and attach a box shape using a fixture definition.
|
||||
|
||||
```js
|
||||
body.createFixture({
|
||||
shape: new Box(1.0, 1.0),
|
||||
density: 1.0,
|
||||
friction: 0.3,
|
||||
});
|
||||
```
|
||||
|
||||
Notice that we set density to 1. The default density is zero. Setting fixture's density automatically updates the mass of the body. Also, the friction on the shape is set to 0.3.
|
||||
|
||||
> **Caution**:
|
||||
> A dynamic body should have at least one fixture with a non-zero density. Otherwise you will get strange behavior.
|
||||
|
||||
You can add as many fixtures as you like to a body. Each one contributes to the total mass.
|
||||
|
||||
Box dimensions are specified as the **half-width** and **half-height** (like a circler radius).
|
||||
So in this case the ground box is 2 units wide (x-axis) and 2 units tall (y-axis).
|
||||
|
||||
### Units
|
||||
Planck.js by default is tuned for meters, kilograms, and seconds. So you can consider the dimensions to be in meters.
|
||||
Planck.js generally works best when objects are the size of typical real world objects. For example, a barrel is about 1 meter tall.
|
||||
Due to the limitations of floating point arithmetic, using Planck.js to model the movement of glaciers or dust particles is not a good idea.
|
||||
If you use a different units for your objects, you can change the value of `Settings.lengthUnitsPerMeter`.
|
||||
For example if you use pixels and a barrel height is 80 pixels set the `lengthUnitsPerMeter` to 80.
|
||||
BIN
docs/pages/images/body_origin.gif
Normal file
|
After Width: | Height: | Size: 912 B |
1
docs/pages/images/captured_toi.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="296.5" height="142.844"><path fill="none" stroke="#000" d="M.5 125.343H296v17H.5zM131.673.704l6.16 5.104-85.506 103.175-6.16-5.105z"/><path fill="none" stroke="#000" d="M145.05 3.9l7.847-1.555 26.053 131.443-7.847 1.555z"/><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="328" y="465.362" font-weight="400" font-family="Calibri" transform="translate(-245 -431.019)"><tspan x="328" y="465.362" style="line-height:1.25" font-size="12">t=0</tspan></text><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="419.5" y="465.339" font-weight="400" font-family="Calibri" transform="translate(-245 -431.019)"><tspan x="419.5" y="465.339" style="line-height:1.25" font-size="12">t=1</tspan></text><path fill="none" stroke="#000" stroke-dasharray="1,2" d="M133.627 4.619l6.888 4.068-68.14 115.381L65.486 120z"/></svg>
|
||||
|
After Width: | Height: | Size: 923 B |
1
docs/pages/images/chain_shape.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="401.76" height="216.621"><g transform="translate(-184.534 -272.828)"><path d="M187.768 435.596l66.003 30.73 70.027-17.56s66.002 36.583 70.027 38.046c4.024 1.463 84.417-38.312 84.417-38.312l104.736-34.122-76.466-98.041 58.758-35.852" fill="none" stroke="#767676" stroke-width=".76"/><circle transform="translate(-54.372 -177.182)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(11.817 -145.14)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(81.492 -163.513)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(235.876 -162.86)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(152.385 -125.513)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(341.337 -197.586)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(265.173 -295.863)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(323.653 -332.435)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="196.41" y="429.327" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan x="196.41" y="429.327" style="line-height:1.25" font-size="14">isolated</tspan></text><text y="282.35" x="502.991" style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan y="282.35" x="502.991" style="line-height:1.25" font-size="14">isolated</tspan></text></g></svg>
|
||||
|
After Width: | Height: | Size: 2.1 KiB |
BIN
docs/pages/images/convex_concave.gif
Normal file
|
After Width: | Height: | Size: 2.2 KiB |
1
docs/pages/images/distance.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="271.283" height="111.33"><path d="M178.699 69.312l-62 .473" fill="none" stroke="#000" stroke-width="1.214" stroke-dasharray="1.21355975,2.4271195"/><path d="M177.699 12.549l79-1 14 56-91 43zM36.897.81l80.641 69.26L.811 78.545z" fill="none" stroke="#000"/><path fill="#0f0" d="M176.199 65.048h7v7h-7zM113.699 65.548h7v7h-7z"/></svg>
|
||||
|
After Width: | Height: | Size: 378 B |
BIN
docs/pages/images/distance_joint.gif
Normal file
|
After Width: | Height: | Size: 2.3 KiB |
BIN
docs/pages/images/gear_joint.gif
Normal file
|
After Width: | Height: | Size: 2.1 KiB |
1
docs/pages/images/ghost_collision.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="262.63" height="103.721"><defs><marker orient="auto" refY="0" refX="0" id="a" overflow="visible"><path d="M-1.2 0l-1 1 3.5-1-3.5-1z" fill-rule="evenodd" stroke="#000" stroke-width=".2666"/></marker><marker orient="auto" refY="0" refX="0" id="b" overflow="visible"><path d="M-4 0l-2 2 7-2-7-2z" fill-rule="evenodd" stroke="#000" stroke-width=".5332"/></marker></defs><g transform="translate(-286.888 -532.208)"><path d="M289.914 613.45l255.558 1.516" fill="none" stroke="#7d7d7d" stroke-linecap="round"/><circle transform="translate(47.982 1.515)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(181.322 2.525)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(304.561 3.536)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><path fill="#d7e3f4" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round" d="M375.231 569.509h47.982v41.921h-47.982z"/><path d="M373.756 552.337h51.013" fill="none" stroke="#000" stroke-width="4" marker-end="url(#a)"/><path d="M454.548 609.915h-28.284" fill="none" stroke="#000" marker-end="url(#b)"/><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="370.221" y="541.73" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan x="370.221" y="541.73" style="line-height:1.25" font-size="14">box motion</tspan></text><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="439.286" y="606.291" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan x="439.286" y="606.291" style="line-height:1.25" font-size="14">internal normal</tspan></text><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="328.929" y="633.434" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan x="328.929" y="633.434" style="line-height:1.25" font-size="14">edge1</tspan></text><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="460.783" y="633.362" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan x="460.783" y="633.362" style="line-height:1.25" font-size="14">edge2</tspan></text></g></svg>
|
||||
|
After Width: | Height: | Size: 2.4 KiB |
1
docs/pages/images/ghost_vertices.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="248.004" height="94.101"><g transform="translate(-270.195 -531.497)"><path d="M291.786 534.505l66.428 52.5" fill="none" stroke="#7d7d7d" stroke-dasharray="1,3"/><path d="M358.214 586.648l80.715-26.072" fill="none" stroke="#7d7d7d"/><path d="M438.571 560.576l56.786 32.143" fill="none" stroke="#7d7d7d" stroke-dasharray="1,3"/><circle transform="translate(49.054 -77.413)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(116.322 -24.975)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(254.918 -18.607)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(197.061 -51.107)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="492.143" y="610.576" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan x="492.143" y="610.576" style="line-height:1.25" font-size="14">v0</tspan></text><text y="577.362" x="432.5" style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan y="577.362" x="432.5" style="line-height:1.25" font-size="14">v1</tspan></text><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="349.643" y="602.719" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan x="349.643" y="602.719" style="line-height:1.25" font-size="14">v2</tspan></text><text y="552.005" x="283.929" style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan y="552.005" x="283.929" style="line-height:1.25" font-size="14">v3</tspan></text><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="269.286" y="565.934" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan x="269.286" y="565.934" style="line-height:1.25" font-size="14">(ghost)</tspan></text><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="479.214" y="623.103" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan x="479.214" y="623.103" style="line-height:1.25" font-size="14">(ghost)</tspan></text></g></svg>
|
||||
|
After Width: | Height: | Size: 2.6 KiB |
1
docs/pages/images/manifolds.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="278.649" height="199.681"><defs><marker orient="auto" refY="0" refX="0" id="a" overflow="visible"><path d="M8.719 4.034L-2.207.016 8.719-4.002c-1.746 2.372-1.736 5.618 0 8.036z" transform="scale(-.6)" font-size="12" fill-rule="evenodd" stroke-width=".625" stroke-linejoin="round"/></marker></defs><g transform="translate(-208.193 -534.314)"><path d="M227 602.362l79-1 14 56-91 43z" fill="none" stroke="#000"/><path d="M246.198 535.123l80.642 69.26-116.727 8.476z" fill="none" stroke="#000"/><path fill="#0f0" d="M224 608.362h7v7h-7zM303.5 602.362h7v7h-7z"/><path d="M386 601.862l79-1 14 56-91 43z" fill="none" stroke="#000"/><circle transform="translate(-2 14)" cx="428.75" cy="556.612" r="34.75" fill="none" stroke="#000"/><path fill="#0f0" d="M424.5 602.862h7v7h-7z"/><path d="M264 601.362v-26.5M427.51 601.024v-26.5" fill="none" stroke="#000" marker-end="url(#a)"/><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="208" y="731.862" font-weight="400" font-family="Calibri"><tspan x="208" y="731.862" style="line-height:1.25" font-size="12">two points, one normal</tspan></text><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="378.831" y="731.862" font-weight="400" font-family="Calibri"><tspan x="378.831" y="731.862" style="line-height:1.25" font-size="12">one point, one normal</tspan></text></g></svg>
|
||||
|
After Width: | Height: | Size: 1.4 KiB |
1
docs/pages/images/missed_toi.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="296.5" height="148.657"><defs><marker orient="auto" refY="0" refX="0" id="a" overflow="visible"><path d="M8.719 4.034L-2.207.016 8.719-4.002c-1.746 2.372-1.736 5.618 0 8.036z" transform="scale(-.6)" font-size="12" fill-rule="evenodd" stroke-width=".625" stroke-linejoin="round"/></marker></defs><path fill="none" stroke="#000" d="M.5 131.157H296v17H.5zM134.187.645l7.473 2.857-47.847 125.166-7.473-2.856zM154.67 3.854l7.488-2.816L209.33 126.46l-7.487 2.816z"/><path fill="none" stroke="#000" stroke-dasharray="2,4" d="M144 4.157h8v134h-8z"/><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="340.5" y="466.362" font-weight="400" font-family="Calibri" transform="translate(-245 -425.205)"><tspan x="340.5" y="466.362" style="line-height:1.25" font-size="12">t=0</tspan></text><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="432.5" y="466.339" font-weight="400" font-family="Calibri" transform="translate(-245 -425.205)"><tspan x="432.5" y="466.339" style="line-height:1.25" font-size="12">t=1</tspan></text><path d="M500.5 556.362v-40.5" fill="none" stroke="#000" marker-end="url(#a)" transform="translate(-245 -425.205)"/><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="462.5" y="507.862" font-weight="400" font-family="Calibri" transform="translate(-245 -425.205)"><tspan x="462.5" y="507.862" style="line-height:1.25" font-size="12">separating axis</tspan></text></svg>
|
||||
|
After Width: | Height: | Size: 1.5 KiB |
1
docs/pages/images/modules.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="216.625" height="229"><defs><marker orient="auto" refY="0" refX="0" id="a" overflow="visible"><path d="M8.719 4.034L-2.207.016 8.719-4.002c-1.746 2.372-1.736 5.618 0 8.036z" transform="matrix(-1.1 0 0 -1.1 -1.1 0)" font-size="12" fill-rule="evenodd" stroke-width=".625" stroke-linejoin="round"/></marker></defs><path fill="#d7e3f4" d="M0 92h120v46H0zM96.625 0h120v46h-120z"/><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="310.137" y="351.927" font-weight="400" font-family="Calibri" transform="translate(-183 -324.362)"><tspan x="310.137" y="351.927" style="line-height:1.25" font-size="16">Common</tspan></text><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="215.793" y="442.927" font-weight="400" font-family="Calibri" transform="translate(-183 -324.362)"><tspan x="215.793" y="442.927" style="line-height:1.25" font-size="16">Collision</tspan></text><path fill="#d7e3f4" d="M96.625 183h120v46h-120z"/><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="307.945" y="535.927" font-weight="400" font-family="Calibri" transform="translate(-183 -324.362)"><tspan x="307.945" y="535.927" style="line-height:1.25" font-size="16">Dynamics</tspan></text><path d="M315.469 370.362l-48.313 46M267.422 462.362l47.781 45M339.625 370.362v137" fill="none" stroke="#000" marker-end="url(#a)" transform="translate(-183 -324.362)"/></svg>
|
||||
|
After Width: | Height: | Size: 1.4 KiB |
1
docs/pages/images/overlap_test.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="231.149" height="184.63"><g fill="none"><path stroke="#00d200" d="M22.472 67.472h19.816v16.816H22.472zM168.463 22.963h54.335v36.335h-54.335zM12.153 142.653h35.454v21.954H12.153z"/><path stroke="#000" d="M198.61 102.11h32.039v20.539H198.61z"/><path stroke="#00d200" d="M96.597 118.097h43.567v61.067H96.597zM83.016 23.516h33.728v66.228H83.016zM164.735 141.235h33.79v30.79h-33.79z"/><path stroke="#000" d="M.5.5h49.26v43.76H.5z"/><path stroke="#000" stroke-dasharray="2,4" d="M38.13 56.13h149.5v128H38.13z"/></g></svg>
|
||||
|
After Width: | Height: | Size: 562 B |
BIN
docs/pages/images/prismatic_joint.gif
Normal file
|
After Width: | Height: | Size: 2.2 KiB |
BIN
docs/pages/images/pulley_joint.gif
Normal file
|
After Width: | Height: | Size: 3.4 KiB |
1
docs/pages/images/raycast.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="248.014" height="218.692"><defs><marker orient="auto" refY="0" refX="0" id="a" overflow="visible"><path d="M8.719 4.034L-2.207.016 8.719-4.002c-1.746 2.372-1.736 5.618 0 8.036z" transform="scale(-.6)" font-size="12" fill-rule="evenodd" stroke-width=".625" stroke-linejoin="round"/></marker></defs><g fill="none" stroke="#000"><path d="M39.337 106.5h19.816v16.816H39.337zM185.328 61.991h54.335v36.335h-54.335zM29.018 181.681h35.454v21.954H29.018zM215.476 141.14h32.038v20.537h-32.038zM113.462 157.125h43.567v61.067h-43.567zM99.88 62.544h33.729v66.228H99.88zM181.6 180.263h33.79v30.791H181.6zM17.365 39.528h49.26v43.76h-49.26z"/><path d="M413.965 367.897l-219.93 175.43" stroke-dasharray="1,2" marker-end="url(#a)" transform="translate(-193.005 -367.204)"/><path d="M414.268 367.594l-86.856 69.282" marker-end="url(#a)" transform="translate(-193.005 -367.204)"/></g></svg>
|
||||
|
After Width: | Height: | Size: 917 B |
BIN
docs/pages/images/revolute_joint.gif
Normal file
|
After Width: | Height: | Size: 1.9 KiB |
1
docs/pages/images/self_intersect.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="335.57" height="156.773"><g transform="translate(-250.723 -313.047)"><path d="M253.77 466.326l70.028-17.56s71.558-119.486 75.583-118.023c4.024 1.464 78.861 117.757 78.861 117.757l104.736-34.122-76.466-98.041-191.107 74.534z" fill="none" stroke="#767676" stroke-width=".76"/><circle transform="translate(11.817 -145.14)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(81.492 -163.513)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(235.876 -162.86)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(72.583 -220.467)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(341.337 -197.586)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(265.173 -295.863)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/><circle transform="translate(157.483 -281.422)" cx="241.932" cy="611.936" r="2.525" fill="#b0ddb3" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round"/></g></svg>
|
||||
|
After Width: | Height: | Size: 1.4 KiB |
1
docs/pages/images/skin_collision.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="322.269" height="108.76"><g transform="translate(-178.071 -467.673)"><path fill="#d7e3f4" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M314.034 471.861h56.569v42.426h-56.569z"/><path d="M313.957 468.173a3.215 3.215 0 00-3.215 3.215v42.438a3.215 3.215 0 003.215 3.215h56.562a3.215 3.215 0 003.215-3.215v-42.438a3.215 3.215 0 00-3.215-3.215z" fill="none" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="1,3"/><path fill="#d7e3f4" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M319.461 520.264h53.538v47.477h-53.538z"/><path d="M319.159 517.972a3.293 3.293 0 00-3.293 3.293v47.469a3.293 3.293 0 003.293 3.293h53.531a3.293 3.293 0 003.293-3.293v-47.469a3.293 3.293 0 00-3.293-3.293z" fill="none" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="1,3"/><path d="M181.827 572.54h313.148" fill="none" stroke="#000"/><rect width="321.269" height="6.071" x="178.571" y="569.862" ry="3.036" fill="none" stroke="#7d7d7d" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="1,3"/><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="393.959" y="501.071" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0"><tspan x="393.959" y="501.071" style="line-height:1.25" font-size="14">Polygons collide</tspan><tspan x="393.959" y="518.571" style="line-height:1.25" font-size="14">with their skin</tspan></text></g></svg>
|
||||
|
After Width: | Height: | Size: 1.5 KiB |
1
docs/pages/images/skinned_polygon.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="174.87" height="149.37"><g stroke="#000"><path d="M6.367 51.331l26 47.5 57.5 43.5 77.5-70-17-61.5-70.5-4z" fill="#d7e3f4"/><path d="M80.155.506a6.436 6.436 0 00-3.055.924L3.6 45.93a6.436 6.436 0 00-2.31 8.596l26 47.5a6.436 6.436 0 001.761 2.043l57.5 43.5a6.436 6.436 0 008.198-.358l77.5-70a6.436 6.436 0 001.888-6.49l-17-61.5a6.436 6.436 0 00-5.838-4.71l-70.5-4a6.436 6.436 0 00-.644-.005z" fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="1,4"/></g></svg>
|
||||
|
After Width: | Height: | Size: 531 B |
1
docs/pages/images/tunneling1.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="274.69" height="244.503"><defs><marker orient="auto" refY="0" refX="0" id="a" overflow="visible"><path d="M-10 0l-4 4L0 0l-14-4z" fill-rule="evenodd" stroke="#000" stroke-width="1.0664"/></marker></defs><path d="M106.582.108l54.286 244.286" fill="none" stroke="#000"/><path d="M55.154 200.108l-43.71-2.695L.5 155.009l36.946-23.511 33.778 27.873zM243.756 139.675l-39.353-19.215 6.113-43.364 43.13-7.586 20.544 38.675z" fill="none" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path d="M290 413.79c27.143-48.57 84.286-68.57 144.286-51.428" fill="none" stroke="#000" stroke-width="1.8" stroke-dasharray="7.19999981,7.19999981" marker-end="url(#a)" transform="translate(-241.99 -300.825)"/><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="260" y="533.791" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0" transform="translate(-241.99 -300.825)"><tspan x="260" y="533.791" style="line-height:1.25" font-size="14">time0</tspan></text><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="466.857" y="472.076" font-weight="400" font-family="Calibri" letter-spacing="0" word-spacing="0" transform="translate(-241.99 -300.825)"><tspan x="466.857" y="472.076" style="line-height:1.25" font-size="14">time1</tspan></text></svg>
|
||||
|
After Width: | Height: | Size: 1.3 KiB |
1
docs/pages/images/tunneling2.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="234" height="101.75"><defs><marker orient="auto" refY="0" refX="0" id="a" overflow="visible"><path d="M8.719 4.034L-2.207.016 8.719-4.002c-1.746 2.372-1.736 5.618 0 8.036z" transform="scale(-.6)" font-size="12" fill-rule="evenodd" stroke-width=".625" stroke-linejoin="round"/></marker></defs><g transform="translate(-210 -490.362)"><path fill="none" stroke="#000" d="M210.5 541.862h233v13.5h-233z"/><circle transform="translate(7.5 3)" cx="295.25" cy="494.112" r="6.25" fill="none" stroke="#000"/><circle transform="translate(7.5 91.25)" cx="295.25" cy="494.112" r="6.25" fill="none" stroke="#000"/><path d="M303 505.33v71.676" fill="none" stroke="#000" stroke-width=".937" stroke-dasharray=".93691866,1.87383732" marker-end="url(#a)"/><text style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" x="319" y="499.862" font-weight="400" font-family="Calibri"><tspan x="319" y="499.862" style="line-height:1.25" font-size="12">t=0</tspan></text><text y="587.862" x="319" style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" font-weight="400" font-family="Calibri"><tspan x="319" y="587.862" style="line-height:1.25" font-size="12">t=1</tspan></text></g></svg>
|
||||
|
After Width: | Height: | Size: 1.2 KiB |
1
docs/pages/images/wheel_joint.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="69.632" height="119.937"><defs><marker orient="auto" refY="0" refX="0" id="b" overflow="visible"><path d="M8.719 4.034L-2.207.016 8.719-4.002c-1.746 2.372-1.736 5.618 0 8.036z" transform="matrix(-1.1 0 0 -1.1 -1.1 0)" font-size="12" fill-rule="evenodd" stroke-width=".625" stroke-linejoin="round"/></marker><marker orient="auto" refY="0" refX="0" id="a" overflow="visible"><path d="M8.719 4.034L-2.207.016 8.719-4.002c-1.746 2.372-1.736 5.618 0 8.036z" transform="translate(1.1) scale(1.1)" font-size="12" fill-rule="evenodd" stroke-width=".625" stroke-linejoin="round"/></marker></defs><g transform="translate(-313.07 -471.36)"><path fill="#d7e3f4" stroke="#767676" stroke-linecap="round" stroke-linejoin="round" d="M314.034 471.861h56.569v42.426h-56.569z"/><circle transform="translate(-8.571 -2.857)" cx="351.25" cy="560.755" r="16.964" fill="#d7e3f4" stroke="#767676" stroke-linecap="round" stroke-linejoin="round"/><path d="M341.786 492.362l1.428 98.929" fill="none" stroke="#000"/><circle transform="translate(134.224 67.175)" cx="208.571" cy="490.934" r="2.143"/><path d="M377.857 506.47l.536 45" fill="none" stroke="#000" marker-start="url(#a)" marker-end="url(#b)"/><path d="M308.311 578.192A23.393 23.393 0 01290.458 559a23.393 23.393 0 0111.166-23.714" transform="translate(23.393 2.5)" fill="none" stroke="#767676" marker-start="url(#a)" marker-end="url(#b)"/></g></svg>
|
||||
|
After Width: | Height: | Size: 1.4 KiB |
1
docs/pages/images/winding.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="236.532" height="176.419"><defs><marker orient="auto" refY="0" refX="0" id="b" overflow="visible"><path d="M8.719 4.034L-2.207.016 8.719-4.002c-1.746 2.372-1.736 5.618 0 8.036z" transform="scale(.6)" font-size="12" fill-rule="evenodd" stroke-width=".625" stroke-linejoin="round"/></marker><marker orient="auto" refY="0" refX="0" id="a" overflow="visible"><path d="M8.719 4.034L-2.207.016 8.719-4.002c-1.746 2.372-1.736 5.618 0 8.036z" transform="scale(-.6)" font-size="12" fill-rule="evenodd" stroke-width=".625" stroke-linejoin="round"/></marker></defs><text x="476.473" y="507.864" style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" font-weight="400" font-size="12" font-family="Calibri" transform="translate(-245.942 -381.592)">x</text><text x="482.473" y="507.864" style="line-height:0%;text-align:start" font-weight="400" font-size="13.8" font-family="Calibri" transform="translate(-245.942 -381.592)"></text><text x="387.673" y="387.193" style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" font-weight="400" font-size="12" font-family="Calibri" transform="translate(-245.942 -381.592)">y</text><text x="396.323" y="383.193" style="line-height:0%;text-align:start" font-weight="400" font-size="13.8" font-family="Calibri" transform="translate(-245.942 -381.592)"></text><text x="245.373" y="420.096" style="line-height:0%;-inkscape-font-specification:Calibri;text-align:start" font-weight="400" font-size="12" font-family="Calibri" transform="translate(-245.942 -381.592)">CCW winding</text><text x="294.623" y="397.596" style="line-height:0%;text-align:start" font-weight="400" font-size="13.8" font-family="Calibri" transform="translate(-245.942 -381.592)"></text><path d="M345.5 414.362l-56.5 34" fill="none" stroke="#000" stroke-width="1.5" marker-end="url(#a)" transform="translate(-245.942 -381.592)"/><path d="M43.558 84.77l26 47.5 57.5 43.5 77.5-70-17-61.5-70.5-4z" fill="#d7e3f4" stroke="#000"/><path d="M384 392.862v101h95.5" fill="none" stroke="#000" stroke-width="1.5" marker-start="url(#b)" marker-end="url(#a)" transform="translate(-245.942 -381.592)"/></svg>
|
||||
|
After Width: | Height: | Size: 2.1 KiB |
17
docs/pages/index.md
Normal file
@ -0,0 +1,17 @@
|
||||
|
||||
### Planck.js
|
||||
|
||||
Planck.js is JavaScript/TypeScript rewrite of the [Box2D](https://box2d.org/) C++ physics engine for cross-platform game development.
|
||||
|
||||
### Box2D
|
||||
|
||||
Box2D is a 2D rigid-body physics simulation library for games. You can use it in your games to make objects move in realistic ways and make the game world more interactive.
|
||||
From the game engine's point of view, a physics engine is just a system for procedural animation.
|
||||
|
||||
Planck.js documentation is based on the Box2D manual with adjustments and additions for JavaScript. Both projects' names are used interchangeably in the documentation.
|
||||
|
||||
### Before You Start
|
||||
|
||||
Planck.js is a physics engine, so to use the library you need to be familiar with basic physics concepts, such as mass, force, torque, and impulses. If not, you can ask ChatGPT to explain them.
|
||||
|
||||
Since Planck.js is written in JavaScript, you need to be familiar with JavaScript programming.
|
||||
70
docs/pages/install.md
Normal file
@ -0,0 +1,70 @@
|
||||
|
||||
## Install
|
||||
|
||||
Planck can be installed or downloaded from NPM or a CDN.
|
||||
|
||||
#### NPM
|
||||
|
||||
First install the package.
|
||||
```sh
|
||||
npm install planck
|
||||
```
|
||||
|
||||
Then import the library in your code:
|
||||
|
||||
```js
|
||||
import { World } from 'planck';
|
||||
|
||||
const world = new World();
|
||||
```
|
||||
|
||||
You can alternatively import planck namespace to access all classes:
|
||||
|
||||
```js
|
||||
import planck from 'planck';
|
||||
|
||||
const world = new planck.World();
|
||||
```
|
||||
|
||||
To use testbed you need to import `planck/with-testbed` instead:
|
||||
|
||||
```js
|
||||
import { World, Testbed } from 'planck/with-testbed';
|
||||
|
||||
const world = new World();
|
||||
|
||||
const testbed = Testbed.mount();
|
||||
testbed.start(world);
|
||||
```
|
||||
|
||||
|
||||
#### Script tag
|
||||
|
||||
Planck.js is available on [jsDelivr](https://www.jsdelivr.com/package/npm/planck), [cdnjs](https://cdnjs.com/libraries/planck), and [unpkg](https://unpkg.com/planck/).
|
||||
|
||||
```html
|
||||
<script src="https://cdn.jsdelivr.net/npm/planck/dist/planck.min.js"></script>
|
||||
<script>
|
||||
const { World } = planck;
|
||||
const world = new World();
|
||||
</script>
|
||||
```
|
||||
|
||||
To use testbed you need to use `planck-with-testbed.min.js` instead:
|
||||
|
||||
```html
|
||||
<html><body>
|
||||
<span id="testbed-info"></span>
|
||||
<span id="testbed-status"></span>
|
||||
<button id="testbed-play">Play</button>
|
||||
|
||||
<script src="https://cdn.jsdelivr.net/npm/planck/dist/planck-with-testbed.min.js"></script>
|
||||
<script>
|
||||
const { World, Testbed } = planck;
|
||||
const world = new World();
|
||||
|
||||
const testbed = Testbed.mount();
|
||||
testbed.start(world);
|
||||
</script>
|
||||
</body></html>
|
||||
```
|
||||
108
docs/pages/joint.md
Normal file
@ -0,0 +1,108 @@
|
||||
|
||||
## Joint
|
||||
Joints are used to constrain bodies to the world or to each other.
|
||||
Typical examples in games include ragdolls, teeters, and pulleys. Joints
|
||||
can be combined in many different ways to create interesting motions.
|
||||
|
||||
Some joints provide limits so you can control the range of motion. Some
|
||||
joints provide motors which can be used to drive the joint at a
|
||||
prescribed speed until a prescribed force/torque is exceeded.
|
||||
|
||||
Joint motors can be used in many ways. You can use motors to control
|
||||
position by specifying a joint velocity that is proportional to the
|
||||
difference between the actual and desired position. You can also use
|
||||
motors to simulate joint friction: set the joint velocity to zero and
|
||||
provide a small, but significant maximum motor force/torque. Then the
|
||||
motor will attempt to keep the joint from moving until the load becomes
|
||||
too strong.
|
||||
|
||||
### Joint Definition
|
||||
Each joint type has a definition that derives from JointDef. All
|
||||
joints are connected between two different bodies. One body may be static.
|
||||
Joints between static and/or kinematic bodies are allowed, but have no
|
||||
effect and use some processing time.
|
||||
|
||||
You can specify user data for any joint type and you can provide a flag
|
||||
to prevent the attached bodies from colliding with each other. This is
|
||||
actually the default behavior and you must set `collideConnected`
|
||||
to `true` to allow collision between two connected bodies.
|
||||
|
||||
Many joint definitions require that you provide some geometric data.
|
||||
Often a joint will be defined by anchor points. These are points fixed
|
||||
in the attached bodies. Planck.js requires these points to be specified in
|
||||
local coordinates. This way the joint can be specified even when the
|
||||
current body transforms violate the joint constraint—a common
|
||||
occurrence when a game is saved and reloaded. Additionally, some joint
|
||||
definitions need to know the default relative angle between the bodies.
|
||||
This is necessary to constrain rotation correctly.
|
||||
|
||||
Initializing the geometric data can be tedious, so many joints have a
|
||||
constructor that uses the current body transforms to remove
|
||||
much of the work. However, these initialization functions should usually
|
||||
only be used for prototyping. Production code should define the geometry
|
||||
directly. This will make joint behavior more robust.
|
||||
|
||||
The rest of the joint definition data depends on the joint type. We
|
||||
cover these now.
|
||||
|
||||
### Joint Factory
|
||||
Joints are created and destroyed using the world factory methods.
|
||||
|
||||
> **Caution**:
|
||||
> You must create and destroy bodies and joints using the create
|
||||
> and destroy methods of the World class.
|
||||
|
||||
Here's an example of the lifetime of a revolute joint:
|
||||
|
||||
```js
|
||||
let joint = myWorld.createJoint(new RevoluteJoint({
|
||||
bodyA: myBodyA,
|
||||
bodyB: myBodyB,
|
||||
anchorPoint: myBodyA.getCenterPosition(),
|
||||
}));
|
||||
|
||||
// ... do stuff ...
|
||||
|
||||
myWorld.destroyJoint(joint);
|
||||
joint = null;
|
||||
```
|
||||
|
||||
It is always good to nullify your variables after they are destroyed. This
|
||||
will make the program crash in a controlled manner if you try to reuse
|
||||
the variable.
|
||||
|
||||
The lifetime of a joint is not simple. Heed this warning well:
|
||||
|
||||
> **Caution**:
|
||||
> Joints are destroyed when an attached body is destroyed.
|
||||
|
||||
This precaution is not always necessary. You may organize your game
|
||||
engine so that joints are always destroyed before the attached bodies.
|
||||
In this case you don't need to implement the listener class. See the
|
||||
section on Implicit Destruction for details.
|
||||
|
||||
### Using Joints
|
||||
Many simulations create the joints and don't access them again until
|
||||
they are destroyed. However, there is a lot of useful data contained in
|
||||
joints that you can use to create a rich simulation.
|
||||
|
||||
First of all, you can get the bodies, anchor points, and user data from
|
||||
a joint.
|
||||
|
||||
```js
|
||||
joint.getBodyA();
|
||||
joint.getBodyB();
|
||||
joint.getAnchorA();
|
||||
joint.getAnchorB();
|
||||
joint.getUserData();
|
||||
```
|
||||
|
||||
All joints have a reaction force and torque. This the reaction force
|
||||
applied to body 2 at the anchor point. You can use reaction forces to
|
||||
break joints or trigger other game events. These functions may do some
|
||||
computations, so don't call them if you don't need the result.
|
||||
|
||||
```js
|
||||
joint.getReactionForce(inv_dt); // Vec2
|
||||
joint.getReactionTorque(inv_dt); // number
|
||||
```
|
||||
42
docs/pages/joint/distance-joint.md
Normal file
@ -0,0 +1,42 @@
|
||||
|
||||
## Distance Joint
|
||||
One of the simplest joints is a distance joint which says that the
|
||||
distance between two points on two bodies must be constant. When you
|
||||
specify a distance joint the two bodies should already be in place. Then
|
||||
you specify the two anchor points in world coordinates. The first anchor
|
||||
point is connected to body 1, and the second anchor point is connected
|
||||
to body 2. These points imply the length of the distance constraint.
|
||||
|
||||

|
||||
|
||||
Here is an example of a distance joint definition. In this case we
|
||||
decide to allow the bodies to collide.
|
||||
|
||||
```js
|
||||
new DistanceJoint({
|
||||
collideConnected: true,
|
||||
}, myBodyA, myBodyB, worldAnchorOnBodyA, worldAnchorOnBodyB);
|
||||
```
|
||||
|
||||
The distance joint can also be made soft, like a spring-damper
|
||||
connection. See the Web example in the testbed to see how this behaves.
|
||||
|
||||
Softness is achieved by tuning two constants in the definition:
|
||||
frequency and damping ratio. Think of the frequency as the frequency of
|
||||
a harmonic oscillator (like a guitar string). The frequency is specified
|
||||
in Hertz. Typically the frequency should be less than a half the
|
||||
frequency of the time step. So if you are using a 60Hz time step, the
|
||||
frequency of the distance joint should be less than 30Hz. The reason is
|
||||
related to the Nyquist frequency.
|
||||
|
||||
The damping ratio is non-dimensional and is typically between 0 and 1,
|
||||
but can be larger. At 1, the damping is critical (all oscillations
|
||||
should vanish).
|
||||
|
||||
```js
|
||||
new DistanceJoint({
|
||||
frequencyHz: 4,
|
||||
dampingRatio: 0.5,
|
||||
collideConnected: true,
|
||||
}, myBodyA, myBodyB, worldAnchorOnBodyA, worldAnchorOnBodyB);
|
||||
```
|
||||
5
docs/pages/joint/friction-joint.md
Normal file
@ -0,0 +1,5 @@
|
||||
|
||||
## Friction Joint
|
||||
The friction joint is used for top-down friction. The joint provides 2D
|
||||
translational friction and angular friction. See FrictionJoint.js and
|
||||
ApplyForce.js for details.
|
||||
44
docs/pages/joint/gear-joint.md
Normal file
@ -0,0 +1,44 @@
|
||||
|
||||
## Gear Joint
|
||||
If you want to create a sophisticated mechanical contraption you might
|
||||
want to use gears. In principle you can create gears in Planck.js by using
|
||||
compound shapes to model gear teeth. This is not very efficient and
|
||||
might be tedious to author. You also have to be careful to line up the
|
||||
gears so the teeth mesh smoothly. Planck.js has a simpler method of creating
|
||||
gears: the gear joint.
|
||||
|
||||

|
||||
|
||||
The gear joint can only connect revolute and/or prismatic joints.
|
||||
|
||||
Like the pulley ratio, you can specify a gear ratio. However, in this
|
||||
case the gear ratio can be negative. Also keep in mind that when one
|
||||
joint is a revolute joint (angular) and the other joint is prismatic
|
||||
(translation), and then the gear ratio will have units of length or one
|
||||
over length.
|
||||
|
||||
```
|
||||
coordinate1 + ratio * coordinate2 == constant
|
||||
```
|
||||
|
||||
Here is an example gear joint. The bodies myBodyA and myBodyB are any
|
||||
bodies from the two joints, as long as they are not the same bodies.
|
||||
|
||||
```js
|
||||
new GearJoint({
|
||||
bodyA: myBodyA,
|
||||
bodyB: myBodyB,
|
||||
joint1: myRevoluteJoint,
|
||||
joint2: myPrismaticJoint,
|
||||
ratio: 2 * Math.PI / myLength,
|
||||
})
|
||||
```
|
||||
|
||||
Note that the gear joint depends on two other joints. This creates a
|
||||
fragile situation. What happens if those joints are deleted?
|
||||
|
||||
> **Caution**:
|
||||
> Always delete gear joints before the revolute/prismatic joints on the
|
||||
> gears. Otherwise your code will crash in a bad way due to the orphaned
|
||||
> joint references in the gear joint. You should also delete the gear joint
|
||||
> before you delete any of the bodies involved.
|
||||
8
docs/pages/joint/motor-joint.md
Normal file
@ -0,0 +1,8 @@
|
||||
|
||||
## Motor Joint
|
||||
A motor joint lets you control the motion of a body by specifying target
|
||||
position and rotation offsets. You can set the maximum motor force and
|
||||
torque that will be applied to reach the target position and rotation.
|
||||
If the body is blocked, it will stop and the contact forces will be
|
||||
proportional the maximum motor force and torque. See MotorJoint and
|
||||
MotorJoint.h for details.
|
||||
18
docs/pages/joint/mouse-joint.md
Normal file
@ -0,0 +1,18 @@
|
||||
|
||||
## Mouse Joint
|
||||
The mouse joint is used in the testbed to manipulate bodies with the
|
||||
mouse. It attempts to drive a point on a body towards the current
|
||||
position of the cursor. There is no restriction on rotation.
|
||||
|
||||
The mouse joint definition has a target point, maximum force, frequency,
|
||||
and damping ratio. The target point initially coincides with the body's
|
||||
anchor point. The maximum force is used to prevent violent reactions
|
||||
when multiple dynamic bodies interact. You can make this as large as you
|
||||
like. The frequency and damping ratio are used to create a spring/damper
|
||||
effect similar to the distance joint.
|
||||
|
||||
Many users have tried to adapt the mouse joint for game play. Users
|
||||
often want to achieve precise positioning and instantaneous response.
|
||||
The mouse joint doesn't work very well in that context. You may wish to
|
||||
consider using kinematic bodies instead.
|
||||
|
||||
43
docs/pages/joint/prismatic-joint.md
Normal file
@ -0,0 +1,43 @@
|
||||
|
||||
## Prismatic Joint
|
||||
A prismatic joint allows for relative translation of two bodies along a
|
||||
specified axis. A prismatic joint prevents relative rotation. Therefore,
|
||||
a prismatic joint has a single degree of freedom.
|
||||
|
||||

|
||||
|
||||
The prismatic joint definition is similar to the revolute joint
|
||||
description; just substitute translation for angle, and force for torque.
|
||||
Using this analogy provides an example prismatic joint definition with a
|
||||
joint limit and a friction motor:
|
||||
|
||||
```js
|
||||
let worldAxis = new Vec2(1, 0);
|
||||
new PrismaticJoint({
|
||||
lowerTranslation: -5,
|
||||
upperTranslation: 2.5,
|
||||
enableLimit: true,
|
||||
maxMotorForce: 1,
|
||||
motorSpeed: 0,
|
||||
enableMotor: true,
|
||||
}, myBodyA, myBodyB, myBodyA.getWorldCenter(), worldAxis);
|
||||
```
|
||||
|
||||
The revolute joint has an implicit axis coming out of the screen. The
|
||||
prismatic joint needs an explicit axis parallel to the screen. This axis
|
||||
is fixed in the two bodies and follows their motion.
|
||||
|
||||
Like the revolute joint, the prismatic joint translation is zero when
|
||||
it is not defined. So be sure zero is between your
|
||||
lower and upper translation limits.
|
||||
|
||||
Using a prismatic joint is similar to using a revolute joint. Here are
|
||||
the relevant member functions:
|
||||
|
||||
```js
|
||||
prismaticJoint.getJointTranslation(); // number
|
||||
prismaticJoint.getJointSpeed(); // number
|
||||
prismaticJoint.getMotorForce(); // number
|
||||
prismaticJoint.setMotorSpeed(speed /*number*/);
|
||||
prismaticJoint.setMotorForce(force /*number*/);
|
||||
```
|
||||
51
docs/pages/joint/pulley.md
Normal file
@ -0,0 +1,51 @@
|
||||
|
||||
## Pulley Joint
|
||||
A pulley is used to create an idealized pulley. The pulley connects two
|
||||
bodies to ground and to each other. As one body goes up, the other goes
|
||||
down. The total length of the pulley rope is conserved according to the
|
||||
initial configuration.
|
||||
|
||||
```
|
||||
length1 + length2 == constant
|
||||
```
|
||||
|
||||
You can supply a ratio that simulates a block and tackle. This causes
|
||||
one side of the pulley to extend faster than the other. At the same time
|
||||
the constraint force is smaller on one side than the other. You can use
|
||||
this to create mechanical leverage.
|
||||
|
||||
```
|
||||
length1 + ratio * length2 == constant
|
||||
```
|
||||
|
||||
For example, if the ratio is 2, then `length1` will vary at twice the rate
|
||||
of `length2`. Also the force in the rope attached to `body1` will have half
|
||||
the constraint force as the rope attached to `body2`.
|
||||
|
||||

|
||||
|
||||
Pulleys can be troublesome when one side is fully extended. The rope on
|
||||
the other side will have zero length. At this point the constraint
|
||||
equations become singular (bad). You should configure collision shapes
|
||||
to prevent this.
|
||||
|
||||
Here is an example pulley definition:
|
||||
|
||||
```js
|
||||
let anchor1 = myBody1.getWorldCenter();
|
||||
let anchor2 = myBody2.getWorldCenter();
|
||||
|
||||
let groundAnchor1 = Vec2(p1.x, p1.y + 10);
|
||||
let groundAnchor2 = Vec2(p2.x, p2.y + 12);
|
||||
|
||||
let ratio = 1;
|
||||
|
||||
new PulleyJoint({}, myBody1, myBody2, groundAnchor1, groundAnchor2, anchor1, anchor2, ratio);
|
||||
```
|
||||
|
||||
Pulley joints provide the current lengths.
|
||||
|
||||
```js
|
||||
pulleyJoint.getLengthA(); // number
|
||||
pulleyJoint.getLengthB(); // number
|
||||
```
|
||||
106
docs/pages/joint/revolute-joint.md
Normal file
@ -0,0 +1,106 @@
|
||||
|
||||
## Revolute Joint
|
||||
A revolute joint forces two bodies to share a common anchor point, often
|
||||
called a hinge point. The revolute joint has a single degree of freedom:
|
||||
the relative rotation of the two bodies. This is called the joint angle.
|
||||
|
||||

|
||||
|
||||
To specify a revolute you need to provide two bodies and a single anchor
|
||||
point in world space. The initialization function assumes that the
|
||||
bodies are already in the correct position.
|
||||
|
||||
In this example, two bodies are connected by a revolute joint at the
|
||||
first body's center of mass.
|
||||
|
||||
```js
|
||||
new RevoluteJoint({}, myBodyA, myBodyB, myBodyA.getWorldCenter());
|
||||
```
|
||||
|
||||
The revolute joint angle is positive when bodyB rotates CCW about the
|
||||
angle point. Like all angles in Planck.js, the revolute angle is measured in
|
||||
radians. By convention the revolute joint angle is zero if it not specified,
|
||||
regardless of the current rotation of the two bodies.
|
||||
|
||||
In some cases you might wish to control the joint angle. For this, the
|
||||
revolute joint can optionally simulate a joint limit and/or a motor.
|
||||
|
||||
A joint limit forces the joint angle to remain between a lower and upper
|
||||
bound. The limit will apply as much torque as needed to make this
|
||||
happen. The limit range should include zero, otherwise the joint will
|
||||
lurch when the simulation begins.
|
||||
|
||||
A joint motor allows you to specify the joint speed (the time derivative
|
||||
of the angle). The speed can be negative or positive. A motor can have
|
||||
infinite force, but this is usually not desirable. Recall the eternal
|
||||
question:
|
||||
|
||||
> *What happens when an irresistible force meets an immovable object?*
|
||||
|
||||
I can tell you it's not pretty. So you can provide a maximum torque for
|
||||
the joint motor. The joint motor will maintain the specified speed
|
||||
unless the required torque exceeds the specified maximum. When the
|
||||
maximum torque is exceeded, the joint will slow down and can even
|
||||
reverse.
|
||||
|
||||
You can use a joint motor to simulate joint friction. Just set the joint
|
||||
speed to zero, and set the maximum torque to some small, but significant
|
||||
value. The motor will try to prevent the joint from rotating, but will
|
||||
yield to a significant load.
|
||||
|
||||
Here's a revision of the revolute joint definition above; this time the
|
||||
joint has a limit and a motor enabled. The motor is setup to simulate
|
||||
joint friction.
|
||||
|
||||
```js
|
||||
new RevoluteJoint({
|
||||
lowerAngle: -0.5 * Math.PI, // -90 degrees
|
||||
upperAngle: 0.25 * Math.PI, // 45 degrees
|
||||
enableLimit: true,
|
||||
maxMotorTorque: 10,
|
||||
motorSpeed: 0,
|
||||
enableMotor: true,
|
||||
}, myBodyA, myBodyB, myBodyA.getWorldCenter());
|
||||
|
||||
```
|
||||
You can access a revolute joint's angle, speed, and motor torque.
|
||||
|
||||
```js
|
||||
revoluteJoint.getJointAngle(); // number
|
||||
revoluteJoint.getJointSpeed(); // number
|
||||
revoluteJoint.getMotorTorque(); // number
|
||||
```
|
||||
|
||||
You also update the motor parameters each step.
|
||||
|
||||
```js
|
||||
revoluteJoint.setMotorSpeed(speed /*number*/);
|
||||
revoluteJoint.setMaxMotorTorque(torque /*number*/);
|
||||
```
|
||||
|
||||
Joint motors have some interesting abilities. You can update the joint
|
||||
speed every time step so you can make the joint move back-and-forth like
|
||||
a sine-wave or according to whatever function you want.
|
||||
|
||||
```js
|
||||
// ... Game Loop Begin ...
|
||||
|
||||
myJoint.setMotorSpeed(Math.cos(0.5 * time));
|
||||
|
||||
// ... Game Loop End ...
|
||||
```
|
||||
|
||||
You can also use joint motors to track a desired joint angle. For example:
|
||||
|
||||
```js
|
||||
// ... Game Loop Begin ...
|
||||
|
||||
let angleError = myJoint.getJointAngle() - angleTarget;
|
||||
let gain = 0.1;
|
||||
myJoint.setMotorSpeed(-gain * angleError);
|
||||
|
||||
// ... Game Loop End ...
|
||||
```
|
||||
|
||||
Generally your gain parameter should not be too large. Otherwise your
|
||||
joint may become unstable.
|
||||
5
docs/pages/joint/rope-joint.md
Normal file
@ -0,0 +1,5 @@
|
||||
|
||||
## Rope Joint
|
||||
The rope joint restricts the maximum distance between two points. This
|
||||
can be useful to prevent chains of bodies from stretching, even under
|
||||
high load. See RopeJoint.js and RopeJoint.js for details.
|
||||
14
docs/pages/joint/weld-joint.md
Normal file
@ -0,0 +1,14 @@
|
||||
|
||||
## Weld Joint
|
||||
The weld joint attempts to constrain all relative motion between two
|
||||
bodies. See the Cantilever.js in the testbed to see how the weld joint
|
||||
behaves.
|
||||
|
||||
It is tempting to use the weld joint to define breakable structures.
|
||||
However, the Planck.js solver is iterative so the joints are a bit soft. So
|
||||
chains of bodies connected by weld joints will flex.
|
||||
|
||||
Instead it is better to create breakable bodies starting with a single
|
||||
body with multiple fixtures. When the body breaks, you can destroy a
|
||||
fixture and recreate it on a new body. See the Breakable example in the
|
||||
testbed.
|
||||
6
docs/pages/joint/wheel-joint.md
Normal file
@ -0,0 +1,6 @@
|
||||
|
||||
## Wheel Joint
|
||||
The wheel joint restricts a point on bodyB to a line on bodyA. The wheel
|
||||
joint also provides a suspension spring. See WheelJoint class, and Car example for details.
|
||||
|
||||

|
||||
64
docs/pages/limitations.md
Normal file
@ -0,0 +1,64 @@
|
||||
|
||||
## Limitations
|
||||
Planck.js uses several approximations to simulate rigid body physics
|
||||
efficiently. This brings some limitations.
|
||||
|
||||
Here are the current limitations:
|
||||
1. Stacking heavy bodies on top of much lighter bodies is not stable. Stability degrades as the mass ratio passes 10:1.
|
||||
2. Chains of bodies connected by joints may stretch if a lighter body is supporting a heavier body. For example, a wrecking ball connect to a chain of light weight bodies may not be stable. Stability degrades as the mass ratio passes 10:1.
|
||||
3. There is typically around 0.5cm of slop in shape versus shape collision.
|
||||
4. Continuous collision does not handle joints. So you may see joint stretching on fast moving objects.
|
||||
5. Planck.js uses the symplectic Euler integration scheme. It does not reproduce parabolic motion of projectiles and has only first-order accuracy. However it is fast and has good stability.
|
||||
6. Planck.js uses an iterative solver to provide real-time performance. You will not get precisely rigid collisions or pixel perfect accuracy. Increasing the iterations will improve accuracy.
|
||||
|
||||
## Accuracy
|
||||
|
||||
Box2D/Planck.js uses approximate methods for a few reasons.
|
||||
|
||||
* Performance
|
||||
* Some differential equations don't have known solutions
|
||||
* Some constraints cannot be determined uniquely
|
||||
|
||||
What this means is that constraints are not perfectly rigid and sometimes you will see some bounce even when the restitution is zero.
|
||||
Box2D/Planck.js uses Gauss-Seidel to approximately solve constraints.
|
||||
Box2D/Planck.js also uses Semi-implicit Euler to approximately solve the differential equations.
|
||||
Box2D/Planck.js also does not have exact collision. Polygons are covered with a thin skin (around 0.5cm thick) to avoid numerical problems. This can sometimes lead to unexpected contact normals. Also, some shapes may begin to overlap and then be pushed apart by the solver.
|
||||
|
||||
|
||||
## Restitution/Friction mixing accuracy
|
||||
|
||||
A physically correct restitution value must be measured in experiments.
|
||||
But as soon as you change the geometry from the experiment then the value is wrong.
|
||||
Next, adding simultaneous collision makes the answer worse.
|
||||
|
||||
## Determinism
|
||||
|
||||
For the same input, and same javascript runtime, Box2D/Planck.js will reproduce any simulation.
|
||||
Box2D/Planck.js does not use any random numbers nor base any computation on random events (such as timers, etc).
|
||||
|
||||
However, people often want more stringent determinism.
|
||||
People often want to know if Box2D/Planck.js can produce identical results on different binaries and on different platforms. The answer is no. The reason for this answer has to do with how floating point math is implemented in many compilers and processors. I recommend reading this article if you are curious: http://www.yosefk.com/blog/consistency-how-to-defeat-the-purpose-of-ieee-floating-point.html
|
||||
|
||||
This naturally leads to the question of fixed-point math.
|
||||
Box2D/Planck.js does not support fixed-point math.
|
||||
In the past Box2D was ported to the NDS in fixed-point and apparently it worked okay.
|
||||
Fixed-point math is slower and more tedious to develop, so fixed-point is used for the development of Box2D.
|
||||
|
||||
## Making Games
|
||||
|
||||
### Worms Clones
|
||||
|
||||
Making a worms clone requires arbitrarily destructible terrain.
|
||||
This is beyond the scope of Box2D/Planck.js, so you will have to figure out how to do this on your own.
|
||||
|
||||
### Tile Based Environment
|
||||
|
||||
Using many boxes for your terrain may not work well because box-like characters can get snagged on internal corners.
|
||||
A future update to Box2D/Planck.js should allow for smooth motion over edge chains.
|
||||
In general you should avoid using a rectangular character because collision tolerances will still lead to undesirable snagging.
|
||||
|
||||
### Asteroid Type Coordinate Systems
|
||||
|
||||
Box2D/Planck.js does not have any support for coordinate frame wrapping.
|
||||
You would likely need to customize Box2D/Planck.js for this purpose.
|
||||
You may need to use a different broad-phase for this to work.
|
||||
22
docs/pages/references-resources.md
Normal file
@ -0,0 +1,22 @@
|
||||
|
||||
### References
|
||||
- [Erin Catto's Publications](https://box2d.org/publications/)
|
||||
- Collision Detection in Interactive 3D Environments, Gino van den Bergen, 2004
|
||||
- Real-Time Collision Detection, Christer Ericson, 2005
|
||||
|
||||
Box2D was created as part of a physics tutorial at the Game Developer
|
||||
Conference. You can get these tutorials from the download section of
|
||||
box2d.org.
|
||||
|
||||
|
||||
### More Resources
|
||||
|
||||
After learning Planck.js basics and how to run your code, there are plenty of Box2D resources available online to learn advanced topics. Here are few great examples:
|
||||
|
||||
- [iforce2d](https://www.iforce2d.net/b2dtut/) - A collection of helpful Box2D tutorials
|
||||
- Box2D [tutorials](https://www.emanueleferonato.com/category/box2d/) by Emanuele Feronato
|
||||
|
||||
|
||||
If are interested in learning about algorithms used in Box2D/Planck.js following resources are helpful.
|
||||
|
||||
- [dyn4j Blog Posts](http://www.dyn4j.org/category/gamedev/) by William Bittle
|
||||
126
docs/pages/rendering.md
Normal file
@ -0,0 +1,126 @@
|
||||
|
||||
## Rendering
|
||||
|
||||
Planck.js is a physics engine and it can be used with any graphics library or ui framework for rendering.
|
||||
|
||||
For development and debugging you can use the [Testbed](./testbed) that is provided with the library. For production you can use an existing integration or create a new one.
|
||||
|
||||
To run simulation and renderer physics objects you need to do the following:
|
||||
- Advance physics simulation by calling `world.step(timeStep)` in each frame
|
||||
- Iterate over world entities to draw or update them
|
||||
- Optionally listen to world events for objects which are removed from simulation and remove them from rendering
|
||||
|
||||
```js
|
||||
class Renderer {
|
||||
world = null;
|
||||
started = false;
|
||||
|
||||
start(world) {
|
||||
this.world = world;
|
||||
|
||||
// Add listeners
|
||||
world.on('remove-body', this.removeBody);
|
||||
world.on('remove-joint', this.removeJoint);
|
||||
world.on('remove-fixture', this.removeFixture);
|
||||
|
||||
// Start frame loop
|
||||
this.started = true;
|
||||
this.loop(0);
|
||||
}
|
||||
|
||||
stop() {
|
||||
// Remove listeners
|
||||
world.off('remove-body', this.removeBody);
|
||||
world.off('remove-joint', this.removeJoint);
|
||||
world.off('remove-fixture', this.removeFixture);
|
||||
|
||||
// Stop next frame
|
||||
this.started = false;
|
||||
}
|
||||
|
||||
// Game loop
|
||||
loop = (timeStamp) => {
|
||||
if (!this.started) {
|
||||
return;
|
||||
}
|
||||
|
||||
// In each frame call world.step with fixed timeStep
|
||||
// This is a simplified implementation, in a more advanced implementation
|
||||
// you need to use elapsed time since last frame and call step more than once if needed.
|
||||
// When called by requestAnimationFrame() you'll get a timestamp as argument,
|
||||
// https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
|
||||
this.world.step(1 / 60);
|
||||
|
||||
// Iterate over bodies
|
||||
for (let body = this.world.getBodyList(); body; body = body.getNext()) {
|
||||
this.renderBody(body);
|
||||
// ... and fixtures
|
||||
for (let fixture = body.getFixtureList(); fixture; fixture = fixture.getNext()) {
|
||||
this.renderFixture(fixture);
|
||||
}
|
||||
}
|
||||
|
||||
// Iterate over joints
|
||||
for (let joint = this.world.getJointList(); joint; joint = joint.getNext()) {
|
||||
this.renderJoint(joint);
|
||||
}
|
||||
|
||||
// Request a new frame
|
||||
window.requestAnimationFrame(this.loop);
|
||||
}
|
||||
|
||||
renderBody(body) {
|
||||
// Render or update body rendering
|
||||
}
|
||||
|
||||
renderFixture(fixture) {
|
||||
// Render or update fixture rendering
|
||||
}
|
||||
|
||||
renderJoint(joint) {
|
||||
// Render or update joint rendering
|
||||
}
|
||||
|
||||
removeBody(body) {
|
||||
// Remove body rendering
|
||||
}
|
||||
|
||||
removeFixture(fixture) {
|
||||
// Remove fixture rendering
|
||||
}
|
||||
|
||||
removeJoint(joint) {
|
||||
// Remove joint from rendering
|
||||
}
|
||||
}
|
||||
|
||||
const renderer = new Renderer();
|
||||
|
||||
renderer.start(world);
|
||||
|
||||
```
|
||||
|
||||
### Pixels and Coordinate Systems
|
||||
|
||||
Planck.js uses MKS (meters, kilograms, and seconds) units and
|
||||
radians for angles, however rendering is done in pixels.
|
||||
So you need to transformation world geometry into screen and vice versa.
|
||||
|
||||
You should consider using MKS units in your game code and find a scale to convert
|
||||
to pixels when you render. This will simplify your game logic and reduce
|
||||
the chance for errors since the rendering conversion can be isolated to
|
||||
a small amount of code.
|
||||
|
||||
If you use a conversion factor, you should try tweaking it globally to
|
||||
make sure nothing breaks. You can also try adjusting it to improve
|
||||
stability.
|
||||
|
||||
### Existing Integration Projects
|
||||
|
||||
- [notchris/phaser3-planck](https://github.com/notchris/phaser3-planck) Phaser 3 Planck.js Plugin by Chris McGrane
|
||||
- [Phaser 3 with Planck.js](https://www.emanueleferonato.com/2019/10/12/use-box2d-physics-in-your-phaser-3-projects-with-planck-js-javascript-physics-engine/) by Emanuele Feronato
|
||||
- [P5Play](https://p5play.org/) - A game engine based on P5.js and Planck.js, by Quinton Ashley and Paolo Pedercini
|
||||
- [P5.js integration](https://sites.google.com/site/professorcookga/planck-box2d-physics-for-javascript-p5) by Professor Robert Cook
|
||||
- [Modd.io](https://www.modd.io/) - Online io game platform
|
||||
- [KaPlanck](https://github.com/KeSuave/KaPlanck) - Physics extension for KaPlay
|
||||
- [RealPeha/planck-renderer](https://github.com/RealPeha/planck-renderer)
|
||||
11
docs/pages/run-your-code.md
Normal file
@ -0,0 +1,11 @@
|
||||
|
||||
## Run Your Code
|
||||
|
||||
Planck.js is a physics simulation library, and it doesn't draw anything.
|
||||
|
||||
[Piqnt](https://piqnt.com/) is an online playground for Planck.js. You can explore [examples](https://piqnt.com/planck.js/), inspect and edit them, or create new ones.
|
||||
|
||||
[Testbed](./testbed) is a simple tool (included in the project repository) to visualize and interact with physics simulation. Testbed is compatible with Piqnt playground.
|
||||
|
||||
You can use Planck.js with any game engines or frameworks, or use an existing integrations. See [Simulation](./world/simulation) and [Rendering](./rendering) page for more information.
|
||||
|
||||
91
docs/pages/shape.md
Normal file
@ -0,0 +1,91 @@
|
||||
|
||||
## Shape
|
||||
|
||||
Shapes describe collision geometry and may be used independently of
|
||||
physics simulation. At a minimum, you should understand how to create
|
||||
shapes that can be later attached to rigid bodies.
|
||||
|
||||
Planck.js shapes implement the Shape base class. The base class defines
|
||||
functions to:
|
||||
- Test a point for overlap with the shape.
|
||||
- Perform a ray cast against the shape.
|
||||
- Compute the shape's AABB.
|
||||
- Compute the mass properties of the shape.
|
||||
|
||||
In addition, each shape has a type member and a radius. The radius even
|
||||
applies to polygons, as discussed below.
|
||||
|
||||
Keep in mind that a shape does not know about bodies and stand apart
|
||||
from the dynamics system. In Planck.js shapes are considered immutable.
|
||||
When a shape is attached to a body using a fixture, the
|
||||
shapes move rigidly with the host body. In summary:
|
||||
- When a shape is **not** attached to a body, you can view its vertices as being expressed in world-space.
|
||||
- When a shape is attached to a body, you can view its vertices as being expressed in local coordinates.
|
||||
|
||||
### Geometric Queries
|
||||
|
||||
You can perform a couple geometric queries on a single shape.
|
||||
|
||||
#### Shape Point Test
|
||||
|
||||
You can test a point for overlap with a shape. You provide a transform
|
||||
for the shape and a world point.
|
||||
|
||||
```js
|
||||
let transform = Transform.identity();
|
||||
let point = Vec2(5, 2);
|
||||
|
||||
let hit = shape.testPoint(transform, point);
|
||||
```
|
||||
|
||||
Edge and chain shapes always return false, even if the chain is a loop.
|
||||
|
||||
#### Shape Ray Cast
|
||||
|
||||
You can cast a ray at a shape to get the point of first intersection and normal
|
||||
vector. A child index is included for chain shapes because the ray cast will
|
||||
only check a single edge at a time.
|
||||
|
||||
> **Caution**:
|
||||
> No hit will register if the ray starts inside a convex shape like a circle or
|
||||
> polygon. This is consistent with Planck.js treating convex shapes as solid.
|
||||
>
|
||||
|
||||
```js
|
||||
let transform = Transform.identity();
|
||||
|
||||
let input = {}; // RayCastInput
|
||||
input.p1 = Vec2(0, 0);
|
||||
input.p2 = Vec2(1, 0);
|
||||
input.maxFraction = 1;
|
||||
let childIndex = 0;
|
||||
|
||||
let output = {}; // RayCastOutput
|
||||
let hit = shape.RayCast(output, input, transform, childIndex);
|
||||
|
||||
if (hit) {
|
||||
let hitPoint = Vec2.add(
|
||||
Vec2.mul(1 - output.fraction, input.p1),
|
||||
Vec2.mul(output.fraction, input.p2)
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
#### Pairwise Functions
|
||||
|
||||
The Collision module contains functions that take a pair of shapes and compute some results. These include:
|
||||
- Overlap
|
||||
- Contact manifolds
|
||||
- Distance
|
||||
- Time of impact
|
||||
|
||||
#### Overlap
|
||||
|
||||
You can test two shapes for overlap using this function:
|
||||
|
||||
```js
|
||||
Transform xfA = ..., xfB = ...;
|
||||
bool overlap = TestOverlap(shapeA, indexA, shapeB, indexB, xfA, xfB);
|
||||
```
|
||||
|
||||
Again you must provide child indices for the case of chain shapes.
|
||||
56
docs/pages/shape/chain.md
Normal file
@ -0,0 +1,56 @@
|
||||
|
||||
## Chain Shapes
|
||||
|
||||
The chain shape provides an efficient way to connect many edges together
|
||||
to construct your static game worlds. Chain shapes automatically
|
||||
eliminate ghost collisions and provide two-sided collision.
|
||||
|
||||

|
||||
|
||||
```js
|
||||
// This is a chain shape with isolated vertices
|
||||
let vs = [
|
||||
Vec2(1.7, 0),
|
||||
Vec2(1, 0.25),
|
||||
Vec2(0, 0),
|
||||
Vec2(-1.7, 0.4)
|
||||
];
|
||||
|
||||
let chain = new Chain(vs);
|
||||
```
|
||||
|
||||
You may have a scrolling game world and would like to connect several
|
||||
chains together. You can connect chains together using ghost vertices,
|
||||
like we did with EdgeShape.
|
||||
|
||||
```js
|
||||
// Install ghost vertices
|
||||
chain.setPrevVertex(Vec2(3, 1));
|
||||
chain.setNextVertex(Vec2(-2, 0));
|
||||
```
|
||||
|
||||
You may also create loops automatically.
|
||||
|
||||
```js
|
||||
// Create a loop. The first and last vertices are connected.
|
||||
let chain = new Chain(vs, true);
|
||||
```
|
||||
|
||||
Self-intersection of chain shapes is not supported. It might work, it
|
||||
might not. The code that prevents ghost collisions assumes there are no
|
||||
self-intersections of the chain. Also, very close vertices can cause
|
||||
problems. Make sure all your edges are longer than Settings.linearSlop (5mm).
|
||||
|
||||

|
||||
|
||||
Each edge in the chain is treated as a child shape and can be accessed
|
||||
by index. When a chain shape is connected to a body, each edge gets its
|
||||
own bounding box in the broad-phase collision tree.
|
||||
|
||||
```js
|
||||
// Visit each child edge.
|
||||
for (let i = 0; i < chain.getChildCount(); ++i) {
|
||||
let edge = new Edge();
|
||||
chain.getChildEdge(edge, i);
|
||||
}
|
||||
```
|
||||
8
docs/pages/shape/circle.md
Normal file
@ -0,0 +1,8 @@
|
||||
|
||||
## Circle Shapes
|
||||
Circle shapes have a position and radius. Circles are solid. You cannot
|
||||
make a hollow circle using the circle shape.
|
||||
|
||||
```js
|
||||
let circle = new Circle(new Vec2(2, 3), 0.5);
|
||||
```
|
||||
45
docs/pages/shape/edge.md
Normal file
@ -0,0 +1,45 @@
|
||||
|
||||
## Edge Shapes
|
||||
Edge shapes are line segments. These are provided to assist in making a
|
||||
free-form static environment for your game. A major limitation of edge
|
||||
shapes is that they can collide with circles and polygons but not with
|
||||
themselves. The collision algorithms used by Planck.js require that at least
|
||||
one of two colliding shapes have volume. Edge shapes have no volume, so
|
||||
edge-edge collision is not possible.
|
||||
|
||||
```js
|
||||
// This is an edge shape.
|
||||
let edge = new Edge(new Vec2(0, 0), new Vec2(1, 0));
|
||||
```
|
||||
|
||||
In many cases a game environment is constructed by connecting several
|
||||
edge shapes end-to-end. This can give rise to an unexpected artifact
|
||||
when a polygon slides along the chain of edges. In the figure below we
|
||||
see a box colliding with an internal vertex. These *ghost* collisions
|
||||
are caused when the polygon collides with an internal vertex generating
|
||||
an internal collision normal.
|
||||
|
||||

|
||||
|
||||
If edge1 did not exist this collision would seem fine. With edge1
|
||||
present, the internal collision seems like a bug. But normally when
|
||||
Planck.js collides two shapes, it views them in isolation.
|
||||
|
||||
Fortunately, the edge shape provides a mechanism for eliminating ghost
|
||||
collisions by storing the adjacent *ghost* vertices. Planck.js uses these
|
||||
ghost vertices to prevent internal collisions.
|
||||
|
||||

|
||||
|
||||
```js
|
||||
// This is an edge shape with ghost vertices.
|
||||
let v0 = Vec2(1.7, 0);
|
||||
let v1 = Vec2(1, 0.25);
|
||||
let v2 = Vec2(0, 0);
|
||||
let v3 = Vec2(-1.7, 0.4);
|
||||
|
||||
let edge = new Edge(v1, v2).setPrevVertex(v0).setNextVertex(v3);
|
||||
```
|
||||
|
||||
In general stitching edges together this way is a bit wasteful and
|
||||
tedious. This brings us to chain shapes.
|
||||
63
docs/pages/shape/polygon.md
Normal file
@ -0,0 +1,63 @@
|
||||
|
||||
## Polygon Shapes
|
||||
Polygon shapes are solid convex polygons. A polygon is convex when all
|
||||
line segments connecting two points in the interior do not cross any
|
||||
edge of the polygon. Polygons are solid and never hollow. A polygon must
|
||||
have 3 or more vertices.
|
||||
|
||||

|
||||
|
||||
Polygon vertices are stored with a counter-clockwise winding (CCW). We
|
||||
must be careful because the notion of CCW is with respect to a
|
||||
right-handed coordinate system with the z-axis pointing out of the
|
||||
plane. This might turn out to be clockwise on your screen, depending on
|
||||
your coordinate system conventions.
|
||||
|
||||

|
||||
|
||||
The initialization functions create normal vectors and perform validation.
|
||||
So you should use initialization functions to create a polygon.
|
||||
|
||||
You can create a polygon shape by passing in a vertex array. The maximal
|
||||
size of the array is controlled by `Setting.MaxPolygonVertices` which has a
|
||||
default value of 8. This is sufficient to describe most convex polygons.
|
||||
|
||||
The `PolygonShape.set` function automatically computes the convex hull
|
||||
and establishes the proper winding order. This function is fast when the
|
||||
number of vertices is low. If you increase `MaxPolygonVertices`, then
|
||||
the convex hull computation might become slow. Also note that the convex
|
||||
hull function may eliminate and/or re-order the points you provide.
|
||||
Vertices that are closer than `Settings.linearSlop` may be merged.
|
||||
|
||||
```js
|
||||
// This defines a triangle in CCW order.
|
||||
let vertices = [
|
||||
Vec2(0, 0),
|
||||
Vec2(1, 0),
|
||||
Vec2(0, 1)
|
||||
];
|
||||
|
||||
let polygon = new Polygon(vertices);
|
||||
```
|
||||
|
||||
The polygon shape has some convenience functions to create boxes.
|
||||
|
||||
```js
|
||||
new Box(halfWidth, halfHeight);
|
||||
new Box(halfWidth, halfHeight, center, angle);
|
||||
```
|
||||
|
||||
`center` is the local position of the center of the box shape, and `angle` is its rotation. When not provided, center and angle of the box are `{x: 0, y: 0}` and `0` (relative to the body's origin and angle).
|
||||
|
||||
Polygons inherit a radius from Shape. The radius creates a skin around
|
||||
the polygon. The skin is used in stacking scenarios to keep polygons
|
||||
slightly separated. This allows continuous collision to work against the
|
||||
core polygon.
|
||||
|
||||

|
||||
|
||||
The polygon skin helps prevent tunneling by keeping the polygons
|
||||
separated. This results in small gaps between the shapes. Your visual
|
||||
representation can be larger than the polygon to hide any gaps.
|
||||
|
||||

|
||||
127
docs/pages/testbed.md
Normal file
@ -0,0 +1,127 @@
|
||||
|
||||
## Testbed
|
||||
|
||||
Testbed is a debugging tool that is provided with the library. It is useful to get started with Planck.js, and develop and debug physics code, and run examples.
|
||||
|
||||
Testbed is not required to use Planck.js physics. You can run simulation and render physics world directly, with any rendering library or framework (see [Simulation](./world/simulation) and [Rendering](./rendering) sections for more details).
|
||||
|
||||
There are multiple way to use testbed:
|
||||
- Use Piqnt online playground
|
||||
- Install from NPM, or from CDN
|
||||
- Run locally from source
|
||||
|
||||
### Piqnt onlin playground
|
||||
|
||||
[Piqnt](https://piqnt.com/) is an online playground to run testbed code. It is useful to quickly try out physics examples, and share them with others.
|
||||
|
||||
### Install from NPM
|
||||
|
||||
To install testbed from NPM, run `npm install planck`. Then import testbed in your code.
|
||||
|
||||
```bash
|
||||
npm install planck
|
||||
```
|
||||
|
||||
```js
|
||||
import { World, Testbed } from 'planck/with-testbed';
|
||||
```
|
||||
|
||||
### Script tag and CDN
|
||||
|
||||
To use testbed from CDN, add the following script tag to your HTML file.
|
||||
|
||||
```html
|
||||
<html><body>
|
||||
<span id="testbed-info"></span>
|
||||
<span id="testbed-status"></span>
|
||||
<button id="testbed-play">Play</button>
|
||||
|
||||
<script src="https://cdn.jsdelivr.net/npm/planck/dist/planck-with-testbed.min.js"></script>
|
||||
<script>
|
||||
const { World, Testbed } = planck;
|
||||
const world = new World();
|
||||
|
||||
const testbed = Testbed.mount();
|
||||
testbed.start(world);
|
||||
</script>
|
||||
</body></html>
|
||||
```
|
||||
|
||||
### Run locally from source
|
||||
|
||||
Running testbed locally is useful if you want to debug or edit the library or testbed code, or if you want to run testbed examples locally.
|
||||
|
||||
To run testbed from source, clone the repository and run `npm install` and `npm run dev` in the root directory. This will start a local server and open testbed in your browser.
|
||||
|
||||
```bash
|
||||
git clone
|
||||
cd planck.js
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
|
||||
## Testbed Usage and API
|
||||
|
||||
To use testbed first create a world, then start simulation.
|
||||
|
||||
```js
|
||||
// Create a world
|
||||
const world = new World();
|
||||
|
||||
// Start simulation
|
||||
const testbed = Testbed.start(world);
|
||||
```
|
||||
|
||||
If you need to access the testbed instance before starting simulation you can mount the testbed first, and later start simulation.
|
||||
|
||||
```js
|
||||
// Mount testbed
|
||||
const testbed = Testbed.mount();
|
||||
|
||||
// Create a world
|
||||
const world = new World();
|
||||
|
||||
// Start simulation
|
||||
testbed.start(world);
|
||||
```
|
||||
|
||||
#### Viewbox
|
||||
|
||||
You can adjust testbed viewbox, by setting the viewbox center and dimensions. Viewbox center and dimension are in defined in physical units. Testbed will calculate and set rendering scale and offset to match provided dimensions and center.
|
||||
|
||||
```js
|
||||
// Viewbox center
|
||||
testbed.x = 0;
|
||||
testbed.y = 0;
|
||||
|
||||
// Viewbox size
|
||||
testbed.width = 30;
|
||||
testbed.height = 20;
|
||||
```
|
||||
|
||||
#### Game-loop callback
|
||||
|
||||
You can add a game loop callback to testbed, it will be called in each frame.
|
||||
|
||||
```js
|
||||
testbed.step = function() {
|
||||
// Code to run in each game loop
|
||||
};
|
||||
```
|
||||
|
||||
#### Display text information
|
||||
|
||||
Testbed has two methods to display information on screen, `info` and `status`.
|
||||
|
||||
```js
|
||||
// Use info() to print some text on screen
|
||||
testbed.info('Use arrow keys to move player');
|
||||
|
||||
testbed.step = function() {
|
||||
// Use status() to print key-values
|
||||
// Testbed will retain value of keys until they are changed
|
||||
testbed.status('score', score);
|
||||
testbed.status('time', time);
|
||||
};
|
||||
```
|
||||
86
docs/pages/world.md
Normal file
@ -0,0 +1,86 @@
|
||||
|
||||
## World
|
||||
The `World` class contains the bodies and joints. It manages all aspects
|
||||
of the simulation and allows for asynchronous queries (like AABB queries
|
||||
and ray-casts). Much of your interactions with Planck.js will be with a
|
||||
World object.
|
||||
|
||||
Creating a world is fairly simple. You just need to provide a gravity
|
||||
vector and a boolean indicating if bodies can sleep.
|
||||
|
||||
```js
|
||||
let myWorld = new World({
|
||||
gravity: {x: 0, y: -10},
|
||||
allowSleep: true,
|
||||
});
|
||||
```
|
||||
|
||||
The world class contains factories for creating and destroying bodies
|
||||
and joints. These factories are discussed later in the sections on
|
||||
bodies and joints. There are some other interactions with World that I
|
||||
will cover now.
|
||||
|
||||
### Exploring the World
|
||||
The world is a container for bodies, contacts, and joints. You can grab
|
||||
the body, contact, and joint lists off the world and iterate over them.
|
||||
For example, this code wakes up all the bodies in the world:
|
||||
|
||||
```js
|
||||
for (let b = myWorld.getBodyList(); b; b = b.getNext()) {
|
||||
b.setAwake(true);
|
||||
}
|
||||
```
|
||||
|
||||
Unfortunately real programs can be more complicated. For example, the
|
||||
following code is broken:
|
||||
|
||||
```js
|
||||
for (let b = myWorld.getBodyList(); b; b = b.getNext()) {
|
||||
let myActor = b.getUserData();
|
||||
if (myActor.isDead()) {
|
||||
myWorld.destroyBody(b); // ERROR: now GetNext returns garbage.
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Everything goes ok until a body is destroyed. Once a body is destroyed,
|
||||
its next pointer becomes invalid. So the call to `body.getNext()` will
|
||||
return garbage. The solution to this is to copy the next pointer before
|
||||
destroying the body.
|
||||
|
||||
```js
|
||||
let node = myWorld.getBodyList();
|
||||
while (node) {
|
||||
let b = node;
|
||||
node = node.getNext();
|
||||
|
||||
let myActor = b.getUserData();
|
||||
if (myActor.isDead()) {
|
||||
myWorld.destroyBody(b);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This safely destroys the current body. However, you may want to call a
|
||||
game function that may destroy multiple bodies. In this case you need to
|
||||
be very careful. The solution is application specific, but for
|
||||
convenience I'll show one method of solving the problem.
|
||||
|
||||
```js
|
||||
let node = myWorld.getBodyList();
|
||||
while (node) {
|
||||
let b = node;
|
||||
node = node.getNext();
|
||||
|
||||
let myActor = b.getUserData();
|
||||
if (myActor.IsDead()) {
|
||||
let otherBodiesDestroyed = gameCrazyBodyDestroyer(b);
|
||||
if (otherBodiesDestroyed) {
|
||||
node = myWorld.getBodyList();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Obviously to make this work, `gameCrazyBodyDestroyer()` must be honest about
|
||||
what it has destroyed.
|
||||
25
docs/pages/world/aabb-query.md
Normal file
@ -0,0 +1,25 @@
|
||||
|
||||
## AABB Queries
|
||||
Sometimes you want to determine all the shapes in a region. The World
|
||||
class has a fast O(log N) method for this using the broad-phase data
|
||||
structure. You provide an AABB in world coordinates and an
|
||||
implementation of `QueryCallback`. The world calls your class with each
|
||||
fixture whose AABB overlaps the query AABB. Return `true` to continue the
|
||||
query, otherwise return `false`. For example, the following code finds all
|
||||
the fixtures that potentially intersect a specified AABB and wakes up
|
||||
all of the associated bodies.
|
||||
|
||||
```js
|
||||
const query = new AABB(
|
||||
new Vec2(-1, -1),
|
||||
new Vec2(1, 1),
|
||||
);
|
||||
myWorld.queryAABB(query, function(fixture) {
|
||||
let body = fixture.getBody();
|
||||
body.setAwake(true);
|
||||
// Return true to continue the query.
|
||||
return true;
|
||||
});
|
||||
```
|
||||
|
||||
You cannot make any assumptions about the order of the callbacks.
|
||||
46
docs/pages/world/ray-cast.md
Normal file
@ -0,0 +1,46 @@
|
||||
|
||||
## Ray Casts
|
||||
You can use ray casts to do line-of-sight checks, fire guns, etc. You
|
||||
perform a ray cast by implementing a callback class and providing the
|
||||
start and end points. The world class calls your class with each fixture
|
||||
hit by the ray. Your callback is provided with the fixture, the point of
|
||||
intersection, the unit normal vector, and the fractional distance along
|
||||
the ray. You cannot make any assumptions about the order of the
|
||||
callbacks.
|
||||
|
||||
You control the continuation of the ray cast by returning a fraction.
|
||||
Returning a fraction of zero indicates the ray cast should be
|
||||
terminated. A fraction of one indicates the ray cast should continue as
|
||||
if no hit occurred. If you return the fraction from the argument list,
|
||||
the ray will be clipped to the current intersection point. So you can
|
||||
ray cast any shape, ray cast all shapes, or ray cast the closest shape
|
||||
by returning the appropriate fraction.
|
||||
|
||||
You may also return of fraction of -1 to filter the fixture. Then the
|
||||
ray cast will proceed as if the fixture does not exist.
|
||||
|
||||
Here is an example:
|
||||
|
||||
```js
|
||||
// This class captures the closest hit shape.
|
||||
let closest = null;
|
||||
|
||||
myWorld.rayCast(Vec2(-1, 0), Vec2(3, 1), function(fixture, point, normal, fraction) {
|
||||
closest = {
|
||||
fixture: fixture,
|
||||
point: point, // Vec2
|
||||
normal: normal, // Vec2
|
||||
fraction: fraction, // number
|
||||
}
|
||||
|
||||
// By returning the current fraction, we instruct the calling code to clip the ray and
|
||||
// continue the ray-cast to the next fixture. WARNING: do not assume that fixtures
|
||||
// are reported in order. However, by clipping, we can always get the closest fixture.
|
||||
return fraction;
|
||||
});
|
||||
```
|
||||
|
||||
> **Caution**:
|
||||
> Due to round-off errors, ray casts can sneak through small cracks
|
||||
> between polygons in your static environment. If this is not acceptable
|
||||
> in your application, try slightly overlapping your polygons.
|
||||
125
docs/pages/world/simulation.md
Normal file
@ -0,0 +1,125 @@
|
||||
|
||||
## Simulation
|
||||
|
||||
The world class is used to drive the simulation. You specify a time step
|
||||
and a velocity and position iteration count. For example:
|
||||
|
||||
```js
|
||||
let timeStep = 1 / 60;
|
||||
let velocityIterations = 10;
|
||||
let positionIterations = 8;
|
||||
myWorld.step(timeStep, velocityIterations, positionIterations);
|
||||
```
|
||||
|
||||
After the time step you can examine your bodies and joints for
|
||||
information. Most likely you will grab the position off the bodies so
|
||||
that you can update your actors and render them. You can perform the
|
||||
time step anywhere in your game loop, but you should be aware of the
|
||||
order of things. For example, you must create bodies before the time
|
||||
step if you want to get collision results for the new bodies in that
|
||||
frame.
|
||||
|
||||
As I discussed above in the HelloWorld tutorial[todo], you should use a fixed
|
||||
time step. By using a larger time step you can improve performance in
|
||||
low frame rate scenarios. But generally you should use a time step no
|
||||
larger than 1/30 seconds. A time step of 1/60 seconds will usually
|
||||
deliver a high quality simulation.
|
||||
|
||||
The iteration count controls how many times the constraint solver sweeps
|
||||
over all the contacts and joints in the world. More iteration always
|
||||
yields a better simulation. But don't trade a small time step for a
|
||||
large iteration count. 60Hz and 10 iterations is far better than 30Hz
|
||||
and 20 iterations.
|
||||
|
||||
After stepping, you should clear any forces you have applied to your
|
||||
bodies. This is done with the command `world.clearForces()`. This lets
|
||||
you take multiple sub-steps with the same force field.
|
||||
|
||||
```js
|
||||
myWorld.clearForces();
|
||||
```
|
||||
|
||||
|
||||
[todo: clean up next section, it is duplicate]
|
||||
|
||||
### Simulating the World
|
||||
|
||||
Planck.js uses a computational algorithm called an integrator. Integrators
|
||||
simulate the physics equations at discrete points of time. This goes
|
||||
along with the traditional game loop where we essentially have a flip
|
||||
book of movement on the screen. So we need to pick a time step for
|
||||
Planck.js. Generally physics engines for games like a time step at least as
|
||||
fast as 60Hz or 1/60 seconds. You can get away with larger time steps,
|
||||
but you will have to be more careful about setting up the definitions
|
||||
for your world. We also don't like the time step to change much. A
|
||||
variable time step produces variable results, which makes it difficult
|
||||
to debug. So don't tie the time step to your frame rate (unless you
|
||||
really, really have to). Without further ado, here is the time step.
|
||||
|
||||
```js
|
||||
let timeStep = 1 / 60;
|
||||
```
|
||||
|
||||
In addition to the integrator, Planck.js also uses a larger bit of code
|
||||
called a constraint solver. The constraint solver solves all the
|
||||
constraints in the simulation, one at a time. A single constraint can be
|
||||
solved perfectly. However, when we solve one constraint, we slightly
|
||||
disrupt other constraints. To get a good solution, we need to iterate
|
||||
over all constraints a number of times.
|
||||
|
||||
There are two phases in the constraint solver: a velocity phase and a
|
||||
position phase. In the velocity phase the solver computes the impulses
|
||||
necessary for the bodies to move correctly. In the position phase the
|
||||
solver adjusts the positions of the bodies to reduce overlap and joint
|
||||
detachment. Each phase has its own iteration count. In addition, the
|
||||
position phase may exit iterations early if the errors are small.
|
||||
|
||||
The suggested iteration count for Planck.js is 8 for velocity and 3 for
|
||||
position. You can tune this number to your liking, just keep in mind
|
||||
that this has a trade-off between performance and accuracy. Using fewer
|
||||
iterations increases performance but accuracy suffers. Likewise, using
|
||||
more iterations decreases performance but improves the quality of your
|
||||
simulation. For this simple example, we don't need much iteration. Here
|
||||
are our chosen iteration counts.
|
||||
|
||||
```js
|
||||
let velocityIterations = 6;
|
||||
let positionIterations = 2;
|
||||
```
|
||||
|
||||
Note that the time step and the iteration count are completely
|
||||
unrelated. An iteration is not a sub-step. One solver iteration is a
|
||||
single pass over all the constraints within a time step. You can have
|
||||
multiple passes over the constraints within a single time step.
|
||||
|
||||
We are now ready to begin the simulation loop. In your game the
|
||||
simulation loop can be merged with your game loop. In each pass through
|
||||
your game loop you call world.step(). Just one call is usually enough,
|
||||
depending on your frame rate and your physics time step.
|
||||
|
||||
The Hello World program was designed to be simple, so it has no
|
||||
graphical output. The code prints out the position and rotation of the
|
||||
dynamic body. Here is the simulation loop that simulates 60 time steps
|
||||
for a total of 1 second of simulated time.
|
||||
|
||||
```js
|
||||
for (let i = 0; i < 60; ++i) {
|
||||
world.step(timeStep, velocityIterations, positionIterations);
|
||||
let position = body.getPosition();
|
||||
let angle = body.getAngle();
|
||||
console.log(position.x, position.y, angle);
|
||||
}
|
||||
```
|
||||
|
||||
The output shows the box falling and landing on the ground box. Your
|
||||
output should look like this:
|
||||
|
||||
```
|
||||
0.00 4.00 0.00
|
||||
0.00 3.99 0.00
|
||||
0.00 3.98 0.00
|
||||
...
|
||||
0.00 1.25 0.00
|
||||
0.00 1.13 0.00
|
||||
0.00 1.01 0.00
|
||||
```
|
||||
50
eslint.config.mjs
Normal file
@ -0,0 +1,50 @@
|
||||
import js from "@eslint/js";
|
||||
import tseslint from "typescript-eslint";
|
||||
import { defineConfig } from "eslint/config";
|
||||
import prettierConfig from "eslint-config-prettier";
|
||||
|
||||
export default defineConfig([
|
||||
js.configs.recommended,
|
||||
...tseslint.configs.recommended,
|
||||
// ...tseslint.configs.recommendedTypeChecked,
|
||||
// ...tseslint.configs.stylisticTypeChecked,
|
||||
|
||||
{
|
||||
files: ["**/*.ts"],
|
||||
|
||||
languageOptions: {
|
||||
parser: tseslint.parser,
|
||||
parserOptions: {
|
||||
project: true,
|
||||
tsconfigRootDir: import.meta.dirname,
|
||||
},
|
||||
},
|
||||
rules: {
|
||||
"no-var": "off",
|
||||
"prefer-rest-params": "off",
|
||||
"prefer-spread": "off",
|
||||
"quotes": ["warn", "double"],
|
||||
"semi": ["warn", "always"],
|
||||
"one-var-declaration-per-line": "warn",
|
||||
"no-constant-condition": "warn",
|
||||
"no-empty": "warn",
|
||||
"no-prototype-builtins": "warn",
|
||||
"@typescript-eslint/ban-ts-comment": "off",
|
||||
"@typescript-eslint/ban-types": "off",
|
||||
"@typescript-eslint/no-empty-function": "off",
|
||||
"@typescript-eslint/no-empty-interface": "off",
|
||||
"@typescript-eslint/no-explicit-any": "off",
|
||||
"@typescript-eslint/no-inferrable-types": "off",
|
||||
"@typescript-eslint/no-non-null-assertion": "off",
|
||||
"@typescript-eslint/no-unused-vars": "off",
|
||||
"@typescript-eslint/no-var-requires": "off",
|
||||
"@typescript-eslint/typedef": [
|
||||
"error",
|
||||
{
|
||||
propertyDeclaration: true,
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
prettierConfig,
|
||||
]);
|
||||