
                              InFine Scripts
                              ==============
                by Jaakko Kernen <skyjake@doomsdayhq.com>
                         Version 1.0 -- 04/01/2002


CONTENTS:
1. What is InFine?
2. Script syntax
3. Coordinates and values
4. Drawing order
5. Commands
    5.1  Run control
    5.2  Screen control
    5.3  Audio
    5.4  Pictures
    5.5  Text
6. Links

===========================================================================
1. WHAT IS INFINE?

InFine is a very simple script language used to describe the animations
that are played as interludes and finales in jDoom, jHeretic and jHexen. 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 waiting 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).

===========================================================================
2. 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 <#.

* Any number of semicolons (;) can be used to separate commands, but using
  them is optional. The recommended way is to use semicolons between
  commands on the same line, which makes the script easier to read for
  humans.

* The general syntax of a command is:

    (command) (arg1) (arg2) ...

  Note that only whitespace separates the arguments.

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

===========================================================================
3. 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, though.

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

Time is generally specified in seconds.

===========================================================================
4. DRAWING ORDER

* Background flat (or a single-color background).

* Picture objects (offseted using "offx" and "offy"), in the order in which
  they were created.

* Text objects, in the order in which they were created.

* Filter.

Restrictions imposed by this order: text can't be hidden behind pictures,
background flat can't be scrolled, filter always affects everything.

===========================================================================
5. COMMANDS

...........................................................................
5.1  Run Control

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:

    secret          True when a level was exited through a secret exit
                    button.

    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.

    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".

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.

...........................................................................
5.2  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 (color 1 1 1).

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

...........................................................................
5.3  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.

...........................................................................
5.4  Pictures

delpic (pic-id)
    Delete a picture object.

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.

x (pic-id) (x)
    Move the specified picture to the given X coordinate.

y (pic-id) (y)
    Move the specified picture to the given Y coordinate.

sx (pic-id) (scale)
    Scale the specified picture with the given horizontal scaling factor.

sy (pic-id) (scale)
    Scale the specified picture with the given vertical scaling factor.

scale (pic-id) (x-scale) (y-scale)
    Scale the specified picture with the given horizontal and vertical
    scaling factors.

rgb (pic-id) (red) (green) (blue)
    Set the specified picture's color. The color values are floating- point
    numbers between zero and one.

alpha (pic-id) (alpha)
    Set the specified picture's alpha level. The alpha level is a floating-
    point number between zero and one, zero being fully transparent and one
    fully opaque.

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".

...........................................................................
5.5  Text

deltext (text-id)
    Delete a text object.

text (text-id) (initial-x) (initial-y) (string)
    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. "textrgb" can be used to change
    the color of the text.

    Escape sequences that can be used in the text 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

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.

textrgb (text-id) (red) (green) (blue)
    Set the color of a text object. The color values must be floating-
    point values between zero and one. This color will be used if no escape
    sequences are used to change the color of the text. The escape sequence
    \0 draws the text using the object's own color, which is set with this
    command.

textalpha (text-id) (alpha)
    Set the alpha level of the text object. The alpha value must be a
    floating-point value between zero and one, zero being fully transparent
    and one fully opaque.

tx (text-id) (x)
    Move a text object to the specified X coordinate.

ty (text-id) (y)
    Move a text object to the specified Y coordinate.

tsx (text-id) (scale)
    Scale a text object with the given horizontal scaling factor.

tsy (text-id) (scale)
    Scale a text object with the given vertical scaling factor.

textscale (text-id) (x-scale) (y-scale)
    Scale a text object with the given horizontal and vertical scaling
    factors.

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 "ty" 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.

===========================================================================
6. LINKS

http://www.doomsdayhq.com/

