z_mirror/flib

git clone https://git.raiguard.me/z_mirror/flib

Caleb HeuerRemove require guardsa9f2be7

trunk
branchestrunkall refs →
2.7 KiB94 linesraw
1--- Schedule tasks to be executed later.
2--- ```lua
3--- local flib_on_tick_n = require("__flib__.on-tick-n")
4--- ```
5--- @class flib_on_tick_n
6local on_tick_n = {}
7
8--- Initialize the module's script data table.
9---
10--- Must be called at the **beginning** of `on_init`. Can also be used to delete all current tasks.
11function on_tick_n.init()
12  if not storage.__flib then
13    storage.__flib = {}
14  end
15  --- @type table<number, flib.OnTickNTasks>
16  storage.__flib.on_tick_n = {}
17end
18
19--- Retrieve the tasks for the given tick, if any.
20---
21--- Must be called **during** `on_tick`.
22--- @param tick number
23--- @return flib.OnTickNTasks?
24function on_tick_n.retrieve(tick)
25  -- Failsafe for rare cases where on_tick can fire before on_init
26  if not storage.__flib or not storage.__flib.on_tick_n then
27    return
28  end
29  local actions = storage.__flib.on_tick_n[tick]
30  if actions then
31    storage.__flib.on_tick_n[tick] = nil
32    return actions
33  end
34end
35
36--- Add a task to execute on the given tick.
37--- @param tick number
38--- @param task any The data representing this task. This can be anything except for a `function`.
39--- @return flib.OnTickNTaskID ident An identifier for the task. Save this if you might remove the task before execution.
40function on_tick_n.add(tick, task)
41  local list = storage.__flib.on_tick_n
42  local tick_list = list[tick]
43  if tick_list then
44    local index = #tick_list + 1
45    tick_list[index] = task
46    return { index = index, tick = tick }
47  else
48    list[tick] = { task }
49    return { index = 1, tick = tick }
50  end
51end
52
53--- Remove a scheduled task.
54--- @param ident flib.OnTickNTaskID The identifier object for the task, as returned from `on-tick-n.add`.
55function on_tick_n.remove(ident)
56  local tick_list = storage.__flib.on_tick_n[ident.tick]
57  if not tick_list or not tick_list[ident.index] then
58    return false
59  end
60
61  tick_list[ident.index] = nil
62
63  return true
64end
65
66--- A unique identifier for a previously added task, used in `on-tick-n.remove`.
67--- @class flib.OnTickNTaskID
68--- @field tick number The tick this task is scheduled for.
69--- @field index number The tasks' index in the tick's `Tasks` table.
70
71--- A table of tasks.
72---
73--- Each task can be anything that is not a function, as specified in `on-tick-n.add`.
74---
75--- **This is not an array, there may be gaps. Always use `pairs` to iterate this table.**
76---
77--- # Example
78---
79--- ```lua
80--- event.on_tick(function(e)
81---   for _, task in pairs(on_tick_n.retrieve(e.tick) or {}) do
82---     if task == "say_hi" then
83---       game.print("Hello there!")
84---     elseif task == "order_66" then
85---       for _, player in pairs(game.players) do
86---         player.die()
87---       end
88---     end
89---   end
90--- end)
91--- ```
92--- @alias flib.OnTickNTasks table<number, any>
93
94return on_tick_n