The changes are coming
Next week, with the
mod breaking gui changes in 0.18.27, we will also implement the script.raise_event rework discussed here in this thread.
Summary
script.raise_event will be restricted to raising events generated with script.generate_event_name and raising the following built-in events:
- on_console_chat
- on_player_crafted_item
- on_player_fast_transferred
- on_biter_base_built
- on_market_item_purchased
- script_raised_built
- script_raised_destroy
- script_raised_revive
- script_raised_set_tiles
No other built-in events will be raisable directly.
All the raisable built-in events will have the data that you pass to them validated so that mandatory fields must be present and fields must have the correct types. Failing to provide correct and complete event data will result in an error for the mod raising the event.
Extra data that is provided in the event data table e.g. non_existant_event_field = "foo" is not passed along with game events, however the 4 script_raised_* events will pass it along.
Event filtering now also works for events raised by mods, this was the major point of these changes.
Already released in 0.18.26 are the following new events and extra ways to automatically raise events:
- Added script_raised_set_tiles.
- Added by_player to LuaEntity::copy_settings()
- Added by_player to LuaEquipmentGrid::take, take_all, clear, and put.
More information
Replacements for raise event calls that no longer work
Thanks to JanSharp, we have a list of raise_event calls that mods use. Based on that, I am providing you a list of how to replace your (soon to be) broken raise event calls:
Direct replacement:
- on_entity_spawned - use script_raised_built
- on_entity_died - use script_raised_destroy
- on_player_built_tile - use script_raised_set_tiles/script_raised_revive
- on_robot_built_entity - use script_raised_built/script_raised_revive
- on_robot_built_tile - use script_raised_built/script_raised_revive
- on_robot_mined_tile - use script_raised_destroy
- on_robot_pre_mined - use script_raised_destroy
Game raises event automatically:
- on_player_armor_inventory_changed - the game raises this automatically
- on_player_cursor_stack_changed - the game raises this automatically
- on_player_driving_changed_state - the game raises this automatically
Function raises event automatically:
- on_entity_settings_pasted - use by_player in LuaEntity::copy_settings() which raises the event automatically
- on_player_placed_equipment - use by_player in LuaEquipmentGrid::take, take_all, clear, and put which raises the event automatically
- on_player_rotated_entity - use LuaPlayer.rotate() which raises the event automatically
- on_pre_player_mined_item - use LuaPlayer.mine_entity() which raises the event automatically
- on_player_respawned - set ticks_to_respawn = 0 for respawning which raises the event automatically
- on_resource_depleted - use LuaEntity.deplete() which raises the event automatically
Function raises event automatically, alternative script_raised_*:
- on_player_mined_item - use LuaPlayer.mine_entity() which raises the event automatically, alternatively use script_raised_destroy
- on_built_entity - use LuaPlayer.build_from_cursor() which raises the event automatically, alternatively use script_raised_built/script_raised_revive
- on_entity_cloned - the clone function raises the event automatically, alternatively use script_raised_built
Special case:
- on_gui_click - use remote interfaces to interact with other mods (mod was using this to "click" gui elements)
Some notes on raisability removal reasons
None of the
on_robot_* events that were being raised by mods had valid construction robots being provided. For that reason, these can replaced with the generic script_raised_* events without losing information.
Originally
on_built_entity was planned to be raisable due to being whopping 40 out of the 100 raised game events (does not include script_raised_*) and we did not want to break all those mods. However, I went through all 40 places where the event was being used, and it turned out that only 5 of those uses were giving all mandatory fields (and 3 of those places were just copies of the other places). This means that all 35 other raise_event(on_built_entity,..) calls would have broken anyways due to the new validation. So, we decided to remove the ability to raise the event directly, since it results in the same amount of broken mods while also forcing mods to raise the correct events.
Extra features
The following functions are being added in 0.18.27, they allow you to raise the built-in events without using script.raise_event, so you can reserve that for custom mod events. You don't have to use these functions, script.raise_event will continue to work for the events listed in the summary.
- script.raise_console_chat
- script.raise_player_crafted_item
- script.raise_player_fast_transferred
- script.raise_biter_base_built
- script.raise_market_item_purchased
- script.raise_script_built
- script.raise_script_destroy
- script.raise_script_revive
- script.raise_script_set_tiles
The following three events can now be filtered based on the entity passed to them:
- script_raised_built
- script_raised_destroy
- script_raised_revive
My tip
You can already replace all your soon to be broken raise_event calls right now since all listed fixes already work (if you dont want to use the new raise_* functions). If you do that, make sure to double-check that you are raising the raisable events with the correct fields. If you do these fixes now, you wont have to do them at the same time as the GUI fixes :)
Feedback
We continue to listen to feedback on this and will adjust things if we feel it's beneficial, so please feel free to discuss these changes.
Disclaimer
There is always the possibility that these changes are delayed/the changes change. I will update this post if that is the case.