python-bulletml/index.html

   1 <!DOCTYPE html>
   2 <html>
   3   <head>
   4     <meta charset="utf-8">
   5     <meta name=viewport content="width=device-width, initial-scale=1">
   6     <link rel="stylesheet" href="/css/main.css" type="text/css">
   7     <title>Python BulletML - Yukkuri Games</title>
   8   </head>
   9   <body>
  10     <header>
  11       <a href="/">
  12         <img src="/logotype_horizontal_1.png" class=logo alt="(◕ ヮ ◕)">
  13         <img src="/logotype_horizontal_2.png" class=optional
  14              alt="Yukkuri Games">
  15       </a>
  16       <h1>Python BulletML</h1>
  17     </header>
  18     <main>
  19       <aside class="important">
  20         This project isn't dead, but also isn't actively maintained
  21         against current versions of Python and Pygame. Specific
  22         problems and requests may be dealt with, but working with it
  23         might be rough-going at first.
  24       </aside>
  25       <p>
  26         BulletML is the Bullet Markup Language. BulletML can describe
  27         the barrage of bullets in shooting games. (For example
  28         Progear, Psyvariar, Gigawing2, G DARIUS, XEVIOUS, ...) This
  29         module parses and executes BulletML scripts in
  30         <a href="https://www.python.org/">Python</a>. All data
  31         structures in it are renderer-agnostic. A sample renderer for
  32         <a href="http://pygame.org">Pygame</a> is included. The full
  33         API documentation is contained in its Python docstrings.
  34       </p>
  35       <ul class=download>
  36         <li class=sh><span data-optional>git clone
  37           </span><a href="http://git.yukkurigames.com/python-bulletml.git">http://git.yukkurigames.com/python-bulletml.git</a>
  38       </ul>
  39       <p>
  40         More information about BulletML is available at
  41         <a href="http://www.asahi-net.or.jp/~cs8k-cyu/bulletml/index_e.html">the
  42           BulletML homepage</a>.
  43       </p>
  44       <p>
  45         In addition to the standard BulletML XML format, this module
  46         supports an equivalent YAML format. For convenience, two
  47         simple collision routines are provided,
  48         <code>bulletml.overlaps</code> for stationary circles and
  49         <code>bulletml.collides</code> for moving circles.
  50       </p>
  51       <h2>API Example</h2>
  52       <pre><code>from bulletml import Bullet, BulletML
  53
  54 doc = BulletML.FromDocument(open("test.xml", "rU"))
  55 player = ...  # On your own here, but it needs x and y fields.
  56 rank = 0.5    # Player difficulty, 0 to 1
  57
  58 bullet = Bullet.FromDocument(doc, x, y, target=player, rank=rank)
  59 bullets = [bullet]
  60 ...
  61 for bullet in bullets:
  62     bullets.extend(bullet.step()) # step() returns new Bullets
  63 ...</code></pre>
  64       <p>
  65         For drawing, you're on your own, but <code>Bullet</code>
  66         instances have a number of attributes that can be used to
  67         influence it.
  68       </p>
  69
  70       <h2>BulletYAML</h2>
  71       <p>
  72         BulletYAML is a translation of BulletML into YAML. The
  73         structure is mostly the same as the XML version, except
  74         BulletRef/FireRef/ActionRef elements are only used if they
  75         contain parameters, as YAML has its own intra-document
  76         references. Parameterless references are turned into direct
  77         YAML references.
  78       </p>
  79       <p>
  80         If <a href="http://pyyaml.org/">PyYAML</a> is installed,
  81         importing this module automatically registers BulletYAML tags
  82         with the default loader and dumper.
  83       </p>
  84       <h3>YAML Example</h3>
  85       <pre><code>!BulletML
  86   type: vertical
  87   actions:
  88     - !ActionDef
  89       actions:
  90       - !FireDef
  91     bullet: !BulletDef {}</code></pre>
  92       <h2>FAQ</h2>
  93       <dl class="faq">
  94         <dt>Can I use bulletml with pyglet / PyOGRE / Panda3d / etc?</dt>
  95         <dd>
  96           Yes. BulletML works on abstract data structures that have
  97           x/y/speed/direction fields. Depending on your renderer, you
  98           can either use these directly to render, or feed the
  99           simulation data output by BulletML into a physics controller
 100           or scenegraph.
 101         </dd>
 102         <dt>What Python version is required?</dt>
 103         <dd>
 104           Python 2.6 or later is required; this includes 3.x (although
 105           the sample runner will not work without a functional Pygame
 106           for Python 3).
 107         </dd>
 108         <dt>How stable is the API?</dt>
 109         <dd>
 110           As of version 2, I expect the API to be stable enough to use
 111           for your game, including adding new kinds of actions or
 112           subclassing Bullet. However, I still recommend including the
 113           entire module with your game if possible.
 114         </dd>
 115         <dt>How fast is is the module?</dt>
 116         <dd>
 117           This depends on what features you are using. There used to
 118           be a table here explaining it, but starting in version 2 it
 119           varies even more depending on the bullet definition used. If
 120           you're stuck with pure-Python collision detection and no
 121           Pysco, you might get as low as 100 per frame; if you've got
 122           _collision.so and Psyco available, you can get over 2000.
 123         </dd>
 124
 125         <dt>
 126           My BulletML file doesn't load / play correctly in this module!
 127         </dt>
 128         <dd>
 129           Send us an email and attach your script.
 130         </dd>
 131
 132         <dt>My BulletML plays fine in this module, but nowhere else!</dt>
 133         <dd>
 134           This module has several major extensions to the BulletML
 135           format, as well as a much more lax parser. If you're using
 136           the extensions you're probably SOL, but you may just need to
 137           clean up your XML elements a bit.
 138         </dd>
 139         <dt>Can I output BulletML?</dt>
 140         <dd>
 141           No. Some data about the XML structure is lost in the loading
 142           process. You can output BulletYAML however, or anything else
 143           supporting the standard Python serialization interface.
 144         </dd>
 145       </dl>
 146
 147       <h3>Spec Deviations</h3>
 148       <dl>
 149         <dt>XML Validation</dt>
 150         <dd>
 151           This module does absolutely no XML validation. Element order
 152           doesn't matter, unknown elements are completely ignored, and
 153           when duplicate elements are found the most-recently-parsed
 154           one is used.
 155         </dd>
 156         <dt>Direction Frame Counts</dt>
 157         <dd>
 158           The BulletML reference implementation contains code which
 159           makes a <code>changeDirection</code> element with a term of
 160           1 do nothing. In this implementation, it causes a change of
 161           direction during the next frame. This change had no effect
 162           on the reference samples. Kenta Cho has confirmed this is a
 163           bug in the reference implementation.
 164         </dd>
 165         <dt>Firing Speed</dt>
 166         <dd><p>
 167           The reference implementation, when creating a bullet with
 168           <code>&lt;speed type="relative"></code>, uses the previous
 169           fire speed, and not the source bullet's speed. This module
 170           instead uses the speed of the source bullet for relative,
 171           and the previous fire speed for sequence. This change had no
 172           effect on the reference samples. Kenta Cho has confirmed
 173           this is a bug in the reference implementation.
 174         </p></dd>
 175       </dl>
 176       <h3>Extensions</h3>
 177       <p>
 178         This module contains some extensions to the BulletML
 179         element set. These use a separate XML namespace,
 180         <code>http://code.google.com/p/python-bulletml/</code>. Sample
 181         documents that use them begin as follows:
 182       </p>
 183       <pre><code>&lt;bulletml xmlns="http://www.asahi-net.or.jp/~cs8k-cyu/bulletml"
 184           xmlns:py="http://code.google.com/p/python-bulletml/"></code></pre>
 185       <p>
 186         These extensions do make your document invalid BulletML, and
 187         they may not parse correctly in other parsers. (For example,
 188         the reference implementation applet will not read them.)
 189       </p>
 190       <dl>
 191         <dt>0 frame times</dt>
 192         <dd><p>
 193           The reference applet does not correctly handle
 194           <code>changeDirection</code>, <code>changeSpeed</code>, or
 195           accel elements if they have terms of 0 (it ends up dividing
 196           by zero). This module instead applies the change immediately
 197           if the type is relative, absolute, or aim, and does nothing
 198           if the type is sequence. A <wait>0</wait> in the reference
 199           applet and in this implementation behave the same - it stops
 200           evaluation of the action immediately, but advances it again
 201           next frame (as opposed to 1, which stops it immediately,
 202           waits the next, then advances the next).
 203         </p></dd>
 204         <dt>&lt;offset> - within &lt;fire></dt>
 205         <dd>
 206           <dl>
 207             <dt>Attribute</dt><dd>label - STRING</dd>
 208             <dt>Contents</dt><dd>x?, y?</dd>
 209             <dt>Example</dt>
 210             <dd><pre><code>&lt;offset type="absolute">
 211   &lt;x>$rand*3&lt;/x>
 212   &lt;y>-5&lt;/y>
 213 &lt;/offset></code></pre></dd>
 214           </dl>
 215           <p>
 216             The &lt;offset> element can be used to give a positional
 217             offset to a newly-fired bullet. Normally, bullets appear
 218             at the same location as their parent bullet. Using offset,
 219             these can either be moved around in absolute space, or
 220             relative to the parent's direction.
 221           </p>
 222           <p>
 223             When using a relative direction, positive x is to the
 224             "right" of the source's facing, and positive y is "in
 225             front of" the source.
 226           </p>
 227         </dd>
 228         <dt>&lt;tag> and &lt;untag> - within &lt;action></dt>
 229         <dd>
 230           <dl>
 231             <dt>Contents</dt><dd>STRING</dd>
 232             <dt>Example</dt>
 233             <dd><pre><code>&lt;action>
 234   &lt;tag>new&lt;/tag>
 235   &lt;wait>20&lt;/wait>
 236   &lt;untag>new&lt;/untag>
 237 &lt;/action></code></pre></dd>
 238           </dl>
 239           <p>
 240             &lt;tag> sets a simple string tag on the bullet running this
 241             action. &lt;untag> removes a tag. Setting the same tag twice
 242             or trying to remove a tag that is not set has no effect.
 243           </p>
 244           <p>
 245             Bullet tags are implemented as Python set object in the tags
 246             attribute of the Bullet class.
 247           </p>
 248         </dd>
 249         <dt>&lt;appearance> within &lt;action></dt>
 250         <dd>
 251           <dl>
 252             <dt>Contents</dt><dd>STRING</dd>
 253             <dt>Example</dt>
 254             <dd>&lt;appearance>pewpew&lt;/appearance></dd>
 255           </dl>
 256           <p>
 257             &lt;appearance> sets the appearance attribute on the
 258             Bullet instance. The effect of this is game-dependent, but
 259             the intended use is to set a texture, color, or animation
 260             sequence for the bullet.
 261           </p>
 262         </dd>
 263         <dt>
 264           &lt;tag> and &lt;appearance> within &lt;bullet> and &lt;fire>
 265         </dt>
 266         <dd>
 267           Like &lt;action>, &lt;bullet> and &lt;fire> can contain
 268           &lt;tag> and &lt;appearance> elements. This causes the
 269           bullet to be created with those tags and an appearance
 270           already set.
 271         </dd>
 272         <dt>&lt;if>, &lt;cond>, &lt;then>, &lt;else></dt>
 273         <dd>
 274           <dl>
 275             <dt>Contents</dt>
 276             <dd>
 277               &lt;cond>STRING&lt;/cond><br>
 278               &lt;then>action | actionRef&lt;/then><br>
 279               [ &lt;else>action | actionRef&lt;/else> ]
 280             </dd>
 281           </dl>
 282           <p>
 283             Conditional actions are supported. These have one of two
 284             forms:
 285           </p>
 286           <pre><code>&lt;!-- Fire a bullet 70% of the time. -->
 287 &lt;if>&lt;cond>$rand > 0.3&lt;/cond>
 288   &lt;then>&lt;fire>&lt;bullet/>&lt;/fire>&lt;/then>
 289 &lt;/if>
 290
 291 &lt;!-- Randomly fire red or blue bullets. -->
 292 &lt;if>&lt;cond>$rand > 0.5&lt;/cond>
 293   &lt;then>&lt;fire>
 294      &lt;bullet/>&lt;appearance>red&lt;/appearance>
 295   &lt;/fire>&lt;/then>
 296   &lt;else>&lt;fire>
 297     &lt;bullet/>&lt;appearance>blue&lt;/appearance>
 298   &lt;/fire>&lt;/else>
 299 &lt;/if></code></pre>
 300           <p>
 301             If the conditional has no else branch, execution proceeds
 302             immediately to the next instruction of the action
 303             containing the conditional. Otherwise, as &lt;action>,
 304             &lt;repeat>, etc., the first step of the subaction is
 305             executed.
 306           </p>
 307         </dd>
 308       </dl>
 309       <h2>License</h2>
 310       <p>
 311         All example BulletML files in the examples folder are released
 312         into the public domain. The BulletML specification is the work
 313         of <a href="http://www.asahi-net.or.jp/~cs8k-cyu/">Kenta Cho</a>.
 314       </p>
 315       <div class=copyright>
 316         2010 Joe Wreschnig
 317         <p>
 318           Permission is hereby granted, free of charge, to any person
 319           obtaining a copy of this software and associated
 320           documentation files (the "Software"), to deal in the
 321           Software without restriction, including without limitation
 322           the rights to use, copy, modify, merge, publish, distribute,
 323           sublicense, and/or sell copies of the Software, and to
 324           permit persons to whom the Software is furnished to do so,
 325           provided the above copyright notice and this permission
 326           notice shall be included in all copies or substantial
 327           portions of the Software.
 328         </p>
 329       </div>
 330     </main>
 331   </body>
 332 </html>