Classes:PowerupGiver

From ZDoom Wiki
Jump to navigation Jump to search
Note: Wait! Stop! Before you copy this actor's definition into your mod, remember the following things:
  1. You do not need to copy that actor, since it is already defined.
  2. In fact, it's not just useless, it's actually harmful as it can cause problems.
  3. If you want to modify it, or use a modified version, using inheritance is the way to go.
  4. The actor definitions here are put on the wiki for reference purpose only. Learn from them, don't copy them.
  5. There is only one exception: if what you want is changing Ammo capacity, you need to create a new type from Ammo.
Inventory
Actor type Internal Game MiniZDoomLogoIcon.png (ZDoom)
DoomEd Number None Class Name Inventory


Classes: InventoryPowerupGiver
 →ArtiFly
 →ArtiInvisibility
 →ArtiInvulnerability
 →ArtiInvulnerability2
 →ArtiSpeedBoots
 →ArtiTomeOfPower
 →ArtiTorch
 →BlurSphere
 →EnvironmentalSuit
 →Infrared
 →InvulnerabilitySphere
 →RadSuit
 →Scanner
 →ShadowArmor
 →Targeter

A PowerupGiver is used to give one of the existing powerups to the player using or picking up this item. PowerupGiver is never used directly, it is only used as a base class for many predefined inventory items (e.g. the partial invisibility sphere of Doom) or as a base to define new powerup pickups.

Note: If you're designing a custom powerup that is not meant to be spawned on the map, and instead is only meant to be given to the player directly (via scripts), defining a powerup giver for that powerup is unnecessary. Just make a powerup based on the Powerup class and use it directly. The sole function of a powerup giver is to be a pickup for a specific powerup; if there's no pickup, there's no need for a powerup giver.


Powerup givers can be either placed in the player's inventory and then activated manually (this is how they work in Heretic, for example), or, if they have the INVENTORY.AUTOACTIVATE flag, they are immediately consumed and give the player the Powerup associated with this powerup giver via the Powerup.Type property (this is how all Doom powerups work). Powerup givers utilize their Use function to give the player the powerup.

PowerupGiver and Powerup have a lot of identical properties, such as Powerup.Duration and others. When a PowerupGiver is consumed (picked up or used from inventory), it transfers its values to the Powerup it gives. Conversely, if PowerupGiver is not involved and the Powerup is given directly, the Powerup will utilize the values defined in it. As such, if you're creating a Powerup that can be given both directly and from a PowerupGiver, make sure the properties are defined properly in both classes.

Using in ZScript and DECORATE

There are two ways to define a powerup giver item:

  • Items that activate automatically when the player picks them up
To do this, set the INVENTORY.AUTOACTIVATE flag. Normally, the Inventory.MaxAmount property should be set to 0 in this case.
  • Items that go into the player's inventory and have to be used to do their work.
To do this, do not set the AUTOACTIVATE flag, and define Inventory.Amount and Inventory.MaxAmount as you would for any normal items.

Powerup givers support these special properties in addition to the basic Inventory properties:

  • Powerup.Color color [, alpha]
  • Powerup.Color BlueMap
  • Powerup.Color GoldMap
  • Powerup.Color GreenMap
  • Powerup.Color InverseMap
  • Powerup.Color RedMap
  • Powerup.Color None
Specifies the color and the opacity of the screen blend that is used when the powerup is active. Color is specified either as three integers (DECORATE only), an "RR GG BB" string or a color name from the X11R6RGB lump. Alpha is optional, and is a value between 0.0 and 1.0, defaulting to 0.33333 if not specified. Instead of specifying a color you can also use the predefined values BlueMap, GoldMap, GreenMap, InverseMap and RedMap. These do not set a blending value but instead use a predefined blend.
Using a color value of None for a PowerupGiver, results in having no screen blend. Setting an arbitrary color with zero alpha, instead, to override the powerup's own does not achieve the same task.
  • Powerup.Colormap [sourcecolor, ]destcolor
A generalization of the colormaps (which, counter-intuitively, are used with Powerup.Color), this creates a color ramp from the source color to the destination color. This uses decimal numbers for the red, green, blue components, ranging from 0.0 to 1.0, inclusive. If only one color is provided, then black (0.0, 0.0, 0.0) is used as the source color. For example, Powerup.Colormap 0.0, 0.0, 0.0, 1.0, 1.0, 1.0 and Powerup.Colormap 1.0, 1.0, 1.0 both create a grayscale, Powerup.Colormap 1.0, 1.0, 1.0, 0.0, 0.0, 0.0 creates the well known inverse map and Powerup.Colormap 1.0, 0.0, 0.0, 0.0, 1.0, 0.0 creates a red to green effect.
  • Powerup.Duration time
The length of time the power up will last in tics (1/35 of a second). If a negative duration is given, it will be taken as the duration in seconds (e.g., -30 is half a minute, while 30 is less than a second). The maximum duration is 0x7FFFFFFF, which corresponds to about two years of real time and can therefore safely be used for permanent powerups. Note, however, that due to the design of the TimeFreezer powerup, using such a duration value for this powerup is not recommended, as the engine will add two tics to the powerup's duration if the duration's value was even and the powerup was activated on an odd game tic, resulting in a signed overflow error. A value of 0x7FFFFFFD is safe to use in such a case.
  • Powerup.Mode mode
For some powerups which may behave in different ways, specify the mode. Currently affects Invulnerability, Invisibility and Environment protection.
  • Invulnerability modes: None and Reflective. "None" is invulnerability without any added effect. "Reflective" also makes all projectiles bounce off of the player while the powerup is in effect.
  • Invisibility modes: Cumulative, Fuzzy, Opaque, Stencil and Translucent. "Cumulative" allow multiple invisibility powerups of the same type to stack when active at the same time, adding their strength value together. "Fuzzy" uses the fuzz effect renderstyle, like that of the spectre. "Opaque" results in an opaque renderstyle, making the actor not invisible graphically speaking. "Stencil" uses the stencil renderstyle, showing just the shape. "Translucent" is merely a way of explicitly specifying the default invisibility mode.
  • Environment protection modes: Normal and Full. "Normal" is environment protection's default mode. "Full" is total-protection mode. It is similar to "Normal", but it also protects against the types of damaging floors that the "Normal" mode does not protect against, whether it is partial protection or not.
  • Powerup.Strength strength
The magnitude of a powerup's effect. Currently applies to Invisibility and Regeneration, as other powerups have unquantifiable effects or use predetermined fields such as DamageFactor.
  • Invisibility strength: determines how translucent the affected actor becomes. 0 is for opaque, and 100 is for fully invisible. Does not apply to "Fuzzy" mode.
  • Regeneration strength: determines the amount of health regenerated.
  • Powerup.Type power_name
The type of powerup given when item is used. This must be the name of an existing powerup. In DECORATE only, when passing the powerup's name, the "Power" prefix is optional and may be left out.
Note: If you want to display an icon in your HUD while the powerup is active, you must define Inventory.Icon for your Powerup. Defining it in PowerupGiver will only define the icon used while the giver is in your inventory, but it will not be displayed for the powerup itself when it's active.


ZScript definition

Note: The ZScript definition below is for reference and may be different in the current version of GZDoom.The most up-to-date version of this code can be found on GZDoom GitHub.
class PowerupGiver : Inventory
{
	
	Class<Actor> PowerupType;
	int EffectTics;		// Non-0 to override the powerup's default tics
	color BlendColor;	// Non-0 to override the powerup's default blend
	Name Mode;			// Meaning depends on powerup - used for Invulnerability and Invisibility
	double Strength;	// Meaning depends on powerup - currently used only by Invisibility
	
	property prefix: Powerup;
	property Strength: Strength;
	property Mode: Mode;
	
	Default
	{
		Inventory.DefMaxAmount;
		+INVENTORY.INVBAR
		+INVENTORY.FANCYPICKUPSOUND
		Inventory.PickupSound "misc/p_pkup";
	}
	
	//===========================================================================
	//
	// APowerupGiver :: Use
	//
	//===========================================================================

	override bool Use (bool pickup)
	{
		if (PowerupType == NULL) return true;	// item is useless
		if (Owner == null) return true;

		let power = Powerup(Spawn (PowerupType));

		if (EffectTics != 0)
		{
			power.EffectTics = EffectTics;
		}
		if (BlendColor != 0)
		{
			if (BlendColor != Powerup.SPECIALCOLORMAP_MASK | 65535) power.BlendColor = BlendColor;
			else power.BlendColor = 0;
		}
		if (Mode != 'None')
		{
			power.Mode = Mode;
		}
		if (Strength != 0)
		{
			power.Strength = Strength;
		}

		power.bAlwaysPickup |= bAlwaysPickup;
		power.bAdditiveTime |= bAdditiveTime;
		power.bNoTeleportFreeze |= bNoTeleportFreeze;
		if (power.CallTryPickup (Owner))
		{
			return true;
		}
		power.GoAwayAndDie ();
		return false;
	}
}

Examples

Nuvolachalk.png Note: This article lists no examples. If you make use of this feature in your own project(s) or know of any basic examples that could be shared, please add them. This will make it easier to understand for future authors seeking assistance. Your contributions are greatly appreciated.


DECORATE definition

Note: This is legacy code, kept here for reference only. DECORATE is still supported but no longer used by GZDoom. GZDoom internally uses the ZScript definition above.
ACTOR PowerupGiver : Inventory native
{
  Inventory.DefMaxAmount
  +INVENTORY.INVBAR
  +INVENTORY.FANCYPICKUPSOUND
  Inventory.PickupSound "misc/p_pkup"
}