This page has been translated automatically.
UnigineScript
The Language
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins
Content Creation
Materials
Unigine Material Library
Tutorials
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

System Functions

Variable as_double (variable v)

Interprets the long as the double data type on the bit level.

Arguments

  • variable v - Long value.

Return value

Value of the double type.

Examples

To check correctness of such interpretation, perform the following:

  • Interpret double as long.
  • Interpret the long values that you got on the previous step as double.
  • Check the result: the returned double values should be equal to the double values from the first step.
Source code (UnigineScript)
// interpret double as long
log.message("0x%lx 0x%lx\n",as_long(1.0),as_long(-1.0)); // 0x3ff0000000000000l 0xbff0000000000000l
// interpret long as double
log.message("%f %f\n",as_double(0x3ff0000000000000l),as_double(0xbff0000000000000l)); // 1.0 -1.0
			

Another example:

Source code (UnigineScript)
as_double(as_long(2.0));   // the result is 2.0
			

Variable as_float (variable value)

Interprets the int as the float data type on the bit level.

Arguments

  • variable value - Int value.

Return value

Float value.

Examples

To check correctness of such interpretation, perform the following:

  • Interpret float as int.
  • Interpret the int values that you got on the previous step as float.
  • Check the result: the returned float values should be equal to the float values from the first step.
Source code (UnigineScript)
// interpret float as int
log.message("0x%x 0x%x\n",as_int(1.0f),as_int(-1.0f)); // 0x3f800000 0xbf800000
// interpret int as float
log.message("%f %f\n",as_float(0x3f800000),as_float(0xbf800000)); // 1.0f -1.0f
			

Another example:

Source code (UnigineScript)
as_float(as_int(2.0f));   // the result is 2.0f
			

Variable as_half (variable v)

Interprets the int as the half float data type (16-bit floating point value) on the bit level.

Arguments

  • variable v - Int value.

Return value

16-bit floating point value.

Examples

Source code (UnigineScript)
// interpret float as 16-bit int
log.message("0x%x 0x%x\n",as_short(1.0f),as_short(-1.0f)); // 0x3c00 0xbc00
// perform opposite interpretation to check correctness of the result
log.message("%f %f\n",as_half(0x3c00),as_half(0xbc00)); // 1.0f -1.0f
		

Variable as_int (variable value)

Interprets the float as the int data type on the bit level.

Arguments

  • variable value - Float value.

Return value

Int value.

Examples

Source code (UnigineScript)
// interpret float as int
log.message("0x%x 0x%x\n",as_int(1.0f),as_int(-1.0f)); // 0x3f800000 0xbf800000
// perform opposite interpretation to check correctness of the result
log.message("%f %f\n",as_float(0x3f800000),as_float(0xbf800000)); // 1.0f -1.0f
			

Another example:

Source code (UnigineScript)
as_int(as_float(2));    // the result is 2
			

Variable as_long (variable v)

Interprets the double as the long data type on the bit level.

Arguments

  • variable v - Double value.

Return value

Value of the long type.

Examples

To check correctness of such interpretation, perform the following:

  • Interpret double as long.
  • Interpret the long values that you got on the previous step as double.
  • Check the result: the returned double values should be equal to the double values from the first step.
Source code (UnigineScript)
// interpret double as long
log.message("0x%lx 0x%lx\n",as_long(1.0),as_long(-1.0)); // 0x3ff0000000000000l 0xbff0000000000000l
// interpret long as double
log.message("%f %f\n",as_double(0x3ff0000000000000l),as_double(0xbff0000000000000l)); // 1.0 -1.0
			

Variable as_short (variable v)

Interprets the float as the 16-bit int data type on the bit level.

Arguments

  • variable v - Float value.

Return value

16-bit integer.

Examples

Source code (UnigineScript)
// interpret float as 16-bit int
log.message("0x%x 0x%x\n",as_short(1.0f),as_short(-1.0f)); // 0x3c00 0xbc00
// perform opposite interpretation to check correctness of the result
log.message("%f %f\n",as_half(0x3c00),as_half(0xbc00)); // 1.0f -1.0f
		

string call_stack ()

Prints the stack of function calls.

Return value

Current stack of function calls.

variable class_append (variable obj)

Makes an external class object to be handled by the scripting system (serialization, deletion). This means, after being appended, it will be automatically deleted on the script shutdown; or, if necessary, it can be deleted using "delete" operator.
Notice
Be careful, as deleting the object from the outside of the scripting system (in the C++ part) causes double deletion at the same address. Chances are, this will lead to an application crash.

Arguments

  • variable obj - Object of any external (C++) class.

Return value

Input object.

Examples

Source code (UnigineScript)
class_append(engine.editor.loadNode(name));

Node clone = node.clone();
class_append(clone);
delete clone;

variable class_cast (variable target_class, variable obj)

Performs class conversions between external objects.
Notice
Use with caution and only for polymorphic objects. The C++ analogue for this function is reinterpret_cast.

Arguments

  • variable target_class - Target class name.
  • variable obj - Object of any external (C++) class.

Return value

Object of the specified target class.

Examples

Source code (UnigineScript)
Node node_cast(Node node) {
	return class_cast(node.getTypeName(),node);
}

ObjectMesh mesh = node_cast(node);
mesh.getNumSurfaces();

Variable class_manage (variable v)

Indicates that an object should be handled by the UnigineScript garbage collector. This means, the object will be automatically deleted by the script, when its references count reaches 0. But to start with, it should be appended to the script via class_append() function; or it can be created using "new" operator.

Arguments

  • variable v - Object of any external (C++) class.

Return value

Input object.

Examples

Source code (UnigineScript)
File file = class_manage(new File());
file = 0; // file will be automatically deleted when no variables reference it

Variable class_release (variable obj)

Removes all references to the external class including its pointers. It removes even the smallest memory leaks.

Arguments

  • variable obj - Object of any external (C++) class.

Return value

Input object.

Variable class_remove (variable obj)

Prevents an object from being handled by the scripting system (serialization, deletion). After this function is called for an object, the object should be handled by the engine. If a pointer to the released object was not passed to an outside function, it can't be (and will not be) deleted by the engine, thus, there will be a memory leak.

Arguments

  • variable obj - Object of any external (C++) class.

Return value

Input object.

Examples

Source code (UnigineScript)
engine.editor.addNode(class_remove(new ObjectMesh()));

Variable classid (variable v)

Returns the class ID of a given variable or a class signature.

Arguments

  • variable v - Variable name.

Return value

The class signature or variable.

Examples

Source code (UnigineScript)
class Foo { };
if(classid(new Foo()) == classid(Foo)) 
log.message("Foo\n"); // the output is "Foo"
			
You can also pass the class name as a string:
Source code (UnigineScript)
class Bar { };
log.message("Bar ID is: %d\n",classid("Bar")); // the output is "Bar ID is: 1"
			
If the class or variable is declared in a namespace, the class name should be prepended the namespace name. For example:
Source code (UnigineScript)
namespace Foo {
	class Bar { };
}

classid(Foo::Bar);
classid("Foo::Bar");
			

Variable functionid (variable v, int num_args)

Returns internal function identifier without the full namespace path.

Arguments

  • variable v - Function name, string.
  • int num_args - Number of function arguments.

Return value

Function ID.

Variable get_analyze ()

Returns the performance statistics.

Return value

Performance listing.

string get_disassemble ()

Returns a disassembled code of the current script in the terms of assembly mnemonics of the virtual machine.

Return value

Assembly listing.

string get_extern_info (int mask)

Returns a list of registered external variables, functions and classes (to specify data types use a mask).

Arguments

  • int mask - Mask value.

Return value

List of registered entities.

int get_function (string name, int num_args)

Returns the ID of the user-defined function. It can be used to call a function by its ID instead of the name (speeds up the function call; it is almost as fast the direct call).

Arguments

  • string name - Name of the function.
  • int num_args - The number of function arguments.

Return value

Function ID.

Examples

Source code (UnigineScript)
class Foo {
	void foo() { 
	log.message("Foo::foo function is called\n");
	}
};

int id = get_function("Foo::foo");
Foo foo = new Foo();
foo.call(id);

// the result is: Foo::foo function is called
						

Variable get_memory_usage ()

Returns the amount of used memory if the binary is built with debugging support.

Return value

Amount of used memory.

Variable get_thread ()

Returns the current thread identifier. If the code is not in the thread, -1 is returned.

Return value

Thread identifier.

Examples

Source code (UnigineScript)
log.message("%d\n",get_thread());
						

Variable get_variable (string name)

Returns the variable ID. It can be used to pass a variable by its ID instead of the name. It speeds up passing of the variable and can be used, for example, on mobile devices when the performance is crucial.

Arguments

  • string name - Variable name.

Return value

Variable, if it exists; otherwise, 0.

Variable instanceid (variable v)

Returns a unique ID of the user-defined or external class instance.

Arguments

  • variable v - User-defined or external class instance.

Return value

Unique instance ID.

Variable instanceinfo (variable v)

Returns information about the user-defined or external class instance: class type ID, class instance.

Arguments

  • variable v - User-defined or external class instance.

Return value

Information about the class instance.

Variable is_base_class (variable type, variable v)

Checks if the specified variable belongs to the base class.
Notice
This statement can receive the result of the classid() statement as a first argument to provide a very fast querying result.

Arguments

  • variable type - Type of the variable.
  • variable v - A variable to check.

Return value

Variable, if it belongs to the base class; otherwise - 0.

Examples

You can pass the type of the variable as a string:

Source code (UnigineScript)
File file = new File();
is_base_class("File",file);		// returns 1: file is an instance of the File class
is_base_class("Stream",file);	// returns 1: the Stream class is a base class for the File class
is_base_class("Socket",file);	// returns 0: the Socket class is not a base class for the File class
			
Also it is possible to pass the classid() as the first argument:
Source code (UnigineScript)
is_base_class(classid(File),file);		// returns 1
is_base_class(classid(Stream),file);	// returns 1
is_base_class(classid(Socket),file);	// returns 0
			

int is_dmat4 (variable v)

Checks if a given variable is of the dmat4 type.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the dmat4 type; otherwise, 0.

int is_double (variable v)

Checks if a given variable is of the doubletype.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the double type; otherwise, 0.

int is_dvec3 (variable v)

Checks if a given variable is of the dvec3type.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the dvec3 type; otherwise, 0.

int is_dvec4 (variable v)

Checks if a given variable is of the dvec4type.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the dvec4 type; otherwise, 0.

int is_extern_class (variable v)

Checks if a given variable is an instance of an external class.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is an instance of an external class; otherwise, 0.

int is_float (variable v)

Checks if a given variable is of the float type.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the float type; otherwise, 0.

Variable is_function (variable name, int argc)

Checks if a given user-defined function exists. Always returns 0 for functions exported from C++.

Arguments

  • variable name - Full name or ID of the target function.
  • int argc - Number of arguments of the target function.

Return value

1 if the function exists; otherwise, 0.

Examples

Source code (UnigineScript)
int foo(int a,int b) {
	return a * b;
}

if(is_function("foo",2)) {
	log.message("exists\n");
} 
if(is_function(functionid("foo",2),2)) {
	log.message("exists\n");
}
else {
	log.message("doesn't exist\n");
}

int is_int (variable v)

Checks if a given variable is of the int type.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the int type; otherwise, 0.

Variable is_ivec3 (variable v)

Checks if a given variable is of the ivec3.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the ivec3 type; otherwise, 0.

Variable is_ivec4 (variable v)

Checks if a given variable is of the ivec4.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the ivec4 type; otherwise, 0.

int is_long (variable v)

Checks if a given variable is of the longtype.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the long type; otherwise, 0.

int is_mat4 (variable v)

Checks if a given variable is of the mat4 type.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the mat4 type; otherwise, 0.

Variable is_null (variable v)

Returns a value indicating if the variable is equal to zero.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is equal to zero; otherwise, 0.

int is_quat (variable v)

Checks if a given variable is of the quat type.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the quat type; otherwise, 0.

int is_string (variable v)

Checks if a given variable is of the string type.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the string type; otherwise, 0.

int is_thread (int id)

Checks if a thread is still active.

Arguments

  • int id - Thread ID.

Return value

1 if the thread is active; otherwise, 0.

int is_user_class (variable v)

Checks if a given variable is an instance of a user class .

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is an instance of a user class; otherwise, 0.

Variable is_variable (string name)

Checks if a given user-defined variable exists. Always returns 0 for variables exported from C++.

Arguments

  • string name - Name of the target variable.

Return value

Variable, if it exists; otherwise, 0.

int is_vec3 (variable v)

Checks if a given variable is of the vec3 type.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the vec3 type; otherwise, 0.

int is_vec4 (variable v)

Checks if a given variable is of the vec4 type.

Arguments

  • variable v - Variable to test.

Return value

1 if the variable is of the vec4 type; otherwise, 0.

void kill_thread (int id)

Terminates the given thread. This function should not be called from within the terminated thread.

Arguments

  • int id - ID of the thread to be terminated.

int preprocessor (string name, string defines)

Preprocesses a source file (such as a UnigineScript or a shader).

Arguments

  • string name - An absolute path to a file.
  • string defines - Defines to be preprocessed. Several defines are separated with a comma, no whitespaces. It is also possible to use the following syntax: AA=BB.

Return value

1 if the directory was changed; otherwise, 0.

Variable run_threads ()

Runs all threads from the waiting list. This function allows terminating a thread without calling the kill_thread() function.

Return value

1 if threads are run successfully; otherwise, 0.

void set_variable (string name, variable value)

Set the value of the variable by its name.

Arguments

  • string name - Variable name.
  • variable value - Variable value to set.

string stack_dump ()

Prints the memory stack.

Return value

Current memory stack.

void throw (string str, ... )

Generates an exception.

Arguments

  • string str - Message that uses a log.message format. Can be omitted.
  • ... - Message arguments, multiple allowed. Can be omitted.

Examples

Source code (UnigineScript)
throw();
// the result is: "Interpreter throw"
throw("data: %d %s",10,"20");
// the result is: "Interpreter throw: data: 10 20"

Variable typeid (variable v)

Returns the type of the specified variable or type.

Arguments

  • variable v - Variable or type signature to check.

Return value

Zero-based variable type ID:
  1. int
  2. long
  3. float
  4. double
  5. vec3
  6. vec4
  7. dvec3
  8. dvec4
  9. ivec3
  10. ivec4
  11. mat4
  12. dmat4
  13. quat
  14. string
  15. user class
  16. extern class

Examples

For example, you can check the type of the variable as follows:

Source code (UnigineScript)
int a = 1;
if(typeid(a) == typeid(int))
log.message("int\n");
			

string typeinfo (variable obj)

Returns information about a variable.

Arguments

  • variable obj - Variable of any type.

Return value

Information about the variable: type, value.

Examples

Source code (UnigineScript)
int a = 10;
log.message("a is %s\n", typeinfo(a)); // the result will be "a is int: 10"

string typeof (variable obj)

Detects the type of a variable.

Arguments

  • variable obj - Variable of any type.

Return value

Type of the variable.

Examples

Source code (UnigineScript)
int a = 10;
log.message("a is of the %s type\n", typeof(a)); // the result will be "a is of the int type"
					
If the variable is the class instance, the function returns the class name:
Source code (UnigineScript)
class Foo { };

Foo f = new Foo();
log.message("%s\n",typeof(f));

// the output is: Foo
					

void usleep (int usec)

Causes the application to sleep (cease execution of update()) for the specified number of microseconds.

Arguments

  • int usec - Time of sleeping in microseconds.
Last update: 2017-07-03
Build: ()