Unigine::Schemer

Schemer is a visual scripting system that allows a developer to create complex sequences of gameplay events without having to script them manually. This way the artists can add interactivity to the world without the help of a programmer. By connecting paths in a flow graph, it is possible to script cutscenes, switches, timers, changes in lighting and much more.
Schemer (as well as Skinner) can either be loaded inside Unigine window or in the external widgets.

Schemer scripts can be found under data/core/systems/schemer folder.

Schemer flow graph consists of the following entities:

• Blocks are the main entities of the Schemer. They describe events, operations or variables of different types. The gameplay programmers code these actions depending on the project needs and make them available to be used in the Schemer by artists. For example, a block can describe the behavior of the game object, for example, the explosion sequence of a game vehicle.
  There is also a number of predefined blocks that perform various arithmetic operations, print a message, etc.
• Nodes are Block units that form the graph sequence; they can be dragged around the graph canvas. That is, while Block is the type of the node that determines what action to do, a node is a block that has been added to the graph to perform this action, given the exact input data. Nodes of the same Block differ in their variables and states.
• Nodes are connected together by Joints. Joints can be of two types:
  • Paths are rendered in white. They control the sequence of executing nodes when the Schemer script is run. That is, by moving along the path joints we could trace how the graph is unrolling starting from each possible entry point (the first nodes of the script) and what are the next triggered nodes.
  • Links are rendered in green. They simply connect nodes that store values and do not perform anything by themselves.
• The point of connection is called an Anchor. Anchors can be of different shapes (round for output paths from a node and square for input paths into a node).
• Schemer editor is a canvas on which the created graph is drawn. It uses Unigine::Widgets::Graph classes for drawing.

To create a graph, drag the blocks onto editor canvas.

1. The first node to start the graph with should always be schemer.entry. The name of this entry point is specified in the world script. By default (in Schemer sample), main name should be specified.
2. Put the cursor over the Output anchor and drag the joint to the Input anchor of the next node. Paths that connect Output and Input anchors control a sequence of executing a graph.
3. Values that nodes operate on are marked in green. The value on the right side of a node is an output value that contains the result of the operation performed by this node. The value on the right side is an input value. Connect two values to pass a value from one node to another.

After the Schemer graph has been created or modified, click Run button. A script will be generated out of the graph, compiled on-the-fly and run.

You can also save the created script into *.script file to be loaded and edited later or executed at runtime.

Inside blocks are functions or snippets of UnigineScript code. The resulting script created from a Schemer graph is made up of code snippets from all blocks put together one after another. When blocks are processed, separate namespaces are created for each of the block to avoid name collisions.

Just like any other script, a block has a number of functions to control its behavior:

• init is for code executed on the Schemer script initialization. It can be used to initialize heavy resources: for example, Skinner loads animations and creates buffers in the init code.
• shutdown is for code executed on the Schemer script shutdown.
  Both init() and shutdown() code snippets do not depend on the graph execution sequence. All blocks will be initialized or shout down at once (see the details).
• update is for code executed when the graph is executed and it is the turn for node with the current block to be activated.
• common is for functions and variables that should have a global scope inside of the block.

Any of these functions inside of the block can be omitted, if necessary.

Blocks File Syntax

<?xml version="1.0" encoding="utf-8"?>
<blocks version="1.00">
	<block type="schemer.message">
		<input_path>input</input_path>
		<output_path>output</output_path>
		<input_link>value</input_link>
		<init>log.message("schemer.message: block is initialized with a script\n");</init>
		<shutdown>log.message("schemer.message: block is shut down with a script\n");</init>
		<update>log.message("schemer.message: %s\n",typeinfo(value));</update>
	</block>
</blocks>

<update><![CDATA[
	if(a > b) goto output_gt;
	if(a < b) goto output_lt;
	goto output_eq;
]]></update>

Customize Basic Blocks

Adding a Custom Blocks File

The following blocks are the basic Schemer blocks defined in the data/core/systems/schemer/schemer_blocks.h script.

The following blocks are the predefined Schemer blocks loaded from data/core/systems/schemer/blocks/schemer.blocks file.

To run the Schemer from the script (here, without a visual editor), you need to add the code as in the following example. update() function of the script compiled from a graph. It will execute all its nodes one by one in the specified order.

#include <core/scripts/utils.h>
#include <core/systems/schemer/schemer.h>

/*
 */
int init() {

	// Use Schemer namespace.
	using Unigine::Schemer;

	// Create a Schemer.
	Schemer schemer = new Schemer();

	// Create Schemer script that will compile an executable script out of the graph.
	SchemerScript script = new SchemerScript(schemer);
	
	// Load the previously created a graph.
	script.load("samples/schemer/scripts/delay.script");
	
	// Compile the loaded graph into a script.
	script.compile();
	
	// Run <init></init> code of all blocks used in the script. Here,
	// constants in schemer.constant blocks are initialized. This line could be omitted,
	// if not necessary.
	script.init();
	
	// Run the graph.
	script.update(script.getEntryID("main"));

	return 1;
}