Starward Rogue:XML - BulletPattern Definitions

Overview

Unlike the other things being read in (GameEntity, EntitySystem, etc) this is more of a programming language than a chunk of data. That is, it's imperative as much as it is descriptive.

It's also different in that it relies heavily on template "variables" to avoid duplicating a lot of xml when you want your bullets to do the same or similar thing a lot.

Here's an example usage:

In a file in Configuration/EntitySystem/

<system name="TestWeapon"
	category="Weapon"
	shot_type="BulletPointedYellow"
	damage_type="Ballistic"
	attack_power="40"
	fire_rate="3"
	range_actual="500"
	shots_per_salvo="1"
	targeting_logic="Lead"
	firing_timing="AllTheTime"
	special_bullet_patterns="TestVariablePattern"
	>
</system>

And in a file in Configuration/BulletPattern/

<bullet_pattern name="TestVariablePattern">
	$TestOuterVar SPEED=500
</bullet_pattern>

And in a file in Configuration/BulletPatternVariables/

<var name="TestOuterVar">
  <bullet angle="0" speed="0">
    <loop iterations="5">
      <spawn>
        <bullet_pattern>
          $TestInnerVar A1=45 A2=-45
          $TestInnerVar A1=-45 A2=45
        </bullet_pattern>
      </spawn>
      <wait time="0.1" />
    </loop>
    <die />
  </bullet>
</var>

<var name="TestInnerVar">
  <bullet angle="[A1]" speed="[SPEED]" shot_type="BulletBentEnergyRed">
    <wait time="0.5" />
    <loop iterations="5">
      <change angle="[A2]" time="0.0001" />
      <wait time="1" />
      <change angle="[A1]" time="0.0001" />
      <wait time="1" />
    </loop>
    <die />
  </bullet>
</var>

Now let's trace what's going on:

Massively more confusing than the examples of the data-chunk files, right? Well, welcome to the neighborhood, it's at least as bad as it sounds.

• There's a system (TestWeapon) with special_bullet_patterns="TestVariablePattern" . This tells it to ignore a lot of its normal firing logic and instead "do whatever that pattern tells you" whenever it fires.
• In TestVariablePattern's definition, it references the template "TestOuterVar" and passes in the value "500" for the parameter "SPEED"
  • the 500 could have been hardcoded later on, but this allows multiple patterns to use this behavior with different bullet velocities without extra copy-and-paste
• In TestOuterVar's definition, it:
  • creates a single "starter" bullet with no velocity (it's still visible in this example, but that's probably not desirable), which does the following five times:
    • spawn another bullet pattern, whose description references the template "TestInnerVar" twice, each time with different parameter values for A1 and A2
      • Again, the angles could have been hardcoded, but then the code in TestInnerVar would have to be written twice: once for each different set of values. Code duplication is the enemy!
    • waits a tenth of a second (before going back to the beginning of the loop)
  • and then the starter bullet dies
• In TestInnerVar's definition, it:
  • creates a BulletBentEnergyRed bullet with angle = A1 and speed = SPEED (note: TestOuterVar doesn't have to pass SPEED in, that's already defined), which then:
    • travels at that course and speed for half a second
    • changes angle to A2 (instantly, that's the time="0.0001"
    • travels at that course and speed for a full second
    • changes back to A1
    • travels at that course and speed for a full second
    • switches back and forth four more times
    • dies

The overall result is that it fires two strings of bullets 45 degrees on either side of the line to the target, and the lines "crisscross" five times before disappearing.

IMPORTANT NOTE: the use of the template variables was completely optional and has no bearing on the actual xml schema: those just cause a bunch of text replacement when the xml is being read in. Here's how the file in Configuration/BulletPattern/ would have looked without any template vars, and also the actual xml text that the game would have _seen_ in the main parsing in the TestVariablePattern case:

<bullet_pattern name="TestVariablePattern">
  <bullet angle="0" speed="0">
    <loop iterations="5">
      <spawn>
        <bullet_pattern>
  <bullet angle="45" speed="500" shot_type="BulletBentEnergyRed">
    <wait time="0.5" />
    <loop iterations="5">
      <change angle="-45" time="0.0001" />
      <wait time="1" />
      <change angle="45" time="0.0001" />
      <wait time="1" />
    </loop>
    <die />
  </bullet>
  <bullet angle="-45" speed="500" shot_type="BulletBentEnergyRed">
    <wait time="0.5" />
    <loop iterations="5">
      <change angle="45" time="0.0001" />
      <wait time="1" />
      <change angle="-45" time="0.0001" />
      <wait time="1" />
    </loop>
    <die />
  </bullet>
        </bullet_pattern>
      </spawn>
      <wait time="0.1" />
    </loop>
    <die />
  </bullet>
</bullet_pattern>

Node Types and Attributes

var

this is a template variable that can be referenced elsewhere to save effort. Can only be defined in files in Configuration/BulletPatternVariables/

attributes

• name (string)
  • must be unique, this is how it's referenced

sub-node(s)

• any
  • the game just basically copy-and-pastes it into whatever referenced it, after replacing any parameter names (enclosed in square brackets) with their values in that context

IMPORTANT NOTE

the syntax for referencing a variable is to have:

• a $ as the first non-whitespace on a line
• followed immediately by the name of the variable
• followed by zero or more:
  • one space
  • followed immediately by a parameter name (alpha-numeric, starts with a letter)
  • followed immediately by an equal sign
  • followed immediately by the parameter value (alpha-numeric, most symbols probably work, no spaces)

bullet_pattern

this is the main thing being defined, but the node can also be used within a bullet's spawn sub-node

attributes

• name (string, required unless this is within a spawn node)
  • Must be unique across all BulletPattern's being loaded by the game

sub-node(s)

• bullet

loop

sub-node(s)

Starward Rogue XML Documentation Main