Factorio.com|Forums|Wiki|Mod Portal|API Docs Prototype|Runtime|Auxiliary

# Factorio Runtime Docs Version 2.0.7

## Class LuaForce changed

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

## Members

get_entity_count(name) changed | → uint | Count entities of given type. [...]
Count entities of given type. [...]
disable_research() |  | Disable research for this force.
Disable research for this force.
enable_research() |  | Enable research for this force.
Enable research for this force.
disable_all_prototypes() |  | Disable all recipes and technologies. [...]
Disable all recipes and technologies. [...]
enable_all_prototypes() |  | Enables all recipes and technologies. [...]
Enables all recipes and technologies. [...]
reset_recipes() |  | Load the original version of all recipes from the prototypes.
Load the original version of all recipes from the prototypes.
enable_all_recipes() |  | Unlock all recipes.
Unlock all recipes.
enable_all_technologies() |  | Unlock all technologies.
Unlock all technologies.
research_all_technologies(include_disabled_prototypes?) |  | Research all technologies.
Research all technologies.
reset_technologies() |  | Load the original versions of technologies from prototypes. [...]
Load the original versions of technologies from prototypes. [...]
reset() |  | Reset everything. [...]
Reset everything. [...]
reset_technology_effects() |  | Reapplies all possible research effects, including unlocked recipes. [...]
Reapplies all possible research effects, including unlocked recipes. [...]
chart(surface, area) |  | Chart a portion of the map. [...]
Chart a portion of the map. [...]
clear_chart(surface?) |  | Erases chart data for this force.
Erases chart data for this force.
rechart(surface?) |  | Force a rechart of the whole chart.
Force a rechart of the whole chart.
chart_all(surface?) |  | Chart all generated chunks.
Chart all generated chunks.
copy_from(force) new |  | Copies all of the given changeable values (except charts) from the given force to this force.
Copies all of the given changeable values (except charts) from the given force to this force.
copy_chart(source_force, source_surface, destination_surface) new |  | Copies the given surface's chart from the given force to this force.
Copies the given surface's chart from the given force to this force.
is_chunk_charted(surface, position) | → boolean | Has a chunk been charted?
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.
Is the given chunk currently charted and visible (not covered by fog of war) on the map.
is_chunk_requested_for_charting(surface, position) | → boolean | Has a chunk been requested for charting?
Has a chunk been requested for charting?
cancel_charting(surface?) |  | Cancels pending chart requests for the given surface or all surfaces.
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) changed | → double |
set_turret_attack_modifier(turret, modifier) changed |  |
set_cease_fire(other, cease_fire) changed |  | Add `other` force to this force's cease fire list. [...]
Add `other` force to this force's cease fire list. [...]
get_cease_fire(other) changed | → boolean | Is `other` force in this force's cease fire list?
Is `other` force in this force's cease fire list?
set_friend(other, friend) changed |  | Add `other` force to this force's friends list. [...]
Add `other` force to this force's friends list. [...]
get_friend(other) changed | → boolean | Is `other` force in this force's friends list.
Is `other` force in this force's friends list.
is_pathfinder_busy() | → boolean | Is pathfinder busy? [...]
Is pathfinder busy? [...]
kill_all_units() |  | Kill all units and flush the pathfinder.
Kill all units and flush the pathfinder.
find_logistic_network_by_position(position, surface) | → LuaLogisticNetwork? |
set_spawn_position(position, surface) |  |
get_spawn_position(surface) | → MapPosition |
set_surface_hidden(surface, hidden) new |  |
get_surface_hidden(surface) new | → boolean |
unchart_chunk(position, surface) |  |
get_item_launched(item) changed | → uint | Gets the count of a given item launched in rockets.
Gets the count of a given item launched in rockets.
set_item_launched(item, count) changed |  | Sets the count of a given item launched in rockets.
Sets the count of a given item launched in rockets.
print(message, print_settings?) changed |  | Print text to the chat console of all players on this force. [...]
Print text to the chat console of all players on this force. [...]
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. [...]
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.
Finds all custom chart tags within the given bounding box on the given surface.
reset_evolution() |  | Resets evolution for this force to zero.
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. [...]
Play a sound for every player in this force. [...]
get_hand_crafting_disabled_for_recipe(recipe) changed | → boolean | Gets if the given recipe is explicitly disabled from being hand crafted.
Gets if the given recipe is explicitly disabled from being hand crafted.
set_hand_crafting_disabled_for_recipe(recipe, hand_crafting_disabled) changed |  | Sets if the given recipe can be hand-crafted. [...]
Sets if the given recipe can be hand-crafted. [...]
add_research(technology) changed | → boolean | Add this technology to the back of the research queue if the queue is enabled. [...]
Add this technology to the back of the research queue if the queue is enabled. [...]
cancel_current_research() |  | Stop the research currently in progress. [...]
Stop the research currently in progress. [...]
get_linked_inventory(prototype, link_id) changed | → LuaInventory? | Gets the linked inventory for the given prototype and link ID if it exists or `nil`.
Gets the linked inventory for the given prototype and link ID if it exists or `nil`.
is_friend(other) changed | → boolean | Is this force a friend? [...]
Is this force a friend? [...]
is_enemy(other) changed | → boolean | Is this force an enemy? [...]
Is this force an enemy? [...]
lock_space_location(name) new |  | Locks the planet to not be accessible to this force.
Locks the planet to not be accessible to this force.
unlock_space_location(name) new |  | Unlocks the planet to be accessible to this force.
Unlocks the planet to be accessible to this force.
is_space_location_unlocked(name) new |  | Is the specified planet unlocked for this force?
Is the specified planet unlocked for this force?
lock_quality(quality) new |  | Locks the quality to not be accessible to this force.
Locks the quality to not be accessible to this force.
unlock_quality(quality) new |  | Unlocks the quality to be accessible to this force.
Unlocks the quality to be accessible to this force.
is_quality_unlocked(quality) new |  | Is the specified quality unlocked for this force?
Is the specified quality unlocked for this force?
lock_space_platforms() new |  | Locks the space platforms, which disables the space platforms button
Locks the space platforms, which disables the space platforms button
unlock_space_platforms() new |  | Unlocks the space platforms, which enables the space platforms button
Unlocks the space platforms, which enables the space platforms button
is_space_platforms_unlocked() new | → boolean | Are the space platforms unlocked? [...]
Are the space platforms unlocked? [...]
create_space_platform{name?=…, planet=…, starter_pack=…} new | → LuaSpacePlatform? | Creates a new space platform on this force.
Creates a new space platform on this force.
get_evolution_factor(surface?) new | → double | Fetches the evolution factor of this force on the given surface.
Fetches the evolution factor of this force on the given surface.
get_evolution_factor_by_pollution(surface?) new | → double | Fetches the pollution part of the evolution factor of this force on the given surface.
Fetches the pollution part of the evolution factor of this force on the given surface.
get_evolution_factor_by_time(surface?) new | → double | Fetches the time part of the evolution factor of this force on the given surface.
Fetches the time part of the evolution factor of this force on the given surface.
get_evolution_factor_by_killing_spawners(surface?) new | → double | Fetches the spawner kill part of the evolution factor of this force on the given surface.
Fetches the spawner kill part of the evolution factor of this force on the given surface.
set_evolution_factor(factor, surface?) new |  | Sets the evolution factor of this force on the given surface.
Sets the evolution factor of this force on the given surface.
set_evolution_factor_by_pollution(factor, surface?) new |  | Sets the pollution part of the evolution factor of this force on the given surface.
Sets the pollution part of the evolution factor of this force on the given surface.
set_evolution_factor_by_time(factor, surface?) new |  | Sets the time part of the evolution factor of this force on the given surface.
Sets the time part of the evolution factor of this force on the given surface.
set_evolution_factor_by_killing_spawners(factor, surface?) new |  | Sets the spawner kill part of the evolution factor of this force on the given surface.
Sets the spawner kill part of the evolution factor of this force on the given surface.
get_item_production_statistics(surface) new | → LuaFlowStatistics | The item production statistics for this force for the given surface.
The item production statistics for this force for the given surface.
get_fluid_production_statistics(surface) new | → LuaFlowStatistics | The fluid production statistics for this force for the given surface.
The fluid production statistics for this force for the given surface.
get_kill_count_statistics(surface) new | → LuaFlowStatistics | The kill counter statistics for this force for the given surface.
The kill counter statistics for this force for the given surface.
get_entity_build_count_statistics(surface) new | → LuaFlowStatistics | The entity build statistics for this force (built and mined) for the given surface.
The entity build statistics for this force (built and mined) for the given surface.
name | :: R string | Name of the force.
Name of the force.
technologies | :: R LuaCustomTable[string → LuaTechnology] | Technologies owned by this force, indexed by `name`.
Technologies owned by this force, indexed by `name`.
recipes | :: R LuaCustomTable[string → LuaRecipe] | Recipes available to this force, indexed by `name`.
Recipes available to this force, indexed by `name`.
manual_mining_speed_modifier | :: RW double | Multiplier of the manual mining speed. [...]
Multiplier of the manual mining speed. [...]
manual_crafting_speed_modifier | :: RW double | Multiplier of the manual crafting speed. [...]
Multiplier of the manual crafting speed. [...]
laboratory_speed_modifier | :: RW double |
laboratory_productivity_bonus | :: RW double |
worker_robots_speed_modifier | :: RW double |
worker_robots_battery_modifier | :: RW double |
worker_robots_storage_bonus | :: RW double |
current_research | :: R LuaTechnology? | The currently ongoing technology research, if any.
The currently ongoing technology research, if any.
research_progress | :: RW double | Progress of current research, as a number in range `[0, 1]`.
Progress of current research, as a number in range `[0, 1]`.
previous_research | :: RW LuaTechnology? | The previous research, if any.
The previous research, if any.
inserter_stack_size_bonus | :: RW double | The inserter stack size bonus for non stack inserters
The inserter stack size bonus for non stack inserters
bulk_inserter_capacity_bonus new | :: RW uint | Number of items that can be transferred by bulk inserters. [...]
Number of items that can be transferred by bulk inserters. [...]
belt_stack_size_bonus new | :: RW uint | Belt stack size bonus.
Belt stack size bonus.
character_trash_slot_count | :: RW double | Number of character trash slots.
Number of character trash slots.
maximum_following_robot_count | :: RW uint | Maximum number of follower robots.
Maximum number of follower robots.
following_robots_lifetime_modifier | :: RW double | Additional lifetime for following robots.
Additional lifetime for following robots.
create_ghost_on_entity_death new | :: RW boolean | When an entity dies, a ghost will be placed for automatic reconstruction.
When an entity dies, a ghost will be placed for automatic reconstruction.
players | :: R array[LuaPlayer] | Players belonging to this force.
Players belonging to this force.
ai_controllable | :: RW boolean | Enables some higher-level AI behaviour for this force. [...]
Enables some higher-level AI behaviour for this force. [...]
logistic_networks | :: R dictionary[string → array[LuaLogisticNetwork]] | List of logistic networks, grouped by surface.
List of logistic networks, grouped by surface.
character_running_speed_modifier | :: RW double | Modifies the running speed of all characters in this force by the given value as a percentage. [...]
Modifies the running speed of all characters in this force by the given value as a percentage. [...]
artillery_range_modifier | :: RW double |
beacon_distribution_modifier new | :: RW double |
character_build_distance_bonus | :: RW uint |
character_item_drop_distance_bonus | :: RW uint |
character_reach_distance_bonus | :: RW uint |
character_resource_reach_distance_bonus | :: RW double |
character_item_pickup_distance_bonus | :: RW double |
character_loot_pickup_distance_bonus | :: RW double |
character_inventory_slots_bonus | :: RW uint | The number of additional inventory slots the character main inventory has.
The number of additional inventory slots the character main inventory has.
deconstruction_time_to_live | :: RW uint | The time, in ticks, before a deconstruction order is removed.
The time, in ticks, before a deconstruction order is removed.
character_health_bonus | :: RW double |
max_successful_attempts_per_tick_per_construction_queue | :: RW uint |
max_failed_attempts_per_tick_per_construction_queue | :: RW uint |
character_logistic_requests | :: RW boolean | `true` if character requester logistics is enabled.
`true` if character requester logistics is enabled.
rockets_launched | :: RW uint | The number of rockets launched.
The number of rockets launched.
items_launched changed | :: R array[ItemCountWithQuality] | All of the items that have been launched in rockets.
All of the items that have been launched in rockets.
connected_players | :: R array[LuaPlayer] | The connected players belonging to this force. [...]
The connected players belonging to this force. [...]
mining_drill_productivity_bonus | :: RW double |
train_braking_force_bonus | :: RW double |
friendly_fire | :: RW boolean | If friendly fire is enabled for this force.
If friendly fire is enabled for this force.
share_chart | :: RW boolean | If sharing chart data is enabled for this force.
If sharing chart data is enabled for this force.
index | :: R uint | This force's index in LuaGameScript::forces (unique ID). [...]
This force's index in LuaGameScript::forces (unique ID). [...]
research_queue changed | :: RW array[TechnologyID] | The research queue of this force. [...]
The research queue of this force. [...]
research_enabled | :: R boolean | Whether research is enabled for this force, see LuaForce::enable_research and LuaForce::disable_research.
Whether research is enabled for this force, see LuaForce::enable_research and LuaForce::disable_research.
platforms new | :: R dictionary[uint → LuaSpacePlatform] | The space platforms that belong to this force mapped by their index value. [...]
The space platforms that belong to this force mapped by their index value. [...]
custom_color | :: RW Color? | Custom color for this force. [...]
Custom color for this force. [...]
color | :: R Color | Effective color of this force.
Effective color of this force.
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. [...]

## Methods

### get_entity_count(name) → uint changed

Count entities of given type.

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

#### Parameters

name | :: EntityID | Prototype name of the entity.
Prototype name of the entity.

#### Return values

→ uint | Number of entities of given prototype belonging to this force.

### 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? | Whether technologies that are explicitly disabled in the prototype should also be researched. Defaults to `false`.
Whether technologies that are explicitly disabled in the prototype should also be researched. Defaults to `false`.

#### Raised events

on_research_finished instantly |

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

#### Raised events

on_force_reset instantly |

### reset_technology_effects()

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

#### Raised events

on_technology_effects_reset instantly |

### 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

surface | :: SurfaceIdentification |
area | :: BoundingBox | The area on the given surface to chart.
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 | :: SurfaceIdentification? | Which surface to erase chart data for or if not provided all surfaces charts are erased.
Which surface to erase chart data for or if not provided all surfaces charts are erased.

### rechart(surface?)

Force a rechart of the whole chart.

#### Parameters

surface | :: SurfaceIdentification? | Which surface to rechart or all if not given.
Which surface to rechart or all if not given.

### chart_all(surface?)

Chart all generated chunks.

#### Parameters

surface | :: SurfaceIdentification? | Which surface to chart or all if not given.
Which surface to chart or all if not given.

### copy_from(force) new

Copies all of the given changeable values (except charts) from the given force to this force.

#### Parameters

force | :: ForceID | The force to copy from.
The force to copy from.

### copy_chart(source_force, source_surface, destination_surface) new

Copies the given surface's chart from the given force to this force.

#### Parameters

source_force | :: ForceID | The force to copy from
The force to copy from
source_surface | :: SurfaceIdentification | The surface to copy from.
The surface to copy from.
destination_surface | :: SurfaceIdentification | The surface to copy to.
The surface to copy to.

### is_chunk_charted(surface, position) → boolean

Has a chunk been charted?

#### Parameters

surface | :: SurfaceIdentification |
position | :: ChunkPosition | Position of the chunk.
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

surface | :: SurfaceIdentification |
position | :: ChunkPosition |

### is_chunk_requested_for_charting(surface, position) → boolean

Has a chunk been requested for charting?

#### Parameters

surface | :: SurfaceIdentification |
position | :: ChunkPosition | Position of the chunk.
Position of the chunk.

### cancel_charting(surface?)

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

#### Parameters

surface | :: SurfaceIdentification? |

### get_ammo_damage_modifier(ammo) → double

#### Parameters

ammo | :: string | Ammo category
Ammo category

### set_ammo_damage_modifier(ammo, modifier)

#### Parameters

ammo | :: string | Ammo category
Ammo category
modifier | :: double |

### get_gun_speed_modifier(ammo) → double

#### Parameters

ammo | :: string | Ammo category
Ammo category

### set_gun_speed_modifier(ammo, modifier)

#### Parameters

ammo | :: string | Ammo category
Ammo category
modifier | :: double |

### get_turret_attack_modifier(turret) → double changed

#### Parameters

turret | :: EntityID | Turret prototype name
Turret prototype name

### set_turret_attack_modifier(turret, modifier) changed

#### Parameters

turret | :: EntityID | Turret prototype name
Turret prototype name
modifier | :: double |

### set_cease_fire(other, cease_fire) changed

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

#### Parameters

other | :: ForceID |
cease_fire | :: boolean |

#### Raised events

on_force_cease_fire_changed instantly |

### get_cease_fire(other) → boolean changed

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

#### Parameters

other | :: ForceID |

### set_friend(other, friend) changed

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

#### Parameters

other | :: ForceID |
friend | :: boolean |

#### Raised events

on_force_friends_changed instantly |

### get_friend(other) → boolean changed

Is `other` force in this force's friends list.

#### Parameters

other | :: ForceID |

### 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 | :: MapPosition | Position to find a network for
Position to find a network for
surface | :: SurfaceIdentification | Surface to search on
Surface to search on

#### Return values

→ LuaLogisticNetwork? | The found network or `nil`.

### set_spawn_position(position, surface)

#### Parameters

position | :: MapPosition | The new position on the given surface.
The new position on the given surface.
surface | :: SurfaceIdentification | Surface to set the spawn position for.
Surface to set the spawn position for.

### get_spawn_position(surface) → MapPosition

#### Parameters

surface | :: SurfaceIdentification |

### set_surface_hidden(surface, hidden) new

#### Parameters

surface | :: SurfaceIdentification | Surface to set hidden for.
Surface to set hidden for.
hidden | :: boolean | Whether to hide the surface or not.
Whether to hide the surface or not.

### get_surface_hidden(surface) → boolean new

#### Parameters

surface | :: SurfaceIdentification |

### unchart_chunk(position, surface)

#### Parameters

position | :: ChunkPosition | The chunk position to unchart.
The chunk position to unchart.
surface | :: SurfaceIdentification | Surface to unchart on.
Surface to unchart on.

### get_item_launched(item) → uint changed

Gets the count of a given item launched in rockets.

#### Parameters

item | :: ItemID | The item to get
The item to get

#### Return values

→ uint | The count of the item that has been launched.

### set_item_launched(item, count) changed

Sets the count of a given item launched in rockets.

#### Parameters

item | :: ItemID | The item to set
The item to set
count | :: uint | The count to set
The count to set

### print(message, print_settings?) changed

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

By default, messages that are identical to a message sent in the last 60 ticks are not printed again.

#### Parameters

message | :: LocalisedString |
print_settings | :: PrintSettings? |

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

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

#### Parameters

surface | :: SurfaceIdentification | Which surface to add the tag to.
Which surface to add the tag to.
tag | :: ChartTagSpec | The tag to add.
The tag to add.

#### Raised events

on_chart_tag_added? instantly | Raised if the chart tag was successfully added.

### find_chart_tags(surface, area?) → array[LuaCustomChartTag]

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

#### Parameters

surface | :: SurfaceIdentification |
area | :: BoundingBox? |

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

The sound is not played if its location is not charted for this force.

#### Parameters

Table with the following fields:

path | :: SoundPath | The sound to play.
The sound to play.
position | :: MapPosition? | Where the sound should be played. If not given, it's played at the current position of each player.
Where the sound should be played. If not given, it's played at the current position of each player.
volume_modifier | :: double? | The volume of the sound to play. Must be between 0 and 1 inclusive.
The volume of the sound to play. Must be between 0 and 1 inclusive.
override_sound_type | :: SoundType? | The volume mixer to play the sound through. Defaults to the default mixer for the given sound type.
The volume mixer to play the sound through. Defaults to the default mixer for the given sound type.

### get_hand_crafting_disabled_for_recipe(recipe) → boolean changed

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

#### Parameters

recipe | :: RecipeID |

### set_hand_crafting_disabled_for_recipe(recipe, hand_crafting_disabled) changed

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 | :: RecipeID |
hand_crafting_disabled | :: boolean |

### add_research(technology) → boolean changed

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 | :: TechnologyID |

#### Return values

→ boolean | Whether the technology was successfully added.

#### Raised events

on_research_started? instantly | Raised if the technology was successfully 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?changed

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

#### Parameters

prototype | :: EntityID |
link_id | :: uint |

### is_friend(other) → boolean changed

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

other | :: ForceID |

### is_enemy(other) → boolean changed

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

other | :: ForceID |

### lock_space_location(name) new

Locks the planet to not be accessible to this force.

#### Parameters

name | :: SpaceLocationID | Name of the planet.
Name of the planet.

### unlock_space_location(name) new

Unlocks the planet to be accessible to this force.

#### Parameters

name | :: SpaceLocationID | Name of the planet.
Name of the planet.

### is_space_location_unlocked(name) new

Is the specified planet unlocked for this force?

#### Parameters

name | :: SpaceLocationID | Name of the planet.
Name of the planet.

### lock_quality(quality) new

Locks the quality to not be accessible to this force.

#### Parameters

quality | :: QualityID | Name of the quality.
Name of the quality.

### unlock_quality(quality) new

Unlocks the quality to be accessible to this force.

#### Parameters

quality | :: QualityID | Name of the quality.
Name of the quality.

### is_quality_unlocked(quality) new

Is the specified quality unlocked for this force?

#### Parameters

quality | :: QualityID | Name of the quality.
Name of the quality.

### lock_space_platforms() new

Locks the space platforms, which disables the space platforms button

### unlock_space_platforms() new

Unlocks the space platforms, which enables the space platforms button

### is_space_platforms_unlocked() → boolean new

Are the space platforms unlocked? This basically just controls the availability of the space platforms button.

### create_space_platform{name?=…, planet=…, starter_pack=…} → LuaSpacePlatform?new

Creates a new space platform on this force.

#### Parameters

Table (optional) with the following fields:

name | :: string? | The platform name. If not provided, a random name will be used.
The platform name. If not provided, a random name will be used.
planet | :: SpaceLocationID | The planet that the platform will orbit.
The planet that the platform will orbit.
starter_pack | :: ItemID | The starter pack required to build the platform.
The starter pack required to build the platform.

### get_evolution_factor(surface?) → double new

Fetches the evolution factor of this force on the given surface.

#### Parameters

surface | :: SurfaceIdentification? | Defaults to "nauvis".
Defaults to "nauvis".

### get_evolution_factor_by_pollution(surface?) → double new

Fetches the pollution part of the evolution factor of this force on the given surface.

#### Parameters

surface | :: SurfaceIdentification? | Defaults to "nauvis".
Defaults to "nauvis".

### get_evolution_factor_by_time(surface?) → double new

Fetches the time part of the evolution factor of this force on the given surface.

#### Parameters

surface | :: SurfaceIdentification? | Defaults to "nauvis".
Defaults to "nauvis".

### get_evolution_factor_by_killing_spawners(surface?) → double new

Fetches the spawner kill part of the evolution factor of this force on the given surface.

#### Parameters

surface | :: SurfaceIdentification? | Defaults to "nauvis".
Defaults to "nauvis".

### set_evolution_factor(factor, surface?) new

Sets the evolution factor of this force on the given surface.

#### Parameters

factor | :: double |
surface | :: SurfaceIdentification? | Defaults to "nauvis".
Defaults to "nauvis".

### set_evolution_factor_by_pollution(factor, surface?) new

Sets the pollution part of the evolution factor of this force on the given surface.

#### Parameters

factor | :: double |
surface | :: SurfaceIdentification? | Defaults to "nauvis".
Defaults to "nauvis".

### set_evolution_factor_by_time(factor, surface?) new

Sets the time part of the evolution factor of this force on the given surface.

#### Parameters

factor | :: double |
surface | :: SurfaceIdentification? | Defaults to "nauvis".
Defaults to "nauvis".

### set_evolution_factor_by_killing_spawners(factor, surface?) new

Sets the spawner kill part of the evolution factor of this force on the given surface.

#### Parameters

factor | :: double |
surface | :: SurfaceIdentification? | Defaults to "nauvis".
Defaults to "nauvis".

### get_item_production_statistics(surface) → LuaFlowStatistics new

The item production statistics for this force for the given surface.

#### Parameters

surface | :: SurfaceIdentification |

### get_fluid_production_statistics(surface) → LuaFlowStatistics new

The fluid production statistics for this force for the given surface.

#### Parameters

surface | :: SurfaceIdentification |

### get_kill_count_statistics(surface) → LuaFlowStatistics new

The kill counter statistics for this force for the given surface.

#### Parameters

surface | :: SurfaceIdentification |

### get_entity_build_count_statistics(surface) → LuaFlowStatistics new

The entity build statistics for this force (built and mined) for the given surface.

#### Parameters

surface | :: SurfaceIdentification |

## Attributes

### name :: Read string

Name of the force.

#### Example

    game.player.print(game.player.force.name) -- => "player"

### technologies :: Read LuaCustomTable[string → LuaTechnology]

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

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 :: Read|Write double

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 :: Read|Write double

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 :: Read|Write double

### laboratory_productivity_bonus :: Read|Write double

### worker_robots_speed_modifier :: Read|Write double

### worker_robots_battery_modifier :: Read|Write double

### worker_robots_storage_bonus :: Read|Write double

### current_research :: Read LuaTechnology?

The currently ongoing technology research, if any.

### research_progress :: Read|Write double

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

### previous_research :: Read|Write LuaTechnology?

The previous research, if any.

### inserter_stack_size_bonus :: Read|Write double

The inserter stack size bonus for non stack inserters

### bulk_inserter_capacity_bonus :: Read|Write uint new

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

### belt_stack_size_bonus :: Read|Write uint new

Belt stack size bonus.

### character_trash_slot_count :: Read|Write double

Number of character trash slots.

### maximum_following_robot_count :: Read|Write uint

Maximum number of follower robots.

### following_robots_lifetime_modifier :: Read|Write double

Additional lifetime for following robots.

### create_ghost_on_entity_death :: Read|Write boolean new

When an entity dies, a ghost will be placed for automatic reconstruction.

### players :: Read array[LuaPlayer]

Players belonging to this force.

### ai_controllable :: Read|Write boolean

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.

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 :: Read dictionary[string → array[LuaLogisticNetwork]]

List of logistic networks, grouped by surface.

### character_running_speed_modifier :: Read|Write double

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 :: Read|Write double

### beacon_distribution_modifier :: Read|Write double new

### character_build_distance_bonus :: Read|Write uint

### character_item_drop_distance_bonus :: Read|Write uint

### character_reach_distance_bonus :: Read|Write uint

### character_resource_reach_distance_bonus :: Read|Write double

### character_item_pickup_distance_bonus :: Read|Write double

### character_loot_pickup_distance_bonus :: Read|Write double

### character_inventory_slots_bonus :: Read|Write uint

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

### deconstruction_time_to_live :: Read|Write uint

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

### character_health_bonus :: Read|Write double

### max_successful_attempts_per_tick_per_construction_queue :: Read|Write uint

### max_failed_attempts_per_tick_per_construction_queue :: Read|Write uint

### character_logistic_requests :: Read|Write boolean

`true` if character requester logistics is enabled.

### rockets_launched :: Read|Write uint

The number of rockets launched.

### items_launched :: Read array[ItemCountWithQuality] changed

All of the items that have been launched in rockets.

### connected_players :: Read array[LuaPlayer]

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.

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

### mining_drill_productivity_bonus :: Read|Write double

### train_braking_force_bonus :: Read|Write double

### friendly_fire :: Read|Write boolean

If friendly fire is enabled for this force.

### share_chart :: Read|Write boolean

If sharing chart data is enabled for this force.

### index :: Read uint

This force's index in LuaGameScript::forces (unique ID). It is assigned when a force is created, and remains so until it is merged (ie. deleted). Indexes of merged forces can be reused.

### research_queue :: Read|Write array[TechnologyID] changed

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.

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 :: Read boolean

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

### platforms :: Read dictionary[uint → LuaSpacePlatform] new

The space platforms that belong to this force mapped by their index value.

This will include platforms that are pending deletion.

### custom_color :: Read|Write Color?

Custom color for this force. If specified, will take priority over other sources of the force color. Writing `nil` clears custom color. Will return `nil` if it was not specified or if was set to `{0,0,0,0}`.

### color :: Read Color

Effective color of this force.

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