InFine script reference
The content of this article is out-of-date and should be updated with the latest details.
InFine  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.
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
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 ;
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.
- Background flat (or a single-color background).
- Picture objects (globally offseted with
OffY), in the order in which they were created.
- Text objects, in the order in which they were created.
Restrictions imposed by this order:
- Text can't be hidden behind pictures.
- Background flat can't be scrolled.
- Filter always affects everything.
- Begin a compound. A semicolon ends the compound.
IF commercial DO #> Here can be multiple commands spanning multiple lines. <# ; ELSE DO # More commands. ;
- End the script immediately. Normally a script ends when there are no more commands to execute.
- The command following
IFand its condition are only executed if the condition evaluates to true. The condition can be one of the following:
|| True if the current game mode is |
|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).|
- The command following
IFNOTand its condition are only executed if the condition evaluates to false. The same conditions are used as with
- Use with
IFNOTto provide an alternative execution path.
- Marks a position in the script that can be jumped to with the
gotocommand. Don't use duplicate marker IDs.
- 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.
- 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
NoSkipcommands. When a script is paused and the player causes a skip event, only the pause mode ends, no actual skipping happens.
- 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
Filtercommand 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
Waitcommand pauses the script for two seconds, during which the filter will have time to interpolate to its destination color, i.e. opaque black.
- Pauses the script for one tic, i.e. 28.6 milliseconds (1/35 sec).
- Pauses the script for the specified number of seconds.
- Pauses the script until the specified picture finishes its animation sequence.
- Pauses the script until the specified text object has finished typing its text.
- Allows the player to skip in the script by pressing a key or a button. When skipping, if no
SkipHereis encountered, all the commands from the current position to the end of the script are ignored and the execution of the script ends.
CanSkipis the default mode.
- Disable skipping. The execution of the script will continue non-interactively. Nothing happens even if the player presses a key or a button.
- 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.
- Enable interactive mode. After the
Eventscommand has been executed, the script will begin tracking input events.
- Disable interactive mode. This is the default. When the script is not interactive, any input events will be ignored.
- 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
- Clear the marker name bound to the key. (key-name) must be one of the symbolic key names used by the console command
- Play back a demo file. After the demo ends, the InFine script resumes execution.
- Execute a console command.
- 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.
- Disable the trigger. Input events detected during the execution of the script won't activate the game menu.
- Play the specified sound. There must be a Sound definition with the given ID.
- Play a sound at the specified volume. The volume must be between zero and one, one being the maximum.
- Play the "see" sound of the given thing. There must be a Thing definition with a matching ID.
- Play the "death" sound of the given thing. There must be a Thing definition with a matching 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.
- Same as
music, but (if possible) plays the song only once.
- Stop the currently playing song.
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.
- Set the flat that is used as a tiled background. Give the name of the flat as an argument, for example:
- The flat will be tinted with the background color.
- Clears the currently selected background flat.
- A general X offset that affects all pictures.
OffX 160would appear to move the origin of the screen 160 pixels to the right (half a screen). Note that only picture objects are affected.
- 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
These commands are shared by all objects (rectangle objects, text objects, and picture objects).
- Delete an object.
- Move the specified object to the given X coordinate.
- Move the specified object to the given Y coordinate.
- Rotate the specified object. Positive angles rotate the object in the clockwise direction.
- Scale the specified object with the given horizontal scaling factor.
- Scale the specified object with the given vertical scaling factor.
- 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.
- 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.
Rect(rect-id) (x) (y) (width) (height)
- Create a rectangle object.
- Change the background of a rectangle object to the specified graphics resource. Do not use a file name extension (for example,
XImage R "Mouse").
BOTH) (r) (g) (b) (a)
- Change the fill color of a rectangle object. You can create a gradient by setting the
BOTTOMcolors to different values.
BOTH) (r) (g) (b) (a)
- Change the edge color of a rectangle object. You can create a gradient by setting the
BOTTOMcolors to different values.
- 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
Imagecommand 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 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.
- 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
ImageAnimin the same picture's animation.
- Associate a sound with the last frame of the specified picture's animation sequence. A sound definition with (sound-id) must exist.
- 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-id) (initial-x) (initial-y) (string)
|\"||Double quote (")|
|\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).
- Change a text object's text to the given string. No other properties of the object are modified.
- 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.
- 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.
- 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.
- 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
- 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.
- 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.
- 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.
- 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.
- Set the line height of a text object. The default setting depends on the game you're using.
- 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.