+<!DOCTYPE html>
+<html>
+ <head>
+ <meta charset="utf-8">
+ <meta name=viewport content="width=device-width, initial-scale=1">
+ <link rel="stylesheet" href="/css/main.css" type="text/css">
+ <title>Python BulletML - Yukkuri Games</title>
+ </head>
+ <body>
+ <header>
+ <a href="/">
+ <img src="/logotype_horizontal_1.png" class=logo alt="(◕ ヮ ◕)">
+ <img src="/logotype_horizontal_2.png" class=optional
+ alt="Yukkuri Games">
+ </a>
+ <h1>Python BulletML</h1>
+ </header>
+ <main>
+ <aside class="important">
+ This project isn't dead, but also isn't actively maintained
+ against current versions of Python and Pygame. Specific
+ problems and requests may be dealt with, but working with it
+ might be rough-going at first.
+ </aside>
+ <p>
+ 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
+ <a href="https://www.python.org/">Python</a>. All data
+ structures in it are renderer-agnostic. A sample renderer for
+ <a href="http://pygame.org">Pygame</a> is included. The full
+ API documentation is contained in its Python docstrings.
+ </p>
+ <ul class=download>
+ <li class=sh><span data-optional>git clone
+ </span><a href="http://git.yukkurigames.com/python-bulletml.git">http://git.yukkurigames.com/python-bulletml.git</a>
+ </ul>
+ <p>
+ More information about BulletML is available at
+ <a href="http://www.asahi-net.or.jp/~cs8k-cyu/bulletml/index_e.html">the
+ BulletML homepage</a>.
+ </p>
+ <p>
+ In addition to the standard BulletML XML format, this module
+ supports an equivalent YAML format. For convenience, two
+ simple collision routines are provided,
+ <code>bulletml.overlaps</code> for stationary circles and
+ <code>bulletml.collides</code> for moving circles.
+ </p>
+ <h2>API Example</h2>
+ <pre><code>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
+...</code></pre>
+ <p>
+ For drawing, you're on your own, but <code>Bullet</code>
+ instances have a number of attributes that can be used to
+ influence it.
+ </p>
+
+ <h2>BulletYAML</h2>
+ <p>
+ 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.
+ </p>
+ <p>
+ If <a href="http://pyyaml.org/">PyYAML</a> is installed,
+ importing this module automatically registers BulletYAML tags
+ with the default loader and dumper.
+ </p>
+ <h3>YAML Example</h3>
+ <pre><code>!BulletML
+ type: vertical
+ actions:
+ - !ActionDef
+ actions:
+ - !FireDef
+ bullet: !BulletDef {}</code></pre>
+ <h2>FAQ</h2>
+ <dl class="faq">
+ <dt>Can I use bulletml with pyglet / PyOGRE / Panda3d / etc?</dt>
+ <dd>
+ 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.
+ </dd>
+ <dt>What Python version is required?</dt>
+ <dd>
+ 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).
+ </dd>
+ <dt>How stable is the API?</dt>
+ <dd>
+ 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.
+ </dd>
+ <dt>How fast is is the module?</dt>
+ <dd>
+ 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.
+ </dd>
+
+ <dt>
+ My BulletML file doesn't load / play correctly in this module!
+ </dt>
+ <dd>
+ Send us an email and attach your script.
+ </dd>
+
+ <dt>My BulletML plays fine in this module, but nowhere else!</dt>
+ <dd>
+ 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.
+ </dd>
+ <dt>Can I output BulletML?</dt>
+ <dd>
+ 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.
+ </dd>
+ </dl>
+
+ <h3>Spec Deviations</h3>
+ <dl>
+ <dt>XML Validation</dt>
+ <dd>
+ 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.
+ </dd>
+ <dt>Direction Frame Counts</dt>
+ <dd>
+ The BulletML reference implementation contains code which
+ makes a <code>changeDirection</code> 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.
+ </dd>
+ <dt>Firing Speed</dt>
+ <dd><p>
+ The reference implementation, when creating a bullet with
+ <code><speed type="relative"></code>, 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.
+ </p></dd>
+ </dl>
+ <h3>Extensions</h3>
+ <p>
+ This module contains some extensions to the BulletML
+ element set. These use a separate XML namespace,
+ <code>http://code.google.com/p/python-bulletml/</code>. Sample
+ documents that use them begin as follows:
+ </p>
+ <pre><code><bulletml xmlns="http://www.asahi-net.or.jp/~cs8k-cyu/bulletml"
+ xmlns:py="http://code.google.com/p/python-bulletml/"></code></pre>
+ <p>
+ 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.)
+ </p>
+ <dl>
+ <dt>0 frame times</dt>
+ <dd><p>
+ The reference applet does not correctly handle
+ <code>changeDirection</code>, <code>changeSpeed</code>, 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 <wait>0</wait> 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).
+ </p></dd>
+ <dt><offset> - within <fire></dt>
+ <dd>
+ <dl>
+ <dt>Attribute</dt><dd>label - STRING</dd>
+ <dt>Contents</dt><dd>x?, y?</dd>
+ <dt>Example</dt>
+ <dd><pre><code><offset type="absolute">
+ <x>$rand*3</x>
+ <y>-5</y>
+</offset></code></pre></dd>
+ </dl>
+ <p>
+ 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.
+ </p>
+ <p>
+ 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.
+ </p>
+ </dd>
+ <dt><tag> and <untag> - within <action></dt>
+ <dd>
+ <dl>
+ <dt>Contents</dt><dd>STRING</dd>
+ <dt>Example</dt>
+ <dd><pre><code><action>
+ <tag>new</tag>
+ <wait>20</wait>
+ <untag>new</untag>
+</action></code></pre></dd>
+ </dl>
+ <p>
+ <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.
+ </p>
+ <p>
+ Bullet tags are implemented as Python set object in the tags
+ attribute of the Bullet class.
+ </p>
+ </dd>
+ <dt><appearance> within <action></dt>
+ <dd>
+ <dl>
+ <dt>Contents</dt><dd>STRING</dd>
+ <dt>Example</dt>
+ <dd><appearance>pewpew</appearance></dd>
+ </dl>
+ <p>
+ <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.
+ </p>
+ </dd>
+ <dt>
+ <tag> and <appearance> within <bullet> and <fire>
+ </dt>
+ <dd>
+ 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.
+ </dd>
+ <dt><if>, <cond>, <then>, <else></dt>
+ <dd>
+ <dl>
+ <dt>Contents</dt>
+ <dd>
+ <cond>STRING</cond><br>
+ <then>action | actionRef</then><br>
+ [ <else>action | actionRef</else> ]
+ </dd>
+ </dl>
+ <p>
+ Conditional actions are supported. These have one of two
+ forms:
+ </p>
+ <pre><code><!-- 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></code></pre>
+ <p>
+ 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.
+ </p>
+ </dd>
+ </dl>
+ <h2>License</h2>
+ <p>
+ All example BulletML files in the examples folder are released
+ into the public domain. The BulletML specification is the work
+ of <a href="http://www.asahi-net.or.jp/~cs8k-cyu/">Kenta Cho</a>.
+ </p>
+ <div class=copyright>
+ 2010 Joe Wreschnig
+ <p>
+ 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.
+ </p>
+ </div>
+ </main>
+ </body>
+</html>
projects / yukkurigames.com.git / commitdiff