User:Jekyll Grim Payne/ZScript classes overview

From ZDoom Wiki
Jump to navigation Jump to search
Note: This is a draft

ZScript classes overview

This is a generalized, visual overview of the classes used by ZScript that covers the main classes, their scopes, use and inheritance/dependencies.

RATIONALE: Hierarchical class list is unwieldy, humongous, and includes every actor from every game, which is unnecessary. The idea is to give a general overview of what handles what, only covering basic classes for everything (the classes that you have to inherit from to create something meaningfully new).

THOUGHTS: Presentation?

  • A list would be unhelpful and not visual enough.
  • A chart? (do we have extensions?)
  • Could a simple table work?

Play scope classes

Below is the list of all play-scoped base classes. This means that:

  • None of these classes must be spawned, given or otherwise initialized directly. They're base classes for other classes.
  • None of these classes can be replaced. This wouldn't make sense anyway, because they're never directly initialized/spawned.
  • All of these classes provide some kind of special functionality, and if you want to have access to that functionality in your class, your new class must inherit from one of these classes.
Object
Thinker StaticEventHandler
↓ ↓
↓ EventHandler
↓
↓ ↴
Actor VisualThinker
↓
↓ ↴ ↴ ↴
Inventory PlayerPawn MapMarker DynamicLight
↓
↓ ↴ ↴ ↴ ↴ ↴ ↴ ↴ ↴ ↴ ↴ ↴
StateProvider Ammo Armor Health Powerup PowerupGiver WeaponPiece WeaponHolder Key MapRevealer PuzzleItem FakeInventory
↓ ↓ ↓
↓ ↴ ↓ ↓ ↴
Weapon CustomInventory ↓ MaxHealth HealthPickup
↓ ↓
WeaponGiver ↓ ↴ ↴ ↴
BasicArmor HexenArmor BasicArmorPickup BasicArmorBonus

As a list

Used to handle events. Can be used to make something happen when an actor spawns, respawns, dies, is destroyed; a player spawns, and such. Has one method, RenderOverlay(), which runs in UI scope, others are play-scoped. Created at the start of game session and destroyed when the game is closed; not serializable (isn't written into save games).
Same as StaticEventHandler, but created at level start and destroyed at level end. Is serializable (written into save games).
The base class for all objects that "think", i.e. perform some kind of actions automatically while a level is loaded. Can utilize the Tick function to perform repeated actions.
A class dedicated to rendering special effects that can be used en masse. They serve as a middle ground between particles and Actors with notable differences.
The biggest and arguably most important play-scoped class. All "things" that are present in the world, have sprites associated with them and can interact with each other, have to be based on Actor. This is mainly true for any kind of prop or an enemy. More specific classes must be inherited from if specific functionality is required (such as creating a new item).
Classes inheriting from Actor have access to Action functions, Actor virtual functions and ZScript actor functions.
The actor controlled by players. Creating new player classes requires inheriting either from this directly, or from one of the predefined player classes, like DoomPlayer. New classes are added via the GameInfo block of the MAPINFO lump.
The base class for dynamic lights. Dynamic lights can be assigned via GLDEFS or dynamically attached with A_AttachLightDef. New dynamic lights with custom logic can be created based on this class, but also you can use A_AttachLight to dynamically spawn and modify a light.
The base class for actors that can be placed in other actors' inventories. Only PlayerPawn actors can pick up Inventory items in the world (this is handled in the item's Touch virtual function). However, all actors can hold items; even Inventory items can hold other items in them. Items can be given directly with GiveInventory, A_GiveInventory, GiveInventoryType and other methods. The process of receiving an item by an actor is handled in the item's TryPickup virtual. This class has a host of unique virtual functions.
New classes based on the Inventory class directly have the following functionality: they can be placed in actors' inventories; they can be placed in the world and players can pick them up by walking over them. If the item has the INVENTORY.AUTOACTIVATE flag, it'll execute its Use virtual function when picked up, which can be overridden to add custom behavior.
This class extends the Inventory class, giving items inheriting from it the ability to utilize PSprite to draw sprite animations on the screen.
A special type of Inventory item that has display sprite animations via PSprite, and has access to various special attack functions, such as A_FireBullets, A_FireProjectile, A_RailAttack and others. Can create sprite layers with A_Overlay. Needs A_WeaponReady to be called to be allowed to fire and/or switch weapons. Needs a valid SlotNumber assigned to be selectable (slots are handled throguh the WeaponSlots struct).
A class that is used to define alternate pickups for weapons. A weapon giver is affected by game modes like a weapon (for respawning, staying, and so on) but isn't, itself, a weapon. Instead, it gives the last weapon defined in its DropItem list. For this reason, a weapon giver should have only one entry in its DropItem list.
A variation of Inventory that can utilize Use and Pickup states for simple scripting. Is largely irrelevant in ZScript because the same functionality can be achieved in the regular Inventory class by overriding its Use virtual. However, has one unique feature that allows it to draw sprite animations with PSprite, much like weapons can.
Base class for ammo items, a special variation of Inventory items that are used by weapons when performing attacks. All custom ammo items must inherit from this.
Note, only actors that inherit from Ammo directly create a new ammo type. Further inheritance will create new pickups for the same ammo type. See Creating new ammo types for more information.
A new base ammo class can be created by inheriting from Ammo and then overriding its GetParentAmmo virtual function. This can be used if you want to add some specific behavior to all ammo pickups of all types in your project.
A special variation of Inventory that provides protection to the player. Mainly, utilizes the AbsorbDamage virtual function to handle protection (this virtual is not Armor-specific and is available to all Inventory items), but there's a lot of unique functionality involved. See SaveAmount and SavePercent properties.
This class must not be inherited from directly, it only serves as a base for other internal classes. New armor pickups must inherit from BasicArmorPickup or BasicArmorBonus.
A basic armor class that all players have in their inventory by default. Must not be used or given directly. Its values are modified by BasicArmorPickup and BasicArmorBonus when they're picked up.
A basic armor class that all players have in their inventory by default. Although players always have this, this special variation of armor is used only in Hexen due to its very unique (and not very flexible) armor system.
The base class for all armor pickups, like Doom's GreenArmor for example. To create a new armor pickup, inherit from this class. These items are never actually put in the player's inventory; instead, when picked up, they find BasicArmor in the player's inventory, modify its values (like savepercent, saveamount its inventory icon and such), after which the pickup disappears.
The base class for all armor bonuses, like Doom's ArmorBonus for example. The difference from BasicArmorPickup is that armor bonuses add to the armor the player already has, simply increasing its amount but not modifying its values.
Only if the player has never picked up a BasicArmorPickup before, the armor bonus will actually give them some armor first.
A dummy item that exists only to execute an attached map special when it's picked up. Is never placed in the inventory of the actor who picked it up, simply disappears on pickup.
A variation of Inventory that can heal the player when picked up, increasing their Health. Health items are never placed in the inventory, they use GiveBody to provide healing and then disappear. Doom's Stimpack and Medikit are examples of this. New health items can be created based on this class.
Same as Health, but always restores player's health to its maximum.
Same as Health, but instead of healing on pickup, it's placed in the player's inventory so it can be used later. Hexen's QuartzFlask is based on this.
A base class for keys, items that unlock locked doors/switches. The association between key classes and their lock numbers is defined in the LOCKDEFS lump. The default key types and their lock numbers are documented here. To make a door/switch locked, you need to use a specific locked special, for example Door_LockedRaise.
A base class for items that, when picked up, reveal the whole level in the player's automap. Doom's {{class|Allmap]] item is based on this.
A special Inventory item that doesn't have any function by itself. Puzzle items can be used with the UsePuzzleItem special to trigger special actions that depend on the presence of these items in a player's inventory. Essentially they act like keys that get removed once they have been used. The base PuzzleItem class is never used directly, but is used as the base class for predefined items (like Hexen's Clock gears). New puzzle items can be created; they need their Number property to be set up.
A variation of Inventory that is specifically set up to have a limited duration. Their effects are handled with the InitEffect, DoEffect and EndEffect virtual functions. Powerups cannot function as pickups, i.e. they can't be placed in the world directly. Instead, the PowerupGiver class is set up to function as a pickup, and it gives a related powerup when received. However, powerups can be given directly. If you want an item that provides some kind of a timed effect for scripting purposes and never actually spawns in the world, you don't need a PowerupGiver for it, it can be given directly instead.
The base class only defines functionality related to duration and counting it down, as well as applying a Powerup.Colormap to the player's screen (optionally). If you want to make a new item with a built-in time-limited effect but want to add custom functionality, you can inherit from Powerup directly and override its virtuals. However, if you need a specific type of powerup, use one of the predefined powerup types (they're listed on the Powerup page).
An item that gives a Powerup when picked up. The powerup it gives is specified through PowerupGiver's PowerupType property. If you want an item that provides some kind of a timed effect for scripting purposes and never actually spawns in the world, you don't need a PowerupGiver for it, the necessary Powerup can be given directly instead.
Used internally to track how many weapon pieces the player has picked up. Does not need to be used manually.
Items used to assemble a weapon, like the most powerful weapons in Hexen. Utilizes unique properties: WeaponPiece.Weapon tells which Weapon this pieces is for, and WeaponPiece.Number assigns the piece a number. When all existing pieces for the specified weapon are collected, the weapon is added to the player's inventory. The pieces themselves are not placed in the player's inventory; instead, they're tracked through a separate internal class, WeaponHolder.
When placed in the world, these actors render their sprite on the automap, but they don't actually render in the world. None of the base games use this, but this can be used in custom projects to mark places of interest, objectives, etc. New map markers can be created based on this class and placed manually. They can be modified, spawned and destroyed dynamically, just like any actor.

UI scope classes

Retrieved from "https://zdoom.org/w/index.php?title=User:Jekyll_Grim_Payne/ZScript_classes_overview&oldid=54684"