
Script API Definitions
----------------------
$Id: scriptAPI.txt,v 1.8 2004/08/02 17:42:52 tonic Exp $
$Revision: 1.8 $
----------------------

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

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


Mandatory Functions in Scripts
------------------------------

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;

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.


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.

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");


GameApp
-------

Global constants:

    const int GAME_BLOCK_COLORS

	Amount of predefined game block colors.

Global functions:

    GameApp * getGameApp()

	Returns pointer to the current game application instance.

Class methods:

    int getScreenWidth()
    int getScreenHeight()

	Returns screen width and height in pixels.

    UIFont * getFont(bstr &name)

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

    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.

    PhysicsWorld * getPhysicsWorld()

	Returns pointer to the physics world object in use.


PhysicsWorld
------------

Represents the state of the game world. You can access the game objects
using the current PhysicsWorld instance available from the GameApp instance.
The PhysicsWorld contains both active and inactive objects. Active objects
manifest themselves in the world as an object with geometry which can be
collided against and which can be visible or not. It can also optionally
have physics enabled so that the object dynamically reacts to collisions
against other objects. Inactive objects aren't present in the world as is,
but which can still be accessed through the PhysicsWorld instance, and
activated again, for example.

Class methods:

    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.


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

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.
