Scripting

Introduction

Inanity scripting system follows the same "abstraction" approach as the rest of the engine. The abstract script bindings are implemented, allowing to use several scripting languages (possibly simultaneously) with single and simple code on a C++ side.

At the moment Inanity supports Lua and V8 Javascript Engine integration. Adding support for new languages is easy thanks to general abstracted framework. For example, the essential part of V8 integration was implemented in just 2 days of coding.

Scripting Concepts

There is a list of things you can do with script:

• Load and run script from a source or bytecode
• Expose C++ classes, methods and constructors into script environment
• Receive data from script via autobindings or as Script::Any values
• Return data to script
• Call script functions/closures from C++

Class Metadata

Inanity meta system allows to describe and store information about C++ classes and methods. Using this information, script system can export these C++ things into script's entities.

So, what can be exposed to metadata? You can define classes with their names and full names (i.e. with namespaces). You can specify optional one constructor for a class. If you do that, instances of the class can be created directly in script. If you don't specify a constructor, instances of the class couldn't be created in script directly; instead, instances should be created by C++ code and returned back to script.

A class can export non-static and static methods. Each method exposes its name, and types of arguments. There is no overloading, so all methods of the class should have distinct names.

Arguments of the methods and constructors have out-of-the-box support for elementary C++ types such as int, double or bool, plus Inanity::String and pointers to RefCounted C++ objects. Value-type items (structs) are supported too via extensible script conversion API.

There is support for raw script values exposed via Script::Any abstract class. This allows to work with any script values including arrays, hash tables and functions.

Script Environment

The script environment (global scope in Javascript, environment in Lua) contains names of exported namespaces and classes.

In order to use static methods of a class or create instances by calling class constructor you need to explicitly add the class into an environment. Adding class is not necessary for calling non-static methods of the class instances.

Reclaiming Objects

Object exposed to a script could be reclaimed which means all references to it in a script are wiped out. You may want to reclaim object from script if you don't want to rely on a script's garbage collection. Reclaiming appropriately dereferences an object.

Accessing reclaimed object from script leads to runtime error. Reclaimed object is not equal to null/nil/undefined.