Factorio API Docs

1.1.51 <>

Class LuaForce

LuaForce encapsulates data local to each "force" or "faction" of the game. Default forces are player, enemy and neutral. Players and mods can create additional forces (up to 64 total).

uint

Count entities of given type.


Disable research for this force.


Enable research for this force.


Disable all recipes and technologies.


Enables all recipes and technologies.


Load the original version of all recipes from the prototypes.


Unlock all recipes.


Unlock all technologies.


research_all_technologies(include_disabled_prototypes)

Research all technologies.


Load the original versions of technologies from prototypes.


reset()

Reset everything.


Reapplies all possible research effects, including unlocked recipes.


chart(surface, area)

Chart a portion of the map.


clear_chart(surface)

Erases chart data for this force.


Force a rechart of the whole chart.


chart_all(surface)

Chart all generated chunks.


is_chunk_charted(surface, position)
boolean

Has a chunk been charted?


is_chunk_visible(surface, position)
boolean

Is the given chunk currently charted and visible (not covered by fog of war) on the map.


cancel_charting(surface)

Cancels pending chart requests for the given surface or all surfaces.



set_ammo_damage_modifier(ammo, modifier)


set_gun_speed_modifier(ammo, modifier)


set_turret_attack_modifier(turret, modifier)

set_cease_fire(other, cease_fire)

Add other force to this force's cease fire list.


boolean

Is other force in this force's cease fire list?


set_friend(other, friend)

Add other force to this force's friends list.


get_friend(other)
boolean

Is other force in this force's friends list.


boolean

Is pathfinder busy?


Kill all units and flush the pathfinder.



set_spawn_position(position, surface)


unchart_chunk(position, surface)

uint

Gets the count of a given item launched in rockets.


set_item_launched(item, count)

Sets the count of a given item launched in rockets.


print(message, color)

Print text to the chat console of all players on this force.


get_trains(surface)
→ array[LuaTrain]

add_chart_tag(surface, tag)

Adds a custom chart tag to the given surface and returns the new tag or nil if the given position isn't valid for a chart tag.


find_chart_tags(surface, area)
→ array[LuaCustomChartTag]

Finds all custom chart tags within the given bounding box on the given surface.


double

Gets the saved progress for the given technology or nil if there is no saved progress.


set_saved_technology_progress(technology, progress)

Sets the saved progress for the given technology.


Resets evolution for this force to zero.


play_sound{path, position, volume_modifier, override_sound_type}

Play a sound for every player in this force.


get_train_stops{name, surface}
→ array[LuaEntity]

Gets train stops matching the given filters.


boolean

Gets if the given recipe is explicitly disabled from being hand crafted.


set_hand_crafting_disabled_for_recipe(recipe, hand_crafting_disabled)

Sets if the given recipe can be hand-crafted.


add_research(technology)
boolean

Add this technology to the back of the research queue if the queue is enabled.


Stop the research currently in progress.


get_linked_inventory(prototype, link_id)

Gets the linked inventory for the given prototype and link ID if it exists or nil.


is_friend(other)
boolean

Is this force a friend?


is_enemy(other)
boolean

Is this force an enemy?


help()
string

All methods and properties that this object supports.


:: string
[R]

Name of the force.


[R]

Technologies owned by this force, indexed by name.


[R]

Recipes available to this force, indexed by name.


:: double
[RW]

Multiplier of the manual mining speed.


:: double
[RW]

Multiplier of the manual crafting speed.







[R]

The current technology in research, or nil if no research is currently ongoing.


:: double
[RW]

Progress of current research, as a number in range [0, 1].


[RW]

The previous research if any.


:: double
[RW]

The inserter stack size bonus for non stack inserters


:: uint
[RW]

Number of items that can be transferred by stack inserters.


:: double
[RW]

Number of character trash slots.


:: uint
[RW]

Maximum number of follower robots.


:: double
[RW]

Additional lifetime for following robots.


:: uint
[RW]

The time, in ticks, before a placed ghost disappears.


:: array[LuaPlayer]
[R]

Players belonging to this force.


:: boolean
[RW]

Enables some higher-level AI behaviour for this force.


:: dictionary[string → array[LuaLogisticNetwork]]
[R]

List of logistic networks, grouped by surface.


[R]

The item production statistics for this force.


[R]

The fluid production statistics for this force.


[R]

The kill counter statistics for this force.


[R]

The entity build statistics for this force (built and mined)


:: double
[RW]

Modifies the running speed of all characters in this force by the given value as a percentage.









:: uint
[RW]

the number of additional inventory slots the character main inventory has.


:: uint
[RW]

The time, in ticks, before a deconstruction order is removed.





:: boolean
[RW]

Ability to use zoom-to-world on map.


:: boolean
[RW]

Ability to build ghosts through blueprint or direct ghost placement, or "mine" ghosts when using zoom-to-world.


:: boolean
[RW]

Ability to create new blueprints using empty blueprint item when using zoom-to-world.


:: boolean
[RW]

Ability to use deconstruction planner when using zoom-to-world.


:: boolean
[RW]

Ability to use custom selection tools when using zoom-to-world.


:: boolean
[RW]

true if character requester logistics is enabled.


:: uint
[RW]

The number of rockets launched.


:: dictionary[stringuint]
[R]

All of the items that have been launched in rockets.


:: array[LuaPlayer]
[R]

The connected players belonging to this force.




:: double
[RW]

Evolution factor of this force.





:: boolean
[RW]

If friendly fire is enabled for this force.


:: boolean
[RW]

If sharing chart data is enabled for this force.


:: boolean
[RW]

Whether the research queue is available for this force.


:: uint
[R]

Unique ID associated with this force.


[RW]

The research queue of this force.


:: boolean
[R]

Whether research is enabled for this force, see LuaForce::enable_research and LuaForce::disable_research


:: boolean
[R]

Is this object valid?


:: string
[R]

The class name of this object.

Methods

get_entity_count (name) → uint

Count entities of given type.

Parameters

name
:: string

Prototype name of the entity.

Return value

Number of entities of given prototype belonging to this force.

Note

This function has O(1) time complexity as entity counts are kept and maintained in the game engine.


disable_research ()

Disable research for this force.


enable_research ()

Enable research for this force.


disable_all_prototypes ()

Disable all recipes and technologies. Only recipes and technologies enabled explicitly will be useable from this point.


enable_all_prototypes ()

Enables all recipes and technologies. The opposite of LuaForce::disable_all_prototypes


reset_recipes ()

Load the original version of all recipes from the prototypes.


enable_all_recipes ()

Unlock all recipes.


enable_all_technologies ()

Unlock all technologies.


research_all_technologies (include_disabled_prototypes)

Research all technologies.

Parameters

include_disabled_prototypes
:: boolean
Optional

Whether technologies that are explicitly disabled in the prototype should also be researched. Defaults to false.


reset_technologies ()

Load the original versions of technologies from prototypes. Preserves research state of technologies.


reset ()

Reset everything. All technologies are set to not researched, all modifiers are set to default values.


reset_technology_effects ()

Reapplies all possible research effects, including unlocked recipes. Any custom changes are lost. Preserves research state of technologies.


chart (surface, area)

Chart a portion of the map. The chart for the given area is refreshed; it creates chart for any parts of the given area that haven't been charted yet.

Parameters


area

The area on the given surface to chart.

Example

Charts a 2048x2048 rectangle centered around the origin.

game.player.force.chart(game.player.surface, {{x = -1024, y = -1024}, {x = 1024, y = 1024}})

clear_chart (surface)

Erases chart data for this force.

Parameters

surface
Optional

Which surface to erase chart data for or if not provided all surfaces charts are erased.


rechart ()

Force a rechart of the whole chart.


chart_all (surface)

Chart all generated chunks.

Parameters

surface
Optional

Which surface to chart or all if not given.


is_chunk_charted (surface, position) → boolean

Has a chunk been charted?

Parameters


position

Position of the chunk.


is_chunk_visible (surface, position) → boolean

Is the given chunk currently charted and visible (not covered by fog of war) on the map.

Parameters


position

cancel_charting (surface)

Cancels pending chart requests for the given surface or all surfaces.

Parameters

surface
Optional

get_ammo_damage_modifier (ammo) → double

Parameters

ammo
:: string

Ammo category


set_ammo_damage_modifier (ammo, modifier)

Parameters

ammo
:: string

Ammo category


modifier
:: double

get_gun_speed_modifier (ammo) → double

Parameters

ammo
:: string

Ammo category


set_gun_speed_modifier (ammo, modifier)

Parameters

ammo
:: string

Ammo category


modifier
:: double

get_turret_attack_modifier (turret) → double

Parameters

turret
:: string

Turret prototype name


set_turret_attack_modifier (turret, modifier)

Parameters

turret
:: string

Turret prototype name


modifier
:: double

set_cease_fire (other, cease_fire)

Add other force to this force's cease fire list. Forces on the cease fire list won't be targeted for attack.

Parameters


cease_fire
:: boolean

get_cease_fire (other) → boolean

Is other force in this force's cease fire list?

Parameters


set_friend (other, friend)

Add other force to this force's friends list. Friends have unrestricted access to buildings and turrets won't fire at them.

Parameters


friend
:: boolean

get_friend (other) → boolean

Is other force in this force's friends list.

Parameters


is_pathfinder_busy () → boolean

Is pathfinder busy? When the pathfinder is busy, it won't accept any more pathfinding requests.


kill_all_units ()

Kill all units and flush the pathfinder.


find_logistic_network_by_position (position, surface) → LuaLogisticNetwork

Parameters

position

Position to find a network for


surface

Surface to search on

Return value

The found network or nil.


set_spawn_position (position, surface)

Parameters

position

The new position on the given surface.


surface

Surface to set the spawn position for.


get_spawn_position (surface) → Position

Parameters


unchart_chunk (position, surface)

Parameters

position

The chunk position to unchart.


surface

Surface to unchart on.


get_item_launched (item) → uint

Gets the count of a given item launched in rockets.

Parameters

item
:: string

The item to get

Return value

The count of the item that has been launched.


set_item_launched (item, count)

Sets the count of a given item launched in rockets.

Parameters

item
:: string

The item to set


count
:: uint

The count to set


print (message, color)

Print text to the chat console of all players on this force.

Parameters

message

color
:: Color
Optional

Note

Messages that are identical to a message sent in the last 60 ticks are not printed again.


get_trains (surface) → array[LuaTrain]

Parameters

surface
Optional

If given only trains on the surface are returned.


add_chart_tag (surface, tag) → LuaCustomChartTag

Adds a custom chart tag to the given surface and returns the new tag or nil if the given position isn't valid for a chart tag.

Parameters

surface

Which surface to add the tag to.


tag

The tag to add.

Note

The chunk must be charted for a tag to be valid at that location.


find_chart_tags (surface, area) → array[LuaCustomChartTag]

Finds all custom chart tags within the given bounding box on the given surface.

Parameters


area
Optional

get_saved_technology_progress (technology) → double

Gets the saved progress for the given technology or nil if there is no saved progress.

Parameters

technology

The technology

Return value

The progress as a percent.


set_saved_technology_progress (technology, progress)

Sets the saved progress for the given technology. The technology must not be in progress, must not be completed, and the new progress must be < 100%.

Parameters

technology

The technology


progress
:: double

Progress as a percent. Set to nil to remove the saved progress.


reset_evolution ()

Resets evolution for this force to zero.


play_sound {path, position, volume_modifier, override_sound_type}

Play a sound for every player in this force.

Parameters

Table with the following fields:
path

The sound to play.


position
Optional

Where the sound should be played. If not given, it's played at the current position of each player.


volume_modifier
:: double
Optional

The volume of the sound to play. Must be between 0 and 1 inclusive.


override_sound_type
Optional

The volume mixer to play the sound through. Defaults to the default mixer for the given sound type.


get_train_stops {name, surface} → array[LuaEntity]

Gets train stops matching the given filters.

Parameters

Table (optional) with the following fields:
name
:: string or array[string]
Optional

surface
Optional

get_hand_crafting_disabled_for_recipe (recipe) → boolean

Gets if the given recipe is explicitly disabled from being hand crafted.

Parameters

recipe

set_hand_crafting_disabled_for_recipe (recipe, hand_crafting_disabled)

Sets if the given recipe can be hand-crafted. This is used to explicitly disable hand crafting a recipe - it won't allow hand-crafting otherwise not hand-craftable recipes.

Parameters

recipe

hand_crafting_disabled
:: boolean

add_research (technology) → boolean

Add this technology to the back of the research queue if the queue is enabled. Otherwise, set this technology to be researched now.

Parameters

technology

Return value

If the technology was added.


cancel_current_research ()

Stop the research currently in progress. This will remove any dependent technologies from the research queue.


get_linked_inventory (prototype, link_id) → LuaInventory

Gets the linked inventory for the given prototype and link ID if it exists or nil.

Parameters


link_id
:: uint

is_friend (other) → boolean

Is this force a friend? This differs from get_friend in that it is always true for neutral force. This is equivalent to checking the friend ForceCondition.

Parameters


is_enemy (other) → boolean

Is this force an enemy? This differs from get_cease_fire in that it is always false for neutral force. This is equivalent to checking the enemy ForceCondition.

Parameters


help () → string

All methods and properties that this object supports.

Attributes

name :: string [Read]

Name of the force.

Example

Prints "player"

game.player.print(game.player.force.name)

technologies :: LuaCustomTable[stringLuaTechnology] [Read]

Technologies owned by this force, indexed by name.

Example

Researches the technology for the player's force

game.player.force.technologies["steel-processing"].researched = true

recipes :: LuaCustomTable[stringLuaRecipe] [Read]

Recipes available to this force, indexed by name.

Example

Prints the category of the given recipe

game.player.print(game.player.force.recipes["transport-belt"].category)

manual_mining_speed_modifier :: double [Read/Write]

Multiplier of the manual mining speed. Default value is 0. The actual mining speed will be multiplied by 1 + manual_mining_speed_modifier.

Example

Double the player's mining speed

game.player.force.manual_mining_speed_modifier = 1

manual_crafting_speed_modifier :: double [Read/Write]

Multiplier of the manual crafting speed. Default value is 0. The actual crafting speed will be multiplied by 1 + manual_crafting_speed_modifier.

Example

Double the player's crafting speed

game.player.force.manual_crafting_speed_modifier = 1

laboratory_speed_modifier :: double [Read/Write]


laboratory_productivity_bonus :: double [Read/Write]


worker_robots_speed_modifier :: double [Read/Write]


worker_robots_battery_modifier :: double [Read/Write]


worker_robots_storage_bonus :: double [Read/Write]


current_research :: LuaTechnology [Read]

The current technology in research, or nil if no research is currently ongoing.


research_progress :: double [Read/Write]

Progress of current research, as a number in range [0, 1].


previous_research :: LuaTechnology [Read/Write]

The previous research if any.


inserter_stack_size_bonus :: double [Read/Write]

The inserter stack size bonus for non stack inserters


stack_inserter_capacity_bonus :: uint [Read/Write]

Number of items that can be transferred by stack inserters. When writing to this value, it must be >= 0 and <= 254.


character_trash_slot_count :: double [Read/Write]

Number of character trash slots.


maximum_following_robot_count :: uint [Read/Write]

Maximum number of follower robots.


following_robots_lifetime_modifier :: double [Read/Write]

Additional lifetime for following robots.


ghost_time_to_live :: uint [Read/Write]

The time, in ticks, before a placed ghost disappears.


players :: array[LuaPlayer] [Read]

Players belonging to this force.


ai_controllable :: boolean [Read/Write]

Enables some higher-level AI behaviour for this force. When set to true, biters belonging to this force will automatically expand into new territories, build new spawners, and form unit groups. By default, this value is true for the enemy force and false for all others.

Notes

Setting this to false does not turn off biters' AI. They will still move around and attack players who come close.

It is necessary for a force to be AI controllable in order to be able to create unit groups or build bases from scripts.


logistic_networks :: dictionary[string → array[LuaLogisticNetwork]] [Read]

List of logistic networks, grouped by surface.


item_production_statistics :: LuaFlowStatistics [Read]

The item production statistics for this force.


fluid_production_statistics :: LuaFlowStatistics [Read]

The fluid production statistics for this force.


kill_count_statistics :: LuaFlowStatistics [Read]

The kill counter statistics for this force.


entity_build_count_statistics :: LuaFlowStatistics [Read]

The entity build statistics for this force (built and mined)


character_running_speed_modifier :: double [Read/Write]

Modifies the running speed of all characters in this force by the given value as a percentage. Setting the running modifier to 0.5 makes the character run 50% faster. The minimum value of -1 reduces the movement speed by 100%, resulting in a speed of 0.


artillery_range_modifier :: double [Read/Write]


character_build_distance_bonus :: uint [Read/Write]


character_item_drop_distance_bonus :: uint [Read/Write]


character_reach_distance_bonus :: uint [Read/Write]


character_resource_reach_distance_bonus :: double [Read/Write]


character_item_pickup_distance_bonus :: double [Read/Write]


character_loot_pickup_distance_bonus :: double [Read/Write]


character_inventory_slots_bonus :: uint [Read/Write]

the number of additional inventory slots the character main inventory has.


deconstruction_time_to_live :: uint [Read/Write]

The time, in ticks, before a deconstruction order is removed.


character_health_bonus :: double [Read/Write]


max_successful_attempts_per_tick_per_construction_queue :: uint [Read/Write]


max_failed_attempts_per_tick_per_construction_queue :: uint [Read/Write]


zoom_to_world_enabled :: boolean [Read/Write]

Ability to use zoom-to-world on map.


zoom_to_world_ghost_building_enabled :: boolean [Read/Write]

Ability to build ghosts through blueprint or direct ghost placement, or "mine" ghosts when using zoom-to-world.


zoom_to_world_blueprint_enabled :: boolean [Read/Write]

Ability to create new blueprints using empty blueprint item when using zoom-to-world.


zoom_to_world_deconstruction_planner_enabled :: boolean [Read/Write]

Ability to use deconstruction planner when using zoom-to-world.


zoom_to_world_selection_tool_enabled :: boolean [Read/Write]

Ability to use custom selection tools when using zoom-to-world.


character_logistic_requests :: boolean [Read/Write]

true if character requester logistics is enabled.


rockets_launched :: uint [Read/Write]

The number of rockets launched.


items_launched :: dictionary[stringuint] [Read]

All of the items that have been launched in rockets.


connected_players :: array[LuaPlayer] [Read]

The connected players belonging to this force.

This is primarily useful when you want to do some action against all online players of this force.

Note

This does not index using player index. See LuaPlayer::index on each player instance for the player index.


mining_drill_productivity_bonus :: double [Read/Write]


train_braking_force_bonus :: double [Read/Write]


evolution_factor :: double [Read/Write]

Evolution factor of this force.


evolution_factor_by_pollution :: double [Read/Write]


evolution_factor_by_time :: double [Read/Write]


evolution_factor_by_killing_spawners :: double [Read/Write]


friendly_fire :: boolean [Read/Write]

If friendly fire is enabled for this force.


share_chart :: boolean [Read/Write]

If sharing chart data is enabled for this force.


research_queue_enabled :: boolean [Read/Write]

Whether the research queue is available for this force.


index :: uint [Read]

Unique ID associated with this force.


research_queue :: array[TechnologyIdentification] [Read/Write]

The research queue of this force. The first technology in the array is the currently active one. Reading this attribute gives an array of LuaTechnology.

To write to this, the entire table must be written. Providing an empty table or nil will empty the research queue and cancel the current research. Writing to this when the research queue is disabled will simply set the last research in the table as the current research.

Note

This only allows mods to queue research that this force is able to research in the first place. As an example, an already researched technology or one whose prerequisites are not fulfilled will not be queued, but dropped silently instead.


research_enabled :: boolean [Read]

Whether research is enabled for this force, see LuaForce::enable_research and LuaForce::disable_research


valid :: boolean [Read]

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 :: string [Read]

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.

|<

Classes

Events

Concepts

Defines

Builtin types

>|