Condition

A condition triggers events in a level. Each condition has a when property, which specifies what to watch for, and an action sequence that specifies what to do when the condition is triggered. There are many types of conditions, such as destroyed, owner and time.

Every level has an array of conditions. Because conditions are tied to a level, they can only refer to that level’s initials, not to objects created during game play.

Conditions are checked once per second, or whenever a check action runs.

Example condition

1 Definition
- 1.1 disabled
- 1.2 persistent
- 1.3 subject, direct
- 1.4 when
  - 1.4.1 op
2 Types
- 2.1 autopilot
- 2.2 building
- 2.3 cash
- 2.4 computer
- 2.5 count
- 2.6 destroyed
- 2.7 distance
- 2.8 health
- 2.9 identity
- 2.10 message
- 2.11 owner
- 2.12 score
- 2.13 ships
- 2.14 speed
- 2.15 target
- 2.16 time
- 2.17 zoom
3 Footnotes

1 Definition

A condition is a procyon value with the following fields:

Field	Req?	Type
disabled	no	boolean
persistent	no	boolean
when	yes	when
subject	no	object reference
direct	no	object reference
action	yes	array of actions

1.1 disabled

If true, the condition is not initially enabled and will not trigger. Conditions can be enabled or disabled with the condition action. Conditions are also disabled after they trigger, unless they are persistent.

1.2 persistent

If true, the condition does not become disabled after it triggers.

1.3 subject, direct

The subject object and direct object that will be used if the condition’s action executes.

1.4 when

A condition’s “when” block is a map with the following fields, plus any fields appropriate to its type:

Field	Req?	Type
type	yes	“autopilot”, “building”, “cash”, “computer”, “count”, “score”, “destroyed”, “distance”, “health”, “identity”, “message”, “owner”, “ships”, “speed”, “target”, “time”, or “zoom”

1.4.1 op

All “when” blocks have a field called op. This determines the comparison to make. All conditions support:

"eq" (equal)
"ne" (not equal)

Some conditions additionally support:

"lt" (less than)
"gt" (greater than)
"le" (less than or equal)
"ge" (greater than or equal)

2 Types

2.1 autopilot

Field	Req?	Type
op	yes	“eq” or “ne”
player	yes	index of a player
value	yes	boolean

Compares the given player’s autopilot status (true = on autopilot, false = not on autopilot) to value.

Preconditions: player is an active, human player.

2.2 building

Field	Req?	Type
op	yes	“eq” or “ne”
player	yes	index of a player
value	yes	boolean

Compares the given player’s build status (true = building something, false = not building anything) to value.

Preconditions: player is an active player with a build object.

2.3 cash

Field	Req?	Type
op	yes	“eq”, “ne”, “lt”, “gt”, “le”, or “ge”
player	yes	index of a player
value	yes	money

Compares the given player’s cash reserves to value.

Preconditions: player is an active player.

2.4 computer

Field	Req?	Type
op	yes	“eq” or “ne”
screen	yes	“main”, “build”, “special”, “message”, or “status”
line	no	integer

Compares the local player’s computer screen to screen. If line is not null, compares the local players screen and line to (screen, line).

Warning

not net-safe. Use only in solo levels.

2.5 count

Field	Req?	Type
op	yes	“eq”, “ne”, “lt”, “gt”, “le”, or “ge”
value	yes	integer
of	yes	array of conditions

Evaluates the sub-conditions in of and compares the count of sub-conditions that are true to value. This can simulate different logical operators, like “all”, “any”, or “not”.

Some example count conditions:

First player owns all three planets:

when:
  type:   "count"
  op:     "eq"
  value:  3
  of:
    * type:    "owner"
      op:      "eq"
      object:  {initial: 0}
      player:  0
    * type:    "owner"
      op:      "eq"
      object:  {initial: 1}
      player:  0
    * type:    "owner"
      op:      "eq"
      object:  {initial: 2}
      player:  0

Either or both of the first player’s carriers has been destroyed:

when:
  type:   "count"
  op:     "ge"
  value:  1
  of:
    * type:    "destroyed"
      op:      "eq"
      object:  {initial: 3}
      value:   true
    * type:    "destroyed"
      op:      "eq"
      object:  {initial: 4}
      value:   true

2.6 destroyed

Field	Req?	Type
op	yes	“eq” or “ne”
object	yes	object reference
value	yes	boolean

Compares object’s state (true = destroyed, false = not destroyed) to value.

The comparison really considers whether the object exists or not, so a hidden initial that has yet to be revealed counts as “destroyed” (true) for the purposes of this condition.

2.7 distance

Field	Req?	Type
op	yes	“eq”, “ne”, “lt”, “gt”, “le”, or “ge”
from	yes	object reference
to	yes	object reference
value	yes	number

Compares the cartesian distance between the two objects from and to to value.

Preconditions: the objects from and to both exist.

2.8 health

Field	Req?	Type
op	yes	“eq”, “ne”, “lt”, “gt”, “le”, or “ge”
object	yes	object reference
value	yes	number

Compares object’s health fraction to value. value: 1.0 means “full health”, value: 0.5 means “half health”, and value: 0 is equivalent to the destroyed condition.

2.9 identity

Field	Req?	Type
op	yes	“eq” or “ne”
a	yes	object reference
b	yes	object reference

Compares the identity of the objects a and b. This is usually not interesting if both a and b reference initials, but can be useful with other forms of object references:

when:
  type:  "object"
  op:    "eq"
  a:     {"flagship": 0}
  b:     {"initial": 1}

Preconditions: the objects a and b both exist.

2.10 message

Field	Req?	Type
op	yes	“eq” or “ne”
id	yes	integer
page	yes	integer

Compares the message ID and page the local player is viewing to (id, page).

Warning

not net-safe. Use only in solo levels.

Preconditions: the local player is viewing a message.

2.11 owner

Field	Req?	Type
op	yes	“eq” or “ne”
object	yes	object reference
player	yes	index of a player

Compares the owner of object to player.

Preconditions: object exists.

2.12 score

Field	Req?	Type
op	yes	“eq”, “ne”, “lt”, “gt”, “le”, or “ge”
counter	yes	counter
value	yes	integer

Compares the value of the counter counter to value.

2.13 ships

Field	Req?	Type
op	yes	“eq”, “ne”, “lt”, “gt”, “le”, or “ge”
player	yes	index of a player
value	yes	integer

Compares the ship count of player to value.

2.14 speed

Field	Req?	Type
op	yes	“eq”, “ne”, “lt”, “gt”, “le”, or “ge”
object	yes	object reference
value	yes	number

Compares the speed of object to value.

Preconditions: object exists.

2.15 target

Field	Req?	Type
op	yes	“eq” or “ne”
object	yes	object reference
target	yes	object reference

Compares the target of object to the object target.

Preconditions: object and target both exist.

2.16 time

Field	Req?	Type
op	yes	“eq”, “ne”, “lt”, “gt”, “le”, or “ge”
duration	yes	duration
legacy_start_time	no	boolean

Compares the elapsed game time to duration. If the level has a start_time setup phase, then positive durations indicate time during actual gameplay, and negative durations indicate setup time.

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

2.17 zoom

Field	Req?	Type
op	yes	“eq”, “ne”, “lt”, “gt”, “le”, or “ge”
value	yes	“2:1”, “1:1”, “1:2”, “1:4”, “1:16”, “foe”, “object”, or “all”

Compares the local player’s zoom level to zoom.

Warning

not net-safe. Use only in solo levels.

3 Footnotes

[1]	In Ares, all `duration` values were positive, and the setup time in a level with start_time counted for ⅓ as much as gameplay time. `legacy_start_time: true` preserves this behavior for compatibility.