Classes:PlayerPawn

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.
Player pawn
Actor type Internal Game MiniZDoomLogoIcon.png (ZDoom)
DoomEd Number None Class Name PlayerPawn


Classes: PlayerPawn
 →DoomPlayer
  →ChexPlayer
 →ClericPlayer
 →ChickenPlayer
 →FighterPlayer
 →HereticPlayer
 →MagePlayer
 →PigPlayer
 →PlayerChunk
 →StrifePlayer

PlayerPawn is the base class for player actors. By inheriting from it you can create custom player classes.

Using in ZScript and DECORATE

The PlayerPawn base class defines the following properties which are available to all player subclasses:

  • Player.AirCapacity value
Sets the air supply for the player class. This acts as a multiplier for the level's air supply value. A value of 2 will double the air supply, for instance. A value of 0 or less means the air supply is infinite, and thus the player class cannot drown.
Default is 1.0.
  • Player.AttackZOffset value
The height offset (in Doom map pixels) from the center of the player at which his attacks are fired. Scales according to crouched height.
Default is 8.
  • Player.ClearColorSet number
Removes a color set from the player class. This allows to remove color sets inherited from a parent class.
  • Player.ColorRange start, end
Defines the color range in which to translate the player's sprite.
Default is no translation (0, 0).
  • Player.ColorSet number, name, start, end, color [...]
Defines a preset color set for the player class. The number must be unique. The name is used to identify the preset in the player setup menu. The start and end parameters determine the translation for the ColorRange, and the color parameter is used as the visual identifier for the set in the scoreboard.
Up to six additional color ranges can be defined, each with four parameter for range_start, range_end, first_color and last_color, in this order. See StrifePlayer for an example.
  • Player.ColorSetFile number, name, table, color
Defines a preset color set for the player class. The number must be unique. The name is used to identify the preset in the player setup menu. The translation is indicated by a translation table lump using the format defined by Hexen (TRANTBL0 to TRANTBLD). The color parameter is used as the visual identifier for the set in the scoreboard.
  • Player.CrouchSprite sprite
Defines the sprites for when your skin is crouching. If you don't define them your sprite will shrink half its vertical size to show it is crouching. For the crouch sprites you have to define all frames apart from the dying and gib frames. Please note that there is no "Crouch" state that is definable for players, as the engine would not support such a feature. Players need to be able to move seamlessly between crouching and standing during any given state (See, Missile, Melee, etc.) without losing their place in that state, hence there can be no generic "Crouch" state to jump to.
  • Player.DamageScreenColor color[, intensity[, damagetype]]
The color the player's display turns when the player is in pain. This can be specified as three hex values for R, G, B respectively, or as a literal color name (e.g. "blue"). If this isn't defined, it defaults to red. The intensity of the flash can be scaled from 0.0 to 1.0. If a damagetype is specified, the color only applies when the last damage type received is that type. If there is no color specified for a given damage type, it defaults to what is set without one.
  • Player.DisplayName string
This is the identification string of the player class. It is used in addplayerclass KEYCONF command, in playerclass console variable, in skin definitions, and in menus. Each player class used in game must have an unique display name!
  • Player.Face string
This is the three-character prefix that will be used by the status bar face display built into DOOM and by custom status bars that define faces; note that with custom status bars in SBARINFO, faces can be used in all games (not just DOOM), provided the necessary graphics are supplied. This is like the face property of S_SKIN but for player classes. To include a status bar face you must put the 3 first letters of the sprite for the face here. For example, if one of the animations was BUGST00 you would put Face "BUG".
When deciding which face to use, the engine checks for STF**** (DOOM games only), the SBARINFO face, the current player class face, the face of the currently loaded skin and finally the morphed animal player class face; whichever it finds last "wins".
The engine also maintains faces across morphing; for example, if you were playing deathmatch in HeXen and have loaded an SBARINFO which defines faces for the fighter and also a DECORATE script containing a custom morph attack weapon that changes your enemy into a dog and includes dog face graphics; if you are turned into a dog, the status bar would change to show your face as a dog and turn back to a human again when you unmorph.
  • Player.FallingScreamSpeed value_min, value_max
When a player is falling within this range of speeds, they will play *falling sound.
Default is (35.0, 40.0).
  • Player.FlechetteType string
Type of fléchette used by this player class.
  • Player.FlyBob value (New from 4.11.0)
A multiplier for how much the players' view and height bobs up and down when they are flying and the fviewbob console variable is on.
Default is 1.0.
  • Player.ForwardMove value[, value-run]
Speed modifier for forward/backward movement. The value is for walking and value-run is for running.
Default is 1 for both values. The default run speed is double the walking speed, so Player.ForwardMove 1, 0.5 would disable running.
  • Player.GruntSpeed value
The minimum speed a player must be falling at the time of landing to play *grunt sound.
Default is 12.0.
  • Player.HealRadiusType string
The nature of the healing effect the player offers to his allies in cooperative multiplayer when using a Mystic Ambit Incant.
Value can be Health, Armor or Mana. Default is Health.
The player's armor class values in Hexen. All values must be a multiple of five (they are divided by five when displayed on the HUD). Base value is the player class's minimum, all other values are the increases gained by picking up the corresponding Hexen armor item.
  • Player.InvulnerabilityMode string
The secondary effect an invulnerability powerup will have on the player, in addition to the invulnerability and display gimmick.
Ghost will make the player phase in an out of ghost mode rapidly; Reflective will make the player reflect projectile attacks.
Default is unnamed. To obtain the default effect, just make sure the line is not present.
  • Player.JumpZ value (fixed point)
The player's jump speed. The player's jump height in normal gravity is (value × (value + 1)) / 2). A player can still climb their MaxStepHeight while jumping, allowing to reach heights higher than indicated purely by the jump height. For example with the default values, a player can climb a height of up to 60 map units: 36 from jump, 24 from step.
Default is 8.0.
  • Player.MaxHealth value
Default is 100.
The maximum health reachable by using normal health items.
  • Player.MorphWeapon weapon
Sets the weapon the player will use when morphed to this class.
  • Player.MugShotMaxHealth value
Defines the value that is considered to be max health for the status bar mugshot. Negative values use the player's max health as the mug shot max health, zero (default value) uses 100 as the mug shot max health, and positive values are used directly as the mug shot max health.
  • Player.Portrait string
Replaces the player portrait in the class selection menu to show a customized image, much like Hexen's player classes.
  • Player.RunHealth value
The minimum health the player can have and still be able to run. (This is normally 16% for Strife)
Default is 0.
  • Player.ScoreIcon sprite
The icon visible next to the player's name on multiplayer scoreboard.
  • Player.SideMove value [value-run]
Speed modifier for left/right movement. The value is for walking and value-run is for running.
Default is 1 for both values. The default run speed is double the walking speed, so Player.SideMove 1, 0.5
would disable side-running.
NOTE: Side movement running speed is actually 4/5ths forward running speed, and the side walk speed is 24/25ths forward walk.
  • Player.SoundClass string
The sound class used by SNDINFO's $playersound command.
Default is "player".
  • Player.SpawnClass spawnclass
This is the filter for spawning things in a map. The spawnclass can be one of Any, Fighter, Cleric, Mage or a number between 1 and 16. 1 is synonymous with Fighter, 2 with Cleric and 3 with Mage.
  • Player.StartItem classname [amount]
Adds an item to player's start inventory. First weapon added is the weapon selected at start.
Note: The initial startitem list is never inherited and must be specified in full for each player class.
  • Player.TeleportFreezeTime value
The time in tics the player remains immobile after teleportation. If this is 0 or less, or the player has at least one active powerup which has the INVENTORY.NOTELEPORTFREEZE flag set, this behavior is overridden, and as a result, the player does not become immobile after teleportation.
Default is 18.
  • Player.UseRange range
Determines how far away a player class can activate lines or objects with the +use command.
Default is 64.0.
  • Player.ViewBob value
A multiplier for move and still bob. Determines how far the player's camera bobs up and down. Higher values increase the bob range.
Default is 1.0.
  • Player.ViewBobSpeed value (New from 4.11.0)
A multiplier for camera bobbing speed while moving. Determines how quickly the camera moves while bobbing (and thus the frequency of bobbing). Higher values make the camera move through the bob range more slowly.
Default is 20.0.
  • Player.ViewHeight value
Specifies how high above the floor the player's eyes are.
Default is 41.0.
  • Player.WaterClimbSpeed value (New from 4.11.0)
The speed at which the player can climb walls when swimming.
Default is 3.5.
  • Player.WeaponSlot slot, weapon1[, weapon2, weapon3, ...]
Assigns the specified weapons to the given slot number for this player class. slot can be any single digit from 0 - 9. This is followed by a comma-separated list of each weapon's class name that should be assigned to that slot. If there is more than one weapon assigned to a given slot, the player can cycle between them by repeatedly pressing the slot button. For other ways to assign weapons to slots, see weapon slots.

PlayerPawn-specific flags also exist:

  • PLAYERPAWN.NOTHRUSTWHENINVUL
Player is not thrusted by attacks when invulnerable.
  • PLAYERPAWN.CANSUPERMORPH
If this flag is given to a player morph, the morphed player recieves a tome of power if they are attempted to be morphed again. This is used by the chicken morph to reproduce the original behavior of Heretic and its "super chickens".
  • PLAYERPAWN.CROUCHABLEMORPH
Enables crouching for morphed player classes.
  • PLAYERPAWN.WEAPONLEVEL2ENDED
Signals that an enhanced weapon power has expired, so the code responsible switches the player's powered-up weapon back to its normal form.
This flag was introduced as part of a solution to make switching from the powered-up weapon to its normal form seamless upon the power's expiration, so it may not be used in user code.


ZScript definition

The full ZScript definition is too long for this page. Please find the full definition on GZDoom Github.

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 PlayerPawn native
{
  Health 100
  Radius 16
  Height 56
  Mass 100
  Painchance 255
  Speed 1
  +SOLID
  +SHOOTABLE
  +DROPOFF
  +PICKUP
  +NOTDMATCH
  +FRIENDLY
  +SLIDESONWALLS
  +CANPASS
  +CANPUSHWALLS
  +FLOORCLIP
  +WINDTHRUST
  +TELESTOMP
  +NOBLOCKMONST
  Player.AttackZOffset 8
  Player.JumpZ 8
  Player.GruntSpeed 12
  Player.FallingScreamSpeed 35, 40
  Player.ViewHeight 41
  Player.UseRange 64
  Player.ForwardMove 1,1
  Player.SideMove 1,1
  Player.ColorRange 0,0
  Player.SoundClass "player"
  Player.DamageScreenColor "ff 00 00"
  Player.MugShotMaxHealth 0
  Player.FlechetteType "ArtiPoisonBag3"
  Player.AirCapacity 1
  Obituary "$OB_MPDEFAULT"
}

Client Prediction (ZScript only)

Certain actions the player takes can have prediction when playing in a multiplayer game. This means that the code is being ran on the client's end but has not yet been verified with all other players in the game currently. This is done to help the player feel they have better control over their character than having to wait for verification to perform an action. Not all actions should be predicted, however (e.g. activating a sector's action if the game hasn't verified the player is actually there yet). You can check if a player is currently predicting by seeing if the CF_PREDICTING flag is set in their PlayerInfo pointer:

   player.cheats & CF_PREDICTING

This flag is set and unset internally. Below are special actions that happen while predicting:

  • 3D floor, sector, fake sector, thing, and most line actions won't be triggered when hit
  • When teleporting
  • Teleport fog will not be spawned at either the origin spot or the destination
  • If there are multiple teleport destinations, the spot chosen will not be random
  • Enemies will not be telefragged
  • The player's idle state won't be set when they stop moving in general
  • The player's run state won't be set when they start moving
  • If the player lands from a fall, only the camera bobbing will be applied (other actions like fall damage and grunting aren't)
  • The player won't call their items' DoEffect() virtual
  • Poison damage won't tick
  • HitWater() will not spawn a splash and always returns false
  • Collision damage functionality outside of SKULLFLY will not be applied to things the player hits
  • Teleport line specials can still be used
  • Grunt sounds will not be played while bouncing off a wall on ice
  • The player's jump sound won't be played
  • If the player is falling and hits water, their fall scream won't be stopped if they have one
  • If the player presses fly up while they have the flight artifact, it won't automatically activate
  • Certain player functions are not called
  • MorphPlayerThink()
  • CheckUse()
  • CheckUndoMorph()
  • TickPSprites()
  • CheckPoison()
  • CheckDegeneration()
  • CheckAirSupply()
  • Palette flashes won't be modified (e.g. taking damage, picking up an item up)
  • PowerSpeed won't do its visual effects
  • PowerTimeFreezer won't tick

Voodoo dolls

A voodool doll is a vanilla Doom effect that is supported by source ports, including ZDoom. The effect occurs when multiple player starts for the same players are placed in the map editor. When this is done, multiple PlayerPawn actors are created bound to the same PlayerInfo struct. The player can only directly control the first PlayerPawn spawned for them, while the other PlayerPawn actors will be the voodoo dolls.

Damage and health are transferred between the voodoo dolls and the original PlayerPawn actor. When a voodoo doll receives an inventory item, that item is given to the original PlayerPawn instead.

Voodoo dolls have been commonly used in older map formats (including vanilla) to create various effects. They're described in more detail on the DoomWikiLogoIcon.pngDoom Wiki.

Scripting concerns

Voodoo dolls pose certain concerns in ZScript. When performing operations on PlayerPawn actors, voodoo dolls will be included in the list of those actors and can cause certain scripts to not function correctly, if not accounted for. For example:

  • PlayerSpawned() event is triggered for all PlayerPawn actors, including voodoo dolls.
  • PostBeginplay() of a PlayerPawn will be called for each voodoo doll present on the map for the same player. For example, if this override is used to give the PlayerPawn some items, they'll be given multiple times for each of the PlayerPawns.

Checking for voodoo dolls

ZScript can check if a specific PlayerPawn is a voodoo doll by accessing its PlayerInfo struct, and then checking if the mo pointer of that struct is pointing to the specified PlayerPawn. As such, it's possible to use a simple static function to run the check:

static bool IsVoodooDoll(PlayerPawn mo) 
{
	return !mo.player || !mo.player.mo || mo.player.mo != mo;
}

This will return true if the PlayerPawn instance provided in the function's first argument is a voodoo doll.