Action

1.1   What

In any given action, there are two objects with different roles:

• A subject object. The subject object is normally the one acting in an action. When a missile collides with a ship, the missile is the subject object. When a transport lands on a planet, the transport is the subject object.
• A direct object. The direct object is usually the one acted upon by the action. When a missile collides with a ship, the ship is the direct object. When a transport lands on a planet, the planet is the direct object.

Most actions are defined in terms of what they do to these objects. In a capture action, the subject object captures the direct object.

Actions can also be reflexive. This swaps the roles of the subject object and direct object. In a reflexive capture action, the subject object is captured by the direct object.

1.2   Where

Actions take place at a location. Normally, this is the center of the direct object (or subject object if reflexive). When a missile collides with a ship, the location is at the center of the ship.

One exception: when a weapon fires, that action takes place at the weapon’s positions on the firing ship, rather than the center of the ship.

1.3   When

Every condition has an associated action. If the condition becomes true, it executes its action with its subject object and direct object.

An object can have up to six different actions. It is always the subject object for its own actions, but the direct object depends on the action:

1.4   How

All actions come in arrays, which together make up an action sequence. Actions in a sequence execute one after another until the whole sequence has executed.

If there is a delay action, that postpones the remainder of the sequence until the delay duration finishes.

It’s possible for an action from one sequence to trigger another action sequence. In this case, the second action sequence will run to completion, and then the first action sequence will resume. For example, if a gun’s activate.action creates a bullet and gunsmoke, then the bullet’s create.action will run before the gun creates the gunsmoke.

2.1   reflexive

If reflexive is true, then the roles of the subject object and direct object are swapped.

For example, if an missile hits a ship and explodes, its collide action needs a create action to create the explosion and a remove action to remove the missile. The create action should be reflexive, so that the explosion is centered on the missile, not the ship. The remove action should also be reflexive, so that it removes the missile, not the ship.

2.2   if

Each action can have filters set on it. If the direct object does not match an action’s filters, the action sequence skips that action. The following fields are supported:

If override.direct is used, the filters apply to the new direct object. However, reflexive doesn’t make the filters apply to the subject object; they still apply to the direct object.

For example, a transport’s “arrive” action specifies:

if:
  tags:   {planet: true}
  owner:  "different"

This ensures that the transport only attempts to land on a hostile planet. It will never:

• land on a station, flak drone, ship, or other non-planet, because of the tag filter, or
• land on a friendly planet, because of the owner filter.

(use of the attributes [1] field is not recommended. It exists only for compatibility with some Hera-created scenarios)

2.3   override

Executes the action on a different subject object or direct object from the default. This can be used in level-specific actions to operate on a level’s initial objects.

For example, in Hornet’s Nest, overrides are used to order both escort ships to attack. One action’s override.subject is the first escort, and the following action’s override.subject is the second escort.

Overrides only affect their own action. Subsequent actions in the action sequence use the original objects.

3.1   age

Modifies the direct object’s expire.after.age. Picks a random duration from value. If relative is true, adds that duration to the object’s age. Otherwise, sets the object’s age to that duration.

3.2   assume

Causes the direct object to become an initial object. Adds the first counter of the first player to which, and gives the object the resulting initial object number.

3.3   cap_speed

Sets the direct object’s max_velocity. If value is null, then sets the direct object’s max_velocity to its default value.

3.4   capture

Changes the owner of the direct object:

• If player is null, sets the owner of the direct object to the owner of the subject object.
• If not, sets the owner of the direct object to player.

3.5   check

Causes all conditions to be re-checked, possibly triggering their own action sequences.

Checking conditions isn’t free, so this action should only be used when it’s likely that a condition became true, such as after modifying a player’s score. [2]

Check actions have no additional fields.

3.6   cloak

Causes the direct object to become invisible. The cloak action can affect any object, even one that doesn’t have a cloaking device. The object will decloak if it uses its pulse or beam weapon, but not if it uses its special weapon.

Cloak actions have no additional fields.

3.7   condition

Enables all of the conditions listed in enable and disables the ones in disable. This can be used to script a situation in which events need to happen in sequence.

For example, if the player needs to visit two planets in a specific order, there could be two conditions, with the latter disabled. Upon visiting Example Alpha, the first condition would enable the second. Upon visiting Example Beta, the second condition would declare victory. (if the order doesn’t matter, using the score action might be easier)

Condition indexes are tied to a particular level, so the condition action should generally be used by other conditions, not by objects.

3.8   create

Creates count new objects of type base, centered on the direct object.

If count is null, creates 1 new object. If count is a range, picks a count randomly within the range, and creates nothing if the result is ≤0. For example, count: {begin: 1, end: 6} means to randomly create at least 1 and at most 5 new objects. count: {begin: -4, end: 2} means to create a new object with a 1 in 6 chance.

If relative_velocity is true, adds the current velocity of the direct object to that of the new objects. If relative_direction is true, adds the current direction of the direct object. Guns should set relative_direction when creating their projectiles. Turrets should set autotarget on their projectiles and not set relative_direction.

If inherit is set, the new object’s is ordered to target the direct object’s target. Otherwise, the new object is ordered to target the direct object. If the object is neutral or its target.order is false, then its target is cleared.

If distance is set, the new objects will be created at random distances up to the given amount.

(use of the within [3] and legacy_random [4] fields is not recommended. They exist only for compatibility with some Hera-created scenarios)

3.9   delay

Postpones further processing of the current action sequence until duration has passed. [5]

3.10   destroy

Destroys the direct object. If the direct object has a destroy.action, executes its destroy.action. Then, unless the direct object’s destroy.die is true, removes it from existence.

Destroy actions have no additional fields.

3.11   disable

Impairs control of the direct object for some length of time. Only meaningful for objects that think and attempt to control their movement (including players’ flagships). While control is impaired, there’s a chance that a pressed or released key might not register.

Takes a random duration in duration and divides it by the direct object’s mass. The direct object’s controls are impaired for this long. If the direct object’s controls were already impaired, the old remaining duration is replaced by the new duration.

If the remaining time an object is disabled is d, the likelihood that a key will fail to register is (d – ¼) ÷ d. Turning is disabled for the full duration.

For example, a Zerbilite’s collide.action has a disable action with duration: {begin: "0s", end: "3s"}. If a Zerbilite collides with an Ishiman carrier (mass: 2.0), it will disable the carrier for up to 1.5 seconds. If it disables the carrier for the full 1.5 seconds, the carrier will initially ignore ⅚ of keypresses, and regain control over time.

3.12   energize

Increases the current energy of the direct object by value. If that would increase the object’s energy past full, the balance is added to the object’s battery.

3.13   equip

Replaces one of the direct object’s weapons. Sets the weapon which to base, restoring it to full ammunition.

3.14   fire

Fires one of the direct object’s weapons. Fails if the direct object is not able to fire the weapon (insufficient ammo or energy, weapon fired too recently, or no weapon equipped in that slot).

3.15   flash

Causes the player’s entire screen to flash. Overlays the screen with a solid color for the duration.

3.16   group

Groups together multiple actions. Actions in the group are all affected by the if, and override of the group.

Group actions should never be reflexive (it would work, but be confusing).

3.17   heal

Adds value to the direct object’s health.

Positive values heal the direct object. Health is capped at the direct object’s maximum.

Negative values cause the direct object to take damage. If the direct object’s health would be decreased below 0, it is destroyed.

3.18   hold

Removes the direct object’s target and causes it to maintain its current position.

Hold actions have no additional fields.

3.19   key

Enables or disables the use of certain keys by the player. enable or disable is a list of strings that name keys. Some of the keys, like "mouse" are not really keys, but other kinds of player input that can be disabled.

By default, all keys are enabled.

3.20   land

Causes the direct object to land at its target. The object will shrink to nothingness, after which it will execute its expire.action with its target as the direct object.

Used (with reflexive) in the arrive.action for transports landing on planets or ships going through jump gates.

3.21   message

Displays message text at the bottom of the player’s screen. Each string in pages is a page of text that the player will see.

Strings can contain formatting characters like \\i.

id is optional. It is used only by the message condition.

3.22   morph

Changes the base type of the direct object. The object is reset and recreated with the defaults from base, preserving only:

• Owner
• Velocity and orientation
• Health, energy, and battery
• Cloaking (if active)
• Weapon ammunition (if keep_ammo is true)

The morph action can be used in many ways to create complicated behaviors. It can:

• Create an extended destruction sequence. In The Mothership Connection, the Cantharan gateship’s destroy.action morphs the gateship into a form that creates lots of smaller explosions before finally expiring.
• Activate a disabled object. In Captivating, the Bazidanese battleship starts in a “disabled” form and morphs into an active form when freed.
• Disable an active object. In Capture the Flagpod, a Grolk cruiser’s destroy.action morphs it into an inactive form and teleports it to a tractor moor.
• Enable or disable interactions. In Shoplifter 1, the Obish transport morphs between a form that can pick up prisoners and a form that can’t, depending on whether the transport is full.

3.23   move

Modifies the location of the direct object. The new location is relative to an origin, one of:

• "level" (the default), the center (0, 0) of the level,
• "subject", the location of the subject object, or
• "direct", the location of the direct object.

(in a reflexive action, modifies the location of the subject object, but "subject" and "direct" still have their original meanings)

Offsets the new location by to. This offset takes the scenario’s rotation into account. This is typically used with origin: "subject" to place an object at an absolute location.

If distance is set, the new location will additionally be offset by a random distance up to the given amount.

(use of the within [3] field is not recommended. It exists only for compatibility with some Hera-created scenarios)

3.24   occupy

Adds value to the occupation count of the direct object for the owner of the subject object. Requires that the direct object sets:

• occupy_count
• destroy.neutralize
• target.base

When a player’s occupation count on an object reaches occupy_count, that player takes control over the object. This is used in the factory scenario when EVATs take over stations.

3.25   pay

Adds value to a player’s cash reserves. If value is negative, reduces the player’s cash (but not below zero). If player is null, pays the direct object’s owner. If player is non-null, pays player.

3.26   play

Plays a sound. If sound is non-null, plays that sound. Otherwise, picks a sound at random from any.

Plays the sound at the given volume. Unless absolute is true, the sound’s origin is centered on the direct object. The sound’s volume is reduced proportionately to the player flagship’s distance from the sound’s origin. absolute sounds play at full volume no matter how far away the player’s flagship is.

Antares has a limited number of sound channels to play sounds with. priority and persistence affect how it decides when to stop a sound and allow a more important or recent sound to take over the channel. Higher priority makes it more likely that a sound will play, and longer persistence means it will be longer before another sound can take over its channel. The exact rules are:

• if the same sound is already playing at the same or lower volume, stop it and take over its channel. Otherwise,
• if any sound is playing at a lower volume, stop it and take over its channel. Otherwise,
• if any sound is playing at a lower priority, stop it and take its channel. Otherwise,
• if any sounds have been playing for longer than their persistence, stop and take the channel of the sound that is furthest past its persistence.

If Antares can’t find a suitable channel per the above rules, the sound doesn’t play.

3.27   push

Modifies the velocity of the direct object, applying the change in the direction that the subject object is facing.

If value is non-null, sets the direct object’s direction to match the direct object, and its speed to value (like the Cantharan gateship’s Shrikeolator).

If value is null, treats the push like a collision (like the Elejeetian Cruiser’s Onas Pulse):

1. Takes the difference between the two objects’ velocity.
2. Divides that change by the mass of the direct object.
3. Adds the modified difference to the direct object’s velocity.
4. Caps the direct object’s speed to its max_velocity.

See also: slow, speed, and stop.

3.28   remove

Removes the direct object from existence. Does not execute its destroy action.

Remove actions have no additional fields.

3.29   reveal

Reveals the hidden initial objects specified by initial.

“Revealing” actually means creating the object, so revealing an object executes its create action.

3.30   score

Adds value to the score counter. If counter.player is null, modifies the score of direct object’s owner.

3.31   select

Selects the given screen and line number in the player’s computer.

3.32   slow

Decreases the velocity of the direct object, without changing its direction. Multiplies the current velocity by value. For example, value: 0.75 means to decrease its current velocity by one quarter.

See also: push, speed, and stop.

3.33   spark

Creates count single-pixel visual effects, centered on the direct object and shooting away at speed up to velocity. If there is no direct object, they are created at the center of the screen. Up to 125 sparks may exist on-screen at any given time.

The sparks are hue-colored. They are initially bright and fade over time. After they have been around for the duration age, they disappear.

3.34   speed

Modifies the velocity of the direct object, without changing its direction. If relative is true, adds value to the object’s current velocity. Otherwise, sets its velocity to value.

See also: push, slow, and stop.

3.35   spin

Spins the direct object. Requires that:

• The direct object can turn (turn_rate is not null), and
• either:
  • the direct object is non-thinking, or
  • the direct object is disabled.

Picks a random turn velocity from value and sets it on the direct object. If a disabled direct object regains control, it will stop spinning.

Almost always used together with the disable action.

3.36   stop

Sets the velocity of the direct object to zero. This is equivalent to a slow or speed action with a value of 0.

Stop actions have no additional fields.

See also: push, slow, and speed.

3.37   target

Sets the subject object’s target to the direct object.

Target actions have no additional fields.

3.38   thrust

Sets the current thrust of the direct object. Only meaningful for non-thinking objects; thinking objects control their own thrust.

3.39   warp

Causes the direct object to enter warp. There is no delay or energy cost.

Warp actions have no additional fields.

3.40   win

Ends the level, displaying text in the mission debriefing.

In a solo level, if player is the human player, declares victory for the player. If next is non-null, unlocks that level and continues the game. If next is null, ends the game in victory.

In a solo level, if player is a non-human player, ends the level in defeat. The player will be given the option to retry or exit. next is ignored.

In a net level, declares victory for player. next is ignored.

3.41   zoom

Sets the player’s zoom level to value.