Python BulletML - Yukkuri Games

+ +

+ 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. A 0 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. +

+ 2010 Joe Wreschnig +

+ 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. +