PageRenderTime 50ms CodeModel.GetById 12ms RepoModel.GetById 0ms app.codeStats 0ms

/Cocos2d-x/Cocos2d-x/libs/chipmunk/chipmunk-docs.html

https://gitlab.com/Mr.Tomato/Cocos2d-X-text
HTML | 944 lines | 546 code | 398 blank | 0 comment | 0 complexity | 0b2a9816da4d8449b1200ad14fb9c245 MD5 | raw file
    

  1. 	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    2. 

  2. 	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    3. 

  3. 	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    4. 

  4.     <head>
    5. 

  5.         <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    6. 

  6.         <title>Chipmunk Game Dynamics Documentation</title>
    7. 

  7.                     <style type="text/css">
    8. 

  8.                         h1 {
    9. 

  9.                                 text-align: center;
    10. 

  10.                                 font-size: 300%;
    11. 

  11.                         }
    12. 

  12. 

  13.                         h2, h3 {
    14. 

  14.                                 background-color: BurlyWood;
    15. 

  15.                                 padding: 3px;
    16. 

  16.                         }
    17. 

  17. 

  18.                         p {
    19. 

  19.                                 margin-left: 1em;
    20. 

  20.                         }
    21. 

  21. 

  22.                         p.expl {
    23. 

  23.                                 margin-left: 2em;
    24. 

  24.                         }
    25. 

  25. 

  26.                         pre {
    27. 

  27.                                 background-color: lightGrey;
    28. 

  28.                                 padding: 3px;
    29. 

  29.                                 margin-left: 1em;
    30. 

  30.                         }
    31. 

  31.                 </style>
    32. 

  32.     </head>
    33. 

  33.     <body>
    34. 

  34. 

  35. 	<h1>Chipmunk Game Dynamics</h1>
    36. 

  36. 

  37. 

  38. 	<h2>Introduction</h2>
    39. 

  39. 

  40. 

  41. 	<p>First of all, Chipmunk is a 2D rigid body physics library distributed under the <span class="caps">MIT</span> license. Though not yet complete, it is intended to be fast, numerically stable, and easy to use.</p>
    42. 

  42. 

  43. 

  44. 	<p>It&#8217;s been a long time in coming, but I&#8217;ve finally made a stable and usable physics implementation. While not feature complete yet, it&#8217;s well on it&#8217;s way. I would like to give a Erin Catto a big thank you, as the most of the ideas for the constraint solver come from his Box2D example code. (<a href="http://www.gphysics.com/">gPhysics Website</a>). His contact persistence idea allows for stable stacks of objects with very few iterations of the contact solution. Couldn&#8217;t have gotten that working without his help.</p>
    45. 

  45. 

  46. 

  47. 	<h2>Overview</h2>
    48. 

  48. 

  49. 

  50. 	<ul>
    51. 

  51. 	<li><strong>rigid bodies:</strong> A rigid body holds the physical properties of an object. (mass, position, rotation, velocity, etc.) It does not have a shape by itself. If you&#8217;ve done physics with particles before, rigid bodies differ mostly in that they are able to rotate.</li>
    52. 

  52. 		<li><strong>collision shapes:</strong> By attaching shapes to bodies, you can define the a body&#8217;s shape. You can attach many shapes to a single body to define a complex shape, or none if it doesn&#8217;t require a shape.</li>
    53. 

  53. 		<li><strong>joints:</strong> You can attach joints between two bodies to constrain their behavior.</li>
    54. 

  54. 		<li><strong>spaces:</strong> Spaces are the basic simulation unit in Chipmunk. You add bodies, shapes and joints to a space, and then update the space as a whole.</li>
    55. 

  55. 	</ul>
    56. 

  56. 

  57. 

  58. 	<p><strong>Rigid bodies, collision shapes and sprites:</strong></p>
    59. 

  59. 

  60. 

  61. 	<p>There is often confusion between rigid bodies and their collision shapes in Chipmunk and how they relate to sprites. A sprite would be a visual representation of an object, the sprite is drawn at the position of the rigid body. The collision shape would be the material representation of the object, and how it should collide with other objects. A sprite and collision shape have little to do with one another other than you probably want the collision shape to match the sprite&#8217;s shape.</p>
    62. 

  62. 

  63. 

  64. 	<h2><span class="caps">C API</span> Documentation</h2>
    65. 

  65. 

  66. 

  67. 	<h3>Initializing Chipmunk</h3>
    68. 

  68. 

  69. 

  70. 	<p>Initializing Chipmunk is an extremely complicated process. The following code snippet steps you through the process:</p>
    71. 

  71. 

  72. 

  73. <pre><code>
    74. 

  74. cpInitChipmunk(); /* Actually, that's pretty much it */
    75. 

  75. </code></pre>
    76. 

  76. 

  77. 	<h3>Chipmunk memory management</h3>
    78. 

  78. 

  79. 

  80. 	<p>For many of the structures you will use, Chipmunk uses a more or less standard set of memory management functions. For instance:</p>
    81. 

  81. 

  82. 

  83. 	<ul>
    84. 

  84. 	<li><code>cpSpaceAlloc()</code> allocates but does not initialize a <code>cpSpace</code> struct.</li>
    85. 

  85. 		<li><code>cpSpaceInit(space, other_args)</code> initializes a <code>cpSpace</code> struct.</li>
    86. 

  86. 		<li><code>cpSpaceNew(args)</code> allocates and initializes a <code>cpSpace</code> struct using <code>args</code>.</li>
    87. 

  87. 		<li><code>cpSpaceDestroy(space)</code> frees all dependancies, but does not free the <code>cpSpace</code> struct.</li>
    88. 

  88. 		<li><code>cpSpaceFree(space)</code> frees all dependancies and the <code>cpSpace</code> struct.</li>
    89. 

  89. 	</ul>
    90. 

  90. 

  91. 

  92. 	<p>While you will probably use the new/free versions exclusively, the others can be helpful when writing language extensions.</p>
    93. 

  93. 

  94. 

  95. 	<p>In general, you are responsible for freeing any structs that you allocate. The only exception is that <code>cpShapeDestroy()</code> also destroys the specific shape struct that was passed to the constructor.</p>
    96. 

  96. 

  97. 

  98. 	<h3>Chipmunk floats: <code>cpFloat</code></h3>
    99. 

  99. 

  100. 

  101. <pre><code>
    102. 

  102. typedef float cpFloat;
    103. 

  103. </code></pre>
    104. 

  104. 

  105. 	<p>All Chipmunk code should be <code>double</code> safe, so feel free to redefine this.</p>
    106. 

  106. 

  107. 

  108. 	<h3>Chipmunk vectors: <code>cpVect</code></h3>
    109. 

  109. 

  110. 

  111. 	<p><strong>User accessible fields:</strong></p>
    112. 

  112. 

  113. 

  114. <pre><code>
    115. 

  115. typedef struct cpVect{
    116. 

  116.     cpFloat x,y;
    117. 

  117. } cpVect
    118. 

  118. </code></pre>
    119. 

  119. 

  120. 	<p class="expl">Simply a 2D vector packed into a struct. May change in the future to take advantage of <span class="caps">SIMD</span>.</p>
    121. 

  121. 

  122. 

  123. <pre><code>
    124. 

  124. #define cpvzero ((cpVect){0.0f, 0.0f})
    125. 

  125. </code></pre>
    126. 

  126. 

  127. 	<p class="expl">Constant for the zero vector.</p>
    128. 

  128. 

  129. 

  130. <pre><code>
    131. 

  131. cpVect cpv(const cpFloat x, const cpFloat y)
    132. 

  132. </code></pre>
    133. 

  133. 

  134. 	<p class="expl">Convenience constructor for creating new <code>cpVect</code> structs.</p>
    135. 

  135. 

  136. 

  137. <pre><code>
    138. 

  138. cpVect cpvadd(const cpVect v1, const cpVect v2)
    139. 

  139. cpVect cpvsub(const cpVect v1, const cpVect v2)
    140. 

  140. </code></pre>
    141. 

  141. 

  142. 	<p class="expl">Add or subtract two vectors.</p>
    143. 

  143. 

  144. 

  145. <pre><code>
    146. 

  146. cpVect cpvneg(const cpVect v)
    147. 

  147. </code></pre>
    148. 

  148. 

  149. 	<p class="expl">Negate a vector.</p>
    150. 

  150. 

  151. 

  152. <pre><code>
    153. 

  153. cpVect cpvmult(const cpVect v, const cpFloat s)
    154. 

  154. </code></pre>
    155. 

  155. 

  156. 	<p class="expl">Scalar multiplication.</p>
    157. 

  157. 

  158. 

  159. <pre><code>
    160. 

  160. cpFloat cpvdot(const cpVect v1, const cpVect v2)
    161. 

  161. </code></pre>
    162. 

  162. 

  163. 	<p class="expl">Vector dot product.</p>
    164. 

  164. 

  165. 

  166. <pre><code>
    167. 

  167. cpFloat cpvcross(const cpVect v1, const cpVect v2)
    168. 

  168. </code></pre>
    169. 

  169. 

  170. 	<p class="expl">2D vector cross product analog. The cross product of 2D vectors exists only in the z component, so only that value is returned.</p>
    171. 

  171. 

  172. 

  173. <pre><code>
    174. 

  174. cpVect cpvperp(const cpVect v)
    175. 

  175. </code></pre>
    176. 

  176. 

  177. 	<p class="expl">Returns the perpendicular vector. (90 degree rotation)</p>
    178. 

  178. 

  179. 

  180. <pre><code>
    181. 

  181. cpVect cpvproject(const cpVect v1, const cpVect v2)
    182. 

  182. </code></pre>
    183. 

  183. 

  184. 	<p class="expl">Returns the vector projection of <code>v1</code> onto <code>v2</code>.</p>
    185. 

  185. 

  186. 

  187. <pre><code>
    188. 

  188. cpVect cpvrotate(const cpVect v1, const cpVect v2)
    189. 

  189. </code></pre>
    190. 

  190. 

  191. 	<p class="expl">Uses complex multiplication to rotate (and scale) <code>v1</code> by <code>v2</code>.</p>
    192. 

  192. 

  193. 

  194. <pre><code>
    195. 

  195. cpVect cpvunrotate(const cpVect v1, const cpVect v2)
    196. 

  196. </code></pre>
    197. 

  197. 

  198. 	<p class="expl">Inverse of <code>cpvrotate()</code>.</p>
    199. 

  199. 

  200. 

  201. <pre><code>
    202. 

  202. cpFloat cpvlength(const cpVect v)
    203. 

  203. </code></pre>
    204. 

  204. 

  205. 	<p class="expl">Returns the length of <code>v</code>.</p>
    206. 

  206. 

  207. 

  208. <pre><code>
    209. 

  209. cpFloat cpvlengthsq(const cpVect v)
    210. 

  210. </code></pre>
    211. 

  211. 

  212. 	<p class="expl">Returns the squared length of <code>v</code>. Faster than <code>cpvlength()</code> when you only need to compare lengths.</p>
    213. 

  213. 

  214. 

  215. <pre><code>
    216. 

  216. cpVect cpvnormalize(const cpVect v)
    217. 

  217. </code></pre>
    218. 

  218. 

  219. 	<p class="expl">Returns a normalized copy of <code>v</code>.</p>
    220. 

  220. 

  221. 

  222. <pre><code>
    223. 

  223. cpVect cpvforangle(const cpFloat a)
    224. 

  224. </code></pre>
    225. 

  225. 

  226. 	<p class="expl">Returns the unit length vector for the given angle (in radians).</p>
    227. 

  227. 

  228. 

  229. <pre><code>
    230. 

  230. cpFloat cpvtoangle(const cpVect v)
    231. 

  231. </code></pre>
    232. 

  232. 

  233. 	<p class="expl">Returns the angular direction <code>v</code> is pointing in (in radians).</p>
    234. 

  234. 

  235. 

  236. <pre><code>
    237. 

  237. *cpvstr(const cpVect v)
    238. 

  238. </code></pre>
    239. 

  239. 

  240. 	<p class="expl">Returns a string representation of <code>v</code>. <strong><span class="caps">NOTE</span>:</strong> <em>The string points to a static local and is reset every time the function is called.</em></p>
    241. 

  241. 

  242. 

  243. 	<h3>Chipmunk bounding boxes: <code>cpBB</code></h3>
    244. 

  244. 

  245. 

  246. 	<p><strong>User accessible fields:</strong></p>
    247. 

  247. 

  248. 

  249. <pre><code>
    250. 

  250. typedef struct cpBB{
    251. 

  251.     cpFloat l, b, r ,t;
    252. 

  252. } cpBB
    253. 

  253. </code></pre>
    254. 

  254. 

  255. 	<p class="expl">Simple bounding box struct. Stored as left, bottom, right, top values.</p>
    256. 

  256. 

  257. 

  258. <pre><code>
    259. 

  259. cpBB cpBBNew(const cpFloat l, const cpFloat b, const cpFloat r, const cpFloat t)
    260. 

  260. </code></pre>
    261. 

  261. 

  262. 	<p class="expl">Convenience constructor for <code>cpBB</code> structs.</p>
    263. 

  263. 

  264. 

  265. <pre><code>
    266. 

  266. int cpBBintersects(const cpBB a, const cpBB b)
    267. 

  267. </code></pre>
    268. 

  268. 

  269. 	<p class="expl">Returns true if the bounding boxes intersect.</p>
    270. 

  270. 

  271. 

  272. <pre><code>
    273. 

  273. int cpBBcontainsBB(const cpBB bb, const cpBB other)
    274. 

  274. </code></pre>
    275. 

  275. 

  276. 	<p class="expl">Returns true if <code>bb</code> completely contains <code>other</code>.</p>
    277. 

  277. 

  278. 

  279. <pre><code>
    280. 

  280. int cpBBcontainsVect(const cpBB bb, const cpVect v)
    281. 

  281. </code></pre>
    282. 

  282. 

  283. 	<p class="expl">Returns true if <code>bb</code> contains <code>v</code>.</p>
    284. 

  284. 

  285. 

  286. <pre><code>
    287. 

  287. cpVect cpBBClampVect(const cpBB bb, const cpVect v)
    288. 

  288. </code></pre>
    289. 

  289. 

  290. 	<p class="expl">Returns a copy of <code>v</code> clamped to the bounding box.</p>
    291. 

  291. 

  292. 

  293. <pre><code>
    294. 

  294. cpVect cpBBWrapVect(const cpBB bb, const cpVect v)
    295. 

  295. </code></pre>
    296. 

  296. 

  297. 	<p class="expl">Returns a copy of <code>v</code> wrapped to the bounding box.</p>
    298. 

  298. 

  299. 

  300. 	<h3>Chipmunk spatial hashes: <code>cpSpaceHash</code></h3>
    301. 

  301. 

  302. 

  303. 	<p><em>The spatial hash isn&#8217;t yet ready for user use. However, it has been made in a generic manner that would allow it to be used for more than just Chipmunk&#8217;s collision detection needs.</em></p>
    304. 

  304. 

  305. 

  306. 	<h3>Chipmunk rigid bodies: <code>cpBody</code></h3>
    307. 

  307. 

  308. 

  309. 	<p><strong>User accessible fields:</strong></p>
    310. 

  310. 

  311. 

  312. <pre><code>
    313. 

  313. typedef struct cpBody{
    314. 

  314.     cpFloat m, m_inv;
    315. 

  315.     cpFloat i, i_inv;
    316. 

  316. 

  317.     cpVect p, v, f;
    318. 

  318.     cpFloat a, w, t;
    319. 

  319.     cpVect rot;
    320. 

  320. } cpBody
    321. 

  321. </code></pre>
    322. 

  322. 

  323. 	<ul>
    324. 

  324. 	<li><code>m</code>, and <code>m_inv</code> are the mass and its inverse.</li>
    325. 

  325. 		<li><code>i</code>, and <code>i_inv</code> are the moment of inertia and its inverse.</li>
    326. 

  326. 		<li><code>p</code>, <code>v</code>, and <code>f</code> are the position, velocity and force respectively.</li>
    327. 

  327. 		<li><code>a</code>, <code>w</code>, and <code>t</code> are the angle (in radians), angular velocity (rad/sec), and torque respectively.</li>
    328. 

  328. 		<li><code>rot</code> is the rotation of the body as a unit length vector. (can be used with <code>cpvrotate()</code>)</li>
    329. 

  329. 	</ul>
    330. 

  330. 

  331. 

  332. <pre><code>
    333. 

  333. cpBody *cpBodyAlloc(void)
    334. 

  334. cpBody *cpBodyInit(cpBody *body, cpFloat m, cpFloat i)
    335. 

  335. cpBody *cpBodyNew(cpFloat m, cpFloat i)
    336. 

  336. 

  337. void cpBodyDestroy(cpBody *body)
    338. 

  338. void cpBodyFree(cpBody *body)
    339. 

  339. </code></pre>
    340. 

  340. 

  341. 	<p class="expl">Uses the standard suite of Chipmunk memory functions. <code>m</code> and <code>i</code> are the mass and moment of inertia for the body.</p>
    342. 

  342. 

  343. 

  344. <pre><code>
    345. 

  345. void cpBodySetMass(cpBody *body, cpFloat m);
    346. 

  346. void cpBodySetMoment(cpBody *body, cpFloat i);
    347. 

  347. void cpBodySetAngle(cpBody *body, cpFloat a);
    348. 

  348. </code></pre>
    349. 

  349. 

  350. 	<p class="expl">Because several of the values are linked, (m/m_inv, i/i_inv, a/rot) don&#8217;t set them explicitly, use these setter functions instead.</p>
    351. 

  351. 

  352. 

  353. <pre><code>
    354. 

  354. cpVect cpBodyLocal2World(cpBody *body, cpVect v)
    355. 

  355. </code></pre>
    356. 

  356. 

  357. 	<p class="expl">Convert from body local coordinates to world space coordinates.</p>
    358. 

  358. 

  359. 

  360. <pre><code>
    361. 

  361. cpVect cpBodyWorld2Local(cpBody *body, cpVect v)
    362. 

  362. </code></pre>
    363. 

  363. 

  364. 	<p class="expl">Convert from world space coordinates to body local coordinates.</p>
    365. 

  365. 

  366. 

  367. <pre><code>
    368. 

  368. void cpBodyApplyImpulse(cpBody *body, cpVect j, cpVect r)
    369. 

  369. </code></pre>
    370. 

  370. 

  371. 	<p class="expl">Apply the impulse <code>j</code> to <code>body</code> with offset <code>r</code>. Both <code>j</code> and <code>r</code> should be in world coordinates.</p>
    372. 

  372. 

  373. 

  374. <pre><code>
    375. 

  375. void cpBodyResetForces(cpBody *body)
    376. 

  376. </code></pre>
    377. 

  377. 

  378. 	<p class="expl">Zero both the forces and torques accumulated on <code>body</code>.</p>
    379. 

  379. 

  380. 

  381. <pre><code>
    382. 

  382. void cpBodyApplyForce(cpBody *body, cpVect f, cpVect r)
    383. 

  383. </code></pre>
    384. 

  384. 

  385. 	<p class="expl">Apply (accumulate) the force <code>f</code> on <code>body</code> with offset <code>r</code>. Both <code>f</code> and <code>r</code> should be in world coordinates.</p>
    386. 

  386. 

  387. 

  388. <pre><code>
    389. 

  389. void cpBodyUpdateVelocity(cpBody *body, cpVect gravity, cpFloat damping, cpFloat dt)
    390. 

  390. </code></pre>
    391. 

  391. 

  392. 	<p class="expl">Updates the velocity of the body using Euler integration. You don&#8217;t need to call this unless you are managing the object manually instead of adding it to a <code>cpSpace</code>.</p>
    393. 

  393. 

  394. 

  395. <pre><code>
    396. 

  396. void cpBodyUpdatePosition(cpBody *body, cpFloat dt)
    397. 

  397. </code></pre>
    398. 

  398. 

  399. 	<p class="expl">Updates the position of the body using Euler integration. Like <code>cpBodyUpdateVelocity()</code> you shouldn&#8217;t normally need to call this yourself.</p>
    400. 

  400. 

  401. 

  402. <pre><code>
    403. 

  403. void cpDampedSpring(cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2, cpFloat rlen, cpFloat k, cpFloat dmp, cpFloat dt)
    404. 

  404. </code></pre>
    405. 

  405. 

  406. 	<p class="expl">Apply a spring force between bodies <code>a</code> and <code>b</code> at anchors <code>anchr1</code> and <code>anchr2</code> respectively.  <code>k</code> is the spring constant (force/distance),  <code>rlen</code> is the rest length of the spring,  <code>dmp</code> is the damping constant (force/velocity), and <code>dt</code> is the time step to apply the force over. <strong>Note:</strong> <em>not solving the damping forces in the impulse solver causes problems with large damping values. This function will eventually be replaced by a new constraint (joint) type.</em></p>
    407. 

  407. 

  408. 

  409. 	<p><strong>Notes:</strong></p>
    410. 

  410. 

  411. 

  412. 	<ul>
    413. 

  413. 	<li>Use forces to modify the rigid bodies if possible. This is likely to be the most stable.</li>
    414. 

  414. 		<li>Modifying a body&#8217;s velocity shouldn&#8217;t necessarily be avoided, but applying large changes can cause strange results in the simulation. Experiment freely, but be warned.</li>
    415. 

  415. 		<li><strong>Don&#8217;t</strong> modify a body&#8217;s position every step unless you really know what you are doing. Otherwise you&#8217;re likely to get the position/velocity badly out of sync.</li>
    416. 

  416. 	</ul>
    417. 

  417. 

  418. 

  419. 	<h3>Chipmunk collision shapes: <code>cpShape</code></h3>
    420. 

  420. 

  421. 

  422. 	<p>There are currently 3 possible collision shapes:</p>
    423. 

  423. 

  424. 

  425. 	<ul>
    426. 

  426. 	<li><strong>Circles</strong>: Fastest collision shape. They also roll smoothly.</li>
    427. 

  427. 		<li><strong>Line segments</strong>: Meant mainly as a static shape. They can be attached to moving bodies, but they don&#8217;t generate collisions with other line segments.</li>
    428. 

  428. 		<li><strong>Convex polygons</strong>: Slowest, but most flexible collision shape.</li>
    429. 

  429. 	</ul>
    430. 

  430. 

  431. 

  432. 	<p><strong>User accessible fields:</strong></p>
    433. 

  433. 

  434. 

  435. <pre><code>
    436. 

  436. typedef struct cpShape{
    437. 

  437.     cpBB bb;
    438. 

  438. 

  439.     unsigned long collision_type;
    440. 

  440.     unsigned long group;
    441. 

  441.     unsigned long layers;
    442. 

  442. 

  443.     void *data;
    444. 

  444. 

  445.     cpBody *body;
    446. 

  446.     cpFloat e, u;
    447. 

  447.     cpVect surface_v;
    448. 

  448. } cpShape;
    449. 

  449. </code></pre>
    450. 

  450. 

  451. 	<ul>
    452. 

  452. 	<li><code>bb</code>: The bounding box of the shape. Only guaranteed to be valid after <code>cpShapeCacheBB()</code> is called.</li>
    453. 

  453. 		<li><code>collision_type</code>: A user definable field, see the collision pair function section below for more information.</li>
    454. 

  454. 		<li><code>group</code>: Shapes in the same non-zero group do not generate collisions. Useful when creating an object out of many shapes that you don&#8217;t want to self collide. Defaults to <code>0</code>;</li>
    455. 

  455. 		<li><code>layers</code>: Shapes only collide if they are in the same bit-planes. i.e. <code>(a-&gt;layers &#38; b-&gt;layers) != 0</code> By default, a shape occupies all 32 bit-planes.</li>
    456. 

  456. 		<li><code>data</code>: A user definable field.</li>
    457. 

  457. 		<li><code>body</code>: The rigid body the shape is attached to.</li>
    458. 

  458. 		<li><code>e</code>: Elasticity of the shape. A value of 0.0 gives no bounce, while a value of 1.0 will give a &#8220;perfect&#8221; bounce. However due to inaccuracies in the simulation using 1.0 or greater is not recommended however. <em>See the notes at the end of the section.</em></li>
    459. 

  459. 		<li><code>u</code>: Friction coefficient. Chipmunk uses the Coulomb friction model, a value of 0.0 is frictionless. <a href="http://www.roymech.co.uk/Useful_Tables/Tribology/co_of_frict.htm">Tables of friction coefficients</a>. <em>See the notes at the end of the section.</em></li>
    460. 

  460. 		<li><code>surface_v</code>: The surface velocity of the object. Useful for creating conveyor belts or players that move around. This value is only used when calculating friction, not the collision.</li>
    461. 

  461. 	</ul>
    462. 

  462. 

  463. 

  464. <pre><code>
    465. 

  465. void cpShapeDestroy(cpShape *shape)
    466. 

  466. void cpShapeFree(cpShape *shape)
    467. 

  467. </code></pre>
    468. 

  468. 

  469. 	<p class="expl"><code>Destroy</code> and <code>Free</code> functions are shared by all shape types.</p>
    470. 

  470. 

  471. 

  472. <pre><code>
    473. 

  473. cpBB cpShapeCacheBB(cpShape *shape)
    474. 

  474. </code></pre>
    475. 

  475. 

  476. 	<p class="expl">Updates and returns the bounding box of <code>shape</code>.</p>
    477. 

  477. 

  478. 

  479. <pre><code>
    480. 

  480. void cpResetShapeIdCounter(void)
    481. 

  481. </code></pre>
    482. 

  482. 

  483. 	<p class="expl">Chipmunk keeps a counter so that every new shape is given a unique hash value to be used in the spatial hash. Because this affects the order in which the collisions are found and handled, you should reset the shape counter every time you populate a space with new shapes. If you don&#8217;t, there might be (very) slight differences in the simulation.</p>
    484. 

  484. 

  485. 

  486. <pre><code>
    487. 

  487. cpCircleShape *cpCircleShapeAlloc(void)
    488. 

  488. cpCircleShape *cpCircleShapeInit(cpCircleShape *circle, cpBody *body, cpVect offset, cpFloat radius)
    489. 

  489. cpShape *cpCircleShapeNew(cpBody *body, cpVect offset, cpFloat radius)
    490. 

  490. </code></pre>
    491. 

  491. 

  492. 	<p class="expl"><code>body</code> is the body to attach the circle to, <code>offset</code> is the offset from the body&#8217;s center of gravity in body local coordinates.</p>
    493. 

  493. 

  494. 

  495. <pre><code>
    496. 

  496. cpSegmentShape* cpSegmentShapeAlloc(void)
    497. 

  497. cpSegmentShape* cpSegmentShapeInit(cpSegmentShape *seg, cpBody *body, cpVect a, cpVect b, cpFloat radius)
    498. 

  498. cpShape* cpSegmentShapeNew(cpBody *body, cpVect a, cpVect b, cpFloat radius)
    499. 

  499. </code></pre>
    500. 

  500. 

  501. 	<p class="expl"><code>body</code> is the body to attach the segment to, <code>a</code> and <code>b</code> are the endpoints, and <code>radius</code> is the thickness of the segment.</p>
    502. 

  502. 

  503. 

  504. <pre><code>
    505. 

  505. cpPolyShape *cpPolyShapeAlloc(void)
    506. 

  506. cpPolyShape *cpPolyShapeInit(cpPolyShape *poly, cpBody *body, int numVerts, cpVect *verts, cpVect offset)
    507. 

  507. cpShape *cpPolyShapeNew(cpBody *body, int numVerts, cpVect *verts, cpVect offset)
    508. 

  508. </code></pre>
    509. 

  509. 

  510. 	<p class="expl"><code>body</code> is the body to attach the poly to, <code>verts</code> is an array of <code>cpVect</code>&#8217;s defining a convex hull with a counterclockwise winding, <code>offset</code> is the offset from the body&#8217;s center of gravity in body local coordinates.</p>
    511. 

  511. 

  512. 

  513. <strong>Notes:</strong> 
    514. 

  514. 	<ul>
    515. 

  515. 	<li>You can attach multiple collision shapes to a rigid body. This should allow you to create almost any shape you could possibly need.</li>
    516. 

  516. 		<li>Shapes attached to the same rigid body will never generate collisions. You don&#8217;t have to worry about overlap when attaching multiple shapes to a rigid body.</li>
    517. 

  517. 		<li>The amount of elasticity applied during a collision is determined by multiplying the elasticity of both shapes together. The same is done for determining the friction.</li>
    518. 

  518. 		<li>Make sure you add both the body and it&#8217;s collision shapes to a space. The exception is when you want to have a static body or a body that you integrate yourself. In that case, only add the shape.</li>
    519. 

  519. 	</ul>
    520. 

  520. 

  521. 

  522. 	<h3>Chipmunk joints: <code>cpJoint</code></h3>
    523. 

  523. 

  524. 

  525. 	<p>There are currently 4 kinds of joints:</p>
    526. 

  526. 

  527. 

  528. 	<ul>
    529. 

  529. 	<li><strong>Pin Joints</strong> connect two rigid bodies with a solid pin or rod. It keeps the anchor points at a set distance from one another.</li>
    530. 

  530. 		<li><strong>Slide Joints</strong> are like pin joints, but have a minimum and maximum distance. A chain could be modeled using this joint. It keeps the anchor points from getting to far apart, but will allow them to get closer together.</li>
    531. 

  531. 		<li><strong>Pivot Joints</strong> simply allow two objects to pivot about a single point.</li>
    532. 

  532. 		<li><strong>Groove Joints</strong> attach a point on one body to a groove on the other. Think of it as a sliding pivot joint.</li>
    533. 

  533. 	</ul>
    534. 

  534. 

  535. 

  536. <pre><code>
    537. 

  537. void cpJointDestroy(cpJoint *joint)
    538. 

  538. void cpJointFree(cpJoint *joint)
    539. 

  539. </code></pre>
    540. 

  540. 

  541. 	<p class="expl"><code>Destroy</code> and <code>Free</code> functions are shared by all joint types.</p>
    542. 

  542. 

  543. 

  544. <pre><code>
    545. 

  545. cpPinJoint *cpPinJointAlloc(void)
    546. 

  546. cpPinJoint *cpPinJointInit(cpPinJoint *joint, cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2)
    547. 

  547. cpJoint *cpPinJointNew(cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2)
    548. 

  548. </code></pre>
    549. 

  549. 

  550. 	<p class="expl"><code>a</code> and <code>b</code> are the two bodies to connect, and <code>anchr1</code> and <code>anchr2</code> are the anchor points on those bodies.</p>
    551. 

  551. 

  552. 

  553. <pre><code>
    554. 

  554. cpSlideJoint *cpSlideJointAlloc(void)
    555. 

  555. cpSlideJoint *cpSlideJointInit(cpSlideJoint *joint, cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2, cpFloat min, cpFloat max)
    556. 

  556. cpJoint *cpSlideJointNew(cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2, cpFloat min, cpFloat max)
    557. 

  557. </code></pre>
    558. 

  558. 

  559. 	<p class="expl"><code>a</code> and <code>b</code> are the two bodies to connect, <code>anchr1</code> and <code>anchr2</code> are the anchor points on those bodies, and <code>min</code> and <code>max</code> define the allowed distances of the anchor points.</p>
    560. 

  560. 

  561. 

  562. <pre><code>
    563. 

  563. cpPivotJoint *cpPivotJointAlloc(void)
    564. 

  564. cpPivotJoint *cpPivotJointInit(cpPivotJoint *joint, cpBody *a, cpBody *b, cpVect pivot)
    565. 

  565. cpJoint *cpPivotJointNew(cpBody *a, cpBody *b, cpVect pivot)
    566. 

  566. </code></pre>
    567. 

  567. 

  568. 	<p class="expl"><code>a</code> and <code>b</code> are the two bodies to connect, and <code>pivot</code> is the point in world coordinates of the pivot. Because the pivot location is given in world coordinates, you must have the bodies moved into the correct positions already.</p>
    569. 

  569. 

  570. 

  571. <pre><code>
    572. 

  572. cpGrooveJoint *cpGrooveJointAlloc(void)
    573. 

  573. cpGrooveJoint *cpGrooveJointInit(cpGrooveJoint *joint, cpBody *a, cpBody *b, cpVect groove_a, cpVect groove_b, cpVect anchr2)
    574. 

  574. cpJoint *cpGrooveJointNew(cpBody *a, cpBody *b, cpVect groove_a, cpVect groove_b, cpVect anchr2)
    575. 

  575. </code></pre>
    576. 

  576. 

  577. 	<p class="expl">The groove goes from <em>groov_a</em> to <em>groove_b</em> on body <em>a_, and the pivot is attached to _anchr2</em> on body <em>b</em>. All coordinates are body local.</p>
    578. 

  578. 

  579. 

  580. 	<p><strong>Notes:</strong></p>
    581. 

  581. 

  582. 

  583. 	<ul>
    584. 

  584. 	<li>You can add multiple joints between two bodies, but make sure that they don&#8217;t fight. It can cause the bodies to explode.</li>
    585. 

  585. 		<li>Make sure you add both of the connected bodies and the joint to a space.</li>
    586. 

  586. 	</ul>
    587. 

  587. 

  588. 

  589. 	<h3>Chipmunk spaces: <code>cpSpace</code></h3>
    590. 

  590. 

  591. 

  592. 	<p><strong>User accessible fields:</strong></p>
    593. 

  593. 

  594. 

  595. <pre><code>
    596. 

  596. typedef struct cpSpace{
    597. 

  597.     int iterations;
    598. 

  598. 

  599.     cpVect gravity;
    600. 

  600.     cpFloat damping;
    601. 

  601. 

  602.     int stamp;
    603. 

  603. } cpSpace;
    604. 

  604. </code></pre>
    605. 

  605. 

  606. 	<ul>
    607. 

  607. 	<li><code>iterations</code>: The number of iterations to use when solving constraints (collisions and joints). Defaults to 10.</li>
    608. 

  608. 		<li><code>gravity</code>: The amount of gravity applied to the system.</li>
    609. 

  609. 		<li><code>damping</code>: The amount of viscous damping applied to the system.</li>
    610. 

  610. 		<li><code>stamp</code>: The tick stamp. Incremented every time <code>cpSpaceStep()</code> is called. <em>read only</em></li>
    611. 

  611. 	</ul>
    612. 

  612. 

  613. 

  614. <pre><code>
    615. 

  615. void cpSpaceFreeChildren(cpSpace *space)
    616. 

  616. </code></pre>
    617. 

  617. 

  618. 	<p class="expl">Frees all bodies, shapes and joints added to the system.</p>
    619. 

  619. 

  620. 

  621. <pre><code>
    622. 

  622. cpSpace* cpSpaceAlloc(void)
    623. 

  623. cpSpace* cpSpaceInit(cpSpace *space, int iterations)
    624. 

  624. cpSpace* cpSpaceNew(int iterations)
    625. 

  625. 

  626. void cpSpaceDestroy(cpSpace *space)
    627. 

  627. void cpSpaceFree(cpSpace *space)
    628. 

  628. </code></pre>
    629. 

  629. 

  630. 	<p class="expl">More standard Chipmunk memory functions.</p>
    631. 

  631. 

  632. 

  633. <pre><code>
    634. 

  634. void cpSpaceFreeChildren(cpSpace *space)
    635. 

  635. </code></pre>
    636. 

  636. 

  637. 	<p class="expl">This function will free all of the shapes, bodies and joints that have been added to <code>space</code>.</p>
    638. 

  638. 

  639. 

  640. <pre><code>
    641. 

  641. void cpSpaceAddShape(cpSpace *space, cpShape *shape)
    642. 

  642. void cpSpaceAddStaticShape(cpSpace *space, cpShape *shape)
    643. 

  643. void cpSpaceAddBody(cpSpace *space, cpBody *body)
    644. 

  644. void cpSpaceAddJoint(cpSpace *space, cpJoint *joint)
    645. 

  645. 

  646. void cpSpaceRemoveShape(cpSpace *space, cpShape *shape)
    647. 

  647. void cpSpaceRemoveStaticShape(cpSpace *space, cpShape *shape)
    648. 

  648. void cpSpaceRemoveBody(cpSpace *space, cpBody *body)
    649. 

  649. void cpSpaceRemoveJoint(cpSpace *space, cpJoint *joint)
    650. 

  650. </code></pre>
    651. 

  651. 

  652. 	<p class="expl">These functions add and remove shapes, bodies and joints from <code>space</code>. Shapes added as static are assumed not to move. Static shapes should be be attached to a rigid body with an infinite mass and moment of inertia. Also, don&#8217;t add the rigid body used to the space, as that will cause it to fall under the effects of gravity.</p>
    653. 

  653. 

  654. 

  655. <pre><code>
    656. 

  656. void cpSpaceResizeStaticHash(cpSpace *space, cpFloat dim, int count)
    657. 

  657. void cpSpaceResizeActiveHash(cpSpace *space, cpFloat dim, int count)
    658. 

  658. </code></pre>
    659. 

  659. 

  660. 	<p class="expl">The spatial hashes used by Chipmunk&#8217;s collision detection are fairly size sensitive. <code>dim</code> is the size of the hash cells. Setting <code>dim</code> to the average objects size is likely to give the best performance.</p>
    661. 

  661. 

  662. 

  663. 	<p class="expl"><code>count</code> is the suggested minimum number of cells in the hash table. Bigger is better, but only to a point. Setting <code>count</code> to ~10x the number of objects in the hash is probably a good starting point.</p>
    664. 

  664. 

  665. 

  666. 	<p class="expl">By default, <code>dim</code> is 100.0, and <code>count</code> is 1000.</p>
    667. 

  667. 

  668. 

  669. <pre><code>
    670. 

  670. void cpSpaceRehashStatic(cpSpace *space)
    671. 

  671. </code></pre>
    672. 

  672. 

  673. 	<p class="expl">Rehashes the shapes in the static spatial hash. You only need to call this if you move one of the static shapes.</p>
    674. 

  674. 

  675. 

  676. <pre><code>
    677. 

  677. void cpSpaceStep(cpSpace *space, cpFloat dt)
    678. 

  678. </code></pre>
    679. 

  679. 

  680. 	<p class="expl">Update the space for the given time step. Using a fixed time step is <em>highly</em> recommended. Doing so will increase the efficiency of the contact persistence, requiring an order of magnitude fewer iterations to resolve the collisions in the usual case.</p>
    681. 

  681. 

  682. 

  683. 	<p><strong>Notes:</strong></p>
    684. 

  684. 

  685. 

  686. 	<ul>
    687. 

  687. 	<li>When removing objects from the space, make sure you remove any other objects that reference it. For instance, when you remove a body, remove the joints and shapes attached to it.</li>
    688. 

  688. 		<li>The number of iterations, and the size of the time step determine the quality of the simulation. More iterations, or smaller time steps increase the quality.</li>
    689. 

  689. 		<li>Because static shapes are only rehashed when you request it, it&#8217;s possible to use a much higher <code>count</code> argument to <code>cpHashResizeStaticHash()</code> than to <code>cpHashResizeStaticHash()</code>. Doing so will use more memory though.</li>
    690. 

  690. 	</ul>
    691. 

  691. 

  692. 

  693. 	<h3>Miscellaneous.</h3>
    694. 

  694. 

  695. 

  696. <pre><code>
    697. 

  697. cpFloat cpMomentForCircle(cpFloat m, cpFloat r1, cpFloat r2, cpVect offset)
    698. 

  698. </code></pre>
    699. 

  699. 

  700. 	<p class="expl">Calculate the moment of inertia for a circle. Arguments are similar to <code>cpCircleShapeInit()</code>. <em>m_ is the mass, _r1</em> and <em>r2</em> define an inner and outer radius, and <em>offset</em> is the offset of the center from the center of gravity of the rigid body.</p>
    701. 

  701. 

  702. 

  703. <pre><code>
    704. 

  704. cpFloat cpMomentForPoly(cpFloat m, int numVerts, cpVect *verts, cpVect offset)
    705. 

  705. </code></pre>
    706. 

  706. 

  707. 	<p class="expl">Calculate the moment of inertia for a poly. Arguments are similar to <code>cpPolyShapeInit()</code> <em>m_ is the mass, _numVerts</em> is the number of vertexes in <em>verts</em>, and <em>offset</em> is the offset of the poly coordinates from the center of gravity of the rigid body.</p>
    708. 

  708. 

  709. 

  710. 	<h3>Collision pair functions</h3>
    711. 

  711. 

  712. 

  713. 	<p>Collision pair functions allow you to add callbacks for certain collision events. Each <code>cpShape</code> structure has a user definable <code>collision_type</code> field that is used to identify its type. For instance, you could define an enumeration of collision types such as bullets and players, and then register a collision pair function to reduce the players health when a collision is found between the two.</p>
    714. 

  714. 

  715. 

  716. 	<p>Additionally, the return value of a collision pair function determines whether or not a collision will be processed. If the function returns false, the collision will be ignored. One use for this functionality is to allow a rock object to break a vase object. If the approximated energy of the collision is above a certain level, flag the vase to be removed from the space, apply an impulse to the rock to slow it down, and return false. After the <code>cpSpaceStep()</code> returns, remove the vase from the space.</p>
    717. 

  717. 

  718. 

  719. 	<p><strong><span class="caps">WARNING</span>:</strong> <em>It is not safe for collision pair functions to remove or free shapes or bodies from a space. Doing so will likely end in a segfault as an earlier collision may already be referencing the shape or body. You must wait until after the <code>cpSpaceStep()</code> function returns.</em></p>
    720. 

  720. 

  721. 

  722. <pre><code>
    723. 

  723. typedef struct cpContact{
    724. 

  724.     cpVect p, n;
    725. 

  725.     cpFloat dist;
    726. 

  726. 

  727.     cpFloat jnAcc, jtAcc;
    728. 

  728. } cpContact;
    729. 

  729. </code></pre>
    730. 

  730. 

  731. 	<p class="expl">An array of <code>cpContact</code> structs are passed to collision pair functions. Some user accessible fields include:</p>
    732. 

  732. 

  733. 

  734. 	<ul>
    735. 

  735. 	<li><code>p</code>: position of the collision.</li>
    736. 

  736. 		<li><code>n</code>: normal of the collision.</li>
    737. 

  737. 		<li><code>dist</code>: penetration distance of the collision.</li>
    738. 

  738. 		<li><code>jnAcc</code> and <code>jtAcc</code>: The normal and tangential components of the accumulated (final) impulse applied to resolve the collision. Values will not be valid until after the call to <code>cpSpaceStep()</code> returns.</li>
    739. 

  739. 	</ul>
    740. 

  740. 

  741. 

  742. <pre><code>
    743. 

  743. typedef int (*cpCollFunc)(cpShape *a, cpShape *b, cpContact *contacts, int numContacts, cpFloat normal_coef, void *data)
    744. 

  744. </code></pre>
    745. 

  745. 

  746. 	<p class="expl">Prototype for a collision callback function. The two colliding shapes are passed as <code>a</code> and <code>b</code>, along with the contact points, and a user definable pointer are passed as arguments. The shapes are passed in the same order as their types were registered using <code>cpSpaceAddCollisionPairFunc()</code>. Because Chipmunk may swap the shapes to accommodate your collision pair function the normals may be backwards. Always multiply the normals by <em>normal_coef</em> before using the values. The <code>contacts</code> array may be freed on the next call to <code>cpSpaceStep()</code>.</p>
    747. 

  747. 

  748. 

  749. <pre><code>
    750. 

  750. void cpSpaceAddCollisionPairFunc(cpSpace *space, unsigned long a, unsigned long b, cpCollFunc func, void *data)
    751. 

  751. </code></pre>
    752. 

  752. 

  753. 	<p class="expl">Register <code>func</code> to be called when a collision is found between a shapes with <code>collision_type</code> fields that match <code>a</code> and <code>b</code>. <code>data</code> is passed to <code>func</code> as a parameter. The ordering of the collision types will match the ordering passed to the callback function.</p>
    754. 

  754. 

  755. 

  756. 	<p class="expl">Passing <code>NULL</code> for <code>func</code> will reject any collision with the given collision type pair.</p>
    757. 

  757. 

  758. 

  759. <pre><code>
    760. 

  760. void cpSpaceRemoveCollisionPairFunc(cpSpace *space, unsigned long a, unsigned long b)
    761. 

  761. </code></pre>
    762. 

  762. 

  763. 	<p class="expl">Remove the function for the given collision type pair. The order of <code>a</code> and <code>b</code> must match the original order used with <code>cpSpaceAddCollisionPairFunc()</code>.</p>
    764. 

  764. 

  765. 

  766. <pre><code>
    767. 

  767. void cpSpaceSetDefaultCollisionPairFunc(cpSpace *space, cpCollFunc func, void *data)
    768. 

  768. </code></pre>
    769. 

  769. 

  770. 	<p class="expl">The default function is called when no collision pair function is specified. By default, the default function simply accepts all collisions. Passing <code>NULL</code> for <code>func</code> will reset the default function back to the default. (You know what I mean.)</p>
    771. 

  771. 

  772. 

  773. 	<p class="expl">Passing <code>NULL</code> for <code>func</code> will reject collisions by default.</p>
    774. 

  774. 

  775. 

  776. 	<h2>Advanced topics</h2>
    777. 

  777. 

  778. 

  779. 	<h3>Advanced collision processing</h3>
    780. 

  780. 

  781. 

  782. 	<p>Using collision pair functions, it&#8217;s possible to get information about a collision such as the locations of the contact points and the normals, but you can&#8217;t get the impulse applied to each contact point at the time the callback is called. Because Chipmunk caches the impulses, it is possible to access them after the call to <code>cpSpaceStep()</code> returns.</p>
    783. 

  783. 

  784. 

  785. 	<p>The impulse information is stored in the <code>jnAcc</code> and <code>jtAcc</code> fields of the <code>cpContact</code> structures passed to the collision pair function. So you must store a reference to the <code>contacts</code> array in the collision pair function so that you can access it later once the impulses have been calculated.</p>
    786. 

  786. 

  787. 

  788. <pre><code>
    789. 

  789. cpVect cpContactsSumImpulses(cpContact *contacts, int numContacts);
    790. 

  790. cpVect cpContactsSumImpulsesWithFriction(cpContact *contacts, int numContacts);
    791. 

  791. </code></pre>
    792. 

  792. 

  793. 	<p class="expl">Sums the impulses applied to the the given contact points. <code>cpContactsSumImpulses()</code> sums only the normal components, while <code>cpContactsSumImpulsesWithFriction()</code> sums the normal and tangential componets.</p>
    794. 

  794. 

  795. 

  796. 	<p><strong>Notes:</strong></p>
    797. 

  797. 

  798. 

  799. 	<ul>
    800. 

  800. 	<li>The <code>contact</code> array will either be destroyed or out of date after the next call to <code>cpSpaceStep()</code>. If you need to store the collision information permanently, you&#8217;ll have to copy it.</li>
    801. 

  801. 	</ul>
    802. 

  802. 

  803. 

  804. 	<h3>Collision pair functions, groups, and layers</h3>
    805. 

  805. 

  806. 

  807. 	<p>There are three ways that you can specify which shapes are allowed to collide in Chipmunk: collision pair functions, groups, and layers. What are their intended purposes?</p>
    808. 

  808. 

  809. 

  810. 	<p><strong>Collision pair functions:</strong> More than just a callback, collision pair functions can conditionally allow a collision between two shapes. This is the only choice if you need to perform some logic based on the shapes or contact information before deciding to allow the collision.</p>
    811. 

  811. 

  812. 

  813. 	<p><strong>Groups:</strong> Groups filter out collisions between objects in the same non-zero groups. A good example of when groups would be useful is to create a multi-body, multi-shape object such as a ragdoll. You don&#8217;t want the parts of the ragdoll to collide with itself, but you do want it to collide with other ragdolls.</p>
    814. 

  814. 

  815. 

  816. 	<p><strong>Layers:</strong> Layers are another way of grouping shapes. Collision between shapes that don&#8217;t occupy one or more of the same layers are filtered out. Layers are implemented using a bitmask on an unsigned long, so there are up to 32 layers available.</p>
    817. 

  817. 

  818. 

  819. 	<p>To be clear, for a collision to occur, all of the tests have to pass. Additionally, collisions between static shapes are not considered nor are collisions between shapes connected to the same rigid body.</p>
    820. 

  820. 

  821. 

  822. 	<h3>Mysteries of <code>cpSpaceStep()</code> explained.</h3>
    823. 

  823. 

  824. 

  825. 	<p>The <code>cpSpaceStep()</code> function is really the workhorse of Chipmunk. So what exactly does it do?</p>
    826. 

  826. 

  827. 

  828. 	<ul>
    829. 

  829. 	<li>Persistent contacts with a stamp that is out of date by more than <code>cp_contact_persistence</code> are filtered out.</li>
    830. 

  830. 		<li>Velocities of all rigid bodies in the space are integrated using <code>cpBodyUpdateVelocity()</code>.</li>
    831. 

  831. 		<li>All active shapes have their bounding boxes calculated and cached.</li>
    832. 

  832. 		<li>Collisions between the active shapes and static shapes are found. (collision pair functions are called)</li>
    833. 

  833. 		<li>Collisions between the active shapes are found. (collision pair functions are called)</li>
    834. 

  834. 		<li>Information about all constraints (collisions and joints) is pre-calculated.</li>
    835. 

  835. 		<li>Impulses are found and applied to solve all constraints (joints and collisions).</li>
    836. 

  836. 		<li>Positions of all rigid bodies in the space are integrated using <code>cpBodyUpdatePosition()</code>.</li>
    837. 

  837. 	</ul>
    838. 

  838. 

  839. 

  840. 	<p>Chipmunk does a lot of processing on the shapes in the system in order to provide robust and fast collision detection, but the same is not true of the rigid bodies. Really all <code>cpSpaceStep()</code> does to the bodies in the system is to integrate them and apply impulses to them.</p>
    841. 

  841. 

  842. 

  843. 	<p>The integration step is really just for convenience. If you integrate the velocity of your rigid bodies before calling <code>cpSpaceStep()</code> and integrate their positions afterward, you don&#8217;t have to add them to the space at all. In fact, there are good reasons for not doing so. All bodies in the space are integrated using the same gravity and damping, and this prevents you from providing interesting objects such as moving platforms.</p>
    844. 

  844. 

  845. 

  846. 	<p>If you are going to do the integration for your rigid bodies manually, I would highly recommend that you use <code>cpBodyUpdatePosition()</code> to integrate the position of the objects and only integrate the velocity. <code>cpBodyUpdatePosition()</code> is a required step for penetration resolution, and weird things could happen if it&#8217;s not called. Chipmunk uses Euler integration, so calculating the velocity required to move a body to a specific position is trivial if that is what you wish to do.</p>
    847. 

  847. 

  848. 

  849. 	<h3>Chipmunk globals.</h3>
    850. 

  850. 

  851. 

  852. 	<p>Chipmunk was designed with multithreading in mind, so very few globals are used. This shouldn&#8217;t be a problem in most cases as it&#8217;s likely you&#8217;ll only need to set them on a per application basis (if at all).</p>
    853. 

  853. 

  854. 

  855. 	<p><code>int cp_contact_persistence</code>: This determines how long contacts should persist. This number should be fairly small as the cached contacts will only be close for a short time. <code>cp_contact_persistence</code> defaults to 3 as it is large enough to help prevent oscillating contacts, but doesn&#8217;t allow stale contact information to be used.</p>
    856. 

  856. 

  857. 

  858. 	<p><code>cpFloat cp_collision_slop</code>: The amount that shapes are allowed to penetrate. Setting this to zero will work just fine, but using a small positive amount will help prevent oscillating contacts. <code>cp_collision_slop</code> defaults to 0.1.</p>
    859. 

  859. 

  860. 

  861. 	<p><code>cpFloat cp_bias_coef</code>: The amount of penetration to reduce in each step. Values should range from 0 to 1. Using large values will eliminate penetration in fewer steps, but can cause vibration. <code>cp_bias_coef</code> defaults to 0.1.</p>
    862. 

  862. 

  863. 

  864. 	<p><code>cpFloat cp_joint_bias_coef</code>: Similar to <code>cp_bias_coef</code>, but for joints. Defaults to 0.1. <em>In the future, joints might have their own bias coefficient instead.</em></p>
    865. 

  865. 

  866. 

  867. 	<h2>Known Problems</h2>
    868. 

  868. 

  869. 

  870. 	<ul>
    871. 

  871. 	<li>Fast moving objects sometimes pass right through one another. This is because I&#8217;m not doing swept volume collisions. Use smaller time steps if this is a problem.</li>
    872. 

  872. 		<li>Pointy or thin polygons aren&#8217;t handled well. Collision points are generated at the poly&#8217;s vertexes. I haven&#8217;t decided what to do about this yet.</li>
    873. 

  873. 		<li>Elastic shapes don&#8217;t stack well.</li>
    874. 

  874. 	</ul>
    875. 

  875. 

  876. 

  877. 	<h2>Performance/Quality tuning</h2>
    878. 

  878. 

  879. 

  880. 	<p>There are a number of things you can do to increase the performance of Chipmunk:</p>
    881. 

  881. 

  882. 

  883. 	<ul>
    884. 

  884. 	<li>Use simpler collision shapes when possible. It&#8217;s easier on the collision detection, you&#8217;ll generate fewer contact points, and require fewer iterations.</li>
    885. 

  885. 		<li>Make sure you have your spatial hashes tuned properly. It may take some experimenting to find the optimal dim/count parameters.</li>
    886. 

  886. 		<li>Use fewer iterations.</li>
    887. 

  887. 		<li>Use a larger time step.</li>
    888. 

  888. 		<li>Use a fixed time step. This allows contact persistence to work properly, reducing the number of iterations you need by an order of magnitude.</li>
    889. 

  889. 	</ul>
    890. 

  890. 

  891. 

  892. 	<p>If you have problems with jittery or vibrating objects, you need to do mostly the opposite:</p>
    893. 

  893. 

  894. 

  895. 	<ul>
    896. 

  896. 	<li>Use simpler shapes. Simpler shapes generate fewer contacts, increasing the efficiency of each iteration.</li>
    897. 

  897. 		<li>Use more iterations.</li>
    898. 

  898. 		<li>Use a smaller time step.</li>
    899. 

  899. 		<li>Use a fixed time step. By allowing the contact persistence to work properly, you can use more iterations without increasing the computational cost.</li>
    900. 

  900. 	</ul>
    901. 

  901. 

  902. 

  903. 	<h2>To do</h2>
    904. 

  904. 

  905. 

  906. There are a number of things left on my todo list:
    907. 

  907. 	<ul>
    908. 

  908. 	<li>More joint types.</li>
    909. 

  909. 		<li>Post collision queries. Being able to query for all the impulses that were applied to an object would be useful.</li>
    910. 

  910. 		<li>Python binding. (possibly others if I can get help)</li>
    911. 

  911. 	</ul>
    912. 

  912. 

  913. 

  914. 	<h2>Contact information</h2>
    915. 

  915. 

  916. 

  917. 	<p>Drop me a line. Tell me how great you think Chipmunk is or how terribly buggy it is. I&#8217;d love to hear about any project that people are using Chipmunk for.</p>
    918. 

  918. 

  919. 

  920. 	<p><strong><span class="caps">AIM</span>:</strong> slembcke@mac.com</p>
    921. 

  921. 

  922. 

  923. 	<p><strong>Email:</strong> lemb0029(at)morris(dot)umn(dot)edu or slembcke(at)gmail(dot)com</p>
    924. 

  924. 

  925. 

  926. 	<p>I can also be found lurking about the <a href="http://www.idevgames.com">iDevGames</a> forums.</p>
    927. 

  927. 

  928. 

  929. 	<h2>License</h2>
    930. 

  930. 

  931. 

  932. 	<p>Copyright&#169; 2007 Scott Lembcke</p>
    933. 

  933. 

  934. 

  935. 	<p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the &#8220;Software&#8221;), 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:</p>
    936. 

  936. 

  937. 

  938. 	<p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>
    939. 

  939. 

  940. 

  941. <span class="caps">THE SOFTWARE IS PROVIDED</span> &#8220;AS IS&#8221;, <span class="caps">WITHOUT WARRANTY OF ANY KIND</span>, EXPRESS <span class="caps">OR IMPLIED</span>, INCLUDING <span class="caps">BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY</span>, FITNESS <span class="caps">FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT</span>. IN <span class="caps">NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM</span>, DAMAGES <span class="caps">OR OTHER LIABILITY</span>, WHETHER <span class="caps">IN AN ACTION OF CONTRACT</span>, TORT <span class="caps">OR OTHERWISE</span>, ARISING <span class="caps">FROM</span>, OUT <span class="caps">OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE</span>.
    942. 

  942. 

  943.     </body>
    944. 

  944. </html>
    945. 

  945.