0.17 Mod/Script changelog as of February 25 2019

[Rseding91]

This is the 0.17 mod/script change log as of February 25 2019. Mostly just so people can see what's coming to better request things that aren't already done.

Note: this doesn't mean 0.17 is around the corner - it's just me trying to be transparent about future changes related to mods.

Lua API docs can be found here. (updated January 04)

Change log:

Modding:

• Added a new entity type "infinity-pipe" that automatically adds/removes fluid from itself; similar to the infinity-chest.
• Added a new entity type "heat-interface" that automatically sets its own temperature.
• Added "void" energy_source type which makes any entity using the type not require power.
• Added CraftingMachinePrototype::show_recipe_icon which changes if the recipe icon is shown in alt-mode.
• Added "stop" AI command, which tells the unit to just stop moving where it is. Takes a "ticks_to_wait" parameter, after which it returns to normal.
• Added LuaGuiElement type "list-box".
• Added Entity prototype flags "no-automated-item-removal" and "no-automated-item-insertion".
• Added support for hidden optional dependencies via '(?) mod-name'.
• Added SelectionToolPrototype flags "not-same-force", "friend", and "enemy".
• Added SelectionToolPrototype optional filters: entity_filters, entity_type_filters, tile_filters, entity_filter_mode, and tile_filter_mode.
• Added SelectionToolPrototype optional filters: alt_entity_filters, alt_entity_type_filters, alt_tile_filters, alt_entity_filter_mode, and alt_tile_filter_mode.
• Added support to set wire_count on wires to define how many items are needed to connect 2 entities.
• Added UnitPrototype::ai_settings, which allows overriding default biter behavior.
• Added a spectator controller type that can view anything but can't change anything.
• Added GeneratorPrototype::burner to allow making an entity that burns fuel and produces power.
• Added ticks_to_wait parameter to wander ai command.
• Added Entity prototype property "next_upgrade".
• Added support to set draw_copper_wires and draw_circuit_wires for any entity that uses wires.
• Added optional "min_working_temperature" and "default_temperature" to heat buffer prototype.
• Added optional technology prototype property "hidden".
• Added optional fluid prototype property "hidden".
• Added "fluid" energy_source type can be used for both fuel-value based fluids, and heat capacity based fluids configured the same was as the generator entity.
• Added ReactorPrototype::scale_energy_usage to allow making a heat source that stops consuming fuel when max temperature is reached.
• Added EnemySpawnerPrototype::min_darkness_to_spawn and max_darkness_to_spawn.
• Added optional beam prototype properties random_end_animation_rotation and transparent_start_end_animations.
• Added rotation_speed value to Unit prototype.
• Added support for arbitrary non-circular references to named noise expressions.
• Added "spot-noise" noise function.
• Added "if-else-chain" and "literal-boolean" noise expression types.
• Added "cutscene" controller.
• Added "speech-bubble" entity.
• Added ResourceEntityPrototype::randomize_visual_position.
• Added EquipmentGridPrototype::locked.
• Added DamageType::hidden.
• Added optional draw_cargo property to construction robot and logistic robot prototypes.
• Added optional fluid_product to production achievement prototypes.
• Added UnitPrototype::affected_by_tiles.
• Added LuaStyle::stretch_image_to_widget_size, only applies to "sprite" widget styles.
• Added optional EntityPrototype::map_generator_bounding_box.
• Added EntityPrototypeFlag "not-upgradable".
• Added EntityPrototypeFlags "no-copy-paste" and "not-selectable-in-game".
• Added ItemPrototypeFlags "only-in-cursor", "not-stackable", "can-extend-inventory", "primary-place-result" and "mod-openable".
• Changed radars so they support dynamic energy source types.
• Changed ItemWithInventoryPrototype flag "when_manually_filtered" to "when-manually-filtered".
• Changed SelectionToolPrototype flag "matches-force" to "same-force".
• Changed the maximum number of surfaces from 255 to 4,294,967,295.
• Changed migration scripts so they run in the context of the mod that created them.
• Changed TilePrototype::decorative_removal_probability default value to 0 (it was 1).
• Changed ReactorPrototype::burner to ReactorPrototype::energy_source to allow heat sources with alternate energy types.
• Changed ElectricEnergyInterfacePrototype::enable_gui to gui_mode.
• Changed EnemySpawnerPrototype::result_units to support any type of entity.
• Changed recipes to support having no results by setting results = {}.
• Lua scripts can now use require("__mod-name__.file") syntax.
• AutoplaceSpecifications can now be defined in terms of probability_expression and richness_expression as an alternative to peaks.
• property_expression_name values can be numeric constants.
• All autoplace controls are now available as noise expression variables.
• energy_per_movement and energy_per_rotation of inserter is now specified in energy format (aka "5KJ") instead of just a number.
• Removed the "default-" prefix from core NamedNoiseExpressions; property_expression_names in MapGenSettings simply override the expression named by the key.
• Removed ItemPrototypeFlags "goes-to-main-inventory" and "goes-to-quickbar".

Scripting:

• Added LuaRendering accessed via the lua global "rendering".
• Added LuaEntity::get_infinity_pipe_filter() and set_infinity_pipe_filter().
• Added LuaEntity::recipe_locked read/write for assembling machines.
• Added LuaRailPath.
• Added LuaTrain::path read.
• Added LuaEntity::connected_rail read.
• Added previous_direction to the on_player_rotated_entity event.
• Added LuaItemStack::deconstruct_area() and cancel_deconstruct_area().
• Added LuaSurface::deconstruct/cancel_deconstruct optional parameters skip_fog_of_war and item.
• Added LuaEntity::clone().
• Added LuaSurface::clone_area().
• Added LuaSurface::clone_entities().
• Added LuaGameScript::auto_save().
• Added LuaEntity::neighbours support for power switches, wall-connectable entities, and reactors.
• Added LuaFluidBoxPrototype.
• Added LuaEntityPrototype::fluidbox_prototypes read.
• Added LuaGameScript::take_technology_screenshot().
• Added LuaSurface::clear().
• Added LuaSurface::solar_power_multiplier read/write.
• Added on_pre_surface_cleared and on_surface_cleared events.
• Added on_pre_chunk_deleted and on_chunk_deleted events.
• Added on_chart_tag_added, on_chart_tag_modified, and on_chart_tag_removed events.
• Added LuaGameScript::styles read.
• Added LuaEntity::crafting_speed read.
• Added LuaTrain::max_forward_speed and max_backward_speed read.
• Added on_train_schedule_changed event.
• Added LuaForce::previous_research read/write.
• Added LuaSurface::find_decoratives_filtered().
• Added LuaEntity::inserter_filter_mode read/write.
• Added LuaEntity::neighbour_bonus read.
• Added LuaEntityPrototype::neighbour_bonus and neighbour_collision_increase read.
• Added LuaEntityPrototype::container_distance, belt_distance and belt_length read.
• Added LuaGameScript::table_to_json() and LuaGameScript::json_to_table().
• Added events on_player_banned, on_player_kicked, and on_player_unbanned.
• Added event on_rocket_launch_ordered.
• Added LuaItemPrototype::wire_count read.
• Added LuaRecipePrototype::main_product read.
• Added LuaEntity::get_fluid_count(), get_fluid_contents(), remove_fluid(), insert_fluid(), and clear_fluid_inside().
• Added LuaEntity::silent_revive().
• Added LuaFluidBox::get_prototype().
• Added LuaSurface::request_path().
• Added LuaGameScript::reload_mods().
• Added on_player_toggled_alt_mode, on_player_repaired_entity, and on_player_fast_transferred events.
• Added on_game_created_from_scenario event.
• Added on_surface_renamed event.
• Added on_ai_command_completed event, which can be used to detect command completion and failure/success.
• Added "pathfind_flags" parameter to "go_to_location" AI command.
• Added "radius" and "wander_in_group" parameters to "wander" AI command.
• Added "radius" parameter to "go_to_location" AI command.
• Added support for mods to change their own mod settings runtime.
• Added LuaEntityPrototype::next_upgrade read.
• Added optional parameters to LuaSurface::create_entity, LuaEntity::destroy and LuaEntity::revive to raise the associated script events.
• Added support to run console commands in a specific mod context via: /c __mod-name__ *command*.
• Added LuaTechnologyPrototype::hidden read.
• Added LuaFluidPrototype::hidden read.
• Added LuaSurface::get_map_exchange_string().
• Added LuaGameScript::get_map_exchange_string().
• Added LuaFlowStatistics::get_flow_count().
• Added LuaEntity::trains_in_block read.
• Added LuaGameScript::get_player().
• Added LuaGameScript::get_surface().
• Added LuaGameScript::set_wait_for_screenshots_to_finish().
• Added LuaGuiElement::resize_to_sprite (read/write).
• Added LuaGroup::localised_name read.
• Added SpritePath::equipment.
• Added LuaEquipmentGridPrototype::background_color read.
• Added LuaItemPrototype::reload_time read.
• Added highlight-box entity that can be passed a "bounding_box" or "source" entity parameter to display a highlight box around an area or entity.
• Added LuaEntityPrototype::is_building read.
• Added LuaEntityPrototype::automated_ammo_count read.
• Added LuaEntity::get_beam_source(), set_beam_source(), get_beam_target() and set_beam_target().
• Added LuaSurface::get_closest().
• Added LuaSurface::get_total_pollution().
• Added LuaPlayer::create_local_flying_text().
• Added LuaEntityPrototype::darkness_for_all_lamps_on and darkness_for_all_lamps_off read.
• Added LuaEntity::status read.
• Added LuaLogisticNetwork::robots, construction_robots, logistic_robots read.
• Added LuaGameScript::get_train_stops(), LuaSurface::get_train_stops(), and LuaForce::get_train_stops().
• Added LuaEntityPrototype::min_darkness_to_spawn and max_darkness_to_spawn read.
• Added "loot" to the on_entity_died event.
• Added LuaTrain::go_to_station().
• Added support to set quality when using LuaGameScript::take_screenshot.
• Added LuaForce::evolution_factor_by_pollution, evolution_factor_by_time, and evolution_factor_by_killing_spawners read/write.
• Added optional create_build_effect_smoke parameter to LuaSurface::create_entity.
• Added LuaEntity::drop_target/pickup_target write.
• Added LuaEntity::ghost_has_flag().
• Added runtime editable speed attribute to Unit.
• Added LuaSurface::get_starting_area_radius().
• Added LuaItemPrototype::robot_action read.
• Added LuaEntity::enable_logistics_while_moving read/write.
• Added optional render_player_index parameter for flying-text and simple-entities to LuaSurface::create_entity.
• Added LuaEntity::render_player read/write.
• Added LuaEntity::render_to_forces read/write.
• Added LuaGameScript::disable_tutorial_triggers().
• Added LuaEntity::get_radius() and LuaEntityPrototype::radius read.
• Added LuaEntity::get_health_ratio().
• Added LuaSurface::find_units().
• Added LuaTransportLine::output_lines read.
• Added LuaEntity::pump_rail_target read.
• Added LuaTrain::get_rails().
• Added LuaEquipmentGridPrototype::locked read.
• Added LuaForce::index read.
• Added direction to LuaSurface::count/find_entities_filtered.
• Added collision_mask to LuaSurface::count/find_entities_filtered.
• Added LuaEntity::clear_market_items().
• Added LuaEntityPrototype::cliff_explosive_prototype read.
• Added LuaDamagePrototype::hidden read.
• Added LuaControl::character_running_speed read.
• Added LuaEntityPrototype::draw_cargo read.
• Added LuaPlayer::use_from_cursor().
• Added LuaGameScript::autosave_enabled variable, that can be used to disable autosaving.
• Added LuaEntity::ai_settings read.
• Added LuaAISettings::destroy_when_commands_fail. When true, units will be destroyed when repeatedly failing to execute commands.
• Added LuaAISettings::allow_try_return_to_spawner. When true, units will try to return to a spawner when they are idle.
• Added LuaAISettings::do_separation. When true, units will try to separate themselves from nearby friendly units.
• Added LuaEntity::moving. Returns true if the unit is moving.
• Added on_unit_group_created, on_unit_added_to_group, and on_unit_removed_from_group events.
• Added LuaEntity::create_build_effect_smoke.
• Added LuaEntityPrototype::vision_distance read.
• Added LuaPlayer::open_map(), zoom_to_world() and close_map().
• Added LuaPlayer::render_mode read.
• Added LuaPlayer::map_view_settings write.
• Added LuaStyle::top_margin, right_margin, bottom_margin and left_margin read/write.
• Added LuaStyle::use_header_filler, natural_width and natural_height read/write.
• Added LuaStyle::extra_padding_when_activated read/write.
• Added LuaStyle::extra_top_margin_when_activated, extra_bottom_margin_when_activated, extra_left_margin_when_activated and extra_right_margin_when_activated read/write.
• Added LuaEntity::electric_network_id read.
• Added LuaControl::character_additional_mining_categories read/write.
• Added LuaGameScript::draw_resource_selection read/write.
• Added LuaForce::get_hand_crafting_disabled_for_recipe() and set_hand_crafting_disabled_for_recipe().
• Added LuaEntityPrototype::map_generator_bounding_box read.
• Added LuaEntity::release_from_spawner().
• Added on_cutscene_waypoint_reached, on_entity_cloned, on_area_cloned, on_marked_for_upgrade, on_cancelled_upgrade,
  on_post_entity_died, on_pre_player_removed, on_pre_robot_exploded_cliff, on_robot_exploded_cliff,
  on_script_path_request_finished, on_surface_imported, on_player_toggled_map_editor events.
• Added LuaEntity::timeout read/write.
• Added LuaEntity::highlight_box_type and highlight_box_blink_interval read/write.
• Added LuaEntity::order_upgrade(), cancel_upgrade() and to_be_upgraded().
• Added LuaEntity::research_queue_enabled read/write.
• Added LuaGameScript::get_active_entities_count().
• Added LuaGameScript::ticks_played read.
• Added LuaGameScript::tick_paused and ticks_to_run read/write.
• Added LuaItemPrototype::infinite read.
• Added LuaItemStack::clear_upgrade_item(), get_mapper(), set_mapper().
• Added LuaItemStack::is_upgrade_item read.
• Added LuaLogisticCell::logistics_connection_distance read.
• Added LuaLogisticNetwork::select_pickup_point() and select_drop_point().
• Added LuaPlayer::jump_to_cutscene_waypoint().
• Added LuaUnitGroup::group_number read.
• Changed LuaEntity::destroy() to accept a table of arguments.
• Changed LuaEntity::revive() to accept a table of arguments.
• Changed the player_used_capsule event so it's fired after the capsule item is consumed from the cursor.
• Changed LuaEntity::splitter_filter, splitter_input_priority, and splitter_output_priority so they also work on ghosts.
• Changed LuaSurface::destroy_decoratives() to take filters similar to find_entities_filtered.
• Changed LuaEntityPrototype::items_to_place_this and LuaTilePrototype::items_to_place_this to return an array of SimpleItemStack.
• Changed most LuaEntity properties/functions to also work on ghosts.
• Changed on_player_crafted_item item_stack to allow editing the stack before it's put into the player inventory.
• Changed LuaSurface::regenerate_entity()/regenerate_decorative() to treat "nil" as "all" for the autoplace list.
• Changed LuaEquipmentPrototype::energy_source to return a LuaElectricEnergySourcePrototype.
• Renamed LuaEntity::get_infinity_filter(), set_infinity_filter(), and infinity_filters to get_infinity_container_filter(),
  set_infinity_container_filter(), and infinity_container_filters.
• Renamed on_canceled_deconstruction event to on_cancelled_deconstruction.
• Fixed the spelling of LuaForce::max_successful_attempts_per_tick_per_construction_queue.
• LuaSurface::find_entities/filtered now accepts a zero sized bounding box as "find everything that collides with this point".
• CustomSprite now scales to the size of the sprite if a manual size isn't defined.
• Removed LuaStyle::visible, LuaGuiElement::visible is used instead.
• Removed LuaSurface::get_tile_properties().
• Removed LuaCustomChartTag::orientation and target.
• Removed LuaFluidPrototype::pressure_to_speed_ratio and flow_to_energy_ratio.

[eradicator]

Thanks! Looking awesome so far! Your work is most appreciated and factorio wouldn't be the same without you :)

Just to be really, really...really sure, does "void" energy work with absolutely. every. prototype. or does it have limitations like burner energy source?

[Boodals]

Looking forward to the clone functions.
Does LuaSurface::request_path create paths similar to biter paths? Or to train paths?

[bobingabout]

It Begins!

[Rseding91]

Just to be really, really...really sure, does "void" energy work with absolutely. every. prototype. or does it have limitations like burner energy source?

Everything except the following supports it:

• Accumulator
• Electric energy interface
• Generator
• Solar panel
• Equipment

[eradicator]

Just to be really, really...really sure, does "void" energy work with absolutely. every. prototype. or does it have limitations like burner energy source?

Everything except the following supports it:

• Accumulator
• Electric energy interface
• Generator
• Solar panel
• Equipment

Thanks for the answer. That sounds reasonable and fits all my current concepts :).
Though,...staring at "equipment" and thinking about possible usecases....makes me want armor with a built-in energy source to artificially limit the maximum power for cheap armor. :lol: :lol:

[bobingabout]

Just to be really, really...really sure, does "void" energy work with absolutely. every. prototype. or does it have limitations like burner energy source?

Everything except the following supports it:

• Accumulator
• Electric energy interface
• Generator
• Solar panel
• Equipment

Yeah, it all makes sense except maybe equipment. I've actually wanted to make a couple of peices that draw no power at all (the tuning kit for trains that increases acceleration for example), and although you can set the draw to 0, you still need a power source for it to work.

Then again, Equipment is special in that you can't specify a source, it just assumes grid equipment energy.

The rest of the exceptions make sense, because they're all special cases.
Accumulator is electricity in/out, EEI is a magic energy creating/destroying entity, Generator specifically converts fluids into electricity, and the Solar panel makes electricity out of light.

[eradicator]

• Added Entity prototype flags "no-inserter-pickup" and "no-inserter-dropoff".

Btw does this also apply to loaders? I can't find the original thread so i don't know the original intent. And i can think of applications for both it applying to loaders (entity should be manually/script used only) and it not applying to loaders (entity is supposed to be some kind of belt-driven assembly line).

[Rseding91]

• Added Entity prototype flags "no-inserter-pickup" and "no-inserter-dropoff".

Btw does this also apply to loaders? I can't find the original thread so i don't know the original intent. And i can think of applications for both it applying to loaders (entity should be manually/script used only) and it not applying to loaders (entity is supposed to be some kind of belt-driven assembly line).

Loaders are a form of automated insertion/removal so yes it applies.

[Omnifarious]

As a random thought, it might be nice to specify that an item can be moved by inserters, but not by bot. I'm thinking of Deadlock's Crating, Universal Palleting, and Shrink Wrap.

I'm not sure if this would even be possible though.

And the hovercraft mod would greatly benefit from the ability of a vehicle to move in a direction that was different from where it was pointing. Otherwise the hovercraft handles far too adroitly.

[bobingabout]

I don't know about the "Can be moved by robots" filters... One of the key rules for adding new content is that it shouldn't add additional slowdowns. Inserters and robots move A LOT of stuff, so having them check to see if they can pick up an item every time they try would be CPU expensive.
Having said that, Inserters can have that filter option that limits it to specific items only, so it's not entirely out of the question, it just depends on implementation.
It is worth looking into in source though, but, don't hold your breath on it.
If it were to be done though, it should be done right. I would imagine can_be_picked_up_by being a new table, with tags such as player, robot and inserter, maybe stack_inserter all being options set to true be default, that you could turn off.
inserter and stack_inserter could be a bit ambiguous though, so in theory stack inserter would default to whatever inserter is set to unless specified alongside it.

[eradicator]

Checking the list after some time...oh, nice more delicious cookies =).

• Added highlight-box entity that can be passed a "bounding_box" or "source" entity parameter to display a highlight box around an area or entity.
• Added LuaPlayer::create_local_flying_text().

Can i assume that these two will only be visible to a specific player? Can highlight boxes use custom sprites?

[Nexela]

Checking the list after some time...oh, nice more delicious cookies =).

• Added highlight-box entity that can be passed a "bounding_box" or "source" entity parameter to display a highlight box around an area or entity.
• Added LuaPlayer::create_local_flying_text().

Can i assume that these two will only be visible to a specific player? Can highlight boxes use custom sprites?

Good assumption (highlight-box can be set to render to a player). No custom sprites

[bobingabout]

• Added "fluid" energy_source type can be used for both fuel-value based fluids, and heat capacity based fluids configured the same was as the generator entity.

Woo.

Maybe I'm blind, but I didn't see the changes to the reactor in the list.

[dewiniaid]

As a random thought, it might be nice to specify that an item can be moved by inserters, but not by bot. I'm thinking of Deadlock's Crating, Universal Palleting, and Shrink Wrap.

I don't know about the "Can be moved by robots" filters... One of the key rules for adding new content is that it shouldn't add additional slowdowns. Inserters and robots move A LOT of stuff, so having them check to see if they can pick up an item every time they try would be CPU expensive.

The simple solution would be "Can be requested". If the item can't be selected by a requester/buffer chest or by the player (who is essentially just a requester/active provider chest anyways), it'd prevent logistics bots from going for it.

Unless someone cheeses it by using (filtered?) storage chests + active providers. That would only work in certain setups though.

[Omnifarious]

The simple solution would be "Can be requested". If the item can't be selected by a requester/buffer chest or by the player (who is essentially just a requester/active provider chest anyways), it'd prevent logistics bots from going for it.

Unless someone cheeses it by using (filtered?) storage chests + active providers. That would only work in certain setups though.

Oh! Yeah, that'd be perfect. If you just turned it off so it couldn't be used as a filter or request in the logistics system at all, it would make it really hard to do any kind of bulk transport of the item. It would still be picked up off the ground or from inside machines by the decon planner. And you could still put it in your garbage slot or in an active provider, and it'd end up in a storage chest somewhere. But it'd be way too unpredictable to use for any kind of logistics-based delivery system.

A player wouldn't even be able to request on using the player's logistics slots.

And that should only have a performance issue when someone is setting a logistics filter.

Yeah, that should work great.

[dewiniaid]

It still wouldn't prevent the Active Provider -> Storage Chest cheese though. Which, while not particularly useful in a main base or whatnot, would be just fine in an area designed for it.

[Optera]

From what I gather on_chunk_deleted is called after a chunk has been removed and entities on it are already invalid.
Could we have on_pre_chunk_deleted to safely remove script associated entities before they become invalid from chunk deletion?

[theDirector]

Thanks!

energy_source "void" and energy_source "fluid" entity properties will solve problems I am having. It also opens up more themes of item production systems that are possible!

[DiegoPro77]

EnemySpawnerPrototype::min_darkness_to_spawn and max_darkness_to_spawn
and
EnemySpawnerPrototype::result_units

could be used for create and tier biter farms?

And the fact that "Recipes now support having no results by setting results = {}." is a very helping hand for delete unwanted items and fluids in processings, like flare stacks.

Great work, congratulations.
_DiegoPro77