Classes:Inventory

From ZDoom Wiki
(Redirected from Inventory)
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: ActorInventory

 →Ammo
 →Armor
 →ArtiBlastRadius
 →ArtiBoostArmor
 →ArtiDarkServant
 →ArtiHealingRadius
 →ArtiPoisonBag
 →ArtiTeleport
 →ArtiTeleportOther
 →ArtiTimeBomb
 →BackpackItem
 →CustomInventory
 →DehackedPickup
 →DummyStrifeItem
 →FakeInventory
 →Health
 →HealthPickup
 →Key
 →MapRevealer
 →Powerup
 →PowerupGiver
 →PuzzleItem
 →QuestItem
 →ScoreItem
 →Weapon
 →WeaponGiver
 →WeaponHolder
 →WeaponPiece

Using in ACS

Actors that inherit from an Inventory class can be used as a parameter for the following functions:

Using in ZScript and DECORATE

Inventory is the base class for all items that can be picked up or placed into the inventory by other means. This class itself has is never used directly; its only purpose is to be a base class for other items. Any item derived directly from Inventory will be a functional item but won't produce any effects by itself. Such items may be used as counters or status markers.

Inventory items are special actors that can be picked up and/or placed into a player's or monster's inventory.

To define an inventory item you have to inherit from one of the predefined inventory classes:

  • Inventory - used for items without special function
  • PowerupGiver - used for pickups that give powerups to the user (either upon picking them up or upon using them from the inventory bar)
  • Health - used for items that immediately increase the player's health
  • HealthPickup - used for items that are placed in the inventory and give health when being used
  • BasicArmorPickup - used for armor items
  • BasicArmorBonus - used for items that increase the amount of armor
  • Ammo - used for ammunition items
  • Weapon - used for weapons
  • Key - used for keys
  • PuzzleItem - used for Puzzle items.
  • WeaponPiece - used for weapon pieces. These are used to create weapons that have to be put together from more than one item.
  • MapRevealer - used to give the player the automap
  • Backpack - used to increase the player's ammo carrying capacity.
  • CustomInventory - used to define items with simple DECORATE based behavior.
  • FakeInventory - used to replicate simple pickups like the ones defined with the old DECORATE definitions.

The Inventory base class defines the following properties which are available to all inventory subclasses:

  • Inventory.Amount value
Sets the amount of inventory items given by this item. Mostly used for item types that give larger quantities.
If the item in question is ammo and was dropped by another actor via A_DropItem or A_NoBlocking, its amount will be reduced by half by default. This can be changed by modifying the ammo's DropAmount property, or the DropAmmoFactor value in your custom skill definition.
  • Inventory.DefMaxAmount
Sets the maximum amount the player can carry of this item to the game's default. That is normally 16 for Heretic and 25 for the other games, but can be changed in MAPINFO through the GameInfo section.
  • Inventory.MaxAmount value
Sets the maximum amount the player can carry of this item.
  • Inventory.InterHubAmount value
Sets the maximum amount the player can keep of this item when traveling between hubs or non-hub levels. The default value of one replicates the original behavior of Heretic. This property replaces the deprecated INVENTORY.INTERHUBSTRIP.
  • Inventory.Icon sprite
Defines the icon this item uses when displayed in the HUD or status bar.
  • Inventory.AltHUDIcon sprite
Defines the icon this item uses when displayed in the alternate HUD. This is of use with keys, weapons, ammunition and artifacts.
  • Inventory.PickupMessage message
Defines the message that is printed when the player picks up this item. Strings from the LANGUAGE lump can be used by passing the string's identifier prefixed with '$'. For Health items, this can be overriden by the Health.LowMessage property.
  • Inventory.PickupSound sound
Defines the sound that is played when a player picks up this item.
  • Inventory.PickupFlash actor
Defines what actor should appear when the item is picked up; normally this would be used with the PickupFlash actor to make a flash appear as the player picks up the item. If this is not specified there will be no flash when the item is picked up.
  • Inventory.UseSound sound
Defines the sound that is played when a player uses this item. The sound is played on the item channel (CHAN_ITEM) with normal attenuation.
  • Inventory.RespawnTics value
Defines the time it takes until this item respawns (if respawn is enabled) in 1/35 of a second.
  • Inventory.GiveQuest value
Also give a quest item for controlling Strife's dialogs when picking up this one. value can be in the range of [1..31]
  • Inventory.ForbiddenTo classname[, classname2[, classname3[, ...]]]
Prevents players using one of the listed classes (use actor names, not Player.DisplayName) from picking up this type of inventory item. Note that unless playing in cooperative mode, a forbidden player will still try to pickup a Weapon or WeaponPiece for ammunition, as in Hexen. Use an empty string (e.g., Inventory.ForbiddenTo "") to clear an inventory item of inherited interdictions.
  • Inventory.RestrictedTo classname[, classname2[, classname3[, ...]]]
Prevents players not using one of the listed classes (use actor names, not Player.DisplayName) from picking up this type of inventory item. Note that unless playing in cooperative mode, a forbidden player will still try to pickup a Weapon or WeaponPiece for ammunition, as in Hexen. Use an empty string (e.g., Inventory.ForbiddenTo "") to clear an inventory item of inherited restrictions.


(Further, some of the subclasses have their own additional properties.)

The Inventory base class also defines some new flags:

  • INVENTORY.QUIET
When this item is picked up, its pickup sound is not played. Additionally, neither its pickup message nor the pickup palette flash are displayed.
  • INVENTORY.AUTOACTIVATE
This item activates automatically when being picked up.
  • INVENTORY.UNDROPPABLE
This item cannot be dropped once it has been picked up. Note that this also prevents the actor from being removed when ClearInventory or ClearActorInventory is called.
  • INVENTORY.UNCLEARABLE
This item cannot be removed by ClearInventory or ClearActorInventory, but can be dropped/tossed.
  • INVENTORY.INVBAR
This item is placed into the visible inventory when picked up.
  • INVENTORY.HUBPOWER
This item is kept when travelling between levels of the same hub.
  • INVENTORY.PERSISTENTPOWER
This item is kept when travelling between levels, even outside of a hub.
This item is taken away when traveling between hubs or single levels. Replaced by the more flexible Inventory.InterHubAmount property.
When being picked up a PickupFlash actor is spawned. This is the blue effect you can observe on Heretic and Hexen. This flag has been deprecated and it is recommended that you use the Inventory.PickupFlash property instead.
  • INVENTORY.ALWAYSPICKUP
This item is always picked up no matter whether the player can use it or not. This only applies to items that activate automatically.
The pickup sound is supposed to be played in surround mode. This flag does not actually have any effect.
  • INVENTORY.NOATTENPICKUPSOUND
The pickup sound is played with no attenuation, which means it is played at full volume and is heard clearly regardless of distance.
  • INVENTORY.BIGPOWERUP
Marks this item as a 'powerful' item which is controlled by the 'mega powerups respawn' dmflag option.
  • INVENTORY.NEVERRESPAWN
An item with this flag will never respawn in any circumstance.
  • INVENTORY.KEEPDEPLETED
This item will remain in the player's inventory bar even after the last one is used. If the item also has an inventory icon, it will be drawn darkened when the quantity is 0.
  • INVENTORY.IGNORESKILL
Normally, the amount of ammo picked up from an inventory item is doubled on the easiest and hardest skill levels. If this flag is set, the item will ignore the skill setting and only give the specified ammo amount. This flag is typically used on a magazine for reloading weapons so that only one round is inserted into the magazine per round of ammunition depleted from the main ammo pool.
  • INVENTORY.ADDITIVETIME
If set, when a player picks up a second powerup of this type before the first has worn off, the new powerup's duration will be added to the old, rather than overwriting it. For example, if a powerup has a duration of 60 seconds, and a player who currently has the powerup with 21 seconds left picks up a second one, normally the new powerup will override the old and the duration will be reset to 60 seconds. With this flag set, the duration would be extended to 81 seconds instead. This flag can either be set directly on a powerup or its giver.
  • INVENTORY.UNTOSSABLE
If set, the item cannot be tossed with the drop console command.
  • INVENTORY.RESTRICTABSOLUTELY
If set, the Inventory.ForbiddenTo and Inventory.RestrictedTo will prevent player classes not allowed to pick up a weapon from attempting to pick it up for ammo. This function prevents the item's TryPickupRestricted virtual from running.
  • INVENTORY.NOSCREENFLASH
Upon picking up an item with this flag, the associated pickup palette flash will not be displayed.
  • INVENTORY.TOSSED
An item with this flag is treated as being dropped.
  • INVENTORY.ALWAYSRESPAWN
An item with this flag will always respawn, regardless of the dmflag option. Note, this flag is different from the regular ALWAYSRESPAWN flag (without prefix): the latter one is for monsters, while this one is for items. In ZScript, where flag prefixes are not optional, you have to use +INVENTORY.ALWAYSRESPAWN, not +ALWAYSRESPAWN to make it work for Inventory items. Also, if dealing with a non-Inventory pointer, you will need to cast to Inventory first in order to access this flag.
  • INVENTORY.TRANSFER
An item with this flag will transfer all items in its inventory to the acquiring actor's own.
  • INVENTORY.NOTELEPORTFREEZE
Normally, a teleporting player loses the ability to move for about half a second before regaining it; an active power with this flag overrides this behavior.This flag can either be set directly on a powerup or its giver.
  • INVENTORY.NOSCREENBLINK
Powerups will never show the fade blinking every 1/4 of a second, which serves as an expiration warning. Useful when using scripting to allow special effects to happen without the blinking causing visual interference.
  • INVENTORY.ISHEALTH
An item with this flag set does not spawn if the sv_nohealth console variable is true.
  • INVENTORY.ISARMOR
An item with this flag set does not spawn if the sv_noarmor console variable is true.


To create items that automatically activate when being picked up, add the +INVENTORY.AUTOACTIVATE flag. Normally, in this case their amount is set to 0 (which still allows to pick them up).

Methods

Static

Dynamic

Makes a thing visible again and calls DoRespawn().
Sets the SPECIAL flag to true and resets the NOGRAVITY flag to false if it's false by default for the actor, then moves it to its Spawn state.
Like A_RestoreSpecialThing2, but also plays misc/respawn and spawns teleport fog on top of the respawning actor.
  • bool DoRespawn()
Resets the item's position to its original spawn position. Returns true if the respawn was successfull (by default always returns true).
  • void BecomeItem()
Lets this actor know that it's about to be placed in an inventory. This is called in AttachToOwner right before using AddInventory to place the item into the player's inventory.
  • void BecomePickup()
Lets this actor know it should wait to be picked up. Removes its owner if it has one, and resets all of the values that are necessary for it to become a pickup. This is called in CreateTossable() when the player is dropping an item from their inventory.
  • void GiveQuestItem (Actor toucher)
Gives the toucher a quest item based on the value of this item's GiveQuest property.
  • protected bool GoAway()
Returns true if you must create a copy of this item to give to the player or false if you can use this one instead. Used in CreateCopy().
  • protected void GoAwayAndDie()
Calls GoAway(), and if that returns false, unlinks the item from the world and sets its state to HoldAndDestroy.
  • clearscope Inventory NextInv() const
Returns a pointer to the next item after this one in the list if the INVBAR flag is set; otherwise returns a pointer to self.
  • clearscope Inventory PrevInv()
Returns a pointer to the previous item after this one in the list if the INVBAR flag is set; otherwise returns a pointer to self.

Virtual

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.
  • void UseAll(Actor user)
Called when the item's owner uses the "use all inventory items" key.
  • user - The actor trying to use the item.
  • void DoPickupSpecial(Actor toucher)
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.
  • Inventory CreateTossable(int amt = -1)
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.
  • void PreTravelled()
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.
  • void Travelled()
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).
  • void Hide()
Called when an item that respawns is set to hide after being picked up. This is not called if ShouldStay returns true.
  • bool ShouldRespawn()
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.
  • double GetSpeedFactor()
Returns the speed modifier the item applies to the owner.
  • bool GetNoTeleportFreeze()
Returns whether or not the owner should be frozen briefly after teleporting. Returning true tells the owner not to freeze.
  • ui void AlterWeaponSprite(VisStyle vis, in out int changed)
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.
  • color GetBlend()
Returns the color of the screen blend the item applies. Mainly used with power ups.
  • bool SpecialDropAction(Actor dropper)
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.
  • void ModifyDropAmount(int dropamount)
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.
  • void SetGiveAmount(Actor receiver, int amount, bool givecheat)
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.

ZScript definition

ZScript definition of the Inventory class is very long and can be found on GZDoom GitHub repository.


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 Inventory native
{
  Inventory.Amount 1
  Inventory.MaxAmount 1
  Inventory.InterHubAmount 1
  Inventory.UseSound "misc/invuse"
  Inventory.PickupSound "misc/i_pkup"
  Inventory.PickupMessage "$TXT_DEFAULTPICKUPMSG"
  
  action native A_BFGSound();
  action native A_CheckForReload(int counter, state label, bool dontincrement = FALSE);
  action native A_CheckReload();
  action native A_ClearReFire();
  action native A_CloseShotgun2();
  action native A_CustomPunch(int damage, bool norandom = FALSE, int flags = CPF_USEAMMO,
                              class<Actor> pufftype = "BulletPuff", float range = 0, float lifesteal = 0,
                              int lifestealmax = 0, class<BasicArmorBonus> armorbonustype = "ArmorBonus",
                              sound MeleeSound = "", sound MissSound = "");
  action native A_FireBFG();
  action native A_FireBullets(float spread_xy, float spread_z, int numbullets, int damageperbullet,
                              class<Actor> pufftype = "BulletPuff", int flags = 1, float range = 0,
                              class<Actor> missile = "", float Spawnheight = 32, float Spawnofs_xy = 0);
  action native A_FireCGun();
  action native A_FireCustomMissile(class<Actor> missiletype, float angle = 0, bool useammo = TRUE,
                                    float spawnofs_xy = 0, float spawnheight = 0, int flags = 0,
                                    float pitch = 0);
  action native A_FireMissile();
  action native A_FireOldBFG();
  action native A_FirePistol();
  action native A_FirePlasma();
  action native A_FireRailgun();
  action native A_FireRailgunLeft();
  action native A_FireRailgunRight();
  action native A_FireShotgun();
  action native A_FireShotgun2();
  action native A_FireSTGrenade(class<Actor> grenadetype = "Grenade");
  action native A_GunFlash(state flash = "", int flags = 0);
  action native A_JumpIfNoAmmo(state label);
  action native A_Light(int extralight);
  action native A_Light0();
  action native A_Light1();
  action native A_Light2();
  action native A_LightInverse();
  action native A_LoadShotgun2();
  action native A_Lower();
  action native A_OpenShotgun2();
  action native A_RailAttack(int damage, int spawnofs_xy = 0, bool useammo = TRUE, color color1 = "",
                             color color2 = "", int flags = 0, float maxdiff = 0,
                             class<Actor> pufftype = "BulletPuff", float spread_xy = 0, float spread_z = 0,
                             float range = 0, int duration = 0, float sparsity = 1.0, float driftspeed = 1.0,
                             class<Actor> spawnclass = "none", float spawnofs_z = 0, int spiraloffset = 270,
                             int limit = 0);
  action native A_RailWait();
  action native A_Raise();
  action native A_ReFire(state flash = "");
  action native A_ResetReloadCounter();
  action native A_RestoreSpecialDoomThing();
  action native A_RestoreSpecialPosition();
  action native A_RestoreSpecialThing1();
  action native A_RestoreSpecialThing2();
  action native A_Saw(sound fullsound = "weapons/sawfull", sound hitsound = "weapons/sawhit", int damage = 2,
                      class<Actor> pufftype = "BulletPuff", int flags = 0, float range = 0,
                      float spread_xy = 2.8125, float spread_z = 0, float lifesteal = 0, int lifestealmax = 0,
                      class<BasicArmorBonus> armorbonustype = "ArmorBonus");
  action native A_WeaponReady(int flags = 0);
  
  States
  {
  HideDoomish:
    TNT1 A 1050
    TNT1 A 0 A_RestoreSpecialPosition
    TNT1 A 1 A_RestoreSpecialDoomThing
    Stop
  HideSpecial:
    ACLO E 1400
    ACLO A 0 A_RestoreSpecialPosition
    ACLO A 4 A_RestoreSpecialThing1
    ACLO BABCBCDC 4
    ACLO D 4 A_RestoreSpecialThing2
    Stop
  Held:
    TNT1 A -1
    Stop
  HoldAndDestroy:
    TNT1 A 1
    Stop
  }
}