Stratagus Configuration Language Description: Triggers


         _________ __                 __                               
        /   _____//  |_____________ _/  |______     ____  __ __  ______
        \_____  \\   __\_  __ \__  \\   __\__  \   / ___\|  |  \/  ___/
        /        \|  |  |  | \// __ \|  |  / __ \_/ /_/  >  |  /\___ \ 
       /_______  /|__|  |__|  (____  /__| (____  /\___  /|____//____  >
               \/                  \/          \//_____/            \/ 
    ______________________                           ______________________
			  T H E   W A R   B E G I N S
	   Stratagus - A free fantasy real time strategy game engine

(C) Copyright 2002-2006 by The Stratagus Project. Distributed under the "GNU General Public License"


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 7669 2006-11-05 20:59:47Z feber $
All trademarks and copyrights on this page are owned by their respective owners.
(c) 2002-2006 by The Stratagus Project