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.
• 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. S_StartSound(mobj, sfx_kslow) may be used instead if this is desired.
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 bounce is set to true, the momy of the mobj1 becomes reversed, effectively working as Goomba Stomp. When solid is set to true, the weight of mobj2 is set to be the same as mobj1, to handle cases where the mobj1 collides with a wall, or a solid, unmovable block like the ice blocks in Vanilla Lake.
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 player.kartstuff[k_instashield] is set to zero.
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. source is to whom the animation will appear. victim is optional, but if inputted, the visuals will have the victim's palette, while setting it to nil will use the source's colors. The amount indicates how many points the animation will have. There's only animations for +1, +2 and +3 points gained - anything else than these will make the animation not appear.
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 type to zero (spinout) will make sfx_slip play and make the player move if they were moving less than a fourth of their speed, which is banana-stepping behaviour. Setting it higher than zero does not cause these effects to happen (internally referred to as a wipeout instead). In Battle, setting trapitem to true will make this spinout not award extra points or reduce the player's or the source's wanted status. Does nothing in Race otherwise.
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_SpawnKartExplosion and K_SpawnMineExplosion to perform the AoE damage effect and explosion visuals respectively.
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, player will steal a bumper from victim. This also handles Karma Comeback if player did not have any more bumpers left. If force is set to true, player will steal a bumper from victim regardless of if it was normally possible or not (if they had any more bumpers left, in flash-tics, etc..)
K_SpawnKartExplosion(fixed_t x, fixed_t y, fixed_t z, [fixed_t radius, INT32 number, mobjtype_t type, angle_t rotangle, boolean spawncenter, boolean ghostit, mobj_t source])	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). radius is the explosion radius. Defaults to 32 * FRACUNIT. number is the number of type spawned to determine the explosion radius. Defaults to 32. type is the type of object spawned. Defaults to MT_MINEEXPLOSION. rotangle is the angle of the spawned object. Defaults to 0. spawncenter determines if the Objects spawned should be on the inputted x, y and z. Defaults to true. ghostit determines if ghosts of the objects should spawn instead. This nullifies the explosion's effects. Defaults to false. source determines who did the explosion. Defaults to nil. 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 translucent is set to true, the smoke becomes transparent and does not move around as much, which is the same effect used when players drag an item or enter offroad. Likewise with the other trail functions, this should be called multiple times to make the smoke effect more prominent.
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. type changes some cosmetic effects: 0 will not make the player taunt. 1 will make the player taunt. In addition, any non-zero type will make the player taunt. 2 will make the boost trail effect appear on player.mo.hnext instead.
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. vertispeed, if set to zero, will at least be between 48<<FRACBITS and 72<<FRACBITS, while sound: If set to 0, it will not play any sound. If set to 1, it will play the spring panel/object sound. If set to 2, it will play the pogo spring item sound.
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. In the Race gametype, players who are in front of the source position-wise take precedence. The cone to detect players in front of the source is also ANGLE_67h (67.5º). In the Battle gametype, the maximum range of a Jawz is 1028 fracunits, and the cone to detect players in front of the source is ANGLE_45 (45º) instead. 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 doboostpower is set to true, the player's k_boostpower and k_speedboost kartstuff variables will be accounted for the calculation.
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 3*TICRATE/2. This is multiplied by 2 if the Battle gametype is active. In addition, to account for the player's acceleration stat (or lack thereof), the flashtics amount is added by (flashingtics / 8) * (player.kartspeed).
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: 0 is MU_NONE - no music. 1 is MU_CMD. 2 is MU_WAV. 3 is MU_MOD. 4 is MU_MID. 5 is MU_OGG. 6 is MU_MP3. 7 is MU_MP3_MAD_UNUSED. 8 is MU_FLAC. 9 is MU_MODPLUG_UNUSED. 10 is MU_GME.
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: string - the music filename. integer - sound flags. boolean - returns true if the song has a looping point.
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: flags determines the video flags given, which control extra effects such as color and translucency.
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: c determines the colormap applied to the patch – use v.getColormap to obtain a value that can be used here. centered misleadingly de-centers the patch, as it is assumed to be centered by default.

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.