Manual de Box2D en Español

Box2D v2.2.0 manual de usuario Copyright © 2007 – 2011 Erin Catto Tradui!n por "aros Barrios #$urias% © &nlain Entertainment 201' Cap(tulo 1 )ntrodui!n .................................................................................................................... 2 Cap(tulo 2 *ola Box2D .................................................................................................................... + Cap(tulo ' Datos ............................................................................................................................ 1, Cap(tulo , "odulo de olisi!n -.................................................................................................... 1 Cap(tulo / "odulo de dinmias -................................................................................................ 27 Cap(tulo  dornos $ixtures3 $ixtures3 -................................... ........................................ .......................... 2+ Cap(tulo 7 Cuerpos -.................................................................................................................... '2 Cap(tulo + &niones 4oints3 -........................................................................................................ '5 Cap(tulo 5 Contatos -.................................................................................................................. ,+ Cap(tulo 10 6a lase "undo -....................................................................................................... / Cap(tulo 11 $inales sueltos -........................................................................................................ 2 Cap(tulo 12 Diu8ando Diu8ando por depurai!n depurai!n -........................................ ...................................... ......... , Cap(tulo 1' 6imitaiones -............................................................................................................ / Cap(tulo 1, 9e:erenias -............................................................................................................. 

Cap(tulo 1 )ntrodui!n 1.1 ;ore Box2D es una lirer(a para video8uegos de simulai!n de uerpos r(gidos en 2D. 6os programadores pueden utili un motor de :(sias is ?niamente un sistema de animai!n por proedimientos. Box2D est esrito en C++ portale. "uhos de los tipos de:inidos en el motor empie
1.2 @rere=uisitos En este manual asumimos =ue estas :amiliari omo la masa> la :uer la rotai!n y los impulsos. ;i no> por :avor onsulta Google y Wikipedia. Box2D ha sido reado omo parte de un tutorial de :(sias en la Conferencia de Desarrollo de Videojuegos. @uedes onseguir los tutoriales en la sei!n de desargas de ox2d.org. Como Box2D est esrito en C++> deer(as tener experienia en la programai!n on C++. Box2 D no dee ser tu primer proyeto en C++. Deer(as estar omodo on la ompilai!n> la vinulai!n y la depurai!n ompiling> linAing and deugging en )ngls3. Advertencia

Box2D no debe ser tu primer proyecto C++. Por favor, aprende programación con C++, compilación, vinculación y depuración antes de empezar a trabajar con Box2D. Hay mucos recursos para esto en internet.

1.' ;ore este manual Este manual inluye la mayor(a de la  API  Application Programming Interface3 o IPA Interfa de  programaci!n de aplicaciones3. un=ue no todos los aspetos estn inluidos. Ests invitado a mirar el test"ed# inluido on Box2D para aprender ms. demas> el !digo ase de Box2D tiene omentarios generados por Dox$gen> por lo =ue es :il rear un doumento on un hypervinulo haia la IPA. Diccionario

Testbed: !banco de pruebas en espa"ol# $n Testbed  es una plataforma para experimentación de proyectos de

gran desarrollo. Doxygen: %s un generador de documentación para C++, C ,  Java, Objetive-C , Python, IDL !versiones Corba y Microsoft #, VHDL y en cierta medida para PHP, C#  y D.

Este manual solo es atuali
1., $eedaA y reporte de errores ;i tienes alguna pregunta o :eedaA sore Box2D> por :avor de8a un omentario en el :oro. a =ue tamin es un gran lugar para disutir.

6os errores de Box2D son puliados usando un proyeto de Google ode. Es una uena manera de puliar errores y asegurarse de =ue tu error no se va a perder en las pro:undidades de los :oros.

Por favor, los arcivos con errores y las solicitudes de ediciones van a&u'( http://code.google.com/p/box2d @uedes ayudar a asegurar =ue tus errores se soluionan si proporionas su:iientes detalles. 6o ideal es =ue proporiones un test"ed   =ue reprodu<a el prolema. @uedes leer sore los ?ltimos test"ed  en este doumento.

1./ Coneptos prinipales Box2D traa8a on varios o8etos :undamentales.  ontinuai!n vamos a de:inir dihos o8etos y a dar ms detalles sore ellos.

Forma (Shape) Es una :orma geomtria en 2D. &n e8emplo de ella es un (rulo o un pol(gono.

Cuerpo rígido (Rigid body) Es un peda
Adorno (Fixture) &n adorno de:ine la :orma de un uerpo y le aade propiedades de material omo la densidad> la :rii!n y la restitui!n.

Limitación (Constraint) &na limitai!n es una onexi!n :(sia =ue elimina el movimiento lire de los uerpos r(gidos.

Limitación de contacto (Contact constraint) Es una limitai!n espeial diseada para prevenir la penetrai!n de uerpos r(gidos y simular :rii!n y restitui!n. o es neesario rear una> ya =ue son reados automtiamente por Box2D.

Unión (Joint) Es una limitai!n usada para tener dos o ms uerpos 8untos. Box2D  soporta varios tipos de unionesF %e&olute gira en torno a algo3> Prismatic por e8emplo unir dos o8etos simulando una uerda3> Distance limita la distania de un o8eto :rente a otro3 y ms.

Límite de unión (Joint imit) &na limitai!n de uni!n restringe el rango de poder de una limitai!n. @or e8emplo> la rodilla humana permite un determinado rango de ngulos> por lo =ue se podr(a simular utili
!otor de unión(Joint motor) &n motor de uni!n es =uien de:ine el movimiento de los uerpos onetados de auerdo a los grados de limitai!n de liertad =ue tienen. @or e8emplo> puedes usar un motor para de:inir la rotai!n de una rodilla.

!undo ("ord) &n mundo :(sio es una olei!n de uerpos> adornos y l(mites =ue interat?an entre s(. Box2D soporta la reai!n de m?ltiples mundos a la ve<> pero usualmente no es neesario> ya =ue hay poos video8uegos =ue haen uso de esta arater(stia.

Soucionador (So#er) 6as :(sias de un mundo tienen un soluionador =ue es utili donde  es el n?mero de limitaiones.

Coisión continua (continuous coision) Graias al soluionador solver3> los o8etos amian de posii!n dependiendo del tiempo =ue pasa. Esto puede llevar a la tuneli
Box2D ontiene algoritmos espeiali el algoritmo de la olisi!n puede interpolar el movimiento de dos uerpos para enontrar el primer tiempo de impato. En segundo lugar un soluionador mueve los uerpos al primer tiempo de impato y resuelve la olisi!n.

1. "!dulos Box2D est ompuesto por tres m!dulosF Common> Colisi!n y Dinmias. El m!dulo Common tiene !digo para asignai!n> matemtias y on:iguraiones. El m!dulo de olisi!n de:ine las :ormas> una amplia etapa y :unionesHpreguntas de olisi!n.  :inalmente el m!dulo de dinmias distriuye la simulai!n de mundo> uerpos> adornos y uniones Iorld> odies> :ixtures and 8oints3.

1.7 &nidades Box2D traa8a on n?meros on oma :lotante y los asentimientos tienen =ue ser usados para onseguir =ue el rendimiento de Box2D sea ueno. Estos asentimientos tienen =ue ser a8ustados para traa8ar on las unidades metrosJAilogramoJsegundo '()3. En partiular> Box2D  tiene =ue ser a8ustado para traa8ar ien on el movimiento de o8etos entre 0.1 y 10 metros. 6os o8etos esttios pueden reiir una :uer
o!"D est) ajustado para las unidades M$!Metros-%i&o'ra(os-se')ndos#. *uarda el tama"o del movimiento

de los objetos aproximadamente entre +. y + metros. -as a necesitar usar algn sistema de escala cuando vayas a renderizar el entorno y los actores !actors#. %l anco de trabajo ! testbed # de o!"D ace esto usando una transformación del vie,ort . /0 $1%1 P3%4%1. Diccionario

Viewport: %l vie,ort   es la zona rectangular donde se muestra parte de una escena renderizada en tu

videojuego. Es me8or pensar =ue sore los uerpos de Box2D se mueve una valla =ue tiene aopladas las imgenes de tu video8uego. 6a valla podr(a moverse en un sistema de unidades de metros> pero puedes onvertirla a oordenadas de p(xeles on un simple :ator de esala. @uedes usar a=uellas oordenadas de p(xeles para poner tus sprites> et. Box2D usa radians para los ngulos. 6a rotai!n del uerpo es almaenada en radians por lo =ue podr(a reer de manera ilimitada. Considerando normalmente el angulo de tus uerpos >si la magnitud del angulo se hae demasiado grande podemos usar 2BodyFF;etngle.

1.+ $atores y de:iniiones 6a gesti!n de memoria 8ug! un importante papel en el diseo de la IPA o  API   en )ngls3 de Box2D. s( =ue uando reas un 2Body o un 24oint> neesitas llamar las :uniones en 2Korld. o deer(as intentar nuna asignar estos tipos de otra manera. *ay :uniones de reai!n b2Body* b2World::CreateBody(const b2BodyDef* def) b2Joint* b2World::CreateJoint(const b2JointDef* def)

 tamin estn sus orrespondientes :uniones de destrui!nF void b2World::DestroyBody(b2Body* body) void b2World::DestroyJoint(b2Joint* joint)

Cuando reas un uerpo o una uni!n> neesitas poner una de:inii!n. Estas de:iniiones ontienen toda la in:ormai!n neesitada para onstruir el uerpo o la uni!n. ;i usamos este mtodo evitaremos errores> mantener pe=ueos los n?meros de los parmetros de la :uni!n proporiona predeterminados sensiles y redue el n?mero de aededores. @uesto =ue los adornos tienen =ue ser reados por un uerpo> son reados y destro
b2Fixture* b2Body::CreateFixture(const b2FixtureDef* def) void b2Body::DestroyFixture(b2Fixture* fixture)

Tamin hay una manera rpida de rear un adorno diretamente desde la :orma y la densidad. b2Fixture* b2Body::CreateFixture(const b2Sa!e* sa!e" float#2 density)

6os :atores no retienen las re:erenias a las de:iniiones. un=ue puedes rear de:iniiones en la pila y mantenerlas en reursos temporales.

1.5 Datos de usuario 6as lases 2$ixture> 2Body y 24oint te permiten vinular datos de usuario utili es t(pio rear una :uni!n para vinular un ator al uerpo r(gido en diho ator. Graias a esto se onsigue total ontrol sore los elementos vinulados. ;i tienes el ator> puedes onseguir el uerpo. ;i tienes el uerpo> puedes onseguir el ator. $a%e&ctor* actor ' $a%eCreate&ctor() b2BodyDef bodyDef bodyDefuserData ' actor actor+body ' box2D,orld+CreateBody(-bodyDef)

 =u( hay algunos e8emplos de asos donde tu pre:erirs utili
Causando dao a un ator utili
"antener en medio los datos de usuario es opional y puedes poner lo =ue =uieras en llos. De todas maneras> deer(as ser onstante. @or e8emplo> si =uieres almaenar un puntero de un ator en un uerpo> deer(as mantener un puntero de ator en todos los uerpos. o almaenes un puntero de ator en un solo uerpo y un puntero L> ya =ue se te podr(a rashear el 8uego.

Cap(tulo 2 *ola Box2D Cuando desargas Box2D te viene un proyeto llamado *ello World . En ese mismo proyeto hay reado un largo retngulo o a8a> omo =ueris3 simulando el suelo y enima de este otra a8a dinmia. El !digo de este no ontiene ninguna imagen. Todo lo =ue vas a ver es texto en la onsola =ue india la posii!n de las a8as. El programa del proyeto es un uen e8emplo de omo empe
2.1 Creando el mundo Todos los proyetos de Box2D empie en este asi un 2Korld. El o8eto 2Korld es el n?leo de la gesti!n de memoria> o8etos y simulai!n> por lo =ue si no tenemos este o8eto no podremos rear nada. @uedes poner el mundo :(sio en la pila de variales o en la sei!n de datos.

Es :il rear un mundo de Box2D. 6o primero =ue tenemos =ue haer es de:inir la gravedad =ue har dentro del mundo> esto es neesario haerlo usando un vetor. Tamin tendremos =ue indiar si =ueremos =ue los uerpos puedan estar en reposo. Cuando un uerpo est en reposo no re=uiere de ning?n tipo de simulai!n. b2.ec2 /ravity(00f" 100f) bool doSlee! ' true

  ontinuai!n vamos a rear el mundo. $(8ate =ue estamos reando el mundo en la pila de variales> por lo =ue podremos aeder a la variale desde ual=uier lugar de la lase. b2World ,orld(/ravity" doSlee!)

 hora =ue hemos reado el mundo podremos empe
2.2 Creando el suelo  ntes de rear el suelo> deeremos saer =ue para rear un uerpo tenemos =ue seguir estos pasosF 1. 2. '. ,.

De:inir la posii!n> el tipo de uerpo > et. &tili su :rii!n> su densidad> ettera. Crear los adornos en el uerpo.

@ara el primer paso rearemos el uerpo =ue ser el suelo. @ara haer esto neesitamos una de:inii!n del uerpo> on esa de:inii!n espei:iaremos la posii!n iniial del uerpo. b2BodyDef /roundBodyDef /roundBodyDef!ositionSet(00f" 100f)

En segundo lugar neesitaremos pasar la de:inii!n del uerpo al mundo para =ue lo ree. 6os uerpos son esttios por de:eto> as( =ue si no de:inimos el tipo de uerpo siempre ser esttio. 6os uerpos esttios no olisionan on otros uerpos del mismo tipo esttios3 y no se pueden mover. b2Body* /roundBody ' ,orldCreateBody(-/roundBodyDef)

En terer lugar rearemos la :orma del suelo> usaremos un pol(gono para onseguir =ue el suelo sea un retngulo. @ara onseguir =ue sea un retngulo simplemente usaremos el mtodo ;etsBox. b2oly/onSa!e /roundBox /roundBoxSet&sBox(300f" 100f)

6a :uni!n ;etsBox neesita dos valoresM lo anho =ue va a ser el retngulo y lo alto. En este aso el retngulo tendr 100 unidades de anho y 20 unidades de alto. @uedes poner estas unidades en metros> ya =ue generalmente Box2D traa8a me8or uando el tamao de los o8etos es el mismo =ue el de los o8etos reales. @or e8emplo> un arril est sore el metro de altura. Deido a las limitaiones del algoritmo de la oma :lotante> no es una uena idea utili
materia ustomi por lo =ue no usaremos al densidad en este aso. /roundBody+CreateFixture(-/roundBox" 00f)

Box2D no mantiene la re:erenia de la :orma> simplemente lona los datos dentro de una nueva :orma. Tienes =ue saer =ue todos los adornos tienen =ue tener un uerpo> inluso los adornos =ue son esttios tienen =ue tener un uerpo. un=ue de todas maneras puedes vinular todos los adornos esttios a un solo uerpo esttio.

2.' Creando un uerpo dinmio  hora =ue tenemos suelo> podemos usar la misma tnia para rear uerpos dinmios. 6a prinipal di:erenia> adems de las dimensiones> es =ue tenemos =ue de:inir las propiedades de masa del uerpo. Como por e8emplo la densidad> la :rii!n y la restitui!n. @rimero reamos el uerpo usando CreateBody. @or de:eto los uerpos son esttios> por lo =ue deer(amos amiar el 2BodyType a dinmio. b2BodyDef bodyDef bodyDefty!e ' b24dyna%icBody bodyDef!ositionSet(00f" 50f) b2Body* body ' ,orldCreateBody(-bodyDef) Advertencia

5ienes &ue cambiar el tipo de cuerpo a b26dynamicBody si &uieres &ue el cuerpo sea din)mico. El siguiente paso es rear y vinular una :orma poligonal usando la de:inii!n de adorno. @rimero tenemos =ue rear una :orma retangularF b2oly/onSa!e dyna%icBox dyna%icBoxSet&sBox(10f" 10f)

  ontinuai!n reamos la de:inii!n de adorno utili
&sando la de:inii!n de adorno ahora podemos rear el adorno. Esto lo =ue hae es atuali
a estamos listos para empe
2., ;imulando el mundo  hora =ue ya tenemos el suelo y una a8a dinmia ya estamos listos para onseguir aproximarnos a las osas de eIton. ;olo tenemos unos poos prolemas mas =ue a:rontar. Box2D utili pero vas a tener =ue ser ms uidadoso a la hora de de:inir las on:iguraiones para tu mundo. )gualmente no nos gusta amiar el paso del tiempo demasiado. &na variale en el tiempo produe resultados> por lo =ue es ms di:(il de depurar. float#2 ti%eSte! ' 10f 6 700f

 dems> Box2D  tamin usa grandes partes de !digo llamado soluionadores de l(mites. 6os soluionadores de l(mites son los enargados de simular los l(mites> uno a ada segundo. &n solo l(mite puede ser soluionador per:etamente. ;in emargo> uando resolvemos un l(mite> perturamos ligeramente otros l(mites. @ara onseguir una uena soluion> neesitamos trans:ormar todos los l(mites un n?mero de vees. *ay dos etapas en el soluionador de l(mitesF la etapa de la veloidad y la etapa de la posii!n. En la etapa de la veloidad el resolvedor alula los impulsos neesarios para =ue los uerpos se muevan orretamente. En la etapa de la posii!n el resolvedor a8usta la posii!n de los uerpos para reduir la solapai!n de los uerpos y la separai!n de las uniones. Cada etapa tiene un n?mero espe(:io de iteraiones.  para aadir> la etapa de la posii!n podr(a eliminar las iteraiones si los errores son pe=ueos. El atual n?mero de iteraiones para Box2D  son + para veloidad y ' para posii!n. @uedes a8ustar este n?mero omo tu =uieras> solo mantn en medio =ue estn a8ustados entre veloidad y exatitud. &tili no neesitamos muhas iteraiones. =u( est nuestro n?mero elegido de interaiones. int#2 velocity8terations ' 7 int#2 !osition8terations ' 2

Date uenta de =ue el paso del tiempo y el n?mero de interaiones no estn relaionados. &na iterai!n no es un supaso. &n resolvedor de iteraiones es un solo paso por enima de todos los l(miten on el paso del tiempo. @uedes tener varios pasos enima de los l(miten on un solo paso del tiempo.  hora ests listo para el ule de simulai!n. En tu video8uego el ule de simulai!n puede ser ominado on el ule de tu video8uego. En ada paso a travs del ule de tu video8uego puede ser llamado 2KorldFF;tep. ormalmente on llamarlo una ve< es su:iiente> pero depende de tu n?mero de :otogramas por segundo y tu paso del tiempo de las :(sias. El programa *ola "undo ha sido diseado para ser simple> aun=ue no tiene una salida gr:ia. El !digo imprime la posii!n y rotai!n del uerpo dinmio. =u( est el ule de simulaion =ue simula 0 pasos en el tiempo para un total de 1 segundo de tiempo simulado.

for (int#2 i ' 0 i 9 70 i) ; ,orldSte!(ti%eSte!" velocity8terations" !osition8terations) b2.ec2 !osition ' body+$etosition() float#2 an/le ' body+$et&n/le() !rintf(<=52f =52f =52f>n<" !ositionx" !ositiony" an/le) ?

6a salida ensea la a8a ayendo y aterri
2./ 6impie toda la memoria reservada para los uerpos> los adornos y los l(mites es lierada. Esto se hae para onseguir rendimiento y haerte la vida ms :il. ;in emargo> vas a neesitar eliminar un uerpo> adorno o punteros de l(mites =ue tengas por=ue van a onvertirse en invlidos.

2. The Tested &na ve< ontroles el e8emplo *ola "undo> deer(as empe
Camara on on:igurai!n de parmetros y depurar opiones de diu8o