Communication between lua and C is held through stacks with each element in stack representing lua value (nil, number, string, etc.). For example, a C wrapped function cswap is called in lua as: x, y = cswap(4, 5). StackTracePlus provides enhanced stack traces for Lua 5.1, Lua 5.2, Lua 5.3, LuaJIT and OpenResty. StackTracePlus can be used as a replacement for debug.traceback. It gives detailed information about locals, tries to guess function names when they're not available, etc, so, instead of.

Overview

In general, the Factorio API consists of 3 phases:

The settings stage is used to set up mod configuration options. The mod settings are documented on the wiki: Tutorial:Mod settings
The data stage is used to set up the prototypes of everything in the game. The prototypes are documented on the wiki: Prototype definitions
The third stage is runtime scripting. The classes and events used in this phase are documented here on this website.

For more information about how mods are loaded, initialized, and the different phases, see Data Lifecycle.

All of the scripting API functionality is implemented via class members. To make any use of the API, therefore, youneed to have access to instances of these classes. To facilitate that, some are provided as global classes.

Global classes:

game :: LuaGameScript: This is the main object, through which most of the API is accessed. It is, however, not available inside handlers registered with LuaBootstrap::on_load.
script :: LuaBootstrap: Provides an interface for registering event handlers.
remote :: LuaRemote: Allows inter-mod communication by way of providing a repository of interfaces that is shared by all mods.
commands :: LuaCommandProcessor: Allows registering custom commands for the in-game console accessible via the grave key.
settings :: LuaSettings: Allows reading the current mod settings.
rcon :: LuaRCON: Allows printing messages to the calling RCON instance if any.
rendering :: LuaRendering: Allows rendering of geometric shapes, text and sprites in the game world.

Lua C Api Print Stack 2

Other global objects:

global: The global dictionary, useful for storing data persistent across a save-load cycle.
Defines: Contents of the defines table, which contains symbolic constants used throughout the API.
Libraries and functions: General libraries and functions that Factorio provides or changes.

The following data types are used across the API:

Builtin types: Lua builtin types.
Concepts: Lua table formats that some of the API functions expect or return. For example, positions or crafting ingredients.

Classes

As described above, it is necessary to have access to instances of classes to use the scripting API. Using the provided global classes, instances of all other classes can be accessed.

This will print the first player's username, making use of LuaGameScript::get_player to gain access to players' information, and LuaPlayer::print to display a string in the player's game console.

 local first_player = game.get_player(1)
 first_player.print(first_player.name)

You can browse the overview of Factorio classes or view the documentationfor a particular class in the list below:

LuaAISettings	Collection of settings for overriding default ai behavior.
LuaAccumulatorControlBehavior	Control behavior for accumulators.
LuaAchievementPrototype	Prototype of a achievement.
LuaAmmoCategoryPrototype	Prototype of a ammo category.
LuaArithmeticCombinatorControlBehavior	Control behavior for arithmetic combinators.
LuaAutoplaceControlPrototype	Prototype of an autoplace control.
LuaBootstrap	Entry point for registering event handlers.
LuaBurner	A reference to the burner energy source owned by a specific LuaEntity or LuaEquipment.
LuaBurnerPrototype	Prototype of a burner energy source.
LuaChunkIterator	A chunk iterator can be used for iterating chunks coordinates of a surface.
LuaCircuitNetwork	A circuit network associated with a given entity, connector, and wire type.
LuaCombinatorControlBehavior
LuaCommandProcessor	Allows for the registration of custom console commands.
LuaConstantCombinatorControlBehavior	Control behavior for constant combinators.
LuaContainerControlBehavior	Control behavior for container entities.
LuaControl	This is an abstract base class containing the common functionality between LuaPlayer and entities (see LuaEntity).
LuaControlBehavior	The control behavior for an entity.
LuaCustomChartTag	A custom tag that shows on the map view.
LuaCustomInputPrototype	Prototype of a custom input.
LuaCustomTable	Lazily evaluated table.
LuaDamagePrototype	Prototype of a damage.
LuaDeciderCombinatorControlBehavior	Control behavior for decider combinators.
LuaDecorativePrototype	Prototype of an optimized decorative.
LuaElectricEnergySourcePrototype	Prototype of an electric energy source.
LuaEntity	The primary interface for interacting with entities through the Lua API.
LuaEntityPrototype	Prototype of an entity.
LuaEquipment	An item in a LuaEquipmentGrid, for example one's power armor.
LuaEquipmentCategoryPrototype	Prototype of a equipment category.
LuaEquipmentGrid	An equipment grid is for example the inside of a power armor.
LuaEquipmentGridPrototype	Prototype of an equipment grid.
LuaEquipmentPrototype	Prototype of a modular equipment.
LuaFlowStatistics	Encapsulates statistic data for different parts of the game.
LuaFluidBox	An array of fluid boxes of an entity.
LuaFluidBoxPrototype	A prototype of a fluidbox owned by some LuaEntityPrototype.
LuaFluidEnergySourcePrototype	Prototype of a fluid energy source.
LuaFluidPrototype	Prototype of a fluid.
LuaFontPrototype	Prototype of a font.
LuaForce	`LuaForce` encapsulates data local to each 'force' or 'faction' of the game.
LuaFuelCategoryPrototype	Prototype of a fuel category.
LuaGameScript	Main toplevel type, provides access to most of the API though its members.
LuaGenericOnOffControlBehavior	An abstract base class for behaviors that support switching the entity on or off based on some condition.
LuaGroup	Item group or subgroup.
LuaGui	The root of the GUI.
LuaGuiElement	An element of a custom GUI.
LuaHeatEnergySourcePrototype	Prototype of a heat energy source.
LuaInserterControlBehavior	Control behavior for inserters.
LuaInventory	A storage of item stacks.
LuaItemPrototype	Prototype of an item.
LuaItemStack	A reference to an item and count owned by some external entity.
LuaLampControlBehavior	Control behavior for lamps.
LuaLazyLoadedValue	A lazily loaded value.
LuaLogisticCell	Logistic cell of a particular LuaEntity.
LuaLogisticContainerControlBehavior	Control behavior for logistic chests.
LuaLogisticNetwork	A single logistic network of a given force on a given surface.
LuaLogisticPoint	Logistic point of a particular LuaEntity.
LuaMiningDrillControlBehavior	Control behavior for mining drills.
LuaModSettingPrototype	Prototype of a mod setting.
LuaModuleCategoryPrototype	Prototype of a module category.
LuaNamedNoiseExpression	Prototype of a named noise