This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
ded:infine_script_reference [2017-03-13 19:08] – [Audio] skyjake | ded:infine_script_reference [2017-03-22 07:06] (current) – ↷ Links adapted because of a move operation skyjake | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== InFine script reference ====== | ||
+ | |||
+ | // | ||
+ | ((Why is it called " | ||
+ | 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, | ||
+ | |||
+ | 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 '' | ||
+ | |||
+ | |||
+ | ===== 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 ''#>'' | ||
+ | |||
+ | 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: | ||
+ | |||
+ | < | ||
+ | MusicOnce " | ||
+ | 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 ===== | ||
+ | |||
+ | - Background [[:flat]] (or a single-color background). | ||
+ | - Picture objects (globally offseted with '' | ||
+ | - 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. | ||
+ | |||
+ | |||
+ | ===== Commands ===== | ||
+ | |||
+ | |||
+ | |||
+ | ==== Control flow ==== | ||
+ | |||
+ | |||
+ | ; '' | ||
+ | : Begin a compound. A semicolon ends the compound. | ||
+ | < | ||
+ | #> Here can be multiple commands | ||
+ | | ||
+ | ; | ||
+ | ELSE DO | ||
+ | # More commands. | ||
+ | ; | ||
+ | </ | ||
+ | ; '' | ||
+ | : End the script immediately. Normally a script ends when there are no more commands to execute. | ||
+ | ; '' | ||
+ | : The command following '' | ||
+ | | MODE:'' | ||
+ | | secret| True if the current map was exited through a [[: | ||
+ | | netgame| True in multiplayer games. | | ||
+ | | deathmatch| True in [[: | ||
+ | | shareware| True when a [[: | ||
+ | | ultimate| True if the [[: | ||
+ | | commercial| True if the [[: | ||
+ | | leavehub| True if a [[:hub]] has just been exited ([[: | ||
+ | | fighter| True if the player' | ||
+ | | cleric| True if the player' | ||
+ | | mage| True if the player' | ||
+ | |||
+ | ; '' | ||
+ | : The command following '' | ||
+ | ; '' | ||
+ | : Use with '' | ||
+ | ; '' | ||
+ | : Marks a position in the script that can be jumped to with the '' | ||
+ | ; '' | ||
+ | : 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 '' | ||
+ | ; '' | ||
+ | : Sets the interpolation timer, which is used by many commands (color settings, coordinates, | ||
+ | Wait 2</ | ||
+ | ; '' | ||
+ | : 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 '' | ||
+ | ; '' | ||
+ | : 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 '' | ||
+ | ; '' | ||
+ | : Enable interactive mode. After the '' | ||
+ | ; '' | ||
+ | : Disable interactive mode. This is the default. When the script is not interactive, | ||
+ | ; '' | ||
+ | : 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 '' | ||
+ | |||
+ | ==== Game control ==== | ||
+ | |||
+ | |||
+ | ;'' | ||
+ | : Play back a demo file. After the demo ends, the InFine script resumes execution. | ||
+ | ;'' | ||
+ | : Execute a [[: | ||
+ | ;'' | ||
+ | : 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. | ||
+ | |||
+ | ==== Audio ==== | ||
+ | |||
+ | |||
+ | ; '' | ||
+ | : 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 " | ||
+ | |||
+ | ; '' | ||
+ | : Play the " | ||
+ | |||
+ | ; '' | ||
+ | : Start playing a song. There must a [[:music]] definition with a matching ID. (Except in [[:hexen]], where songs are identified by their [[: | ||
+ | |||
+ | ; '' | ||
+ | : Same as '' | ||
+ | |||
+ | ; '' | ||
+ | : Stop the currently playing song. | ||
+ | |||
+ | ==== Screen control ==== | ||
+ | |||
+ | |||
+ | ; '' | ||
+ | : 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:< | ||
+ | ; '' | ||
+ | : 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. < | ||
+ | ; '' | ||
+ | : A general Y offset that affects all pictures. | ||
+ | ; '' | ||
+ | : Set the screen filter. The alpha value defines how strong the filter appears, the following would make the whole screen red:< | ||
+ | |||
+ | ==== Objects ==== | ||
+ | |||
+ | 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. | ||
+ | ; '' | ||
+ | : Scale the specified object with the given horizontal and vertical scaling factors. | ||
+ | ; '' | ||
+ | : Set the specified object' | ||
+ | ; '' | ||
+ | : Set the specified object' | ||
+ | |||
+ | |||
+ | === Rectangles === | ||
+ | |||
+ | |||
+ | ; '' | ||
+ | : Create a rectangle object. | ||
+ | ; '' | ||
+ | : Change the background of a rectangle object to the specified [[: | ||
+ | ; '' | ||
+ | : Change the fill color of a rectangle object. You can create a gradient by setting the '' | ||
+ | ; '' | ||
+ | : Change the edge color of a rectangle object. You can create a gradient by setting the '' | ||
+ | |||
+ | |||
+ | === Pictures === | ||
+ | |||
+ | |||
+ | ; '' | ||
+ | : 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 " | ||
+ | ; '' | ||
+ | : Works like " | ||
+ | ; '' | ||
+ | : Create a picture object out of a [[: | ||
+ | ; '' | ||
+ | : Set the patch of an existing picture object. Only the [[: | ||
+ | ; '' | ||
+ | : Clear the specified picture object' | ||
+ | ; '' | ||
+ | : Append a new frame to the picture' | ||
+ | ; '' | ||
+ | : Append a new frame to the picture' | ||
+ | ; '' | ||
+ | : Associate a sound with the last frame of the specified picture' | ||
+ | ; '' | ||
+ | : End the picture' | ||
+ | ; '' | ||
+ | : Append (count) frames to the specified picture' | ||
+ | |||
+ | |||
+ | === Text === | ||
+ | |||
+ | |||
+ | ; '' | ||
+ | : 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' | ||
+ | | \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' | ||
+ | | \1| Predefined color 1 | | ||
+ | | \2| Predefined color 2 | | ||
+ | | :| | | ||
+ | | \9| Predefined color 9 | | ||
+ | |||
+ | ; '' | ||
+ | : Create a text object with the ID (text-id). Works like '' | ||
+ | ; '' | ||
+ | : Create a text object with the ID (text-id). Works like '' | ||
+ | ; '' | ||
+ | : Change a text object' | ||
+ | ; '' | ||
+ | : Change a text object' | ||
+ | ; '' | ||
+ | : 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): | ||
+ | ; '' | ||
+ | : 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' | ||
+ | ; '' | ||
+ | : 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' | ||
+ | ; '' | ||
+ | : Set a text object' | ||
+ | ; '' | ||
+ | : Set the line height of a text object. The default setting depends on the game you're using. | ||
+ | |||
+ | ===== See also ===== | ||
+ | |||
+ | * [[finale|InFine definitions]] | ||