This is the documentation for the CGL scriptable game engine. The engine is still in active development, as such, its features and the documentation may change at any time without warning.
General considerations
In order to enable the ability to reload code without restarting the game, variables in global scope must be exclusively static data. Any mutable data should be stored in the table named "data".

By default, lua creates all variables in global scope, in order to avoid this, please declare all temporary variables using the "local" keyword.

Some function callbacks, mainly those that pass entities along, will also enable access to a table called "userdata". Here you may store any mutable data tied to the spesific entity.

Because all of the components are data structures only, none of them have methods, however, they do have getters and setters that are treated as methods in lua, prefixed with get[member] and set[member], respectively.
Global callbacks
nil Load(Scene)
Called once upon starting the engine or doing a partial reload using the F6 key. Please use this to load any scripts and assets you may have.

nil Initialize(Scene, Inputs)
Called once upon starting the engine or doing a full reload using the F5 key. This is the entry point of your game and should be used to init any game states.
Global functions
nil Log(String msg)
Prints a message to standard output.

vec2f vec2f(float x, float y)
Creates a struct containing an x and y coordinate. Arithmetic operators +-*/ are allowed against other variables of the same struct type.

int BitSet(int bitmask, int position, bool value)
Copies the bitmask and sets the bit at given position to the given value.

bool BitGet(int bitmask, int position)
Returns the state of the bit at the given position in the bitmask
String/nil GetAnyKeyDesc()
Once a button press is detected, return a string describing the key binding properties of the key pressed. If no keys are pressed, returns nil.

nil Bind(String keyname, int input, int device, int key)
Returns: Nothing
Bind a key to a name using input, device and key values as such:
-Mouse: input=0, device=-1, key=[0-5]
-Keyboard: input=1, device=-1, key=[0-512]
-GamepadAxis: input=3, device=deviceid, key=[axisid]
-GamepadButton: input=4, device=deviceid, key=[buttonid]
-GamepadDpad: input=5, device=deviceid, key=[dpadid]

bool GetPressed(String keyname)
Returns: bool
Returns true if the button was pressed this frame.

float GetAnalog(String keyname)
Returns: float [0,1]
Given a key name, get the current state of the key or axis.

float GetAxis(String leftname, String rightname)
Returns: float [-1,1]
Given 2 axis inputs, combine the data into a single float value

vec2f GetDualAxis(String upname, String downname, String leftname, String rightname)
Returns: vec2f struct [-1,1]
Given 4 axis inputs, combine the data into a single vec2f struct treating all of them as an analog stick.
nil Load(String filename)
Load an asset (.lua, .png, .wav)

Entity CreateEntity()
Create a new entity. Needs to be filled with components to be useful.

int SetCamera(Entity)
Sets the entity as current camera node.

nil PlaySound(String filename, float volume)
Plays a file at the selected volume level. The file needs to be preloaded using the Load method.
Entities are containers for a collection of components. Depending on which components are added to an entity, its behaveour changes. The is the basic concept of Entity Component Systems which is an extension of Data Driven Development.

You can only add one instance of any component type to an entity, but you can later recall the component and change its values at runtime.

Component CreateComponentTransform()
Component CreateComponentRectangle()
Component CreateComponentCircle()
Component CreateComponentFilter()
Component CreateComponentDynamic()
Component CreateComponentCamera()
Component CreateComponentSprite()
Component CreateComponentScript()
Create a component for the given entity. Comes with default values, but should be set manually.

Component/nil GetComponentTransform()
Component/nil GetComponentRectangle()
Component/nil GetComponentCircle()
Component/nil GetComponentFilter()
Component/nil GetComponentDynamic()
Component/nil GetComponentCamera()
Component/nil GetComponentSprite()
Component/nil GetComponentScript()
Get, if possible, a given component. If it hasn't been created, returns nil.
Any entities with a transform component can be placed in the world, and frankly, this should be the case in nearly all instances.

vec2f position (0.0, 0.0)
The current position of the entity.

float rotation (0.0)
The current rotation of the entity.

float scale (1.0)
The current scale of the entity.
Creates a rectangle collider for the entity.

vec2f size (1.0, 1.0)
The size of the rectangle.

bool sensor (false)
If set to true, will disable collisions, but will still report collision callbacks.
Creates a circle collider for the entity.

float radius (0.5)
The radius of the circle.

bool sensor (false)
If set to true, will disable collisions, but will still report collision callbacks.
If attached to a collision object (rectangle/circle/dynamic), you can selectively control what objects can collide with using bitmasks with up to 16 groups. Use BitSet and BitGet to selectively toggle bits in a integer bitmask.

int self (1)
The bitmask of the entity itself, should only ever be a single group.

int collide (65535)
The bitmask of what groups the entity can collide with, defaults to all.
Gives the component a dynamic attribute, meaning it can move around and interact with other collideables. If set without a shape (rectangle,circle), it can only serve as a parent for other components. (Not yet implemented.)

vec2f velocity (0.0, 0.0)
A struct containing the velocity of the object in two directions.

bool kinematic (false)
If set to true, the object can't be pushed around, and will for the most part act as an object with infinite mass.

bool fixedrotation (false)
If set to true, this object cannot be rotated by external forces.

float gravity (1.0)
The objects spesific gravity.

float density (1.0)
Density of the object. The weight will scale with the size of the shape.

float friction (0.3)
A value between 0 and 1, controlling the amount of slipping between shapes when colliding with other entities.

float restitution (0.1)
A value between 0 and 1, controlling the amount the object will bounce and preserve its kinetic energy when colliding with other entities.
If an entity is created with this component, the entity can be assigned as a camera by using the scene.SetCamera() method. This will set the current viewport to the attributes owned by this entity.

float zoom (1.0)
The amount of scaling done on the entire scene.
Entities with this attribute will be drawn in the scene. This should include most objects you use in your game. Area detectors are one of few exceptions.

int layer (0)
A value used to sort all sprites so that the important ones are drawn on the top and not obscured by less important background objects.

String sprite (empty)
Filename of the texture to be used for drawing.

bool flipx (false)
Set this to true if you want to vertically flip the sprite.

bool flipy (false)
Set this to true if you want to horizontally flip the sprite.
Entites with this component attached to it will be exposed to the lua scripting environment. Assign any of the callbacks with names of lua functions in order to add game logic.

String create (empty)
String inputs (empty)
String update (empty)
String collide (empty)
Set the lua callback to the given function name. See section below for further explaination.
Callback functions for script component
nil EntityCreate(Scene, Entity)
Called once after creating the entity, please use this to allocate any userdata variables you may need.

nil EntityUpdate(Scene, Entity)
Called once every frame for the given entity, this amounts to most of any game logic that your game may have.

nil EntityInput(Scene, Inputs, Entity)
This is also called once every frame for a given entity. This function also exposes the inputs system that enable you to read controller, mouse and keyboard input.

nil EntityCollide(Scene, Entity self, Entity victim)
This is called once every time an entity collides with another entity. Be aware that this can easily occur up to several times in a single frame. If there is continuous collision between two entities, only the first contact will be reported.