User:JugadorXEI/SRB2Kart/Hooks and Functions
This page gathers all Lua hooks and functions that are specific to SRB2Kart, or differ from SRB2 v2.1's default functionality. For further reading on how these work, please see their respective hooks and functions pages.
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-Specific
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, 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
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.
- If it's a boolean, passing
- 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.
Functions
To do Write descriptions for functions, add missing Kart-exclusive functions. |
K_Kart
Function | Return value(s) | Description |
---|---|---|
K_PlayAttackTaunt(mobj_t source)
|
void | Plays the attack taunt of the source mobj. This is intended to be used for player mobjs.
This function respects the player's voice preferences (never, tasteful or meme), so it is fine to use this multiple times over a short timespan, and let the game handle the cooldown. In-game, players will perform their attack taunts as they throw offensive items, such as an Orbinauts, Jawz or Bananas thrown forwards. |
K_PlayBoostTaunt(mobj_t source)
|
void | Plays the boost taunt of the source mobj. This is intended to be used for player mobjs.
This function respects the player's voice preferences (never, tasteful or meme), so it is fine to use this multiple times over a short timespan, and let the game handle the cooldown. In-game, players will perform their boost taunts as they use Sneakers or Pogo Springs. |
K_PlayPowerGloatSound(mobj_t source)
|
void | Plays the power gloat sound of the source mobj. This is intended to be used for player mobjs.
In-game, player will perform power gloating when they use Shrink, Grow or Invincibility, and will always taunt by doing so. |
K_PlayOvertakeSound(mobj_t source)
|
void | Plays the overtaking position sound of the source mobj. This is intended to be used for player mobjs.
This function respects the player's voice preferences (never, tasteful or meme), so it is fine to use this multiple times over a short timespan, and let the game handle the cooldown.
In addition, players may not play their overtake sound up until 10 seconds have passed in a Race.
They will never play their overtake sound in Battle. |
K_PlayLossSound(mobj_t source)
|
void | Plays the loss sound of the source mobj. This is intended to be used for player mobjs.
This function does not perform voice preference handling, and as such it can be used repeatedly. Players will perform their loss sound if they finish a race in a bottom-half placement. |
K_PlayHitEmSound(mobj_t source)
|
void | Plays the hit 'em sound of the source mobj. This is intended to be used for player mobjs.
There will always be a four second cooldown on how often this function can be used. Even if the player has voice preferences set to never, they will still hear a ping sound. Players will perform their hit 'em sound if they successfully hit another player with an item, or make them explode (using an Eggman Monitor, for example.) |
K_GetKartColorByName(string name)
|
UINT8 (SKINCOLOR_*) | Returns a color by their common name, or SKINCOLOR_NONE if there is no name that matches the color.
|
K_IsPlayerLosing(player_t player)
|
boolean | Returns true if the player is in a bottom-half placing in Race, false otherwise.
|
K_IsPlayerWanted(player_t player)
|
boolean | Returns true if the player is one of the Wanted players in Battle, false otherwise.
|
K_KartBouncing(mobj_t mobj1, mobj_t mobj2, boolean bounce, boolean solid)
|
void | The function that performs the "bumpcode" of the game. mobj1 and mobj2 indicates who (or what) collided with who (or what).
When |
K_MatchGenericExtraFlags(mobj_t mo, mobj_t master)
|
void | Handles flipping, transparency and split-screen rendering flags from the master mobj to the mo mobj. Very useful if you want another attached mobj to the player to also show flash-tics, flipping, etc..
|
K_DoInstashield(player_t player)
|
void | Performs the instashield animation on the player , which is the blue shield animation that appears when a player nullifies damage through flash-tics. Do note that this is visual only and does not handle invulnerability of the sort.
Instashield effects last for 15 tics. Calling the function during this duration will not play it again unless |
K_SpawnBattlePoints(player_t source, [player_t victim], UINT8 amount)
|
void | Creates Battle's point gaining animation. Do note that it is visual only and does not add any points by itself.
|
K_SpinPlayer(player_t player, [mobj_t source, INT32 type, mobj_t inflictor, boolean trapitem])
|
void | Spins a player out. source is where the spin-out comes from, and inflictor is the player who caused it.
Setting |
K_SquishPlayer(player_t player, [mobj_t source, mobj_t inflictor])
|
void | Squishes a player . source is where the squishing comes from, and inflictor is the player who caused it. Normally, squishes caused by Grow or Shrink set source and inflictor to be the same.
|
K_ExplodePlayer(player_t player, [mobj_t source, mobj_t inflictor])
|
void | Causes a player to blow up. source is what caused the explosion, and inflictor is who caused it.
This skips the area-of-effect damage and visual elements of the explosion - call |
K_StealBumper(player_t player, player_t victim, boolean force)
|
void | Handles bumper stealing in Battle. Does nothing if called on the Race gametype.
If called, |
K_SpawnKartExplosion(fixed_t x, fixed_t y, fixed_t z, [fixed_t radius, INT32 number, mobjtype_t type,
|
void | Spawns a mine explosion on the x , y and z coordinates. The optional parameters default to the Mine's parameters. Note that the visuals are handled by K_SpawnMineExplosion instead (see below).
Do note that the default values might not lead to an accurate explosion radius to the visuals. Here is a snippet that creates an accurate Mine explosion radius: local explodedist = FixedMul( (3 * (192 * FRACUNIT) ) / 2, mapobjectscale)
-- player.mo can be any mobj you wish to use as a reference or an actual position.
-- the last nil is your source
for i = 0, 15 do
K_SpawnKartExplosion(player.mo.x, player.mo.y, player.mo.z,
explodedist + (32 * mapobjectscale), 32, MT_MINEEXPLOSION,
i * (ANGLE_45 / 4), true, false, nil)
end
|
K_SpawnMineExplosion(mobj_t source, [UINT8 color])
|
void | Spawns the purely visual Mine explosion effect to where the source is. If no color is set, SKINCOLOR_KETCHUP is used as the default color, otherwise it's possible to use any SKINCOLOR_* enumeration to color the explosion.
|
K_SpawnBoostTrail(player_t player)
|
void | Spawns the characteristic fire trail after using a Sneaker or getting a perfect Starboost behind the player 's wheels. This function should be called once every tic to make a worthwhile boost trail.
|
K_SpawnSparkleTrail(mobj_t mo)
|
void | Spawns invincibility sparkles around mo . This should be called multiple times to make the sparkles more prominent.
|
K_SpawnWipeoutTrail(mobj_t mo, boolean translucent)
|
void | Spawns a white smoke effect on the mo 's wheels - this is the same smoke effect used when players receive a hit.
If |
K_DriftDustHandling(mobj_t spawner)
|
void | Spawns the drift dust and plays the drift sound on the spawner mobj. These will not happen unless the spawner is on the ground, and on odd frames. Thus, this function should be ran over multiple tics to make a noticeable drift effect.
|
K_DoSneaker(player_t player, [INT32 type])
|
void | Gives the player the sneaker effect, as if they were using a Sneaker item or stood on a boost pad.
|
K_DoPogoSpring(mobj_t mo, [fixed_t vertispeed, UINT8 sound])
|
void | Handles the vertical momentum given to mo when launched by a spring, handling gravity flipping and underwater physics. Note that this does not give the yellow/red spring's k_pogospring kartthing unless it is set to a non-zero value manually. In addition, the thrust factor will be increased by 1.25 or 1.115 if the player is under the effect of Sneakers or Invulnerability respectively, as long as the k_pogospring kartthing is not set to 2 (yellow springs). Do note that this thrust factor increase does not stack if both effects are present - Sneakers take priority.
|
K_KillBananaChain(mobj_t banana, [mobj_t inflictor, mobj_t source])
|
void | Destroys the banana chain that the player is currently dragging. Do note that the name is misleading, and it works with dragging Mines and Kitchen Sinks as well. inflictor and source can be set for MobjDeath hook handling purposes, but aside from directing the direction to where the dragging items move when destroyed, they serve no purpose.
|
K_RepairOrbitChain(mobj_t orbit)
|
void | "Repairs" a Jawz' and Orbinauts' orbital chain to make sure their hnext and hprev references are correct and to correct the player's item amount number.
|
K_FindJawzTarget(mobj_t actor, player_t source)
|
player_t | The Jawz' targetting system. The actor is the Jawz, and the source is the player who possesses it. Returns the player who is nearest to the source , which can be nil . The targetting will ignore dead players, invisible players and its source .
See also A_JawzChase. |
K_GetKartDriftSparkValue(player_t player)
|
INT32 | Returns the Drift Spark Value of the player, based on their speed and weight. This is used to determine the thresholds for blue, red and rainbow miniturbos and their respective spark effects. |
K_KartUpdatePosition(player_t player)
|
void | Updates the current position or standing of the player in Race or Battle, respectively.
|
K_DropItems(player_t player)
|
void | Drops the player 's current item, alongside their amount, that they were holding in their item box. If their item was deployed, they will drop to the ground instead.
|
K_StripItems(player_t player)
|
void | Completely wipes the player 's item-related states, except for an Eggman Monitor's roulette.
|
K_StripOther(player_t player)
|
void | Resets all item roulettes' status, Invincibility and Grow/Shrink timers, and Eggman Monitor-related timers. |
K_MomentumToFacing(player_t player)
|
void | Transforms the player's momentum to where the player is looking. This function will not work if they're not on the ground, or if the difference between the player's direction and their momentum is higher than 90 degrees. |
K_GetKartSpeed(player_t player, [boolean doboostpower])
|
fixed_t | Returns the player's speed in fixed_t , accounting for the game's current kartspeed and if the player has any bumpers left in Battle (which sets their speed stat to 1).
If |
K_GetKartAccel(player_t player)
|
fixed_t | Returns the player's acceleration in fixed_t , accounting if the player has any bumpers left in Battle (which sets their speed stat to 1).
|
K_GetKartFlashing(player_t player)
|
UINT16 | Returns the flashtics amount that the player should get after recovering from damage, depending on the mode being played and the player's speed stat.
By default, the flashtics amount is |
K_GetItemPatch(UINT8 item, [boolean tiny])
|
string | Returns a 64x64 patch name based on the KITEM_* or KRITEM_* type that is passed to the item variable. If tiny is set to true, it'll return a 32x32 patch instead.
|
K_SetRaceCountdown(tic_t racecountdown)
|
void | Sets the remaining time before all players blow up, in tics. This is used in the Race gametype to blow up players on bottom-half placements, after all top-halp placement players have finished. The default time used in races is 30 * TICRATE
|
K_SetExitCountdown(tic_t exitcountdown)
|
void | Sets the remaining time before the game finishes, after all players have finished the game (by crossing the finish line enough times in Race or by being the last one standing in Battle, for example), in tics. The default time used is 5 * TICRATE .
|
K_SetIndirectItemCooldown(tic_t indirectitemcooldown)
|
void | Sets the time before a Self-Propelled Bomb or a Shrink item can be rolled again, in tics. The default time set in-game is 20 * TICRATE .
|
K_SetHyudoroCooldown(tic_t hyubgone)
|
void | Sets the time before a Hyudoro item can be rolled again, in tics. The default time set in-game is 5 * TICRATE .
|
Iterator functions
Function | Iterator type | Description |
---|---|---|
displayplayers.iterate()
|
displayplayers | Iterates over all split-screen players. |
S_Music
Function | Return value(s) | Description |
---|---|---|
S_MusicType()
|
musictype_t | Returns the music's format:
|
S_MusicPlaying()
|
boolean | Returns true if music is loaded.
|
S_MusicPaused()
|
boolean | Returns true if music is paused.
|
S_MusicInfo(player_t player)
|
string, integer, boolean | Gets the music information that is being played on the player.
The function returns the following:
|
S_MusicName()
|
string | Returns the song's filename as a string. |
S_MusicExists(string mname, [boolean checkMIDI, boolean checkDigi])
|
boolean | Checks if the music whose filename is mname exists. checkMIDI and checkDigi helps check if there's MIDI and Digital versions of the music.
|
S_SetMusicLoopPoint(UINT32 looppoint)
|
boolean | Sets at which point should the music start again once it is finished playing, in miliseconds. |
S_GetMusicLoopPoint()
|
UINT32 | Gets at which point should the music start again once it is finished playing, in miliseconds. |
S_PauseMusic([player_t player])
|
boolean | Pauses the music if it is playing. |
S_ResumeMusic([player_t player])
|
boolean | Resumes the music if it is playing. |
Patch/string drawing functions
Function | Return value(s) | Description |
---|---|---|
v.drawKartString(int x, int y, string text, [int flags])
|
nil | Draws text on the screen at the screen coordinates given, using the same font as the one used by the "FREE PLAY" text, or the item counters when a player has multiple of the same item, among other uses.
Notes:
|
v.drawOnMinimap(fixed_t x, fixed_t y, fixed_t scale, patch_t patch, [colormap c, boolean centered])
|
nil | Draws a patch on the minimap according to the x and y coordinates on the actual level, and its set scale .
Notes:
|
Additional togglable HUD items
Huditem name | Description |
---|---|
"gametypeinfo"
|
Bumpers, karma, or laps, depending on the game type. |
"minimap"
|
The minimap on the right side of the screen in 1P, middle in 2P and 4P, and bottom right in 3P. |
"item"
|
Item slot on the top left. |
"position"
|
The position indicator on the bottom right. |
"check"
|
The "CHECK" F-Zero indicator. |
"minirankings"
|
The gametype rankings on the left side of the screen. |
"battlerankingsbumpers"
|
The bumper drawer for battle. Useful if you wish a custom battle game type without involving bumpers. |
"battlefullscreen"
|
Battle's full-screen overlay, telling the player to "WAIT", or "ATTACK OR PROTECT", etc.. |
"battlecomebacktimer"
|
The comeback timer in "battlefullscreen". |
"wanted"
|
The "WANTED" picture that appears on the bottom-right of the screen when a player is wanted in Battle. |
"speedometer"
|
The speedometer on the bottom-left of the screen. |
"freeplay"
|
"Free Play" text when playing solo. |
"rankings"
|
The player rankings that displays all players' position, name and time (or NO CONTEST if they did not finish in time), as well as the game speed. |
Lua | [view] | |
Language features | Syntax • Metatables | |
SRB2 data | Actions • Constants • Functions • Global variables • Hooks • Userdata structures | |
SRB2Kart data | Kart Userdata structures • Kart Functions • Kart Hooks • Kart Global Variables and Constants | |
Tutorials | Freeslots and Object resources • Custom player ability |