Sie sind auf Seite 1von 66

!"#$% '$($() *+,- .

/01/2
!"#$%&'() + ,--./,-00 1%&2 !3))"
ChapLer 1 lnLroducLlon ............................................................................................................................ 2
ChapLer 2 Pello 8ox2u............................................................................................................................. 8
ChapLer 3 Common ............................................................................................................................... 14
ChapLer 4 Colllslon Module ................................................................................................................... 16
ChapLer 3 uynamlcs Module .................................................................................................................. 27
ChapLer 6 llxLures ................................................................................................................................. 28
ChapLer 7 8odles ................................................................................................................................... 32
ChapLer 8 !olnLs ..................................................................................................................................... 39
ChapLer 9 ConLacLs ................................................................................................................................ 48
ChapLer 10 World Class ......................................................................................................................... 36
ChapLer 11 Loose Lnds .......................................................................................................................... 62
ChapLer 12 uebug urawlng .................................................................................................................... 64
ChapLer 13 LlmlLaLlons .......................................................................................................................... 63
ChapLer 14 8eferences .......................................................................................................................... 66

!"#$%&' ) *+%',-./%0,+
)1) 23,.%
8ox2u ls a 2u rlgld body slmulaLlon llbrary for games. rogrammers can use lL ln Lhelr games Lo make
ob[ecLs move ln bellevable ways and make Lhe game world more lnLeracLlve. lrom Lhe game englne's
polnL of vlew a physlcs englne ls [usL a sysLem for procedural anlmaLlon.
8ox2u ls wrlLLen ln porLable C++. MosL of Lhe Lypes deflned ln Lhe englne begln wlLh Lhe b2 preflx.
Popefully Lhls ls sufflclenL Lo avold name clashlng wlLh your game englne.
)14 5'&'&6.070%&7
ln Lhls manual l'll assume you are famlllar wlLh baslc physlcs concepLs, such as mass, force, Lorque, and
lmpulses. lf noL, please flrsL consulL Coogle search and Wlklpedla.
8ox2u was creaLed as parL of a physlcs LuLorlal aL Lhe Came ueveloper Conference. ?ou can geL Lhese
LuLorlals from Lhe download secLlon of box2d.org.
Slnce 8ox2u ls wrlLLen ln C++, you are expecLed Lo be experlenced ln C++ programmlng. 8ox2u should
noL be your flrsL C++ programmlng pro[ecL. ?ou should be comforLable wlLh complllng, llnklng, and
debugglng.
!"#$%&'
8ox2u should noL be your flrsL C++ pro[ecL. lease learn C++ programmlng,
complllng, llnklng, and debugglng before worklng wlLh 8ox2u. 1here are many
resources for Lhls on Lhe neL.
)18 23,.% %"07 9#+.#:
1hls manual covers Lhe ma[orlLy of Lhe 8ox2u Al. Powever, noL every aspecL ls covered. ?ou are
encouraged Lo look aL Lhe LesLbed lncluded wlLh 8ox2u Lo learn more. Also, Lhe 8ox2u code base has
commenLs formaLLed for uoxygen, so lL ls easy Lo creaLe a hyper-llnked Al documenL.
1hls manual ls only updaLed wlLh new releases. 1he verslon ln source conLrol ls llkely Lo be ouL of daLe.
)1; <&&-3#/= #+- >&$,'%0+? @.?7
lf you have a quesLlon or feedback abouL 8ox2u, please leave a commenL ln Lhe forum. 1hls ls also a
greaL place for communlLy dlscusslon.
8ox2u lssues are Lracked uslng a Coogle code pro[ecL. 1hls ls a greaL way Lo Lrack lssues and ensures
LhaL your lssue wlll noL be losL ln Lhe depLhs of Lhe forums.
lease flle bugs and feaLure requesLs here: hLLp://code.google.com/p/box2d/
?ou can help Lo ensure your lssue geLs flxed lf you provlde sufflclenL deLall. A LesLbed example LhaL
reproduces Lhe problem ls ldeal. ?ou can read abouL Lhe LesLbed laLer ln Lhls documenL.
)1A !,'& !,+/&$%7
8ox2u works wlLh several fundamenLal ob[ecLs. We brlefly deflne Lhese ob[ecLs here and more deLalls
are glven laLer ln Lhls documenL.
!"#$%
A 2u geomeLrlcal ob[ecL, such as a clrcle or polygon.
'()(* +,*-
A chunk of maLLer LhaL ls so sLrong LhaL Lhe dlsLance beLween any Lwo blLs of maLLer on Lhe chunk ls
consLanL. 1hey are hard llke a dlamond. ln Lhe followlng dlscusslon we use body lnLerchangeably wlLh
rlgld body.
.(/01'%
A flxLure blnds a shape Lo a body and adds maLerlal properLles such as denslLy, frlcLlon, and resLlLuLlon.
2,3!0'#(30
A consLralnL ls a physlcal connecLlon LhaL removes degrees of freedom from bodles. ln 2u a body has 3
degrees of freedom (Lwo LranslaLlon coordlnaLes and one roLaLlon coordlnaLe). lf we Lake a body and pln
lL Lo Lhe wall (llke a pendulum) we have consLralned Lhe body Lo Lhe wall. AL Lhls polnL Lhe body can only
roLaLe abouL Lhe pln, so Lhe consLralnL has removed 2 degrees of freedom.
2,30#20 2,3!0'#(30
A speclal consLralnL deslgned Lo prevenL peneLraLlon of rlgld bodles and Lo slmulaLe frlcLlon and
resLlLuLlon. ?ou do noL creaLe conLacL consLralnLs, Lhey are creaLed auLomaLlcally by 8ox2u.
4,(30
1hls ls a consLralnL used Lo hold Lwo or more bodles LogeLher. 8ox2u supporLs several [olnL Lypes:
revoluLe, prlsmaLlc, dlsLance, and more. Some [olnLs may have llmlLs and moLors.
4,(30 5(6(0
A [olnL llmlL resLrlcLs Lhe range of moLlon of a [olnL. lor example, Lhe human elbow only allows a cerLaln
range of angles.
4,(30 6,0,'
A [olnL moLor drlves Lhe moLlon of Lhe connecLed bodles accordlng Lo Lhe [olnL's degrees of freedom. lor
example, you can use a moLor Lo drlve Lhe roLaLlon of an elbow.
7,'5*
A physlcs world ls a collecLlon of bodles, flxLures, and consLralnLs LhaL lnLeracL LogeLher. 8ox2u supporLs
Lhe creaLlon of mulLlple worlds, buL Lhls ls usually noL necessary or deslrable.
!,58%'
1he physlcs world has a solver LhaL ls used Lo advance Llme and Lo resolve conLacL and [olnL consLralnLs.
1he 8ox2u solver ls a hlgh performance lLeraLlve solver LhaL operaLes ln order n Llme, where n ls Lhe
number of consLralnLs.
2,30(31,1! 2,55(!(,3
1he solver advances bodles ln Llme uslng dlscreLe Llme sLeps. WlLhouL lnLervenLlon Lhls can lead Lo
Lunnellng.

8ox2u conLalns speclallzed algorlLhms Lo deal wlLh Lunnellng. llrsL, Lhe colllslon algorlLhms can
lnLerpolaLe Lhe moLlon of Lwo bodles Lo flnd Lhe flrsL Llme of lmpacL (1Cl). Second, Lhere ls a sub-
sLepplng solver LhaL moves bodles Lo Lhelr flrsL Llme of lmpacL and Lhen resolves Lhe colllslon.
)1B 9,-.:&7
8ox2u ls composed of Lhree modules: Common, Colllslon, and uynamlcs. 1he Common module has code
for allocaLlon, maLh, and seLLlngs. 1he Colllslon module deflnes shapes, a broad-phase, and colllslon
funcLlons/querles. llnally Lhe uynamlcs module provldes Lhe slmulaLlon world, bodles, flxLures, and
[olnLs.

)1C D+0%7
8ox2u works wlLh floaLlng polnL numbers and Lolerances have Lo be used Lo make 8ox2u perform well.
1hese Lolerances have been Luned Lo work well wlLh meLers-kllogram-second (MkS) unlLs. ln parLlcular,
8ox2u has been Luned Lo work well wlLh movlng ob[ecLs beLween 0.1 and 10 meLers. So Lhls means
ob[ecLs beLween soup cans and buses ln slze should work well. SLaLlc ob[ecLs may be up Lo 30 meLers blg
wlLhouL Loo much Lrouble.
8elng a 2u physlcs englne, lL ls LempLlng Lo use plxels as your unlLs. unforLunaLely Lhls wlll lead Lo a poor
slmulaLlon and posslbly welrd behavlor. An ob[ecL of lengLh 200 plxels would be seen by 8ox2u as Lhe
slze of a 43 sLory bulldlng.
!"#$%&'
8ox2u ls Luned for MkS unlLs. keep Lhe slze of movlng ob[ecLs roughly beLween 0.1
and 10 meLers. ?ou'll need Lo use some scallng sysLem when you render your
envlronmenL and acLors. 1he 8ox2u LesLbed does Lhls by uslng an CpenCL vlewporL
Lransform. uC nC1 uSL lxLLS.
lL ls besL Lo Lhlnk of 8ox2u bodles as movlng blllboards upon whlch you aLLach your arLwork. 1he
blllboard may move ln a unlL sysLem of meLers, buL you can converL LhaL Lo plxel coordlnaLes wlLh a
slmple scallng facLor. ?ou can Lhen use Lhose plxel coordlnaLes Lo place your sprlLes, eLc.
8ox2u uses radlans for angles. 1he body roLaLlon ls sLored ln radlans and may grow unbounded.
Conslder normallzlng Lhe angle of your bodles lf Lhe magnlLude of Lhe angle becomes Loo large (use
b28ody::SeLAngle).
)1E <#/%,'0&7 #+- F&G0+0%0,+7
Memory managemenL plays a cenLral role ln Lhe deslgn of Lhe 8ox2u Al. So when you creaLe a b28ody
or a b2!olnL, you need Lo call Lhe facLory funcLlons on b2World. ?ou should never Lry Lo allocaLe Lhese
Lypes ln anoLher manner.
1here are creaLlon funcLlons:
!"#$%&' !")$*+%,,-*./0.#$%&12$340 !"#$%&5.6' %.67
!"8$930' !")$*+%,,-*./0.8$93012$340 !"8$9305.6' %.67
And Lhere are correspondlng desLrucLlon funcLlons:
:$9% !")$*+%,,5.40*$&#$%&1!"#$%&' !$%&7
:$9% !")$*+%,,5.40*$&8$9301!"8$930' ;$9307
When you creaLe a body or [olnL, you need Lo provlde a deflnlLlon. 1hese deflnlLlons conLaln all Lhe
lnformaLlon needed Lo bulld Lhe body or [olnL. 8y uslng Lhls approach we can prevenL consLrucLlon
errors, keep Lhe number of funcLlon parameLers small, provlde senslble defaulLs, and reduce Lhe
number of accessors.
Slnce flxLures musL be parenLed Lo a body, Lhey are creaLed and desLroyed uslng a facLory meLhod on
b28ody:
!"<9=0>*.' !"#$%&,,-*./0.<9=0>*.12$340 !"<9=0>*.5.6' %.67
:$9% !"#$%&,,5.40*$&<9=0>*.1!"<9=0>*.' 69=0>*.7
1here ls also shorLcuL Lo creaLe a flxLure dlrecLly from Lhe shape and denslLy.
!"<9=0>*.' !"#$%&,,-*./0.<9=0>*.12$340 !"?@/A.' 4@/A.B 6+$/0C" %.3490&7
lacLorles do noL reLaln references Lo Lhe deflnlLlons. So you can creaLe deflnlLlons on Lhe sLack and keep
Lhem ln Lemporary resources.
)1H D7&' F#%#
1he b2llxLure, b28ody, and b2!olnL classes allow you Lo aLLach user daLa as a vold polnLer. 1hls ls handy
when you are examlnlng 8ox2u daLa sLrucLures and you wanL Lo deLermlne how Lhey relaLe Lo Lhe
enLlLles ln your game englne.
lor example, lL ls Lyplcal Lo aLLach an acLor polnLer Lo Lhe rlgld body on LhaL acLor. 1hls seLs up a clrcular
reference. lf you have Lhe acLor, you can geL Lhe body. lf you have Lhe body, you can geL Lhe acLor.
D/E.F20$*' /20$* G D/E.-*./0.F20$*17H
!"#$%&5.6 !$%&5.6H
!$%&5.6I>4.*5/0/ G /20$*H
/20$*JK!$%& G !$="5L$*+%JK-*./0.#$%&1M!$%&5.67H
Pere are some examples of cases where you would need Lhe user daLa:
Applylng damage Lo an acLor uslng a colllslon resulL.
laylng a scrlpLed evenL lf Lhe player ls lnslde an axls-allgned box.
Accesslng a game sLrucLure when 8ox2u noLlfles you LhaL a [olnL ls golng Lo be desLroyed.
keep ln mlnd LhaL user daLa ls opLlonal and you can puL anyLhlng ln lL. Powever, you should be
conslsLenL. lor example, lf you wanL Lo sLore an acLor polnLer on one body, you should keep an acLor
polnLer on all bodles. uon'L sLore an acLor polnLer on one body, and a foo polnLer on anoLher body.
CasLlng an acLor polnLer Lo a foo polnLer may lead Lo a crash.
user daLa polnLers are nuLL by defaulL.

!"#$%&' 4 I&::, @,J4F
ln Lhe dlsLrlbuLlon of 8ox2u ls a Pello World pro[ecL. 1he program creaLes a large ground box and a small
dynamlc box. 1hls code does noL conLaln any graphlcs. All you wlll see ls LexL ouLpuL ln Lhe console of Lhe
box's poslLlon over Llme.
1hls ls a good example of how Lo geL up and runnlng wlLh 8ox2u.
41) !'&#%0+? # K,':-
Lvery 8ox2u program beglns wlLh Lhe creaLlon of a b2World ob[ecL. b2World ls Lhe physlcs hub LhaL
manages memory, ob[ecLs, and slmulaLlon. ?ou can allocaLe Lhe physlcs world on Lhe sLack, heap, or
daLa secLlon.
lL ls easy Lo creaLe a 8ox2u world. llrsL, we deflne Lhe gravlLy vecLor. Also we Lell Lhe world Lo allow
bodles Lo sleep when Lhey come Lo resL. A sleeplng body doesn'L requlre any slmulaLlon.
!"N.2" O*/:90&1PIP6B JQPIP67H
!$$+ %$?+..A G 0*>.H
now we creaLe Lhe world ob[ecL. noLe LhaL we are creaLlng Lhe world on Lhe sLack, so Lhe world musL
remaln ln scope.
!")$*+% L$*+%1O*/:90&B %$?+..A7H
So now we have our physlcs world, leL's sLarL addlng some sLuff Lo lL.
414 !'&#%0+? # L',.+- @,J
8odles are bullL uslng Lhe followlng sLeps:
1. ueflne a body wlLh poslLlon, damplng, eLc.
2. use Lhe world ob[ecL Lo creaLe Lhe body.
3. ueflne flxLures wlLh a shape, frlcLlon, denslLy, eLc.
4. CreaLe flxLures on Lhe body.
lor sLep 1 we creaLe Lhe ground body. lor Lhls we need a body deflnlLlon. WlLh Lhe body deflnlLlon we
speclfy Lhe lnlLlal poslLlon of Lhe ground body.
!"#$%&5.6 O*$>3%#$%&5.6H
O*$>3%#$%&5.6IA$4909$3I?.01PIP6B JQPIP67H
lor sLep 2 Lhe body deflnlLlon ls passed Lo Lhe world ob[ecL Lo creaLe Lhe ground body. 1he world ob[ecL
does noL keep a reference Lo Lhe body deflnlLlon. 8odles are sLaLlc by defaulL. SLaLlc bodles don'L colllde
wlLh oLher sLaLlc bodles and are lmmovable.
!"#$%&' O*$>3%#$%& G L$*+%I-*./0.#$%&1MO*$>3%#$%&5.67H
lor sLep 3 we creaLe a ground polygon. We use Lhe SeLAs8ox shorLcuL Lo form Lhe ground polygon lnLo a
box shape, wlLh Lhe box cenLered on Lhe orlgln of Lhe parenL body.
!"R$+&O$3?@/A. O*$>3%#$=H
O*$>3%#$=I?.0F4#$=1SPIP6B QPIP67H
1he SeLAs8ox funcLlon Lakes Lhe half-wldLh and half-helghL (exLenLs). So ln Lhls case Lhe ground box ls
100 unlLs wlde (x-axls) and 20 unlLs Lall (y-axls). 8ox2u ls Luned for meLers, kllograms, and seconds. So
you can conslder Lhe exLenLs Lo be ln meLers. 8ox2u generally works besL when ob[ecLs are Lhe slze of
Lyplcal real world ob[ecLs. lor example, a barrel ls abouL 1 meLer Lall. uue Lo Lhe llmlLaLlons of floaLlng
polnL arlLhmeLlc, uslng 8ox2u Lo model Lhe movemenL of glaclers or dusL parLlcles ls noL a good ldea.
We flnlsh Lhe ground body ln sLep 4 by creaLlng Lhe shape flxLure. lor Lhls sLep we have a shorLcuL. We
do noL have a need Lo alLer Lhe defaulL flxLure maLerlal properLles, so we can pass Lhe shape dlrecLly Lo
Lhe body wlLhouL creaLlng a flxLure deflnlLlon. LaLer we wlll see how Lo use a flxLure deflnlLlon for
cusLomlzed maLerlal properLles. 1he second parameLer ls Lhe shape denslLy ln kllograms per meLer
squared. A sLaLlc body has zero mass by deflnlLlon, so Lhe denslLy ls noL used ln Lhls case.
O*$>3%#$%&JK-*./0.<9=0>*.1MO*$>3%#$=B PIP67H
8ox2u does noL keep a reference Lo Lhe shape. lL clones Lhe daLa lnLo a new b2Shape ob[ecL.
noLe LhaL every flxLure musL have a parenL body, even flxLures LhaL are sLaLlc. Powever, you can aLLach
all sLaLlc flxLures Lo a slngle sLaLlc body.
418 !'&#%0+? # FM+#N0/ @,-M
So now we have a ground body. We can use Lhe same Lechnlque Lo creaLe a dynamlc body. 1he maln
dlfference, besldes dlmenslons, ls LhaL we musL esLabllsh Lhe dynamlc body's mass properLles.
llrsL we creaLe Lhe body uslng CreaLe8ody. 8y defaulL bodles are sLaLlc, so we should seL Lhe
b28ody1ype aL consLrucLlon Llme Lo make Lhe body dynamlc.
!"#$%&5.6 !$%&5.6H
!$%&5.6I0&A. G !"T%&3/E92#$%&H
!$%&5.6IA$4909$3I?.01PIP6B UIP67H
!"#$%&' !$%& G L$*+%I-*./0.#$%&1M!$%&5.67H
CauLlon
?ou musL seL Lhe body Lype Lo b2_dynamlc8ody lf you wanL Lhe body Lo move ln
response Lo forces.
nexL we creaLe and aLLach a polygon shape uslng a flxLure deflnlLlon. llrsL we creaLe a box shape:
!"R$+&O$3?@/A. %&3/E92#$=H
%&3/E92#$=I?.0F4#$=1QIP6B QIP67H
nexL we creaLe a flxLure deflnlLlon uslng Lhe box. noLlce LhaL we seL denslLy Lo 1. 1he defaulL denslLy ls
zero. Also, Lhe frlcLlon on Lhe shape ls seL Lo 0.3.
!"<9=0>*.5.6 69=0>*.5.6H
69=0>*.5.6I4@/A. G M%&3/E92#$=H
69=0>*.5.6I%.3490& G QIP6H
69=0>*.5.6I6*9209$3 G PIC6H
uslng Lhe flxLure deflnlLlon we can now creaLe Lhe flxLure. 1hls auLomaLlcally updaLes Lhe mass of Lhe
body. ?ou can add as many flxLures as you llke Lo a body. Lach one conLrlbuLes Lo Lhe LoLal mass.
!$%&JK-*./0.<9=0>*.1M69=0>*.5.67H
1haL's lL for lnlLlallzaLlon. We are now ready Lo begln slmulaLlng.
41; O0N.:#%0+? %"& K,':- P,G @,J4FQ
So we have lnlLlallzed Lhe ground box and a dynamlc box. now we are ready Lo seL newLon loose Lo do
hls Lhlng. We [usL have a couple more lssues Lo conslder.
8ox2u uses a compuLaLlonal algorlLhm called an lnLegraLor. lnLegraLors slmulaLe Lhe physlcs equaLlons
aL dlscreLe polnLs of Llme. 1hls goes along wlLh Lhe LradlLlonal game loop where we essenLlally have a
fllp book of movemenL on Lhe screen. So we need Lo plck a Llme sLep for 8ox2u. Cenerally physlcs
englnes for games llke a Llme sLep aL leasL as fasL as 60Pz or 1/60 seconds. ?ou can geL away wlLh larger
Llme sLeps, buL you wlll have Lo be more careful abouL seLLlng up Lhe deflnlLlons for your world. We also
don'L llke Lhe Llme sLep Lo change much. A varlable Llme sLep produces varlable resulLs, whlch makes lL
dlfflculL Lo debug. So don'L Lle Lhe Llme sLep Lo your frame raLe (unless you really, really have Lo).
WlLhouL furLher ado, here ls Lhe Llme sLep.
6+$/0C" 09E.?0.A G QIP6 V WPIP6H
ln addlLlon Lo Lhe lnLegraLor, 8ox2u also uses a larger blL of code called a consLralnL solver. 1he
consLralnL solver solves all Lhe consLralnLs ln Lhe slmulaLlon, one aL a Llme. A slngle consLralnL can be
solved perfecLly. Powever, when we solve one consLralnL, we sllghLly dlsrupL oLher consLralnLs. 1o geL a
good soluLlon, we need Lo lLeraLe over all consLralnLs a number of Llmes.
1here are Lwo phases ln Lhe consLralnL solver: a veloclLy phase and a poslLlon phase. ln Lhe veloclLy
phase Lhe solver compuLes Lhe lmpulses necessary for Lhe bodles Lo move correcLly. ln Lhe poslLlon
phase Lhe solver ad[usLs Lhe poslLlons of Lhe bodles Lo reduce overlap and [olnL deLachmenL. Lach phase
has lLs own lLeraLlon counL. ln addlLlon, Lhe poslLlon phase may exlL lLeraLlons early lf Lhe errors are
small.
1he suggesLed lLeraLlon counL for 8ox2u ls 8 for veloclLy and 3 for poslLlon. ?ou can Lune Lhls number Lo
your llklng, [usL keep ln mlnd LhaL Lhls has a Lrade-off beLween speed and accuracy. uslng fewer
lLeraLlons lncreases performance buL accuracy suffers. Llkewlse, uslng more lLeraLlons decreases
performance buL lmproves Lhe quallLy of your slmulaLlon. lor Lhls slmple example, we don'L need much
lLeraLlon. Pere are our chosen lLeraLlon counLs.
930C" :.+$290&X0.*/09$34 G WH
930C" A$4909$3X0.*/09$34 G "H
noLe LhaL Lhe Llme sLep and Lhe lLeraLlon counL are compleLely unrelaLed. An lLeraLlon ls noL a sub-sLep.
Cne solver lLeraLlon ls a slngle pass over all Lhe consLralnLs wlLhln a Llme sLep. ?ou can have mulLlple
passes over Lhe consLralnLs wlLhln a slngle Llme sLep.
We are now ready Lo begln Lhe slmulaLlon loop. ln your game Lhe slmulaLlon loop can be merged wlLh
your game loop. ln each pass Lhrough your game loop you call b2World::SLep. !usL one call ls usually
enough, dependlng on your frame raLe and your physlcs Llme sLep.
1he Pello World program was deslgned Lo be slmple, so lL has no graphlcal ouLpuL. 1he code prlnLs ouL
Lhe poslLlon and roLaLlon of Lhe dynamlc body. Pere ls Lhe slmulaLlon loop LhaL slmulaLes 60 Llme sLeps
for a LoLal of 1 second of slmulaLed Llme.
6$* 1930C" 9 G PH 9 Y WPH ZZ97
[
L$*+%I?0.A109E.?0.AB :.+$290&X0.*/09$34B A$4909$3X0.*/09$347H
!"N.2" A$4909$3 G !$%&JKD.0R$4909$317H
6+$/0C" /3O+. G !$%&JKD.0F3O+.17H
A*93061\]UI"6 ]UI"6 ]UI"6^3\B A$4909$3I=B A$4909$3I&B /3O+.7H
_
1he ouLpuL shows Lhe box falllng and landlng on Lhe ground box. ?our ouLpuL should look llke Lhls:
PIPP UIPP PIPP
PIPP CI`` PIPP
PIPP CI`a PIPP
III
PIPP QI"S PIPP
PIPP QIQC PIPP
PIPP QIPQ PIPP
41A !:&#+.$
When a world leaves scope or ls deleLed by calllng deleLe on a polnLer, all Lhe memory reserved for
bodles, flxLures, and [olnLs ls freed. 1hls ls done Lo lmprove performance and make your llfe easler.
Powever, you wlll need Lo nulllfy any body, flxLure, or [olnL polnLers you have because Lhey wlll become
lnvalld.
41B R"& R&7%3&-
Cnce you have conquered Lhe PelloWorld example, you should sLarL looklng aL 8ox2u's LesLbed. 1he
LesLbed ls a unlL-LesLlng framework and demo envlronmenL. Pere are some of Lhe feaLures:
Camera wlLh pan and zoom.
Mouse plcklng of shapes aLLached Lo dynamlc bodles.
LxLenslble seL of LesLs.
Cul for selecLlng LesLs, parameLer Lunlng, and debug drawlng opLlons.
ause and slngle sLep slmulaLlon.
1exL renderlng.

1he LesLbed has many examples of 8ox2u usage ln Lhe LesL cases and Lhe framework lLself. l encourage
you Lo explore and Llnker wlLh Lhe LesLbed as you learn 8ox2u.
noLe: Lhe LesLbed ls wrlLLen uslng freegluL and CLul. 1he LesLbed ls noL parL of Lhe 8ox2u llbrary. 1he
8ox2u llbrary ls agnosLlc abouL renderlng. As shown by Lhe PelloWorld example, you don'L need a
renderer Lo use 8ox2u.
!"#$%&' 8 !,NN,+
81) 23,.%
1he Common module conLalns seLLlngs, memory managemenL, and vecLor maLh.
814 O&%%0+?7
1he header b2SeLLlngs.h conLalns:
1ypes such as lnL32 and floaL32
ConsLanLs
AllocaLlon wrappers
1he verslon number
RM$&7
8ox2u deflnes varlous Lypes such as floaL32, lnL8, eLc. Lo make lL easy Lo deLermlne Lhe slze of
sLrucLures.
!,+7%#+%7
8ox2u deflnes several consLanLs. 1hese are all documenLed ln b2SeLLlngs.h. normally you do noL need Lo
ad[usL Lhese consLanLs.
8ox2u uses floaLlng polnL maLh for colllslon and slmulaLlon. uue Lo round-off error some numerlcal
Lolerances are deflned. Some Lolerances are absoluLe and some are relaLlve. AbsoluLe Lolerances use
MkS unlLs.
2::,/#%0,+ S'#$$&'7
1he seLLlngs flle deflnes b2Alloc and b2lree for large allocaLlons. ?ou may forward Lhese calls Lo your
own memory managemenL sysLem.
T&'70,+
1he b2verslon sLrucLure holds Lhe currenL verslon so you can query Lhls aL run-Llme.
818 9&N,'M 9#+#?&N&+%
A large number of Lhe declslons abouL Lhe deslgn of 8ox2u were based on Lhe need for qulck and
efflclenL use of memory. ln Lhls secLlon l wlll dlscuss how and why 8ox2u allocaLes memory.
8ox2u Lends Lo allocaLe a large number of small ob[ecLs (around 30-300 byLes). uslng Lhe sysLem heap
Lhrough malloc or new for small ob[ecLs ls lnefflclenL and can cause fragmenLaLlon. Many of Lhese small
ob[ecLs may have a shorL llfe span, such as conLacLs, buL can perslsL for several Llme sLeps. So we need
an allocaLor LhaL can efflclenLly provlde heap memory for Lhese ob[ecLs.
8ox2u's soluLlon ls Lo use a small ob[ecL allocaLor (SCA) called b28lockAllocaLor. 1he SCA keeps a
number of growable pools of varylng slzes. When a requesL ls made for memory, Lhe SCA reLurns a block
of memory LhaL besL flLs Lhe requesLed slze. When a block ls freed, lL ls reLurned Lo Lhe pool. 8oLh of
Lhese operaLlons are fasL and cause llLLle heap Lrafflc.
Slnce 8ox2u uses a SCA, you should never new or malloc a body, flxLure, or [olnL. Powever, you do have
Lo allocaLe a b2World on your own. 1he b2World class provldes facLorles for you Lo creaLe bodles,
flxLures, and [olnLs. 1hls allows 8ox2u Lo use Lhe SCA and hlde Lhe gory deLalls from you. never, call
deleLe or free on a body, flxLure, or [olnL.
Whlle execuLlng a Llme sLep, 8ox2u needs some Lemporary workspace memory. lor Lhls, lL uses a sLack
allocaLor called b2SLackAllocaLor Lo avold per-sLep heap allocaLlons. ?ou don'L need Lo lnLeracL wlLh Lhe
sLack allocaLor, buL lL's good Lo know lL's Lhere.
81; 9#%"
8ox2u lncludes a slmple small vecLor and maLrlx module. 1hls has been deslgned Lo sulL Lhe lnLernal
needs of 8ox2u and Lhe Al. All Lhe members are exposed, so you may use Lhem freely ln your
appllcaLlon.
1he maLh llbrary ls kepL slmple Lo make 8ox2u easy Lo porL and malnLaln.

!"#$%&' ; !,::070,+ 9,-.:&
;1) 23,.%
1he Colllslon module conLalns shapes and funcLlons LhaL operaLe on Lhem. 1he module also conLalns a
dynamlc Lree and broad-phase Lo acceleraLlon colllslon processlng of large sysLems.
1he colllslon module ls deslgned Lo be usable ouLslde of Lhe dynamlc sysLem. lor example, you can use
Lhe dynamlc Lree for oLher aspecLs of your game besldes physlcs.
;14 O"#$&7
Shapes descrlbe colllslon geomeLry and may be used lndependenLly of physlcs slmulaLlon. ?ou may
perform several operaLlons wlLh shapes.
8ox2u shapes lmplemenL Lhe b2Shape base class. 1he base class deflnes funcLlons Lo:
1esL a polnL for overlap wlLh Lhe shape.
erform a ray casL agalnsL Lhe shape.
CompuLe Lhe shape's AA88.
CompuLe Lhe mass properLles of Lhe shape.
ln addlLlon, each shape has a Lype member and a radlus. 1he radlus even applles Lo polygons, as
dlscussed below.
;18 !0'/:& O"#$&7
Clrcle shapes have a poslLlon and radlus.
Clrcles are solld. ?ou cannoL make a hollow clrcle. Powever, you can creaLe chalns of llne segmenLs
uslng polygon shapes.
!"-9*2+.?@/A. 29*2+.H
29*2+.IETAI?.01"IP6B CIP67H
29*2+.IET*/%9>4 G PIS6H
;1; 5,:M?,+ O"#$&7
olygon shapes are solld convex polygons. A polygon ls convex when all llne segmenLs connecLlng Lwo
polnLs ln Lhe lnLerlor do noL cross any edge of Lhe polygon. olygons are solld and never hollow. A
polygon musL have 3 or more verLlces.

?ou musL creaLe polygons wlLh a counLer clockwlse wlndlng (CCW). We musL be careful because Lhe
noLlon of CCW ls wlLh respecL Lo a rlghL-handed coordlnaLe sysLem wlLh Lhe z-axls polnLlng ouL of Lhe
plane. 1hls mlghL Lurn ouL Lo be clockwlse on your screen, dependlng on your coordlnaLe sysLem
convenLlons.

1he polygon members are publlc, buL you should use lnlLlallzaLlon funcLlons Lo creaLe a polygon. 1he
lnlLlallzaLlon funcLlons creaLe normal vecLors and perform valldaLlon.
?ou can creaLe a polygon shape by passlng ln a verLex array. 1he maxlmal slze of Lhe array ls conLrolled
by b2_maxolygonverLlces whlch has a defaulL value of 8. 1hls ls sufflclenL Lo descrlbe mosL convex
polygons.
VV b@94 %.693.4 / 0*9/3O+. 93 --) $*%.*I
!"N.2" :.*092.4cCdH
:.*092.4cPdI?.01PIP6B PIP67H
:.*092.4cQdI?.01QIP6B PIP67H
:.*092.4c"dI?.01PIP6B QIP67H
930C" 2$>30 G CH

!"R$+&O$3?@/A. A$+&O$3H
A$+&O$3I?.01:.*092.4B 2$>307H
1he polygon shape has some cusLom lnlLlallzaLlon funcLlons Lo creaLe boxes.
:$9% ?.0F4#$=16+$/0C" @=B 6+$/0C" @&7H
:$9% ?.0F4#$=16+$/0C" @=B 6+$/0C" @&B 2$340 !"N.2"M 2.30.*B 6+$/0C" /3O+.7H
olygons lnherlL a radlus from b2Shape. 1he radlus creaLes a skln around Lhe polygon. 1he skln ls used ln
sLacklng scenarlos Lo keep polygons sllghLly separaLed. 1hls allows conLlnuous colllslon Lo work agalnsL
Lhe core polygon.


1he polygon skln helps prevenL Lunnellng by keeplng Lhe polygons separaLed. 1hls resulLs ln small gaps
beLween Lhe shapes. ?our vlsual represenLaLlon can be larger Lhan Lhe polygon Lo hlde any gaps.



;1A U-?& O"#$&7
Ldge shapes are llne segmenLs. 1hese are provlded Lo asslsL ln maklng a free-form sLaLlc envlronmenL
for your game. A ma[or llmlLaLlon of edge shapes ls LhaL Lhey can colllde wlLh clrcles and polygons buL
noL wlLh Lhemselves. 1he colllslon algorlLhms used by 8ox2u requlre LhaL aL leasL one of Lwo collldlng
shapes have volume. Ldge shapes have no volume, so edge-edge colllslon ls noL posslble.
VV b@94 /3 .%O. 4@/A.I
!"N.2" :Q1PIP6B PIP67H
!"N.2" :"1QIP6B PIP67H

!"e%O.?@/A. .%O.H
.%O.I?.01:QB :"7H
ln many cases a game envlronmenL ls consLrucLed by connecL several edge shapes end-Lo-end. 1hls can
glve rlse Lo an unexpecLed arLlfacL when a polygon slldes along Lhe chaln of edges. ln Lhe flgure below
we see a box collldlng wlLh an lnLernal verLex. 1hese !"#$% colllslons are caused when Lhe polygon
collldes wlLh an lnLernal verLex generaLlng an lnLernal colllslon normal.

lf edge1 dld noL exlsL Lhls colllslon would seem flne. WlLh edge1 presenL, Lhe lnLernal colllslon seems llke
a bug. 8uL normally when 8ox2u collldes Lwo shapes, lL vlews Lhem ln lsolaLlon.
lorLunaLely, Lhe edge shape provldes a mechanlsm for ellmlnaLlng ghosL colllslons by sLorlng Lhe
ad[acenL !"#$% verLlces. 8ox2u uses Lhese ghosL verLlces Lo prevenL lnLernal colllslons.

VV b@94 94 /3 .%O. 4@/A. L90@ O@$40 :.*092.4I
!"N.2" :P1QIf6B PIP67H
!"N.2" :Q1QIP6B PI"S67H
!"N.2" :"1PIP6B PIP67H
!"N.2" :C1JQIf6B PIU67H

!"e%O.?@/A. .%O.H
.%O.I?.01:QB :"7H
.%O.IET@/4N.*0.=P G 0*>.H
.%O.IET@/4N.*0.=C G 0*>.H
.%O.IET:.*0.=P G :PH
.%O.IET:.*0.=C G :CH
ln general sLlLchlng edges LogeLher Lhls way ls a blL wasLeful and Ledlous. 1hls brlngs us Lo Lhe nexL
shape Lype.
;1B !"#0+ O"#$&7
1he chaln shape provldes an efflclenL way Lo connecL many edges LogeLher Lo consLrucL your sLaLlc game
worlds. Chaln shapes auLomaLlcally ellmlnaLe ghosL colllslons and provlde Lwo slded colllslon.

VV b@94 / 2@/93 4@/A. L90@ 94$+/0.% :.*092.4
!"N.2" :4cUdH
:4cPdI?.01QIf6B PIP67H
:4cQdI?.01QIP6B PI"S67H
:4c"dI?.01PIP6B PIP67H
:4cCdI?.01JQIf6B PIU67H

!"-@/93?@/A. 2@/93H
2@/93I-*./0.-@/931:4B U7H
?ou may have a scrolllng game world and would llke Lo connecL several chalns LogeLher. ?ou can
connecL chalns LogeLher uslng ghosL verLlces, llke we dld wlLh b2LdgeShape.
VV X340/++ O@$40 :.*092.4
2@/93I?.0R*.:N.*0.=1!"N.2"1CIP6B QIP677H
2@/93I?.0g.=0N.*0.=1!"N.2"1J"IP6B PIP677H
?ou may also creaLe loops auLomaLlcally.
VV -*./0. / +$$AI b@. 69*40 /3% +/40 :.*092.4 /*. 2$33.20.%I
!"-@/93?@/A. 2@/93H
2@/93I-*./0.h$$A1:4B U7H
Self-lnLersecLlon of chaln shapes ls noL supporLed. lL mlghL work, lL mlghL noL. 1he code LhaL prevenLs
ghosL colllslons assumes Lhere are no self-lnLersecLlons of Lhe chaln.


Lach edge ln Lhe chaln ls LreaLed as a chlld shape and can be accessed by lndex.
VV N9490 ./2@ 2@9+% .%O.I
6$* 1930C" 9 G PH 9 Y 2@/93ID.0-@9+%-$>3017H ZZ97
[
!"e%O.?@/A. .%O.H
2@/93ID.0-@9+%e%O.1M.%O.B 97H

_
;1C *+ O"#$& 5,0+% R&7%
?ou can LesL a polnL for overlap wlLh a shape. ?ou provlde a Lransform for Lhe shape and a world polnL.
!"b*/346*$E 0*/346$*EH
0*/346$*EI?.0X%.3090&17H
!"N.2" A$9301SIP6B "IP67H
!$$+ @90 G 4@/A.JKb.40R$93010*/346$*EB A$9307H
Ldge and chaln shapes always reLurn false, even lf Lhe chaln ls a loop.

;1E O"#$& >#M !#7%
?ou can casL a ray aL a shape Lo geL Lhe polnL of flrsL lnLersecLlon and normal vecLor. no hlL wlll reglsLer
lf Lhe ray sLarLs lnslde Lhe shape. A chlld lndex ls lncluded for chaln shapes because Lhe ray casL wlll only
check a slngle edge aL a Llme.
!"b*/346*$E 0*/346$*EH
0*/346$*EI?.0X%.3090&17H
!"i/&-/40X3A>0 93A>0H
93A>0IAQI?.01PIP6B PIP6B PIP67H
93A>0IA"I?.01QIP6B PIP6B PIP67H
93A>0IE/=<*/209$3 G QIP6H
930C" 2@9+%X3%.= G PH
!"i/&-/40j>0A>0 $>0A>0H
!$$+ @90 G 4@/A.JKi/&-/401M$>0A>0B 93A>0B 0*/346$*EB 2@9+%X3%.=7H
96 1@907
[
!"N.2" @90R$930 G 93A>0IAQ Z $>0A>0I6*/209$3 ' 193A>0IA" 93A>0IAQ7H

_
;1H @0:#%&'#: <.+/%0,+7
1he Colllslon module conLalns bllaLeral funcLlons LhaL Lake a palr of shapes and compuLe some resulLs.
1hese lnclude:
Cverlap
ConLacL manlfolds
ulsLance
1lme of lmpacL
;1)V WX&':#$
?ou can LesL Lwo shapes for overlap uslng Lhls funcLlon:
!"b*/346$*E =6F G , xfB = ;
!$$+ $:.*+/A G !"b.40j:.*+/A14@/A.FB 93%.=FB 4@/A.#B 93%.=#B =6FB =6#7H
Agaln you musL provlde chlld lndlces Lo for Lhe case of chaln shapes.
;1)) !,+%#/% 9#+0G,:-7
8ox2u has funcLlons Lo compuLe conLacL polnLs for overlapplng shapes. lf we conslder clrcle-clrcle or
clrcle-polygon, we can only geL one conLacL polnL and normal. ln Lhe case of polygon-polygon we can geL
Lwo polnLs. 1hese polnLs share Lhe same normal vecLor so 8ox2u groups Lhem lnLo a manlfold sLrucLure.
1he conLacL solver Lakes advanLage of Lhls Lo lmprove sLacklng sLablllLy.

Normally you dont need to compute contact manifolds directly, however you will likely use the results
produced ln Lhe slmulaLlon.
1he b2Manlfold sLrucLure holds a normal vecLor and up Lo Lwo conLacL polnLs. 1he normal and polnLs
are held ln local coordlnaLes. As a convenlence for Lhe conLacL solver, each polnL sLores Lhe normal and
LangenLlal (frlcLlon) lmpulses.
1he daLa sLored ln b2Manlfold ls opLlmlzed for lnLernal use. lf you need Lhls daLa, lL ls usually besL Lo use
Lhe b2WorldManlfold sLrucLure Lo generaLe Lhe world coordlnaLes of Lhe conLacL normal and polnLs. ?ou
need Lo provlde a b2Manlfold and Lhe shape Lransforms and radll.
!")$*+%k/396$+% L$*+%k/396$+%H
L$*+%k/396$+%IX3909/+9l.1ME/396$+%B 0*/346$*EFB 4@/A.FIET*/%9>4B
0*/346$*E#B 4@/A.#IET*/%9>47H
6$* 1930C" 9 G PH 9 Y E/396$+%IA$930-$>30H ZZ97
[
!"N.2" A$930 G L$*+%k/396$+%IA$9304c9dH

_
uurlng slmulaLlon shapes may move and Lhe manlfolds may change. olnLs may be added or removed.
?ou can deLecL Lhls uslng b2CeLolnLSLaLes.
!"R$930?0/0. 40/0.Qc"dB 40/0."c"dH
!"D.0R$930?0/0.4140/0.QB 40/0."B ME/396$+%QB ME/396$+%"7H
96 140/0.QcPd GG !"T*.E$:.?0/0.7
[
VV A*$2.44 .:.30
_
;1)4 F07%#+/&
1he b2ulsLance funcLlon can be used Lo compuLe Lhe dlsLance beLween Lwo shapes. 1he dlsLance
funcLlon needs boLh shapes Lo be converLed lnLo a b2ulsLanceroxy. 1here ls also some cachlng used Lo
warm sLarL Lhe dlsLance funcLlon for repeaLed calls. ?ou can see Lhe deLalls ln b2ulsLance.h.

;1)8 R0N& ,G *N$#/%
lf Lwo shapes are movlng fasL, Lhey may %'(()* Lhrough each oLher ln a slngle Llme sLep.

1he b21lmeCflmpacL ls used Lo deLermlne Lhe Llme when Lwo movlng shapes colllde. 1hls ls called Lhe
%+,) #- +,./0% (1Cl). 1he maln purpose of b21lmeCflmpacL ls for Lunnel prevenLlon. ln parLlcular, lL ls
deslgned Lo prevenL movlng ob[ecLs from Lunnellng ouLslde of sLaLlc level geomeLry.
1hls funcLlon accounLs for roLaLlon and LranslaLlon of boLh shapes, however lf Lhe roLaLlons are large
enough, Lhen Lhe funcLlon may mlss a colllslon. Powever Lhe funcLlon wlll sLlll reporL a non-overlapped
Llme and wlll capLure all LranslaLlonal colllslons.
1he Llme of lmpacL funcLlon ldenLlLles an lnlLlal separaLlng axls and ensures Lhe shapes do noL cross on
LhaL axls. 1hls wlll mlss colllslons LhaL are clear aL Lhe flnal poslLlons. Whlle Lhls approach may mlss some
colllslons, lL ls very fasL and adequaLe for Lunnel prevenLlon.


lL ls dlfflculL Lo puL a resLrlcLlon on Lhe roLaLlon magnlLude. 1here may be cases where colllslons are
mlssed for small roLaLlons. normally, Lhese mlssed roLaLlonal colllslons should noL harm game play.
1he funcLlon requlres Lwo shapes (converLed Lo b2ulsLanceroxy) and Lwo b2Sweep sLrucLures. 1he
sweep sLrucLure deflnes Lhe lnlLlal and flnal Lransforms of Lhe shapes.
?ou can use flxed roLaLlons Lo perform a $"/.) 0/$%. ln Lhls case, Lhe Llme of lmpacL funcLlon wlll noL
mlss any colllslons.
;1); FM+#N0/ R'&&
1he b2uynamlc1ree class ls used by 8ox2u Lo organlze large numbers of shapes efflclenLly. 1he class
does noL know abouL shapes. lnsLead lL operaLes on axls-allgned boundlng boxes (AA88s) wlLh user daLa
polnLers.
1he dynamlc Lree ls a hlerarchlcal AA88 Lree. Lach lnLernal node ln Lhe Lree can has Lwo chlldren. A leaf
node ls a slngle user AA88. 1he Lree uses roLaLlons Lo keep Lhe Lree balance, even ln Lhe case of
degeneraLe lnpuL.
1he Lree sLrucLure allows for efflclenL ray casLs and reglon querles. lor example, you may have hundreds
of shapes ln your scene. ?ou could perform a ray casL agalnsL Lhe scene ln a bruLe force manner by ray
casLlng each shape. 1hls would be lnefflclenL because lL does noL Lake advanLage of shapes belng spread
ouL. lnsLead, you can malnLaln a dynamlc Lree and perform ray casLs agalnsL Lhe Lree. 1hls Lraverses Lhe
ray Lhrough Lhe Lree sklpplng large numbers of shapes.
A reglon query uses Lhe Lree Lo flnd all leaf AA88s LhaL overlap a query AA88. 1hls ls fasLer Lhan a bruLe
force approach because many shapes can be sklpped.


normally you wlll noL use Lhe dynamlc Lree dlrecLly. 8aLher you wlll go Lhrough Lhe b2World class for ray
casLs and reglon querles. lf you do plan Lo creaLe your own dynamlc Lree, you can learn how Lo use lL by
looklng aL how 8ox2u uses lL.
;1)A @',#-Y$"#7&
Colllslon processlng ln a physlcs sLep can be dlvlded lnLo narrow-phase and broad-phase. ln Lhe narrow-
phase we compuLe conLacL polnLs beLween palrs of shapes. lmaglne we have n shapes. uslng bruLe
force, we would need Lo perform Lhe narrow-phase for n*n/2 palrs.
1he b28roadhase class reduces Lhls load by uslng a dynamlc Lree for palr managemenL. 1hls greaLly
reduces Lhe number of narrow-phase calls.
normally you do noL lnLeracL wlLh Lhe broad-phase dlrecLly. lnsLead, 8ox2u creaLes and manages a
broad-phase lnLernally. Also, b2BroadPhase is designed with Box2Ds simulation loop in mind, so it is
llkely noL sulLed for oLher use cases.
!"#$%&' A FM+#N0/7 9,-.:&
A1) WX&'X0&S
1he uynamlcs module ls Lhe mosL complex parL of 8ox2u and ls Lhe parL you llkely lnLeracL wlLh Lhe
mosL. 1he uynamlcs module slLs on Lop of Lhe Common and Colllslon modules, so you should be famlllar
wlLh Lhose by now.
1he uynamlcs module conLalns:
shape flxLure class
rlgld body class
conLacL class
[olnL classes
world class
llsLener classes
1here are many dependencles beLween Lhese classes so lL ls dlfflculL Lo descrlbe one class wlLhouL
referrlng Lo anoLher. ln Lhe followlng, you may see some references Lo classes LhaL have noL been
descrlbed yeL. 1herefore, you may wanL Lo qulckly sklm Lhls chapLer before readlng lL closely.
1he dynamlcs module ls covered ln Lhe followlng chapLers.
!"#$%&' B <0J%.'&7
B1) 23,.%
Recall that shapes dont know about bodies and may be used independently of Lhe physlcs slmulaLlon.
1herefore 8ox2u provldes Lhe b2llxLure class Lo aLLach shapes Lo bodles. llxLures hold Lhe followlng:
a slngle shape
broad-phase proxles
denslLy, frlcLlon, and resLlLuLlon
colllslon fllLerlng flags
back polnLer Lo Lhe parenL body
user daLa
sensor flag
1hese are descrlbed ln Lhe followlng secLlons.
B14 <0J%.'& !'&#%0,+
llxLures are creaLed by lnlLlallzlng a flxLure deflnlLlon and Lhen passlng Lhe deflnlLlon Lo Lhe parenL body.
!"<9=0>*.5.6 69=0>*.5.6H
69=0>*.5.6I4@/A. G ME&?@/A.H
69=0>*.5.6I%.3490& G QIP6H
!"<9=0>*.' E&<9=0>*. G E&#$%&JK-*./0.<9=0>*.1M69=0>*.5.67H
1hls creaLes Lhe flxLure and aLLaches lL Lo Lhe body. ?ou do noL need Lo sLore Lhe flxLure polnLer slnce
Lhe flxLure wlll auLomaLlcally be desLroyed when Lhe parenL body ls desLroyed. ?ou can creaLe mulLlple
flxLures on a slngle body.
?ou can desLroy a flxLure on Lhe parenL body. ?ou may do Lhls Lo model a breakable ob[ecL. CLherwlse
you can [usL leave Lhe flxLure alone and leL Lhe body desLrucLlon Lake care of desLroylng Lhe aLLached
flxLures.
E&#$%&JK5.40*$&<9=0>*.1E&<9=0>*.7H
F&+70%M
1he flxLure denslLy ls used Lo compuLe Lhe mass properLles of Lhe parenL body. 1he denslLy can be zero
or poslLlve. ?ou should generally use slmllar denslLles for all your flxLures. 1hls wlll lmprove sLacklng
sLablllLy.
1he mass of a body ls noL ad[usLed when you seL Lhe denslLy. ?ou musL call 8eseLMassuaLa for Lhls Lo
occur.
69=0>*.JK?.05.3490&1SIP67H
!$%&JKi.4.0k/445/0/17H
<'0/%0,+
lrlcLlon ls used Lo make ob[ecLs sllde along each oLher reallsLlcally. 8ox2u supporLs sLaLlc and dynamlc
frlcLlon, buL uses Lhe same parameLer for boLh. lrlcLlon ls slmulaLed accuraLely ln 8ox2u and Lhe frlcLlon
sLrengLh ls proporLlonal Lo Lhe normal force (Lhls ls called Coulomb frlcLlon). 1he frlcLlon parameLer ls
usually seL beLween 0 and 1, buL can be any non-negaLlve value. A frlcLlon value of 0 Lurns off frlcLlon
and a value of 1 makes Lhe frlcLlon sLrong. When Lhe frlcLlon force ls compuLed beLween Lwo shapes,
8ox2u musL comblne Lhe frlcLlon parameLers of Lhe Lwo parenL flxLures. 1hls ls done wlLh Lhe geomeLrlc
mean:
6+$/0C" 6*9209$3H
6*9209$3 G 4m*0614@/A.QJK6*9209$3 ' 4@/A."JK6*9209$37H
So lf one flxLure has zero frlcLlon Lhen Lhe conLacL wlll have zero frlcLlon.
>&7%0%.%0,+
8esLlLuLlon ls used Lo make ob[ecLs bounce. 1he resLlLuLlon value ls usually seL Lo be beLween 0 and 1.
Conslder dropplng a ball on a Lable. A value of zero means Lhe ball won'L bounce. 1hls ls called an
lnelasLlc colllslon. A value of one means Lhe ball's veloclLy wlll be exacLly reflecLed. 1hls ls called a
perfecLly elasLlc colllslon. 8esLlLuLlon ls comblned uslng Lhe followlng formula.
6+$/0C" *.4090>09$3H
*.4090>09$3 G !"k/=14@/A.QJK*.4090>09$3B 4@/A."JK*.4090>09$37H
llxLures carry colllslon fllLerlng lnformaLlon Lo leL you prevenL colllslons beLween cerLaln game ob[ecLs.
When a shape develops mulLlple conLacLs, resLlLuLlon ls slmulaLed approxlmaLely. 1hls ls because 8ox2u
uses an lLeraLlve solver. 8ox2u also uses lnelasLlc colllslons when Lhe colllslon veloclLy ls small. 1hls ls
done Lo prevenL [lLLer.
<0:%&'0+?
Colllslon fllLerlng allows you Lo prevenL colllslon beLween flxLures. lor example, say you make a
characLer LhaL rldes a blcycle. ?ou wanL Lhe blcycle Lo colllde wlLh Lhe Lerraln and Lhe characLer Lo
colllde wlLh Lhe Lerraln, buL you don'L wanL Lhe characLer Lo colllde wlLh Lhe blcycle (because Lhey musL
overlap). 8ox2u supporLs such colllslon fllLerlng uslng caLegorles and groups.
8ox2u supporLs 16 colllslon caLegorles. lor each flxLure you can speclfy whlch caLegory lL belongs Lo.
?ou also speclfy whaL oLher caLegorles Lhls flxLure can colllde wlLh. lor example, you could speclfy ln a
mulLlplayer game LhaL all players don'L colllde wlLh each oLher and monsLers don'L colllde wlLh each
oLher, buL players and monsLers should colllde. 1hls ls done wlLh masklng blLs. lor example:
A+/&.*<9=0>*.5.6I69+0.*I2/0.O$*&#904 G P=PPP"H
E$340.*<9=0>*.5.6I69+0.*I2/0.O$*&#904 G P=PPPUH
A+/&.*<9=0>*.5.6I69+0.*IE/4n#904 G P=PPPUH
E$340.*<9=0>*.5.6I69+0.*IE/4n#904 G P=PPP"H
Pere ls Lhe rule for a colllslon Lo occur:
>930QW 2/0F G 69=0>*.FI69+0.*I2/0.O$*&#904H
>930QW E/4nF G 69=0>*.FI69+0.*IE/4n#904H
>930QW 2/0# G 69=0>*.#I69+0.*I2/0.O$*&#904H
>930QW E/4n# G 69=0>*.#I69+0.*IE/4n#904H

96 112/0F M E/4n#7 oG P MM 12/0# M E/4nF7 oG P7
[
VV 69=0>*.4 2/3 2$++9%.
_
Colllslon groups leL you speclfy an lnLegral group lndex. ?ou can have all flxLures wlLh Lhe same group
lndex always colllde (poslLlve lndex) or never colllde (negaLlve lndex). Croup lndlces are usually used for
Lhlngs LhaL are somehow relaLed, llke Lhe parLs of a blcycle. ln Lhe followlng example, flxLure1 and
flxLure2 always colllde, buL flxLure3 and flxLure4 never colllde.
69=0>*.Q5.6I69+0.*IO*$>AX3%.= G "H
69=0>*."5.6I69+0.*IO*$>AX3%.= G "H
69=0>*.C5.6I69+0.*IO*$>AX3%.= G JaH
69=0>*.U5.6I69+0.*IO*$>AX3%.= G JaH
Colllslons beLween flxLures of dlfferenL group lndlces are fllLered accordlng Lhe caLegory and mask blLs.
ln oLher words, group fllLerlng has hlgher precedence Lhan caLegory fllLerlng.
noLe LhaL addlLlonal colllslon fllLerlng occurs ln 8ox2u. Pere ls a llsL:
A flxLure on a sLaLlc body can only colllde wlLh a dynamlc body.
A flxLure on a klnemaLlc body can only colllde wlLh a dynamlc body.
llxLures on Lhe same body never colllde wlLh each oLher.
?ou can opLlonally enable/dlsable colllslon beLween flxLures on bodles connecLed by a [olnL.
SomeLlmes you mlghL need Lo change colllslon fllLerlng afLer a flxLure has already been creaLed. ?ou can
geL and seL Lhe b2lllLer sLrucLure on an exlsLlng flxLure uslng b2llxLure::CeLlllLeruaLa and
b2llxLure::SeLlllLeruaLa. noLe LhaL changlng Lhe fllLer daLa wlll noL add or remove conLacLs unLll Lhe nexL
Llme sLep (see Lhe World class).
B18 O&+7,'7
SomeLlmes game loglc needs Lo know when Lwo flxLures overlap yeL Lhere should be no colllslon
response. 1hls ls done by uslng sensors. A sensor ls a flxLure LhaL deLecLs colllslon buL does noL produce
a response.
?ou can flag any flxLure as belng a sensor. Sensors may be sLaLlc or dynamlc. 8emember LhaL you may
have mulLlple flxLures per body and you can have any mlx of sensors and solld flxLures.
Sensors do noL generaLe conLacL polnLs. 1here are Lwo ways Lo geL Lhe sLaLe of a sensor:
1. b2ConLacL::ls1ouchlng
2. b2ConLacLLlsLener::8eglnConLacL and LndConLacL

!"#$%&' C @,-0&7
C1) 23,.%
8odles have poslLlon and veloclLy. ?ou can apply forces, Lorques, and lmpulses Lo bodles. 8odles can be
sLaLlc, klnemaLlc, or dynamlc. Pere are Lhe body Lype deflnlLlons:
+9:!0#0(2;,*-
A sLaLlc body does noL move under slmulaLlon and behaves as lf lL has lnflnlLe mass. lnLernally, 8ox2u
sLores zero for Lhe mass and Lhe lnverse mass. SLaLlc bodles can be moved manually by Lhe user. A sLaLlc
body has zero veloclLy. SLaLlc bodles do noL colllde wlLh oLher sLaLlc or klnemaLlc bodles.
+9:<(3%6#0(2;,*-
A klnemaLlc body moves under slmulaLlon accordlng Lo lLs veloclLy. klnemaLlc bodles do noL respond Lo
forces. 1hey can be moved manually by Lhe user, buL normally a klnemaLlc body ls moved by seLLlng lLs
veloclLy. A klnemaLlc body behaves as lf lL has lnflnlLe mass, however, 8ox2u sLores zero for Lhe mass
and Lhe lnverse mass. klnemaLlc bodles do noL colllde wlLh oLher sLaLlc or klnemaLlc bodles.
+9:*-3#6(2;,*-
A dynamlc body ls fully slmulaLed. 1hey can be moved manually by Lhe user, buL normally Lhey move
accordlng Lo forces. A dynamlc body can colllde wlLh all body Lypes. A dynamlc body always has flnlLe,
non-zero mass. lf you Lry Lo seL Lhe mass of a dynamlc body Lo zero, lL wlll auLomaLlcally acqulre a mass
of one kllogram.
8odles are Lhe backbone for flxLures. 8odles carry flxLures and move Lhem around ln Lhe world. 8odles
are always rlgld bodles ln 8ox2u. 1haL means LhaL Lwo flxLures aLLached Lo Lhe same rlgld body never
move relaLlve Lo each oLher.
llxLures have colllslon geomeLry and denslLy. normally, bodles acqulre Lhelr mass properLles from Lhe
flxLures. Powever, you can overrlde Lhe mass properLles afLer a body ls consLrucLed. 1hls ls dlscussed
below.
?ou usually keep polnLers Lo all Lhe bodles you creaLe. 1hls way you can query Lhe body poslLlons Lo
updaLe Lhe poslLlons of your graphlcal enLlLles. ?ou should also keep body polnLers so you can desLroy
Lhem when you are done wlLh Lhem.
C14 @,-M F&G0+0%0,+
8efore a body ls creaLed you musL creaLe a body deflnlLlon (b28odyuef). 1he body deflnlLlon holds Lhe
daLa needed Lo creaLe and lnlLlallze a body.
8ox2u coples Lhe daLa ouL of Lhe body deflnlLlon, lL does noL keep a polnLer Lo Lhe body deflnlLlon. 1hls
means you can recycle a body deflnlLlon Lo creaLe mulLlple bodles.
Lets go over some of the key members of the body definition.
@,-M RM$&
As dlscussed aL Lhe beglnnlng of Lhls chapLer, Lhere are Lhree dlfferenL body Lypes: sLaLlc, klnemaLlc, and
dynamlc. ?ou should esLabllsh Lhe body Lype aL creaLlon because changlng Lhe body Lype laLer ls
expenslve.
!$%&5.6I0&A. G !"T%&3/E92#$%&H
SeLLlng Lhe body Lype ls mandaLory.
5,70%0,+ #+- 2+?:&
1he body deflnlLlon glves you Lhe chance Lo lnlLlallze Lhe poslLlon of Lhe body on creaLlon. 1hls has far
beLLer performance Lhan creaLlng Lhe body aL Lhe world orlgln and Lhen movlng Lhe body.
!"#$%&'
uo noL creaLe a body aL Lhe orlgln and Lhen move lL. lf you creaLe several bodles aL
Lhe orlgln, Lhen performance wlll suffer.
A body has Lwo maln polnLs of lnLeresL. 1he flrsL polnL ls Lhe body's orlgln. llxLures and [olnLs are
aLLached relaLlve Lo Lhe body's orlgln. 1he second polnL of lnLeresL ls Lhe cenLer of mass. 1he cenLer of
mass ls deLermlned from mass dlsLrlbuLlon of Lhe aLLached shapes or ls expllclLly seL wlLh b2MassuaLa.
Much of 8ox2u's lnLernal compuLaLlons use Lhe cenLer of mass poslLlon. lor example b28ody sLores Lhe
llnear veloclLy for Lhe cenLer of mass.
When you are bulldlng Lhe body deflnlLlon, you may noL know where Lhe cenLer of mass ls locaLed.
1herefore you speclfy Lhe poslLlon of Lhe body's orlgln. ?ou may also speclfy Lhe body's angle ln radlans,
whlch ls noL affecLed by Lhe poslLlon of Lhe cenLer of mass. lf you laLer change Lhe mass properLles of
Lhe body, Lhen Lhe cenLer of mass may move on Lhe body, buL Lhe orlgln poslLlon does noL change and
Lhe aLLached shapes and [olnLs do noL move.
!$%&5.6IA$4909$3I?.01PIP6B "IP67H VV 0@. !$%&p4 $*9O93 A$4909$3I
!$%&5.6I/3O+. G PI"S6 ' !"TA9H VV 0@. !$%&p4 /3O+. 93 */%9/34I
F#N$0+?
uamplng ls used Lo reduce Lhe world veloclLy of bodles. uamplng ls dlfferenL Lhan frlcLlon because
frlcLlon only occurs wlLh conLacL. uamplng ls noL a replacemenL for frlcLlon and Lhe Lwo effecLs should
be used LogeLher.
uamplng parameLers should be beLween 0 and lnflnlLy, wlLh 0 meanlng no damplng, and lnflnlLy
meanlng full damplng. normally you wlll use a damplng value beLween 0 and 0.1. l generally do noL use
llnear damplng because lL makes bodles look floaLy.
!$%&5.6I+93./*5/EA93O G PIP6H
!$%&5.6I/3O>+/*5/EA93O G PIPQ6H
uamplng ls approxlmaLed for sLablllLy and performance. AL small damplng values Lhe damplng effecL ls
mosLly lndependenL of Lhe Llme sLep. AL larger damplng values, Lhe damplng effecL wlll vary wlLh Lhe
Llme sLep. 1hls ls noL an lssue lf you use a flxed Llme sLep (recommended).
L'#X0%M O/#:&
?ou can use Lhe gravlLy scale Lo ad[usL Lhe gravlLy on a slngle body. 8e careful Lhough, lncreased gravlLy
can decrease sLablllLy.
VV ?.0 0@. O*/:90& 42/+. 0$ l.*$ 4$ 0@94 !$%& L9++ 6+$/0
!$%&5.6IO*/:90&?2/+. G PIP6H
O:&&$ 5#'#N&%&'7
WhaL does sleep mean? Well lL ls expenslve Lo slmulaLe bodles, so Lhe less we have Lo slmulaLe Lhe
beLLer. When a body comes Lo resL we would llke Lo sLop slmulaLlng lL.
When 8ox2u deLermlnes LhaL a body (or group of bodles) has come Lo resL, Lhe body enLers a sleep
sLaLe whlch has very llLLle Cu overhead. lf a body ls awake and collldes wlLh a sleeplng body, Lhen Lhe
sleeplng body wakes up. 8odles wlll also wake up lf a [olnL or conLacL aLLached Lo Lhem ls desLroyed. ?ou
can also wake a body manually.
1he body deflnlLlon leLs you speclfy wheLher a body can sleep and wheLher a body ls creaLed sleeplng.
!$%&5.6I/++$L?+..A G 0*>.H
!$%&5.6I/L/n. G 0*>.H
<0J&- >,%#%0,+
?ou may wanL a rlgld body, such as a characLer, Lo have a flxed roLaLlon. Such a body should noL roLaLe,
even under load. ?ou can use Lhe flxed roLaLlon seLLlng Lo achleve Lhls:
!$%&5.6I69=.%i$0/09$3 G 0*>.H
1he flxed roLaLlon flag causes Lhe roLaLlonal lnerLla and lLs lnverse Lo be seL Lo zero.
@.::&%7
Came slmulaLlon usually generaLes a sequence of lmages LhaL are played aL some frame raLe. 1hls ls
called dlscreLe slmulaLlon. ln dlscreLe slmulaLlon, rlgld bodles can move by a large amounL ln one Llme
sLep. lf a physlcs englne doesn'L accounL for Lhe large moLlon, you may see some ob[ecLs lncorrecLly pass
Lhrough each oLher. 1hls effecL ls called Lunnellng.
8y defaulL, 8ox2u uses conLlnuous colllslon deLecLlon (CCu) Lo prevenL dynamlc bodles from Lunnellng
Lhrough sLaLlc bodles. 1hls ls done by sweeplng shapes from Lhelr old poslLlon Lo Lhelr new poslLlons.
1he englne looks for new colllslons durlng Lhe sweep and compuLes Lhe Llme of lmpacL (1Cl) for Lhese
colllslons. 8odles are moved Lo Lhelr flrsL 1Cl and Lhen halLed for Lhe remalnder of Lhe Llme sLep.
normally CCu ls noL used beLween dynamlc bodles. 1hls ls done Lo keep performance reasonable. ln
some game scenarlos you need dynamlc bodles Lo use CCu. lor example, you may wanL Lo shooL a hlgh
speed bulleL aL a sLack of dynamlc brlcks. WlLhouL CCu, Lhe bulleL mlghL Lunnel Lhrough Lhe brlcks.
lasL movlng ob[ecLs ln 8ox2u can be labeled as bulleLs. 8ulleLs wlll perform CCu wlLh boLh sLaLlc and
dynamlc bodles. ?ou should declde whaL bodles should be bulleLs based on your game deslgn. lf you
declde a body should be LreaLed as a bulleL, use Lhe followlng seLLlng.
!$%&5.6I!>++.0 G 0*>.H
1he bulleL flag only affecLs dynamlc bodles.
8ox2u performs conLlnuous colllslon sequenLlally, so bulleLs may mlss fasL movlng bodles.
2/%0X#%0,+
?ou may wlsh a body Lo be creaLed buL noL parLlclpaLe ln colllslon or dynamlcs. 1hls sLaLe ls slmllar Lo
sleeplng excepL Lhe body wlll noL be woken by oLher bodles and Lhe body's flxLures wlll noL be placed ln
Lhe broad-phase. 1hls means Lhe body wlll noL parLlclpaLe ln colllslons, ray casLs, eLc.
?ou can creaLe a body ln an lnacLlve sLaLe and laLer re-acLlvaLe lL.
!$%&5.6I/209:. G 0*>.H
!olnLs may be connecLed Lo lnacLlve bodles. 1hese [olnLs wlll noL be slmulaLed. ?ou should be careful
when you acLlvaLe a body LhaL lLs [olnLs are noL dlsLorLed.
D7&' F#%#
user daLa ls a vold polnLer. 1hls glves you a hook Lo llnk your appllcaLlon ob[ecLs Lo bodles. ?ou should
be conslsLenL Lo use Lhe same ob[ecL Lype for all body user daLa.
!"#$%&5.6 !$%&5.6H
!$%&5.6I>4.*5/0/ G ME&F20$*H
C18 @,-M <#/%,'M
8odles are creaLed and desLroyed uslng a body facLory provlded by Lhe world class. 1hls leLs Lhe world
creaLe Lhe body wlLh an efflclenL allocaLor and add Lhe body Lo Lhe world daLa sLrucLure.
8odles can be dynamlc or sLaLlc dependlng on Lhe mass properLles. 8oLh body Lypes use Lhe same
creaLlon and desLrucLlon meLhods.
!"#$%&' %&3/E92#$%& G E&)$*+%JK-*./0.#$%&1M!$%&5.67H
III %$ 40>66 III
E&)$*+%JK5.40*$&#$%&1%&3/E92#$%&7H
%&3/E92#$%& G gqhhH
!"#$%&'
?ou should never use new or malloc Lo creaLe a body. 1he world won'L know abouL
Lhe body and Lhe body won'L be properly lnlLlallzed.
SLaLlc bodles do noL move under Lhe lnfluence of oLher bodles. ?ou may manually move sLaLlc bodles,
buL you should be careful so LhaL you don'L squash dynamlc bodles beLween Lwo or more sLaLlc bodles.
lrlcLlon wlll noL work correcLly lf you move a sLaLlc body. SLaLlc bodles never colllde wlLh sLaLlc or
klnemaLlc bodles. lL ls fasLer Lo aLLach several shapes Lo a sLaLlc body Lhan Lo creaLe several sLaLlc bodles
wlLh a slngle shape on each one. lnLernally, 8ox2u seLs Lhe mass and lnverse mass of sLaLlc bodles Lo
zero. 1hls makes Lhe maLh work ouL so LhaL mosL algorlLhms don'L need Lo LreaL sLaLlc bodles as a speclal
case.
8ox2u does noL keep a reference Lo Lhe body deflnlLlon or any of Lhe daLa lL holds (excepL user daLa
polnLers). So you can creaLe Lemporary body deflnlLlons and reuse Lhe same body deflnlLlons.
8ox2u allows you Lo avold desLroylng bodles by deleLlng your b2World ob[ecL, whlch does all Lhe
cleanup work for you. Powever, you should be mlndful Lo nulllfy body polnLers LhaL you keep ln your
game englne.
When you desLroy a body, Lhe aLLached flxLures and [olnLs are auLomaLlcally desLroyed. 1hls has
lmporLanL lmpllcaLlons for how you manage shape and [olnL polnLers.
C1; D70+? # @,-M
AfLer creaLlng a body, Lhere are many operaLlons you can perform on Lhe body. 1hese lnclude seLLlng
mass properLles, accesslng poslLlon and veloclLy, applylng forces, and Lransformlng polnLs and vecLors.
9#77 F#%#
Lvery body has a mass (scalar), cenLer of mass (2-vecLor), and roLaLlonal lnerLla (scalar). lor sLaLlc
bodles, Lhe mass and roLaLlonal lnerLla are seL Lo zero. When a body has flxed roLaLlon, lLs roLaLlonal
lnerLla ls zero.
normally Lhe mass properLles of a body are esLabllshed auLomaLlcally when flxLures are added Lo Lhe
body. ?ou can also ad[usL Lhe mass of a body aL run-Llme. 1hls ls usually done when you have speclal
game scenarlos LhaL requlre alLerlng Lhe mass.
:$9% ?.0k/445/0/12$340 !"k/445/0/' %/0/7H
AfLer seLLlng a body's mass dlrecLly, you may wlsh Lo reverL Lo Lhe naLural mass dlcLaLed by Lhe flxLures.
?ou can do Lhls wlLh:
:$9% i.4.0k/445/0/17H
1he body's mass daLa ls avallable Lhrough Lhe followlng funcLlons:
6+$/0C" D.0k/4417 2$340H
6+$/0C" D.0X3.*09/17 2$340H
2$340 !"N.2"M D.0h$2/+-.30.*17 2$340H
:$9% D.0k/445/0/1!"k/445/0/' %/0/7 2$340H
O%#%& *+G,'N#%0,+
1here are many aspecLs Lo Lhe body's sLaLe. ?ou can access Lhls sLaLe daLa efflclenLly Lhrough Lhe
followlng funcLlons:
:$9% ?.0b&A.1!"#$%&b&A. 0&A.7H
!"#$%&b&A. D.0b&A.17H

:$9% ?.0#>++.01!$$+ 6+/O7H
!$$+ X4#>++.017 2$340H

:$9% ?.0?+..A93OF++$L.%1!$$+ 6+/O7H
!$$+ X4?+..A93OF++$L.%17 2$340H

:$9% ?.0FL/n.1!$$+ 6+/O7H
!$$+ X4FL/n.17 2$340H

:$9% ?.0F209:.1!$$+ 6+/O7H
!$$+ X4F209:.17 2$340H

:$9% ?.0<9=.%i$0/09$31!$$+ 6+/O7H
!$$+ X4<9=.%i$0/09$317 2$340H
5,70%0,+ #+- T&:,/0%M
?ou can access Lhe poslLlon and roLaLlon of a body. 1hls ls common when renderlng your assoclaLed
game acLor. ?ou can also seL Lhe poslLlon, alLhough Lhls ls less common slnce you wlll normally use
8ox2u Lo slmulaLe movemenL.
!$$+ ?.0b*/346$*E12$340 !"N.2"M A$4909$3B 6+$/0C" /3O+.7H
2$340 !"b*/346$*EM D.0b*/346$*E17 2$340H
2$340 !"N.2"M D.0R$4909$317 2$340H
6+$/0C" D.0F3O+.17 2$340H
?ou can access Lhe cenLer of mass poslLlon ln local and world coordlnaLes. Much of Lhe lnLernal
slmulaLlon ln 8ox2u uses Lhe cenLer of mass. Powever, you should normally noL need Lo access lL.
lnsLead you wlll usually work wlLh Lhe body Lransform. lor example, you may have a body LhaL ls square.
1he body orlgln mlghL be a corner of Lhe square, whlle Lhe cenLer of mass ls locaLed aL Lhe cenLer of Lhe
square.
2$340 !"N.2"M D.0)$*+%-.30.*17 2$340H
2$340 !"N.2"M D.0h$2/+-.30.*17 2$340H
?ou can access Lhe llnear and angular veloclLy. 1he llnear veloclLy ls for Lhe cenLer of mass. 1herefore,
Lhe llnear veloclLy may change lf Lhe mass properLles change.

!"#$%&' E Z,0+%7
E1) 23,.%
!olnLs are used Lo consLraln bodles Lo Lhe world or Lo each oLher. 1yplcal examples ln games lnclude
ragdolls, LeeLers, and pulleys. !olnLs can be comblned ln many dlfferenL ways Lo creaLe lnLeresLlng
moLlons.
Some [olnLs provlde llmlLs so you can conLrol Lhe range of moLlon. Some [olnL provlde moLors whlch can
be used Lo drlve Lhe [olnL aL a prescrlbed speed unLll a prescrlbed force/Lorque ls exceeded.
!olnL moLors can be used ln many ways. ?ou can use moLors Lo conLrol poslLlon by speclfylng a [olnL
veloclLy LhaL ls proporLlonal Lo Lhe dlfference beLween Lhe acLual and deslred poslLlon. ?ou can also use
moLors Lo slmulaLe [olnL frlcLlon: seL Lhe [olnL veloclLy Lo zero and provlde a small, buL slgnlflcanL
maxlmum moLor force/Lorque. 1hen Lhe moLor wlll aLLempL Lo keep Lhe [olnL from movlng unLll Lhe load
becomes Loo sLrong.
E14 R"& Z,0+% F&G0+0%0,+
Lach [olnL Lype has a deflnlLlon LhaL derlves from b2!olnLuef. All [olnLs are connecLed beLween Lwo
dlfferenL bodles. Cne body may sLaLlc. !olnLs beLween sLaLlc and/or klnemaLlc bodles are allowed, buL
have no effecL and use some processlng Llme.
?ou can speclfy user daLa for any [olnL Lype and you can provlde a flag Lo prevenL Lhe aLLached bodles
from collldlng wlLh each oLher. 1hls ls acLually Lhe defaulL behavlor and you musL seL Lhe
collldeConnecLed 8oolean Lo allow colllslon beLween Lo connecLed bodles.
Many [olnL deflnlLlons requlre LhaL you provlde some geomeLrlc daLa. CfLen a [olnL wlll be deflned by
anchor polnLs. 1hese are polnLs flxed ln Lhe aLLached bodles. 8ox2u requlres Lhese polnLs Lo be speclfled
ln local coordlnaLes. 1hls way Lhe [olnL can be speclfled even when Lhe currenL body Lransforms vlolaLe
Lhe [olnL consLralnL --- a common occurrence when a game ls saved and reloaded. AddlLlonally, some
[olnL deflnlLlons need Lo know Lhe defaulL relaLlve angle beLween Lhe bodles. 1hls ls necessary Lo
consLraln roLaLlon correcLly.
lnlLlallzlng Lhe geomeLrlc daLa can be Ledlous, so many [olnLs have lnlLlallzaLlon funcLlons LhaL use Lhe
currenL body Lransforms Lo remove much of Lhe work. Powever, Lhese lnlLlallzaLlon funcLlons should
usually only be used for proLoLyplng. roducLlon code should deflne Lhe geomeLry dlrecLly. 1hls wlll
make [olnL behavlor more robusL.
1he resL of Lhe [olnL deflnlLlon daLa depends on Lhe [olnL Lype. We cover Lhese now.
E18 Z,0+% <#/%,'M
!olnLs are creaLed and desLroyed uslng Lhe world facLory meLhods. 1hls brlngs up an old lssue:
!"#$%&'
uon'L Lry Lo creaLe a [olnL on Lhe sLack or on Lhe heap uslng new or malloc. ?ou
musL creaLe and desLroy bodles and [olnLs uslng Lhe creaLe and desLroy meLhods of
Lhe b2World class.
Pere's an example of Lhe llfeLlme of a revoluLe [olnL:
!"i.:$+>0.8$9305.6 ;$9305.6H
;$9305.6I!$%&F G E&#$%&FH
;$9305.6I!$%&# G E&#$%&#H
;$9305.6I/32@$*R$930 G E&#$%&FJKD.0-.30.*R$4909$317H
!"i.:$+>0.8$930' ;$930 G 1!"i.:$+>0.8$930'7E&)$*+%JK-*./0.8$9301M;$9305.67H
III %$ 40>66 III
E&)$*+%JK5.40*$&8$9301;$9307H
;$930 G gqhhH
lL ls always good Lo nulllfy your polnLer afLer Lhey are desLroyed. 1hls wlll make Lhe program crash ln a
conLrolled manner lf you Lry Lo reuse Lhe polnLer.
1he llfeLlme of a [olnL ls noL slmple. Peed Lhls warnlng well:
!"#$%&'
!olnLs are desLroyed when an aLLached body ls desLroyed.
1hls precauLlon ls noL always necessary. ?ou may organlze your game englne so LhaL [olnLs are always
desLroyed before Lhe aLLached bodles. ln Lhls case you don'L need Lo lmplemenL Lhe llsLener class. See
Lhe secLlon on lmpllclL uesLrucLlon for deLalls.
E1; D70+? Z,0+%7
Many slmulaLlons creaLe Lhe [olnLs and don'L access Lhem agaln unLll Lhey are desLroyed. Powever,
Lhere ls a loL of useful daLa conLalned ln [olnLs LhaL you can use Lo creaLe a rlch slmulaLlon.
llrsL of all, you can geL Lhe bodles, anchor polnLs, and user daLa from a [olnL.
!"#$%&' D.0#$%&F17H
!"#$%&' D.0#$%&#17H
!"N.2" D.0F32@$*F17H
!"N.2" D.0F32@$*#17H
:$9%' D.0q4.*5/0/17H
All [olnLs have a reacLlon force and Lorque. 1hls Lhe reacLlon force applled Lo body 2 aL Lhe anchor polnL.
?ou can use reacLlon forces Lo break [olnLs or Lrlgger oLher game evenLs. 1hese funcLlons may do some
compuLaLlons, so don'L call Lhem lf you don'L need Lhe resulL.
!"N.2" D.0i./209$3<$*2.17H
6+$/0C" D.0i./209$3b$*m>.17H
E1A F07%#+/& Z,0+%
Cne of Lhe slmplesL [olnL ls a dlsLance [olnL whlch says LhaL Lhe dlsLance beLween Lwo polnLs on Lwo
bodles musL be consLanL. When you speclfy a dlsLance [olnL Lhe Lwo bodles should already be ln place.
1hen you speclfy Lhe Lwo anchor polnLs ln world coordlnaLes. 1he flrsL anchor polnL ls connecLed Lo
body 1, and Lhe second anchor polnL ls connecLed Lo body 2. 1hese polnLs lmply Lhe lengLh of Lhe
dlsLance consLralnL.

Pere ls an example of a dlsLance [olnL deflnlLlon. ln Lhls case we declde Lo allow Lhe bodles Lo colllde.
!"5940/32.8$9305.6 ;$9305.6H
;$9305.6IX3909/+9l.1E&#$%&FB E&#$%&#B L$*+%F32@$*j3#$%&FB L$*+%F32@$*j3#$%&#7H
;$9305.6I2$++9%.-$33.20.% G 0*>.H
1he dlsLance [olnL can also be made sofL, llke a sprlng-damper connecLlon. See Lhe Web example ln Lhe
LesLbed Lo see how Lhls behaves.
SofLness ls achleved by Lunlng Lwo consLanLs ln Lhe deflnlLlon: frequency and damplng raLlo. 1hlnk of Lhe
frequency as Lhe frequency of a harmonlc osclllaLor (llke a gulLar sLrlng). 1he frequency ls speclfled ln
PerLz. 1yplcally Lhe frequency should be less Lhan a half Lhe frequency of Lhe Llme sLep. So lf you are
uslng a 60Pz Llme sLep, Lhe frequency of Lhe dlsLance [olnL should be less Lhan 30Pz. 1he reason ls
relaLed Lo Lhe nyqulsL frequency.
1he damplng raLlo ls non-dlmenslonal and ls Lyplcally beLween 0 and 1, buL can be larger. AL 1, Lhe
damplng ls crlLlcal (all osclllaLlons should vanlsh).
;$9305.6I6*.m>.32&rl G UIP6H
;$9305.6I%/EA93Oi/09$ G PIS6H
E1B >&X,:.%& Z,0+%
A revoluLe [olnL forces Lwo bodles Lo share a common anchor polnL, ofLen called a hlnge polnL. 1he
revoluLe [olnL has a slngle degree of freedom: Lhe relaLlve roLaLlon of Lhe Lwo bodles. 1hls ls called Lhe
[olnL angle.

1o speclfy a revoluLe you need Lo provlde Lwo bodles and a slngle anchor polnL ln world space. 1he
lnlLlallzaLlon funcLlon assumes LhaL Lhe bodles are already ln Lhe correcL poslLlon.
ln Lhls example, Lwo bodles are connecLed by a revoluLe [olnL aL Lhe flrsL body's cenLer of mass.
!"i.:$+>0.8$9305.6 ;$9305.6H
;$9305.6IX3909/+9l.1E&#$%&FB E&#$%&#B E&#$%&FJKD.0)$*+%-.30.*177H
1he revoluLe [olnL angle ls poslLlve when body8 roLaLes CCW abouL Lhe angle polnL. Llke all angles ln
8ox2u, Lhe revoluLe angle ls measured ln radlans. 8y convenLlon Lhe revoluLe [olnL angle ls zero when
Lhe [olnL ls creaLed uslng lnlLlallze(), regardless of Lhe currenL roLaLlon of Lhe Lwo bodles.
ln some cases you mlghL wlsh Lo conLrol Lhe [olnL angle. lor Lhls, Lhe revoluLe [olnL can opLlonally
slmulaLe a [olnL llmlL and/or a moLor.
A [olnL llmlL forces Lhe [olnL angle Lo remaln beLween a lower and upper bound. 1he llmlL wlll apply as
much Lorque as needed Lo make Lhls happen. 1he llmlL range should lnclude zero, oLherwlse Lhe [olnL
wlll lurch when Lhe slmulaLlon beglns.
A [olnL moLor allows you Lo speclfy Lhe [olnL speed (Lhe Llme derlvaLlve of Lhe angle). 1he speed can be
negaLlve or poslLlve. A moLor can have lnflnlLe force, buL Lhls ls usually noL deslrable. 8ecall Lhe eLernal
quesLlon:
12"/% "/..)($ 3")( /( +44)$+$%+5*) -#40) ,))%$ /( +,,#6/5*) #57)0%81
l can Lell you lL's noL preLLy. So you can provlde a maxlmum Lorque for Lhe [olnL moLor. 1he [olnL moLor
wlll malnLaln Lhe speclfled speed unless Lhe requlred Lorque exceeds Lhe speclfled maxlmum. When Lhe
maxlmum Lorque ls exceeded, Lhe [olnL wlll slow down and can even reverse.
?ou can use a [olnL moLor Lo slmulaLe [olnL frlcLlon. !usL seL Lhe [olnL speed Lo zero, and seL Lhe
maxlmum Lorque Lo some small, buL slgnlflcanL value. 1he moLor wlll Lry Lo prevenL Lhe [olnL from
roLaLlng, buL wlll yleld Lo a slgnlflcanL load.
Pere's a revlslon of Lhe revoluLe [olnL deflnlLlon above, Lhls Llme Lhe [olnL has a llmlL and a moLor
enabled. 1he moLor ls seLup Lo slmulaLe [olnL frlcLlon.
!"i.:$+>0.8$9305.6 ;$9305.6H
;$9305.6IX3909/+9l.1!$%&FB !$%&#B E&#$%&FJKD.0)$*+%-.30.*177H
;$9305.6I+$L.*F3O+. G JPIS6 ' !"TA9H VV J`P %.O*..4
;$9305.6I>AA.*F3O+. G PI"S6 ' !"TA9H VV US %.O*..4
;$9305.6I.3/!+.h9E90 G 0*>.H
;$9305.6IE/=k$0$*b$*m>. G QPIP6H
;$9305.6IE$0$*?A..% G PIP6H
;$9305.6I.3/!+.k$0$* G 0*>.H
?ou can access a revoluLe [olnL's angle, speed, and moLor Lorque.
6+$/0C" D.08$930F3O+.17 2$340H
6+$/0C" D.08$930?A..%17 2$340H
6+$/0C" D.0k$0$*b$*m>.17 2$340H
?ou also updaLe Lhe moLor parameLers each sLep.
:$9% ?.0k$0$*?A..%16+$/0C" 4A..%7H
:$9% ?.0k/=k$0$*b$*m>.16+$/0C" 0$*m>.7H
!olnL moLors have some lnLeresLlng ablllLles. ?ou can updaLe Lhe [olnL speed every Llme sLep so you can
make Lhe [olnL move back-and-forLh llke a slne-wave or accordlng Lo whaLever funcLlon you wanL.
III D/E. h$$A #.O93 III
E&8$930JK?.0k$0$*?A..%12$461PIS6 ' 09E.77H
III D/E. h$$A e3% III
?ou can also use [olnL moLors Lo Lrack a deslred [olnL angle. lor example:
III D/E. h$$A #.O93 III
6+$/0C" /3O+.e**$* G E&8$930JKD.08$930F3O+.17 J /3O+.b/*O.0H
6+$/0C" O/93 G PIQ6H
E&8$930JK?.0k$0$*?A..%1JO/93 ' /3O+.e**$*7H
III D/E. h$$A e3% III
Cenerally your galn parameLer should noL be Loo large. CLherwlse your [olnL may become unsLable.
E1C 5'07N#%0/ Z,0+%
A prlsmaLlc [olnL allows for relaLlve LranslaLlon of Lwo bodles along a speclfled axls. A prlsmaLlc [olnL
prevenLs relaLlve roLaLlon. 1herefore, a prlsmaLlc [olnL has a slngle degree of freedom.

1he prlsmaLlc [olnL deflnlLlon ls slmllar Lo Lhe revoluLe [olnL descrlpLlon, [usL subsLlLuLe LranslaLlon for
angle and force for Lorque. uslng Lhls analogy provldes an example prlsmaLlc [olnL deflnlLlon wlLh a [olnL
llmlL and a frlcLlon moLor:
!"R*94E/0928$9305.6 ;$9305.6H
!"N.2" L$*+%F=941QIP6B PIP67H
;$9305.6IX3909/+9l.1E&#$%&FB E&#$%&#B E&#$%&FJKD.0)$*+%-.30.*17B L$*+%F=947H
;$9305.6I+$L.*b*/34+/09$3 G JSIP6H
;$9305.6I>AA.*b*/34+/09$3 G "IS6H
;$9305.6I.3/!+.h9E90 G 0*>.H
;$9305.6IE/=k$0$*<$*2. G QIP6H
;$9305.6IE$0$*?A..% G PIP6H
;$9305.6I.3/!+.k$0$* G 0*>.H
1he revoluLe [olnL has an lmpllclL axls comlng ouL of Lhe screen. 1he prlsmaLlc [olnL needs an expllclL axls
parallel Lo Lhe screen. 1hls axls ls flxed ln Lhe Lwo bodles and follows Lhelr moLlon.
Llke Lhe revoluLe [olnL, Lhe prlsmaLlc [olnL LranslaLlon ls zero when Lhe [olnL ls creaLed uslng lnlLlallze().
So be sure zero ls beLween your lower and upper LranslaLlon llmlLs.
uslng a prlsmaLlc [olnL ls slmllar Lo uslng a revoluLe [olnL. Pere are Lhe relevanL member funcLlons:
6+$/0C" D.08$930b*/34+/09$317 2$340H
6+$/0C" D.08$930?A..%17 2$340H
6+$/0C" D.0k$0$*<$*2.17 2$340H
:$9% ?.0k$0$*?A..%16+$/0C" 4A..%7H
:$9% ?.0k$0$*<$*2.16+$/0C" 6$*2.7H
E1E 5.::&M Z,0+%
A pulley ls used Lo creaLe an ldeallzed pulley. 1he pulley connecLs Lwo bodles Lo ground and Lo each
oLher. As one body goes up, Lhe oLher goes down. 1he LoLal lengLh of Lhe pulley rope ls conserved
accordlng Lo Lhe lnlLlal conflguraLlon.
+.3O0@Q Z +.3O0@" GG 2$340/30
?ou can supply a raLlo LhaL slmulaLes a block and Lackle. 1hls causes one slde of Lhe pulley Lo exLend
fasLer Lhan Lhe oLher. AL Lhe same Llme Lhe consLralnL force ls smaller on one slde Lhan Lhe oLher. ?ou
can use Lhls Lo creaLe mechanlcal leverage.
+.3O0@Q Z */09$ ' +.3O0@" GG 2$340/30
lor example, lf Lhe raLlo ls 2, Lhen lengLh1 wlll vary aL Lwlce Lhe raLe of lengLh2. Also Lhe force ln Lhe
rope aLLached Lo body1 wlll have half Lhe consLralnL force as Lhe rope aLLached Lo body2.

ulleys can be Lroublesome when one slde ls fully exLended. 1he rope on Lhe oLher slde wlll have zero
lengLh. AL Lhls polnL Lhe consLralnL equaLlons become slngular (bad). ?ou should conflgure colllslon
shapes Lo prevenL Lhls.
Pere ls an example pulley deflnlLlon:
!"N.2" /32@$*Q G E&#$%&QJKD.0)$*+%-.30.*17H
!"N.2" /32@$*" G E&#$%&"JKD.0)$*+%-.30.*17H
!"N.2" O*$>3%F32@$*Q1AQI=B AQI& Z QPIP67H
!"N.2" O*$>3%F32@$*"1A"I=B A"I& Z Q"IP67H
6+$/0C" */09$ G QIP6H
!"R>++.&8$9305.6 ;$9305.6H
;$9305.6IX3909/+9l.1E&#$%&QB E&#$%&"B O*$>3%F32@$*QB O*$>3%F32@$*"B /32@$*QB
/32@$*"B */09$7H
ulley [olnLs provlde Lhe currenL lengLhs.
6+$/0C" D.0h.3O0@F17 2$340H
6+$/0C" D.0h.3O0@#17 2$340H
E1H L&#' Z,0+%
lf you wanL Lo creaLe a sophlsLlcaLed mechanlcal conLrapLlon you mlghL wanL Lo use gears. ln prlnclple
you can creaLe gears ln 8ox2u by uslng compound shapes Lo model gear LeeLh. 1hls ls noL very efflclenL
and mlghL be Ledlous Lo auLhor. ?ou also have Lo be careful Lo llne up Lhe gears so Lhe LeeLh mesh
smooLhly. 8ox2u has a slmpler meLhod of creaLlng gears: Lhe gear [olnL.

1he gear [olnL can only connecL revoluLe and/or prlsmaLlc [olnLs.
Llke Lhe pulley raLlo, you can speclfy a gear raLlo. Powever, ln Lhls case Lhe gear raLlo can be negaLlve.
Also keep ln mlnd LhaL when one [olnL ls a revoluLe [olnL (angular) and Lhe oLher [olnL ls prlsmaLlc
(LranslaLlon), and Lhen Lhe gear raLlo wlll have unlLs of lengLh or one over lengLh.
2$$*%93/0.Q Z */09$ ' 2$$*%93/0." GG 2$340/30
Pere ls an example gear [olnL. 1he bodles my8odyA and my8ody8 are any bodles from Lhe Lwo [olnLs, as
long as Lhey are noL Lhe same bodles.
!"D./*8$9305.6 ;$9305.6H
;$9305.6I!$%&F G E&#$%&FH
;$9305.6I!$%&# G E&#$%&#H
;$9305.6I;$930Q G E&i.:$+>0.8$930H
;$9305.6I;$930" G E&R*94E/0928$930H
;$9305.6I*/09$ G "IP6 ' !"TA9 V E&h.3O0@H
noLe LhaL Lhe gear [olnL depends on Lwo oLher [olnLs. 1hls creaLes a fraglle slLuaLlon. WhaL happens lf
Lhose [olnLs are deleLed?
!"#$%&'
Always deleLe gear [olnLs before Lhe revoluLe/prlsmaLlc [olnLs on Lhe gears.
CLherwlse your code wlll crash ln a bad way due Lo Lhe orphaned [olnL polnLers ln
Lhe gear [olnL. ?ou should also deleLe Lhe gear [olnL before you deleLe any of Lhe
bodles lnvolved.
E1)V 9,.7& Z,0+%
1he mouse [olnL ls used ln Lhe LesLbed Lo manlpulaLe bodles wlLh Lhe mouse. lL aLLempLs Lo drlve a polnL
on a body Lowards Lhe currenL poslLlon of Lhe cursor. 1here ls no resLrlcLlon on roLaLlon.
1he mouse [olnL deflnlLlon has a LargeL polnL, maxlmum force, frequency, and damplng raLlo. 1he LargeL
point initially coincides with the bodys anchor point. The maximum force is used to prevent violent
reacLlons when mulLlple dynamlc bodles lnLeracL. ?ou can make Lhls as large as you llke. 1he frequency
and damplng raLlo are used Lo creaLe a sprlng/damper effecL slmllar Lo Lhe dlsLance [olnL.
Many users have Lrled Lo adapL Lhe mouse [olnL for game play. users ofLen wanL Lo achleve preclse
positioning and instantaneous response. The mouse joint doesnt work very well in that context. You
may wlsh Lo conslder uslng klnemaLlc bodles lnsLead.
E1)) K"&&: Z,0+%
1he wheel [olnL resLrlcLs a polnL on body8 Lo a llne on bodyA. 1he wheel [olnL also provldes a suspenslon
sprlng. See b2Wheel!olnL.h and Car.h for deLalls.

E1)4 K&:- Z,0+%
1he weld [olnL aLLempLs Lo consLraln all relaLlve moLlon beLween Lwo bodles. See Lhe CanLllever.h ln Lhe
LesLbed Lo see how Lhe weld [olnL behaves.
lL ls LempLlng Lo use Lhe weld [olnL Lo deflne breakable sLrucLures. Powever, Lhe 8ox2u solver ls lLeraLlve
so Lhe [olnLs are a blL sofL. So chalns of bodles connecLed by weld [olnLs wlll flex.
lnsLead lL ls beLLer Lo creaLe breakable bodles sLarLlng wlLh a slngle body wlLh mulLlple flxLures. When
Lhe body breaks, you can desLroy a flxLure and recreaLe lL on a new body. See Lhe 8reakable example ln
Lhe LesLbed.
E1)8 >,$& Z,0+%
1he rope [olnL resLrlcLs Lhe maxlmum dlsLance beLween Lwo polnLs. 1hls can be useful Lo prevenL chalns
of bodles from sLreLchlng, even under hlgh load. See b28ope!olnL.h and 8ope!olnL.h for deLalls.
E1); <'0/%0,+ Z,0+%
1he frlcLlon [olnL ls used for Lop-down frlcLlon. 1he [olnL provldes 2u LranslaLlonal frlcLlon and angular
frlcLlon. See b2lrlcLlon!olnL.h and Applylorce.h for deLalls.
!"#$%&' H !,+%#/%7
H1) 23,.%
ConLacLs are ob[ecLs creaLed by 8ox2u Lo manage colllslon beLween Lwo flxLures. lf Lhe flxLure has
chlldren, such as a chaln shape, Lhen a conLacL exlsLs for each relevanL chlld. 1here are dlfferenL klnds of
conLacLs, derlved from b2ConLacL, for managlng conLacL beLween dlfferenL klnds of flxLures. lor
example Lhere ls a conLacL class for managlng polygon-polygon colllslon and anoLher conLacL class for
managlng clrcle-clrcle colllslon.
Pere ls some Lermlnology assoclaLed wlLh conLacLs.
/,+%#/% $,0+%
A conLacL polnL ls a polnL where Lwo shapes Louch. 8ox2u approxlmaLes conLacL wlLh a small number of
polnLs.
/,+%#/% +,'N#:
A conLacL normal ls a unlL vecLor LhaL polnLs from one shape Lo anoLher. 8y convenLlon, Lhe normal
polnLs from flxLureA Lo flxLure8.
/,+%#/% 7&$#'#%0,+
SeparaLlon ls Lhe opposlLe of peneLraLlon. SeparaLlon ls negaLlve when shapes overlap. lL ls posslble LhaL
fuLure verslons of 8ox2u wlll creaLe conLacL polnLs wlLh poslLlve separaLlon, so you may wanL Lo check
Lhe slgn when conLacL polnLs are reporLed.
/,+%#/% N#+0G,:-
ConLacL beLween Lwo convex polygons may generaLe up Lo 2 conLacL polnLs. 8oLh of Lhese polnLs use
Lhe same normal, so Lhey are grouped lnLo a conLacL manlfold, whlch ls an approxlmaLlon of a
conLlnuous reglon of conLacL.
+,'N#: 0N$.:7&
1he normal force ls Lhe force applled aL a conLacL polnL Lo prevenL Lhe shapes from peneLraLlng. lor
convenlence, 8ox2u works wlLh lmpulses. 1he normal lmpulse ls [usL Lhe normal force mulLlplled by Lhe
Llme sLep.
%#+?&+% 0N$.:7&
1he LangenL force ls generaLed aL a conLacL polnL Lo slmulaLe frlcLlon. lor convenlence, Lhls ls sLored as
an lmpulse.
/,+%#/% 0-7
8ox2u Lrles Lo re-use Lhe conLacL force resulLs from a Llme sLep as Lhe lnlLlal guess for Lhe nexL Llme
sLep. 8ox2u uses conLacL lds Lo maLch conLacL polnLs across Llme sLeps. 1he lds conLaln geomeLrlc
feaLures lndlces LhaL help Lo dlsLlngulsh one conLacL polnL from anoLher.
ConLacLs are creaLed when Lwo fixtures AA88s overlap. SomeLlmes colllslon fllLerlng wlll prevenL Lhe
creaLlon of conLacLs. ConLacLs are desLroyed wlLh Lhe AA88s cease Lo overlap.
So you mlghL gaLher LhaL Lhere may be conLacLs creaLed for flxLures LhaL are noL Louchlng ([usL Lhelr
AA88s). Well, Lhls ls correcL. lL's a "chlcken or egg" problem. We don'L know lf we need a conLacL ob[ecL
unLll one ls creaLed Lo analyze Lhe colllslon. We could deleLe Lhe conLacL rlghL away lf Lhe shapes are noL
Louchlng, or we can [usL walL unLll Lhe AA88s sLop overlapplng. 8ox2u Lakes Lhe laLLer approach because
lL leLs Lhe sysLem cache lnformaLlon Lo lmprove performance.
H14 !,+%#/% !:#77
As menLloned before, Lhe conLacL class ls creaLed and desLroyed by 8ox2u. ConLacL ob[ecLs are noL
creaLed by Lhe user. Powever, you are able Lo access Lhe conLacL class and lnLeracL wlLh lL.
?ou can access Lhe raw conLacL manlfold:
!"k/396$+%' D.0k/396$+%17H
2$340 !"k/396$+%' D.0k/396$+%17 2$340H
?ou can poLenLlally modlfy Lhe manlfold, buL Lhls ls generally noL supporLed and ls for advanced usage.
1here ls a helper funcLlon Lo geL Lhe b2WorldManlfold:
:$9% D.0)$*+%k/396$+%1!")$*+%k/396$+%' L$*+%k/396$+%7 2$340H
1hls uses Lhe currenL poslLlons of Lhe bodles Lo compuLe world poslLlons of Lhe conLacL polnLs.
Sensors do noL creaLe manlfolds, so for Lhem use:
!$$+ 0$>2@93O G 4.34$*-$30/20JKX4b$>2@93O17H
1hls funcLlon also works for non-sensors.
?ou can geL Lhe flxLures from a conLacL. lrom Lhose you can geL Lhe bodles.
!"<9=0>*.' 69=0>*.F G E&-$30/20JKD.0<9=0>*.F17H
!"#$%&' !$%&F G 69=0>*.FJKD.0#$%&17H
k&F20$*' /20$*F G 1k&F20$*'7!$%&FJKD.0q4.*5/0/17H
?ou can dlsable a conLacL. 1hls only works lnslde Lhe b2ConLacLLlsLener::reSolve evenL, dlscussed
below.
H18 2//&770+? !,+%#/%7
?ou can geL access Lo conLacLs ln several ways. ?ou can access Lhe conLacLs dlrecLly on Lhe world and
body sLrucLures. ?ou can also lmplemenL a conLacL llsLener.
?ou can lLeraLe over all conLacLs ln Lhe world:
6$* 1!"-$30/20' 2 G E&)$*+%JKD.0-$30/20h94017H 2H 2 G 2JKD.0g.=0177
[
VV A*$2.44 2
_
?ou can also lLeraLe over all Lhe conLacLs on a body. 1hese are sLored ln a graph uslng a conLacL edge
sLrucLure.
6$* 1!"-$30/20e%O.' 2. G E&#$%&JKD.0-$30/20h94017H 2.H 2. G 2.JK3.=07
[
!"-$30/20' 2 G 2.JK2$30/20H
VV A*$2.44 2
_
?ou can also access conLacLs uslng Lhe conLacL llsLener LhaL ls descrlbed below.
!"#$%&'
Accesslng conLacLs off b2World and b28ody may mlss some LranslenL conLacLs LhaL
occur ln Lhe mlddle of Lhe Llme sLep. use b2ConLacLLlsLener Lo geL Lhe mosL
accuraLe resulLs.
H1; !,+%#/% [07%&+&'
?ou can recelve conLacL daLa by lmplemenLlng b2ConLacLLlsLener. 1he conLacL llsLener supporLs several
evenLs: begln, end, pre-solve, and posL-solve.
2+/44 k&-$30/20h940.3.* , A>!+92 !"-$30/20h940.3.*
[
A>!+92,
:$9% #.O93-$30/201!"-$30/20' 2$30/207
[ V' @/3%+. !.O93 .:.30 'V _

:$9% e3%-$30/201!"-$30/20' 2$30/207
[ V' @/3%+. .3% .:.30 'V _

:$9% R*.?$+:.1!"-$30/20' 2$30/20B 2$340 !"k/396$+%' $+%k/396$+%7
[ V' @/3%+. A*.J4$+:. .:.30 'V _

:$9% R$40?$+:.1!"-$30/20' 2$30/20B 2$340 !"-$30/20XEA>+4.' 9EA>+4.7
[ V' @/3%+. A$40J4$+:. .:.30 'V _
_H

!"#$%&'
uo noL keep a reference Lo Lhe polnLers senL Lo b2ConLacLLlsLener. lnsLead make a
deep copy of Lhe conLacL polnL daLa lnLo your own buffer. 1he example below
shows one way of dolng Lhls.
AL run-Llme you can creaLe an lnsLance of Lhe llsLener and reglsLer lL wlLh b2World::SeLConLacLLlsLener.
8e sure your llsLener remalns ln scope whlle Lhe world ob[ecL exlsLs.
@&?0+ !,+%#/% UX&+%
1hls ls called when Lwo flxLures begln Lo overlap. 1hls ls called for sensors and non-sensors. 1hls evenL
can only occur lnslde Lhe Llme sLep.
U+- !,+%#/% UX&+%
1hls ls called when Lwo flxLures cease Lo overlap. 1hls ls called for sensors and non-sensors. 1hls may be
called when a body ls desLroyed, so Lhls evenL can occur ouLslde Lhe Llme sLep.
5'&YO,:X& UX&+%
1hls ls called afLer colllslon deLecLlon, buL before colllslon resoluLlon. 1hls glves you a chance Lo dlsable
Lhe conLacL based on Lhe currenL conflguraLlon. lor example, you can lmplemenL a one-slded plaLform
uslng Lhls callback and calllng b2ConLacL::SeLLnabled(false). 1he conLacL wlll be re-enabled each Llme
Lhrough colllslon processlng, so you wlll need Lo dlsable Lhe conLacL every Llme-sLep. 1he pre-solve
evenL may be flred mulLlple Llmes per Llme sLep per conLacL due Lo conLlnuous colllslon deLecLlon.
:$9% R*.?$+:.1!"-$30/20' 2$30/20B 2$340 !"k/396$+%' $+%k/396$+%7
[
!")$*+%k/396$+% L$*+%k/396$+%H
2$30/20JKD.0)$*+%k/396$+%1ML$*+%k/396$+%7H
96 1L$*+%k/396$+%I3$*E/+I& Y JPIS67
[
2$30/20JK?.0e3/!+.%16/+4.7H
_
_
1he pre-solve evenL ls also a good place Lo deLermlne Lhe polnL sLaLe and Lhe approach veloclLy of
colllslons.
:$9% R*.?$+:.1!"-$30/20' 2$30/20B 2$340 !"k/396$+%' $+%k/396$+%7
[
!")$*+%k/396$+% L$*+%k/396$+%H
2$30/20JKD.0)$*+%k/396$+%1ML$*+%k/396$+%7H
!"R$930?0/0. 40/0.Qc"dB 40/0."c"dH
!"D.0R$930?0/0.4140/0.QB 40/0."B $+%k/396$+%B 2$30/20JKD.0k/396$+%177H
96 140/0."cPd GG !"T/%%?0/0.7
[
2$340 !"#$%&' !$%&F G 2$30/20JKD.0<9=0>*.F17JKD.0#$%&17H
2$340 !"#$%&' !$%&# G 2$30/20JKD.0<9=0>*.#17JKD.0#$%&17H
!"N.2" A$930 G L$*+%k/396$+%IA$9304cPdH
!"N.2" :F G !$%&FJKD.0h93./*N.+$290&<*$E)$*+%R$9301A$9307H
!"N.2" :# G !$%&#JKD.0h93./*N.+$290&<*$E)$*+%R$9301A$9307H
6+$/0C" /AA*$/2@N.+$290& G !"5$01:# :FB L$*+%k/396$+%I3$*E/+7H
96 1/AA*$/2@N.+$290& K QIP67
[
k&R+/&-$++949$3?$>3%17H
_
_
_

5,7%YO,:X& UX&+%
1he posL solve evenL ls where you can gather collision impulse results. If you dont care about the
lmpulses, you should probably [usL lmplemenL Lhe pre-solve evenL.
lL ls LempLlng Lo lmplemenL game loglc LhaL alLers Lhe physlcs world lnslde a conLacL callback. lor
example, you may have a colllslon LhaL applles damage and Lry Lo desLroy Lhe assoclaLed acLor and lLs
rlgld body. Powever, 8ox2u does noL allow you Lo alLer Lhe physlcs world lnslde a callback because you
mlghL desLroy ob[ecLs LhaL 8ox2u ls currenLly processlng, leadlng Lo orphaned polnLers.
1he recommended pracLlce for processlng conLacL polnLs ls Lo buffer all conLacL daLa LhaL you care
abouL and process lL afLer Lhe Llme sLep. ?ou should always process Lhe conLacL polnLs lmmedlaLely afLer
Lhe Llme sLep, oLherwlse some oLher cllenL code mlghL alLer Lhe physlcs world, lnvalldaLlng Lhe conLacL
buffer. When you process Lhe conLacL buffer you can alLer Lhe physlcs world, buL you sLlll need Lo be
careful LhaL you don'L orphan polnLers sLored ln Lhe conLacL polnL buffer. 1he LesLbed has example
conLacL polnL processlng LhaL ls safe from orphaned polnLers.
1hls code from Lhe Colllslonrocesslng LesL shows how Lo handle orphaned bodles when processlng Lhe
conLacL buffer. Pere ls an excerpL. 8e sure Lo read Lhe commenLs ln Lhe llsLlng. 1hls code assumes LhaL
all conLacL polnLs have been buffered ln Lhe b2ConLacLolnL array m_polnLs.
VV ). /*. O$93O 0$ %.40*$& 4$E. !$%9.4 /22$*%93O 0$ 2$30/20
VV A$9304I ). E>40 !>66.* 0@. !$%9.4 0@/0 4@$>+% !. %.40*$&.%
VV !.2/>4. 0@.& E/& !.+$3O 0$ E>+09A+. 2$30/20 A$9304I
2$340 930C" nTE/=g>n. G WH
!"#$%&' 3>n.cnTE/=g>n.dH
930C" 3>n.-$>30 G PH

VV b*/:.*4. 0@. 2$30/20 !>66.*I 5.40*$& !$%9.4 0@/0
VV /*. 0$>2@93O @./:9.* !$%9.4I
6$* 1930C" 9 G PH 9 Y ETA$930-$>30H ZZ97
[
-$30/20R$930' A$930 G ETA$9304 Z 9H

!"#$%&' !$%&Q G A$930JK4@/A.QJKD.0#$%&17H
!"#$%&' !$%&" G A$930JK4@/A."JKD.0#$%&17H
6+$/0C" E/44Q G !$%&QJKD.0k/4417H
6+$/0C" E/44" G !$%&"JKD.0k/4417H

96 1E/44Q K PIP6 MM E/44" K PIP67
[
96 1E/44" K E/44Q7
[
3>n.c3>n.-$>30ZZd G !$%&QH
_
.+4.
[
3>n.c3>n.-$>30ZZd G !$%&"H
_

96 13>n.-$>30 GG nTE/=g>n.7
[
!*./nH
_
_
_

VV ?$*0 0@. 3>n. /**/& 0$ O*$>A %>A+92/0.4I
40%,,4$*013>n.B 3>n. Z 3>n.-$>307H

VV 5.40*$& 0@. !$%9.4B 4n9AA93O %>A+92/0.4I
930C" 9 G PH
L@9+. 19 Y 3>n.-$>307
[
!"#$%&' ! G 3>n.c9ZZdH
L@9+. 19 Y 3>n.-$>30 MM 3>n.c9d GG !7
[
ZZ9H
_

ETL$*+%JK5.40*$&#$%&1!7H
_

H1A !,+%#/% <0:%&'0+?
CfLen ln a game you don'L wanL all ob[ecLs Lo colllde. lor example, you may wanL Lo creaLe a door LhaL
only cerLaln characLers can pass Lhrough. 1hls ls called conLacL fllLerlng, because some lnLeracLlons are
fllLered ouL.
8ox2u allows you Lo achleve cusLom conLacL fllLerlng by lmplemenLlng a b2ConLacLlllLer class. 1hls class
requlres you Lo lmplemenL a ShouldColllde funcLlon LhaL recelves Lwo b2Shape polnLers. ?our funcLlon
reLurns Lrue lf Lhe shapes should colllde.
1he defaulL lmplemenLaLlon of ShouldColllde uses Lhe b2lllLeruaLa deflned ln ChapLer 6, llxLures.
!$$+ !"-$30/20<9+0.*,,?@$>+%-$++9%.1!"<9=0>*.' 69=0>*.FB !"<9=0>*.' 69=0>*.#7
[
2$340 !"<9+0.*M 69+0.*F G 69=0>*.FJKD.0<9+0.*5/0/17H
2$340 !"<9+0.*M 69+0.*# G 69=0>*.#JKD.0<9+0.*5/0/17H

96 169+0.*FIO*$>AX3%.= GG 69+0.*#IO*$>AX3%.= MM 69+0.*FIO*$>AX3%.= oG P7
[
*.0>*3 69+0.*FIO*$>AX3%.= K PH
_

!$$+ 2$++9%. G 169+0.*FIE/4n#904 M 69+0.*#I2/0.O$*&#9047 oG P MM
169+0.*FI2/0.O$*&#904 M 69+0.*#IE/4n#9047 oG PH
*.0>*3 2$++9%.H
_
AL run-Llme you can creaLe an lnsLance of your conLacL fllLer and reglsLer lL wlLh
b2World::SeLConLacLlllLer. Make sure your fllLer sLays ln scope whlle Lhe world exlsLs.
k&-$30/20<9+0.* 69+0.*H
L$*+%JK?.0-$30/20<9+0.*1M69+0.*7H
// filter remains in scope

!"#$%&' )V K,':- !:#77
23,.%
1he b2World class conLalns Lhe bodles and [olnLs. lL manages all aspecLs of Lhe slmulaLlon and allows for
asynchronous querles (llke AA88 querles and ray-casLs). Much of your lnLeracLlons wlLh 8ox2u wlll be
wlLh a b2World ob[ecL.
!'&#%0+? #+- F&7%',M0+? # K,':-
CreaLlng a world ls falrly slmple. ?ou [usL need Lo provlde a gravlLy vecLor and a 8oolean lndlcaLlng lf
bodles can sleep. usually you wlll creaLe and desLroy a world uslng new and deleLe.
!")$*+%' E&)$*+% G 3.L !")$*+%1O*/:90&B %$?+..A7H
III %$ 40>66 III
%.+.0. E&)$*+%H
D70+? # K,':-
1he world class conLalns facLorles for creaLlng and desLroylng bodles and [olnLs. 1hese facLorles are
dlscussed laLer ln Lhe secLlons on bodles and [olnLs. 1here are some oLher lnLeracLlons wlLh b2World
LhaL l wlll cover now.
O0N.:#%0,+
1he world class ls used Lo drlve Lhe slmulaLlon. ?ou speclfy a Llme sLep and a veloclLy and poslLlon
lLeraLlon counL. lor example:
6+$/0C" 09E.?0.A G QIP6 V WPI6H
930C" :.+$290&X0.*/09$34 G QPH
930C" A$4909$3X0.*/09$34 G aH
E&)$*+%JK?0.A109E.?0.AB :.+$290&X0.*/09$34B A$4909$3X0.*/09$347H
AfLer Lhe Llme sLep you can examlne your bodles and [olnLs for lnformaLlon. MosL llkely you wlll grab Lhe
poslLlon off Lhe bodles so LhaL you can updaLe your acLors and render Lhem. ?ou can perform Lhe Llme
sLep anywhere ln your game loop, buL you should be aware of Lhe order of Lhlngs. lor example, you
musL creaLe bodles before Lhe Llme sLep lf you wanL Lo geL colllslon resulLs for Lhe new bodles ln LhaL
frame.
As l dlscussed above ln Lhe PelloWorld LuLorlal, you should use a flxed Llme sLep. 8y uslng a larger Llme
sLep you can lmprove performance ln low frame raLe scenarlos. 8uL generally you should use a Llme sLep
no larger Lhan 1/30 seconds. A Llme sLep of 1/60 seconds wlll usually dellver a hlgh quallLy slmulaLlon.
1he lLeraLlon counL conLrols how many Llmes Lhe consLralnL solver sweeps over all Lhe conLacLs and
[olnLs ln Lhe world. More lLeraLlon always ylelds a beLLer slmulaLlon. 8uL don'L Lrade a small Llme sLep for
a large lLeraLlon counL. 60Pz and 10 lLeraLlons ls far beLLer Lhan 30Pz and 20 lLeraLlons.
AfLer sLepplng, you should clear any forces you have applled Lo your bodles. 1hls ls done wlLh Lhe
command b2World::Clearlorces. 1hls leLs you Lake mulLlple sub-sLeps wlLh Lhe same force fleld.
E&)$*+%JK-+./*<$*2.417H
UJ$:,'0+? %"& K,':-
1he world ls a conLalner for bodles, conLacLs, and [olnLs. ?ou can grab Lhe body, conLacL, and [olnL llsLs
off Lhe world and lLeraLe over Lhem. lor example, Lhls code wakes up all Lhe bodles ln Lhe world:
6$* 1!"#$%&' ! G E&)$*+%JKD.0#$%&h94017H !H ! G !JKD.0g.=0177
[
!JK?.0FL/n.10*>.7H
_
unforLunaLely real programs can be more compllcaLed. lor example, Lhe followlng code ls broken:
6$* 1!"#$%&' ! G E&)$*+%JKD.0#$%&h94017H !H ! G !JKD.0g.=0177
[
D/E.F20$*' E&F20$* G 1D/E.F20$*'7!JKD.0q4.*5/0/17H
96 1E&F20$*JKX45./%177
[
E&)$*+%JK5.40*$&#$%&1!7H VV eiiji, 3$L D.0g.=0 *.0>*34 O/*!/O.I
_
_
LveryLhlng goes ok unLll a body ls desLroyed. Cnce a body ls desLroyed, lLs nexL polnLer becomes lnvalld.
So Lhe call Lo b28ody::CeLnexL() wlll reLurn garbage. 1he soluLlon Lo Lhls ls Lo copy Lhe nexL polnLer
before desLroylng Lhe body.
!"#$%&' 3$%. G E&)$*+%JKD.0#$%&h94017H
L@9+. 13$%.7
[
!"#$%&' ! G 3$%.H
3$%. G 3$%.JKD.0g.=017H

D/E.F20$*' E&F20$* G 1D/E.F20$*'7!JKD.0q4.*5/0/17H
96 1E&F20$*JKX45./%177
[
E&)$*+%JK5.40*$&#$%&1!7H
_
_
1hls safely desLroys Lhe currenL body. Powever, you may wanL Lo call a game funcLlon LhaL may desLroy
mulLlple bodles. ln Lhls case you need Lo be very careful. 1he soluLlon ls appllcaLlon speclflc, buL for
convenlence l'll show one meLhod of solvlng Lhe problem.
!"#$%&' 3$%. G E&)$*+%JKD.0#$%&h94017H
L@9+. 13$%.7
[
!"#$%&' ! G 3$%.H
3$%. G 3$%.JKD.0g.=017H

D/E.F20$*' E&F20$* G 1D/E.F20$*'7!JKD.0q4.*5/0/17H
96 1E&F20$*JKX45./%177
[
!$$+ $0@.*#$%9.45.40*$&.% G D/E.-*/l&#$%&5.40*$&.*1!7H
96 1$0@.*#$%9.45.40*$&.%7
[
3$%. G E&)$*+%JKD.0#$%&h94017H
_
_
_
Cbvlously Lo make Lhls work, CameCrazy8odyuesLroyer musL be honesL abouL whaL lL has desLroyed.
22@@ \.&'0&7
SomeLlmes you wanL Lo deLermlne all Lhe shapes ln a reglon. 1he b2World class has a fasL log(n) meLhod
for Lhls uslng Lhe broad-phase daLa sLrucLure. ?ou provlde an AA88 ln world coordlnaLes and an
lmplemenLaLlon of b2CueryCallback. 1he world calls your class wlLh each flxLure whose AA88 overlaps
Lhe query AA88. 8eLurn Lrue Lo conLlnue Lhe query, oLherwlse reLurn false. lor example, Lhe followlng
code flnds all Lhe flxLures LhaL poLenLlally lnLersecL a speclfled AA88 and wakes up all of Lhe assoclaLed
bodles.
2+/44 k&s>.*&-/++!/2n , A>!+92 !"s>.*&-/++!/2n
[
A>!+92,
!$$+ i.A$*0<9=0>*.1!"<9=0>*.' 69=0>*.7
[
!"#$%&' !$%& G 69=0>*.JKD.0#$%&17H
!$%&JK?.0FL/n.10*>.7H

VV i.0>*3 0*>. 0$ 2$3093>. 0@. m>.*&I
*.0>*3 0*>.H
_
_H

III

k&s>.*&-/++!/2n 2/++!/2nH
!"FF## //!!H
//!!I+$L.*#$>3%I?.01JQIP6B JQIP67H
//!!I>AA.*#$>3%I?.01QIP6B QIP67H
E&)$*+%JKs>.*&1M2/++!/2nB //!!7H
?ou cannoL make any assumpLlons abouL Lhe order of Lhe callbacks.
>#M !#7%7
?ou can use ray casLs Lo do llne-of-slghL checks, flre guns, eLc. ?ou perform a ray casL by lmplemenLlng a
callback class and provldlng Lhe sLarL and end polnLs. 1he world class calls your class wlLh each flxLure hlL
by Lhe ray. ?our callback ls provlded wlLh Lhe flxLure, Lhe polnL of lnLersecLlon, Lhe unlL normal vecLor,
and Lhe fracLlonal dlsLance along Lhe ray. ?ou cannoL make any assumpLlons abouL Lhe order of Lhe
callbacks.
?ou conLrol Lhe conLlnuaLlon of Lhe ray casL by reLurnlng a fracLlon. 8eLurnlng a fracLlon of zero lndlcaLes
Lhe ray casL should be LermlnaLed. A fracLlon of one lndlcaLes Lhe ray casL should conLlnue as lf no hlL
occurred. lf you reLurn Lhe fracLlon from Lhe argumenL llsL, Lhe ray wlll be cllpped Lo Lhe currenL
lnLersecLlon polnL. So you can ray casL any shape, ray casL all shapes, or ray casL Lhe closesL shape by
reLurnlng Lhe approprlaLe fracLlon.
?ou may also reLurn of fracLlon of -1 Lo fllLer Lhe flxLure. 1hen Lhe ray casL wlll proceed as lf Lhe flxLure
does noL exlsL.
Pere ls an example:
VV b@94 2+/44 2/A0>*.4 0@. 2+$4.40 @90 4@/A.I
2+/44 k&i/&-/40-/++!/2n , A>!+92 !"i/&-/40-/++!/2n
[
A>!+92,
k&i/&-/40-/++!/2n17
[
ET69=0>*. G gqhhH
_

6+$/0C" i.A$*0<9=0>*.1!"<9=0>*.' 69=0>*.B 2$340 !"N.2"M A$930B
2$340 !"N.2"M 3$*E/+B 6+$/0C" 6*/209$37
[
ET69=0>*. G 69=0>*.H
ETA$930 G A$930H
ET3$*E/+ G 3$*E/+H
ET6*/209$3 G 6*/209$3H
*.0>*3 6*/209$3H
_

!"<9=0>*.' ET69=0>*.H
!"N.2" ETA$930H
!"N.2" ET3$*E/+H
6+$/0C" ET6*/209$3H
_H

k&i/&-/40-/++!/2n 2/++!/2nH
!"N.2" A$930Q1JQIP6B PIP67H
!"N.2" A$930"1CIP6B QIP67H
E&)$*+%JKi/&-/401M2/++!/2nB A$930QB A$930"7H

!"#$%&'
uue Lo round-off errors, ray casLs can sneak Lhrough small cracks beLween
polygons ln your sLaLlc envlronmenL. lf Lhls ls noL accepLable ln your appllcaLlon,
please enlarge your polygons sllghLly.

:$9% ?.0h93./*N.+$290&12$340 !"N.2"M :7H
!"N.2" D.0h93./*N.+$290&17 2$340H
:$9% ?.0F3O>+/*N.+$290&16+$/0C" $E.O/7H
6+$/0C" D.0F3O>+/*N.+$290&17 2$340H
<,'/&7 #+- *N$.:7&7
?ou can apply forces, Lorques, and lmpulses Lo a body. When you apply a force or an lmpulse, you
provlde a world polnL where Lhe load ls applled. 1hls ofLen resulLs ln a Lorque abouL Lhe cenLer of mass.
:$9% FAA+&<$*2.12$340 !"N.2"M 6$*2.B 2$340 !"N.2"M A$9307H
:$9% FAA+&b$*m>.16+$/0C" 0$*m>.7H
:$9% FAA+&h93./*XEA>+4.12$340 !"N.2"M 9EA>+4.B 2$340 !"N.2"M A$9307H
:$9% FAA+&F3O>+/*XEA>+4.16+$/0C" 9EA>+4.7H
Applylng a force, Lorque, or lmpulse wakes Lhe body. SomeLlmes Lhls ls undeslrable. lor example, you
may be applylng a sLeady force and wanL Lo allow Lhe body Lo sleep Lo lmprove performance. ln Lhls
case you can use Lhe followlng code.
96 1E&#$%&JKX4FL/n.17 GG 0*>.7
[
E&#$%&JKFAA+&<$*2.1E&<$*2.B E&R$9307H
_
!,,'-0+#%& R'#+7G,'N#%0,+7
1he body class has some uLlllLy funcLlons Lo help you Lransform polnLs and vecLors beLween local and
world space. lf you don'L undersLand Lhese concepLs, please read "LssenLlal MaLhemaLlcs for Cames and
lnLeracLlve AppllcaLlons" by !lm van verLh and Lars 8lshop. 1hese funcLlons are efflclenL (when lnllned).
!"N.2" D.0)$*+%R$93012$340 !"N.2"M +$2/+R$9307H
!"N.2" D.0)$*+%N.20$*12$340 !"N.2"M +$2/+N.20$*7H
!"N.2" D.0h$2/+R$93012$340 !"N.2"M L$*+%R$9307H
!"N.2" D.0h$2/+N.20$*12$340 !"N.2"M L$*+%N.20$*7H
[07%7
?ou can lLeraLe over a body's flxLures. 1hls ls malnly useful lf you need Lo access Lhe flxLure's user daLa.
6$* 1!"<9=0>*.' 6 G !$%&JKD.0<9=0>*.h94017H 6H 6 G 6JKD.0g.=0177
[
k&<9=0>*.5/0/' %/0/ G 1k&<9=0>*.5/0/'76JKD.0q4.*5/0/17H
III %$ 4$E.0@93O L90@ %/0/ III
_
?ou can slmllarly lLeraLe over Lhe body's [olnL llsL.
1he body also provldes a llsL of assoclaLed conLacLs. ?ou can use Lhls Lo geL lnformaLlon abouL Lhe
currenL conLacLs. 8e careful, because Lhe conLacL llsL may noL conLaln all Lhe conLacLs LhaL exlsLed durlng
Lhe prevlous Llme sLep.

!"#$%&' )) [,,7& U+-7
))1) *N$:0/0% F&7%'./%0,+
8ox2u doesn'L use reference counLlng. So lf you desLroy a body lL ls really gone. Accesslng a polnLer Lo a
desLroyed body has undeflned behavlor. ln oLher words, your program wlll llkely crash and burn. 1o help
flx Lhese problems, Lhe debug bulld memory manager fllls desLroyed enLlLles wlLh lulululu. 1hls can
help flnd problems more easlly ln some cases.
lf you desLroy a 8ox2u enLlLy, lL ls up Lo you Lo make sure you remove all references Lo Lhe desLroyed
ob[ecL. 1hls ls easy lf you only have a slngle reference Lo Lhe enLlLy. lf you have mulLlple references, you
mlghL conslder lmplemenLlng a handle class Lo wrap Lhe raw polnLer.
CfLen when uslng 8ox2u you wlll creaLe and desLroy many bodles, shapes, and [olnLs. Managlng Lhese
enLlLles ls somewhaL auLomaLed by 8ox2u. lf you desLroy a body Lhen all assoclaLed shapes and [olnLs
are auLomaLlcally desLroyed. 1hls ls called lmpllclL desLrucLlon.
When you desLroy a body, all lLs aLLached shapes, [olnLs, and conLacLs are desLroyed. 1hls ls called
lmpllclL desLrucLlon. Any body connecLed Lo one of Lhose [olnLs and/or conLacLs ls woken. 1hls process ls
usually convenlenL. Powever, you musL be aware of one cruclal lssue:
!"#$%&'
When a body ls desLroyed, all flxLures and [olnLs aLLached Lo Lhe body are
auLomaLlcally desLroyed. ?ou musL nulllfy any polnLers you have Lo Lhose shapes
and [olnLs. CLherwlse, your program wlll dle horrlbly lf you Lry Lo access or desLroy
Lhose shapes or [olnLs laLer.
1o help you nulllfy your [olnL polnLers, 8ox2u provldes a llsLener class named b2uesLrucLlonLlsLener LhaL
you can lmplemenL and provlde Lo your world ob[ecL. 1hen Lhe world ob[ecL wlll noLlfy you when a [olnL
ls golng Lo be lmpllclLly desLroyed
noLe LhaL Lhere no noLlflcaLlon when a [olnL or flxLure ls expllclLly desLroyed. ln Lhls case ownershlp ls
clear and you can perform Lhe necessary cleanup on Lhe spoL. lf you llke, you can call your own
lmplemenLaLlon of b2uesLrucLlonLlsLener Lo keep cleanup code cenLrallzed.
lmpllclL desLrucLlon ls a greaL convenlence ln many cases. lL can also make your program fall aparL. ?ou
may sLore polnLers Lo shapes and [olnLs somewhere ln your code. 1hese polnLers become orphaned
when an assoclaLed body ls desLroyed. 1he slLuaLlon becomes worse when you conslder LhaL [olnLs are
ofLen creaLed by a parL of Lhe code unrelaLed Lo managemenL of Lhe assoclaLed body. lor example, Lhe
LesLbed creaLes a b2Mouse!olnL for lnLeracLlve manlpulaLlon of bodles on Lhe screen.
8ox2u provldes a callback mechanlsm Lo lnform your appllcaLlon when lmpllclL desLrucLlon occurs. 1hls
glves your appllcaLlon a chance Lo nulllfy Lhe orphaned polnLers. 1hls callback mechanlsm ls descrlbed
laLer ln Lhls manual.
?ou can lmplemenL a b2uesLrucLlonLlsLener LhaL allows b2World Lo lnform you when a shape or [olnL ls
lmpllclLly desLroyed because an assoclaLed body was desLroyed. 1hls wlll help prevenL your code from
accesslng orphaned polnLers.
2+/44 k&5.40*>209$3h940.3.* , A>!+92 !"5.40*>209$3h940.3.*
[
:$9% ?/&D$$%!&.1!"8$930' ;$9307
[
VV *.E$:. /++ *.6.*.32.4 0$ ;$930I
_
_H
?ou can Lhen reglsLer an lnsLance of your desLrucLlon llsLener wlLh your world ob[ecL. ?ou should do Lhls
durlng world lnlLlallzaLlon.
E&)$*+%JK?.0h940.3.*1E&5.40*>209$3h940.3.*7H
!"#$%&' )4 F&3.? F'#S0+?
?ou can lmplemenL Lhe b2uebuguraw class Lo geL deLalled drawlng of Lhe physlcs world. Pere are Lhe
avallable enLlLles:
shape ouLllnes
[olnL connecLlvlLy
broad-phase axls-allgned boundlng boxes (AA88s)
cenLer of mass

1hls ls Lhe preferred meLhod of drawlng Lhese physlcs enLlLles, raLher Lhan accesslng Lhe daLa dlrecLly.
1he reason ls LhaL much of Lhe necessary daLa ls lnLernal and sub[ecL Lo change.
1he LesLbed draws physlcs enLlLles uslng Lhe debug draw faclllLy and Lhe conLacL llsLener, so lL serves as
Lhe prlmary example of how Lo lmplemenL debug drawlng as well as how Lo draw conLacL polnLs.
!"#$%&' )8 [0N0%#%0,+7
8ox2u uses several approxlmaLlons Lo slmulaLe rlgld body physlcs efflclenLly. 1hls brlngs some
llmlLaLlons.
Pere are Lhe currenL llmlLaLlons:
1. SLacklng heavy bodles on Lop of much llghLer bodles ls noL sLable. SLablllLy degrades as Lhe mass
raLlo passes 10:1.
2. Chalns of bodles connecLed by [olnLs may sLreLch lf a llghLer body ls supporLlng a heavler body.
lor example, a wrecklng ball connecL Lo a chaln of llghL welghL bodles may noL be sLable.
SLablllLy degrades as Lhe mass raLlo passes 10:1.
3. 1here ls Lyplcally around 0.3cm of slop ln shape versus shape colllslon.
4. ConLlnuous colllslon does noL handle [olnLs. So you may see [olnL sLreLchlng on fasL movlng
ob[ecLs.
3. 8ox2u uses Lhe symplecLlc Luler lnLegraLlon scheme. lL does noL reproduce parabollc moLlon of
pro[ecLlles and has only flrsL-order accuracy. Powever lL ls fasL and has good sLablllLy.
6. 8ox2u uses an lLeraLlve solver Lo provlde real-Llme performance. ?ou wlll noL geL preclsely rlgld
colllslons or plxel perfecL accuracy. lncreaslng Lhe lLeraLlons wlll lmprove accuracy.
!"#$%&' ); >&G&'&+/&7
Erin Cattos GDC Tutorials: hLLp://code.google.com/p/box2d/downloads/llsL
Colllslon ueLecLlon ln lnLeracLlve 3u LnvlronmenLs, Clno van den 8ergen, 2004
8eal-1lme Colllslon ueLecLlon, ChrlsLer Lrlcson, 2003