

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.
