+ BulletML is the Bullet Markup Language. BulletML can describe + the barrage of bullets in shooting games. (For example + Progear, Psyvariar, Gigawing2, G DARIUS, XEVIOUS, ...) This + module parses and executes BulletML scripts in + Python. All data + structures in it are renderer-agnostic. A sample renderer for + Pygame is included. The full + API documentation is contained in its Python docstrings. +
+-
+
- git clone + http://git.yukkurigames.com/python-bulletml.git +
+ More information about BulletML is available at + the + BulletML homepage. +
+
+ In addition to the standard BulletML XML format, this module
+ supports an equivalent YAML format. For convenience, two
+ simple collision routines are provided,
+ bulletml.overlaps
for stationary circles and
+ bulletml.collides
for moving circles.
+
API Example
+from bulletml import Bullet, BulletML
+
+doc = BulletML.FromDocument(open("test.xml", "rU"))
+player = ... # On your own here, but it needs x and y fields.
+rank = 0.5 # Player difficulty, 0 to 1
+
+bullet = Bullet.FromDocument(doc, x, y, target=player, rank=rank)
+bullets = [bullet]
+...
+for bullet in bullets:
+ bullets.extend(bullet.step()) # step() returns new Bullets
+...
+
+ For drawing, you're on your own, but Bullet
+ instances have a number of attributes that can be used to
+ influence it.
+
BulletYAML
++ BulletYAML is a translation of BulletML into YAML. The + structure is mostly the same as the XML version, except + BulletRef/FireRef/ActionRef elements are only used if they + contain parameters, as YAML has its own intra-document + references. Parameterless references are turned into direct + YAML references. +
++ If PyYAML is installed, + importing this module automatically registers BulletYAML tags + with the default loader and dumper. +
+YAML Example
+!BulletML
+ type: vertical
+ actions:
+ - !ActionDef
+ actions:
+ - !FireDef
+ bullet: !BulletDef {}
+ FAQ
+-
+
- Can I use bulletml with pyglet / PyOGRE / Panda3d / etc? +
- + Yes. BulletML works on abstract data structures that have + x/y/speed/direction fields. Depending on your renderer, you + can either use these directly to render, or feed the + simulation data output by BulletML into a physics controller + or scenegraph. + +
- What Python version is required? +
- + Python 2.6 or later is required; this includes 3.x (although + the sample runner will not work without a functional Pygame + for Python 3). + +
- How stable is the API? +
- + As of version 2, I expect the API to be stable enough to use + for your game, including adding new kinds of actions or + subclassing Bullet. However, I still recommend including the + entire module with your game if possible. + +
- How fast is is the module? +
- + This depends on what features you are using. There used to + be a table here explaining it, but starting in version 2 it + varies even more depending on the bullet definition used. If + you're stuck with pure-Python collision detection and no + Pysco, you might get as low as 100 per frame; if you've got + _collision.so and Psyco available, you can get over 2000. + + +
- + My BulletML file doesn't load / play correctly in this module! + +
- + Send us an email and attach your script. + + +
- My BulletML plays fine in this module, but nowhere else! +
- + This module has several major extensions to the BulletML + format, as well as a much more lax parser. If you're using + the extensions you're probably SOL, but you may just need to + clean up your XML elements a bit. + +
- Can I output BulletML? +
- + No. Some data about the XML structure is lost in the loading + process. You can output BulletYAML however, or anything else + supporting the standard Python serialization interface. + +
Spec Deviations
+-
+
- XML Validation +
- + This module does absolutely no XML validation. Element order + doesn't matter, unknown elements are completely ignored, and + when duplicate elements are found the most-recently-parsed + one is used. + +
- Direction Frame Counts +
-
+ The BulletML reference implementation contains code which
+ makes a
changeDirection
element with a term of + 1 do nothing. In this implementation, it causes a change of + direction during the next frame. This change had no effect + on the reference samples. Kenta Cho has confirmed this is a + bug in the reference implementation. +
+ - Firing Speed +
+ The reference implementation, when creating a bullet with +
<speed type="relative">
, uses the previous + fire speed, and not the source bullet's speed. This module + instead uses the speed of the source bullet for relative, + and the previous fire speed for sequence. This change had no + effect on the reference samples. Kenta Cho has confirmed + this is a bug in the reference implementation. +
+
Extensions
+
+ This module contains some extensions to the BulletML
+ element set. These use a separate XML namespace,
+ http://code.google.com/p/python-bulletml/
. Sample
+ documents that use them begin as follows:
+
<bulletml xmlns="http://www.asahi-net.or.jp/~cs8k-cyu/bulletml"
+ xmlns:py="http://code.google.com/p/python-bulletml/">
+ + These extensions do make your document invalid BulletML, and + they may not parse correctly in other parsers. (For example, + the reference implementation applet will not read them.) +
+-
+
- 0 frame times +
+ The reference applet does not correctly handle +
changeDirection
,changeSpeed
, or + accel elements if they have terms of 0 (it ends up dividing + by zero). This module instead applies the change immediately + if the type is relative, absolute, or aim, and does nothing + if the type is sequence. A0 in the reference + applet and in this implementation behave the same - it stops + evaluation of the action immediately, but advances it again + next frame (as opposed to 1, which stops it immediately, + waits the next, then advances the next). +
+ - <offset> - within <fire> +
-
+
-
+
- Attribute
- label - STRING +
- Contents
- x?, y? +
- Example +
<offset type="absolute"> + <x>$rand*3</x> + <y>-5</y> +</offset>
+
+ The <offset> element can be used to give a positional + offset to a newly-fired bullet. Normally, bullets appear + at the same location as their parent bullet. Using offset, + these can either be moved around in absolute space, or + relative to the parent's direction. +
++ When using a relative direction, positive x is to the + "right" of the source's facing, and positive y is "in + front of" the source. +
+
+ - <tag> and <untag> - within <action> +
-
+
-
+
- Contents
- STRING +
- Example +
<action> + <tag>new</tag> + <wait>20</wait> + <untag>new</untag> +</action>
+
+ <tag> sets a simple string tag on the bullet running this + action. <untag> removes a tag. Setting the same tag twice + or trying to remove a tag that is not set has no effect. +
++ Bullet tags are implemented as Python set object in the tags + attribute of the Bullet class. +
+
+ - <appearance> within <action> +
-
+
-
+
- Contents
- STRING +
- Example +
- <appearance>pewpew</appearance> +
+ <appearance> sets the appearance attribute on the + Bullet instance. The effect of this is game-dependent, but + the intended use is to set a texture, color, or animation + sequence for the bullet. +
+
+ - + <tag> and <appearance> within <bullet> and <fire> + +
- + Like <action>, <bullet> and <fire> can contain + <tag> and <appearance> elements. This causes the + bullet to be created with those tags and an appearance + already set. + +
- <if>, <cond>, <then>, <else> +
-
+
-
+
- Contents +
-
+ <cond>STRING</cond>
+ <then>action | actionRef</then>
+ [ <else>action | actionRef</else> ] +
+
+ Conditional actions are supported. These have one of two + forms: +
+
+<!-- Fire a bullet 70% of the time. --> +<if><cond>$rand > 0.3</cond> + <then><fire><bullet/></fire></then> +</if> + +<!-- Randomly fire red or blue bullets. --> +<if><cond>$rand > 0.5</cond> + <then><fire> + <bullet/><appearance>red</appearance> + </fire></then> + <else><fire> + <bullet/><appearance>blue</appearance> + </fire></else> +</if>
+ If the conditional has no else branch, execution proceeds + immediately to the next instruction of the action + containing the conditional. Otherwise, as <action>, + <repeat>, etc., the first step of the subaction is + executed. +
+
+
License
++ All example BulletML files in the examples folder are released + into the public domain. The BulletML specification is the work + of Kenta Cho. +
++ Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated + documentation files (the "Software"), to deal in the + Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, + sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, + provided the above copyright notice and this permission + notice shall be included in all copies or substantial + portions of the Software. +
+