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

class LuaForce - sort
get_entity_count(name) → uint Count entities of given type.
disable_research() Disable research for this force.
enable_research() Enable research for this force.
disable_all_prototypes() Disable all recipes and technologies.
enable_all_prototypes() Enables all recipes and technologies.
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.
reset_technologies() Load the original versions of technologies from prototypes.
reset() Reset everything.
reset_technology_effects() 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.
rechart() 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.
get_ammo_damage_modifier(ammo) → double
set_ammo_damage_modifier(ammo, modifier)
get_gun_speed_modifier(ammo) → double
set_gun_speed_modifier(ammo, modifier)
get_turret_attack_modifier(turret) → double
set_turret_attack_modifier(turret, modifier)
set_cease_fire(other, cease_fire) Stop attacking members of a given force.
get_cease_fire(other) → boolean Will this force attack members of another force?
set_friend(other, cease_fire) Friends have unrestricted access to buildings and turrets won't fire at them.
get_friend(other) → boolean Is this force a friend?
is_pathfinder_busy() → boolean Is pathfinder busy?
kill_all_units() Kill all units and flush the pathfinder.
find_logistic_network_by_position(position, surface) → LuaLogisticNetwork
set_spawn_position(position, surface)
get_spawn_position(surface) → Position
unchart_chunk(position, surface)
get_item_launched(item) → 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 of LuaTrain
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.
find_chart_tags(surface, area) → array of LuaCustomChartTag Finds all custom chart tags within the given bounding box on the given surface.
get_saved_technology_progress(technology) → double Gets the saved progress for the given technology or nil if there is no saved progress.
set_saved_technology_progress(technology, double) Sets the saved progress for the given technology.
reset_evolution() Resets evolution for this force to zero.
play_sound{path=…, position=…, volume_modifier=…} → boolean Plays a sound for every player on this force
get_train_stops(opts) → array of LuaEntity Gets train stops matching the given filters.
get_hand_crafting_disabled_for_recipe(recipe) → 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.
cancel_current_research() Stop the research currently in progress.
name :: string [R] Name of the force.
technologies :: CustomDictionary stringLuaTechnology [R] Technologies owned by this force, indexed by their name.
recipes :: CustomDictionary stringLuaRecipe [R] Recipes available to this force, indexed by their name.
manual_mining_speed_modifier :: double [RW] Multiplier of the manual mining speed.
manual_crafting_speed_modifier :: double [RW] Multiplier of the manual crafting speed.
laboratory_speed_modifier :: double [RW]
laboratory_productivity_bonus :: double [RW]
worker_robots_speed_modifier :: double [RW]
worker_robots_battery_modifier :: double [RW]
worker_robots_storage_bonus :: double [RW]
current_research :: LuaTechnology [R] The current technology in research, or nil if no research is currently ongoing.
research_progress :: double [RW] Progress of current research, as a number in range [0, 1].
previous_research :: LuaTechnology [RW] The previous research if any.
inserter_stack_size_bonus :: double [RW] The inserter stack size bonus for non stack inserters
stack_inserter_capacity_bonus :: uint [RW] Number of items that can be transferred by stack inserters.
character_trash_slot_count :: double [RW] Number of character trash slots.
maximum_following_robot_count :: uint [RW] Maximum number of follower robots.
following_robots_lifetime_modifier :: double [RW] Additional lifetime for following robots.
ghost_time_to_live :: uint [RW] The time, in ticks, before a placed ghost disappears.
players :: array of LuaPlayer [R] Players belonging to this force.
ai_controllable :: boolean [RW] Enables some higher-level AI behaviour for this force.
logistic_networks :: dictionary stringarray of LuaLogisticNetwork [R] List of logistic networks, grouped by surface.
item_production_statistics :: LuaFlowStatistics [R] The item production statistics for this force.
fluid_production_statistics :: LuaFlowStatistics [R] The fluid production statistics for this force.
kill_count_statistics :: LuaFlowStatistics [R] The kill counter statistics for this force.
entity_build_count_statistics :: LuaFlowStatistics [R] The entity build statistics for this force (built and mined)
character_running_speed_modifier :: double [RW]
artillery_range_modifier :: double [RW]
character_build_distance_bonus :: uint [RW]
character_item_drop_distance_bonus :: uint [RW]
character_reach_distance_bonus :: uint [RW]
character_resource_reach_distance_bonus :: double [RW]
character_item_pickup_distance_bonus :: double [RW]
character_loot_pickup_distance_bonus :: double [RW]
character_inventory_slots_bonus :: uint [RW] the number of additional inventory slots the character main inventory has.
deconstruction_time_to_live :: uint [RW] The time, in ticks, before a deconstruction order is removed.
character_health_bonus :: double [RW]
max_successful_attempts_per_tick_per_construction_queue :: uint [RW]
max_failed_attempts_per_tick_per_construction_queue :: uint [RW]
auto_character_trash_slots :: boolean [RW] true if auto character trash slots are enabled.
zoom_to_world_enabled :: boolean [RW] Ability to use zoom-to-world on map.
zoom_to_world_ghost_building_enabled :: boolean [RW] Ability to build ghosts through blueprint or direct ghost placement, or "mine" ghosts when using zoom-to-world.
zoom_to_world_blueprint_enabled :: boolean [RW] Ability to create new blueprints using empty blueprint item when using zoom-to-world.
zoom_to_world_deconstruction_planner_enabled :: boolean [RW] Ability to use deconstruction planner when using zoom-to-world.
zoom_to_world_selection_tool_enabled :: boolean [RW] Ability to use custom selection tools when using zoom-to-world.
character_logistic_requests :: boolean [RW] true if character requester logistics is enabled.
rockets_launched :: uint [RW] The number of rockets launched.
items_launched :: dictionary stringuint [R] All of the items that have been launched in rockets.
connected_players :: array of LuaPlayer [R] The connected players belonging to this force.
mining_drill_productivity_bonus :: double [RW]
train_braking_force_bonus :: double [RW]
evolution_factor :: double [RW] Evolution factor of this force.
evolution_factor_by_pollution :: double [RW]
evolution_factor_by_time :: double [RW]
evolution_factor_by_killing_spawners :: double [RW]
friendly_fire :: boolean [RW] If friendly fire is enabled for this force.
share_chart :: boolean [RW] If sharing chart data is enabled for this force.
research_queue_enabled :: boolean [RW] Whether the research queue is available for this force.
index :: uint [R] Unique ID associated with this force.
research_queue :: array of TechnologySpecification [RW] The research queue of this force.
research_enabled :: boolean [R] Whether research is enabled for this force, see LuaForce::enable_research and LuaForce::disable_research
valid :: boolean [R] Is this object valid?
help() → string All methods, and properties that this object supports.
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 (optional): If technologies that are explicitly disabled in the prototype are also researched. This 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 :: BoundingBox: 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 :: SurfaceSpecification (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 :: SurfaceSpecification (optional): Which surface to chart or all if not given.
is_chunk_charted(surface, position) → boolean

Has a chunk been charted?

Parameters
position :: ChunkPosition: 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 :: ChunkPosition
cancel_charting(surface)

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

Parameters
surface :: SurfaceSpecification (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)

Stop attacking members of a given force.

Parameters
cease_fire :: boolean: When true, this force won't attack other; otherwise it will.
get_cease_fire(other) → boolean

Will this force attack members of another force?

Parameters
set_friend(other, cease_fire)

Friends have unrestricted access to buildings and turrets won't fire at them.

Parameters
cease_fire :: boolean
get_friend(other) → boolean

Is this force a friend?

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: Position to find a network for
surface :: SurfaceSpecification: Surface to search on
Return value
The found network or nil.
set_spawn_position(position, surface)

Parameters
position :: Position: The new position on the given surface.
surface :: SurfaceSpecification: Surface to set the spawn position for.
get_spawn_position(surface) → Position

Parameters
unchart_chunk(position, surface)

Parameters
position :: ChunkPosition: The chunk position to unchart.
surface :: SurfaceSpecification: 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 :: LocalisedString
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 of LuaTrain

Parameters
surface :: SurfaceSpecification (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 :: SurfaceSpecification: Which surface to add the tag to.
tag: Table with the following fields:
Note: The chunk must be charted for a tag to be valid at that location.
Note: The icon, text, or both must be provided.
find_chart_tags(surface, area) → array of LuaCustomChartTag

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

Parameters
area :: BoundingBox (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 :: TechnologySpecification: The technology
Return value
The progress as a percent.
set_saved_technology_progress(technology, double)

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 :: TechnologySpecification: The technology
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=…} → boolean

Plays a sound for every player on this force

Parameters
Table with the following fields:
  • path :: SoundPath: The sound to play
  • position :: Position (optional): Where the sound should be played. If not given it's played 'everywhere'.
  • volume_modifier :: double (optional): Must be between 0 and 1 inclusive.
get_train_stops(opts) → array of LuaEntity

Gets train stops matching the given filters.

Parameters
opts (optional): Table with the following fields:
get_hand_crafting_disabled_for_recipe(recipe) → boolean

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

Parameters
recipe :: string or LuaRecipe
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 :: string or LuaRecipe
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
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.

name :: string [Read-only]

Name of the force.

Example
Prints "player"
game.player.print(game.player.force.name)
technologies :: CustomDictionary stringLuaTechnology [Read-only]

Technologies owned by this force, indexed by their name.

Example
Researches the technology for the player's force
game.player.force.technologies["steel-processing"].researched = true
recipes :: CustomDictionary stringLuaRecipe [Read-only]

Recipes available to this force, indexed by their 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-only]

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 of LuaPlayer [Read-only]

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.

Note: Setting this to false does not turn off biters' AI. They will still move around and attack players who come close.
Note: 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 stringarray of LuaLogisticNetwork [Read-only]

List of logistic networks, grouped by surface.

item_production_statistics :: LuaFlowStatistics [Read-only]

The item production statistics for this force.

fluid_production_statistics :: LuaFlowStatistics [Read-only]

The fluid production statistics for this force.

kill_count_statistics :: LuaFlowStatistics [Read-only]

The kill counter statistics for this force.

entity_build_count_statistics :: LuaFlowStatistics [Read-only]

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

character_running_speed_modifier :: double [Read-Write]

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]

auto_character_trash_slots :: boolean [Read-Write]

true if auto character trash slots are enabled. Character trash slots must be > 0 as well for this to actually be used.

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-only]

All of the items that have been launched in rockets.

connected_players :: array of LuaPlayer [Read-only]

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-only]

Unique ID associated with this force.

research_queue :: array of TechnologySpecification [Read-Write]

The research queue of this force. 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: The first research in the queue is the current research.
research_enabled :: boolean [Read-only]

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