callback.lua

---@meta _

---@alias Callback
---| string
---|
---|-- Item Callbacks: These are callbacks related to item objects
---| 'onItemRoll' Fired when rolling an item from a pool. The rolled item can be overwritten by returning an item object within the callback.
---| 'onItemDropped' TODO
---| 'onItemInit' Fired whenever an instance of an item is spawned.
---| 'onItemPickup' Fired whenever an item gets picked up.
---| 'onUseItemUse' Fired whenever a player uses a use item.
---| 'postUseItemUse' Fired after onUseItemUse and vanilla use item logic.
---|
---|-- Actor Callbacks: These are callbacks related to any actor instance.
---| 'onActorInit' Called whenever a new actor spawns.
---|
---|-- NPC Callbacks: These are callbacks related to NPCs and bosses
---| 'onNPCDeath' Fired whenever an NPC dies.
---| 'onNPCDeathProc' Fired for each player whenever an NPC dies. Handle death item procs here.
---| 'onEliteInit' TODO
---|-- TODO: this needs testing. Is this correct? is it a truthy value or only booleans, will it cancel all following onDamage callbacks?
---| 'onDamage' Fired whenever an actor takes damage. The damage can be negated by returning a truthy value like `true` from within the callback.
---|
---|-- Player Callbacks: These are callbacks related to the player and are fired for each player object in the game
---| 'onPlayerInit' Fired at the start of the run for every player.
---| 'onPlayerStep' Fired each tick for every player.
---| 'onPlayerDrawBelow' Fired after drawing the player's sprite.
---| 'onPlayerDraw'  Fired when beginning to draw the player, before any part of them is drawn.
---| 'onPlayerDrawAbove' Fired after drawing all parts of the player.
---| 'onPlayerLevelUp' Fired whenever the player levels up.
---| 'onPlayerDeath' Fired whenever a player dies.
---| 'onPlayerHUDDraw' The x and y coordinates are the position of the player's first skill on screen.
---|
---|-- Damager Callbacks: These are callbacks related to damagers, i.e. bullets and explosions
---| 'onFire' Called each time a bullet or explosion is fired.
---| 'onFireSetProcs' Called when setting item procs when a bullet or explosion is fired. Not called when the damager is set not to proc.
---| 'onHit' Fired whenever a damager hits an actor, including the precise coordinates hit at.
---| 'preHit' Fired whenever a damager hits an actor, before dealing damage or most item procs.
---| 'postHit' Fired after hitting an actor but only once per damager.
---| 'onImpact' Fired when any damager hits an actor and when bullet damagers hit a wall.
---|
---|-- MapObject Callbacks: These are callbacks related to map objects
---| 'onMapObjectActivate' Fired whenever a map object is activated by a player.
---|
---|-- Game Callbacks: These are callbacks related to game events
---| 'onStageEntry' Fired at the start of every stage.
---| 'onSecond' Fired whenever the timer second changes.
---| 'onMinute' Fired whenever the timer minute changes.
---| 'onGameStart' Fired at the very start of the game.
---| 'onGameEnd' Fired at the end of the game.
---|
---|-- General Callbacks: These are callbacks related to the running of the game
---| 'onStep' Fired every game tick.
---| 'preStep' Fired at the start of every game tick.
---| 'postStep' Fired at the end of every game tick.
---| 'onDraw' Fired after most vanilla rendering. Custom drawing should be done here.
---| 'onHUDDraw' Fired after most vanilla HUD rendering. Drawing coordinates are screen based.
---| 'preHUDDraw' Fired before most vanilla HUD rendering. Drawing coordinates are screen based.
---| 'onLoad' Fired immediately after all mods are initialized.
---| 'postLoad' Fired immediately after onLoad.
---| 'onCameraUpdate' Fired immediately after the base game's camera movement.
---|
---|-- Global Callbacks: **WARNING**: The API was not really designed to be used outside of runs. Running code outside of the game holds a much higher risk of errors. These are callbacks that can be executed both in and outside of gameplay, such as during menus or cutscenes.
---| 'globalStep' Global equivalent to the "onStep" callback.
---| 'globalPreStep' Global equivalent to the "preStep" callback.
---| 'globalPostStep' Global equivalent to the "postStep" callback.
---| 'globalRoomStart' Called any time a new room is loaded.
---| 'globalRoomEnd' Called when the current room is being unloaded.

---@alias CallbackFunction
---| fun(name: Callback, fn: function, priority?: number)
---|
---|-- Items
---| fun(name: 'onItemRoll', fn: fun(pool: ItemPool, item: Item): (override: Item), priority?: number)
---| fun(name: 'onItemDropped', fn: fun(...), priority?: number) TEST: is this implemented?
---| fun(name: 'onItemInit', fn: fun(item: ItemInstance), priority?: number)
---| fun(name: 'onItemPickup', fn: fun(item: ItemInstance, player: PlayerInstance), priority?: number)
---| fun(name: 'onUseItemUse', fn: fun(player: PlayerInstance, item: Item), priority?: number)
---| fun(name: 'postUseItemUse', fn: fun(player: PlayerInstance, item: Item), priority?: number)
---|
---|-- Actor
---| fun(name: 'onNPCDeath', fn: fun(npc: ActorInstance), priority?: number)
---| fun(name: 'onNPCDeathProc', fn: fun(npc: ActorInstance, player: PlayerInstance), priority?: number)
---| fun(name: 'onActorInit', fn: fun(actor: ActorInstance), priority?: number)
---| fun(name: 'onEliteInit', fn: fun(elite: ActorInstance), priority?: number)
---| fun(name: 'onDamage', fn: fun(target: ActorInstance, damage: number, source?: Instance|DamagerInstance|ActorInstance): (cancel: boolean?), priority?: number)
---|
---|-- Player
---| fun(name: 'onPlayerInit', fn: fun(player: PlayerInstance), priority?: number)
---| fun(name: 'onPlayerStep', fn: fun(player: PlayerInstance), priority?: number)
---| fun(name: 'onPlayerDrawBelow', fn: fun(player: PlayerInstance), priority?: number)
---| fun(name: 'onPlayerDraw', fn: fun(player: PlayerInstance), priority?: number)
---| fun(name: 'onPlayerDrawAbove', fn: fun(player: PlayerInstance), priority?: number)
---| fun(name: 'onPlayerLevelUp', fn: fun(player: PlayerInstance), priority?: number)
---| fun(name: 'onPlayerDeath', fn: fun(player: PlayerInstance), priority?: number)
---| fun(name: 'onPlayerHUDDraw', fn: fun(player: PlayerInstance, x: number, y: number), priority?: number)
---|
---|-- Damagers
---| fun(name: 'onFire', fn: fun(damager: DamagerInstance ), priority?: number)
---| fun(name: 'onFireSetProcs', fn: fun(damager: DamagerInstance, parent: ActorInstance ), priority?: number)
---| fun(name: 'onHit', fn: fun(damager: DamagerInstance, hit: ActorInstance, x: number, y: number), priority?: number)
---| fun(name: 'preHit', fn: fun(damager: DamagerInstance, hit: ActorInstance ), priority?: number)
---| fun(name: 'postHit', fn: fun(damager: DamagerInstance ), priority?: number)
---| fun(name: 'onImpact', fn: fun(damager: DamagerInstance, x: number, y: number), priority?: number)
---|
---|-- Map objects
---| fun(name: 'onMapObjectActivate', fn: fun(mapObject: Instance, activator: PlayerInstance), priority?: number)
---|
---|-- Game
---| fun(name: 'onStageEntry', fn: fun(), priority?: number)
---| fun(name: 'onSecond', fn: fun(minute: number, second: number), priority?: number)
---| fun(name: 'onMinute', fn: fun(minute: number, second: number), priority?: number)
---| fun(name: 'onGameStart', fn: fun(), priority?: number)
---| fun(name: 'onGameEnd', fn: fun(), priority?: number)
---|
---|-- General
---| fun(name: 'onStep', fn: fun(), priority?: number)
---| fun(name: 'preStep', fn: fun(), priority?: number)
---| fun(name: 'postStep', fn: fun(), priority?: number)
---| fun(name: 'onDraw', fn: fun(), priority?: number)
---| fun(name: 'onHUDDraw', fn: fun(), priority?: number)
---| fun(name: 'preHUDDraw', fn: fun(), priority?: number)
---| fun(name: 'onLoad', fn: fun(), priority?: number)
---| fun(name: 'postLoad', fn: fun(), priority?: number)
---| fun(name: 'onCameraUpdate', fn: fun(), priority?: number)
---|
---|-- Global
---| fun(name: 'globalStep', fn: fun(room: Room), priority?: number)
---| fun(name: 'globalPreStep', fn: fun(room: Room), priority?: number)
---| fun(name: 'globalPostStep', fn: fun(room: Room), priority?: number)
---| fun(name: 'globalRoomStart', fn: fun(room: Room), priority?: number)
---| fun(name: 'globalRoomEnd', fn: fun(room: Room), priority?: number)

--- Callbacks are your main method of getting the game to call your code.
---
--- **WARNING**: Callbacks exist forever (even across runs) no matter when they are defined.
---          If you think you need to define a callback after load, then you're probably doing something wrong.
---
---@overload fun(name: Callback, fn: fun(...), priority?: number)
callback = {}



--[[
---- static functions
--]]

--- Adds a function to be called whenever the specified callback is fired.
---
--- # Examples
---   Two functionally identical ways of assigning a function to a callback.
---   In this case we're doing something on the player step callback.
---
---   ```lua
---   local function foo(player)
---       -- Do something
---   end
---
---   callback.register("onPlayerStep", foo)
---   ```
---
---   ```lua
---   callback.register("onPlayerStep", function(player)
---       -- Do something
---   end)
---   ```
---
---
---   Similar to above except we register to the NPC death callback with a priority of 200.
---   The higher priority means the callback will be called before most others.
---
---   ```lua
---   callback.register("onNPCDeath", function(npc)
---       -- Do something
---   end, 200)
---   ```
---
---@-- FIXME: using `Callback` as the type instead of `string` casues every callback to show up
---@--        twice in suggestions due to the overloads.
---@--        It's required for the callback docs, and the overloads for the autocomplete.
---@param name Callback The name of the callback to add a function onto
---@param fn function The function to add as the callback. The arguments fed to this function will depend on what callback is being fired ([see here](https://saturnyoshi.gitlab.io/RoRML-Docs/global/registerCallback.html#list-of-callbacks))
---@param priority? number A priority can be set to decide in which order callbacks will be run. A higher priority means the function is called earlier. This value can be negative. *defaults to 10*
---
---@-- Adds the overloads
---@type CallbackFunction
---
function callback.register(name, fn, priority) end

--- Creates a new callback that all mods can register to.
--- 
--- **WARNING**: Make sure to use unique names!
---          If multiple mods try to create the same callback an error will be thrown.
---
--- # Example
---   Create a new callback, add a function to it, and call it with a random number.
---
---   ```lua
---   -- Create a callback
---   local customCallback = callback.create("exampleCustomCallback")
---
---   -- Add a function to it
---   local function myFunc(number)
---       print("The number is: " .. tostring(number))
---   end
---   callback.register("exampleCustomCallback", myFunc)
---
---   -- Call it
---   customCallback(math.random(100))
---   ```
---
---@param name string The name that will be used to add to this callback with `callback.register`
---@return fun(...) callbackRunner '' A new function used to invoke the callback. Arguments passed to this function will also be passed to all called functions
function callback.create(name) end



--[[
---- legacy
--]]

--- For legacy compatibility. Use `callback.register` instead.
---
---@param name Callback The name of the callback to add a function onto
---@param fn function The function to add as the callback. The arguments fed to this function will depend on what callback is being fired ([see here](https://saturnyoshi.gitlab.io/RoRML-Docs/global/registerCallback.html#list-of-callbacks))
---@param priority? number A priority can be set to decide in which order callbacks will be run. A higher priority means the function is called earlier. This value can be negative. *defaults to 10*
---
---@-- Adds the overloads
---@type CallbackFunction
---
---@deprecated 'Use `callback.register` instead'
function registercallback(name, fn, priority) end

--- For legacy compatibility. Use `callback.create` instead.
---
---@param name string The name that will be used to add to this callback with `callback.register`
---@return fun(...) callbackRunner '' A new function used to invoke the callback. Arguments passed to this function will also be passed to all called functions
---
---@deprecated 'Use `callback.create` instead'
function createcallback(name) end