Factorio Runtime DocsVersion 2.0.20

ClassLuaForcechanged

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

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) changeddouble
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) changedboolean

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

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) newboolean
unchart_chunk(position, surface)
get_item_launched(item) changeduint

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

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

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

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

Is this force a friend? [...]

Is this force a friend? [...]

is_enemy(other) changedboolean

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() newboolean

Are the space platforms unlocked? [...]

Are the space platforms unlocked? [...]

create_space_platform{name?=…, planet=…, starter_pack=…} newLuaSpacePlatform?

Creates a new space platform on this force.

Creates a new space platform on this force.

get_evolution_factor(surface?) newdouble

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

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

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

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

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

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

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

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) → uintchanged

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


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


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) → doublechanged

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


get_cease_fire(other) → booleanchanged

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


get_friend(other) → booleanchanged

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


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) → booleannew

Parameters


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) → uintchanged

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) → booleanchanged

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) → booleanchanged

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) → booleanchanged

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) → booleanchanged

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() → booleannew

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

The starter pack required to build the platform.

The starter pack required to build the platform.


get_evolution_factor(surface?) → doublenew

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

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

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

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) → LuaFlowStatisticsnew

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

Parameters


get_fluid_production_statistics(surface) → LuaFlowStatisticsnew

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

Parameters


get_kill_count_statistics(surface) → LuaFlowStatisticsnew

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

Parameters


get_entity_build_count_statistics(surface) → LuaFlowStatisticsnew

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

Parameters

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.

Classes

Concepts

Events

Defines