Script for 3D Rad

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.

TUTORIAL 1
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.

OBJECT HANDLES
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).

INPUT
This window lists the linked object's internal parameters that can be read by the script.

OUTPUT
This window lists the linked object's internal parameters that can be written (set) by the script.

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.

NOTE: everything in a script is case sensitive. This means that all function names and variables must be typed as listed in the Reference.

TUTORIAL 2
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.

TUTORIAL 3
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.

ADDITIONAL INFORMATION
3D Rad uses AngelScript as script interpreter. For more information on AngelScript, please see the language documentation and the datatype documentation

A coding tutorial written by a community member (IronF) is also available here.

SCRIPT EDITOR FUNCTIONS
Check Script
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.

Find Selected Text
You can find all occurrences of the currently selected text by clicking this button multiple times.

To find and replace a recurring text with something else, select replacement text, do Ctrl+C, select text to replace, click Find Selected Text button, do Ctrl+V, click button again, do Ctrl+V and so on.

Working At Start
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.

Display line numbers
If this option is checked, line numbers are displayed in the script editor window. The setting is global for all Script objects and is preserved when 3D Rad is closed.

INTERNAL PARAMETERS

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_1 to Script's VAL_9.

The 9 internal parameters of a Script object can be accessed by its own script code as variables named VAL_1 to VAL_9.

REMARKS

3D Rad has been designed to work with the minimum scripting possible. But it works great even if you fill your projects with scripts.

Still, please keep in mind that you should design your scripts (each Script object) as 'self-contained', to get the maximum advantage from the object oriented nature of 3D Rad.

Where possible, each script should take care of a specific 'task' in your project. If you succeed in this, your scripts will be much simpler, smaller, easier to update and port.

AUTOMATIC VARIABLE RENUMBERING

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 [email protected]

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.


	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. TUTORIAL 1 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. OBJECT HANDLES 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). INPUT This window lists the linked object's internal parameters that can be read by the script. OUTPUT This window lists the linked object's internal parameters that can be written (set) by the script. 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. NOTE: everything in a script is case sensitive. This means that all function names and variables must be typed as listed in the Reference. TUTORIAL 2 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. TUTORIAL 3 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. ADDITIONAL INFORMATION 3D Rad uses AngelScript as script interpreter. For more information on AngelScript, please see the language documentation and the datatype documentation A coding tutorial written by a community member (IronF) is also available here. SCRIPT EDITOR FUNCTIONS Check Script 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. Find Selected Text You can find all occurrences of the currently selected text by clicking this button multiple times. To find and replace a recurring text with something else, select replacement text, do Ctrl+C, select text to replace, click Find Selected Text button, do Ctrl+V, click button again, do Ctrl+V and so on. Working At Start 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. Display line numbers If this option is checked, line numbers are displayed in the script editor window. The setting is global for all Script objects and is preserved when 3D Rad is closed. INTERNAL PARAMETERS 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_1 to Script's VAL_9. The 9 internal parameters of a Script object can be accessed by its own script code as variables named VAL_1 to VAL_9. REMARKS 3D Rad has been designed to work with the minimum scripting possible. But it works great even if you fill your projects with scripts. Still, please keep in mind that you should design your scripts (each Script object) as 'self-contained', to get the maximum advantage from the object oriented nature of 3D Rad. Where possible, each script should take care of a specific 'task' in your project. If you succeed in this, your scripts will be much simpler, smaller, easier to update and port. AUTOMATIC VARIABLE RENUMBERING 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 [email protected] 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.