User:MIDIMan/Ringslinger Revolution/Hooks

Ringslinger Revolution has its own hook system for inserting custom game logic into the game mode. These hooks work similar to the Lua hooks provided by SRB2, but instead of using addHook to bind a function, RSR.addHook is used instead:

-- A local function hooked
local function MyWeaponTouchSpecialHandler()

end

RSR.addHook("TouchWeapon", MyWeaponTouchSpecialHandler, "sonic")

-- An inline function hooked
RSR.addHook("TouchWeapon", function()
    -- do things
end, "sonic")

Like SRB2's hooks, they take three functions: a string denoting the hook to add this function to, the function being hooked, and a third argument whose type and purpose varies depending on the hook (and which is omitted for some hooks). For more information, check the Lua/Hooks page.

List of hooks

Mobj interactions

The following hooks work more-or-less the same, but use different types of Objects. special is the weapon ring Object being touched, and toucher is the Object representing the player touching it. If the function returns true, the Object's default behavior is completely overridden. If it returns false, the Object's game mode-specific behavior is overridden, but the Object will still run the default TouchSpecial code (the Object is killed, and its DeathSound is played).

For the following hooks, the third argument to RSR.addHook determines what skin for toucher to run this hook for. If omitted or set to nil, it will run for all character skins.

TouchWeapon

Hook format: RSR.addHook("TouchWeapon", functionname, [string skinname])

Function format: function(mobj_t special, mobj_t toucher, int weaponType)

Function return value: Boolean (override default behavior?, nil = use default behavior)

Determines what happens when a player touches a weapon ring Object. weaponType is the type of weapon being given to the player. Default behavior is to give the player a weapon using RSR.GiveWeapon, give a specific amount of ammo for it using RSR.GetAmmoAmountFromWeapon, call RSR.SetItemFuse, and kill the Object.

TouchPowerup

Hook format: RSR.addHook("TouchPowerup", functionname, [string skinname])

Function format: function(mobj_t special, mobj_t toucher, int powerupType)

Function return value: Boolean (override default behavior?, nil = use default behavior)

Determines what happens when a player touches a powerup Object. powerupType is the type of powerup being given to the player. Default behavior is to give the player a powerup using RSR.GivePowerup, call RSR.BonusFade and RSR.SetItemFuse, and kill the Object.

TouchHealth

Hook format: RSR.addHook("TouchHealth", functionname, [string skinname])

Function format: function(mobj_t special, mobj_t toucher, int health)

Function return value: Boolean (override default behavior?, nil = use default behavior)

Determines what happens when a player touches a health Object. health is the amount of health given to the player. Default behavior is to give the player health using RSR.GiveHealth, call RSR.BonusFade and RSR.SetItemFuse, and kill the Object.

TouchArmor

Hook format: RSR.addHook("TouchArmor", functionname, [string skinname])

Function format: function(mobj_t special, mobj_t toucher, int armor)

Function return value: Boolean (override default behavior?, nil = use default behavior)

Determines what happens when a player touches an armor Object. armor is the amount of armor given to the player. Default behavior is to give the player armor using RSR.GiveArmor, call RSR.BonusFade and RSR.SetItemFuse, and kill the Object.

Item intractions

For the following hooks, the third argument to RSR.addHook determines what skin for player to run this hook for. If omitted or set to nil, it will run for all character skins.

GetHealth

Hook format: RSR.addHook("GetHealth", functionname, [string skinname])

Function format: function(player_t player, int health, boolean isBonus, boolean lowMod)

Function return value: Boolean (can pickup item?, nil = use default behavior)

Executes when a player receives health via RSR.GiveHealth. player is the player receiving health, health is the amount of health the player is expected to receive, isBonus determines whether the player's health can go past 100 or not, and lowMod determines whether crit healing takes effect if the player is below 40 health and armor, combined. If the function returns true or false, RSR.GiveHealth's default behavior will be overridden, and the function will return the same value. true forces health pickups to be collected, while false forces health pickups to stay in place.

GetArmor

Hook format: RSR.addHook("GetArmor", functionname, [string skinname])

Function format: function(player_t player, int armor, boolean isBonus, boolean lowMod)

Function return value: Boolean (can pickup item?, nil = use default behavior)

Executes when a player receives armor via RSR.GiveArmor. player is the player receiving armor, armor is the amount of armor the player is expected to receive, isBonus determines whether the player's armor can go past 100 or not, and lowMod determines whether crit healing takes effect if the player is below 40 health and armor, combined. If the function returns true or false, RSR.GiveArmor's default behavior will be overridden and return the same value. true forces armor pickups to be collected, while false forces armor pickups to stay in place.

GetHype

Hook format: RSR.addHook("GetHype", functionname, [string skinname])

Function format: function(player_t player, int hype)

Function return value: Boolean (override default behavior?, nil = use default behavior)

Executes when a player receives hype via RSR.GiveHype. player is the player receiving health and hype is the amount of hype the player is expected to receive. If the function returns true or false, RSR.GiveHype's default behavior will be overridden and return the same value.

GetPowerup

Hook format: RSR.addHook("GetPowerup", functionname, [string skinname])

Function format: function(player_t player, int powerup, int addTics, int addPenalty)

Function return value: Boolean (override default behavior?, nil = use default behavior)

Executes when a player receives a powerup via RSR.GivePowerup. player is the player receiving health, powerup is the powerup type the player is expected to receive, addTics is the amount of tics to add to the powerup's lifespan if the player already has it, and addPenalty is the amount of tics to add to the powerup's penalty value if the player already has the powerup. If the function returns true or false, RSR.GiveHype's default behavior will be overridden and return the same value.

Player

For the following hooks, the third argument to RSR.addHook determines what skin for target to run this hook for. If omitted or set to nil, it will run for all character skins.

PlayerKnockback

Hook format: RSR.addHook("PlayerKnockback", functionname, [string skinname])

Function format: function(mobj_t target, mobj_t inflictor, mobj_t source, int damage, int damagetype, fixed_t knockbackScale)

Function return value: Boolean (override default behavior?)

Executes when the player gets knocked back via RSR.PlayerDamageKnockback. target is the player Object getting knocked back, inflictor is the Object that damaged it, source is the Object responsible for inflictor's existence, and knockbackScale is the scale applied to the player's knockback value. Note that inflictor and/or source may be nil, and should be checked for existence and validity before being accessed to prevent errors. If the function returns true, the default knockback behavior is overridden; otherwise, it will be performed after executing the function.

PlayerShouldDamage

Hook format: RSR.addHook("PlayerShouldDamage", functionname, [string skinname])

Function format: function(mobj_t target, mobj_t inflictor, mobj_t source, int damage, int damagetype)

Function return value: Boolean (override default behavior?)

Executes when the player's ShouldDamage hook is executed in Ringslinger Revolution levels. target is the player Object getting knocked back, inflictor is the Object that damaged it, and source is the Object responsible for inflictor's existence. Note that inflictor and/or source may be nil, and should be checked for existence and validity before being accessed to prevent errors. If the function returns true, the default behavior is overridden; otherwise, it will be performed after executing the function.

PlayerDamage

Hook format: RSR.addHook("PlayerDamage", functionname, [string skinname])

Function format: function(mobj_t target, mobj_t inflictor, mobj_t source, int damage, int damagetype)

Function return value: Boolean (override default behavior?)

Executes when the player gets damaged via RSR.PlayerDamage. target is the player Object getting knocked back, inflictor is the Object that damaged it, and source is the Object responsible for inflictor's existence. Note that inflictor and/or source may be nil, and should be checked for existence and validity before being accessed to prevent errors. If the function returns true. the default behavior is overridden; otherwise, it will be performed after executing the function.

PlayerDeath

Hook format: RSR.addHook("PlayerDeath", functionname, [string skinname])

Function format: function(mobj_t target, mobj_t inflictor, mobj_t source, int damagetype)

Function return value: Boolean (override default behavior?)

Executes when RSR.PlayerDeath is used. target is the player Object getting knocked back, inflictor is the Object that damaged it, and source is the Object responsible for inflictor's existence. Note that inflictor and/or source may be nil, and should be checked for existence and validity before being accessed to prevent errors. If the function returns true. the default behavior is overridden; otherwise, it will be performed after executing the function.

PlayerDeathThink

Hook format: RSR.addHook("PlayerDeathThink", functionname, [string skinname])

Function format: function(player_t player)

Function return value: Boolean (override default behavior?)

Executes once per tic for the player as it runs RSR.PlayerDeathTick while dead. If the function returns true. the default behavior is overridden; otherwise, it will be performed after executing the function.

PlayerDeathFling

Hook format: RSR.addHook("PlayerDeathFling", functionname, [string skinname])

Function format: function(mobj_t target, mobj_t inflictor, mobj_t source, int damage, int damagetype)

Function return value: Boolean (override default behavior?)

Executes when the player gets flung after dying via RSR.SetPlayerDeathFling. target is the player Object getting flung, inflictor is the Object that damaged it, and source is the Object responsible for inflictor's existence. Note that inflictor and/or source may be nil, and should be checked for existence and validity before being accessed to prevent errors. If the function returns true. the default behavior is overridden; otherwise, it will be performed after executing the function.

Enemy

EnemyTouchSpecial

Hook format: RSR.addHook("EnemyTouchSpecial", functionname, [string skinname])

Function format: function(mobj_t special, mobj_t toucher)

Function return value: Boolean (override default behavior?)

Executes when an enemy uses RSR.EnemyTouchSpecial in its TouchSpecial hook. special is the enemy Object being touched, and toucher is the Object representing the player touching it. If the function returns true. the default behavior is overridden; otherwise, it will be performed after executing the function.

EnemyShouldDamage

Hook format: RSR.addHook("EnemyShouldDamage", functionname, [string skinname])

Function format: function(mobj_t target, mobj_t inflictor, mobj_t source, int damage, int damagetype)

Function return value: Boolean (override default behavior?)

Executes when an enemy uses RSR.EnemyShouldDamage in its ShouldDamage hook. target is the enemy Object getting flung, inflictor is the Object that damaged it, and source is the Object responsible for inflictor's existence. Note that inflictor and/or source may be nil, and should be checked for existence and validity before being accessed to prevent errors. If the function returns true. the default behavior is overridden; otherwise, it will be performed after executing the function.

EnemySetHealth

Hook format: RSR.addHook("EnemySetHealth", functionname, [string skinname])

Function format: function(mobj_t target, mobj_t inflictor, mobj_t source, int damage, int damagetype)

Function return value: Boolean (override default behavior?)

Executes when an enemy uses RSR.EnemySetHealth in its ShouldDamage hook. target is the enemy Object getting flung, inflictor is the Object that damaged it, and source is the Object responsible for inflictor's existence. Note that inflictor and/or source may be nil, and should be checked for existence and validity before being accessed to prevent errors. If the function returns true. the default behavior is overridden; otherwise, it will be performed after executing the function.

Other

WeaponReady

Hook format: RSR.addHook("WeaponReady", functionname, int weapon)

Function format: function(player_t player, rsrweaponinfo_t weaponInfo, table args)

Function return value: Boolean (override default behavior?)

Determines what happens when the A_WeaponReady PSprite action is executed. weaponInfo is the weapon's RSR.WEAPON_INFO entry, and args is a table of arguments passed into the A_WeaponReady action. The default behavior is to run RSR.FireWeaponAlt is the player is holding down the "Fire Normal" button, and then run RSR.FireWeapon is the player is holding down the "Attack" button. If the function returns true, the default behavior is overridden.

ProjectileMoveCollide

Hook format: RSR.addHook("ProjectileMoveCollide", functionname, [int objecttype])

Function format: function(mobj_t movingmobj, mobj_t mobj)

Function return value: Boolean (override default behavior?)

Executes when a projectile running RSR.ProjectileMoveCollide in its MobjMoveCollide hook collides with an MF_SHOOTABLE Object. movingmobj is the projectile, and mobj is the shootable Object being collided with. Default behavior is to damage the shootable Object and run P_ExplodeMissile on the projectile if it wasn't removed. If the function returns true, the default behavior is overridden.

KillfeedMsg

Hook format: RSR.addHook("KillfeedMsg", functionname, [int objecttype])

Function format: function(player_t victim, mobj_t inflictor, player_t attacker, int damagetype)

Function return value: Boolean (override default behavior?)

Used to create custom kill messages for players to be displayed in the killfeed in multiplayer. Executes when a player is killed. victim is the player that was killed, inflictor is the Object that killed the player, and attacker is the player responsible for the inflictor's existence. Note that inflictor and/or attacker may be nil, and should be checked for existence and validity before being accessed to prevent errors. If the function returns true, the message normally printed to the console when taking damage in multiplayer is overridden; if it returns false/nil, the message is printed in addition to running the function.

The third argument to RSR.addHook determines what Object type for inflictor to run this hook for (should be one of the MT_* constants). If omitted or set to MT_NULL, it will run for all Object types.

All information below this point refers to the outdated hookLib system used in RSR v2.0. It should not be used for v2.1 and above. It will be moved to a separate page after v2.1 officially comes out.

Ringslinger Revolution v2.0 has four hooks for overriding pickup behavior.

All four hooks are "TouchSpecial" hooks. For every hook, special is the Object being touched, and toucher is the Object representing the player touching it. If the function returns true, the default touching behavior is overridden; Otherwise, if will be performed after executing the function. The default behavior for most items is to play its DeathSound, call RSR.SetItemFuse so it can respawn in "Waves" or multiplayer modes, and use P_KillMobj to go to the item's DeathState, but this depends on the item.

These hooks work similar to the Lua hooks provided by SRB2, but instead of using addHook to bind a function, hookLib.AddHook is used instead:

-- A local function hooked
local function MyWeaponTouchSpecialHandler()

end

hookLib.AddHook("RSR_WeaponTouchSpecial", MyWeaponTouchSpecialHandler)

-- An inline function hooked
hookLib.AddHook("RSR_WeaponTouchSpecial", function()
    -- do things
end)

There are also only two arguments instead of three, since hookLib doesn't support a third argument for Object types.

List of hooks (2.0)

RSR_WeaponTouchSpecial

Hook format: hookLib.AddHook(“RSR_WeaponTouchSpecial”, functionname)

Function format: function(mobj_t special, mobj_t toucher, int weapon)

Function return value: Boolean (override default behavior?)

Determines what happens when a player touches a weapon ring Object. Default behavior is to give the player the weapon, give a specific amount of ammo for it depending on if it’s a panel or not, call RSR.BonusFade and RSR.SetItemFuse, and kill the Object.

RSR_PowerupTouchSpecial

Hook format: hookLib.AddHook(“RSR_PowerupTouchSpecial”, functionname)

Function format: function(mobj_t special, mobj_t toucher, int powerup)

Function return value: Boolean (override default behavior?)

Determines what happens when a player touches a powerup Object. Default behavior is to give the player the powerup, call RSR.BonusFade and RSR.SetItemFuse, and kill the Object.

RSR_HealthTouchSpecial

Hook format: hookLib.AddHook(“RSR_HealthTouchSpecial”, functionname)

Function format: function(mobj_t special, mobj_t toucher, int health)

Function return value: Boolean (override default behavior?)

Determines what happens when a player touches a health Object. Default behavior is to give the player the specified amount of health, call RSR.BonusFade and RSR.SetItemFuse, and kill the Object.

RSR_ArmorTouchSpecial

Hook format: hookLib.AddHook(“RSR_ArmorTouchSpecial”, functionname)

Function format: function(mobj_t special, mobj_t toucher, int armor)

Function return value: Boolean (override default behavior?)

Determines what happens when a player touches a health Object. Default behavior is to give the player the specified amount of armor, call RSR.BonusFade and RSR.SetItemFuse, and kill the Object.