225 lines
7.7 KiB
Lua
225 lines
7.7 KiB
Lua
--- From flib 0.10.1 by Raiguard
|
|
---
|
|
--- Syntax sugar for event manipulation.
|
|
---
|
|
--- Along with the documented functions, this module dynamically generates syntax-shortcuts for all `defines.events`
|
|
--- events. These shortcuts are only to be used when registering a handler to a single event. To register a handler to
|
|
--- multiple events, use `event.register`.
|
|
---
|
|
--- To use a shortcut, replace `event.register(defines.events.on_built_entity, handler, filters)` with
|
|
--- `event.on_built_entity(handler, filters)`. You can also deregister the handler using `event.on_built_entity(nil)`.
|
|
local flib_event = {}
|
|
|
|
-- Generate syntax shortcuts
|
|
-- TODO: Find a way to document these
|
|
for name, id in pairs(defines.events) do
|
|
flib_event[name] = function(handler, filters)
|
|
return script.on_event(id, handler, filters)
|
|
end
|
|
end
|
|
|
|
--- Register or deregister a handler to be run during mod init.
|
|
---
|
|
--- # Examples
|
|
---
|
|
--- ```lua
|
|
--- -- Register a handler to run during mod init
|
|
--- event.on_init(function() log("on_init") end)
|
|
--- -- Deregister the registered handler, if one exists
|
|
--- event.on_init(nil)
|
|
--- ```
|
|
--- @param handler? function The handler to register, or `nil` to deregister the registered handler.
|
|
function flib_event.on_init(handler)
|
|
script.on_init(handler)
|
|
end
|
|
|
|
--- Register or deregister a handler to be run during mod load.
|
|
---
|
|
--- # Examples
|
|
---
|
|
--- ```lua
|
|
--- -- Register a handler to run during mod load
|
|
--- event.on_load(function() log("on_load") end)
|
|
--- -- Deregister the registered handler, if one exists
|
|
--- event.on_load(nil)
|
|
--- ```
|
|
--- @param handler? function The handler to register, or `nil` to deregister the registered handler.
|
|
function flib_event.on_load(handler)
|
|
script.on_load(handler)
|
|
end
|
|
|
|
--- Register or deregister a handler to be run when mod configuration changes.
|
|
---
|
|
--- # Examples
|
|
---
|
|
--- ```lua
|
|
--- -- Register a handler to run when mod configuration changes
|
|
--- event.on_configuration_changed(function() log("on_configuration_changed") end)
|
|
--- -- Deregister the registered handler, if one exists
|
|
--- event.on_configuration_changed(nil)
|
|
--- ```
|
|
--- @param handler? function The handler to register, or `nil` to deregister the registered handler.
|
|
function flib_event.on_configuration_changed(handler)
|
|
script.on_configuration_changed(handler)
|
|
end
|
|
|
|
--- Register or deregister a handler to run every N ticks.
|
|
---
|
|
--- # Examples
|
|
---
|
|
--- ```lua
|
|
--- -- Register a handler to run every 30 ticks
|
|
--- event.on_nth_tick(30, function(e) log("30th tick!") end)
|
|
--- -- Deregister the registered handler, if one exists
|
|
--- event.on_nth_tick(30, nil)
|
|
--- ```
|
|
--- @param nth_tick? number|number[] The nth-tick(s) to invoke the handler on, or `nil` to deregister all nth-tick handlers.
|
|
--- @param handler? function The handler to register, or `nil` to deregister the registered handler.
|
|
function flib_event.on_nth_tick(nth_tick, handler)
|
|
if handler then
|
|
script.on_nth_tick(nth_tick, handler)
|
|
else
|
|
script.on_nth_tick(nth_tick)
|
|
end
|
|
end
|
|
|
|
--- Register or deregister a handler to or from an event or group of events.
|
|
---
|
|
--- Unlike `script.on_event`, `event.register` supports adding compatible filters to multiple events at once.
|
|
--- Additionally, `event.register` supports registering to custom-inputs and other events simultaneously.
|
|
---
|
|
--- # Examples
|
|
---
|
|
--- ```lua
|
|
--- -- Register a handler to a defines.events event that supports filters
|
|
--- event.register(defines.events.on_built_entity, function(e) log("ghost built!") end, {{filter="ghost"}})
|
|
--- -- Register a handler to a custom-input
|
|
--- event.register("my-input", function(e) log("my-input pressed!") end)
|
|
--- -- Register a handler to multiple events of different types
|
|
--- event.register({"my-input", defines.events.on_lua_shortcut}, function(e) log("do something!") end)
|
|
--- -- Deregister a handler from a single event, if one is registered
|
|
--- event.register("my-input", nil)
|
|
--- -- Deregister a handler from multiple events, if one is registered
|
|
--- event.register({"my-input", defines.events.on_lua_shortcut}, nil)
|
|
--- ```
|
|
--- @param ids EventId|EventId[]
|
|
--- @param handler? function The handler to register, or `nil` to deregister the registered handler.
|
|
--- @param filters? EventFilter
|
|
function flib_event.register(ids, handler, filters)
|
|
if type(ids) ~= "table" then
|
|
ids = { ids }
|
|
end
|
|
for i = 1, #ids do
|
|
-- the game doesn't like you passing filters to events that don't support them, even if they're `nil`
|
|
if filters then
|
|
script.on_event(ids[i], handler, filters)
|
|
else
|
|
script.on_event(ids[i], handler)
|
|
end
|
|
end
|
|
end
|
|
|
|
--- Register an entity to raise `on_entity_destroyed` when it's destroyed.
|
|
---
|
|
--- Once an entity is registered it's registered forever (until it's destroyed) and persists through save/load.
|
|
---
|
|
--- Registered is global across all mods: once an entity is registered the event will be fired for all mods when its
|
|
--- destroyed.
|
|
---
|
|
--- An entity registered multiple times will only fire the event once and gives back the same registration number.
|
|
---
|
|
--- Depending on when a given entity is destroyed, `on_entity_destroyed` will be fired at the end of the current tick or end
|
|
--- of the next tick.
|
|
--- @param entity LuaEntity The entity to register.
|
|
--- @return number registration_number
|
|
function flib_event.register_on_entity_destroyed(entity)
|
|
return script.register_on_entity_destroyed(entity)
|
|
end
|
|
|
|
--- Generate a new, unique event ID.
|
|
---
|
|
--- # Examples
|
|
---
|
|
--- ```lua
|
|
--- -- Generate a new event ID
|
|
--- local my_event = event.generate_id()
|
|
--- -- Raise that event with custom parameters
|
|
--- event.raise(my_event, {whatever_you_want=true, ...})
|
|
--- ```
|
|
--- @return number
|
|
function flib_event.generate_id()
|
|
return script.generate_event_name()
|
|
end
|
|
|
|
--- Retrieve the handler for an event, if one exists.
|
|
--- @param id EventId
|
|
--- @return function handler The registered handler, or `nil` if one isn't registered.
|
|
function flib_event.get_handler(id)
|
|
return script.get_event_handler(id)
|
|
end
|
|
|
|
--- Raise an event as if it were actually called.
|
|
---
|
|
--- This will only work for events that actually support being raised, and custom mod events.
|
|
---
|
|
--- # Examples
|
|
---
|
|
--- ```lua
|
|
--- event.raise(defines.events.on_gui_click, {player_index=e.player_index, element=my_button, ...})
|
|
--- ```
|
|
--- @param id EventId
|
|
--- @param event_data table The event data that will be passed to the handlers.
|
|
function flib_event.raise(id, event_data)
|
|
script.raise_event(id, event_data)
|
|
end
|
|
|
|
--- Retrieve the mod event order.
|
|
--- @return string
|
|
function flib_event.get_order()
|
|
return script.get_event_order()
|
|
end
|
|
|
|
--- Set the filters for the given event(s).
|
|
---
|
|
--- # Examples
|
|
---
|
|
--- ```lua
|
|
--- -- Set the filters for a single event
|
|
--- event.set_filters(defines.events.on_built_entity, {
|
|
--- {filter="ghost"},
|
|
--- {filter="type", type="assembling-machine"}
|
|
--- })
|
|
--- -- Set the filters for multiple events that have compatible formats
|
|
--- event.set_filters({defines.events.on_built_entity, defines.events.on_robot_built_entity}, {
|
|
--- {filter="ghost"},
|
|
--- {filter="type", type="assembling-machine"}
|
|
--- })
|
|
--- -- Clear event filters if any are set
|
|
--- event.set_filters(defines.events.on_robot_built_entity, nil)
|
|
--- ```
|
|
--- @param ids EventId|EventId[]
|
|
--- @param filters? EventFilter The filters to set, or `nil` to clear the filters.
|
|
function flib_event.set_filters(ids, filters)
|
|
if type(ids) ~= "table" then
|
|
ids = { ids }
|
|
end
|
|
for i = 1, #ids do
|
|
script.set_event_filter(ids[i], filters)
|
|
end
|
|
end
|
|
|
|
--- Retrieve the filters for the given event.
|
|
--- @param id EventId
|
|
--- @return EventFilter? filters The filters, or `nil` if there are none defined.
|
|
function flib_event.get_filters(id)
|
|
script.get_event_filter(id)
|
|
end
|
|
|
|
--- One of the following:
|
|
--- - A member of `defines.events`
|
|
--- - A positive `number` corresponding to a custom event ID.
|
|
--- - A `string` corresponding to a custom-input name.
|
|
--- @class EventId
|
|
|
|
return flib_event
|