ZScript virtual functions

From ZDoom Wiki
(Redirected from ZScript Virtual Functions)
Jump to navigation Jump to search
Note: This feature is for ZScript only.

Overview

Virtual functions in ZScript are functions designed for inheritance purposes, which allow for child classes to override them with their own version. This grants the ability to also call the super function which will execute everything in the predecessor class's function. 

Class ActA : Actor
{
    int a;
    virtual void MyVirtualFunction()
    {
        // Do some stuff here.
        a++;
    }
}

This class will perform a++ and b++, with b++ going first. 

Class ActB : ActA
{
    int b;
    override void MyVirtualFunction()
    {
        b++;
        Super.MyVirtualFunction();
    }
}

Note: Through chaining actors via inheritance, it's possible to execute every version down to the base actor, if they're set up to call the super function. The following example demonstrates the variables 'c', then 'b', and finally 'a' being incremented in that order. 

Class ActC : ActB
{
    int c;
    override void MyVirtualFunction()
    {
        c++;
        Super.MyVirtualFunction();
    }
}

Abstract functions

Abstract functions are virtual functions that do not have a body (i.e. code). They can only be defined in abstract classes. The purpose of abstract functions is to create interface-like classes with different implementations. If you have a base class that is never used directly, only through implementations, then it should be marked abstract. Virtual functions that are always overridden in derived classes should also be converted to abstract functions.

Example: 

class Base abstract
{
    abstract int MyFunc();
}

class Derived1 : Base
{
    override int MyFunc()
    {
         return 1;
    }
}

class Derived2 : Base
{
    override int MyFunc()
    {
        return 2;
    }
}

Note that if you don't override an abstract function in a derived class, GZDoom will consider it a script error, unless the derived class is also marked abstract. It is also considered a script error to call an abstract function via the Super qualifier. Additionally, you cannot subclass DECORATE-based actors from ZScript classes with abstract functions.

Internal Functions

Some of ZDoom's classes have several functions available for overriding if desired.

Some of these govern fairly basic actor functionality and may produce unintended side effects or behaviours if overridden. Please test thoroughly whenever you override these (or call them in some unusual place, e.g., CanCollideWith() in some custom missile impact code), and if you don't know exactly what a virtual does you might want to call super.<nameofvirtualfunction>() in your override until you've had time to check the GZDoom source code to figure out what (if anything) it does by default.

Object

Called when an object is about to be removed from the game. This could be used for actor maintenance, such as removal of children actors which would otherwise stop functioning without the master, or special effects that may be associated with that actor in particular.

LineTracer

Inherits from Object

Called when the ray trace hits a potential blocker, be it an actor, wall, or plane. Returns the status telling the ray trace what to do next.

Thinker

Inherits from Object

Called after BeginPlay and before the first call to Tick. This is done before the very first state of an actor is ever reached, useful for performing one-time setups like giving local variables a value, without worrying about a monster being dormant at the start and going to Deactivate instead of Spawn.
Called every tic, 35 times a second. As the name implies, this is what makes an entity 'tick', or operate on its own.

Actor

Inherits from Thinker

Called when sound variables are to be cached for faster access via those variables (e.g. AttackSound, ActiveSound, etc.). Useful for caching custom sound variables.
Called just after the actor is created and before PostBeginPlay and the first call to Tick.
Called after BeginPlay and before the first call to Tick. This is done before the very first state of an actor is ever reached, useful for performing one-time setups like giving local variables a value, without worrying about a monster being dormant at the start and going to Deactivate instead of Spawn.
Called every tic, 35 times a second. As the name implies, this is what makes an entity 'tick', or operate on its own.
Called when an actor is activated (specific meaning of activation and possible conditions are described here).
Called when an actor is deactivated (specific meaning of deactivation and possible conditions are described here).
Called by projectiles when they're about to hit and deal damage to another actor. Called before TakeSpecialDamage. Heretic's Phoenix Rod missile uses this to tell D'Sparil to teleport away and not take damage when hit by it.
Called from the damage taker when they're about to take damage but haven't yet. The return value is the new damage to be taken. This occurs after all forms of damage modifiers are applied.
  • void Die(Actor source, Actor inflictor, int dmgflags = 0, Name MeansOfDeath = 'none')
Called when an actor is killed (a damaging attack causes an actor's health to fall less than or equal to 0)
  • bool Slam(Actor victim)
Called when an actor that has SKULLFLY set collides with another. Normally called by Lost Souls and Maulotaurs. Returning true tells the caller to ignore the rest of the collision code with the victim it hit while returning false uses standard collision behavior.
  • victim - The actor the caller is colliding with.
  • void Touch(Actor toucher)
Called when an actor with the SPECIAL flag gets touched by another. Normally only used by Inventory and SpectralMonster.
Called when an actor is touching an item but has not yet picked it up. Returning true tells the engine to touch the item while returning false does the opposite.
  • item - The item the caller is touching.
Called from Inventory's CallTryPickup() before other checks to determine if this actor can receive the item.
Called at the end of Inventory's CallTryPickup(), once the item has been received by the actor. Allows to perform additional behavior when items are received without overriding and copying TryPickup() just to do it.
Called when two actors may be capable of colliding with each other. This function is called from both actors involved in the collision. If one of the actors returns false then the engine will act as though the two actors didn't collide. If both return true then standard collision behavior is used.
NOTE: This will only be called if regular actor blocking is not bypassed entirely with the use of flags like THRUACTORS or an object lacking SOLID while not having BLOCKEDBYSOLIDACTORS, etc.
WARNING: This function assumes that the two colliding actors are the same before and after the calls. Do not destroy, damage, or perform any complex alterations of either actor within these calls as doing so may cause memory issues. If you need to perform checks like these when a collision occurs, then use CollidedWith() (development version fc6191d only) instead !
  • other - The actor the caller is potentially colliding with.
  • passive - Used to determine which actor is currently calling the function. If false, the actor that may cause the collision is the current caller.
Called when two actors capable of colliding with each other actually do so. This function is called from both actors involved in the collision.
NOTE: This virtual is called back ONLY when a collision actually occurs. If you want to check and abort a potential collision instead. e.g to stop an actor made of multiple smaller actors from colliding with itself, use CanCollideWith() instead.
  • other - The actor the caller collided with.
  • passive - Used to determine which actor is currently calling the function. If false, the actor that caused the collision is the current caller.
Called any time the actor is about to cross a linedef, this is called after most checks on PIT_CheckLine have ran. Returning false will make the actor be blocked by the line.
NOTE This virtual needs the actor to have the CROSSLINECHECK flag to run.
  • crossing - The line that was checked to see if the actor can cross it.
  • next - The absolute Vector3 coordinates in which the actor will be moved to if the check succeeds.
Called when the actor is falling and when sinking inside of deep water based on the Transfer_Heights special or swimmable 3D floors. Can be used in conjunction with the waterdepth and waterlevel variables.
  • grav - The current gravity of the actor, returns the same value as GetGravity.
  • oldfloorz - The absolute floor Z coordinate of the sector that the actor is currently sinking within.
Called right before a dead actor is about to be resurrected. This function is called from both the dead actor and its resurrecter. If one of the actors returns false then the dead actor will not be resurrected. If both return true then standard resurrection behavior is used.
Called when an actor is to be blasted by a disc of repulsion. If false is returned, the actor will not be blasted. If true, standard blast behavior is used.
  • source - The actor calling the blast function
  • strength - The current strength level of the blast
Called when a missile hits an actor. This is called after all other collision checks. Returning one of the following values will determine what the missile does next:
  • 1: The missile ignores the actor
  • 0: The missile hits but does no special behavior (e.g. won't deal damage, explode, etc.)
  • -1: Uses standard missile hit behavior
  • victim - The actor that was hit by the missile.
Called when a bouncing projectile collides with an actor, line or plane, based on its flags.
  • bool Used(Actor user)
Called when an actor is used by a player with the use button. Returns false if the actor wasn't used, otherwise returning true.
Returns the class type that the actor's blood uses. This will account for classes that replace it i.e. custom blood types
  • type - The specific blood type to return.
  • 0 - Returns the class type for standard blood
  • 1 - Returns the class type for blood splatters
  • 2 - Returns the class type for axe blood
Returns the health value that an actor will gib at upon death.
Returns the height of the actor when it dies. This will take special deaths into account if the actor is already dead after calling it.
  • string GetObituary(Actor victim, Actor inflictor, Name mod, bool playerattack)
Returns the appropriate obituary for an actor's death depending on how it died.
  • int OnDrain(Actor victim, int damage, Name dmgtype)
Called when an actor is draining health from another actor. Returns the amount of health to be drained.
  • victim - The actor whose health is being drained.
  • damage - The amount of damage dealt in the attack.
  • dmgtype - The damage type applied to the attack.
Called when an actor discovers a secret. Returning false stops the default message from being displayed.
  • printmsg - Whether or not a message is to be displayed
  • playsound - Whether or not a sound is to be played
  • bool PreTeleport(Vector3 destpos, double destangle, int flags)
Called before an actor is teleported to a new location. Returning false stops the teleport.
  • destpos - The 3D position the actor is being teleported to
  • destangle - The angle the actor wishes to face after teleporting
  • flags - The teleportation flags to use in the action
  • void PostTeleport(Vector3 destpos, double destangle, int flags)
Called after an actor teleports to a new location. Can be used to apply special behavior after the fact.
  • destpos - The 3D position the actor teleported to
  • destangle - The angle the actor faced after teleporting
  • flags - The teleportation flags used in the action
Checks to see if the actor can switch its target to the new one upon being damaged. Returning false tells the caller not to switch targets
  • other - The new target the caller wants to switch to
Called when an actor is crushed by the environment (e.g. crushers, Hexen's polyobjects, etc.). Returns true if standard crushing behavior should be used.
  • items - Set to true if dropped items are to be crushed alongside the caller.
  • clearscope int GetMaxHealth(bool withupgrades = false) const
Returns the health an actor spawns with.
  • int DamageMobj(Actor inflictor, Actor source, int damage, Name mod, int flags = 0, double angle = 0)
Called by the actor whenever it takes damage. Returns the amount of damage the caller actually took from the attack.
Determines whether an actor should spawn into the map. If false is returned the actor will not be spawned at all.
(Need more info)
  • void SpawnLineAttackBlood(Actor attacker, Vector3 bleedpos, double SrcAngleFromTarget, int originaldamage, int actualdamage)
Spawns the blood after an actor takes damage from a hitscan attack.
  • attacker - The source of the hitscan attack.
  • bleedpos - The 3D position to spawn the blood.
  • SrcAngleFromTarget - The angle the hitscan attack traveled normalized to a range between -180 and 180 degrees
  • originaldamage - The unmodified damage to deal by the hitscan attack.
  • actualdamage - The actual amount of damage the caller took.
  • void ApplyKickback(Actor inflictor, Actor source, int damage, double angle, Name mod, int flags)
Calle by an actor when it's dealt damage and must be thrusted by the attack.
Adds an item to the caller's inventory.
  • item - The item to be added to the caller's inventory.
Removes an item from the caller's inventory
  • item - The item to be removed from the caller's inventory.
Uses an item in the caller's inventory. Returns true if the item was used successfully.
  • item - The item to be used.
Destroys all valid inventory items of the caller.
Called when an actor dies while morphed. Returns three values:
  • A pointer to the original actor before it was morphed.
  • The style of morph of the original actor.
  • The amount of health the original actor has.
Called right before an actor morphs on both the original actor and the newly created morph actor.
  • mo - A pointer to the other actor in the morph. If the original actor, this is the morph actor. If the morph actor, this is the original actor.
  • current - True if the caller is the newly created morph actor.
Called right after an actor morphs on both the original actor and the newly created morph actor.
  • mo - A pointer to the other actor in the morph. If the original actor, this is the morph actor. If the morph actor, this is the original actor.
  • current - True if the caller is the newly created morph actor.
Called right before an actor changes back on both the original actor and the morph actor.
  • mo - A pointer to the other actor in the morph. If the original actor, this is the morph actor. If the morph actor, this is the original actor.
  • current - True if the caller is the original actor.
Called right after an actor changes back on both the original actor and the morph actor.
  • mo - A pointer to the other actor in the morph. If the original actor, this is the morph actor. If the morph actor, this is the original actor.
  • current - True if the caller is the original actor.
  • bool Morph(Actor activator, class<PlayerPawn> playerclass, class<MorphedMonster> monsterclass, int duration = 0, int style = 0, class<Actor> morphflash = null, class<Actor>unmorphflash = null)
Called when a morph function is used. Returns true if the actor was successfully morphed.
  • activator - The actor responsible for the morph. Only used when players are morphing.
  • playerclass - The class type to use if a player is morphing.
  • monsterclass - The class type to use if a monster is morphing.
  • duration - The duration of the morph in tics.
  • style - The style of morphing to use.
  • morphflash - The class type to use when spawning a flash as the actor morphs.
  • unmorphflash- The class type to use when spawning a flash as the actor unmorphs.
  • bool UnMorph(Actor activator, int flags, bool force)
Called when a morphed actor is going to unmorph. Returns true if the actor successfully unmorphed.
  • activator - The actor responsible for the unmorph. Only used when players are unmorphing.
  • flags - The flags to check when a player is unmorphing. Only MRF_STANDARDUNDOING is used by default.
  • force - If true, don't collision check when unmorphing back into the original actor.
  • bool MorphMonster(Class<Actor> spawntype, int duration, int style, Class<Actor> enter_flash, Class<Actor> exit_flash)
Called when a monster is being morphed. Returns true if the monster morphed successfully.
  • spawntype - The class type to use for the newly created morph actor.
  • duration - The duration of the morph in tics.
  • style - The style of morphing to use.
  • enter_flash - The class type to use when spawning a flash as the monster morphs.
  • exit_flash - The class type to use when spawning a flash as the monster unmorphs.

MorphedMonster

Inherits from Actor

Called when a monster is going to unmorph. Returns true if the monster successfully unmorphed.
  • force - If true, don't collision check when unmorphing back into the original actor.

FastProjectile

Inherits from Actor

Responsible for spawning the FastProjectile's trail while it's traveling.

SorcBall

Inherits from Actor

Called when a SorcBall decides to cast its spell. Can be used to add custom pre and post spell behavior.
Called when the SorcBall is orbiting around its parent and is not casting a spell.
Called when a SorcBall decides to cast its spell. This contains behavior for the spell itself that's being casted.

PathFollower

Inherits from Actor

Handles the behavior for moving from one interpolation point to the next. Returning false tells the PathFollower to not look for its next node after reaching its current destination.

SectorAction

Inherits from Actor

Called when the SectorAction is triggered by an actor. Returns true if the action was successfully triggered.
  • triggerer - The actor directly responsible for triggering the action.
  • activationType - The type of action(s) the triggerer wants to trigger. Will not activate if it doesn't align with the SectorAction's own activation types.
Called when testing if the actor that activated the SectorAction is capable of doing so. Returns true if the actor can activate it.
  • triggerer - The actor directly responsible for triggering the action.

Inventory

Inherits from Actor

Called from CallTryPickup. Used to determine whether the item should be directly picked up (it doesn't respawn) or a copy of it (it does respawn).
Called by all Inventory items that are currently in the player's inventory whenever the player is receiving a new item (but before it's actually received).
  • protected bool TryPickup(in out Actor toucher)
Called when an actor is trying to receive this item (whether directly or by walking over it).
Called when trying to see if the actor is capable of picking up the item based on class type.
Called when checking to see if the item should disappear after being picked up. Returning true tells it to stay.
Called if CanPickup is false but the item does not have the INVENTORY.RESTRICTABSOLUTELY flag set.
Called when the item's owner uses the "use all inventory items" key.
  • user - The actor trying to use the item.
Called when an item is picked up by an actor. Activates the item's special if it has one.
  • toucher - The actor picking the item up.
Called when an item is picked up by an actor for the first time.
Called when an item is removed from its owner's inventory. Is not responsible for the actual removal.
Called when an item is attempting to be dropped from the owner's inventory. Returns the item that should be tossed.
  • amt - The amount of the item that should be dropped. This doesn't create duplicates but instead returns one item with its amount set to amt. Negative values will drop 1 by default.
Returns the pick up message for the item. By default this simply returns PickupMsg (a string variable defined in Inventory), but this function can be overridden to extend the behavior.
Called when an actor picks up an item and the item doesn't have the QUIET flag set. Plays the item's pick up sound.
Called when an item's amount has reached 0 after use. Determines whether the item should stay in the owner's inventory or be destroyed entirely.
Called when an item in somebody's inventory is about to be carried over to another map, in case it needs to do special clean-up.
Called when an item with an owner has entered a different map. This works with both regular maps and hubs.
Called every tic similar to Tick, but only if the item has an owner. Allows for special effects that only work when attached to an actor (e.g. power ups).
Called when an item that respawns is set to hide after being picked up. This is not called if ShouldStay returns true.
Called when determining if the item should stay after being picked up so it can respawn later. Returns true if the item should stay, otherwise the item will be directly picked up and never respawn.
  • void ModifyDamage(int damage, Name damageType, out int newdamage, bool passive, Actor inflictor = null, Actor source = null, int flags = 0)
Allows modification of damage the owner is taking or dealing if the damage flags allow it. Called before AbsorbDamage. This is typically utilized by powerups like PowerDamage and PowerProtection.
This function isn't called if the damage is being dealt with the DMG_NO_ENHANCE flag.
  • void AbsorbDamage(int damage, Name damageType, out int newdamage, Actor inflictor = null, Actor source = null, int flags = 0)
Allows modification of the damage an item's owner is taking if the damage flags allow it. Called after ModifyDamage. This is typically used by Armor items.
This function isn't called if the damage is being dealt with the DMG_NO_PROTECT flag.
  • bool Use(bool pickup)
Called when an item is attempting to be used. Returns true if the item was successfully used. If the item has +INVENTORY.AUTOACTIVATE flag, this will be called automatically in its TryPickup() call.
Returns the speed modifier the item applies to the owner.
Returns whether or not the owner should be frozen briefly after teleporting. Returning true tells the owner not to freeze.
Allows direct modification of an owning player's weapon sprites.
  • vis - The current visual information about the player's weapon sprite. Modifying this directly affects the sprite.
  • vis.RenderStyle - The current rendering style of the weapon sprite.
  • vis.alpha - The current alpha of the sprite.
  • vis.invert - Whether the sprite is currently inverted or not.
  • changed - Whether or not the style was changed in any AlterWeaponSprite calls this frame (must be set manually). Does nothing by default.
Called when the item's owner dies.
Returns the color of the screen blend the item applies. Mainly used with power ups.
Called when dropping an item. Allows for special actions to trigger when doing so. Returning true prevents the standard drop behavior from executing.
  • dropper - The actor dropping the item.
Called after an item has been dropped. Allows for custom post-drop behavior.
  • dropper - The actor that dropped the item.
Called when an item is being dropped. Modifies the amount the item has after doing so.
  • dropamount - The new amount to give the item. If this is 0 or less than the amount is not changed.
Called when an item is being given. Modifies the amount of the item.
  • receiver - The actor the item is being given to.
  • amount - The amount to set the item's amount to.
  • givecheat - If true, the item was given via cheating.

Weapon

Inherits from StateProvider which inherits from Inventory

Called when the level is first loaded if the weapon has neither a defined slot number property nor is assigned to a slot in a player class. Returns the slot number of the weapon and its slot priority multiplied by 65536.
Returns the weapon's Ready state. Called by multiple functions when setting a weapon to its Ready state (e.g. A_Raise).
Returns the weapon's Select state. Called when a pending weapon becomes the player's current weapon.
Returns the weapon's Deselect state. Called when a pending weapon has been queued up and the current weapon needs to be lowered.
Returns the weapon's Fire state. Called by PlayerPawn's fire function.
  • hold - If true, returns the Hold state instead if one is found, otherwise returning Fire.
Returns the weapon's Altfire state. Called by PlayerPawn's alt fire function
  • hold - If true, returns the AltHold state instead if one is found, otherwise returning Altfire.
Plays the weapon's UpSound. Called when a pending weapon becomes the player's current weapon.
  • origin - The actor to play the sound from.
Called when a Tome of Power expires and the weapon is currently powered up.
  • bool CheckAmmo(int fireMode, bool autoSwitch, bool requireAmmo = false, int ammocount = -1)
Called when the game checks to see if a weapon has enough ammo either for firing or for switching to. Returns true if the weapon has enough ammo.
  • bool DepleteAmmo(bool altFire, bool checkEnough = true, int 'ammouse = -1)
Called to consume ammo when attacking.
Allows modifying the weapon bob values after they have been calculated by the BobWeapon() call on the PlayerPawn. (New from 4.11.0)
  • bob - the bob value received from BobWeapon().
  • layer - the number of the layer that is bobbing.
  • ticfrac - current tic fraction.
By default the function returns bob unmodified.
  • ui Vector3, Vector3 ModifyBobLayer3D(Vector3 Translation, Vector3 Rotation, int layer, double ticfrac)
Allows modifying the weapon bob values for 3D-model-based weapons after they have been calculated by the BobWeapon3D() call on the PlayerPawn. (New from 4.11.0)
  • Translation - the 3D position value received from BobWeapon3D().
  • Rotation - the 3D rotation value received from BobWeapon3D().
  • layer - the number of the layer that is bobbing.
  • ticfrac - current tic fraction.
By default the function returns Translation, Rotation unmodified.
(Need more info) (New from 4.11.0)

Powerup

Inherits from Inventory

Called when a power up becomes active for the first time.
Called when the power up ends.
Returns the icon drawn on the screen for the power up
Returns true if the power up is about to run out and is currently in the middle of a blink. Returns false otherwise.

Ammo

Inherits from Inventory

Returns the class type of the base ammo used for this class of ammo e.g. with ClipBox the class type returned would be Clip.

RandomSpawner

Inherits from Actor

Called after the random actor has been spawned and initialized. Allows for further post modifications of the actor from the RandomSpawner itself instead of on the actor.
  • spawned - The actor that the RandomSpawner created
The function for deciding which actor to spawn. Returns the name of the actor class that should be spawned. Returning 'None' will spawn nothing.

PlayerPawn

Inherits from Actor

WARNING: Caution must be used when overriding player virtual functions. Client-prediction can cause desyncs when playing in networked games, especially with functions related to PlayerThink. Only override these functions if you absolutely know what you're doing.
Sets the player to their SpawnState. Called when the player stops moving.
Sets the player to their SeeState. Called when the player starts moving.
Sets the player's state to their MissileState. Called when the player performs an attack.
Sets the player's state to their MeleeState. Often called when the player's weapon fires and a muzzle flash is produced.
Called every tic while the player is morphed. Allows for special behavior when morphed.
Called when the player respawns.
Called when the player fires their weapon's primary attack.
  • stat - The state to set the player's current weapon to.
Called when the player fires their weapon's alternate attack.
  • stat - The state to set the player's current weapon to.
Called every tic when checking to see if the player has a pending weapon. If so, the current weapon starts to lower.
Called every tic. Handles the logic for the player's weapon sprites (including CustomInventory sprites).
Called every tic. Calculates the view height offset of the player (e.g. the view bob when running).
Called every tic while the player is dead. Allows for special behavior while dead.
Called every tic when checking if the player's FOV matches their desired FOV. This is what handles the zooming in and out effect when using A_ZoomFactor.
Called every tic when checking to see what cheats the player currently has active. By default handles flying and noclipping.
Called every tic to check if the player is frozen via the FROZEN flags. Returns true if the player is partially or totally frozen.
Checks if the player is capable of crouching. Returns true if the player can.
Handles the view height movement when crouching and uncrouching.
  • direction - Whether the movement is down (negative, crouching) or up (positive, uncrouching).
Called every tic to check if the player is crouching or not.
  • totallyfrozen - True if the player is partially/totally frozen via the FROZEN flags.
  • double, double TweakSpeeds(double forward, double side)
Modifies the speed values by the player's speed modification properties and items. Returns the modified forward and sideways movement speeds.
  • forward - The original forward speed.
  • side - The original sideways speed.
Moves the player based off their current button inputs.
Called every tic to modify the player's pitch based off their current input.
Handles making the player jump.
Handles the up and down flight movement when using something like Heretic's Wings of Wrath.
Called every tic to handle all of the movement functions of the player.
Called every tic to check if the player should unmorph.
Called every tic to apply poison damage and modify the poison screen effect Hexen has.
Called every tic to check if the player's health should degenerate if over their max health when the CVar is set.
Called every tic to check the player's air supply if underwater.
Called every tic before anything else in the game. Largely handles all player checks, special player tic functions, and player movement.
Called when giving the player their default starting items.
Called when giving the player their death match starting items.
Gets the amount of time the player should be frozen after teleporting. This mainly checks for items that invalidate the player's TeleportFreezeTime property. Returns the duration to freeze in tics.
Called when picking a weapon in a slot. Looks for the last weapon in the slot first. Returns the weapon that should be selected.
  • slot - The slot number to look in.
  • checkammo - If false, don't check if the weapon has enough ammo to fire.
Gets the next weapon when going through the slots in order. Returns the weapon that should be selected.
Gets the previous weapon when going through the slots in order. Returns the weapon that should be selected.
Called every frame. Returns the weapon sprite's xy bobbing offset for that frame.
  • ticfrac - The percentage of the way to the next tic that the current frame is at. Ranges from 0 to 1. Used for interpolating the offset between tics.
Returns the pain flash color the player has when taking damage.
Resets the player's air supply. Returns whether or not the player was drowning.
  • playgasp - If true and the player was drowning, play the gasp sound.
(Need more info)
Called when a player has traveled to a different map. Works on both regular maps and hubs.
Called when the player uses the console give cheat.
  • name - The name of the inventory type to give.
  • amount - The amount to give of the inventory type.
Called when the player uses the console take cheat.
  • name - The name of the inventory type to take.
  • amount - The amount to take of the inventory type.
  • void CheatSetInv(String strng, int amount, bool beyond)
Called when the player uses the console setinv cheat.
  • strng - The name of the inventory type to set.
  • amount - The amount to set the inventory type to.
  • beyond - If true, allow the inventory type to go beyond its max amount.
  • String CheatMorph(class<PlayerPawn> morphClass, bool quickundo)
Called when the player uses the console morphme cheat. Returns the text to display after morphing.
  • morphClass - The class type to morph into.
  • quickundo - If false, allow the player to morph into a different class while still morphed.
Handles taking away the player's non-wimpy weapons.
Called when using a flechette. Returns the flechette item to use in the action.
Called on the morph actor when the player morphs. Responsible for giving the player their appropriate morph weapon after doing so.
  • bool MorphPlayer(playerinfo activator, Class<PlayerPawn> spawntype, int duration, int style, Class<Actor> enter_flash = null, Class<Actor> exit_flash = null)
Morphs the player into the new morph actor. Returns true if the player successfully morphed.
  • activator - The info of the player that's responsible for the morph.
  • spawntype - The class type to use for the new morph actor.
  • duration - The duration of the morph in tics.
  • style - The style to use for the morph.
  • enter_flash - The class type to use when spawning a flash as the player morphs.
  • exit_flash - The class type to use when spawning a flash as the player unmorphs.
  • bool UndoPlayerMorph(playerinfo activator, int unmorphflag = 0, bool force = false)
Unmorphs the player back into their original form. Returns true if the player unmorphed successfully.
  • activator - The info of the player that's responsible for the unmorph.
  • unmorphflag - The flags to check when unmorphing. Only MRF_STANDARDUNDOING is used by default.
  • force - If true, don't collision check when unmorphing back into the original player.

StaticEventHandler

Inherits from Object

InterBackground

Called when loading the background image for the intermission screen. Returns whether or not to automatically start the next map. Returning false will start a count down until the next map automatically starts.
  • isenterpic - If true, load the image for entering the next map instead of the stats screen.
Called every tic during the intermission screen. Handles animating the background image.
Called every frame during the intermission screen. Draws the background for the screen.
  • CurState - The current state of the intermission screen's logic.
  • StatCount - Showing the stats for the previous level.
  • ShowNextLoc - Currently showing the next location.
  • NoState - No current state.
  • LeavingIntermission - Closing the intermission screen.
  • drawsplat - If true, draw the splat effects on locations the player has already been to (see: Doom 1's intermission screens).
  • snl_pointeron - If true, draw the arrow pointing to the location the player is entering (see: Doom 1's intermission screens).

StatusScreen

Called when drawing the title text for finishing a level at the top of the intermission screen. Returns the y offset from the top of the screen.
Called when drawing the title text for entering a level at the top of the intermission screen.
Called when the intermission screen is closing.
Handles the behavior for initializing the intermission screen with no state. Called shortly before the intermission screen is about to close.
Called every tic that the intermission's CurState is set to NoState. Handles automated closing of intermission screen when entering the next map.
Called when going from the stats screen to showing the next location.
Called every tic that the intermission's CurState is set to ShowNextLoc. Handles the blinking arrow and counting down towards setting NoState.
Called every frame that the intermission's CurState is set to ShowNextLoc and LeavingIntermission. Handles drawing the entering level background and entering level title text.
Called every frame that the intermission's CurState is set to NoState. Calls drawShowNextLoc with the arrow set to not blink when drawn.
Handles starting the intermission music on the first tic of the intermission screen.
Called every tic. Handles the update functions for the intermission screen based on the CurState.
Called every frame. Handles the draw functions for the intermission screen based on the CurState.
  • void Start(wbstartstruct wbstartstruct)
Called when the intermission screen is first created.
  • wbstartstruct - Contains information and player stats about the previous level and information about the next level.
Called when the intermission screen is started. Handles initializing the stats.
Called every tic that the intermission's CurState is set to StatCount.
Called every frame that the intermission's CurState is set to StatCount.

HUDMessageBase

Called every tic the HUD message is active by the status bar. Returns true if the message should disappear.
Called by the status bar whenever the screen size changes. Handles resizing the text to fit appropriately.
  • void Draw(int bottom, int visibility)
Called every frame the HUD message is active by the status bar. Handles drawing the text of the message.
  • bottom - The y offset that corresponds to the bottom of the screen. Takes whether or not the status bar is visible into account.
  • visibility - The visibility flags to use when drawing the message. If any of the HUD message's visibility flags match one, the message won't draw.

BaseStatusBar

Called when the status bar is first created. Can be used to set up additional functionality.
Called every tic. Can be used to track functionality that should be handled on a consistently timed basis.
  • void Draw(int state, double TicFrac)
Called every frame. Handles drawing functionality of the HUD.
  • state - The current state of the HUD.
  • HUD_StatusBar - The status bar is currently visible.
  • HUD_Fullscreen - The HUD is currently in full screen mode.
  • HUD_None - The HUD is currently disabled.
  • HUD_AltHud - GZDoom's alternate HUD is being used.
  • TicFrac - The percentage of the way to the next tic that the current frame is at. Ranges from 0 to 1. Can be used to interpolate between tics.
Called whenever the screen size changes. Sets up the HUD to properly scale with the new resolution.
Called when a weapon is picked up for the first time. Signals the mug shot to grin.
  • weapn - The weapon that was picked up.
  • clearscope void SetMugShotState(String state_name, bool wait_till_done=false, bool reset=false)
Sets the current state of the mug shot.
  • state_name - The name of the mug shot image to use.
  • wait_till_done - If true, wait for the current mug shot state to finish before switching to the new one.
  • reset - If true, reset the current state of the mug shot if both it and the new state are the same.
  • clearscope void FlashItem(class<Inventory> itemtype)
Responsible for the flash that appears in the player's visible inventory when using an item (see: Heretic and Hexen).
  • itemtype - The class type of the item that was used.
Attaches the HUD to the specified player.
  • player - The player info of the player that the HUD should attach to.
Responsible for the crosshair size change that can be set when picking up items.
Called whenever a new game is started. Does not include loading a saved game.
Draws a popup box like the character portraits when talking to someone in Strife.
  • popnum - The index of the popup to show.
Checks to see if a log instead of a popup should be drawn. Returning true tells the game to draw the log.
  • state - The current state of the HUD.
Called when the console receives a notification. If true is returned then the console will not print the notification.
  • printlevel - The type of message being received.
  • outline - The text to be printed.
Called when the console notifications are cleared.
Called when the console wants to print a HUD message. If true is returned then the console will not automatically create the HUD message.
  • fnt - The font type to print the message with.
  • msg - The message to be printed.
  • bold - If true, uses the font's bold text.
(Need more info)
Called when a chat message is to be printed. If true is returned then the game will not execute the default logic for chat printing.
  • txt - The current message to be printed.
Called when calculating the height of the status bar when drawing the level name in the auto map. Useful for graphics that extend higher than the status bar itself. Returns the additional height to add to the top of the status bar relative to the resolution of the HUD.
  • scaleratio - The current width ratio of the last line of text to draw of the level name to the width of the HUD.
Called every frame the idmypos cheat is on. Handles drawing the player's current position on the screen.
Called every frame the automap is active. Handles drawing text based information that's printed while the auto map is open.
  • ticfrac - The percentage of the way to the next tic that the current frame is at. Ranges from 0 to 1.
Called every frame. Handles drawing power up icons if they have one.

DoomStatusBar

Inherits from BaseStatusBar

Called every frame. Responsible for drawing the keys in Doom's status bar.
Called every frame. Responsible for drawing the collection of ammo totals in Doom's status bar.
Called every frame. Responsible for drawing the weapon slot numbers in Doom's status bar.
Called every frame. Responsible for drawing the keys on the HUD in Doom when in fullscreen mode.

AltHud

Called when the status bar is first created. Can be used to add custom functionality on creation.
  • void DrawTimeString(Font fnt, int color, int timer, int x, int y, double trans = 0.75)
Called every frame. Responsible for drawing the formatted timer of how long the player has been playing.
  • fnt - The font to use for the text.
  • color - The color to use for the text.
  • timer - The timer being used to create the formatted string (tracked in tics).
  • x - The x offset of the text. The text here is right aligned.
  • y - The y offset of the text.
  • trans - The alpha to use for the text.
  • void DrawStatLine(int x, in out int y, String prefix, String text)
Handles drawing a stat e.g. kills.
  • x - The x offset of the text.
  • y - The y offset of the text. This value is directly modifiable so it can be automatically shifted up when called in DrawStatus.
  • prefix - The prefix for the text, often used to indicate which stat is being printed.
  • text - The text to be printed, often the stat value itself.
Called every frame. Draws any stats that are enabled.
  • CPlayer - The player info of the player to get stats from if applicable (mainly in multiplayer).
  • x - The x offset to draw the stats at.
  • y - The y offset to start drawing the stats at.
Called every frame. Draws the player's health.
  • CPlayer - The player info of the player whose health is being drawn.
  • x - The x offset to draw the health at.
  • y - The y offset to draw the health at.
  • void DrawArmor(BasicArmor barmor, HexenArmor harmor, int x, int y)
Called every frame. Draws the armor value based on the armors passed to it.
  • barmor - The BasicArmor pointer to use when calculating the amount of armor.
  • harmor - The HexenArmor pointer to use when calculating the AC of the armor.
  • x - The x offset to draw the armor value at.
  • y - The y offset to draw the armor value at.
  • bool DrawOneKey(int xo, int x, int y, in out int c, Key inv)
Draws a single key on the HUD. Returns true if the key had a valid icon to draw.
  • xo - The base x offset the keys are drawn at. Does nothing by default.
  • x - The current x offset to draw the key at.
  • y - The y offset to draw the key at.
  • c - The number of keys that have been drawn on the current line. Can be directly modified for more customizability. Does nothing by default.
  • inv - The key to check the icon for so it can be drawn.
  • int DrawKeys(PlayerInfo CPlayer, int x, int y)
Called every frame. Handles drawing all the keys on the HUD. Returns the y offset of the next line on top of the drawn keys.
  • CPlayer - The player info of the player to search for keys.
  • x - The x offset to start drawing the keys at. Keys drawn shift leftward on the line until reaching 10 and then wrap back.
  • y - The y offset to start drawing the keys at. Keys drawn shift upward every time the line wraps.
  • int DrawAmmo(PlayerInfo CPlayer, int x, int y)
Called every frame. Draws all the information related to the player's ammo on the HUD. Returns the y offset of the next line on top of the drawn ammo values.
  • CPlayer - The player info of the player to get the ammo from.
  • x - The x offset to draw the ammo at.
  • y - The y offset to start drawing the ammo at. Shifts upward.
  • void DrawOneWeapon(PlayerInfo CPlayer, int x, in out int y, Weapon weapon)
Draws the image of a weapon on the HUD.
  • CPlayer - The player info of the player who owns the weapon.
  • x - The x offset to draw the image at.
  • y - The y offset to draw the image at. This value is directly modifiable so it can be automatically shifted up when called in DrawWeapons.
  • weapons - The weapon to check for an image to draw.
Called every frame. Draws images of all of the player's current weapons.
  • CPlayer - The player info of the player to look for weapons.
  • x - The x offset to start drawing the weapon images at.
  • y - The y offset to start drawing the weapon images at.
Called every frame. Draws the player's visible inventory items on the HUD.
  • CPlayer - The player info of the player whose inventory should be searched.
  • x - The x offset to start drawing the items at. Shifts rightward.
  • y - The y offset to draw the items at.
  • void DrawFrags(PlayerInfo CPlayer, int x, int y)
Called every frame during death match games. Draws the number of frags the player currently has.
  • CPlayer - The player info of the player to get the frag count from.
  • x - The x offset to draw the frag count at.
  • y - The y offset to draw the frag count at.
Called every frame the automap is open or when the idmypos cheat is true. Draws the player's current coordinates.
  • CPlayer - The player info the player to get the position of.
  • withmapname - If true, draws the name of the level along with it.
Called every frame. Draws the current formatted time based on the option selected by the player. Returns true if the time was drawn.
  • y - The y offset to draw the time at.
Called every frame. Draws the latency from the client to the host of the game. Returns true if the latency was drawn.
  • y - The y offset to draw the latency at.
Called every frame. Draws the player's power up icons if they have any.
  • CPlayer - The player info of the player to check for power ups.
  • y - The y offset to start drawing the icons at. Shifts downward if the icons would go off screen (shifts leftward as more are drawn).
Called every frame. The main drawing function for the HUD.
  • CPlayer - The player info of the player to get information from.
Called every frame the automap is active. Responsible for drawing text information related to the automap.
  • CPlayer - The player info of the player to get information from.
  • void Draw(PlayerInfo CPlayer, int w, int h)
Called every frame. Determines whether to draw the regular HUD or automap HUD.
  • CPlayer - The player info of the player to get information from.
  • w - The width to use for the HUD.
  • h - The height to use for the HUD.

Menu

Inherits from Object

  • bool MenuEvent(int mkey, bool fromcontroller)
Called whenever a hardcoded menu button is pressed. Returns true if the event should have no further handling but does nothing by default.
  • mkey - The code for the menu key that was used.
  • fromcontroller - If true, the event was triggered by a controller.
Called whenever a GUI mouse or keyboard action occurs. Returns true if the event should have no further handling.
  • ev - Contains information about the event that occurred.
Called when any non-GUI related input is used. Returns true if the event should have no further handling.
  • ev - Contains information about the event that occurred.
Called every frame. Handles drawing any generic menu visuals.
If a GUI keyboard action occurs, handle the behavior for converting that action to a menu action. Returning false will stop the default conversion behavior.
Sets the menu item to take focus of. Focus is when an item becomes the currently selected option the player is using. Does nothing by default.
  • fc - The menu item that wants to take focus.
Checks if the menu item is the current focus of the menu. Returns true if the menu item is the current focus. Does nothing by default.
  • fc - The menu item to check if it's focused.
Handles unsetting the current focus of the menu. Does nothing by default.
Used to reset the color value of a color picker. Does nothing by default.
Called from the default OnUIEvent behavior. Handles specific mouse-related actions such as left clicking and movement. Returns true if the mouse should be captured after left clicking.
  • type - The type of mouse event that occurred.
  • mx - The current x position of the mouse on the screen.
  • my - The current y position of the mouse on the screen.
Called every tic. Can be used to handle behavior that should happen on time consistent basis.
Called when returning to a menu from a sub menu.

GenericMenu

Inherits from Menu

  • void Init(Menu parent)
Called when the menu is first created. Allows for custom functionality when initializing.
  • parent - The menu this one belongs to. If parent is not null it can be considered a sub menu.

OptionMenu

Inherits from Menu

  • void Init(Menu parent, OptionMenuDescriptor desc)
Called when the menu is first created. Allows for custom functionality when initializing.
  • parent - The menu this one belongs to. If parent is not null it can be considered a sub menu.
  • desc - The option menu items in this menu and related information of their display.
Calculates the indent for where to draw the option menu's items at. Returns the x offset to draw at.

ListMenu

Inherits from Menu

  • void Init(Menu parent = NULL, ListMenuDescriptor desc = NULL)
Called when the menu is first created. Allows for custom functionality when initializing.
  • parent - The menu this one belongs to. If parent is not null it can be considered a sub menu.
  • desc - The list menu items in this menu and related information of their display.

ConversationMenu

Inherits from Menu

  • int Init(StrifeDialogueNode CurNode, PlayerInfo player, int activereply)
Called when the menu is first created. Allows for custom functionality when initializing. Returns the y offset for the top of the reply list.
  • CurNode - The dialogue node the menu starts at.
  • player - The player info of the player the speaker is talking to.
  • activereply - The reply to be automatically selected.
Handles the text formatting of the replies on menu initialization. Returns the y offset for the top of the reply list.
  • activereply - The reply to be automatically selected.
Handles the text formatting of the speaker's dialogue on menu initialization.
Handles drawing the backdrop for the conversation. Returning true dims the background of the text.
Handles drawing the dialogue of the speaker alongside other information such as their name.
  • dimbg - If true, dims the background behind the text.
Handles drawing the replies in list form.
Handles drawing the player's current gold if the menu has it enabled.

MessageBoxMenu

Inherits from Menu

  • void Init(Menu parent, String message, int messagemode, bool playsound = false, Name cmd = 'None', voidptr native_handler = null)
Called when the menu is first created. Allows for custom functionality when initializing.
  • parent - The menu this one belongs to. If parent is not null it can be considered a sub menu.
  • message - The text of the prompt.
  • messagemode - The mode for displaying the responses. Non-zero values will leave out the generic yes and no responses.
  • playsound - If true, plays the prompt sound.
  • cmd - The name of the menu class to go to if this is a sub menu with no handler.
  • native_handler - The handler to call when handling the result. If there is none the parent menu is used instead.
Handles the player's response to the prompt.
  • res - True if the player hit yes.

MenuItemBase

Inherits from Object

Checks against the passed xy coordinate. Returns true if the check passed. Does nothing by default.
  • x - The x coordinate to check against.
  • y - The y coordinate to check against.
Called every tic by the menu this menu item belongs to. Can be used to handle functionality that should be done with consistent time intervals.
Called every frame. Handles drawing the menu item's generic visuals.
  • selected - If true, this menu item is currently the focus of the menu.
Checks if the menu item can be selected. Returns true if it can. Does nothing by default.
Activates the menu item. Returns true if it activated successfully. Does nothing by default.
Returns the name of the menu class the item goes to and the parameters when setting that menu.
Changes a text value of the menu item. Returns true if the value successfully changed. Does nothing by default.
  • i - Which text value to change.
  • s - The new value to change it to.
Gets a text value of the menu item. Returns true if it retrieved the value successfully and the value it retrieved. Does nothing by default.
  • i - Which text value to get.
Sets a number value of the menu item. Returns true if the value successfully changed. Does nothing by default.
  • i - Which number value to change.
  • value - The new value to change it to.
Gets a number value of the menu item. Returns true if it retrieved the value successfully and the value it retrieved. Does nothing by default.
  • i - Which number value to get.
Handles enabling and disabling of the menu item.
  • on - If true, enable the menu. Otherwise disable it.
  • bool MenuEvent(int mkey, bool fromcontroller)
Called when the menu this menu item belongs to gets a menu event and it's the selected menu item. Returns true if the event should have no further handling but does nothing by default.
  • mkey - The code for the menu key that was used.
  • fromcontroller - If true, the event was triggered by a controller.
Called when the menu this menu item belongs to gets a mouse event and it's the selected menu item. Returns true if the mouse should be captured after left clicking but does nothing by default.
  • type - The type of mouse event that occurred.
  • mx - The current x position of the mouse on the screen.
  • my - The current y position of the mouse on the screen.
Checks if the pressed key is the hot key for the menu item to be selected. Returns true if the hotkey matches. Does nothing by default.
  • c - The character code for the key pressed.
Calculates the width of the menu item. Returns the width.
Calculates the indent of the menu item to draw its values from. Returns the x offset.
  • int Draw(OptionMenuDescriptor desc, int y, int indent, bool selected)
Called every frame by the menu this menu item belongs to. Handles drawing with extra information about the menu as a whole. Returns the indent the menu item used.
  • desc - Contains the menu items the parent menu has and information related to displaying them.
  • y - The current y offset of the menu item.
  • indent - The indent of the menu itself.
  • selected - If true, this menu item is currently the focus of the menu.
Called when the menu this menu item belongs to initializes. Can be used to set up custom functionality when the menu is created.

OptionMenuItemOptionBase

Inherits from OptionMenuItem which inherits from MenuItemBase

Gets which entry the option menu item's CVar belongs to in the map data structure containing all the CVars and their values. Returns the entry number of the CVar.
Sets the option menu item's CVar value with the option menu item's current value.
  • Selection - Which entry corresponds to the CVar in the map data structure containing all the CVars and their values.
Checks if the option is currently grayed out. Returns true if it is.

OptionMenuSliderBaser

Inherits from OptionMenuItem which inherits from MenuItemBase

Returns the slider's value.
Sets the slider's value to the new number.
  • val - The number to set the slider to.

OptionMenuItemSliderReverbEditOption

Inherits fom OptionMenuSliderBase

Returns the formatted text to draw when displaying the reverb editing's text field value.

OptionMenuFieldBase

Inherits from OptionMenuItem which inherits from MenuItemBase

Returns the formatted text to draw when displaying the text field's value.

ListMenuItem

Inherits from MenuItemBase

Handles drawing the selector arrow when the list item is currently selected.
  • xofs - The x offset to use from the list item's current x position.
  • yofs - The y offset to use from the list item's current y position.
  • tex- The id of the texture to draw.

Examples

The following demonstrates how SpecialMissileHit works on MageStaffFX2. 

override int SpecialMissileHit (Actor victim)
{
	if (victim != target && !victim.player && !victim.bBoss)
	{
		victim.DamageMobj (self, target, 10, 'Fire');
		return 1;	// Keep going
	}
	return -1;
}

The following demonstrates how SpecialBlastHandling is performed with the Disc of Repulsion. 

override bool SpecialBlastHandling (Actor source, double strength)
{
    // Reflect to originator
    tracer = target;	
    target = source;
    return true;
}

The following demonstrates how CanCollideWith can be used: 

//--------------------------------------------------------------------------
// Disable collisions on some actors.
//--------------------------------------------------------------------------

override bool CanCollideWith(Actor other, bool passive)
{
    // Non-passive means the one moving into the other is performing the checks.
    if (!passive)
    {
        if (!other)		
            return false;
	
        // Pass through dead things. There is a difference between this and CORPSE.
        if (other.bKILLED)
            return false;
		
        // Solid obstacles must block.
        if (other.bSOLID && !other.bNONSHOOTABLE && !other.bSHOOTABLE)
            return true;
		
        if (other.bSHOOTABLE && (other.bFLOAT || other.bNOGRAVITY))
            return false;

        // Walk over 'em if they're small enough.
        if (other.Height <= 75 && other.Radius <= 60)
            return false;

        // Pass through different species of select types.
        if (other.GetSpecies() == 'CommonInfected')
            return false;
    }
    // We don't really care about others making the check.
    return true;
}

See also

Retrieved from "https://zdoom.org/w/index.php?title=ZScript_virtual_functions&oldid=52413"