GAE boasts a large number of Lua functions that can enhance scenarios. This page lists and documents all functions, categorized by their purpose, but does not teach how to code scenarios. Lua is the scripting language for Glest's scenarios, and GAE expands further what the original Glest had.
Game Control[]
Game control functions directly modify the game or its results. For example, you can disable to AI so it doesn't mess up your commands, or can set a player as a winner to finish the scenario.
disableAi(factionIndex)[]
Disables AI control of a faction.
Parameters:
- factionIndex: the index of the faction to disable the AI on.
setPlayerAsWinner(factionIndex)[]
Sets a faction as having won the game.
Parameters:
- factionIndex: the index of the faction to set as a winner.
endGame()[]
Finishes the game.
GUI Control[]
Controlling the GUI is generally done just as a scenic device, and can be used for cutscenes, such as to make the camera pan on our base while locking the user's input, so they don't mess up the cut scene.
lockInput()[]
Prevents any user input to the game, useful for 'cut-scenes'
unlockInput()[]
If previously locked, unlocks user input.
setCameraPosition(pos)[]
Move the camera so that the cell at pos is in the centre of the view.
Parameters:
- pos: a position to move the camera to, a tables with two values { x, y }
setCameraMotion(move, angle, linFCount, angFCount, linFDelay, angFDelay)[]
Move the camera smoothly to a new position and orientation.
Parameters:
- move: a position to move the camera to, a table with two values { x, y }
- angle: a pair of angles describing the new orientation, a table { vertical, horizontal }
- linFCount: number of world frames the linear movement should take
- angFCount: number of world frames the rotation should take
- linFDelay: the number of frames to delay until starting the linear movement
- angFDelay: the number of frames to delay until the rotation begins
unfogMap(time, area)[]
Reveals an 'area' of the map, and leaves it visible for (approximately) 'time' seconds.
Parameters:
- time: an approximate number of seconds to leave the area revealed
- area: a rectangular area, a table with four values { x, y, w, h }
User Feedback[]
showMessage(text, header)[]
Displays a message to the user in a messagebox that must be dismissed, the game is paused when the message is shown.
Parameters:
- text: A string identifying the text to look up in the lang file, this is the 'body' of the message.
- header: A string, looked up in the lang file, for the message box 'title-bar'.
setDisplayText(text)[]
Displays a message to the user at the top of the screen, remains until setDisplayText() is called again, or clearDisplayText() is called.
Parameters:
- text: A string identifying the text to look up in the lang file, the text for to display.
clearDisplayText()[]
Clears the display message from the top of the screen.
addActor(name, color)[]
or addActor(name, r, g, b)
Used to add an actor who can create dialogue messages with the addDialog() function. Each actor is given a name and a colour which will be assigned to their messages.
Parameters:
- name: is a string containing the name for the actor to add.
- color: is a string in hex rgb format. One of either color or the r, g, and b values can be used.
- r, g, b: are integers containing the rgb color value. One of either color or the r, g, and b values can be used.
addDialog(actor, message)[]
Used with addActor() to create a coloured dialog message in the console area.
Parameters:
- actor: a string containing the actor name. Should be the same name as defined with addActor().
- message: a string containing the message to print. This will be looked up in the language file.
Unit creation and Resource/Upgrade hand-outs[]
Unit creation functions can be used to create a unit, and thus tend to be the most commonly used Lua command. These functions can also give upgrades, resources, etc.
createUnit(type, factionIndex, pos)[]
Create a unit a unit for a faction at (or near) pos.
Parameters:
- type: The unit type to create
- factionIndex: The index of the faction to create the unit for
- pos: a position to create the unit at (or near), array of two elements { x, y }
giveResource(type, factionIndex, amount)[]
Gifts some resources to a faction (don't forget to make sure they can store them!)
Parameters:
- type: The resource type
- factionIndex: The index of the faction to give resources to
- amount: the amount of the resource to give
giveUpgrade(factionIndex, upgrade)[]
Gifts an upgrade to a faction
Parameters:
- factionIndex: The index of the faction to give the upgrade to
- upgrade: the name of the upgrade
damageUnit(unitId, hp)[]
Deals a set amount of damage to a unit
Parameters:
- unitId: The id of unfortunate unit
- hp: the amount of hit-points damage to inflict
destroyUnit(unitId, clean)[]
Destroys a unit
Parameters:
- unitId: The id of the doomed unit
- clean: optional (default = false), if true the unit is removed 'cleanly' with no die animation or corpse
Unit commands[]
The following functions issue commands to units, as of 0.2.13 they all return boolean values, indicating wether the command issue was successful. They are handy as they can tell a unit to attack a location, start producing units, etc.
givePositionCommand(unitId, command, pos)[]
Give a position based command to a unit
Parameters:
- unitId: The ID of the unit to give the command to
- command: the name of the command to give, one of 'move', 'attack' or 'patrol'
- pos: the command's target position { x, y }
giveProductionCommand(unitId, unitType)[]
Give a poduce or morph command to a unit
Parameters:
- unitId: The ID of the unit to give the command to
- unitType: the type of unit to produce
giveStopCommand(unitId, command)[]
Give stop command to a unit
Parameters:
- unitId: The ID of the unit to give the command to
- command: the name of the command to give, one of 'stop' or 'attack-stopped'
giveTargetCommand(unitId, command, targetId)[]
Give a target based command to a unit
Parameters:
- unitId: The ID of the unit to give the command to
- command: the name of the command to give, one of 'attack', 'repair' or 'guard'
- targetId: the command's target unit ID.
giveUpgradeCommand(unitId, upgrade)[]
Give an upgrade command to a unit.
Parameters:
- unitId: The ID of the unit to give the command to
- upgrade: the Upgrade to produce
Timers[]
Timers are useful for creating timed functions, such as creating new units every x seconds, or setting a time limit on the game. It can also be used to check special types of triggers by frequently checking if a statement is true.
setTimer(name, type, interval, periodic)[]
Set a timer, a handler in XML has the form <timer name="myTimerName"> -- </timer>, or can be defined in Lua files (or the startup 'handler' in XML) as function timer_myTimerName() -- end
Parameters:
- name: The name of the timer, used to define your callback function
- type: The type timer, either "game" or "real", indicating measured in game time or real time
- interval: The timer interval, number of world frames for 'game' timers (40 a second at normal game speed) or the number of milliseconds for 'real' timers (but don't bother trying for really accurate ones.. they wont be, and neither game nor real timers will fire while the game is paused.
- periodic: true or false, indicating whether this is a repeating timer or a one-off
stopTimer(name)[]
Stops a named timer.
Parameters:
- name: The name of the timer to stop
Regions, Events and Triggers[]
Regions, events, and triggers are generally used to provide a method of checking for an event occuring. For example, you could have something happen when the player's units reach a certain point of the game, or even set reaching a location as being the objective of the scenario.
registerRegion(name, area)[]
Register a region with the trigger manager, only rectangular areas are supported currently.
Parameters:
- name: The name of the region
- area: a rectangle { x, y, w, h }
registerEvent(name)[]
Register an event with the trigger manager. The handler is then <unitEvent name="myEvent">--</unitEvent> in XML, or function unitEvent_myEvent(unit_id, user_data) -- end in external lua files. The unit_id parameter is the ID of the unit who triggered the event. The user_data parameter may be omitted if you are not using user data, and the parameters may be named as you see fit. If you use the XML embedded handler, the parameters will be called unit_id and user_data.
Parameters:
- name: The name of the event
setUnitTrigger(unitId, condition, event)[]
Set a trigger on a unit.
Parameters:
- unitId: The ID of the unit to set the trigger on
- condition: The trigger condition, can be,
- 'attacked' : trigger when the unit is attacked
- 'death' : triggers when the unit dies
- 'enemy-sighted' : not implemented yet!
- 'command_callback' : trigger will fire when the unit finishes its current command (not trust-worthy yet.)
- 'region=name' : will trigger when unit enters the registered region 'name'
- 'hp-below=x' : will trigger when the unit's HP falls below x
- 'hp-above=x' : will trigger when the unit's HP raises above x
- event: The event to fire when the trigger condition is met
setUnitTriggerX(unitId, condition, event, userData)[]
Set a trigger on a unit with some user data attached.
Parameters:
- unitId: see setUnitTrigger()
- condition: see setUnitTrigger()
- event: see setUnitTrigger()
- userData: a number, your actual data or an index to a table containing 'richer' information
setFactionTrigger(factionIndex, condition, event, userData)[]
Set a trigger to go off when any unit of a faction meets the condition.
Parameters:
- factionIndex: The index of the faction
- condition: 'region=name' is currently the only faction trigger condition supported
- event: the event to trigger
- userData: a number, your actual data or an index to a table containing 'richer' information
Queries[]
Queries are a method of checking for values. For example, we might check a unit's faction to see whom it belongs to, then give cause an event to occur based on this.
playerName(factionIndex)[]
Returns the name of a factions player. Parameters:
- factionIndex: The index of the faction
factionTypeName(factionIndex)[]
Returns the type name of a faction. Parameters:
- factionIndex: The index of the faction
scenarioDir()[]
Returns a string of the path from the glest binary to the scenario's directory.
startLocation(factionIndex)[]
Returns a start location, as an array of two elements.
Parameters:
- factionIndex: The index of the faction
unitPosition(unitId)[]
Returns the location of a unit, as an array of two elements.
Parameters:
- unitId: The ID of the unit.
unitFaction(unitId)[]
Returns the faction index of a unit.
Parameters:
- unitId: The ID of the unit.
resourceAmount(resource, factionIndex)[]
Returns the amount of a resource a player has.
Parameters:
- resource: A string identifying the resource of interest
- factionIndex: The index of the faction
lastCreatedUnitName()[]
Returns the type name of the last created unit.
lastCreatedUnit()[]
Returns the ID of the last created unit.
lastDeadUnitName()[]
Returns the type name of the last unit to die.
lastDeadUnit()[]
Returns the ID of the last unit to die.
unitCount(factionIndex)[]
Returns the number of units a player has.
Parameters:
- factionIndex: The index of the faction
unitCountOfType(factionIndex, type)[]
Returns the number of units of a specific type a player has.
Parameters:
- factionIndex: The index of the faction
- type: String identifying the unit type of interest
Debugging Functions[]
debugLog(msg)[]
Writes a message to glestadv-error.log.
Parameters:
- msg: A string to write to the error log
consoleMsg(msg)[]
Writes a message to the console.
Parameters:
- msg: A string to write to the console
hilightCell(pos)[]
Hilights a cell.
Parameters:
- pos: The position to hilight { x, y }
hilightRegion(region)[]
Hilights a region, previously registered with registerRegion().
Parameters:
- region: The name of the region to hilight
clearHilights()[]
Clears all hilights set with hilightCell() and/or hilightRegion().