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

# Factorio Runtime Docs Version 2.0.77

# LuaForce - Runtime Docs

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

## Members

get_entity_count(name) | → uint32 | 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) |  | 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) |  | 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, chunk_position) | → boolean | Has a chunk been charted?
Has a chunk been charted?
is_chunk_visible(surface, chunk_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, chunk_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) | → double |
set_turret_attack_modifier(turret, modifier) |  |
set_cease_fire(other, cease_fire) |  | Add `other` force to this force's cease fire list. [...]
Add `other` force to this force's cease fire list. [...]
get_cease_fire(other) | → 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) |  | Add `other` force to this force's friends list. [...]
Add `other` force to this force's friends list. [...]
get_friend(other) | → 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) |  |
get_surface_hidden(surface) | → boolean |
unchart_chunk(chunk_position, surface) |  |
get_item_launched(item) | → uint32 | 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) |  | Sets the count of a given item launched in rockets.
Sets the count of a given item launched in rockets.
print(message, print_settings?) |  | 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 a given area on the given surface. [...]
Finds all custom chart tags within a given area on the given surface. [...]
reset_evolution() |  | Resets evolution for this force to zero.
Resets evolution for this force to zero.
play_sound(sound_specification) |  | 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) | → 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) |  | Sets if the given recipe can be hand-crafted. [...]
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. [...]
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) | → 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) | → boolean | Is this force a friend? [...]
Is this force a friend? [...]
is_enemy(other) | → boolean | Is this force an enemy? [...]
Is this force an enemy? [...]
lock_space_location(name) |  | Locks the planet to not be accessible to this force.
Locks the planet to not be accessible to this force.
unlock_space_location(name) |  | Unlocks the planet to be accessible to this force.
Unlocks the planet to be accessible to this force.
is_space_location_unlocked(name) |  | Is the specified planet unlocked for this force?
Is the specified planet unlocked for this force?
lock_quality(quality) |  | Locks the quality to not be accessible to this force.
Locks the quality to not be accessible to this force.
unlock_quality(quality) |  | Unlocks the quality to be accessible to this force.
Unlocks the quality to be accessible to this force.
is_quality_unlocked(quality) |  | Is the specified quality unlocked for this force?
Is the specified quality unlocked for this force?
lock_space_platforms() |  | Locks the space platforms, which disables the space platforms button
Locks the space platforms, which disables the space platforms button
unlock_space_platforms() |  | Unlocks the space platforms, which enables the space platforms button
Unlocks the space platforms, which enables the space platforms button
is_space_platforms_unlocked() | → boolean | Are the space platforms unlocked? [...]
Are the space platforms unlocked? [...]
create_space_platform{name?=…, planet=…, starter_pack=…} | → LuaSpacePlatform? | Creates a new space platform on this force.
Creates a new space platform on this force.
get_evolution_factor(surface?) | → 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?) | → 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?) | → 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?) | → 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?) |  | 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?) |  | 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?) |  | 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?) |  | 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) | → 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) | → 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) | → 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) | → 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.
get_logistic_groups(type?) | → array[string] | Gets the names of the current logistic groups.
Gets the names of the current logistic groups.
get_logistic_group(name, type?) | → LogisticGroup? | Gets the information about the given logistic group.
Gets the information about the given logistic group.
create_logistic_group(name, type?) |  | Creates the given group if it doesn't already exist.
Creates the given group if it doesn't already exist.
delete_logistic_group(name, type?) |  | Deletes the given logistic group if it exists.
Deletes the given logistic group if it exists.
get_chunk_chart(surface, chunk_position) | → string? | Gets the raw chart data for a given chunk as a binary string. [...]
Gets the raw chart data for a given chunk as a binary string. [...]
script_trigger_research(technology) |  | Trigger the "scripted" research trigger of a technology, researching it. [...]
Trigger the "scripted" research trigger of a technology, researching it. [...]
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 | :: RW uint32 | Number of items that can be transferred by bulk inserters. [...]
Number of items that can be transferred by bulk inserters. [...]
belt_stack_size_bonus | :: RW uint32 | 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 uint32 | 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 | :: 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.
circuit_network_enabled | :: RW boolean |
cliff_deconstruction_enabled | :: RW boolean | When true, cliffs will be marked for deconstruction when trying to force-build things that collide.
When true, cliffs will be marked for deconstruction when trying to force-build things that collide.
mining_with_fluid | :: RW boolean |
rail_support_on_deep_oil_ocean | :: RW boolean |
rail_planner_allow_elevated_rails | :: RW boolean |
vehicle_logistics | :: RW boolean | When true, cars/tanks that support logistics will be able to use them.
When true, cars/tanks that support logistics will be able to use them.
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 | :: RW double |
character_build_distance_bonus | :: RW uint32 |
character_item_drop_distance_bonus | :: RW uint32 |
character_reach_distance_bonus | :: RW uint32 |
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 uint32 | 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 uint32 | 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 uint32 |
max_failed_attempts_per_tick_per_construction_queue | :: RW uint32 |
character_logistic_requests | :: RW boolean | `true` if character requester logistics is enabled.
`true` if character requester logistics is enabled.
rockets_launched | :: RW uint32 | The number of rockets launched.
The number of rockets launched.
items_launched | :: R dictionary[string → ItemCountType] | 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 uint32 | This force's index in LuaGameScript::forces (unique ID). [...]
This force's index in LuaGameScript::forces (unique ID). [...]
research_queue | :: 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 | :: R dictionary[uint32 → 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) → uint32

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

→ uint32 | 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, enabled and visible_when_disabled 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)

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)

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, chunk_position) → boolean

Has a chunk been charted?

#### Parameters

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

### is_chunk_visible(surface, chunk_position) → boolean

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

#### Parameters

surface | :: SurfaceIdentification |
chunk_position | :: ChunkPosition |

### is_chunk_requested_for_charting(surface, chunk_position) → boolean

Has a chunk been requested for charting?

#### Parameters

surface | :: SurfaceIdentification |
chunk_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

#### Parameters

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

### set_turret_attack_modifier(turret, modifier)

#### Parameters

turret | :: EntityID | Turret prototype name
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

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

#### Raised events

on_force_cease_fire_changed instantly |

### get_cease_fire(other) → boolean

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

#### Parameters

other | :: ForceID |

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

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

#### Raised events

on_force_friends_changed instantly |

### get_friend(other) → boolean

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)

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

#### Parameters

surface | :: SurfaceIdentification |

### unchart_chunk(chunk_position, surface)

#### Parameters

chunk_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) → uint32

Gets the count of a given item launched in rockets.

#### Parameters

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

#### Return values

→ uint32 | 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 | :: ItemID | The item to set
The item to set
count | :: uint32 | The count to set
The count to set

### print(message, print_settings?)

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 a given area on the given surface. If no area is given all custom chart tags on the surface are returned.

#### Parameters

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

### reset_evolution()

Resets evolution for this force to zero.

### play_sound(sound_specification)

Play a sound for every player in this force.

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

#### Parameters

sound_specification | :: PlaySoundSpecification | The sound to play.
The sound to play.

### get_hand_crafting_disabled_for_recipe(recipe) → boolean

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)

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

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?

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

#### Parameters

prototype | :: EntityID |
link_id | :: uint32 |

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

other | :: ForceID |

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

other | :: ForceID |

### lock_space_location(name)

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)

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)

Is the specified planet unlocked for this force?

#### Parameters

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

### lock_quality(quality)

Locks the quality to not be accessible to this force.

#### Parameters

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

### unlock_quality(quality)

Unlocks the quality to be accessible to this force.

#### Parameters

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

### is_quality_unlocked(quality)

Is the specified quality unlocked for this force?

#### Parameters

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

### lock_space_platforms()

Locks the space platforms, which disables the space platforms button

### unlock_space_platforms()

Unlocks the space platforms, which enables the space platforms button

### is_space_platforms_unlocked() → boolean

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

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

Creates a new space platform on this force.

#### Parameters

Table 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 | :: ItemWithQualityID | The starter pack required to build the platform.
The starter pack required to build the platform.

### get_evolution_factor(surface?) → double

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

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

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

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

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

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

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

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

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

#### Parameters

surface | :: SurfaceIdentification |

### get_fluid_production_statistics(surface) → LuaFlowStatistics

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

#### Parameters

surface | :: SurfaceIdentification |

### get_kill_count_statistics(surface) → LuaFlowStatistics

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

#### Parameters

surface | :: SurfaceIdentification |

### get_entity_build_count_statistics(surface) → LuaFlowStatistics

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

#### Parameters

surface | :: SurfaceIdentification |

### get_logistic_groups(type?) → array[string]

Gets the names of the current logistic groups.

#### Parameters

type | :: defines.logistic_group_type? | Defaults to `defines.logistic_group_type.with_trash`.
Defaults to `defines.logistic_group_type.with_trash`.

### get_logistic_group(name, type?) → LogisticGroup?

Gets the information about the given logistic group.

#### Parameters

name | :: string |
type | :: defines.logistic_group_type? | Defaults to `defines.logistic_group_type.with_trash`.
Defaults to `defines.logistic_group_type.with_trash`.

### create_logistic_group(name, type?)

Creates the given group if it doesn't already exist.

#### Parameters

name | :: string |
type | :: defines.logistic_group_type? | Defaults to `defines.logistic_group_type.with_trash`.
Defaults to `defines.logistic_group_type.with_trash`.

### delete_logistic_group(name, type?)

Deletes the given logistic group if it exists.

#### Parameters

name | :: string |
type | :: defines.logistic_group_type? | Defaults to `defines.logistic_group_type.with_trash`.
Defaults to `defines.logistic_group_type.with_trash`.

### get_chunk_chart(surface, chunk_position) → string?

Gets the raw chart data for a given chunk as a binary string.

The pixel data is returned in RGB565 format (2 bytes per pixel).

Returns `nil` if the chunk has not been charted for this force.

#### Parameters

surface | :: SurfaceIdentification |
chunk_position | :: ChunkPosition |

#### Return values

→ string? | The raw pixel data.

### script_trigger_research(technology)

Trigger the "scripted" research trigger of a technology, researching it. Does nothing if the technology does not have a "scripted" research trigger.

#### Parameters

technology | :: TechnologyID |

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

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 uint32

Belt stack size bonus.

### character_trash_slot_count :: Read|Write double

Number of character trash slots.

### maximum_following_robot_count :: Read|Write uint32

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

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

### circuit_network_enabled :: Read|Write boolean

### cliff_deconstruction_enabled :: Read|Write boolean

When true, cliffs will be marked for deconstruction when trying to force-build things that collide.

### mining_with_fluid :: Read|Write boolean

### rail_support_on_deep_oil_ocean :: Read|Write boolean

### rail_planner_allow_elevated_rails :: Read|Write boolean

### vehicle_logistics :: Read|Write boolean

When true, cars/tanks that support logistics will be able to use them.

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

### character_build_distance_bonus :: Read|Write uint32

### character_item_drop_distance_bonus :: Read|Write uint32

### character_reach_distance_bonus :: Read|Write uint32

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

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

### deconstruction_time_to_live :: Read|Write uint32

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 uint32

### max_failed_attempts_per_tick_per_construction_queue :: Read|Write uint32

### character_logistic_requests :: Read|Write boolean

`true` if character requester logistics is enabled.

### rockets_launched :: Read|Write uint32

The number of rockets launched.

### items_launched :: Read dictionary[string → ItemCountType]

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 uint32

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]

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[uint32 → LuaSpacePlatform]

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.

Class used in

- LuaCommandable::force
- LuaControl::force
- LuaCustomChartTag::force
- LuaEntity::render_to_forces
- LuaFlowStatistics::force
- LuaGameScript::create_force()
- LuaGameScript::forces
- LuaLogisticNetwork::force
- LuaLogisticPoint::force
- LuaRecipe::force
- LuaRenderObject::forces
- LuaSegmentedUnit::force
- LuaSpacePlatform::force
- LuaSurface::clone_brush()
- LuaTechnology::force
- ForceID
- ItemLocationData
- on_area_cloned
- on_brush_cloned
- on_chart_tag_added
- on_chart_tag_modified
- on_chart_tag_removed
- on_chunk_charted
- on_entity_damaged
- on_entity_died
- on_force_cease_fire_changed
- on_force_created
- on_force_friends_changed
- on_force_reset
- on_forces_merged
- on_forces_merging
- on_player_changed_force
- on_post_entity_died
- on_post_segmented_unit_died
- on_research_cancelled
- on_research_moved
- on_research_queued
- on_segmented_unit_damaged
- on_segmented_unit_died
- on_technology_effects_reset