Templates

1   Ships

Ships fall into three broad categories:

And most ships come from a standard ship class:

To declare a new ship, start with the template line. At a minimum, new ships should set rotation.sprite, rotation.frames, weapons, and shield_color. They should also have a portrait, if possible:

template:      "tpl/cruiser"
portrait:      "fed/cruiser"
shield_color:  "white"
weapons:
  pulse:
    base:  "dev/photorp/turret"
    positions:
      * {x: 0, y: -40}
  beam:
    base:  "dev/phaser/turret"
    positions:
      * {x: 0, y: -20}
rotation:
  sprite:  "fed/cruiser"
  frames:  {begin: 0, end: 24}

Depending on how powerful a race is, it might also make sense to override health, energy, turn_rate, max_velocity, warp_speed, or other default values.

2   Projectiles

To declare a new projectile, start with the template line. The most important fields for a projectile are its max_velocity, expire.after.age, and collide.damage. It’s also usually a good idea if its collide.action removes itself after impact.

Beyond those fields, a new projectile needs to have an appearance:

• For tpl/anipulse, new projectiles need animation.sprite, animation.frames, and animation.speed at a minimum.
• For tpl/rotpulse and tpl/missile, new projectiles need rotation.sprite and rotation.frames.
• For tpl/ray, they need ray.to, ray.hue, and ray.range.
• For tpl/bolt, they need bolt.color.

Here’s a basic definition for an animated pulse (tpl/anipulse):

template:      "tpl/anipulse"
long_name:     "Photon Torpedo"
short_name:    "PHOTORP"
max_velocity:  8.0
animation:
  sprite:  "dev/photorp"
  frames:  {begin: 0, end: 6}
  speed:   0.01
expire:
  after:
    age:  "1.0s"
create:
  action:
    * type:         "play"
      sound:        "dev/photorp"
      priority:     3
      persistence:  "0.3s"
      volume:       255
collide:
  damage:  400
  action:
    * type:       "create"
      reflexive:  true
      base:       "sfx/explosion/energy"
    * type:       "remove"
      reflexive:  true

It’s usually good to play the fire sound as part of its create.action, so that the same sound will play for that projectile, no matter what weapon is firing.

3   Weapons

Weapons are equipped by ships. There are four sub-categories of weapons. Most of the differences between weapons are determined by their projectiles, so the sub-categories are mostly about how CPU pilots handle the weapons.

• Guns are used to attack enemies in front of a ship.
• Turrets are used to attack enemies all around a ship.
• Devices are used for defense or transportation, rather than attack.
• Specials are never fired automatically by CPU pilots.

When creating a weapon, the important things to declare are the name, device fields, and activate.action:

template:    "tpl/gun"
long_name:   "Photon Torpedo Launcher"
short_name:  "PHOTORP"
device:
  ammo:       20
  fire_time:  "1.0s"
  range:      480.0
  speed:      10.0
activate:
  action:
    * type:                "create"
      reflexive:           true
      base:                "dev/photorp/pulse"
      relative_velocity:   true
      relative_direction:  true

Note how some of the values have been copied from the example projectile above:

• The weapon’s device.speed is equal to the projectile’s max_velocity.
• The weapon’s device.range is equal to the projectile’s max_velocity times its expire.after.age (keeping in mind that max_velocity is a speed in px/t and that expire.after.age is a duration of 1s, or 60t).

In the common case, where projectiles have a constant velocity, these calculations should work as-is. If projectiles speed up or slow down, then they may need to be adjusted.

4   Waypoints

Fixed locations that the player can select are called waypoints. There are three sub-categories of waypoints:

• Planets can build ships and be captured by transports.
• Structures can be shot at and destroyed.
• Stations can be neutralized and captured by assault transports.

Before creating a new waypoint, consider whether the object needs to act differently, or just look different. For example, the Gaitori Habitat Station in The Stars Have Ears and the Salrilian Battlestation in The Left Hand are actually just Bunker Stations with an override.sprite.

5   Decoration

Decorations make the game look interesting but aren’t interactive. There are two sub-categories:

• Effects are drawn over ships’ sprites. They usually disappear when their animation completes.
• Scenery is drawn under ships. Sometimes it disappears; other times it sticks around.

For example, a new explosion needs an animation.sprite, animation.frames, and animation.speed, and should expire.after.animation:

template:    "tpl/effect"
long_name:   "Photon Torpedo Explosion"
short_name:  "P EXPLSN"
animation:
  sprite:  "sfx/explosion/photon"
  frames:  {begin: 0, end: 10}
  speed:   0.15
expire:
  after:  {animation: true}
create:
  action:
    * type:         "play"
      reflexive:    true
      sound:        "sfx/explosion/small"
      priority:     3
      persistence:  "0.35s"
      volume:       255

It’s usually good to play the explosion sound as part of its create.action, so that the same sound will play for that explosion, no matter what object is exploding.

6   Hazards

Hazards are non-thinking objects that collide with ships and otherwise cause trouble.

7   Miscellaneous

Some objects don’t fit neatly into the categories above:

• EVATs are mostly ship-like, but can’t be selected and expire after a while. They have special behavior for occupying stations.
• Rotations have a different appearance depending on their direction, but don’t fit neatly into any other categories (like ships, projectiles or EVATs).
• Drones are mostly ship-like, but are animations instead of rotations.