This page has been translated automatically.
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Programming
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
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.

Event Handling Callbacks

Warning
The scope of applications for UnigineScript is limited to implementing materials-related logic (material expressions, scriptable materials, brush materials). Do not use UnigineScript as a language for application logic, please consider C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScipt (beyond its scope of applications) is not guaranteed, as the current level of support assumes only fixing critical issues.

Callback is a function wrapper representing a pointer to static and member functions which are expected to be executed with specified parameters at a certain moment. Callback can be passed as an argument to other function.

In UnigineScript callbacks are represented by function identifiers obtained using the functionid() function:

Source code (UnigineScript)
void callback_function(Node node) {
	/* .. */
}
..
int callback = functionid(callback_function);

Usage Example#

The following section contains the complete source code of a simple callback usage example.

world_script.usc

Source code (UnigineScript)
#include <core/unigine.h>
// This file is in UnigineScript language.
// World script, it takes effect only when the world is loaded.

int init() {
	
	Player player = new PlayerSpectator();
	player.setPosition(Vec3(0.0f,3.401f,1.5f));
	player.setDirection(Vec3(0.0f,-1.0f,-0.4f));
	engine.game.setPlayer(player);

	int callback_id = functionid(callback_function);

	call(callback_id);

	return 1;
}

void callback_function() {
	log.message("Callback has been fired\n");
}

// start of the main loop
int update() {

	return 1;
}

int postUpdate() {
	
	return 1;
}

int updatePhysics() {

	return 1;
}
// end of the main loop

int shutdown() {
	
	return 1;
}

Practical Use#

Callbacks are widely used in event handling. A number of Unigine API members have several predefined events which can be handled by using callbacks in certain cases.

Triggers#

Triggers are used to detect changes in nodes position or state. Unigine offers three types of built-in triggers:

Here is a simple WorldTrigger usage example:

Source code (UnigineScript)
// implement the enter callback
void enter_callback(Node node) {
		if(node.getType() == NODE_OBJECT_MESH_STATIC) {
		ObjectMeshStatic mesh = node_cast(node);
		mesh.setMaterialState("emission",1,0);
	}
}

WorldTrigger trigger;

int init() {

	// create a world trigger
	trigger = new WorldTrigger(vec3(3.0f));
	// set the enter callback to be fired when a node enters the world trigger
	trigger.setEnterCallback(functionid(enter_callback));
	
	return 1;
}

Widgets#

The widgets base class Widget allows registering callbacks for events defined in the GUI class. The following example shows how to create a WidgetButton and register a callback function for the CLICKED event:

Source code (UnigineScript)
// button clicked callback
void onButtonClicked() {
	/* .. */
}

/* .. */
// getting the system GUI
Gui gui = engine.getGui();

// creating a button widget and setting its caption
widget_button = new WidgetButton(gui,"Press me");

// rearranging button size
widget_button.arrange();

// setting button position
widget_button.setPosition(10,10);

// setting onButtonClicked function to handle CLICKED event by using an intermediate redirecting function
widget_button.setCallback(GUI_CLICKED,functionid(onButtonClicked));

// adding the created button widget to the system GUI
gui.addChild(widget_button,GUI_ALIGN_OVERLAP);
See Also

A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/widgets/ folder.

Physics#

You can track certain events of the physics-related Bodies and Joints:

The following sample shows the way of registering callbacks for a BodyRigid and change the color of a mesh depending on its state:

Source code (UnigineScript)
// set the node's albedo color to red on freezing event
void frozen_callback(Body body) {
	Object object = body.getObject();
	object.setMaterialParameterFloat4("albedo_color", vec4(1.0f, 0.0f, 0.0f, 1.0f), 0)
}

// set the node's albedo color to blue on position change event
void position_callback(Body body) {
	Object object = body.getObject();
	object.setMaterialParameterFloat4("albedo_color", vec4(0.0f, 0.0f, 1.0f, 1.0f), 0)
}

// set the node's albedo color to yellow on each contact
void contact_enter_callback(Body body, int num) {
	Object object = body.getObject();
	object.setMaterialParameterFloat4("albedo_color", vec4(1.0f, 1.0f, 0.0f, 1.0f), 0)
}

// create a box static mesh
Mesh mesh = new Mesh();
mesh.addBoxSurface("box_0", vec3(1.0f));
ObjectMeshStatic node = new ObjectMeshStatic(mesh);
node.setMaterial("mesh_base", "*");
node.setPosition(Vec3(0, 0, 5.0f));

// add a rigid body
BodyRigid body = new BodyRigid(node);

// register callbacks for events
body.setFrozenCallback(functionid(frozen_callback));
body.setPositionCallback(functionid(position_callback));
body.setContactEnterCallback(functionid(contact_enter_callback));

// add a shape to the body
ShapeBox shape = new ShapeBox(body, vec3(1.0f));
Notice
Physics-based callbacks are executed in the main tread, as they are mainly used for creation, destruction or modification of other objects.
See Also

A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/physics/ folder:

  • callbacks_00
  • callbacks_01
  • callbacks_02

See Also#

These are not all usage examples of event handling callbacks. The following list contains more API members supporting event handling:

  • UserInterface - for handling events from widgets created by loading a UI file.
  • Render - callback functions can be used to get access to buffers and matrices at intermediate stages of the rendering sequence.
  • Console supports adding a callback function that will be executed when a text is output to the console.
  • EditorLogic - a set of editor callback functions can be overridden for certain purposes.
  • ComponentBase - there may be performed certain actions on destroying a component.
  • AsyncQueue - сallback functions can be used to determine actions to be performed when certain resources are loaded.
  • WorldSplineGraph provides a set of callbacks for handling actions on editing points and segments.
  • Viewport - callback functions can be used to get access to buffers and matrices at intermediate stages of the rendering sequence.

Plugins:

Last update: 2020-07-31
Build: ()