Factorio.com|Forums|Wiki|Mod Portal|API Docs

# Factorio Runtime Docs Version 2.0.77

# LuaCustomTable - Runtime Docs

## Class LuaCustomTable

Lazily evaluated table. For performance reasons, we sometimes return a custom table-like type instead of a native Lua table. This custom type lazily constructs the necessary Lua wrappers of the corresponding C++ objects, therefore preventing their unnecessary construction in some cases.

There are some notable consequences to the usage of a custom table type rather than the native Lua table type: Iterating a custom table is only possible using the `pairs` Lua function; `ipairs` won't work. Another key difference is that custom tables cannot be serialised into a game save file -- if saving the game would require serialisation of a custom table, an error will be displayed and the game will not be saved.

In previous versions of Factorio, this would create a LuaPlayer instance for every player in the game, even though only one such wrapper is needed. In the current version, accessing game.players by itself does not create any LuaPlayer instances; they are created lazily when accessed. Therefore, this example only constructs one LuaPlayer instance, no matter how many elements there are in `game.players`.

    game.players["Oxyd"].character.die()

This statement will execute successfully and `storage.p` will be useable as one might expect. However, as soon as the user tries to save the game, a "LuaCustomTable cannot be serialized" error will be shown. The game will remain unsaveable so long as `storage.p` refers to an instance of a custom table.

    storage.p = game.players  -- This has high potential to make the game unsaveable

The following will produce no output because `ipairs` is not supported with custom tables.

    for _, p in ipairs(game.players) do game.player.print(p.name); end  -- incorrect; use pairs instead

## Example

    -- Custom tables may be iterated using `pairs`.
    for _, p in pairs(game.players) do game.player.print(p.name); end

## Members

valid | :: R boolean | Is this object valid? [...]
Is this object valid? [...]
object_name | :: R string | The class name of this object. [...]
The class name of this object. [...]
[] (index) | :: R Any | Access an element of this custom table.
Access an element of this custom table.
# (length) | :: R uint32 | Number of elements in this table.
Number of elements in this table.

## Attributes

### valid :: Read boolean

Is this object valid? This Lua object holds a reference to an object within the game engine. It is possible that the game-engine object is removed whilst a mod still holds the corresponding Lua object. If that happens, the object becomes invalid, i.e. this attribute will be `false`. Mods are advised to check for object validity if any change to the game state might have occurred between the creation of the Lua object and its access.

### object_name :: Read string

The class name of this object. Available even when `valid` is false. For LuaStruct objects it may also be suffixed with a dotted path to a member of the struct.

## Operators

### [] (index)

Access an element of this custom table.

### # (length)

Number of elements in this table.

Class used in

- LuaForce::technologies
- LuaForce::recipes
- LuaGameScript::players
- LuaGameScript::forces
- LuaGameScript::surfaces
- LuaGameScript::planets
- LuaGameScript::backer_names
- LuaPlayer::mod_settings
- LuaPrototypes::get_entity_filtered()
- LuaPrototypes::get_item_filtered()
- LuaPrototypes::get_equipment_filtered()
- LuaPrototypes::get_mod_setting_filtered()
- LuaPrototypes::get_achievement_filtered()
- LuaPrototypes::get_tile_filtered()
- LuaPrototypes::get_decorative_filtered()
- LuaPrototypes::get_fluid_filtered()
- LuaPrototypes::get_recipe_filtered()
- LuaPrototypes::get_technology_filtered()
- LuaPrototypes::font
- LuaPrototypes::map_gen_preset
- LuaPrototypes::style
- LuaPrototypes::utility_constants
- LuaPrototypes::entity
- LuaPrototypes::item
- LuaPrototypes::fluid
- LuaPrototypes::tile
- LuaPrototypes::equipment
- LuaPrototypes::damage
- LuaPrototypes::virtual_signal
- LuaPrototypes::equipment_grid
- LuaPrototypes::recipe
- LuaPrototypes::technology
- LuaPrototypes::decorative
- LuaPrototypes::particle
- LuaPrototypes::autoplace_control
- LuaPrototypes::mod_setting
- LuaPrototypes::custom_input
- LuaPrototypes::ammo_category
- LuaPrototypes::named_noise_expression
- LuaPrototypes::named_noise_function
- LuaPrototypes::item_subgroup
- LuaPrototypes::item_group
- LuaPrototypes::fuel_category
- LuaPrototypes::resource_category
- LuaPrototypes::achievement
- LuaPrototypes::module_category
- LuaPrototypes::equipment_category
- LuaPrototypes::trivial_smoke
- LuaPrototypes::shortcut
- LuaPrototypes::recipe_category
- LuaPrototypes::quality
- LuaPrototypes::surface_property
- LuaPrototypes::space_location
- LuaPrototypes::space_connection
- LuaPrototypes::custom_event
- LuaPrototypes::active_trigger
- LuaPrototypes::asteroid_chunk
- LuaPrototypes::collision_layer
- LuaPrototypes::airborne_pollutant
- LuaPrototypes::burner_usage
- LuaPrototypes::mod_data
- LuaPrototypes::surface
- LuaPrototypes::procession
- LuaPrototypes::procession_layer_inheritance_group
- LuaRailPath::rails
- LuaSettings::get_player_settings()
- LuaSettings::startup
- LuaSettings::global
- LuaSettings::player_default
- LuaStyle::column_alignments