09. Lua Scripting API

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

All APIs are found inside the Nco global table, so to use the Units API for example you would use Nco.Units.doSomething(...).

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

Note: Parameter values are not case sensitive

• Bullets
  • getRuleNames
  • getRule
  • setRule
  • getTypes
• Warheads
  • getRuleNames
  • getRule
  • setRule
  • getTypes
• Aircraft
  • getRuleNames
  • getRule
  • setRule
  • getTypes
• Rules
  • getRuleNames
  • getRule
  • getSectionNames
  • setRule
• Buildings
  • getRuleNames
  • getRule
  • setRule
  • getTypes
• Events
  • onScenarioStart
  • onSaveLoad
  • onGameTick
  • getEventNames
• Info
  • getEventNames
  • getTypeNames
• Infantry
  • getRuleNames
  • getRule
  • setRule
  • getTypes
• Game
  • chargeSuperweaponForHouse
  • revealEntireMap
  • disableSuperweaponForHouse
  • modifyHouseCredits
  • clearHouseMessages
  • showGameMessage
  • clearGameLoopMessages
  • clearGameUiMessages
  • hideEntireMap
  • getActiveHouses
  • enableSuperweaponForHouse
  • refreshSidebar
  • getPlayerHouse
  • getPlayerBaseHouse
• Weapons
  • getRuleNames
  • getRule
  • setRule
  • getTypes
• Utils
  • with
  • logString
  • printString
  • toggleConsoleLog
  • showError
  • showErrorString
  • log
  • getNowInEpochMillis
  • errorFormat
  • getLogLevel
  • getModDataPath
  • buildModDataFilePath
  • setLogLevel
  • readString
• Units
  • getRuleNames
  • getRule
  • setRule
  • getTypes
• Reflection
  • getApis
  • registerApi
  • registerApiFunctions

---

Nco.Bullets

Bullets rule info and control functions

• getRuleNames
• getRule
• setRule
• getTypes

---

getRuleNames

Get a list of Bullets rules

Nco.Bullets.getRuleNames()

Parameters: none

Return value(s): none

---

getRule

Get rules for Bullets

Nco.Bullets.getRule("typeName", "ruleName")

Parameters:

• typeName [string] - The name of one of the Bullets as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI

Return value(s):

• ruleValue [any] - The current value for the specified rule

---

setRule

Set rules for Bullets

Nco.Bullets.setRule("typeName", "ruleName", "value")

Parameters:

• typeName [string] - The name of one of the Bullets as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI
• ruleValue [any] - A valid value for the specified rule

Return value(s): none

---

getTypes

Get a list of all Bullets types (including mod types)

Nco.Bullets.getTypes()

Parameters: none

Return value(s): none

---

Nco.Warheads

Warheads rule info and control functions

• getRuleNames
• getRule
• setRule
• getTypes

---

getRuleNames

Get a list of Warheads rules

Nco.Warheads.getRuleNames()

Parameters: none

Return value(s): none

---

getRule

Get rules for Warheads

Nco.Warheads.getRule("typeName", "ruleName")

Parameters:

• typeName [string] - The name of one of the Warheads as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI

Return value(s):

• ruleValue [any] - The current value for the specified rule

---

setRule

Set rules for Warheads

Nco.Warheads.setRule("typeName", "ruleName", "value")

Parameters:

• typeName [string] - The name of one of the Warheads as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI
• ruleValue [any] - A valid value for the specified rule

Return value(s): none

---

getTypes

Get a list of all Warheads types (including mod types)

Nco.Warheads.getTypes()

Parameters: none

Return value(s): none

---

Nco.Aircraft

Aircraft rule info and control functions

• getRuleNames
• getRule
• setRule
• getTypes

---

getRuleNames

Get a list of Aircraft rules

Nco.Aircraft.getRuleNames()

Parameters: none

Return value(s): none

---

getRule

Get rules for Aircraft

Nco.Aircraft.getRule("typeName", "ruleName")

Parameters:

• typeName [string] - The name of one of the Aircraft as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI

Return value(s):

• ruleValue [any] - The current value for the specified rule

---

setRule

Set rules for Aircraft

Nco.Aircraft.setRule("typeName", "ruleName", "value")

Parameters:

• typeName [string] - The name of one of the Aircraft as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI
• ruleValue [any] - A valid value for the specified rule

Return value(s): none

---

getTypes

Get a list of all Aircraft types (including mod types)

Nco.Aircraft.getTypes()

Parameters: none

Return value(s): none

---

Nco.Rules

Get and set rule values, get rules section and entry info

• getRuleNames
• getRule
• getSectionNames
• setRule

---

getRuleNames

Get a list of entries in a given section

Nco.Rules.getRuleNames("sectionName")

Parameters:

• sectionName [string] - The section name as it appears in RULES.INI

Return value(s):

• ruleNames [table] - Table containing the entry names as strings

---

getRule

Get the current value of a rule in a given section

Nco.Rules.getRule("sectionName", "ruleName")

Parameters:

• sectionName [string] - The section name as it appears in RULES.INI
• ruleName [string] - The section entry name as it appears in RULES.INI

Return value(s):

• ruleValue [any] - The current value for the specified rule

---

getSectionNames

Get a list of rules section names

Nco.Rules.getSectionNames()

Parameters: none

Return value(s):

• sectionNames [table] - Table containing the section names as strings

---

setRule

Set the current value of a rule in a given section

Nco.Rules.setRule("sectionName", "ruleName", "value")

Parameters:

• sectionName [string] - The section name as it appears in RULES.INI
• ruleName [string] - The section entry name as it appears in RULES.INI
• ruleValue [any] - A valid value for the specified rule

Return value(s): none

---

Nco.Buildings

Buildings rule info and control functions

• getRuleNames
• getRule
• setRule
• getTypes

---

getRuleNames

Get a list of Buildings rules

Nco.Buildings.getRuleNames()

Parameters: none

Return value(s): none

---

getRule

Get rules for Buildings

Nco.Buildings.getRule("typeName", "ruleName")

Parameters:

• typeName [string] - The name of one of the Buildings as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI

Return value(s):

• ruleValue [any] - The current value for the specified rule

---

setRule

Set rules for Buildings

Nco.Buildings.setRule("typeName", "ruleName", "value")

Parameters:

• typeName [string] - The name of one of the Buildings as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI
• ruleValue [any] - A valid value for the specified rule

Return value(s): none

---

getTypes

Get a list of all Buildings types (including mod types)

Nco.Buildings.getTypes()

Parameters: none

Return value(s): none

---

Nco.Events

Register event handlers and get info on game events

• onScenarioStart
• onSaveLoad
• onGameTick
• getEventNames

---

onScenarioStart

Register an event handler that will be called on ScenarioStart

Nco.Events.onScenarioStart(function(...)
  -- eventHandler code here
end)

Parameters:

• eventHandler [function] - Function which is called with event parameters when event is fired

Return value(s): none

---

onSaveLoad

Register an event handler that will be called on SaveLoad

Nco.Events.onSaveLoad(function(...)
  -- eventHandler code here
end)

Parameters:

• eventHandler [function] - Function which is called with event parameters when event is fired

Return value(s): none

---

onGameTick

Register an event handler that will be called on GameTick

Nco.Events.onGameTick(function(...)
  -- eventHandler code here
end)

Parameters:

• eventHandler [function] - Function which is called with event parameters when event is fired

Return value(s): none

---

getEventNames

Get a list of game events

Nco.Events.getEventNames()

Parameters: none

Return value(s):

• eventNames [table] - Table containing names of game events as strings

---

Nco.Info

General info functions

• getEventNames
• getTypeNames

---

getEventNames

Get a list of game events

Nco.Info.getEventNames()

Parameters: none

Return value(s):

• eventNames [table] - Table of strings containing the names of game events

---

getTypeNames

Get a list of types in the game (units, infantry etc.)

Nco.Info.getTypeNames()

Parameters: none

Return value(s):

• eventNames [table] - Table of strings containing the names of game types

---

Nco.Infantry

Infantry rule info and control functions

• getRuleNames
• getRule
• setRule
• getTypes

---

getRuleNames

Get a list of Infantry rules

Nco.Infantry.getRuleNames()

Parameters: none

Return value(s): none

---

getRule

Get rules for Infantry

Nco.Infantry.getRule("typeName", "ruleName")

Parameters:

• typeName [string] - The name of one of the Infantry as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI

Return value(s):

• ruleValue [any] - The current value for the specified rule

---

setRule

Set rules for Infantry

Nco.Infantry.setRule("typeName", "ruleName", "value")

Parameters:

• typeName [string] - The name of one of the Infantry as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI
• ruleValue [any] - A valid value for the specified rule

Return value(s): none

---

getTypes

Get a list of all Infantry types (including mod types)

Nco.Infantry.getTypes()

Parameters: none

Return value(s): none

---

Nco.Game

Game info and control functions

• chargeSuperweaponForHouse
• revealEntireMap
• disableSuperweaponForHouse
• modifyHouseCredits
• clearHouseMessages
• showGameMessage
• clearGameLoopMessages
• clearGameUiMessages
• hideEntireMap
• getActiveHouses
• enableSuperweaponForHouse
• refreshSidebar
• getPlayerHouse
• getPlayerBaseHouse

---

chargeSuperweaponForHouse

Charge a superweapon for a given house. Note: this function is async

Nco.Game.chargeSuperweaponForHouse("houseName", "superweaponName")

Parameters:

• houseName [string] - Name of the house to charge superweapon for
• superweaponName [string] - Name of the superweapon as it appears in the RULES.INI file

Return value(s): none

---

revealEntireMap

Reveal the entire map to the player; this is permanent unless you call hideEntireMap. Note: this function is async

Nco.Game.revealEntireMap()

Parameters: none

Return value(s): none

---

disableSuperweaponForHouse

Disable a superweapon for a given house. Note: this function is async

Nco.Game.disableSuperweaponForHouse("houseName", "superweaponName")

Parameters:

• houseName [string] - Name of the house to disable superweapon for
• superweaponName [string] - Name of the superweapon as it appears in the RULES.INI file

Return value(s): none

---

modifyHouseCredits

Write a info line to the log file

Nco.Game.modifyHouseCredits("houseName", 1)

Parameters:

• houseName [string] - Name of the house to modify
• amount [number] - Amount of credits to either add or subtract for current house balance; use negative numbers to deduct credits.

Return value(s): none

---

clearHouseMessages

Cancel any pending events for a given house (enable/disable superweapon etc.)

Nco.Game.clearHouseMessages("houseName")

Parameters:

• houseName [string] - Name of the house to cancelevents for

Return value(s): none

---

showGameMessage

Show the player an in-game message

Nco.Game.showGameMessage("message", 1)

Parameters:

• message [string] - nil
• durationInSeconds [number] - Display the message for this many seconds; minimum value is 0.1. Note: this function is async

Return value(s): none

---

clearGameLoopMessages

Cancel any pending async game events (on game tick etc.)

Nco.Game.clearGameLoopMessages()

Parameters: none

Return value(s): none

---

clearGameUiMessages

Cancel any pending async game UI changes (refresh sidebar, reveal map etc.)

Nco.Game.clearGameUiMessages()

Parameters: none

Return value(s): none

---

hideEntireMap

Hide any areas of the map without player units/buildings from the player. Note: this function is async

Nco.Game.hideEntireMap()

Parameters: none

Return value(s): none

---

getActiveHouses

Get all houses that are active in the current scenario

Nco.Game.getActiveHouses()

Parameters: none

Return value(s):

• activeHouseNames [table] - List of strings, containing the names of active houses.

---

enableSuperweaponForHouse

Enable a superweapon for a given house. Note: this function is async

Nco.Game.enableSuperweaponForHouse("houseName", "superweaponName")

Parameters:

• houseName [string] - Name of the house to enable superweapon for
• superweaponName [string] - Name of the superweapon as it appears in the RULES.INI file

Return value(s): none

---

refreshSidebar

Force a refresh of the sidebar; useful if you make a rule change that affects what the user can build and want to reflect that right away. Note: this function is async

Nco.Game.refreshSidebar()

Parameters: none

Return value(s): none

---

getPlayerHouse

Get the name of the current player house

Nco.Game.getPlayerHouse()

Parameters: none

Return value(s):

• houseName [string] - The house name of the player (BADGUY, GOODGUY etc.)

---

getPlayerBaseHouse

Get the name of the base house for the current player house. Every house has a base house which it acts like, usually NOD or GDI.

Nco.Game.getPlayerBaseHouse()

Parameters: none

Return value(s):

• baseHouseName [string] - The base house name of the player (BADGUY, GOODGUY etc.)

---

Nco.Weapons

Weapons rule info and control functions

• getRuleNames
• getRule
• setRule
• getTypes

---

getRuleNames

Get a list of Weapons rules

Nco.Weapons.getRuleNames()

Parameters: none

Return value(s): none

---

getRule

Get rules for Weapons

Nco.Weapons.getRule("typeName", "ruleName")

Parameters:

• typeName [string] - The name of one of the Weapons as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI

Return value(s):

• ruleValue [any] - The current value for the specified rule

---

setRule

Set rules for Weapons

Nco.Weapons.setRule("typeName", "ruleName", "value")

Parameters:

• typeName [string] - The name of one of the Weapons as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI
• ruleValue [any] - A valid value for the specified rule

Return value(s): none

---

getTypes

Get a list of all Weapons types (including mod types)

Nco.Weapons.getTypes()

Parameters: none

Return value(s): none

---

Nco.Utils

Utility functions

• with
• logString
• printString
• toggleConsoleLog
• showError
• showErrorString
• log
• getNowInEpochMillis
• errorFormat
• getLogLevel
• getModDataPath
• buildModDataFilePath
• setLogLevel
• readString

---

with

Syntax sugar to use fields and methods of a table inside a handler, useful for making multiple calls without repeating the table variable name

Nco.Utils.with(function(...)
  -- handler code here
end, {})

Parameters:

• handler [function] - The handler to execute in the provided context
• context [table] - The keys in this table will be variables withing the scope of the handler

Return value(s):

• handlerReturnValue [any] - If the handler parameter returns a value when executed, this will be returned

---

logString

Write a info line to the log file

Nco.Utils.logString("str")

Parameters:

• str [string] - nil

Return value(s): none

---

printString

Write a line to standard out using string.format style formatting

Nco.Utils.printString("message")

Parameters:

• message [string] - Message format to output, pass one or more parameters after this to provide format values

Return value(s): none

---

toggleConsoleLog

Toggle logging to the console on/off

Nco.Utils.toggleConsoleLog()

Parameters: none

Return value(s): none

---

showError

Show a windows error popup to the user, using string.format style formatting for the message

Nco.Utils.showError("message")

Parameters:

• message [string] - Message format to show in the popup, pass one or more parameters after this to provide format values

Return value(s): none

---

showErrorString

Display an error to the user in a message box

Nco.Utils.showErrorString("errorString")

Parameters:

• errorString [string] - nil

Return value(s): none

---

log

Write a line to the logs using string.format style formatting

Nco.Utils.log("message")

Parameters:

• message [string] - Message format to log, pass one or more parameters after this to provide format values

Return value(s): none

---

getNowInEpochMillis

Get the number of milliseconds between unix epoch and now

Nco.Utils.getNowInEpochMillis()

Parameters: none

Return value(s):

• nowInEpochMillis [number] - nil

---

errorFormat

Raise a lua error, using string.format style formatting for the message

Nco.Utils.errorFormat("message")

Parameters:

• message [string] - Message format to use when raising the error, pass one or more parameters after this to provide format values

Return value(s): none

---

getLogLevel

Get the current log level

Nco.Utils.getLogLevel()

Parameters: none

Return value(s):

• logLevel [string] - See the logging config for valid values

---

getModDataPath

Get the absolute path to the mod data directory

Nco.Utils.getModDataPath()

Parameters: none

Return value(s):

• modDataDirPath [string] - nil

---

buildModDataFilePath

Build the absolute path to a file in the mod data directory

Nco.Utils.buildModDataFilePath("filename")

Parameters:

• filename [string] - Mod data filename

Return value(s):

• filePath [string] - Absolute file path for given filename

---

setLogLevel

Set the current log level

Nco.Utils.setLogLevel("logLevel")

Parameters:

• logLevel [string] - See the logging config for valid values

Return value(s): none

---

readString

Read a line from standard in using io.read format

Nco.Utils.readString("format")

Parameters:

• format [string] - Format to read, defaults to '*l'

Return value(s): none

---

Nco.Units

Units rule info and control functions

• getRuleNames
• getRule
• setRule
• getTypes

---

getRuleNames

Get a list of Units rules

Nco.Units.getRuleNames()

Parameters: none

Return value(s): none

---

getRule

Get rules for Units

Nco.Units.getRule("typeName", "ruleName")

Parameters:

• typeName [string] - The name of one of the Units as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI

Return value(s):

• ruleValue [any] - The current value for the specified rule

---

setRule

Set rules for Units

Nco.Units.setRule("typeName", "ruleName", "value")

Parameters:

• typeName [string] - The name of one of the Units as it appears in RULES.INI
• ruleName [string] - The rule name as it appears in RULES.INI
• ruleValue [any] - A valid value for the specified rule

Return value(s): none

---

getTypes

Get a list of all Units types (including mod types)

Nco.Units.getTypes()

Parameters: none

Return value(s): none

---

Nco.Reflection

Get information about API's, their functions and parameters/return values.

• getApis
• registerApi
• registerApiFunctions

---

getApis

Get available Lua APIs

Nco.Reflection.getApis()

Parameters: none

Return value(s):

• apis [table] - Map of APIs containing info on APIs and their functions, along with function parameters and return values

---

registerApi

Add a new API to the reflection registry

Nco.Reflection.registerApi({})

Parameters:

• api [table] - Table containing:
  • name: API name
  • description: API description
  • functions: dictionary containing API functions, each item - should be a table containing:
    • description: function description
      • parameters: dictionary containing function parameters, each item should be a table containing:
        • description: parameter description
        • type: parameter lua type (table, number etc.)
      • returnValues: dictionary containing function return value(s), each item should be a table containing:
        • description: parameter description
        • type: parameter lua type (table, number etc.)

Return value(s): none

---

registerApiFunctions

Add additional methods to an existing API in the reflection registry

Nco.Reflection.registerApiFunctions("apiName", {})

Parameters:

• apiName [string] - Name of the API to add new methods to, case sensitive
• functions [table] - Dictionary containing API functions, each item should be a table containing:
  • description: function description
    • parameters: dictionary containing function parameters, each item should be a table containing:
    • description: parameter description
    • type: parameter lua type (table, number etc.)
  • returnValues: dictionary containing function return value(s), each item should be a table containing:
    • description: parameter description
    • type: parameter lua type (table, number etc.)

Return value(s): none