Fandom

Glest

GAE/Lua

< GAE

275pages on
this wiki
Add New Page
Talk0 Share

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 Edit

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) Edit

Disables AI control of a faction.

Parameters:

  • factionIndex: the index of the faction to disable the AI on.

setPlayerAsWinner(factionIndex) Edit

Sets a faction as having won the game.

Parameters:

  • factionIndex: the index of the faction to set as a winner.

endGame() Edit

Finishes the game.

GUI Control Edit

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() Edit

Prevents any user input to the game, useful for 'cut-scenes'

unlockInput() Edit

If previously locked, unlocks user input.

setCameraPosition(pos) Edit

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) Edit

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) Edit

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 Edit

showMessage(text, header) Edit

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) Edit

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() Edit

Clears the display message from the top of the screen.

addActor(name, color) Edit

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) Edit

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 Edit

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) Edit

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) Edit

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) Edit

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) Edit

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) Edit

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 Edit

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) Edit

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) Edit

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) Edit

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) Edit

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) Edit

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 Edit

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) Edit

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) Edit

Stops a named timer.

Parameters:

  • name: The name of the timer to stop


Regions, Events and Triggers Edit

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) Edit

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) Edit

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) Edit

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) Edit

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) Edit

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 Edit

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) Edit

Returns the name of a factions player. Parameters:

  • factionIndex: The index of the faction

factionTypeName(factionIndex) Edit

Returns the type name of a faction. Parameters:

  • factionIndex: The index of the faction

scenarioDir() Edit

Returns a string of the path from the glest binary to the scenario's directory.

startLocation(factionIndex) Edit

Returns a start location, as an array of two elements.

Parameters:

  • factionIndex: The index of the faction

unitPosition(unitId) Edit

Returns the location of a unit, as an array of two elements.

Parameters:

  • unitId: The ID of the unit.

unitFaction(unitId) Edit

Returns the faction index of a unit.

Parameters:

  • unitId: The ID of the unit.

resourceAmount(resource, factionIndex) Edit

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() Edit

Returns the type name of the last created unit.

lastCreatedUnit() Edit

Returns the ID of the last created unit.

lastDeadUnitName() Edit

Returns the type name of the last unit to die.

lastDeadUnit() Edit

Returns the ID of the last unit to die.

unitCount(factionIndex) Edit

Returns the number of units a player has.

Parameters:

  • factionIndex: The index of the faction

unitCountOfType(factionIndex, type) Edit

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 Edit

debugLog(msg) Edit

Writes a message to glestadv-error.log.

Parameters:

  • msg: A string to write to the error log

consoleMsg(msg) Edit

Writes a message to the console.

Parameters:

  • msg: A string to write to the console

hilightCell(pos) Edit

Hilights a cell.

Parameters:

  • pos: The position to hilight { x, y }

hilightRegion(region) Edit

Hilights a region, previously registered with registerRegion().

Parameters:

  • region: The name of the region to hilight

clearHilights() Edit

Clears all hilights set with hilightCell() and/or hilightRegion().

See AlsoEdit

External LinksEdit

Ad blocker interference detected!


Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.