# Bos Wars Scripting API: Triggers

Stratagus FAQ PREV NEXT LUA Index

ActionDefeat ActionDraw ActionSetTimer ActionStartTimer ActionStopTimer ActionVictory ActionWait AddTrigger IfNearUnit GetNumOpponents IfRescuedNearUnit GetTimer GetNumUnitsAt

## Intro - Introduction to trigger functions and variables

Everything around triggers.
Triggers are a couple of (condition, action). Each cycles in the game, if the condition of the active triggers is true, then the associated actions are executed. There are used for condition's victory and could be usefull to add special actions when an event occurs.
Some functions use generic data which can be compute during the game like dynamic attacker characteristic. So following present some generic terms and how to use it.

NumberDesc
  Represent a number. it could be :
  number
    direct value. Or value which are not recompute during the game.
  a lua function
    A Lua function (which take no argument) which returns the value.
  Add(NumberDesc, NumberDesc)
    the sum of two numbers.
    Note: prefer do (5 + 9) if you can. But you have to use it for Add(Defender("Armor"), 5) because the left size must be recompute.
  Sub(NumberDesc, NumberDesc)
    It is the difference between the two numbers.
  Mul(NumberDesc, NumberDesc)
    It is the product between the two numbers.
  Div(NumberDesc, NumberDesc)
    It is the division between the two numbers. If the second number is null, return 0 value.
  Min(NumberDesc, NumberDesc)
    It is the minimum between the two numbers.
  Max(NumberDesc, NumberDesc)
    It is the maximum between the two numbers.
  GreaterThan(NumberDesc1, NumberDesc2)
    It is 1 if NumberDesc1 > NumberDesc2 else 0.
  LessThan(NumberDesc1, NumberDesc2)
    It is 1 if NumberDesc1 < NumberDesc2 else 0.
  GreaterThanOrEq(NumberDesc1, NumberDesc2)
    It is 1 if NumberDesc1 >= NumberDesc2 else 0.
  LessThanOrEq(NumberDesc1, NumberDesc2)
    It is 1 if NumberDesc1 <= NumberDesc2 else 0.
  Equal(NumberDesc1, NumberDesc2)
    It is 1 if NumberDesc1 == NumberDesc2 else 0.
  NotEqual(NumberDesc1, NumberDesc2)
    It is 1 if NumberDesc1 <> NumberDesc2 else 0.
  VideoTextLength(Font, StringDesc)
    Size in pixel of the text with the given font.
  StringFind(StringDesc, 'c')
    First occurance of the character 'c' in the text. (Pos begin at 0). return -1 in 'c' is not in the string.
  Rand(NumberDesc)
    It is a random value in [0..Number - 1].
  AttackerVar("Variable" [, Component [, Location]])
    It is the the value of the component of the variable for the attacker (See UnitDesc) unit (if any, else 0). Note that Variable is defined with SetVariables(). And component is one of the following, default is "Value" :
    "Enable"
      1 if enable, 0 else.
    "Value"
      Value of the variable.
    "Max"
      value of max of the variable.
    "Increase"
      Increase value of the variable.
    Location is what type of variable do you want, default is "Unit".
    "Unit"
      value for unit itself.
    "Initial"
      Value initial for the unit (without upgrade).
    "Type"
      value for unit type with upgrade.
  DefenderVar("Variable" [, Component [, Location]])
    Like of Attacker but for the Defender unit.
  ActiveUnitVar("Variable" [, Component [, Location]])
    Like of Attacker but for the Active unit.
StringDesc
  Represent a string. it could be :
  "string"
    direct value. Or value which are not recompute during the game.
  a lua function
    A Lua function (which take no argument) which returns the value.
  Concat(StringDesc, StringDesc[, StringDesc, ...])
    Concatenation of several strings.
  String(NumberDesc)
    Convert a number to string.
  InverseVideo(StringDesc)
    Set string in InverseVideo mode.
  UnitName(UnitDesc)
    Name of the Unit
  SubString(StringDesc, NumberDesc begin[, NumberDesc end])
    Return the substring which begin at the 'begin' character ([0-lenght(s)]) and end at the 'end' character of the given string. default value for 'end' is the end of the initial string.
  Line(NumberDesc line, StringDesc[, NumberDesc maxlen[, Font] ])
    Return the line (which is a subtring) of a multi-line string, maxlen is the size maximum of the string. If Font is specified, maxlen used VideoTextLenght, else it uses number of characters.
  GameInfo("arg")
    Represent a string of the game. "arg" could be :
    "Tips"
      Current tip.
    "Objectives"
      All the objectives of the games.
UnitDesc
  Represent a unit. It could be :
  "Attacker"
    Unit which attack.
  "Defender"
    Unit which is attacked.
  "Active"
    First unit selected or unit under cursor.

## Functions

### ActionDefeat()

The player lose the game.

#### Example

    -- Adds a trigger. If the player on the console has 0 units then he loses.
    AddTrigger(
      function() return IfUnit("this", "==", 0, "all") end,
      function() return ActionDefeat() end)

### ActionDraw()

The condition player is set to draw. (NOT SUPPORTED)

### ActionSetTimer(cycles, increasing)

Set the timer.

cycles
  The number of cycles (default setting is 30 cycles per second).
increasing
  Set this to 1 if you want the timer to increase, set it to 0 for decreasing.

#### Example

    -- Sets the timer to 9000 cycles (300 seconds or 5 minutes) and decreasing.
    ActionSetTimer(9000, 0)

### ActionStartTimer()

Start the timer.

### ActionStopTimer()

Stop the timer.

### ActionVictory()

The condition player is set to victory.

#### Example

    -- Adds a trigger. If the player on the console has killed all his
    -- opponents he won.
    AddTrigger(
      function() return IfOpponents("this", "==", 0) end,
      function() return ActionVictory() end)

### ActionWait(time-ms)

Causes the trigger to wait a number of milliseconds before reexamine this trigger.

time-ms
  Minimum number of milliseconds to wait.

### AddTrigger(condition, action)

Creates a new trigger.
FIXME: in code, action could be a table, but crash on execution..

condition
  Function which must return true to execute the condition. It is tested every FIXME.
action
  Function executed when condition return true. The trigger remains active if the action returns true and is removed if the action returns false.

#### Example

    -- Adds a trigger. If the player on the console has killed all his
    -- opponents he won.
    AddTrigger(
      function() return IfOpponents("this", "==", 0) end,
      function() return ActionVictory() end)

### IfNearUnit(player, op, quantity, unit1, unit2)

Return true if the number of unit1 near of unit2 "op" quantity is true for the player.

player

      0 .. 16     Player number
      "any"       Matches any player
      "this"      Player on the local computer, Human player in the campaign.

op

      "=="         operator equal
      ">"          operator greater than
      ">="         operator greater than or equal
      "<"          operator less than
      "<="         operator less than or equal

quantity
  Number to compare with number of units
unit1

      unit-name    Unit type of this name
      "any"        Matches any unit type
      "all"        All units (sum of units and buildings)
      "units"      All non building units
      "building"   All building units

unit2
  unit-name, so unit type of this name.

#### Example

    -- true when the player on the console has 6 archers near one of his/her circle of power.
    IfNearUnit("this", "==", 6, "unit-archer", "unit-circle-of-power")

### GetNumOpponents(player)

Returns the number of opponent's for the given player.

player

      0 .. 16     Player number

#### Example

    -- You win when you have no opponents left.
    if (GetNumOpponents(GetThisPlayer()) == 0) then
         ActionVictory()

### IfRescuedNearUnit(player, op, quantity, unit1, unit2)

Return true if the number of rescued-units of type unit1 which are currently near of unit2 of the player "op" quantity is true.

player

      0 .. 16     Player number
      "any"       Matches any player
      "this"      Player on the local computer, Human player in the campaign.

op

      "=="         operator equal
      ">"          operator greater than
      ">="         operator greater than or equal
      "<"          operator less than
      "<="         operator less than or equal

quantity
  Number to compare with number of rescued-unit
unit1

      unit-name    Unit type of this name
      "any"        Matches any unit type
      "all"        All units (sum of units and buildings)
      "units"      All non building units
      "building"   All building units

unit2
  unit-name, so unit type of this name.

#### Example

    -- True when The player on the console has 1 rescued archer near the circle of power.
    IfRescuedNearUnit("this", "==", 1, "unit-archer", "unit-circle-of-power")

### GetTimer()

Return the number of cycles the timer ran.

#### Example

    -- True when the timer is at 17 cycles.
    time = GetTimer() == 17

### GetNumUnitsAt(player, unit-type, {x1, y1}, {x2, y2})

Return the number of units of type unit-type which are in the rectangle defined with (x1, y1, x2, y2) of the player.

player

      0 .. 16     Player number

unit

      unit-name    Unit type of this name
      "any"        Matches any unit type
      "all"        All units (sum of units and buildings)
      "units"      All non building units
      "building"   All building units

{x1, y1}
  Upper left corner
{x2, y2}
  Lower right corner

#### Example

    -- True when the player on the console has at least 8 archers in the rectangle
    -- (10 10) to (12 14).
    GetNumUnitsAt(GetThisPlayer(), "unit-archer", {10, 10}, {12, 14}) >= 8

Last changed: $Id: triggers.html 8569 2007-02-10 23:21:43Z feb $
All trademarks and copyrights on this page are owned by their respective owners.