voxelinc/voxellancer — pull request #462 by mrzzzrm (2014-03-04 07:44:14+00:00)
Title: Scripting

This is the current state of scripting. The API available to Lua-Scripts isn't complete, but a lot of the necessary infrastructure in the C++ side is already there, so more functionality can be added more easy.
Since it won't be possible to integrate Selene in the nearer future, the API is completly procedural, following the good and old pattern of passing handles (called (script)keys and being nothing more than integers) of objects as a first parameter to the corresponding functions.
There is also little support for higher level datatypes, so only int, bool, float and string are always available and can be passed from lua to c++ and vice versa. Additionaly, following the implementation of glm::vec3, it is possible to hand more complex objects from c++ to lua.
C++ functions called by Lua cannot return void and should return a status-int whereever possible.

On the C++ side, there are a few central classes:

### Script
Base class for scripts, can load lua script

### GamePlayScript
Script to be run during gameplay, provides the API

### ScriptEngine
Holds all scripts currently running and manages the ScriptHandles; allocates the unique scriptKeys to the Scriptables

### ScriptHandle
Handle<> to a Scriptable objects never disappears so the scriptKey can always be used on the script-side to check whether the encapsulated object is still valid

### Scriptable
Base class for Scriptable objects (currently WorldObjects, EventPolls, AiTasks). Holds the scriptKey and demands the subclass to provides a scriptableType

## ToDo

* Following the example of FlyToTask, implement the API for all remaining tasks
* Make Squads Scriptable and provide an API for them
* valid() to check whether an object still exists
* provide an API to briefing mode (separate state?) where all input is blocked and the user is briefed via textbox
* EventPoll for onAttack(ship, callback)
* EventPoll for onDestroyed(ship, callback)
* EventPoll for onWaypoint(ship, x,y,z,r)
* ?API to set and query factions?
* ?API to equip worldObjects?
* ?API to control freecam mode, freecam-waypoints, ...?
* yet to be defined mission API (missionFail(); missionSuccess();...)

## Also important
* Scripts should never get the program to crash, ever
* scripting functions can be more highlevel than normal C++ functions
* We currently use the lua binding of elemate. Talk to Leander Neiss and Karsten Tausche and make them create a repo for the binding, they already agreed on this.