EDF state reference

From Eternity Wiki
(Redirected from Frame)
Jump to navigationJump to search

The Frame EDF block allows definition of each individual actor frame in Eternity, independent from the thing types. Frames are commonly referred to by name in the thingtype definitions. Their data structure resembles the Dehacked "Frame" block, but is expanded upon, and uses different keywords.

NOTE: most of the time you'll want to use the DECORATE state syntax right inside the thingtype definition. It is more concise than the classic frame definition described here. In any case, this information is still useful if you want to use framedelta or provide compatibility with Dehacked (even though this can also be ensured by using firstdecoratestate in the thing type definition).

See List of codepointers
See DECORATE state syntax
Back to EDF

Syntax[edit]

Expanded form[edit]

The following is the expanded, uncompressed frame definition. It is seldom needed to be specified this way in Eternity, unless delta structures are employed, which use these keywords. Instead, the compressed frame definitions are preferred.

Any field may be omitted, resulting in Eternity assigning them default values.

frame <unique mnemonic>
{
  sprite         <four-letter name>
  spriteframe    <one-letter index, or number>
  fullbright     <true/false or yes/no or on/off>
  tics           <integer number>
  action         <codepointer name> [(arg, ...)]
  nextframe      <frame mnemonic or '@' keyword>
  misc1          <numeric or identifier data>
  misc2          <numeric or identifier data>
  particle_event <particle event identifier>
  args           { <argument value>, ... }
  +|-decorate
  +|-skill5fast
  +|-interpolate
  dehackednum    <integer unique number>
}

Compressed form[edit]

This form allows frames to be conveniently written on one line without becoming difficult to read.

frame <unique mnemonic> {cmp "sprite|frame|bright|tics|action(arg, ...)|nextframe|p_event|misc1|misc2"}

Defaulted fields which are in the middle may not be simply omitted, they must use the * character in their place. Trailing fields may be omitted.

Previous versions of Eternity supported specification of args at the end of the cmp frame, but this is now deprecated. Any arguments placed in a compressed frame definition should be put inside parentheses immediately after the action.

Note that dehackednum is not supported inside the cmp field, but unless Dehacked patch support is intended, it's not required.

Examples[edit]

These frames do not exist in the original game and are only referenced for example purposes

frame killerimp_fire6 {cmp "KILL|6|*|6|MissileAttack(killerfire,homing,8,5,killerimp_claw)|@next"}

In this case, the frame will use sprite KILL, frame number 6 from a 0-based index (which is G, which could have as well been written in the cmp definition), non-fullbright (default being F, specified in this case with a defaulting *), taking 6 tics, and calling a parameterized MissileAttack, then going to the next frame defined in the file, whichever that may be. All the subsequent fields are left at their null defaults.

frame monster_thinkdecide {cmp "MONS|D|*|0|RandomJump|monster_withdraw|*|monster_engage|100"}

Here, the frame takes 0 tics, as it uses a frame-scripting action (see the tics description), the next frame is explicitly named (so this definition can be placed anywhere in the file), and the misc1, misc2 parameters of RandomJump are specified individually - see below.

Fields[edit]

  • sprite
Default: BLANK
Specifies the four-letter part of the sprite lump to be used by the calling actor, or the special word BLANK, which results in not drawing anything. If the name contains special characters or spaces, it has to be enclosed in quotation marks. Make sure to write the sprite name exactly as the four-letter lump stem, because it's case sensitive.
  • spriteframe
Default: 0
Specifies the sprite frame letter or 0-based index. For example, C is equivalent to 2, A to 0 and so on. In Doom-engine games the sprite lump is named of a four letter stem (specified by the sprite field) followed by one or two pairs of a letter (specified by spriteframe) and a rotation number. In-game the sprite will be viewed normally when the actor gets the first letter from the name, at the designated rotation, or viewed flipped when it gets the second letter, also at the designated rotation. Possible rotations are numbered from 0 to 8. 0 means that the lump name will be used no matter how the actor is oriented against the viewport, while 1-8 mean face-to-face rotated progressively by 45 degrees. There may be more lumps for the same letter (such as Zombieman's POSSA1, POSSA2A8 etc.) and single lumps servicing two letters (SPIDA1D1, SPIDB1E1...)
  • fullbright
Default: false
If true, the sprite will always be seen full bright in the map, even in pitch darkness. Technically the brightness is achieved by using colormap 0 over the sprite, which in normal games is an identity function.
  • tics
Default: 1
Specifies how many gametics (units of 1/35 second each) this frame lasts. In frame loops, at least one of the frames has to take longer than 0 tics, otherwise the game will hang. For certain types of frames, whose purpose includes scripting and random or controlled frame jumping, this value is usually set to 0, because the engine jumps to target frames instantly if a condition is met, regardless of tics. For static, non-animated things, as well as all non-disintegrating corpses, the tics value is usually -1 (forever), and is required to be this way if the corpse in question is supposed to be resurrectable by a monster with VileChase walking frames.
  • action
Default: NULL
Specifies the action pointer that this frame will call when accessed by the actor. Action functions which use the args field otherwise, can also be implemented by including the arguments in parantheses on the same line as the action field, removing the need for the args property. Note that misc1, misc2 requiring actions are NOT subject to this and must be used separately with their fields. These include a few pointers which were inherited from MBF, before the args field was introduced: Face, Mushroom, PlaySound, RandomJump, Spawn and Turn.
  • nextframe
Default: S_NULL
Specifies the frame to go to after the tics duration expires. It can be a frame mnemonic just like this frame's name, or one of these four keywords:
  • @next - go to the next frame in the EDF file.
  • @prev - go to the previous frame in the EDF file.
  • @this - loop to this same frame.
  • @null - go to the S_NULL frame. In effect, it removes the actor from the game.
  • misc1
Default: 0
This is the first argument, used by certain codepointers which were inherited from MBF, see their enumeration above.
It is also used for weapon sprites to offset their graphics relative to center horizontally. Positive means to the right
  • misc2
Default: 0
This is the second argument used by some MBF inherited codepointers.
It is also used for weapon sprites to offset their graphics relative to center vertically. Be careful that the origin is 32 and greater values mean downwards.
  • particle_event
Default: pevt_none
Specifies a special particle effect to occur when the actor enters this frame. Possible values are:
  • pevt_none - No effect. The default.
  • pevt_rexpl - Rocket explosion effect. Orange dots exploding in all directions from the thing's origin.
  • pevt_bfgexpl - BFG explosion effect. Same as rocket explosion, except green.
For other particle effects, which continuously affect the actor, see the Thingtype definition.
  • args
Default: all arguments default to 0.
This is a comma-separated list of codepointer arguments, in the form of numbers or identifiers. As of Eternity Engine v3.35.92, frames support any number of arguments, and argument evaluation is performed at runtime and is specific to each action function.
For normal frame definitions, setting the arguments from the args field is no longer required. It is instead preferred to include them in the action property, inside parentheses, appended to the action name. args may still be useful for frame delta structures, however.
  • +decorate
This keyword, if included in the frame definition, will let the parser know that this frame is part of a sequence of externalized Decorate-defined frames from the states heredoc of thingtype, starting from the one declared by firstdecoratestate of thingtype.
  • +skill5fast
If added, will make the state take half tics on skill 5 and fast mode. Used by the demon in Doom. Note that on Heretic the faster Chase state behaviour is different and not influenced by this.
  • +interpolate
This flag only has meaning for weapon state if misc1 and misc2 are nonzero. These two fields will change the weapon sprite offset and by default that will happen without visual interpolation. If this flag is set, interpolation will be enabled even for this case.
  • dehackednum
Default: -1
Specifies what number to be used if Dehacked patches are used to tweak the gameplay defined by an EDF code. Safe user values are greater than or equal to 10000.

Frame blocks[edit]

As of March 13 2016, Eternity supports Decorate-like frame blocks to concisely define groups of frames that don't belong to certain thing types. Currently this is being used to define some Dehacked-compatible frames that aren't currently used by any thing. The syntax is as follows:

frameblock
{
  firststate <mnemonic>
  states
  @"
    <Decorate style syntax>
  "@
}

The fields are:

  • firststate
This is the name of the first of several EDF frame blocks defined consecutively. Each such frame must have the +decorate field included, and the number of these blocks must match the number of Decorate-style items defined in the states property of frameblock.
  • states
Decorate-style definition of the frames.

Back to Editing reference