Editing EDF state reference

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.
{{see|List of codepointers}}
{{see|DECORATE state syntax}}
{{backto|EDF}}
==Syntax==
===Expanded form===
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         <[[List of codepointers|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===
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====

''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===

*'''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 [[List of codepointers|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 [[list of codepointers|codepointers]] which were inherited from MBF, see their enumeration above.
*'''misc2'''
:Default: 0
:This is the second argument used by some MBF inherited codepointers.
*'''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 state syntax|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.
*'''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==

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]]''
[[category:EDF]]