Home

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

Attributes

name

Name of the force.

technologies

Technologies owned by this force, indexed by name.

recipes

Recipes available to this force, indexed by name.

manual_mining_speed_modifier

Multiplier of the manual mining speed. Default value is 0. The actual mining speed will be multiplied by 1 + manual_mining_speed_modifier.

manual_crafting_speed_modifier

Multiplier of the manual crafting speed. Default value is 0. The actual crafting speed will be multiplied by 1 + manual_crafting_speed_modifier.

laboratory_speed_modifier

laboratory_productivity_bonus

worker_robots_speed_modifier

worker_robots_battery_modifier

worker_robots_storage_bonus

current_research

The currently ongoing technology research, if any.

research_progress

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

previous_research

The previous research, if any.

inserter_stack_size_bonus

The inserter stack size bonus for non stack inserters

bulk_inserter_capacity_bonus

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

Belt stack size bonus.

character_trash_slot_count

Number of character trash slots.

maximum_following_robot_count

Maximum number of follower robots.

following_robots_lifetime_modifier

Additional lifetime for following robots.

create_ghost_on_entity_death

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

circuit_network_enabled

cliff_deconstruction_enabled

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

mining_with_fluid

rail_support_on_deep_oil_ocean

rail_planner_allow_elevated_rails

vehicle_logistics

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

players

Players belonging to this force.

ai_controllable

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

List of logistic networks, grouped by surface.

character_running_speed_modifier

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

beacon_distribution_modifier

character_build_distance_bonus

character_item_drop_distance_bonus

character_reach_distance_bonus

character_resource_reach_distance_bonus

character_item_pickup_distance_bonus

character_loot_pickup_distance_bonus

character_inventory_slots_bonus

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

deconstruction_time_to_live

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

character_health_bonus

max_successful_attempts_per_tick_per_construction_queue

max_failed_attempts_per_tick_per_construction_queue

character_logistic_requests

true if character requester logistics is enabled.

rockets_launched

The number of rockets launched.

items_launched

All of the items that have been launched in rockets.

connected_players

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

train_braking_force_bonus

friendly_fire

If friendly fire is enabled for this force.

share_chart

If sharing chart data is enabled for this force.

index

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

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

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

platforms

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

This will include platforms that are pending deletion.

custom_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

Effective color of this force.

valid

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

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.

Methods

get_entity_count

LuaForce.get_entity_count(name: EntityID) -> uint32

Call As

force.get_entity_count("name")

Call Convention

Count entities of given type.

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

Parameters

Returns

disable_research

LuaForce.disable_research()

Call As

force.disable_research()

Call Convention

Disable research for this force.

enable_research

LuaForce.enable_research()

Call As

force.enable_research()

Call Convention

Enable research for this force.

disable_all_prototypes

LuaForce.disable_all_prototypes()

Call As

force.disable_all_prototypes()

Call Convention

Disable all recipes and technologies. Only recipes and technologies enabled explicitly will be useable from this point.

enable_all_prototypes

LuaForce.enable_all_prototypes()

Call As

force.enable_all_prototypes()

Call Convention

Enables all recipes and technologies. The opposite of LuaForce::disable_all_prototypes.

reset_recipes

LuaForce.reset_recipes()

Call As

force.reset_recipes()

Call Convention

Load the original version of all recipes from the prototypes.

enable_all_recipes

LuaForce.enable_all_recipes()

Call As

force.enable_all_recipes()

Call Convention

Unlock all recipes.

enable_all_technologies

LuaForce.enable_all_technologies()

Call As

force.enable_all_technologies()

Call Convention

Unlock all technologies.

research_all_technologies

LuaForce.research_all_technologies(include_disabled_prototypes?: boolean)

Call As

force.research_all_technologies()

Call Convention

Research all technologies.

Parameters

reset_technologies

LuaForce.reset_technologies()

Call As

force.reset_technologies()

Call Convention

Load the original versions of technologies from prototypes. Preserves research state of technologies.

reset

LuaForce.reset()

Call As

force.reset()

Call Convention

Reset everything. All technologies are set to not researched, all modifiers are set to default values.

reset_technology_effects

LuaForce.reset_technology_effects()

Call As

force.reset_technology_effects()

Call Convention

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

chart

LuaForce.chart(surface: SurfaceIdentification, area: BoundingBox)

Call As

force.chart(surface, area)

Call Convention

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

clear_chart

LuaForce.clear_chart(surface?: SurfaceIdentification)

Call As

force.clear_chart()

Call Convention

Erases chart data for this force.

Parameters

rechart

LuaForce.rechart(surface?: SurfaceIdentification)

Call As

force.rechart()

Call Convention

Force a rechart of the whole chart.

Parameters

chart_all

LuaForce.chart_all(surface?: SurfaceIdentification)

Call As

force.chart_all()

Call Convention

Chart all generated chunks.

Parameters

copy_from

LuaForce.copy_from(force: ForceID)

Call As

force.copy_from(force)

Call Convention

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

Parameters

copy_chart

LuaForce.copy_chart(source_force: ForceID, source_surface: SurfaceIdentification, destination_surface: SurfaceIdentification)

Call As

force.copy_chart(source_force, source_surface, destination_surface)

Call Convention

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

Parameters

is_chunk_charted

LuaForce.is_chunk_charted(surface: SurfaceIdentification, chunk_position: ChunkPosition) -> boolean

Call As

force.is_chunk_charted(surface, chunk_position)

Call Convention

Has a chunk been charted?

Parameters

Returns

is_chunk_visible

LuaForce.is_chunk_visible(surface: SurfaceIdentification, chunk_position: ChunkPosition) -> boolean

Call As

force.is_chunk_visible(surface, chunk_position)

Call Convention

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

Parameters

Returns

is_chunk_requested_for_charting

LuaForce.is_chunk_requested_for_charting(surface: SurfaceIdentification, chunk_position: ChunkPosition) -> boolean

Call As

force.is_chunk_requested_for_charting(surface, chunk_position)

Call Convention

Has a chunk been requested for charting?

Parameters

Returns

cancel_charting

LuaForce.cancel_charting(surface?: SurfaceIdentification)

Call As

force.cancel_charting()

Call Convention

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

Parameters

get_ammo_damage_modifier

LuaForce.get_ammo_damage_modifier(ammo: string) -> double

Call As

force.get_ammo_damage_modifier(ammo)

Call Convention

Parameters

Returns

set_ammo_damage_modifier

LuaForce.set_ammo_damage_modifier(ammo: string, modifier: double)

Call As

force.set_ammo_damage_modifier(ammo, modifier)

Call Convention

Parameters

get_gun_speed_modifier

LuaForce.get_gun_speed_modifier(ammo: string) -> double

Call As

force.get_gun_speed_modifier(ammo)

Call Convention

Parameters

Returns

set_gun_speed_modifier

LuaForce.set_gun_speed_modifier(ammo: string, modifier: double)

Call As

force.set_gun_speed_modifier(ammo, modifier)

Call Convention

Parameters

get_turret_attack_modifier

LuaForce.get_turret_attack_modifier(turret: EntityID) -> double

Call As

force.get_turret_attack_modifier(turret)

Call Convention

Parameters

Returns

set_turret_attack_modifier

LuaForce.set_turret_attack_modifier(turret: EntityID, modifier: double)

Call As

force.set_turret_attack_modifier(turret, modifier)

Call Convention

Parameters

set_cease_fire

LuaForce.set_cease_fire(other: ForceID, cease_fire: boolean)

Call As

force.set_cease_fire(other, true)

Call Convention

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

Parameters

get_cease_fire

LuaForce.get_cease_fire(other: ForceID) -> boolean

Call As

force.get_cease_fire(other)

Call Convention

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

Parameters

Returns

set_friend

LuaForce.set_friend(other: ForceID, friend: boolean)

Call As

force.set_friend(other, true)

Call Convention

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

Parameters

get_friend

LuaForce.get_friend(other: ForceID) -> boolean

Call As

force.get_friend(other)

Call Convention

Is other force in this force's friends list.

Parameters

Returns

is_pathfinder_busy

LuaForce.is_pathfinder_busy() -> boolean

Call As

force.is_pathfinder_busy()

Call Convention

Is pathfinder busy? When the pathfinder is busy, it won't accept any more pathfinding requests.

Returns

kill_all_units

LuaForce.kill_all_units()

Call As

force.kill_all_units()

Call Convention

Kill all units and flush the pathfinder.

find_logistic_network_by_position

LuaForce.find_logistic_network_by_position(position: MapPosition, surface: SurfaceIdentification) -> LuaLogisticNetwork?

Call As

force.find_logistic_network_by_position(position, surface)

Call Convention

Parameters

Returns

set_spawn_position

LuaForce.set_spawn_position(position: MapPosition, surface: SurfaceIdentification)

Call As

force.set_spawn_position(position, surface)

Call Convention

Parameters

get_spawn_position

LuaForce.get_spawn_position(surface: SurfaceIdentification) -> MapPosition

Call As

force.get_spawn_position(surface)

Call Convention

Parameters

Returns

set_surface_hidden

LuaForce.set_surface_hidden(surface: SurfaceIdentification, hidden: boolean)

Call As

force.set_surface_hidden(surface, true)

Call Convention

Parameters

get_surface_hidden

LuaForce.get_surface_hidden(surface: SurfaceIdentification) -> boolean

Call As

force.get_surface_hidden(surface)

Call Convention

Parameters

Returns

unchart_chunk

LuaForce.unchart_chunk(chunk_position: ChunkPosition, surface: SurfaceIdentification)

Call As

force.unchart_chunk(chunk_position, surface)

Call Convention

Parameters

get_item_launched

LuaForce.get_item_launched(item: ItemID) -> uint32

Call As

force.get_item_launched(item)

Call Convention

Gets the count of a given item launched in rockets.

Parameters

Returns

set_item_launched

LuaForce.set_item_launched(item: ItemID, count: uint32)

Call As

force.set_item_launched(item, count)

Call Convention

Sets the count of a given item launched in rockets.

Parameters

print

LuaForce.print(message: LocalisedString, print_settings?: PrintSettings)

Call As

force.print(message, print_settings)

Call Convention

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

add_chart_tag

LuaForce.add_chart_tag(surface: SurfaceIdentification, tag: ChartTagSpec) -> LuaCustomChartTag?

Call As

force.add_chart_tag(surface, tag)

Call Convention

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

Returns

find_chart_tags

LuaForce.find_chart_tags(surface: SurfaceIdentification, area?: BoundingBox) -> Array<LuaCustomChartTag>

Call As

force.find_chart_tags(surface, area)

Call Convention

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

Returns

reset_evolution

LuaForce.reset_evolution()

Call As

force.reset_evolution()

Call Convention

Resets evolution for this force to zero.

play_sound

LuaForce.play_sound(sound_specification: PlaySoundSpecification)

Call As

force.play_sound(sound_specification)

Call Convention

Play a sound for every player in this force.

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

Parameters

get_hand_crafting_disabled_for_recipe

LuaForce.get_hand_crafting_disabled_for_recipe(recipe: RecipeID) -> boolean

Call As

force.get_hand_crafting_disabled_for_recipe(recipe)

Call Convention

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

Parameters

Returns

set_hand_crafting_disabled_for_recipe

LuaForce.set_hand_crafting_disabled_for_recipe(recipe: RecipeID, hand_crafting_disabled: boolean)

Call As

force.set_hand_crafting_disabled_for_recipe(recipe, true)

Call Convention

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

add_research

LuaForce.add_research(technology: TechnologyID) -> boolean

Call As

force.add_research(technology)

Call Convention

Add this technology to the back of the research queue if the queue is enabled. Otherwise, set this technology to be researched now.

Parameters

Returns

cancel_current_research

LuaForce.cancel_current_research()

Call As

force.cancel_current_research()

Call Convention

Stop the research currently in progress. This will remove any dependent technologies from the research queue.

get_linked_inventory

LuaForce.get_linked_inventory(prototype: EntityID, link_id: uint32) -> LuaInventory?

Call As

force.get_linked_inventory(prototype, link_id)

Call Convention

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

Parameters

Returns

is_friend

LuaForce.is_friend(other: ForceID) -> boolean

Call As

force.is_friend(other)

Call Convention

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

Returns

is_enemy

LuaForce.is_enemy(other: ForceID) -> boolean

Call As

force.is_enemy(other)

Call Convention

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

Returns

lock_space_location

LuaForce.lock_space_location(name: SpaceLocationID)

Call As

force.lock_space_location("name")

Call Convention

Locks the planet to not be accessible to this force.

Parameters

unlock_space_location

LuaForce.unlock_space_location(name: SpaceLocationID)

Call As

force.unlock_space_location("name")

Call Convention

Unlocks the planet to be accessible to this force.

Parameters

is_space_location_unlocked

LuaForce.is_space_location_unlocked(name: SpaceLocationID)

Call As

force.is_space_location_unlocked("name")

Call Convention

Is the specified planet unlocked for this force?

Parameters

lock_quality

LuaForce.lock_quality(quality: QualityID)

Call As

force.lock_quality(quality)

Call Convention

Locks the quality to not be accessible to this force.

Parameters

unlock_quality

LuaForce.unlock_quality(quality: QualityID)

Call As

force.unlock_quality(quality)

Call Convention

Unlocks the quality to be accessible to this force.

Parameters

is_quality_unlocked

LuaForce.is_quality_unlocked(quality: QualityID)

Call As

force.is_quality_unlocked(quality)

Call Convention

Is the specified quality unlocked for this force?

Parameters

lock_space_platforms

LuaForce.lock_space_platforms()

Call As

force.lock_space_platforms()

Call Convention

Locks the space platforms, which disables the space platforms button

unlock_space_platforms

LuaForce.unlock_space_platforms()

Call As

force.unlock_space_platforms()

Call Convention

Unlocks the space platforms, which enables the space platforms button

is_space_platforms_unlocked

LuaForce.is_space_platforms_unlocked() -> boolean

Call As

force.is_space_platforms_unlocked()

Call Convention

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

Returns

create_space_platform

LuaForce.create_space_platform{ name?: string, planet: SpaceLocationID, starter_pack: ItemWithQualityID } -> LuaSpacePlatform?

Call As

force.create_space_platform{ planet=planet, starter_pack=starter_pack }

Call Convention

Creates a new space platform on this force.

Parameters

Returns

get_evolution_factor

LuaForce.get_evolution_factor(surface?: SurfaceIdentification) -> double

Call As

force.get_evolution_factor()

Call Convention

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

Parameters

Returns

get_evolution_factor_by_pollution

LuaForce.get_evolution_factor_by_pollution(surface?: SurfaceIdentification) -> double

Call As

force.get_evolution_factor_by_pollution()

Call Convention

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

Parameters

Returns

get_evolution_factor_by_time

LuaForce.get_evolution_factor_by_time(surface?: SurfaceIdentification) -> double

Call As

force.get_evolution_factor_by_time()

Call Convention

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

Parameters

Returns

get_evolution_factor_by_killing_spawners

LuaForce.get_evolution_factor_by_killing_spawners(surface?: SurfaceIdentification) -> double

Call As

force.get_evolution_factor_by_killing_spawners()

Call Convention

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

Parameters

Returns

set_evolution_factor

LuaForce.set_evolution_factor(factor: double, surface?: SurfaceIdentification)

Call As

force.set_evolution_factor(factor, surface)

Call Convention

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

Parameters

set_evolution_factor_by_pollution

LuaForce.set_evolution_factor_by_pollution(factor: double, surface?: SurfaceIdentification)

Call As

force.set_evolution_factor_by_pollution(factor, surface)

Call Convention

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

Parameters

set_evolution_factor_by_time

LuaForce.set_evolution_factor_by_time(factor: double, surface?: SurfaceIdentification)

Call As

force.set_evolution_factor_by_time(factor, surface)

Call Convention

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

Parameters

set_evolution_factor_by_killing_spawners

LuaForce.set_evolution_factor_by_killing_spawners(factor: double, surface?: SurfaceIdentification)

Call As

force.set_evolution_factor_by_killing_spawners(factor, surface)

Call Convention

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

Parameters

get_item_production_statistics

LuaForce.get_item_production_statistics(surface: SurfaceIdentification) -> LuaFlowStatistics

Call As

force.get_item_production_statistics(surface)

Call Convention

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

Parameters

Returns

get_fluid_production_statistics

LuaForce.get_fluid_production_statistics(surface: SurfaceIdentification) -> LuaFlowStatistics

Call As

force.get_fluid_production_statistics(surface)

Call Convention

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

Parameters

Returns

get_kill_count_statistics

LuaForce.get_kill_count_statistics(surface: SurfaceIdentification) -> LuaFlowStatistics

Call As

force.get_kill_count_statistics(surface)

Call Convention

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

Parameters

Returns

get_entity_build_count_statistics

LuaForce.get_entity_build_count_statistics(surface: SurfaceIdentification) -> LuaFlowStatistics

Call As

force.get_entity_build_count_statistics(surface)

Call Convention

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

Parameters

Returns

get_logistic_groups

LuaForce.get_logistic_groups(type?: defines.logistic_group_type) -> Array<string>

Call As

force.get_logistic_groups()

Call Convention

Gets the names of the current logistic groups.

Parameters

Returns

get_logistic_group

LuaForce.get_logistic_group(name: string, type?: defines.logistic_group_type) -> LogisticGroup?

Call As

force.get_logistic_group(name, type)

Call Convention

Gets the information about the given logistic group.

Parameters

Returns

create_logistic_group

LuaForce.create_logistic_group(name: string, type?: defines.logistic_group_type)

Call As

force.create_logistic_group(name, type)

Call Convention

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

Parameters

delete_logistic_group

LuaForce.delete_logistic_group(name: string, type?: defines.logistic_group_type)

Call As

force.delete_logistic_group(name, type)

Call Convention

Deletes the given logistic group if it exists.

Parameters

get_chunk_chart

LuaForce.get_chunk_chart(surface: SurfaceIdentification, chunk_position: ChunkPosition) -> string?

Call As

force.get_chunk_chart(surface, chunk_position)

Call Convention

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

Returns

script_trigger_research

LuaForce.script_trigger_research(technology: TechnologyID)

Call As

force.script_trigger_research(technology)

Call Convention

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

Parameters