Lua/Kart/Hooks

This page gathers all Lua hooks that are specific to SRB2Kart, or differ from SRB2 v2.1's default functionality. For further reading on how these work, please see its respective hooks page.

Hooks

Global

IntermissionThinker

Hook format: addHook("IntermissionThinker", functionname)

Function format: function()

Executes every tic during the results screen after a race finishes.

VoteThinker

Hook format: addHook("VoteThinker", functionname)

Function format: function()

Executes every tic during the vote screen.

Player

ShouldSpin

Hook format: addHook("ShouldSpin", functionname)

Function format: function(player_t player, mobj_t inflictor, mobj_t source)

Function return value: Boolean (true to force a spin-out, anything else will induce default behaviour.)

Functionally similar to a ShouldDamage hook. Determines if the player should get spun out by the inflictor using their source of damage, e.g. Sonic becoming spun out by Eggman throwing an Orbinaut. Note that the inflictor and their source may be nil.

Sources of spin-out include any hazards that would normally damage a player, as well as items such as Bananas, Orbinauts, Jawz, Ballhogs, Invincibility, Lighting Shield and explosions (such as from a Mine, Eggman Monitor or Self-Propelled Bomb, provided that the player has not been hit directly by the blast).

Passing true to this hook will completely ignore every state where the player would be immune to spin-outs and do so anyways, although this behaviour can be intercepted still with a PlayerSpin hook.

ShouldExplode

Hook format: addHook("ShouldExplode", functionname)

Function format: function(player_t player, mobj_t inflictor, mobj_t source)

Function return value: Boolean (true to force explosion damage, anything else will induce default behaviour.)

Functionally similar to a ShouldDamage hook. Determines if the player should explode (which causes them to launch into the air, as well as spin out for longer than normal and have their item drop) by the inflictor using their source of damage, e.g. Sonic blowing up by Eggman through an Eggman Monitor. Note that the inflictor and their source may be nil.

Sources of explosion damage include Mines (originating from MT_MINEEXPLOSION), Eggman Monitors and Self-Propelled Bombs (both originating from MT_SPBEXPLOSION, with the SPB's difference that extravalue1 for MT_SPBEXPLOSION is set to 1, indicating a more powerful explosion), provided the player has been hit dead-on with these items. Despite appareances, some hazards that seem to do explosive damage's effects, such as the Midnight Channel's Roaming Shadow attack, do not count as explosive damage. Explosion damage, which this hook covers, can be identified if their attack makes the player's item drop or not.

Passing true to this hook will completely ignore every state where the player would be immune to explosions and explode anyways, although this behaviour can be intercepted still with a PlayerExplode hook.

ShouldSquish

Hook format: addHook("ShouldSquish", functionname)

Function format: function(player_t player, mobj_t inflictor, mobj_t source)

Function return value: Boolean (true to force squish damage, false to force no squish damage, anything else will induce default behaviour.)

Functionally similar to a ShouldDamage hook. Determines if the player should be squished by the inflictor using their source of damage (always the same as the inflictor), e.g. Eggman being flattened by Knuckles using Grow. Note that the inflictor and their source will be nil if the squish source was by the world.

Sources of squish include Grow and Shrink, as racers experiencing a scale change may be subject to squish or be squished, respectively. However, the source itself does not come from the items themselves - colliding with another racer with a scale difference bigger than 0.115 compared to each other will have the smaller racer get squished in these instances. In addition, instances where the player would normally get crushed in regular SRB2 will cause them to be squished instead (e.g., any player taller than the world ceiling will be subject to squishing by the world).

Passing true to this hook will completely ignore every state where the player would be immune from being squished and get squished anyways, although this behaviour can be intercepted still with a SquishPlayer hook.

PlayerSpin

Hook format: addHook("PlayerSpin", functionname)

Function format: function(player_t player, mobj_t inflictor, mobj_t source)

Function return value: Boolean (true to stop spin-out, anything else will induce default behaviour.)

Executes when the player will be spun-out by a source of spin-out. Note that the inflictor and their source may be nil.

PlayerExplode

Hook format: addHook("PlayerExplode", functionname)

Function format: function(player_t player, mobj_t inflictor, mobj_t source)

Function return value: Boolean (true to stop blowing up, anything else will induce default behaviour.)

Executes when the player will explode by an explosion source. Note that the inflictor and their source may be nil.

PlayerSquish

Hook format: addHook("PlayerSquish", functionname)

Function format: function(player_t player, mobj_t inflictor, mobj_t source)

Function return value: Boolean (true to stop squishing, anything else will induce default behaviour.)

Executes when the player gets squished by a squish source. Note that the inflictor and their source will be nil if inflicted by the world, and inflictor and source are usually the same.

PlayerCmd

Hook format: addHook("PlayerCmd", functionname)

Function format: function(player_t player, ticcmd_t cmd)

Allows to override a player's inputs and check what buttons they are pressing.

Music

MusicChange

Note This hook is now in SRB2 v2.2.9

Hook format: addHook("MusicChange", functionname)

Function format: function(string oldname, string newname, UINT16 mflags, boolean looping, UINT32 position, UINT32 prefadems, UINT32 fadeinms)

Function return value: String/Boolean, Int, Boolean, Integer, Integer, Integer (see below.)

A hook for overriding S_ChangeMusicEx in SRB2Kart.

oldname is the audio file that is being overridden, newname is the audio file that will be overridden to, mflags defines the audio flags being used (see Sound#Attributes for more information), looping defines if the song will loop or not, position defines the song's current play time (in milliseconds), prefadems defines if the song should fade in, and fadeinms defines the duration in milliseconds of the fade-in of the song once it starts. Note that even though prefadems is defined as a UINT32 variable, it effectively works as a boolean in the source code.

It is possible to override all parameters, or prevent a song from overriding another, like such:

• The first value to return can be a boolean or string.
  • If it's a boolean, passing true will stop the overriding song from playing at all.
  • If it's a string, it should be a audio file name. The hook will override to this audio file instead.
• The second value is an integer, specifically SF_* flags.
• The third value is a boolean, indicating if the song should loop or not.
• The fourth value is an integer, specifying the song's position in milliseconds.
• The fifth value is internally an integer, although it's used as a boolean in the source code. Passing true will allow the song to fade in.
• The sixth value is an integer, specifying for how many milliseconds should the fade-in last.

Thus, a return statement like return false, mfflags|SF_X2AWAYSOUND, false, 5000, true, 3000 will let the music override happen, using the same flags plus twice the volume, not allow it to loop, start 5 seconds into the song, allow fade-in and let it happen for 3 seconds.