Package | com.boristhebrave.Box2DWith |
Class | public class Box2DXML |
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
Method | Defined 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.
| Box2DXML | ||
loadBodyDef(body:XML, base:b2BodyDef = null):b2BodyDef
[static]
Converts a <body/> element into a b2BodyDef.
| Box2DXML | ||
loadBool(attribute:XMLList, defacto:Boolean = false):Boolean
[static]
Loads a Boolean from a given attribute.
| Box2DXML | ||
loadFloat(attribute:XMLList, defacto:Number):Number
[static]
Loads a Number from a given attribute.
| Box2DXML | ||
loadInt(attribute:XMLList, defacto:int):int
[static]
Loads a int from a given attribute.
| Box2DXML | ||
loadJointDef(joint:XML, resolver:Function, base:b2JointDef = null):b2JointDef
[static]
Converts an XML element into a b2JointDef.
| Box2DXML | ||
loadShapeDef(shape:XML, base:b2ShapeDef = null):b2ShapeDef
[static]
Converts an XML element into a b2ShapeDef.
| Box2DXML | ||
loadVec2(attribute:XMLList, defacto:b2Vec2 = null):b2Vec2
[static]
Loads a b2Vec2 from a given attribute.
| Box2DXML | ||
loadWorld(xml:XML, world:b2World, bodyDef:b2BodyDef = null, shapeDef:b2ShapeDef = null, jointDef:b2JointDef = null):void
[static]
Loads a world given a XML defintion.
| Box2DXML |
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.
Parametersxml: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.
|
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.
|
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.
Parametersattribute: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.
|
Boolean — The parsed Boolean, or defacto.
|
loadFloat | () | method |
public static function loadFloat(attribute:XMLList, defacto:Number):Number
Loads a Number from a given attribute.
Parametersattribute: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.
|
Number — The parsed Number, or defacto.
|
loadInt | () | method |
public static function loadInt(attribute:XMLList, defacto:int):int
Loads a int from a given attribute.
Parametersattribute: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.
|
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.
Parametersjoint: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.
|
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 intParameters
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.
|
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".
Parametersattribute: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.
|
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):void
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.
Parametersxml:XML — A |
|
world:b2World — A world to load into. Unlike other Box2DXMl.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.
|