Last modified on 25 August 2014, at 23:51

InFine script reference

Update Note:
The content of this article is out-of-date and should be updated with the latest details.

InFine [1] is a very simple scripting language used to describe the animations that are played as interludes and finales. The scripts are written in InFine definitions. It can also be used to define introductory animations (InFine scripts can be played before or after any map); briefings and debriefings if you will.

Basics

Once a script starts playing, its commands will be executed until a wait or a pause command is encountered. The script ends when the last command of the script is executed. This means if you forgot to use any wait or pause commands the script will end immediately.

Almost all numeric values (coordinates, colors, scale factors) are interpolated, i.e., their value can change gradually. The In command is used to set the interpolation timer, which will be effective until the next time In is issued. Note that interpolation only occurs while the script is waiting for something. Otherwise the script commands are executed one after another with no delay in between.

The player can interact with the animation by pressing a key on the keyboard or a mouse or a joystick button. This will trigger a skip event (see the CanSkip, NoSkip and SkipHere commands).

Script syntax

Commands are case-insensitive (some arguments are not, however).

Whitespace (spaces, tabs, newlines) is ignored.

Comments are ignored. Comments are lines that begin with the hash character (#), or anything that begins with #> and ends in <#.

The general syntax of a command is:

(command) (arg-1) ... (arg-N)

Some commands don't need any arguments. Note that only whitespace separates the arguments. All commands have a fixed number of arguments.

Semicolons (;) are used to mark the end of a compound. Don't use semicolons elsewhere. An example of how semicolons are used:

IF commercial DO
  MusicOnce "dm2ttl"
  Wait 13
;

Strings can be split onto multiple lines (like in DED files, see the Text definition).

Coordinates and values

The whole screen is thought to be 320 pixels wide and 200 pixels tall, regardless of the actual display resolution. You can freely use fractional pixels (e.g. 104.5) for more accurate placement of objects.

Color values are floating-point numbers, and must be between zero and one. An alpha value of zero means fully transparent and one means opaque.

Time is generally specified in seconds.

Drawing order

  1. Background flat (or a single-color background).
  2. Picture objects (globally offseted with OffX and OffY), in the order in which they were created.
  3. Text objects, in the order in which they were created.
  4. Filter.

Restrictions imposed by this order:

  • Text can't be hidden behind pictures.
  • Background flat can't be scrolled.
  • Filter always affects everything.

Commands

Control flow

DO
Begin a compound. A semicolon ends the compound.
IF commercial DO
  #> Here can be multiple commands
     spanning multiple lines. <#
;
ELSE DO
  # More commands.
;
END
End the script immediately. Normally a script ends when there are no more commands to execute.
IF (condition)
The command following IF and its condition are only executed if the condition evaluates to true. The condition can be one of the following:
MODE:(game-mode) True if the current game mode is (game-mode). For example:

MODE:doom2-plut

secret True if the current map was exited through a secret exit.
netgame True in multiplayer games.
deathmatch True in deathmatch games.
shareware True when a shareware WAD is being used (DOOM 1, Heretic). Always false for DOOM II, Final DOOM and Hexen.
ultimate True if the game mode is "doom1-ultimate" (Doom).
commercial True if the game mode is "doom2" (Doom).
leavehub True if a hub has just been exited (Hexen).
fighter True if the player's class is Fighter (Hexen).
cleric True if the player's class is Cleric (Hexen).
mage True if the player's class is Mage (Hexen).
IFNOT (condition)
The command following IFNOT and its condition are only executed if the condition evaluates to false. The same conditions are used as with IF.
ELSE
Use with IF and IFNOT to provide an alternative execution path.
MARKER (marker-id)
Marks a position in the script that can be jumped to with the goto command. Don't use duplicate marker IDs.
GOTO (marker-id)
Jumps to the given marker. The marker is searched starting from the beginning of the script, so jumps can be made both forward and backward. If the given marker is not found, the script ends.
Pause
Pauses the execution of the script and starts waiting for the player to press a key or a button. This command is not affected by the CanSkip and NoSkip commands. When a script is paused and the player causes a skip event, only the pause mode ends, no actual skipping happens.
In (time-sec)
Sets the interpolation timer, which is used by many commands (color settings, coordinates, etc.) to determine how quickly the changes will be effective. Example:
In 2 Filter 0 0 0 1
Wait 2
The interpolation timer is set to two seconds with the In command. The Filter command changes the screen filter to opaque black but because the interpolation timer is set to a non-zero value, the change will be gradual. In this case it will take two seconds. The Wait command pauses the script for two seconds, during which the filter will have time to interpolate to its destination color, i.e. opaque black.
Tic
Pauses the script for one tic, i.e. 28.6 milliseconds (1/35 sec).
Wait (time-sec)
Pauses the script for the specified number of seconds.
WaitAnim (pic-id)
Pauses the script until the specified picture finishes its animation sequence.
WaitText (text-id)
Pauses the script until the specified text object has finished typing its text.
CanSkip
Allows the player to skip in the script by pressing a key or a button. When skipping, if no SkipHere is encountered, all the commands from the current position to the end of the script are ignored and the execution of the script ends. CanSkip is the default mode.
NoSkip
Disable skipping. The execution of the script will continue non-interactively. Nothing happens even if the player presses a key or a button.
SkipHere
This command only has an effect when a skip is in progress (the player has pressed a key or a button and skipping is enabled). The skipping will stop at this command and the execution of the script continues normally from the command following SkipHere. Note that all the skipped commands were ignored.
Events
Enable interactive mode. After the Events command has been executed, the script will begin tracking input events.
NoEvents
Disable interactive mode. This is the default. When the script is not interactive, any input events will be ignored.
OnKey (key-name) (marker)
When a keyboard input event is detected, execution will jump to (marker). This command will only have an effect in interactive mode. Note that input events are only detected during wait periods. (key-name) must be one of the symbolic key names used by the console command bind.
UnsetKey (key-name)
Clear the marker name bound to the key. (key-name) must be one of the symbolic key names used by the console command bind.

Game control

PlayDemo (filename)
Play back a demo file. After the demo ends, the InFine script resumes execution.
Cmd (console-command)
Execute a console command.
Trigger
When the trigger is enabled, any input events detected during the execution of the script will activate the game menu. The trigger is enabled by default.
NoTrigger
Disable the trigger. Input events detected during the execution of the script won't activate the game menu.

Audio

Sound (sound-id)
Play the specified sound. There must be a Sound definition with the given ID.
SoundAt (sound-id) (volume)
Play a sound at the specified volume. The volume must be between zero and one, one being the maximum.
SeeSound (thing-type)
Play the "see" sound of the given thing. There must be a Thing definition with a matching ID.
DieSound (thing-type)
Play the "death" sound of the given thing. There must be a Thing definition with a matching ID.
Music (music-id)
Start playing a song. There must a Music definition with a matching ID. (Except in Hexen, where songs are identified by their lump names.) The song is played in looped mode.
MusicOnce (music-id)
Same as music, but (if possible) plays the song only once.
NoMusic
Stop the currently playing song.

Screen control

Color (red) (green) (blue)
Set the background color. If no background flat is specified, the whole screen is filled with this color. The color values are given as floating-point numbers, and must be between zero and one. The default background color is white, which is equivalent to the command:
Color 1 1 1
ColorAlpha (red) (green) (blue) (alpha)
Set the background color and alpha. Set alpha to zero to make the background fully transparent.
Flat (flat-lump)
Set the flat that is used as a tiled background. Give the name of the flat as an argument, for example:
flat FLOOR4_8
The flat will be tinted with the background color.
NoFlat
Clears the currently selected background flat.
OffX (pixels)
A general X offset that affects all pictures. OffX 160 would appear to move the origin of the screen 160 pixels to the right (half a screen). Note that only picture objects are affected.
OffY (pixels)
A general Y offset that affects all pictures.
Filter (red) (green) (blue) (alpha)
Set the screen filter. The alpha value defines how strong the filter appears, the following would make the whole screen red:
Filter 1 0 0 1

Objects

These commands are shared by all objects (rectangle objects, text objects, and picture objects).

Del (object-id)
Delete an object.
X (object-id) (x)
Move the specified object to the given X coordinate.
Y (object-id) (y)
Move the specified object to the given Y coordinate.
Angle (object-id) (degrees)
Rotate the specified object. Positive angles rotate the object in the clockwise direction.
Sx (object-id) (scale)
Scale the specified object with the given horizontal scaling factor.
Sy (object-id) (scale)
Scale the specified object with the given vertical scaling factor.
Scale (object-id) (scale)
Scale the specified object with the given scaling factor.
ScaleXY (object-id) (x-scale) (y-scale)
Scale the specified object with the given horizontal and vertical scaling factors.
RGB (object-id) (red) (green) (blue)
Set the specified object's color. The color values are floating-point numbers between zero and one.
Alpha (object-id) (alpha)
Set the specified object's alpha level. The alpha level is a floating- point number between zero and one, zero being fully transparent and one fully opaque.

Rectangles

Rect (rect-id) (x) (y) (width) (height)
Create a rectangle object.
XImage (rect-id) (external-gfx-resource)
Change the background of a rectangle object to the specified graphics resource. Do not use a file name extension (for example, XImage R "Mouse").
FillColor (rect-id) (TOP|BOTTOM|BOTH) (r) (g) (b) (a)
Change the fill color of a rectangle object. You can create a gradient by setting the TOP and BOTTOM colors to different values.
EdgeColor (rect-id) (TOP|BOTTOM|BOTH) (r) (g) (b) (a)
Change the edge color of a rectangle object. You can create a gradient by setting the TOP and BOTTOM colors to different values.

Pictures

Image (pic-id) (image-lump)
Create a picture object. It will be associated with the ID of your choosing. The ID can be any text string but naturally it's best to use descriptive IDs like "back". The (image-lump) is the name of a lump that contains a 320x200 raw image. Raw images are usually exactly 64000 bytes long. You can also insert a PCX image directly into a WAD file and specify its lump name; the Image command accepts PCX images as well as normal raw images.
ImageAt (pic-id) (x) (y) (image-lump)
Works like "image", but lets you specify the initial location of the image. This is not usually needed since the default initial location is (0,0) and images cover the whole screen (320x200).
Patch (pic-id) (x) (y) (patch-lump)
Create a picture object out of a patch image. Patches are the internal image format of Doom. It's most commonly used by the sprites (all sprite frames as patches). Patches can have transparent pixels (e.g. all the characters of the Doom font are patches). (pic-id) is a text string of your choosing. (patch-lump) is the name of the lump that contains the patch image.
Set (pic-id) (patch-lump)
Set the patch of an existing picture object. Only the patch lump of the picture object is changed, other parameters like position and scaling remain the same.
ClrAnim (pic-id)
Clear the specified picture object's animation sequence.
Anim (pic-id) (patch-lump) (time-sec)
Append a new frame to the picture's animation sequence. (time-sec) is the number of seconds that the new frame will last.
ImageAnim (pic-id) (image-lump) (time-sec)
Append a new frame to the picture's animation sequence. The frame is a raw image (320x200 fullscreen image, can also be a PCX image). You can't use Anim and ImageAnim in the same picture's animation.
PicSound (pic-id) (sound-id)
Associate a sound with the last frame of the specified picture's animation sequence. A sound definition with (sound-id) must exist.
Repeat (pic-id)
End the picture's animation sequence in a repeat marker. When the repeat marker is reached, the animation will continue from the first frame of the sequence.
States (pic-id) (state-id) (count)
Append (count) frames to the specified picture's animation sequence, starting from the the state (state-id). For example:
States mo BOSS_RUN1 12
This will append 12 frames starting from the state BOSS_RUN1 to the animation sequence of the picture object named "mo".

Text

Text (text-id) (initial-x) (initial-y) (string)
\n Newline
\" Double quote (")
\_ Space
\w Pause of 0.5 seconds
\W Pause of 1 second
\p Pause of 5 seconds
\P Pause of 10 seconds
\0 Text color changed to the text object's color
\1 Predefined color 1
\2 Predefined color 2
 :
\9 Predefined color 9
Create a text object with the ID (text-id). The ID is a text string of your choosing. You will need it when you later refer to the text object. The text object's upper left corner is placed at the given initial coordinates. In jDoom the text is red by default. In jHeretic and jHexen the default color is white.
Escape sequences that can be used in the text string are listed in the table.
TextDef (text-id) (initial-x) (initial-y) (def-id)
Create a text object with the ID (text-id). Works like Text, but the text itself is taken from the Text definition with the ID (def-id).
TextLump (text-id) (initial-x) (initial-y) (lump)
Create a text object with the ID (text-id). Works like Text, but the text itself is taken from the lump named (lump).
SetText (text-id) (string)
Change a text object's text to the given string. No other properties of the object are modified.
SetTextDef (text-id) (text-id)
Change a text object's text to the string from the Text definition with the ID (text-id).
PreColor (color-number) (red) (green) (blue)
Modify a predefined color. The color values must be floating-point values between zero and one. There are nine color settings you can use as (color-number): 1-9. For example, this'll change the predefined color number 4 to bright green.
PreColor 4 0 1 0
By default all the predefined colors are set to white (1 1 1). Use the escape sequences \1...\9 in the text string of a text object to force the text to be drawn using a predefined color.
Center (text-id)
The text of the specified text object will be drawn centered horizontally around the X coordinate of the object. 160 is the middle of the screen.
NoCenter (text-id)
The text of the specified text object will be drawn in the normal fashion, flushed to the left. The X coordinate of the object specifies the left edge of the text.
Scroll (text-id) (speed)
Set a scrolling speed for the specified text object. Scrolling means that the object is automatically moved upwards. (speed) is the number of 35 Hz tics in which the object moves upward one pixel. If (speed) is zero, the scrolling is stopped. At the speed of 1, the object will move upwards 35 pixels per second. That is the fastest speed you can achieve using this command. Note that you can scroll the text however you want with the In and Y commands.
Pos (text-id) (type-pos)
Set the text object's cursor to the given position. The cursor is actually a counter that counts how many characters of the text object's text string are visible. The command
Pos mytext 0
would rewind the text object "mytext" so that it would start typing its text from the beginning.
Rate (text-id) (rate-tics)
Set the typing speed of the specified text object. The typing rate is given as the number of 35 Hz tics to wait after typing each character. This means at the rate of 1 the text is typed at 35 characters per second. At rate 2 the speed would be 17 characters per second, and so on. 35 characters per second is the fastest speed possible. At rate zero the whole text is immediately visible.
FontA (text-id)
Set a text object's font to Font A, which is the smaller of the available fonts. The line height is modified to match the font.
FontB (text-id)
Set a text object's font to Font B, which is the larger of the available fonts. The line height is modified to match the font. Note that jHeretic and jHexen have only colored versions of Font B (jHeretic: green, jHexen: red), which rather limits the set of colors you can use with this font.
LineHgt (text-id) (pixels)
Set the line height of a text object. The default setting depends on the game you're using.

See also

Footnotes

  1. Why is it called "InFine"? It is a combination of the "infinite" possibilities offered by the scripts for creating "finale" animations (also, fin is French for "end").

This is an exemplary article. It is considered to follow the DEW documentation guidelines in such a way that it serves as an example of good practices.