Eternity Engine Small Function Reference v1.3 -- 05/07/06

Return to the Eternity Engine Page

Format of the Reference

Here is a brief example and explanation of the entries in this reference: The Function Name is the name of the function, by which it is called in a script and can be found in this reference. Below the name is the exact declaration of the function in Small along with a brief explanation of each parameter to the function and its return value. Below this is the header file in which the declaration can be found, and then a description with additional, verbose information about how to use the function. Finally, if the function can cause any exceptions, the types of errors will be explained.

Return to Table of Contents

Core Small Functions

These functions are specified and provided by the Small interpreter, and provide some basic facilities for using the language and the interpreter. Note that not all functions suggested by the Small specification are supported by Eternity, so only supported functions are documented here. Return to Table of Contents

Invocation Functions

Invocation functions allow scripts to be started and for special information to be retrieved from within scripts. Understanding invocation models is important for using Small, as many functions can only be used when a script is started under a certain model.

Currently supported invocation model types can be found in the invoke.inc file, and include the following: 
 _INVOKE_NONE     : No special invocation data is available.
 _INVOKE_CCMD     : Script was started via console command.
 _INVOKE_THING    : Script was started by the StartScript codepointer.
 _INVOKE_PLAYER   : Script was started by the StartPlayerScript codepointer.
 _INVOKE_LINE     : Script was started by a script linedef.
 _INVOKE_TERRAIN  : Reserved for future use.
 _INVOKE_CALLBACK : Script was scheduled as a callback or started by the game engine.
 _INVOKE_SPECIAL  : Reserved for future use.
 _INVOKE_DIALOGUE : Reserved for future use.
Return to Table of Contents

Input/Output

Input/Output functions allow the user to manipulate and print string values. Return to Table of Contents

Fixed-Point Math Library

Because the DOOM Engine internally uses a fixed-point number representation, where the 16 most significant bits of a 32-bit DWORD function as a 16-bit signed integer, and the lower 16 bits function as decimal places, it will sometimes be necessary to work with fixed-point numbers. The fixed-point math library, implemented in the fixed.inc file, makes this almost as easy as working with normal integer numbers. Note that functions declared as 'stock' will not be compiled into your scripts unless they are actually used, and that they are NOT public functions and therefore cannot be executed as scripts by the game engine.

Some of the functions listed here are also aliased as overloaded operators, which means that to perform the operations, you need only use the same natural operator notation used with integers. The proper function will be automatically selected by the Small compiler. You can still call the functions explicitly, however. The list of operators overloaded for the Fixed tag can be viewed in the fixed.inc header file. Return to Table of Contents

Random Number Generators

In order to maintain demo sync and to work with the rest of the engine, Small must utilize the special DOOM pseudo-random number generator. Two functions are provided for interfacing with the system. Return to Table of Contents

Heads-Up Display

Beginning with Eternity Engine v3.33.01, the heads-up display is fully scriptable. HUD elements are called widgets, and are automatically maintained by the game engine, including being erased and drawn each frame. Widgets must be created with a unique mnemonic string that serves as their name. Widgets with duplicate mnemonics won't be created. As with all other symbols, widget mnemonics starting with an underscore character are reserved by Eternity.

Eternity defines the following HUD widgets natively: 

Mnemonic               Type    Description
---------------------------------------------------------------------
_HU_MsgWidget          Misc.   Player message widget
_HU_CrosshairWidget    Patch   Aiming crosshair
_HU_VPOWidget          Patch   VPO warning indicator
_HU_OpenSocketWidget   Patch   Network connection fail indicator
_HU_CenterMsgWidget    Text    Player center message
_HU_LevelTimeWidget    Text    Automap level clock
_HU_LevelNameWidget    Text    Automap level name
_HU_ChatWidget         Text    Player chat widget
_HU_CoordXWidget       Text    Automap x coordinate
_HU_CoordYWidget       Text    Automap y coordinate
_HU_CoordZWidget       Text    Automap z coordinate
---------------------------------------------------------------------
Not all native widgets support manipulation through all of the script interface functions. Errors will not occur if a widget is specified inappropriately, but unexpected results may occur, such as changes to those widgets not applying permanently or not applying at all.

The following optional engine-specified event callback functions can be defined in both the Gamescript and Levelscript to interact smoothly with the native HUD system. The game engine will call the Gamescript handlers first if they exist, and then the Levelscript handlers if they exist. 
Name            Purpose
-------------------------------------------------------------------------------
OnHUDStart      Called at start of a new level or when the player viewpoint
                changes (ie, to a different player in coop mode). Use this
                callback to set new values to auto-cleared text widgets, etc.

OnHUDPreDraw    Called immediately before all HUD widgets are drawn to the 
                screen. This is the safest time to alter the properties of
                HUD widgets. Altering them at any other time may result in
                scraps being left on the game border and other odd visual
                errors.   
-------------------------------------------------------------------------------
Return to Table of Contents

Game Functions

Game functions allow interaction with various aspects of the game engine and player data. Return to Table of Contents

Mapthings

Mapthing functions allow interaction with moving objects in the map, including monsters and player avatars. Most mapthing functions require TIDs, or thing ids, which must be set via ExtraData. For more information, see the ExtraData Reference.

There are several special reserved TID values which can be found as macro definitions in the things.inc file. These are as follows: 
_TID_PLAYER1 : Refers to player 1's avatar.
_TID_PLAYER2 : Refers to player 2's avatar, if player 2 is present.
_TID_PLAYER3 : Refers to player 3's avatar, if player 3 is present.
_TID_PLAYER4 : Refers to player 4's avatar, if player 4 is present.
_TID_TRIGGER : Refers to the current script trigger object, if one exists.
These values are always safe to use, as all mapthing functions check whether the objects exist before using them. However, sometimes results may be unexpected if the objects do not exist, so it is best to check beforehand when possible. Return to Table of Contents

Sounds

Sound functions allow the playing of sounds and music in various ways. Return to Table of Contents

Particles

These functions allow direct manipulation of particle effects. Return to Table of Contents

Sectors

These functions allow manipulation of sectors. Return to Table of Contents

Parameterized Line Specials

These functions correspond to ExtraData parameterized linedef specials. These functions provide functionality similar to BOOM generalized linedefs, but they can accept an even wider range of values than the corresponding BOOM lines, and thus provide additional flexibility far beyond what is possible with the DOOM map format. These specials are based loosely on those available in Hexen. Return to Table of Contents

Cameras

Camera functions allow manipulation of the various types of camera objects which exist in the game. Return to Table of Contents

Special Functions

Return to Table of Contents