Scripting - Last Assignment
Main Structure
Here we have the simple flow diagram of scripting structure:
First we have to talk about the language we chose, Lua. Lua is a powerful, efficient,
lightweight, embeddable scripting language. It supports procedural programming, object-oriented programming,
functional programming, data-driven programming, and data description.
Lua is a good option also for the great integration in C. We have also integrate LuaBridge,
a very good library to relate Lua with and C++ code of engine and vice versa.
Scripting Flow
First, we count with two main files: ModuleScripting and ComponentScript. We will talk
about the component script later. ModuleScripting is a Sub Class of Module that will have the Lua State in order
to use lua scripts in the engine. On the init of Engine will create an instance of Lua State and init all lua
libraries. After, Application
wil call a virtual function in Module called LuaRegister() in charge of register all functions and
fields that we want to use in scripts, for example the Module Input will Register its functions GetKey,
GetMouseButton...
After the init and start of all modules, starts the Update loop. ModuleScripting does not
have any instructions to do in the loop, all logic is in component script. The update of GameObjects do the
update of all its components. The main structure of Component Script is drawed in the diagram above. Once the
engine is in game mode, will check if is the first time the component do the first update, if not, the engine
will compile the script and saved a copy of the lua table in a LuaRef (we will talk later when we explain the
component). After compiling, or not if was already compiled, the script pushes global variables to the lua
state. This is made because you will want to access to the GameObject attached to component script but lua has
not know what GameObject is the object you are calling. Lua allows you to set global variables, so we push the
pointer of GameObject of the component and called it "gameObject", so now in script when we type "gameObject" we
will refering to the GameObject of the script. We made the same with transform and with public vars
in inspector.
Once all variables are pushed we see if we have to call Start or
Update. Is important to call the function from LuaRef because we can have more than one GameObject
with the same script and if we execute the script as normal the variables will we shared with all GameObject
that have the same script (in the script sctructure we will see why we do like that).
After execute the script it is the time to pop the global variables we pushed before in
order that other scripts do not access to other GameObjects and other vars. We pushed from lua stack. Also we
update the public variables because we send a copy of that variables.
This is the Update of component script. After finish the Update, engine will check if the
user wants to exit, if he want, will destroy all modules. ModuleScripting will close Lua State. And finally
close all application.
Script as a Component
The component script will be the container that will compile and execute the script and save the public
variables in order to print them in the inspector. Here we have the class diagram:
The most important in the component is the LuaRef var and the script_path. LuaRef is a
structure of LuaBridge that keep the reference of any variable in a Lua script. To set some context, here we
have the Model Script:
This is the script Model, when you create a script inside the engine, will copy that and
change the name class for the name you setted. As we can see, all is in a function that returns a local table.
Because you cannot get local variables in C++ from Lua we have a complete function that returns a local table.
With that we save some headaches with the shared scripts with some GameObjects. The main variable here is the
Model(or the name you setted to the script) that will act like a class in C++. Model is a table
that has three different variables. Variables is a table that will keep the public variables that
we want to see in the inspector in order to modify in the engine. We also have Start and
Update that we have explained before. The user can create new variables inside Model table. Every
time a component script compile a script, will execute the Init function and save in a LuaRef the table.
In order to have public vars that user can edit we have to consider some things specials in
lua. Firs of all, lua is dynamically typed so you can have a number and later assign a string, this will be
difficult to get in the inspector. Lua types are nil, boolean, number (only "float", int does not exist),
string, userdata, function, thread, and table. WhispEngine can hold in editor the next types: boolean, int,
float, string, GameObject and Prefab. to store that variables in editor we have to read from the raw script and
save in a container. The two classes above were made to store that data and print in the inspector.
PublicVar is the base class and Property class is the class to store data, inheriting from
PublicVar. We made that way because we want to save in the same vector different type of data. Each script
component will save a map of string and PublicVar. PublicVar also keeps the variable type and a list of macros
in order to edit the way variables show in the inspector. WhispEngine for the moment has four macros.
ISGAMEOBJECT is when you declare a GameObject to know that will be a GameObject. This can sound a little weird,
but it is necessary in lua because it is not like c# that you have GameObject variable_name; in lua
is like this: variable_name, and that could be a GameObject, a number, a string... and the same
with Prefabs. So in order to let the engine understand what will be you have to initialize all variables that
you want in the inspector. This are an example:
Script
In engine Inspector
GameObject vars are treated as GameObject pointers, to assign a GameObject to a public variable in the
inspector just drag a Gameobject from the hierarchy to the variable in the inspector. The Engine will save all
variables in the scene with the data you setted. If you want to instantiate a Gameobject from a script the
better way is to create a prefab of that GameObject and create a public var in the script. To assign a Prefab
just Drag from Resource panel the prefab you want to the variable prefab. Don't forget to set the macros, in the
case of GameObjects is: variable_name = nil, --[GameObject]. And for Prefabs is: variable_name = nil,
--[Prefab].
WhispEngine Lua Wiki
Introduction
Here you will find the functions and global variables that uses the scripting system in order to create your
own scripts. WhispEngine has an autocomplete for ZeroBrane editor (see Configuration/ZeroBrane/README.md)
Public variables
All the variables you set in the table of Variables will be public in the inspector. to access later in the
script you will have to add the prefix "var".
For example if you have speed = 5, later in code you will have to refer to it as
var.speed to access the value in the inspector.
GameObject
GameObject is a class of C++ that you can use in lus scripts. All GameObjects you have in scripts will have
that fields:
active:
Changes the active bool of GameObject.
gameObject.active = false --> deactive the GameObject
name:
Changes the name of GameObject.
gameObject.name = 'Tina' --> Sets the name of GameObject to 'Tina'
transform:
Gets the transform object of the GameObject.
GameObject
GameObject is also a namespace. You can use this functions from GameObject namespace
Instantiate:
Crates an instance of a Prefab. Sends a Prefab and return a GameObject pointer.
Destroy:
Destroys a GameObject. Sends a GameObject pointer.
SetColor:
Change the color of a GameObject. Send a GameObject pointer and three numbers from RGB.
gameObject
The word "gameObject" is reserved for the GameObject pointer of the GameObject attached to that script
component.
Vector3
Vector3 is a class and a namespace. You can use this functions and fields
(Constructor):
To create a Vector3 you can send nothing or three numbers. vec = Vector3() or vec = Vector3(0,0,0).
x:
Gets x value.
y:
Gets y value.
z:
Gets z value.
Normalize:
Normalize the Vector3.
Normalized:
Returns the Vector3 normalized.
Magnitude:
Returns the magnitude.
sqrMagnitude:
Returns the magnitude sqrt.
toString:
Returns a string with the info of the Vector3.
FromEuler:
Creates a Quaternion from euler angles XYZ.
Quaternion
Quaternion is a class and a namespace. You can use this functions and fields
(Constructor):
To create a Quaternion you have to send x y z and w numbers. quat = Quaternion(x,y,z,w).
x:
Gets x value.
y:
Gets y value.
z:
Gets z value.
Normalize:
Normalize the Quaternion.
Normalized:
Returns the Quaternion normalized.
toString:
Returns a string with the info of the Quaternion.
ToEuler:
Creates a Vector3 from euler angles XYZ.
SetFromAxisAngle:
Set the Quaternion from an axis and an angle.
FromEuler:
Set the Quaternion from a Vector3 Euler Angles.
RotateAxisAngle:
Rotates the Quaternion from an axis and an angle.
RotateX:
Rotates the Quaternion in X axis the given the angle in radians.
RotateY:
Rotates the Quaternion in Y axis the given the angle in radians.
RotateZ:
Rotates the Quaternion in Z axis the given the angle in radians.
Random
Random is a namespace.
Range:
Gives a random int between the given 2 numbers.
Rangef:
Gives a random float between the given 2 numbers.
Log
Log is a function.
Logs in console the message you send.
Time
Time is a namespace.
deltaTime:
Returns the Delta Time.
time:
Returns the time in seconds since game starts.
transform
The word "transform" is reserved for the Transform pointer of the GameObject attached to that script
component. All GameObjects you have in scripts will have
that fields:
gameObject:
Is the GameObject of the own Transform.
parent:
The parent of the GameObject of the Transform.
position:
The Local position referenced to parent.
gposition:
The Global position.
rotation:
The Local Rotation.
grotation:
The Global Rotation.
forward:
Forward vector of the global rotation.
up:
Upper vector of the global rotation.
right:
Right vector of the global rotation.
scale:
Local Scale.
SetPositionv:
Function to set the position of the GameObject. The argument is a Vector3.
transform:SetPositionv(Vector3(1, 0, 0)) --> Set the position to position (1, 0, 0)
SetPosition3f:
Function to set the position of the GameObject. The argument are 3 numbers.
transform:SetPosition3f(1, 0, 0) --> Set the position to position (1, 0, 0)
transform
The word "transform" is reserved for the Transform pointer of the GameObject attached to that script
component. All GameObjects you have in scripts will have
that fields:
gameObject:
Is the GameObject of the own Transform.
parent:
The parent of the GameObject of the Transform.
position:
The Local position referenced to parent.
gposition:
The Global position.
rotation:
The Local Rotation.
grotation:
The Global Rotation.
forward:
Forward vector of the global rotation.
up:
Upper vector of the global rotation.
right:
Right vector of the global rotation.
scale:
Local Scale.
input
input is a namespace.
getKey:
Returns true while pressing that key.
getKeyDown:
Returns true on press that key.
getKeyUp:
Returns true on release that key.
getMouseDown:
Returns true on press that mouse button.
getMouse:
Returns true while that mouse button.
getMouseUp:
Returns true on release that mouse button.
getMouseX:
Returns the X coordenate of mouse on screen.
getMouseY:
Returns the Y coordenate of mouse on screen.
getMouseZ:
Returns the Z coordenate of mouse on screen.
