A_Overlay
| Note: A_Overlay can ONLY be called either from a PlayerPawn state, or from a StateProvider state handled by a PSprite, such as CustomInventory's Use or Weapon's Ready/Fire/etc. If there's a need to create an overlay in any other context, use <pointer to a PlayerPawn>.player.SetPSprite. |
bool A_Overlay(int layer, statelabel start = null, bool nooverride = false)
Usage
This function is a considerably expanded version of A_GunFlash, allowing users to create multi-layer weapon animations.
Note, although this functions is defined in Actor, its behavior is tied to the PSprite class. As such, it can only be utilized in those classes that have access to PSprite and can create new instances of it, which includes PlayerPawn and classes based on StateProvider: Weapon and CustomInventory. In case of StateProvider, this function can only be called in states that are already being drawn with the help of a PSprite, i.e. the states that are designed to draw sprites on the screen (so, for example, you can use it in the weapon's Ready/Fire/Hold and similar states, but not its Spawn states). For manually creating a new layer without A_Overlay, see PlayerInfo PSprite methods.
Regular actors, Inventory items and such can NOT utilize overlays or PSprite in any way.
Calling A_Overlay creates a new sprite layer (which is handled by a new instance of PSprite) and sends that layer into the specified state sequence. That state sequence will be played on a separate layer. Note that you can create multiple layers that utilize the same state sequence (thus, independently showing multiple versions of the same animation on different layers).
To specify different behaviors for overlays, use A_OverlayFlags.
Parameters
- int layer
- The number of the layer to create.
- Any positive or negative number within the [-2147483647, 2147483647] range, with the exception of 0, can used for a layer ID. Lower numbers are drawn below higher numbers. Aside from numbers, the following constants for specific IDs already exist in GZDoom, and some of them should not be reused:
- PSP_STRIFEHANDS (-1) — Used by the A_ItBurnsItBurns function designed for Strife. This should never be used in custom overlays or passed to A_Overlay due to special hardcoded quirks.
- PSP_WEAPON (1) — The main layer used by the Weapon class. This should never be passed to A_Overlay. This layer should also not be destroyed, because that will make the weapon unusable and also make it impossible to switch to another weapon.
- PSP_FLASH (1000) — Used by A_GunFlash. This layer ID can be freely used for other purposes. Also, using A_GunFlash is not obligatory, and a custom muzzle flash effect can be drawn on any layer using A_Overlay.
- PSP_TARGETCENTER (2147483645)
- PSP_TARGETLEFT (2147483646)
- PSP_TARGETRIGHT (2147483647)
- These three constants are used by PowerTargeter. Should not be used in custom classes.
- In addition, instead of an explicit number or constant OverlayID can be passed as the layer number to make the given function act on the layer utilized by the state from which it's being called. This shouldn't be done with A_Overlay, but can be used with functions like A_OverlayFlags.
- statelabel start
- The name of the state label that the overlay should draw.
- bool nooverride
- If set to
true, the function will not create an overlay if the specified layer already exists.
Examples
This is a generic example of creating a custom muzzle flash layer (instead of using the built-in A_GunFlash) and then modifying its appearance:
Fire:
WEAP B 2
{
A_FireBullets(5, 3.5, 1, 10);
A_Overlay(-100, "MuzzleFlash"); //make a custom muzzle flash layer below the gun
}
WEAP CDE 2;
WEAP A 5 A_ReFire;
goto Ready;
MuzzleFlash:
MUZL A 2 bright
{
A_OverlayFlags(OverlayID(), PSPF_RENDERSTYLE|PSPF_FORCEALPHA, true); //enable renderstyle and alpha change
A_OverlayRenderstyle(OverlayID(), STYLE_ADD); //set additive renderstyle
A_OverlayAlpha(OverlayID(), frandom(0.8, 1.0)); //randomize alpha
}
stop;