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 Jan 2, 2021 · 14 revisions

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

Nco.Aircraft

Aircraft rule info and control functions

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

getRuleNames

Get a list of Aircraft rules

Nco.Aircraft.getRuleNames()

Parameters: none

Return value(s): none

getTypes

Get a list of all Aircraft (including mod types)

Nco.Aircraft.getTypes()

Parameters: none

Return value(s): none

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

Nco.Buildings

Buildings rule info and control functions

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

getRuleNames

Get a list of Buildings rules

Nco.Buildings.getRuleNames()

Parameters: none

Return value(s): none

getTypes

Get a list of all Buildings (including mod types)

Nco.Buildings.getTypes()

Parameters: none

Return value(s): none

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

Nco.Bullets

Bullets rule info and control functions

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

getRuleNames

Get a list of Bullets rules

Nco.Bullets.getRuleNames()

Parameters: none

Return value(s): none

getTypes

Get a list of all Bullets (including mod types)

Nco.Bullets.getTypes()

Parameters: none

Return value(s): none

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

Nco.Events

Register event handlers and get info on game events

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

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

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

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

Nco.Game

Game info and control functions

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

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

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

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

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

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.

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

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

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

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

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

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

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

Nco.Infantry

Infantry rule info and control functions

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

getRuleNames

Get a list of Infantry rules

Nco.Infantry.getRuleNames()

Parameters: none

Return value(s): none

getTypes

Get a list of all Infantry (including mod types)

Nco.Infantry.getTypes()

Parameters: none

Return value(s): none

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

Nco.Info

General info functions

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.Reflection

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

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

Nco.Rules

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

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

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

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.Units

Units rule info and control functions

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

getRuleNames

Get a list of Units rules

Nco.Units.getRuleNames()

Parameters: none

Return value(s): none

getTypes

Get a list of all Units (including mod types)

Nco.Units.getTypes()

Parameters: none

Return value(s): none

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

Nco.Utils

Utility functions

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

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

getNowInEpochMillis

Get the number of milliseconds between unix epoch and now

Nco.Utils.getNowInEpochMillis()

Parameters: none

Return value(s):

  • nowInEpochMillis [number] - nil

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

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

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

setLogLevel

Set the current log level

Nco.Utils.setLogLevel("logLevel")

Parameters:

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

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

toggleConsoleLog

Toggle logging to the console on/off

Nco.Utils.toggleConsoleLog()

Parameters: none

Return value(s): none

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:

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

Return value(s):

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

Nco.Warheads

Warheads rule info and control functions

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

getRuleNames

Get a list of Warheads rules

Nco.Warheads.getRuleNames()

Parameters: none

Return value(s): none

getTypes

Get a list of all Warheads (including mod types)

Nco.Warheads.getTypes()

Parameters: none

Return value(s): none

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

Nco.Weapons

Weapons rule info and control functions

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

getRuleNames

Get a list of Weapons rules

Nco.Weapons.getRuleNames()

Parameters: none

Return value(s): none

getTypes

Get a list of all Weapons (including mod types)

Nco.Weapons.getTypes()

Parameters: none

Return value(s): none

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

Clone this wiki locally