------------------------------------------------------------------------------

Dismount Levels Script API Definitions
--------------------------------------
For game version: 0.4.0


Web References
--------------

AngelScript Web Site:
    http://www.angelcode.com/angelscript/
Script Writer's manual:
    http://www.angelcode.com/angelscript/scriptmanual/index.html


Mandatory Elements in Scripts
-----------------------------

These global variables must be present in all level script files.

    const int SCRIPT_GAME_VERSION

        Defines the game version which the script has been written for. Game
        may choose not to run the level if the version number given here is
        incompatible.

        Examples:
        const int SCRIPT_GAME_VERSION = int(0x000400);
            Defines that script is written for game version 0.4.0.
        const int SCRIPT_GAME_VERSION = int(0x01020a);
            Defines that script is written for game version 1.2.10.


These functions must be present in all level script files.

    void onInit()

        Called once on level initialization.

    void onUpdate(uint time)

        Called once for each game logic update before the physics update
        which may generate collision callbacks. Parameter 'time' is the
        simulation time in milliseconds.

    bool onCollision(PhysicsObject *object1, PhysicsObject *object2)

        Called when there is a collision between the two given objects. The
        function should return true when contacts should be generated between
        these objects for this frame, or false to ignore the collision this
        time.

    void onRender()

        Called when the game view is rendered. Might happen more or less
        frequently than update calls. You can draw the custom text content in
        this function.


Miscellaneous Globals
---------------------

const float PI = 3.1415926535897932f;

int getGameVersion()

    Returns the game version the script is being run with.

void requireGameVersion(int version)

    Signals the game that this script requires at least the given version.
    Game may be implemented not to run script if its version is less than the
    requested version.

const int GAMESTATE_INIT
const int GAMESTATE_RUNNING
const int GAMESTATE_ABORTED
const int GAMESTATE_FINISHED

int getGameState()

    Returns current game state, see GAMESTATE_ constants.
    This function call will probably be changed later.

void setGameState(int state)

    Sets game state, see GAMESTATE_ constants. You should only set states
    ABORTED and FINISHED with this function.
    This function call will probably be changed later.

const int GAME_BLOCK_COLORS

    Amount of predefined game block colors.

int getScreenWidth()
int getScreenHeight()

    Returns screen width and height in pixels.

void setClearColor(float red, float green, float blue)

    Sets the screen (background) color which will be used to clear
    the screen when beginning to render a frame.
    Returns pointer to the physics world object in use.

void setGravity(float x, float y, float z)

    Sets the world gravity.

PhysicsObject * getObject(uint id)

    Returns pointer to an object identified by the given id, or 0 if no
    object matches the id.

PhysicsObject * findObject(bstr &name)

    Finds an object by name and returns a pointer to it, or 0 if no
    object is found. This is slower than the getObject method.

int abs(int)
double acos(double)
double asin(double)
double atan(double)
double atan2(double, double)
double cos(double)
double cosh(double)
double exp(double)
double fabs(double)
double fmod(double, double)
double log(double)
double log10(double)
double pow(double, double)
double sin(double)
double sinh(double)
double tan(double)
double tanh(double)
double sqrt(double)
double ceil(double)
double floor(double)

    Standard math functions identical to ones in C standard library.

void initRandom(uint seed)

    Initializes pseudo random number generator with given seed. The random
    number generator repeats always same sequence of random numbers for each
    seed. If the generator is not explicitly reinitialized, different
    sequence of random numbers is given for each game run.

int randomInt()

    Returns an integer random number.

double randomDouble()

    Returns a floating point random number as double.


UIFont
------

Global alignment flags:

    const bits UIFONT_ALIGN_DEFAULT
    const bits UIFONT_ALIGN_HORIZ_CENTER
    const bits UIFONT_ALIGN_RIGHT
    const bits UIFONT_ALIGN_VERT_CENTER
    const bits UIFONT_ALIGN_BOTTOM

    Default alignment (UIFONT_ALIGN_DEFAULT) implies top vertical alignment
    and left horizontal alignment. Other flags can be ORed together to
    replace default alignment.

Global methods:

    UIFont * getFont(bstr &name)

        Returns pointer to a font by name.
        Currently available font names:
            "small", "medium"

Class methods:

    void setCharacterSpacing(int spacing)
    int getCharacterSpacing()
    uint getFontHeight()
    int getStringWidth(const bstr &string)

        Font spacing, height and width measure is pixels.

    void drawString(float x, float y, bits flags, bstr &string)
    void drawString(float x, float y, bits flags, bstr &string,
                    float red, float green, float blue, float alpha)

        Draws string to screen, using coordinate (x,y) as origin. The flags
        define the string alignment to the origin. The latter method takes
        also color and alpha values for the string, which are in range [0..1].
        Example:
        font->drawString(100, 100,
                         UIFONT_ALIGN_HORIZ_CENTER | UIFONT_ALIGN_BOTTOM,
                         "Foo");


PhysicsObject
-------------

The game world contains both active and inactive objects. The active objects
manifest themselves in the world as an object with geometry which can be
collided against and which can be visible or not. The objects can also
optionally have physics simulation enabled so that the object dynamically
reacts to collisions against other objects.

Global constants:

    const uint PHYSOBJ_ENVIRONMENT_BOX
    const uint PHYSOBJ_RAGDOLL_BODY

        Object types returned by getType().

Class methods:

    uint getId()

        Returns unique object id.

    uint getType()

        Returns object type, see PHYSOBJ_ constants.

    bool isEnvironmentObject()

        Returns true if this is an environment object, or false otherwise.

    uint getBlockColor()

        Returns block color for the object in range [1..GAME_BLOCK_COLORS],
        or 0 if the object doesn't have a block color and the custom color
        is in use instead.

    void getInitialColor(float &red, float &green, float &blue)

        Assigns the initial custom color to given parameters.

    void getColor(float &red, float &green, float &blue)

        Assigns the current custom color to given parameters.

    void setColor(float red, float green, float blue)

        Sets the custom color of object. Note that this is used only when the
        object is not set to use a predefined block color.

    bstr getName()

        Creates and returns a temporary copy of the object name.

    bool getInitialRotation(float &yaw, float &pitch, float &roll)

        Assigns initial rotation of the object to given parameters. Works only
        for environment objects. Returns true if rotation values were returned
        in parameters or false if the object is not an environment object.

    bool setRotation(float yaw, float pitch, float roll)

        Sets rotation of the object. Works only for environment objects which
        don't have physics enabled. Returns true if rotation was set, or false
        if the object was not an environment object or the object has physics
        enabled.

    bool getInitialPosition(float &x, float &y, float &z)

        Assigns initial position of the object to given parameters. Works only
        for environment objects. Returns true if position values were returned
        in parameters or false if the object is not an environment object.

    bool setPosition(float x, float y, float z)

        Sets position of the object. Works only for environment objects which
        don't have physics enabled. Returns true if position was set, or false
        if the object was not an environment object or the object has physics
        enabled.

    void getPosition(float &x, float &y, float &z)

        Assigns the current object position to given parameters.

    bool isPhysicsEnabled()

        Returns true if physics is enabled for this object, or false if the
        physics is disabled or the object is not an environment object.

    bool isCollisionEventsEnabled()

        Returns true if collision events are enabled for this object, or false
        if the collision events are disabled or the object is not an
        environment object.

    bool removeFromPhysicsWorld()

        Removes the object from physics world so that the object becomes
        inactive. Returns true on success, or false if the object was not an
        environment object.

    bool createToPhysicsWorld()

        Creates an inactive object back to physics world so that the object
        becomes active. Returns true on success, or false if the object was
        not an environment object.

    bool setSize(float xDepth, float yDepth, float zDepth)

        Sets size of an environment box object. Returns true on success or
        false if the object is not an environment box object.

    bool getSize(float &xDepth, float &yDepth, float &zDepth)

        Assigns the size of an environment box object to given parameters.
        Returns true on success or false if the object is not an environment
        box object.

------------------------------------------------------------------------------
$Id: scriptAPI.txt,v 1.11 2004/10/24 17:23:40 tonic Exp $
$Revision: 1.11 $
------------------------------------------------------------------------------
