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).
get_entity_count(name) | → 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. |
||
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. |
||
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 |
|
Add |
||
get_cease_fire(other) | → boolean |
Is |
Is |
||
set_friend(other, friend) |
Add |
|
Add |
||
get_friend(other) | → boolean |
Is |
Is |
||
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 |
|
unchart_chunk(position, surface) |
|
|
get_item_launched(item) | → 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) |
Sets the count of a given item launched in rockets. |
|
Sets the count of a given item launched in rockets. |
||
print(message, color?) |
Print text to the chat console of all players on this force. |
|
Print text to the chat console of all players on this force. |
||
get_trains(surface?) | → array[LuaTrain] |
|
add_chart_tag(surface, tag) | → LuaCustomChartTag? |
Adds a custom chart tag to the given surface and returns the new tag or |
Adds a custom chart tag to the given surface and returns the new tag or |
||
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. |
||
get_saved_technology_progress(technology) | → double? |
Gets the saved progress for the given technology or |
Gets the saved progress for the given technology or |
||
set_saved_technology_progress(technology, progress) |
Sets the saved progress for the given technology. |
|
Sets the saved progress for the given technology. |
||
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_train_stops{name?=…, surface?=…} | → array[LuaEntity] |
Gets train stops matching the given filters. |
Gets train stops matching the given filters. |
||
get_hand_crafting_disabled_for_recipe(recipe) | → boolean |
Gets if the given recipe is explicitly disabled from being hand crafted. |
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 |
Gets the linked inventory for the given prototype and link ID if it exists or |
||
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? |
||
help() | → string |
All methods and properties that this object supports. |
All methods and properties that this object supports. |
||
name [R] | :: string |
Name of the force. |
Name of the force. |
||
technologies [R] | :: LuaCustomTable[string → LuaTechnology] |
Technologies owned by this force, indexed by |
Technologies owned by this force, indexed by |
||
recipes [R] | :: LuaCustomTable[string → LuaRecipe] |
Recipes available to this force, indexed by |
Recipes available to this force, indexed by |
||
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 |
||
stack_inserter_capacity_bonus [RW] | :: uint |
Number of items that can be transferred by stack inserters. |
Number of items that can be transferred by stack inserters. |
||
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. |
||
ghost_time_to_live [RW] | :: uint |
The time, in ticks, before a placed ghost disappears. |
The time, in ticks, before a placed ghost disappears. |
||
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. |
||
item_production_statistics [R] | :: LuaFlowStatistics |
The item production statistics for this force. |
The item production statistics for this force. |
||
fluid_production_statistics [R] | :: LuaFlowStatistics |
The fluid production statistics for this force. |
The fluid production statistics for this force. |
||
kill_count_statistics [R] | :: LuaFlowStatistics |
The kill counter statistics for this force. |
The kill counter statistics for this force. |
||
entity_build_count_statistics [R] | :: LuaFlowStatistics |
The entity build statistics for this force (built and mined) |
The entity build statistics for this force (built and mined) |
||
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 |
|
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 |
|
zoom_to_world_enabled [RW] | :: boolean |
Ability to use zoom-to-world on map. |
Ability to use zoom-to-world on map. |
||
zoom_to_world_ghost_building_enabled [RW] | :: boolean |
Ability to build ghosts through blueprint or direct ghost placement, or "mine" ghosts when using zoom-to-world. |
Ability to build ghosts through blueprint or direct ghost placement, or "mine" ghosts when using zoom-to-world. |
||
zoom_to_world_blueprint_enabled [RW] | :: boolean |
Ability to create new blueprints using empty blueprint item when using zoom-to-world. |
Ability to create new blueprints using empty blueprint item when using zoom-to-world. |
||
zoom_to_world_deconstruction_planner_enabled [RW] | :: boolean |
Ability to use deconstruction planner when using zoom-to-world. |
Ability to use deconstruction planner when using zoom-to-world. |
||
zoom_to_world_selection_tool_enabled [RW] | :: boolean |
Ability to use custom selection tools when using zoom-to-world. |
Ability to use custom selection tools when using zoom-to-world. |
||
character_logistic_requests [RW] | :: boolean |
|
|
||
rockets_launched [RW] | :: uint |
The number of rockets launched. |
The number of rockets launched. |
||
items_launched [R] | :: dictionary[string → uint] |
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 |
|
evolution_factor [RW] | :: double |
Evolution factor of this force. |
Evolution factor of this force. |
||
evolution_factor_by_pollution [RW] | :: double |
|
evolution_factor_by_time [RW] | :: double |
|
evolution_factor_by_killing_spawners [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. |
||
research_queue_enabled [RW] | :: boolean |
Whether the research queue is available for this force. |
Whether the research queue is available 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 [RW] | :: array[TechnologyIdentification] |
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 |
||
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. |
Count entities of given type.
name | :: string |
Prototype name of the entity. |
Prototype name of the entity. |
→ uint |
Number of entities of given prototype belonging to this force. |
This function has O(1) time complexity as entity counts are kept and maintained in the game engine.
Disable all recipes and technologies. Only recipes and technologies enabled explicitly will be useable from this point.
Enables all recipes and technologies. The opposite of LuaForce::disable_all_prototypes
Research all technologies.
include_disabled_prototypes | :: boolean? |
Whether technologies that are explicitly disabled in the prototype should also be researched. Defaults to |
Whether technologies that are explicitly disabled in the prototype should also be researched. Defaults to |
on_research_finished instantly |
|
Load the original versions of technologies from prototypes. Preserves research state of technologies.
Reset everything. All technologies are set to not researched, all modifiers are set to default values.
on_force_reset instantly |
|
Reapplies all possible research effects, including unlocked recipes. Any custom changes are lost. Preserves research state of technologies.
on_technology_effects_reset instantly |
|
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.
surface | :: SurfaceIdentification |
|
area | :: BoundingBox |
The area on the given surface to chart. |
The area on the given surface to chart. |
Charts a 2048x2048 rectangle centered around the origin.
|
Erases chart data for this force.
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. |
Force a rechart of the whole chart.
surface | :: SurfaceIdentification? |
Which surface to rechart or all if not given. |
Which surface to rechart or all if not given. |
Chart all generated chunks.
surface | :: SurfaceIdentification? |
Which surface to chart or all if not given. |
Which surface to chart or all if not given. |
Has a chunk been charted?
surface | :: SurfaceIdentification |
|
position | :: ChunkPosition |
Position of the chunk. |
Position of the chunk. |
Is the given chunk currently charted and visible (not covered by fog of war) on the map.
surface | :: SurfaceIdentification |
|
position | :: ChunkPosition |
|
Cancels pending chart requests for the given surface or all surfaces.
surface | :: SurfaceIdentification? |
|
turret | :: string |
Turret prototype name |
Turret prototype name |
Add other
force to this force's cease fire list. Forces on the cease fire list won't be targeted for attack.
other | :: ForceIdentification |
|
cease_fire | :: boolean |
|
on_force_cease_fire_changed instantly |
|
Add other
force to this force's friends list. Friends have unrestricted access to buildings and turrets won't fire at them.
other | :: ForceIdentification |
|
friend | :: boolean |
|
on_force_friends_changed instantly |
|
Is pathfinder busy? When the pathfinder is busy, it won't accept any more pathfinding requests.
position | :: MapPosition |
Position to find a network for |
Position to find a network for |
||
surface | :: SurfaceIdentification |
Surface to search on |
Surface to search on |
→ LuaLogisticNetwork? |
The found network or |
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. |
surface | :: SurfaceIdentification |
|
position | :: ChunkPosition |
The chunk position to unchart. |
The chunk position to unchart. |
||
surface | :: SurfaceIdentification |
Surface to unchart on. |
Surface to unchart on. |
Print text to the chat console of all players on this force.
message | :: LocalisedString |
|
color | :: Color? |
|
Messages that are identical to a message sent in the last 60 ticks are not printed again.
surface | :: SurfaceIdentification? |
The surface to search. Not providing a surface will match trains on any surface. |
The surface to search. Not providing a surface will match trains on any surface. |
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.
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. |
on_chart_tag_added? instantly |
Raised if the chart tag was successfully added. |
The chunk must be charted for a tag to be valid at that location.
Gets the saved progress for the given technology or nil
if there is no saved progress.
technology | :: TechnologyIdentification |
The technology |
The technology |
→ double? |
The progress as a percent. |
Sets the saved progress for the given technology. The technology must not be in progress, must not be completed, and the new progress must be < 100%.
technology | :: TechnologyIdentification |
The technology |
The technology |
||
progress | :: double |
Progress as a percent. Set to |
Progress as a percent. Set to |
Play a sound for every player in this force.
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. |
Gets train stops matching the given filters.
name | :: string or array[string]? |
The name(s) of the train stops. Not providing names will match any stop. |
The name(s) of the train stops. Not providing names will match any stop. |
||
surface | :: SurfaceIdentification? |
The surface to search. Not providing a surface will match stops on any surface. |
The surface to search. Not providing a surface will match stops on any surface. |
Add this technology to the back of the research queue if the queue is enabled. Otherwise, set this technology to be researched now.
technology | :: TechnologyIdentification |
|
→ boolean |
Whether the technology was successfully added. |
on_research_started? instantly |
Raised if the technology was successfully added. |
Stop the research currently in progress. This will remove any dependent technologies from the research queue.
Gets the linked inventory for the given prototype and link ID if it exists or nil
.
prototype | :: EntityPrototypeIdentification |
|
link_id | :: uint |
|
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.
other | :: ForceIdentification |
|
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.
other | :: ForceIdentification |
|
All methods and properties that this object supports.
Name of the force.
Prints "
|
Technologies owned by this force, indexed by name
.
Researches the technology for the player's force
|
Recipes available to this force, indexed by name
.
Prints the category of the given recipe
|
Multiplier of the manual mining speed. Default value is 0
. The actual mining speed will be multiplied by 1 + manual_mining_speed_modifier
.
Double the player's mining speed
|
Multiplier of the manual crafting speed. Default value is 0
. The actual crafting speed will be multiplied by 1 + manual_crafting_speed_modifier
.
Double the player's crafting speed
|
The currently ongoing technology research, if any.
Progress of current research, as a number in range [0, 1].
The previous research, if any.
The inserter stack size bonus for non stack inserters
Number of items that can be transferred by stack inserters. When writing to this value, it must be >= 0 and <= 254.
Number of character trash slots.
Maximum number of follower robots.
Additional lifetime for following robots.
The time, in ticks, before a placed ghost disappears.
Players belonging to this force.
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.
List of logistic networks, grouped by surface.
The item production statistics for this force.
The fluid production statistics for this force.
The kill counter statistics for this force.
The entity build statistics for this force (built and mined)
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
.
the number of additional inventory slots the character main inventory has.
The time, in ticks, before a deconstruction order is removed.
Ability to use zoom-to-world on map.
Ability to build ghosts through blueprint or direct ghost placement, or "mine" ghosts when using zoom-to-world.
Ability to create new blueprints using empty blueprint item when using zoom-to-world.
Ability to use deconstruction planner when using zoom-to-world.
Ability to use custom selection tools when using zoom-to-world.
true
if character requester logistics is enabled.
The number of rockets launched.
All of the items that have been launched in rockets. The attribute is a dictionary mapping the item prototype names to the launched amounts.
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.
Evolution factor of this force.
If friendly fire is enabled for this force.
Whether the research queue is available for this force.
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.
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.
Whether research is enabled for this force, see LuaForce::enable_research and LuaForce::disable_research
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}
Effective color of this force.
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.
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.