Packagecom.boristhebrave.Box2DWith
Classpublic class b2XML

Contains functions for loading Box2D shapes, bodies and joints from a simple XML format.

The XML format is formally defined in using Relax NG in the file box2d.rng found in the same directory as this class. An XML Schema file is also available, autotranslated by Trang.

Simply stated, the XML format has a root <world/> element. Inside that, there are various body and joint elements, and inside each body element is various shape elements, thus matching Box2Ds design layout quite closely. See the methods loadShapeDef, loadBodyDef, and loadJointDef for the details on how each element is formed.

In general, attribute names match exactly the corresponding Box2D property, and has the same defaults as Box2D. Reasonable values are generated for certain properties when not specified, in the same manner as the various Initialize functions of Box2D. Joint anchors can be specified in either world or local co-ordinates, either single or jointly, though this implementation will not prevent you from overspecifying attributes.

It is expected that in most cases, you will not want to use the XML to fully define worlds using loadWorld, as this library doesn't provide any mechanism for handling other data, such as the appearance of a body. Instead, you can use the various loading functions to synthesize your own XML format containing parts of the Box2D XML specification. Or you can simply use this class as a more consise and portable way of writing out defintions, and deal with defining the world in your own way.

See also

loadShapeDef()
loadBodyDef()
loadJointDef()


Public Methods
 MethodDefined by
  
loadBody(xml:XML, world:b2World, bodyDef:b2BodyDef = null, shapeDef:b2ShapeDef = null):b2Body
[static] Creates a body from a <body/> element with nested shape elementss, using the definitions from loadBodyDef and loadShapeDef.
b2XML
  
loadBodyDef(body:XML, base:b2BodyDef = null):b2BodyDef
[static] Converts a <body/> element into a b2BodyDef.
b2XML
  
loadBool(attribute:XMLList, defacto:Boolean = false):Boolean
[static] Loads a Boolean from a given attribute.
b2XML
  
loadFloat(attribute:XMLList, defacto:Number):Number
[static] Loads a Number from a given attribute.
b2XML
  
loadInt(attribute:XMLList, defacto:int):int
[static] Loads a int from a given attribute.
b2XML
  
loadJointDef(joint:XML, resolver:Function, base:b2JointDef = null):b2JointDef
[static] Converts an XML element into a b2JointDef.
b2XML
  
loadShapeDef(shape:XML, base:b2ShapeDef = null):b2ShapeDef
[static] Converts an XML element into a b2ShapeDef.
b2XML
  
loadVec2(attribute:XMLList, defacto:b2Vec2 = null):b2Vec2
[static] Loads a b2Vec2 from a given attribute.
b2XML
  
loadWorld(xml:XML, world:b2World, bodyDef:b2BodyDef = null, shapeDef:b2ShapeDef = null, jointDef:b2JointDef = null):Function
[static] Loads a world given a XML defintion.
b2XML
Method detail
loadBody()method
public static function loadBody(xml:XML, world:b2World, bodyDef:b2BodyDef = null, shapeDef:b2ShapeDef = null):b2Body

Creates a body from a <body/> element with nested shape elementss, using the definitions from loadBodyDef and loadShapeDef.

Parameters
xml:XML — The <body/> element to parse.
 
world:b2World — The world to create the body from.
 
bodyDef:b2BodyDef (default = null) — The base body definition to use for defaults.
 
shapeDef:b2ShapeDef (default = null) — The base shape definition to use for defaults.

Returns
b2Body — A newly created body in world.

See also

loadBodyDef()method 
public static function loadBodyDef(body:XML, base:b2BodyDef = null):b2BodyDef

Converts a <body/> element into a b2BodyDef.

The following attributes are recognized, corresponding directly to the b2BodyDef properties:

   allowSleep       Boolean
   angle            Number
   angularDamping   Number
   fixedRotation    Boolean
   isBullet         Boolean
   isSleeping       Boolean
   linearDamping    Number
   center           b2Vec2
   I                Number
   mass             Number
   x                Number
   y                Number
   position         b2Vec2
   userData         *  
Parameters
body:XML — An XML element in the above format.
 
base:b2BodyDef (default = null) — A body definition to use as the default when an XML attribute is missing.

Returns
b2BodyDef — The specified b2BodyDef.
loadBool()method 
public static function loadBool(attribute:XMLList, defacto:Boolean = false):Boolean

Loads a Boolean from a given attribute. Only the value "true" is recognized as true. Everything else is false.

Parameters
attribute:XMLList — An attribute list of zero or one attributes to parse into a Boolean.
 
defacto:Boolean (default = false) — The default number to use in case there is no attribute.

Returns
Boolean — The parsed Boolean, or defacto.
loadFloat()method 
public static function loadFloat(attribute:XMLList, defacto:Number):Number

Loads a Number from a given attribute.

Parameters
attribute:XMLList — An attribute list of zero or one attributes to parse into a Number.
 
defacto:Number — The default number to use in case there is no attribute or it is not a valid Number.

Returns
Number — The parsed Number, or defacto.
loadInt()method 
public static function loadInt(attribute:XMLList, defacto:int):int

Loads a int from a given attribute.

Parameters
attribute:XMLList — An attribute list of zero or one attributes to parse into a int.
 
defacto:int — The default number to use in case there is no attribute or it is not a valid int.

Returns
int — The parsed int, or defacto.
loadJointDef()method 
public static function loadJointDef(joint:XML, resolver:Function, base:b2JointDef = null):b2JointDef

Converts an XML element into a b2JointDef.

The following elements and attributes are recognized:

   <gear/>    b2GearJointDef
           ratio           Number
           joint1          String    (resolved)
           joint2          String    (resolved)
   
   <prismatic/> b2PrismaticJointDef
           motorSpeed      Number
           maxMotorForce   Number
           enableMotor     Boolean   (automatically set)
           lower           Number
           upper           Number
           enableLimits    Boolean   (automatically set)
           referenceAngle  Number    (automatically set)
           world-axis      b2Vec2
           local-axis1     b2Vec2
   
   <revolute/>    b2RevoluteJointDef
           motorSpeed      Number
           maxMotorTorque  Number
           enableMotor     Boolean   (automatically set)
           lower           Number
           upper           Number
           enableLimits    Boolean   (automatically set)
           referenceAngle  Number    (automatically set)
   
   <distance/>    b2DistanceJointDef
           dampingRatio    Number
           frequencyHz     Number
           length          Number    (automatically set)
   
   <pulley/> b2PulleyJointDef
           ratio           Number
           maxLength1      Number
           maxLength2      Number
           world-ground    b2Vec2
           world-ground1   b2Vec2
           world-ground2   b2Vec2
           length1         Number    (automatically set)
           length2         Number    (automatically set)
   
   <mouse/>    b2MouseJointDef
           dampingRatio    Number
           frequencyHz     Number
           maxForce        Number
           target          b2Vec2 

Additionally, all elements support the following attributes:

   body1             String          (resolved)
   body2             String          (resolved)
   world-anchor      b2Vec2
   world-anchor1     b2Vec2
   world-anchor2     b2Vec2
   local-anchor1     b2Vec2
   local-anchor2     b2Vec2
   collideConnected  Boolean 

Note that if the joint does not have a well defined body from body1/body2 or via providing base, then world co-ordinates cannot be used, except for the ground anchors of a pulley joint.

Parameters
joint:XML — An XML element in the above format
 
resolver:Function — A function mapping strings to b2Bodys (and b2Joint). This is used so that the body1 and body2 (and joint1 and joint2 from <gear/>) can get resolved to the correct references. You can avoid using this if these properties are not defined, and providing them via base.
 
base:b2JointDef (default = null) — A joint definition to use as the default when an XML attribute is missing.

Returns
b2JointDef — The corresponding b2ShapeDef
loadShapeDef()method 
public static function loadShapeDef(shape:XML, base:b2ShapeDef = null):b2ShapeDef

Converts an XML element into a b2ShapeDef.

The following elements/usages are recognized:

   <circle radius="0." x="0." y="0."/>
        b2CircleDef 
   <circle radius="0." localPosition="0. 0."/>
        b2CircleDef    
   <polygon>
    <vertex x="0." y="0."/>
    <vertex x="0." y="0."/>
    <vertex x="0." y="0."/>
   </polygon>
        b2PolygonDef
   <box x="0." y="0." width="0." height="0." angle="0."/>
        b2PolygonDef formed into an OBB.
   <box left="" right="" top="" bottom=""/>
        b2PolygonDef formed into an AABB.
        height and width can substitute for one of top/bottom and one of left/right.

Additionally, all elements support the following attributes.

   density        float
   friction       float
   isSensor       Boolean
   userData       String
   categoryBits   int
   maskBits       int
   groupIndex     int
Parameters
shape:XML — An XML element in the above format
 
base:b2ShapeDef (default = null) — A shape definition to use as the default when an XML attribute is missing.

Returns
b2ShapeDef — The corresponding b2ShapeDef
loadVec2()method 
public static function loadVec2(attribute:XMLList, defacto:b2Vec2 = null):b2Vec2

Loads a b2Vec2 from a given attribute. Vectors are stored as space delimited Numbers, e.g. "1.5 2.3".

Parameters
attribute:XMLList — An attribute list of zero or one attributes to parse into a b2Vec2.
 
defacto:b2Vec2 (default = null) — The default number to use in case there is no attribute or it is not a valid b2Vec2.

Returns
b2Vec2 — The parsed b2Vec2, or defacto.
loadWorld()method 
public static function loadWorld(xml:XML, world:b2World, bodyDef:b2BodyDef = null, shapeDef:b2ShapeDef = null, jointDef:b2JointDef = null):Function

Loads a world given a XML defintion.

xml is expected to a <world> element with child <body> and joint elements as specified in loadBodyDef and loadShapeDef. <body/> elements should have children shape elements as specified in loadShapeDef.

Both body and joint elements can have an id attribute that gives a string identifier to be later resolved for use with the body1 and body2 attributes of joints, and joint1 and joint2 attribute of gear joints.

Parameters
xml:XML — A element in the above format.
 
world:b2World — A world to load into. Unlike other load functions, this function does not create an object from scratch.
 
bodyDef:b2BodyDef (default = null) — A body definition to use for defaults.
 
shapeDef:b2ShapeDef (default = null) — A shape definition to use for defaults.
 
jointDef:b2JointDef (default = null) — A joint definition to use for defaults.

Returns
Function — A function you can use to resolve the loaded elements, as defined in loadJointDef.

See also