Script Components

Scripts themselves are assets just like textures or shaders. This means they have to be referenced in the scene so that they can be executed and operate on scene objects. This is were script components come in. A script component is an instance of a script that can be attached to nodes using customizable parameters.

New script component

Attaching a script to a node automatically creates a script component that instances the script. Attaching scripts can be done by dragging and dropping the script directly on the node from the Solution Explorer or Toolbox. It can also be attached by selecting the node using a right mouse button press and using "Add Scripts... " from its context menu.

After attaching a script to a node, it can be found on the right side of the Scene Tree tab when selecting its corresponding node. Multiple scripts (including the same script) can be attached to the same node.

To delete a script component, select it and press the 'Del' key. Alternatively, select it by pressing the right mouse button and select 'Delete' from the context menu.

Locking a Script item will not also lock the Script Editor.

Script Component Properties

Every script component has the following 2 properties:

Enabled : If this flag is set, the script component will receive callbacks, otherwise not. This flag can be set by the user or by scripts using Candera.SetEnabled.
Priority : This value determines in which order script components receive callbacks. Higher values mean higher priority. Highest priority script components are executed first. The priority is a floating point value, so it's easy to place a new component inbetween other components prioritywise without having to reassign multiple values. Negative values are allowed as well.

The "Enabled" flag and the "Priority" can also be changed in realtime affecting the execution of scripts. After the script system is stopped the properties "Enabled" and "Priority" will display their initial values.

Another possibility to enable/disable script components is by using the option "Enable/Disable all script components" which is available in the context menu of any scene with script components.

Script Component Templates

It is possible to create a template from an existing script component. To do this, just right click on an existing script component - in Scene extra-Tree - and from the context menu select the "Save as Template... > ScriptComponent..." option.

The same operation is possible in "Solution Explorer" panel. Right click on an existing script component and from the context menu select the "Create ScriptComponent Template" option.

The third way to create a template from an existing script component is in the "Templates" panel. Right click on the script component and from the context menu select the "Add Template" option.

In all three cases mentioned above, after the option from the context menu has been selected a dialogue will get opened: "Add New Template". Through this dialogue the user can select a location of the new created template and other details (like Name, Annotations, Script). The created script component templates will be available on both "Solution Explorer" and "Templates" panels.

If the template is used to create many instances which are set set on different nodes, each will should have a different value for the same parameter if the user set them as such. There should be no reference between the template and its instances.

Post Processing Effects

Until the addition of the predefined effects, the rendering flow of the effect had to be modeled completely with the scene graph including manual management of any temporary render targets involved, creating a rigid structure that was hard to extend and tweak since effect parameters were scattered around in the scene graph and its assets. That is why the usage of post processing effects was cumbersome and not intuitive. Consequently, the process was simplified and the user has the possibility to use some predefined effects in an easy and intuitive manner.

The new scripted post processing pipeline allows the following:

Drag-and-drop.
Every script (i.e. effect) has all its parameters exposed in a single UI, and all these parameters can be tweaked in Scene Composer in a WYSIWYG fashion.
Effects parameter values can be saved as templates. This way the user can save different settings of the same effect/script.
Effect parameters can be controlled or animated by other scripts or animations, making complex post processing effects possible (rather than just static post effects).
Several effects on the same camera create a post processing stack where the render target of the camera is automatically passed through to create the final image.
The order of the elements of that stack can be easily changed via the “Priority” parameter of the script.
Individual effects in the stack can be enabled and disabled at any time by the user or by another script.

To see how to write a post processing script check the "Candera Introduction" which is available here: Candera Lua Post Processing.

Three predefined post processing effects are available in the "Templates": "References > SCL:ConstructionKit > ScriptComponents". These effects are the following:

Bloom
Depth of Fiels
FXAA ("Fast Approximate Anti-Aliasing")

To use them, the following steps are mandatory. First, drag some meshes into an already created 3D scene. Second, select one of the available script component templates - "Bloom", "Depth of Field", or "FXAA" - and drop it over the Camera node in the Scene Tree. The camera should be assigned to a render target on a display. Check if the content is visible on the display. Third, start the script system by calling: "Script > Start/Pause" script system menu option or "Ctrl + F6" shortcut.

Script Component Parameters

The terms variable and parameter used in this documentation are interchangeable when it comes to scripting.

Parameters that have been publicly exposed in the script appear automatically in SceneComposer's user interface in the 'Properties' tab of the script component. While the parameters are declared in the script (details about public parameters can be found here), their actual values are defined by the script component. That way the same script can be attached multiple times with different parameter values. This means that scripts can be customized on a per instance (i.e component) basis. Editing and validating the script will not discard the values as long as the parameter has not been removed from the script. The values are saved with the solution and exported as part of the scene.