Link to new python-bulletml page.
[yukkurigames.com.git] / 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>