Creating new inventory items (ZScript)

From ZDoom Wiki
Jump to navigation Jump to search

Inventory items are special actors based on the Inventory class (either directly, or through one of its child classes) that can be picked up and/or placed into a player's or monster's inventory.

All actors can hold items in them. In fact, even items can hold items in them, although it's normally not necessary. However, only the actors with the PICKUP flag in their definition can pick up items from the world — by default only PlayerPawn actors have this flag.

Base classes for items

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

Basic items that can be placed in an actor's inventory but don't come with any special behaviors.
Used for items that immediately increase the player's health upon being received (for example, Doom's Stimpack and Medikit).
Similar to Health, but instead of healing immediately, they're placed in the actor's inventory. They can then be manually used to perform healing. For example, Hexen's Quartz Flask.
Used for armor items. For example, Doom's GreenArmor and BlueArmor are based on this.
Note: armor items aren't placed in the actor's inventory directly. Instead, when being picked up, they modify the values of the special BasicArmor class (which all player actors always have automatically) and set is values (such as amount, absorption, icon, etc.), after which the armor pickup itself is removed.
Used for items that increase the amount of existing armor. Doom's ArmorBonus is an example of this.
Normally, only used in Hexen. A very specific variant of armor that consists of "pieces". It has a limited functionality, so it's almost never used in custom projects.
Ammunition items. Weapons usually need this to be able to fire.
Player weapons. They can display sprite animations on the player's screen and utilize various. They normally need Ammo to work.
A special base class for items hat increase the player's ammo capacity when picked up. Doom's Backpack is an example of this.
These items exist in the player's inventory for a limited duration and give some kind of a special effect while they do. Thins like invulnerability, invisibility and others would be based on Powerup.
Doom has a few powerups, such as radiation suit.
These items cannot be placed in the world directly. Powerups can only exist in somebody's inventory and give an effect while they're in inventory, but they can't function as an in-world pickup. In order to have a pickup for a powerup, you need a PowerupGiver.
These items function as a pickup for a Powerup. They can be placed in the world, and either go into player's inventory, or (if they have the Inventory.AUTOACTIVATE flag), are used automatically. Upon being used, they give a corresponding Powerup to the player, which then gives a specific effect.
Having a pickup for a powerup is not required. For example, if some kind of a powerup is only meant to be given directly (through scripts/functions) but never be picked up from the world, defining a PowerupGiver for it is not necessary.
Used for keys. Keys are coded to open locked doors, and those locks must be defined in the LOCKDEFS lump. Aside from that, keys don't have any special functionality.
Used for Puzzle items. Highly specific item that can be utilized in map puzzles; the map in question will need to use the UsePuzzleItem script special. Hexen makes some use of this.
Used for for weapons that must be assembled out of several pieces. The most powerful weapons in Hexen utilize this.
A special item that can be used to perform simple actions when it's being picke up and/or used. In ZScript this class is generally redundant, because all the necessary functionality can be performed through Inventory virtual functions, such as TryPickup and Use.
Dummy items that exist only in order to perform some kind of a map special when being picked up, but after that they're immediately removed.

Properties, states and sounds

The Inventory class and its subclasses come with unique properties. They're listed on the each class's individual page, linked above.

The two most commonly used properties are:

Most inventory items utilize only two states automatically:

  • Spawn - like with all actors, this is used when the item spawns in the world
  • Held - this is utilized while the item is in another actor's inventory. This can be used the same way as the DoEffect virtual function.

Items also utilize the HoldAndDestroy state when they're about to be removed from an actor's inventory (this state is used for 1 tic only), but it's not always called when the item is destroyed.

In addition to this, Inventory has a lot of unique properties and flags.

Pointers

Items have an owner pointer to the actor who is holding the item.

Inventory-related functions

The most commonly used functions that intereact with items are:

Virtual functions

Inventory classes utilize a wide array of unique virtual functions. Some of the most commonly used ones are:

  • Touch - called when an item is touched by another actor. As a result, the item may be picked up.
  • TryPickup - called when the item is actually being picked up.
  • Use - called when an item is being used (manually or automatically)
  • DoEffect - called every game tic when the item exists in another actor's inventory. Powerups use this to apply constant effects to their owner.
  • InitEffect and EndEffect - only used by the Powerup class to start and end its special effect. This is also where the player's colormap may be altered (for example, Doom's invulnerability orb does this).
  • OwnerDied - called when the item's owner is killed.
  • PickupMessage - called to determine what kind of PickupMessage the item will print. Can be modified to dynamically alter the message.

More functions can be found here.

Retrieved from "https://zdoom.org/w/index.php?title=Creating_new_inventory_items_(ZScript)&oldid=52214"