WHAT IS
3D RAD?
CLICK HERE
TO FIND OUT!
Script
With this object you can manipulate the internal parameters of all the objects linked to it by using a script.
In your script, you can also execute functions on the linked objects, for example to show/hide them, or start/stop their action, and so on.
The script language's syntax is C-like. The script engine is AngelScript, by Andreas Jönsson.
Please see the Script Object Reference document for details on all currently available script functions.
Launch 3D Rad, press [Ctrl]+[O] and double click the TutScript1 project to open it.
The project is made of a Script and a Sprite object, linked together.
Linking an object to a Script makes it available to the script code.
Double-click the Script item in the Object List to open its property dialog.
This window lists all object 'handles' that can be accessed by the script.
These handles can be passed as parameters to object manipulation functions (see Tutorial 2, below).
This window lists the linked object's internal parameters that can be read by the script.
This window lists the linked object's internal parameters that can be written (set) by the script.
This is the editable script code. Note that the Main() function must always be present in your script.
In this example, the actual code is the line between the curly brackets. What it does is setting the OUT_0 variable (sprite opacity) to a random value between 0 and 1.
Because, when the project is launched, the script is executed 75 times per second, what you see on your screen is a twinkling sprite.
Exit the properties dialog and press [Space] to see this little script in action.
Press [Ctrl]+[O] and double click the TutScript2 project to open it. Then double-click the Script item in the Object List to open its property dialog.
This script defines a new variable named count of type int (integer). Its initial value will be zero when the project is launched.
The definition is outside the Main() function, which means that the variable count will preserve its value after every execution of the script code.
In the Main() function we increase the count variable by one at every execution (count++;). It means that, when the project is launched, after one second it will be 75, after two seconds 150 and so on.
At the if (count == 200) iObjectHide(OBJ_0); line, the script checks if the count variable is 200 and, if it is, it calls the iObjectHide() function for the sprite object.
The result is that the sprite will twinkle for a bit more than 2 seconds and then it will disappear.
The third script (TutScript3 project) demonstrates a bit more complex script. We have an additional object (SoundEffect) linked to the Script now.
This makes more environment variables available to our script. They are listed in the top 3 windows, in the property dialog for the Script object.
In this case, in our script, we only set the sprite opacity until the count variable has reached 200 (if (count < 200) OUT_0 = iFloatRand(0,1);).
We also hide the sprite and start the sound effect when the count variable is 300.
The result is that the sprite will twinkle for a while, then freeze at a certain opacity level and finally disappear after approximately one second.
Use this button to verify your script syntax. If any problem is detected in your script code a message box will popup and give you clues on how to fix it.
If this option is not checked, the script will not be executed. It will only execute after it is started by another object, like for example EventOnInput or another Script object.
The remaining controls on the dialog are common to all objects.
They are explained here.
The Script object, like many other objects, has internal parameters you can access/manipulate by using other objects like EventOnValue or another Script. The Script's internal parameters are defined as Script's VAL_01, Script's VAL_02, Script's VAL_03.
The internal parameters of a Script object can be accessed by its own script code as variables named VAL_01, VAL_02, VAL_03 respectively.
When porting a script from a project to another, or from a Script object to another, the variable names in the code may no longer be consistent with the environment variables defined for the new Script object.
You can automatically renumber all instances of a variable in the code by selecting it in the code (double-click or mouse-click & drag) and then double-clicking the proper variable declaration in the OBJECT HANDLE, INPUT or OUTPUT windows on the Script object dialog.
Script's editor window is powered by Scintilla/SciTE, a brilliant free source code editing component.
License for Scintilla and SciTE
Copyright 1998-2003 by Neil Hodgson neilh@scintilla.org
All Rights Reserved
Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation.
NEIL HODGSON DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL NEIL HODGSON BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
