zdoom/qzdoom
0
0
Fork 0
mirror of https://github.com/ZDoom/qzdoom.git synced 2024-11-24 13:01:47 +00:00
Code Issues Projects Releases Packages Wiki Activity
qzdoom/docs/thingdef_doc.txt

598 lines
30 KiB
Text
Raw Normal View History

Directory restructuring to make it easier to version projects that don't build zdoom.exe. SVN r4 (trunk)
2006-02-24 04:48:15 +00:00
Examples for actor definitions
------------------------------
1) a complete definition from scratch:
ACTOR ZombieMan 3004
{
Health 20
Radius 20
Height 56
Speed 8
PainChance 200
MONSTER
+FLOORCLIP
SeeSound grunt/sight
AttackSound grunt/attack
PainSound grunt/pain
DeathSound grunt/death
ActiveSound grunt/active
Obituary "%o was killed by a zombieman."
DropItem Clip
Damage 4
States
{
Spawn:
POSS AB 10 A_Look
Loop
See:
POSS AABBCCDD 4 A_Chase
Loop
Missile:
POSS E 10 A_FaceTarget
POSS F 8 A_BulletAttack
POSS E 8
Goto See
Pain:
POSS G 3
POSS G 3 A_Pain
Goto See
Death:
POSS H 5
POSS I 5 A_Scream
POSS J 5 A_Fall
POSS K 5
POSS L -1
Stop
XDeath:
POSS M 5
POSS N 5 A_XScream
POSS O 5 A_Fall
POSS PQRST 5
POSS U -1
Stop
Raise:
POSS KJIH 5
Goto See
}
}
2) an actor which inherits from an existing one:
ACTOR PlasmaZombie : ZombieMan 9600
{
Health 40
DropItem Cell
MissileType PlasmaBall
States
{
Missile:
POSS E 10 A_FaceTarget
POSS F 5 A_MissileAttack
POSS E 5 A_FaceTarget
POSS F 5 A_MissileAttack
POSS E 5 A_FaceTarget
POSS F 5 A_MissileAttack
Goto See
}
}
(this is a zombie which fires 3 plasma bullets when attacking)
3) an actor which uses SKIP_SUPER
ACTOR DeadZombieMan : ZombieMan 18
{
SKIP_SUPER
Spawn Parent Death+4
}
(this actor doesn't inherit anything from its parent - it just uses
some of its states.)
Syntax:
-------
ACTOR classname [ : parentclassname] [doomednum]
{
properties
flags
...
}
classname: The name this new actor is referenced by in the game
parentclassname: (optional) The name of a parent class this new actor
inherits its attributes from.
doomednum: Editor number for this actor (optional)
List of properties:
===================
SKIP_SUPER reinitializes the actor as if it has no parent
This can be used to have access to the parent's
states without inheriting its attributes. See
3) above for an example.
SPAWNID value defines the spawn ID to be used with Thing_Spawn
and its derivates.
HEALTH value defines the health a monster starts with
Default is 1000
REACTIONTIME value Time in tics (1/35 seconds) a monster needs
to attack back. There is normally no need to
change this value.
Default is 8
PAINCHANCE value Probability of entering the pain state.
255=always, 0=never
Default is 0
DAMAGE value For a projectile defines the damage it inflicts
upon impact. The formula is random(1,8)*damage
or (random(1,4)*damage if STRIFEDAMAGE is set.
This also defines the damage for actors which
attack like the Lost Soul. The formula for this
is random(1,8)*damage.
DAMAGE is also used to define how many bullets
are fired by the generic hitscan attack function
A_Bulletattack.
Default is 0
SPEED value Defines how fast an actor moves. For projectiles
this is the distance it moves. For monsters it
defines the size of one step done in A_Chase.
Default is 0.
RADIUS value Defines the radius of this actor.
Default is 20.
HEIGHT value Defines the height of this actor
Default is 16.
MASS value Defines the mass of this actor.
The larger the mass the less an actor moves when
being thrust by damage.
Default is 100.
XSCALE value Defines the X-scaling for this actor.
Range is [0.0, 4.0].
Default is 1.0
YSCALE value Defines the Y-scaling for this actor.
Range is [0.0, 4.0].
Default is 1.0
SCALE value Combines XScale and YScale
Range is [0.0, 4.0].
Default is 1.0
SEESOUND name Defines the sound the actor makes when it sees
the player (for monsters) or when a projectile
is spawned.
ATTACKSOUND name Defines the sound the actor makes when attacking.
PAINSOUND name Defines the sound the actor makes when in pain.
To hear this sound A_Pain has to be called.
DEATHSOUND name Defines the sound the actor makes when dying
or when a projectile explodes.
ACTIVESOUND name Defines the sound the actor makes when active.
MELEESOUND name Defines the sound the actor makes when doing
a melee attack in A_MeleeAttack. Note that
several original attack functions which have
such a sound use a hard coded reference (e.g.
A_TroopAttack uses imp/melee)
RENDERSTYLE type Defines how this actor is rendered. Useful values are:
NONE - actor is invisible
NORMAL - actor is visible and not translucent
FUZZY - like the Spectre in Doom
TRANSLUCENT - actor is translucent.
ADD - actor uses additive translucency.
Default is NORMAL
ALPHA value defines the opacity/intensity for render styles
TRANSLUCENT and ADD.
Range is [0.0, 1.0]
Default is 1.0
DEATHHEIGHT value Defines the height this actor has after dying.
Default is 1/4 of the original height
BURNHEIGHT value Defines the height this actor has after dying by fire.
Default is 1/4 of the original height
*OBITUARY string Defines the obituary string for this actor. This string
uses a few placeholders:
%o: victim's name
%k: killer's name
%g: he/she/it
%h: him/her/it
%p: his/her/its
*HITOBITUARY string Defines the obituary string for a melee attack by this
actor. If not present OBITUARY is used. The same format
as for OBITUARY appplies.
*DONTHURTSHOOTER If this actor deals explosive damage and is a projectile
it does not hurt the shooter.
*EXPLOSIONRADIUS value Defines the radius of explosive damage
Default is 128
*EXPLOSIONDAMAGE value Defines the amount of explosive damage
Default is 128
MELEEDAMAGE value Defines the amount of damage this monste will inflict
when using A_MeleeAttack. The formula is random(1,8)*damage.
MISSILETYPE name Defines the projectile type this monster is firing when
using A_MissileAttack. Any valid projectile present in the
game can be specified.
MISSILEHEIGHT value Defines the height at which the projectile is spawned.
Default is 32.
MONSTER Sets all appropriate flags to make this actor act as a regular
monster. The following flags are being set:
SHOOTABLE, COUNTKILL, SOLID, CANPUSHWALLS, ACTIVATEMCROSS, CANPASS, ISMONSTER.
PROJECTILE Sets all appropriate flags to make this actor act as a regular
projectile. The following flags are being set:
NOBLOCKMAP, NOGRAVITY, DROPOFF, MISSILE, ACTIVATEIMPACT, ACTIVATEPCROSS, NOTELEPORT.
CLEARFLAGS clears all flags
*DROPITEM name [probability [amount]]
Drops an item of type 'name' when dying. Optionally the probability
can be specified. A probability of 255 means the item is always dropped,
a probability of 0 means it is never dropped.
amount is only applicable for Heretic ammuniton. It specifies how much
ammo the dropped item contains.
There can be more than one DROPITEM definitions for an actor. The
amount is unlimited.
DROPITEM works differently with inherited actors. An actor can inherit
a list of DROPITEM definitions from its parent but if it defines one
of its own the entire parent's list is discarded.
SPAWN
SEE
MELEE
MISSILE
PAIN
DEATH
XDEATH
BURN
ICE
RAISE
CRASH With these keywords a specific state in the actor can be either cleared
or set to one of the parent's states. The syntax is:
SPAWN 0 to clear a state or
SPAWN PARENT DEATH[+offset] to set a parent's state. See 3) above for an
example
STATES Defines an actor's states. See the separate block STATES for more information
Properties prefixed with a '*' cannot be inherited from predefined actors due to the
implementation.
List of flags
=============
Flags are special properties that can be either set or cleared
+flagname sets a flag
-flagname clears a flag
The following flags exist. If applicable the name is identical with the one used
in regular DECORATE items.
SOLID set when the object should be solid (blocking)
SHOOTABLE object can be damaged. If health goes below 0 it dies
NOSECTOR Object is not linked into the sector. This makes it invisible
and excludes it from certain physics checks.
NOBLOCKMAP This object is excluded from passive collision detection. Nothing else
can run into a NOBLOCKMAP object but the object itself can run
into others. All projectiles have this set.
AMBUSH Monster is 'deaf'. Normally this is set in an editor on a per-
object basis.
JUSTHIT try to attack right back (used in monster AI, probably not
particularly useful in actor definitions)
JUSTATTACKED take at least one step before attacking
SPAWNCEILING spawned hanging from the ceiling as opposed to standing on the
floor.
NOGRAVITY Actor is not subject to gravity
DROPOFF Monster can walk over ledges/taller steps.
NOCLIP Actor is totally excluded from collision detection and
can walk through walls etc.
FLOAT Floating monster - can change height at will.
TELEPORT Although implemented there isn't a single actor which
uses this flag. I can't say what it does precisely but
it excludes an actor that has it set from certain parts
of the collision detection logic.
MISSILE Actor is a projectile.
SHADOW Actor is nearly invisible. Unlike regular Doom this does
not automatically imply fuzziness. For that you have to
specify RenderStyle Fuzzy.
NOBLOOD Actor does not bleed when hurt.
CORPSE Actor is a corpse. For normal actors there is no need to
set this but in combination with the crashstate it might
be useful.
COUNTKILL Counts toward kill percentage
COUNTITEM Counts toward item percentage
NOTDMATCH Is not being spawned in Deathmatch games.
NOLIFTDROP Does not drop when a lift under it lowers
STEALTH Stealth monster
ICECORPSE Actor is a frozen corpse
LOWGRAVITY Actor is subject to low gravity
WINDTHRUST Actor is thrust by the Heretic wind specials. I hope its
functionality is some day expanded to the Boom wind specials
HERETICBOUNCE Heretic style bouncing (objects only bounce off the floor)
HEXENBOUNCE Hexen style bouncing (objects bounce off floors and walls)
DOOMBOUNCE ZDoom style bouncing (like hexen but stops when losing a certain
amount of momentum)
The 3 bounce types are mutually exclusive
FLOORCLIP Actor's lower part is clipped when standing in a sector
with a liquid texture (defined in the TERRAIN lump)
SPAWNFLOAT Actor is spawned hat a random height in the sector.
NOTELEPORT Actor cannot teleport
RIPPER For projectiles that can rip through monsters and players.
PUSHABLE Actor can be pushed.
SLIDESONWALLS Actor can slide along walls
CANPASS Actor uses height sensitive collision detection. Use with care!
This only makes sense on actors that can move by themselves.
CANNOTPUSH This actor cannot push pushable objects.
THRUGHOST This actor passes through ghosts (set with the GHOST flag.)
BOSS Actor is a boss. Bosses have a few special properties
(like playing some sounds at full volume.)
FIREDAMAGE Actor inflicts fire damage.
ICEDAMAGE Actor inflicts ice damage.
NODAMAGETHRUST Upon hitting another actor the victim is not thrust when damaged.
TELESTOMP This actor can telefrag others.
FLOATBOB use float bobbing z movement like Heretic/Hexen's powerups
ACTIVATEIMPACT Upon hitting a wall this actor can activate G1/GR lines
CANPUSHWALLS Upon hitting a wall this actor can activate P1/PR lines
ACTIVATEMCROSS This actor can activate 'Monster crosses' lines.
ACTIVATEPCROSS This actor can activate 'Projectile crosses' lines.
CANTLEAVEFLOORPIC This actor cannot cross into a sector with a different floor
texture.
NONSHOOTABLE Actor cannot be hit (projectiles pass through.)
INVULNERABLE Actor cannot be hurt.
DORMANT Actor is dormant and has to be activated with Thing_Activate.
SEEKERMISSILE Actor is a homing missile. This is only used as a hint to the
game. For a homing missile to be effective it has to use
one of the seeker missile code pointers in its moving states.
REFLECTIVE Actor reflects missiles shot at it.
FLOORHUGGER defines a projectile that is moving along the floor.
CEILINGHUGGER defines a projectile that is moving along the ceiling.
NORADIUSDMG Actor cannot be hurt by radius (explosive) damage.
GHOST Actor is a ghost. This does not imply translucency etc.
DONTSPLASH Actor does not create any terrain splashes
DONTOVERLAP Two actors with this flag cannot overlap at the same x/y-position
but different heights
DONTMORPH Cannot be morphed into a chicken or pig.
DONTSQUASH This actor cannot be instantly killed by Heretic's powered up Mace.
FULLVOLACTIVE Plays its active sound at full volume
ISMONSTER Actor is a monster
SKYEXPLODE Projectile explodes when hitting a sky instead of vanishing
STAYMORPHED If morphed this actor cannot revert to its original form.
DONTBLAST Cannot be blasted by Hexen's Disc of Repulsion.
CANBLAST Can be blasted by Hexen's Disc of Repulsion. For monsters this is
implicit.
NOTARGET cannot be targeted by other monsters.
DONTGIB cannot be crushed to a pile of blood.
NOBLOCKMONST can walk through monster blocking lines.
FULLVOLDEATH Plays its death sound at full volume
CANBOUNCEWATER Can bounce on water. Normally an object is destroyed in this case.
NOWALLBOUNCESND Does not play a sound when bouncing off a wall. Normally the
Seesound is played in this case.
FOILINVUL Can hurt invulnerable monsters (but not players.)
NOTELEOTHER Cannot be teleported by Hexen's banishment device.
QUICKTORETALIATE Immediately switches targets when being attacked.
NOICEDEATH Monster cannot be frozen, used to prevent the generic ice death.
RANDOMIZE Randomizes the duration for its first frame. Most of Doom's projectiles
use this.
FIXMAPTHINGPOS Move thing out of walls. For torches and similar things that tend to be
placed directly on a wall.
ACTLIKEBRIDGE Uses the special collision logic for bridge things.
STRIFEDAMAGE Strife uses a different damage calculation for its projectiles.
States (a.k.a. Frames)
======================
States define the behavior of an actor. For any regular actor there are the following
labels:
SPAWN defines the state that is displayed when an actor is spawned
For monsters this is normally also the idle loop.
SEE defines the walking animation for a monster.
MELEE defines the melee (near) attack.
MISSILE defines the missile (far) attack.
PAIN defines the pain action
DEATH defines the normal death sequence
XDEATH defines the extreme (splatter) death sequence
BURN defines the burn (fire) death sequence
ICE defines the freeze (ice) death sequence
RAISE defines the resurrection sequence (for the Arch Vile)
CRASH defines the crash sequence. This is entered when the actor
is a corpse and hits the floor.
A state definition is started with the 'STATES' keyword and enclosed
by braces '{', '}'.
A state definition consists of the following:
1) State labels. This is one of the keywords listed above followed by a ':'.
Example
Spawn:
defines the entry point for the spawn state.
2) State definitions. These consist of a sprite name, a frame sequence,
the duration in tics (1/35 seconds) and optionally the 'BRIGHT'
keyword to indicate a fullbright display and an action function name
(code pointer)
Example
POSS AABBCCDD 4 A_Chase
This defines 8 states. Each one of them uses the sprite POSS, has a duration
of 4 and uses the code pointer A_Chase which is the standard walk function
for monsters. Of these 8 states the first 2 will use the sprite frame 'A',
the next 2 the frame 'B' and so on. The length of theframe sequence can be
up to 256 characters. Valid frames are 'A'-'Z', '[', '\' and ']'.
Different sprites can be freely mixed in an actor definition each separate
state definition is limited to one sprite only.
3) Jump instructions
There are 4 different jump instructions:
-Loop jumps to the most recently defined state label. This is
used for a looping animation
-Stop Stops animating this actor. Normally this is used at the
end of the death sequences.
-Wait Loops the last defined state. This is only useful if a
code pointer is used that waits a given time or for a
certain event. Currently the only usable code pointer
for this is A_FreezeDeathChunks which is normally used
at the end of a freeze death sequence.
-Goto label+offset
Jumps to an arbitrary state in the current actor.
With this you can also jump to a state that was
inherited by a parent. See Example 2) above for this
The 'Goto see' jumps to the walking animation that
has been inherited.
Important note:
---------------
This format has been designed for maximum flexibility. As a result no assumptions
are made what the designer wants. No states are ever implicitly created.
Action functions:
=================
This information is kept rather brief. For normal purposes in-depth information
is not necessary. All action functions names are preceded by 'A_'.
A_BFGSpray Starts the effect when a BFG projectile hits something
A_Pain Plays the pain sound (that's all it does, it can also be used outside the pain sequence!)
A_NoBlocking Sets the actor to non-blocking and drops items.
A_XScream Plays the sound 'misc/gibbed'
A_Look Look for players - used in the idle sequence of monsters
A_Chase Standard walking function - used in the walk sequence of monsters
A_FaceTarget Change angle to face target
A_PosAttack Zombie attack (one bullet)
A_Scream Plays the death sound (that's all it does, it can also be used outside the death sequence!)
A_SPosAttack Shotgunner attack (3 bullets)
A_VileChase Arch Vile: look for corpses and walk.
A_VileStart Plays sound 'vile/start'
A_VileTarget Spawns the Arch Vile fire.
A_VileAttack Arch Vile attack function. Inflicts some damage and thrusts victim in the air.
A_Fire Keeps Arch Vile's fire in front of target
A_StartFire Plays sound 'vile/firestrt' and calls A_Fire
A_FireCrackle Plays sound 'vile/firecrkl' and calls A_Fire
A_Tracer Homing routine for Revenant's missile
A_SkelWhoosh Calls A_FaceTarget and plays sound 'skeleton/swing'.
A_SkelFist Revenant's melee attack.
A_SkelMissile Revenant's missile attack
A_FatRaise Calls A_FaceTarget and plays sound 'fatso/raiseguns'.
A_FatAttack1 Mancubus attack 1
A_FatAttack2 Mancubus attack 2
A_FatAttack3 Mancubus attack 3
A_BossDeath Boss death specials. Has no effect for custom monsters
A_CPosAttack Chaingunner attack
A_CPosRefire Chaingunner refiring
A_TroopAttack Imp attack
A_SargAttack Demon attack
A_HeadAttack Cacodemon attack
A_BruisAttack Baron attack
A_SkullAttack Lost Soul attack
A_Metal Plays 'spider/metal' and calls A_Chase
A_SpidRefire Spider refiring
A_BabyMetal Plays 'baby/walk' and calls A_Chase
A_BspiAttack Arachnotron attack
A_Hoof Plays 'cyber/hoof' and calls A_Chase
A_CyberAttack Cyberdemon attack
A_PainAttack Pain Elemental attack
A_PainDie Pain Elemental death
A_KeenDie Keen death - opens door with tag 666 if all monsters of the calling kind are dead.
A_BrainPain Plays 'brain/pain' at full volume.
A_BrainScream Starts brain explosion
A_BrainDie Ends level if not in deathmatch
A_BrainAwake Plays 'brain/sight' at full volume.
A_BrainSpit Spits one brain cube
A_SpawnFly Brain cube handling incl. monster creation
A_SpawnSound plays 'brain/cube' and calls A_SpawnFly
A_BrainExplode Brain explosion
A_Die Kills actor
A_Detonate Inflicts explosive damage - amount specified by DAMAGE in the actor
A_Mushroom Shoots a lot of mancubus fireballs high in the air
A_SetFloorClip Sets the FLOORCLIP flag
A_UnSetFloorClip Clears the FLOORCLIP flag
A_HideThing Makes actor invisible
A_UnHideThing Makes actor visible
A_SetInvulnerable Makes actor invulnerable
A_UnSetInvulnerable Makes actor vulnerable
A_SetReflective Sets the REFLECTIVE flag
A_UnSetReflective Clears the REFLECTIVE flag
A_SetReflectiveInvulnerable A_SetInvulnerable + A_SetReflective
A_UnSetReflectiveInvulnerable A_UnSetInvulnerable + A_UnSetReflective
A_SetShootable Makes actor shootable
A_UnSetShootable Makes actor non shootable
A_NoGravity makes Actor not subject to gravity
A_Gravity makes Actor subject to gravity
A_LowGravity makes Actor subject to low gravity
A_ScreamAndUnblock combines A_Scream and A_NoBlocking
A_ActiveSound plays actor's active sound
A_ActiveAndUnblock combines A_ActiveSound and A_NoBlocking
A_FastChase A_Chase variation used by Hexen's class bosses
A_FreezeDeath Starts the freeze death sequence.
A_GenericFreezeDeath Starts the generic freeze death sequence. Calls A_FreezeDeath and sets the ice palette translation.
A_FreezeDeathChunks Burst the actor into chunks. The state with this function has to be looped because it waits until all movement has stopped.
A_IceGuyDie Stops all movement and bursts the actor into ice chunks immediately.
The following functions use some actor properties to determine their behavior
-----------------------------------------------------------------------------
A_Explode Inflicts explosive damage.
Uses:
ExplosionDamage Amount of damage being inflicted
ExplosionRadius Radius of damage
DontHurtShooter If a projectile, don't hurt the guy who shot it.
A_MeleeAttack performs a melee attack
Uses:
MeleeDamage Amount of damage, The formula is random(1,8)*MeleeDamage
MeleeSound Sound being played if the actual attack happens.
A_MissileAttack launches a missile
Uses:
MissileName Actor name of the missile being launched
MissileHeight Height above floor for the spawned missile
A_MissileAttack can handle homing missiles as long as the missile
has the SEEKERMISSILE flag set and contains some kind of tracer
code pointer (A_Tracer, A_MummyFX1Seek, etc.) In its moving animation.
A_ComboAttack combines A_MeleeAttack and A_MissileAttack depending on the current
distance to the target.
A_BulletAttack Hitscan attack
Uses:
damage amount of bullets being fired
The following functions use direct parameters:
----------------------------------------------
A_PlaySound ("soundname") Plays the sound soundname
A_PlayWeaponSound ("soundname") Plays the sound soundname on the weapon channel
Sounds played with A_PlaySound and A_PlayWeaponSound
can occur simultaneously.
A_SeekerMissile (threshold, maxturnangle)
Seeker missile handling. threshold and maxturnangle determine
how 'aggressive' the missile will home in on its target. The larger
the values the more precise it is. threshold specifies the angle
inside which the missile will home in directly on its target.
If the angle toward the target is larger than threshold it will
change its movement angle only partially towards the target.
maxturnangle is the maximum change of movement direction that
will be performed in one move. Maxturnangle should be larger
than threshold. Both angles are specified in degrees and must be
in the range [0, 90].
Example: The flaming skull of Heretic's mummy uses an equivalent
of A_SeekerMisile 20 30
A_Jump (chance, distance) Randomly advances to different state. Like painchance, the chance
value can range between 0 and 255. A chance of 0 will never advance,
while a chance of 255 will almost always advance. If the state is
not advanced, then the one immediately following the A_Jump will
be used as if A_Jump had not been present.
A_CustomMissile ("missiletype", spawnheight, spawnofs_xy, angle)
Spawns a missile attack where "missiletype" is the type of missile
to shoot, spawnheight is how high from the monster's feet to shoot
the missile, spawnofs_xy is how far the monster's center to shoot
the missile, and angle is the direction relative to the monster's
facing angle in which to shoot the missile.
Reference in a new issue Copy permalink