Skip to content
This repository was archived by the owner on Aug 1, 2025. It is now read-only.

09. Lua Scripting API

Jump to bottom
matthew snoddy edited this page Jul 24, 2020 · 14 revisions

This page details all the functions that are available in Lua scripts.

The unit/infantry/building names and rule names/values used in Lua can all be found here.

Note: Parameter values are not case sensitive

Events

The NCO mod will call event handlers when a certain events happen in game. These allow configuring the game based on the scenario being played, the player side (GDI/NOD) etc. See here for more info.

onScenarioStart

Register an event handler that will be called when a user starts a new scenario

onScenarioStart(function(scenarioName)
  log(string.format("Scenario: %s"), scenarioName)

  -- do awesome stuff...
end)

Parameters: callback - a event handler function which accepts one parameter:

  • scenarioName string in the format SC<SIDE><SCENARIO_NUMBER><MAP_CHOICE>, for example SCB04EA is NOD mission 4 in the east

Returns: nothing

onSaveLoad

Register an event handler that will be called when a user loads a save game, this is useful because rules set on scenario load are not preserved in a save game (you will need to set them again)

onSaveLoad(function(playerHouse, scenarioNumber)
  log(string.format("%s Scenario: %d"), playerHouse, scenarioNumber)

  -- do awesome stuff...
end)

Parameters: callback - a event handler function which accepts two parameters:

  • playerHouse save game player side: GOODGUY, BADGUY etc.
  • scenarioNumber save game scenario number

Returns: nothing

onGameTick

Register an event handler that will be called as the game plays, every few hundred milliseconds or so. This is useful monitor the state of the game, change rules as the scenario progresses and print messages to the user ingame.

Note: The interval in milliseconds that this event is fired at is configurable using the GameTickIntervalInMs rule, see the RULES.INI Guide

onGameTick(function()
  log("Game tick event fired")

  -- do awesome stuff...
end)

Parameters: nothing

Returns: nothing

Object Info

These functions give you information about the types of infantry, units, aircraft and buildings.

getWeaponTypes

Get a list of all weapon types in the game

getWeaponTypes()

Parameters: none

Returns: A table containing all the Weapon names (FLAMETHROWER, PISTOL etc.)

getBulletTypes

Get a list of all bullet types in the game

getBulletTypes()

Parameters: none

Returns: A table containing all the Bullet names (BULLET, S.S.M etc.)

getWarheadTypes

Get a list of all warhead types in the game

getWarheadTypes()

Parameters: none

Returns: A table containing all the Warhead names (HE, FIRE etc.)

getInfantryTypes

Get a list of all Infantry types in the game

getInfantryTypes()

Parameters: none

Returns: A table containing all the Infantry names (E1, RMBO etc.)

getUnitTypes

Get a list of all Unit types in the game

getUnitTypes()

Parameters: none

Returns: A table containing all the Unit names (MVC, STNK etc.)

getAircraftTypes

Get a list of all Aircraft types in the game

getAircraftTypes()

Parameters: none

Returns: A table containing all the Aircraft names (ORCA etc.)

getBuildingTypes

Get a list of all Building types in the game

getBuildingTypes()

Parameters: none

Returns: A table containing all the Building names (FACT, HPAD etc.)

Rule Info

These functions give you the names of available rules for specific game object types.

getGameRuleNames

Get a list of all rules that can be set for the [Game] section of the INI file

getGameRuleNames()

Parameters: none

Returns: A table containing all the Game rule names (AircraftRepairFactor, MaxHarvesterCapacity etc.)

getWeaponRuleNames

Get a list of all rules that can be set for Weapon types

getWeaponRuleNames()

Parameters: none

Returns: A table containing all the Weapon rule names (Damage, Range etc.)

getInfantryRuleNames

Get a list of all rules that can be set for Infantry types

getInfantryRuleNames()

Parameters: none

Returns: A table containing all the Infantry rule names (Speed, IsCivilian etc.)

getUnitRuleNames

Get a list of all rules that can be set for Unit types

getUnitRuleNames()

Parameters: none

Returns: A table containing all the Unit rule names (CanHarvest, CanCloak etc.)

getAircraftRuleNames

Get a list of all rules that can be set for Aircraft types

getAircraftRuleNames()

Parameters: none

Returns: A table containing all the Aircraft rule names (CantHover, RateOfTurn etc.)

getBuildingRuleNames

Get a list of all rules that can be set for Building types

getBuildingRuleNames()

Parameters: none

Returns: A table containing all the Building rule names (Factory, PowerOutput etc.)

Read/Write Rules

These functions allow you to get current rule values and set them at runtime.

getGameRule

Get the value for a rule found in the [Game] section of the Rules

getGameRule("HideApcFromNod")

Parameters:

  • ruleName

Returns: The value of the rule as a string/boolean/number - this will match the data type found in RULES.INI. NOTE: if the game rule is not present in either RULES.INI or RULES-DEFAULT.INI this may return nil as the defaults are stored in those files.

setGameRule

Set the value for a rule found in the [Game] section of the Rules

setGameRule("OnlyGdiCanUseIonCannon", false)

Parameters:

  • ruleName
  • ruleValue

Returns: nothing

getWeaponRule

Get the value of a rule for a given Weapon type

getInfantryRule("DRAGON", "RateOfFire")

Parameters:

  • weaponType
  • ruleName

Returns: The value of the rule as a string/boolean/number - this will match the data type found in RULES.INI

setWeaponRule

Set the value of a rule for a given Weapon type

setWeaponRule("CHEMSPRAY", "Damage", 160)

Parameters:

  • weaponType
  • ruleName
  • ruleValue

Returns: nothing

getInfantryRule

Get the value of a rule for a given Infantry type

getInfantryRule("E6", "CanCapture")

Parameters:

  • infantryType
  • ruleName

Returns: The value of the rule as a string/boolean/number - this will match the data type found in RULES.INI

setInfantryRule

Set the value of a rule for a given Infantry type

setInfantryRule("RMBO", "PrimaryWeapon", "OBELISK_LASER")

Parameters:

  • infantryType
  • ruleName
  • ruleValue

Returns: nothing

getUnitRule

Get the value of a rule for a given Unit type

getInfantryRule("APC", "PrimaryWeapon")

Parameters:

  • unitType
  • ruleName

Returns: The value of the rule as a string/boolean/number - this will match the data type found in RULES.INI

setUnitRule

Set the value of a rule for a given Unit type

setUnitRule("FTNK", "PrimaryWeapon", "chemspray")

Parameters:

  • unitType
  • ruleName
  • ruleValue

Returns: nothing

getAircraftRule

Get the value of a rule for a given Aircraft type

getInfantryRule("HELI", "PrimaryWeapon")

Parameters:

  • aircraftType
  • ruleName

Returns: The value of the rule as a string/boolean/number - this will match the data type found in RULES.INI

setAircraftRule

Set the value of a rule for a given Aircraft type

setAircraftRule("ORCA", "Cost", 350)

Parameters:

  • aircraftType
  • ruleName
  • ruleValue

Returns: nothing

getBuildingRule

Get the value of a rule for a given Building type

getBuildingRule("GTWR", "Prerequisite")

Parameters:

  • buildingType
  • ruleName

Returns: The value of the rule as a string/boolean/number - this will match the data type found in RULES.INI

setBuildingRule

Set the value of a rule for a given Building type

setBuildingRule("GUN", "Houses", "GOODGUY,BADGUY")

Parameters:

  • buildingType
  • ruleName
  • ruleValue

Returns: nothing

Game Control

Functions that allow you to interact with the game engine.

showGameMessage

Write a string to the ingame text notification box in the top left of the game HUD.

showGameMessage("Kane Lives!")

Parameters:

  • message

Returns: nothing

refreshSidebar

Refresh the player sidebar, this will load all units/infantry/aircraft and buildings they currently have the ability to build. Useful to show a dyanmic change to the rules is made via lua and you want the player to be aware that things have changed.

refreshSidebar()

Parameters: none

Returns: nothing

revealEntireMap

Reveal the entire map to the player.

revealEntireMap()

Parameters: none

Returns: nothing

hideEntireMap

Hide the entire map from the player, leaving only Player owned units/structures etc. visible.

hideEntireMap()

Parameters: none

Returns: nothing

getPlayerHouse

Get the name of the house that the player is currently playing as.

local house = getPlayerHouse()

Parameters: none

Returns: The name of the player house as a string, in the format seen in the RULES.INI file; GOODGUY etc.

getPlayerBaseHouse

Get the name of the house that the player is currently should behave like. This is used in multiplayer games to allow MULT1 for example to behave like GOODGUY if the user selected GDI in the game setup.

local baseHouse = getPlayerBaseHouse()

Parameters: none

Returns: The name of the player base house as a string, in the format seen in the RULES.INI file; BADGUY etc.

getActiveHouses

Get the names of the houses that are currently active in the game, in multiplayer this is houses of AI and human players and in single-player this is the houses listed in the scenario INI file.

local houses = getActiveHouses()

Parameters: none

Returns: A table containing the names of currently active houses. Houses are strings in the format seen in the RULES.INI file; BADGUY etc.

modifyHouseCredits

Add/subtract credits from a house in the currently running scenario.

modifyHouseCredits("BADGUY", 2000) -- add 2K
modifyHouseCredits("MULTI1", -130) -- remove 130

Parameters:

  • houseName The name of the house (same format as seen in the RULES.INI file, GOODGUY etc.)
  • credits The amount of credits to add or subtract

Returns: The amount of credits the house now has (after modification)

enableSuperweaponForHouse

Give a house a superweapon immediately, if they don't already have it. Note: The superweapon will not require the house to maintain a building if not marked as oneTimeOnly (see parameters) - i.e. don't need to have an Adv. Comm Center to keep the Ion Cannon. The only way to remove a superweapon that is not one time use only is to call disableSuperweaponForHouse.

enableSuperweaponForHouse("BADGUY", "NuclearStrike")
enableSuperweaponForHouse("MULT3", "AirStrike", true) -- one airstrike use only

Parameters:

  • houseName The name of the house (same format as seen in the RULES.INI file, GOODGUY etc.)
  • superWeaponName The name of the superweapon to enable (same format as seen in the RULES.INI file, IonCannon etc.)
  • oneTimeOnly (optional) Remove the superweapon from the house when it is fired? (similar to a superweapon from a crate in multiplayer)

Returns: nothing

chargeSuperweaponForHouse

Fully charge a superweapon for a house, has no affect if they don't have it.

chargeSuperweaponForHouse("GOODGUY", "AirStrike")

Parameters:

  • houseName The name of the house (same format as seen in the RULES.INI file, GOODGUY etc.)
  • superWeaponName The name of the superweapon to charge (same format as seen in the RULES.INI file, IonCannon etc.)

Returns: nothing

disableSuperweaponForHouse

Remove a superweapon from a house immediately, does nothing if they don't have it.

disableSuperweaponForHouse("MUTLI2", "IonCannon")

Parameters:

  • houseName The name of the house (same format as seen in the RULES.INI file, GOODGUY etc.)
  • superWeaponName The name of the superweapon to disable (same format as seen in the RULES.INI file, IonCannon etc.)

Returns: nothing

clearGameUiMessages

Clears down any pending UI messages; these are generated when functions are called to updates the sidebar/map etc.

clearGameUiMessages()

Parameters: none Returns: nothing

clearGameLoopMessages

Clears down any pending Game Loop messages; these are generated by the game engine - currently only a game tick places an event on the queue.

clearGameLoopMessages()

Parameters: none Returns: nothing

clearHouseMessages

Clears down any pending House messages; these are generated when functions are called for superweapon control.

clearHouseMessages()

Parameters: none Returns: nothing

Utils

Logging and error handling functions.

log

Write a string to the NCO log file

log("Some important message")
log(string.format("The current value of my var is %s", "some value")) -- write some values to the log

Parameters:

  • logMessage

Returns: nothing

showError

Show the user a error message box with a string and write the error to the NCO log file

showError("Oh crap - something went really wrong")

Parameters:

  • errorMessage

Returns: nothing

getLogLevel

Get the current log level, see here for the various log levels available

local logLevel = getLogLevel()

Parameters: none

Returns: String containing the current log level

setLogLevel

Sets the current log level, see here for the various log levels available

setLogLevel("debug")

Parameters:

  • logLevel

Returns: nothing

toggleConsoleLog

Turn on/off echoing non-error log messages to the console (Used for the Lua Console)

toggleConsoleLog()

Parameters: none

Returns: nothing

getNowInEpochMillis

Get the time in epoch milliseconds - the number of milliseconds since midnight on Jan 1st 1970 (UTC).

local millisSinceEpoch = getNowInEpochMillis()

Parameters: none

Returns: Current time in epoch milliseconds

getModDataPath

Get the full path to the NCO mod Data folder

local modPath = getModDataPath()

Parameters: none

Returns: Path as a string

buildModDataFilePath

Get the full path to a file that is inside the NCO mod Data folder

local someCsvFile = buildModDataFilePath("data.csv")
local someTxtFile = buildModDataFilePath("my-mod\data\something.txt") -- you can specify sub-folders

Parameters: none

Returns: Path to the given file as a string

Clone this wiki locally