BulletMLX DTD

<!--

BulletMLX Document Type Definition.  Originally based on the work
Kenta Cho.  The original work can be found at:

    http://www.asahi-net.or.jp/~cs8k-cyu/bulletml/

This file expands the original with some new elements and attributes
necessary for our game.  All BulletML files are valid BulletMLX
files.  The source file

    src/bullet.lua

contains our implementation of BulletMLX while the file

    docs/Patterns.txt

explains how to write bullet patterns using the language, from the
perspective of designers more than developers.

-->

<!-- <vertical>

We use this tag as a child of <accel> to indicate that a bullet should
accelerate in a vertical direction.  The value of the tag is a degree
in the range of zero to three-hundred fifty-nine.  The optional
attribute ‘type’ determines the semantics of that value.  See the
documentation for <direction> for the meaning of the ‘type’ values.

-->
<!ELEMENT vertical (#PCDATA)>
<!ATTLIST vertical type (absolute|relative|sequence) "absolute">

<!-- <fireRef>

This tag references a labeled <fire> tag.  The game currently does not
use this tag.

-->
<!ELEMENT fireRef (param*)>
<!ATTLIST fireRef label CDATA #REQUIRED>

<!-- <changeDirection>

An <action> uses this tag to modify the current <direction> of the
bullets the pattern is firing.  The <term> indicates how many ticks it
takes before the full change of direction takes place.  See the
<direction> documentation for details on that tag.

-->
<!ELEMENT changeDirection (direction, term)>

<!-- <bulletml>

This is the root tag of bullet pattern definitions.  It must contain
multiple <bullet> and <action> tags.  The ‘xmlns’ attribute is
acceptable but there is no defined namespace for BulletMLX files.  The
‘type’ attribute may contain three possible values; they indicate the
overall direction of the pattern.  That attribute exists more for
self-documentation than anything else.

-->
<!ELEMENT bulletml (bullet | action)*>
<!ATTLIST bulletml xmlns CDATA #IMPLIED>
<!ATTLIST bulletml type (none|vertical|horizontal) "none">

<!-- <debug>

This tag should contain a string of Lua code defining one function.
That function must accept one argument, which will be a Pattern object
representing the current bullet pattern (see “src/bullet.lua” for its
definition).  This makes it easier for designers to add debugging
tools into complex bullet patterns.

-->
<!ELEMENT debug (#PCDATA)>

<!-- <param>

A <param> represents a parameter used within a <bulletRef/> or an
<actionRef/>.  Parameters make it possible to define a bullet or
action with blanks to fill it later during the references.  For
example, we have this bullet definition:

    <bullet label="basic">
        <speed>$1</speed>
        <size>$2*$rand+4</size>
        <color red="0" blue="180" green="240"/>
    </bullet>

The values ‘$1’ and ‘$2’ are special BulletMLX text that represent
parameter values.  The values we give to <param> later will replace
those variables.  Here is how we can reference the bullet and fill in
the parameters:

    <bulletRef label="basic">
        <param>3</param>
        <param>10</param>
    </bulletRef>

So now 3 would replace ‘$1’ and 10 would replace ‘$2’.  Other
<bulletRef/> nodes could reference the same bullet but provide
different parameter values to create different bullets built from the
same mold.

-->
<!ELEMENT param (#PCDATA)>

<!-- <actionRef>

This tag references an existing <action>, which must have a ‘label’
attribute.  It tells the game to execute that action as if we had put
the entire contents of the <action> tag we reference in that spot.  It
also allows for <param> tags just like <bulletRef/>.

-->
<!ELEMENT actionRef (param*)>
<!ATTLIST actionRef label CDATA #REQUIRED>

<!-- <repeat>

Repeat an action a given number of times.

-->
<!ELEMENT repeat (times, (action | actionRef))>

<!-- <accel>

Accelerates a bullet in a certain number of frames, indicate by the
<term> node.  One of two optional nodes must appear: <horizontal/> or
<vertical/>.  These indicate the direction of acceleration.

-->
<!ELEMENT accel (horizontal?, vertical?, term)>

<!-- <times>

The number of times to perform an action, particularly as used by the
<repeat> element.  The content of this tag should either be a BulletML
math expression, e.g. a non-negative integer, or it should be the
string ‘infinite’.  Using the string ‘infinite’ in conjunction with
<repeat> will ensure that the engine never stops executing the
associated action.

-->
<!ELEMENT times (#PCDATA)>

<!-- <term>

A BulletML math expression representing a number of frames.  Other
tags use this as a child node to describe how much time should pass
during a certain event, e.g. changing the speed of a bullet.  Pattern
files should assume the engine runs at sixty frames per second and
write values for <term> accordingly.

-->
<!ELEMENT term (#PCDATA)>

<!-- <wait>

A BulletML math expression indicating how many frames the engine
should wait.  For example, ‘<wait>60</wait>’ will pause the action in
a pattern for one second.

-->
<!ELEMENT wait (#PCDATA)>

<!--  <fireSimulatenously>

This element lets us group together multiple <fire> nodes into a
single entity so that a pattern can shoot more than one bullet at the
same time.

-->
<!ELEMENT fireSimulatenously (fire+)>

<!-- <action>

An <action> tag is the primary way that a pattern describes actual
bullet behavior.  While the <bullet> tags define *what* builds a
pattern, the <action> tag defines *how* the pattern works.  The
<action> tag accepts a large number of optional tags to help control
what the pattern does.

An <action> tag may have a ‘label’ attribute giving it a name.  Later
the pattern may refer back to this action by using that name.

The optional ‘difficulty’ property lets designers ensure the game only
executes the action on a certain difficulty level.  This makes it
possible to create patterns like boss attacks with very different
behavior based on difficulty.  By default the property has the value
of ‘Any’, which means to execute that action under any difficulty.

-->
<!ELEMENT action (
          changeDirection? |
          accel?           |
          vanish?          |
          appear?          |
          changeSpeed?     |
          changeDamage?    |
          repeat?          |
          wait?            |
          (fire | fireRef  | fireSimultaneously) |
          playSound?       |
          (action | actionRef)?
          )*>
<!ATTLIST action label CDATA #IMPLIED>
<!ATTLIST action difficulty (Love|Easy|Normal|Hard|Hate|Any) "Any">

<!-- <playSound>

This tag accepts the path to a sound effect and creates an instruction
for the game to play that sound at that point in the pattern.

-->
<!ELEMENT playSound (#PCDATA)>

<!-- <vanish> <appear>

These two tags cause all bullets in the current action to vanish or
reappear on screen, respectively.  These tags cannot have children.

-->
<!ELEMENT vanish (EMPTY)>
<!ELEMENT appear (EMPTY)>

<!-- <speed>

The number of pixels the bullet will move in one tick.

-->
<!ELEMENT speed (#PCDATA)>
<!ATTLIST speed type (absolute|relative|sequence) "absolute">

<!-- <size>

This takes an integer which determines the size of the bullet.  It
is only valid if the <shape> of the bullet is ‘circle’.  Otherwise the
value has no meaning.

-->
<!ELEMENT size (#PCDATA)>

<!-- <shape>

This defines the shape of the bullet.  The default is ‘circle’, which
the game engine enforces.  See the document

    docs/Patterns.txt

for a list of the valid shapes.

-->
<!ELEMENT shape (#PCDATA)>

<!-- <scale>

Contains a numeric value indicating how to scale the bullet image
horizontally and vertically.  The format allows positive and negative
numbers.  This tag only makes sense in the context of a bullet that
also has

    <shape>image</shape>

as part of its definition.  Because we draw all other shapes with
primitive drawing routines where scaling is not a factor.

-->
<!ELEMENT scale (#PCDATA)>

<!-- <image>

A filepath to the image to use for this bullet.  The filepath must be
relative to the top level of the project directory.

-->
<!ELEMENT image (#PCDATA)>

<!-- <shader>

Can contain GLSL 1.2 code that the game will use as the shader for the
bullet.  This is only used if the <shape> is ‘image’.  The code should
be wrapped in <![CDATA[[ … ]]> tags for the sake of ease.  See the
wiki page

    https://love2d.org/wiki/love.graphics.newShader

for more information of the shader language the engine uses.

-->
<!ELEMENT shader (#PCDATA)>

<!-- <color>

Contains three child nodes which each contain integer values in the
range of zero to two-hundred fifty-five.  These define the color of
the bullet.

-->
<!ELEMENT color (#PCDATA)>
<!ATTLIST color red   CDATA #REQUIRED>
<!ATTLIST color blue  CDATA #REQUIRED>
<!ATTLIST color green CDATA #REQUIRED>

<!-- <horizontal>

Specifies acceleration in a horizontal line, where the contents are a
BulletML math expression indicating the direction.  The number is a
degree.  Values for the ‘type’ attribute have the same semantic
meaning as the same-named parts of <direction/>.

-->
<!ELEMENT horizontal (#PCDATA)>
<!ATTLIST horizontal type (absolute|relative|sequence) "absolute">

<!-- <damage>

This element contains an integer which describes the amount of damage
a bullet causes on impact.  For example, if the value is five then the
bullet would take away five health from an enemy, or from the player’s
ship if an enemy fires the bullet.

The value may also be a BulletMLX expression with math operators and
variables, e.g. “4 * ($rank - 1) + $1 + $2”.

By default a bullet has a damage value of one.

-->
<!ELEMENT damage (#PCDATA)>

<!-- <persistent>

If true, this bullet will persist after hitting a target.
Note that it is up to the game engine to decide which targets persistent
bullets will actually persist after hitting. For example, the game
developer may decide that the persistent tag will make player bullets
travel through multiple enemies, but stop if it hits terrain.

By default, bullets do not persist.

-->
<!ELEMENT persistent (#PCDATA)>

<!-- <bullet>

Represents a type of bullet.  The element has a large number of
potential children which describe the various properties of bullets.
If a bullet has a value for the ‘label’ attribute then other parts of
a pattern can use a <bulletRef/> node to refer to that bullet, which
is useful for re-use.

-->
<!ELEMENT bullet (damage?, direction?, speed?, size?, shape?, color?, image?, scale?, shader?, (action | actionRef)*)>
<!ATTLIST bullet label CDATA #IMPLIED>

<!-- <direction>

Indicates direction as a BulletML math expression which must be in the
range of zero to three-hundred sixty, i.e. a degree.  The ‘type’
attribute affects the interpretation of that value.  See the
documentation in

    docs/Patterns.txt

for a description of the semantic meanings of direction types.

-->
<!ELEMENT direction (#PCDATA)>
<!ATTLIST direction type (aim|absolute|relative|sequence) "aim">

<!-- <changeSpeed>

Changes the speed of a bullet to the value in <speed> after <term>
number of frames.

-->
<!ELEMENT changeSpeed (speed, term)>

<!--  <changeDamage>

Changes the damage which a bullet does to the value of the <damage>
child after <term> number of frames.  If an action uses multiple
bullets then this will change the damage of all of them.

-->
<!ELEMENT changeDamage (damage, term)>

<!-- <offset> <x> <y>

This element lets us define the offset for a given <fire> action.  The
child <x> and <y> tags, which are both optional (defaulting to zero),
contain integers which tell the engine to shoot all bullets in the
<fire> node as if their origin uses the given offsets.  For example,
an offset of ‘<x>10</x>’ would cause the bullets to appear ten pixels
to the right of the pattern’s origin.

These offsets are always *relative* to the origin of the pattern, and
the pattern origin is never inside an actual pattern XML document.
Therefore it remains impossible to create bullets in absolute screen
positions within a pattern definition.

-->
<!ELEMENT offset (x?, y?)>
<!ATTLIST offset label CDATA #IMPLIED>
<!ELEMENT x (#PCDATA)>
<!ELEMENT y (#PCDATA)>

<!-- <offsetRef/>

This refers to an <offset> with a given label.

-->
<!ELEMENT offsetRef (param*)>
<!ATTLIST offsetRef label CDATA #REQUIRED>

<!-- <fire>

Tells the engine to fire a bullet, which can either be a new <bullet>
or a <bulletRef/> that references an existing bullet.  A <fire> node
can have a label for use with <fireRef/> later, but our particular
implementation of BulletMLX currently ignores <fireRef/>.

-->
<!ELEMENT fire ((bullet | bulletRef), direction?, speed?, (offset | offsetRef)?)>
<!ATTLIST fire label CDATA #IMPLIED>

<!-- <bulletRef>

Refers to a pre-existing <bullet> definition and uses it as if that
<bullet> definition were in place of the <bulletRef/>.  This behaves
the same way as <actionRef/>, so looking at its documentation may also
be helpful.

-->
<!ELEMENT bulletRef (param*)>
<!ATTLIST bulletRef label CDATA #REQUIRED>