|
RaySupreme Script API
|
|
RaySupreme Script API
|
Scripts can be used inside RaySupreme in various ways. This guide explains the general Script API as well as the context provided for Scripts through the ScriptContext class which is accessible throught the global g_ctx variable. Note that Scripts used in the NLP context (Natural Language Processing) have a different runtime context, for this, please see the Text-to-3D Artist Guide.
RaySupreme uses AngelScript for it's scripting engine, Documentation about the features of AngelScript are available online.
Scripts, like Objects and Materials, can be shared through the online Database. You can download existing scripts from the Database through the "Download Scripts..." menu item in the Scripts menu. In the Script Editor you can also upload (and share) your own scripts to the Database.
In RaySupreme, Objects are represented by a NodeGraph, each NodeGraph can contain an unlimited amount of Nodes, some of whom may reside inside sub NodeGraph's, these are represented in RaySupreme as sub-objects. Nodes have one or more Terminals which can be connected to (or disconnected from) other Node Terminals of the NodeGraph. Each Node also has a ParameterContainer which contains a list of all Parameters of the Node. Nodes and NodeGraphs have unique id's inside the Graph, these are often used to identify specific key nodes in the Graph hierarchies, in the Shell they are also used to make identification and navigation of specific nodes and gaphs easier.
Using scripts, you can manipulate any aspects of the node based Objects inside RaySupreme. Add nodes, delete them, connect and disconnect them or change their parameters, thus allowing you to create or manipulate Objects in the Project in any way
Using the Mesh Class you can also directly access the mesh of an object and modify it. Use the NodeGraph::getMesh() function to gain access to an existing mesh, which is handled by the Mesh Editor Node, for a given NodeGraph. Each NodeGraph can have exactly one Mesh associated to it per level.
To build a new, empty object, do something like this:
// — Create a new sub-graph in the root graph.
NodeGraph =g_ctx.rootGraph().addSubGraph();
graph.setName( "New Object" );
// — Add the minimum nodes to it necessary for an object, a transform, a material dispatcher, a material and a shape
Node@ transform=graph.addNode( "geometry.afftrans" );
Node@ matdispatcher=graph.addNode( "matdispatcher" );
Node@ material=graph.addNode( "material.material" );
Node@ shape=graph.addNode( "geometry.shape" );
// — Connect the nodes
material.connect( "out", matdispatcher, "mat1" );
shape.connect( "out", matdispatcher, "geom" );
matdispatcher.connect( "out", transform, "in" );
The Shell can be used to parse the nodegraph hierarchy and call functions and macros registered in the Include files (as described in Script Types). For example with the macro ls or dir you can display the contents of the current graph, change the graph level with cd etc.
There are several script types available, all of these can be edited in the Script Editor.
Generic
Generic scripts are the most common script types, they can be run directly from users in RaySupreme and can contain their own user interface. The structure of an Generic script looks like this:
class Generic_TestScript
{
void onParameterContainer( ScriptContext &ctx, ParameterContainer &pc )
{
}
void onExecute( ScriptContext &ctx, ParameterContainer &pc )
{
}
};
onParameterContainer() is called when the script UI is about to be shown. The script is supposed to fill in the passed ParameterContainer structure with the UI of the script. After the user adjusted the values inside the UI and executes the script, onExecute() is called. The UI values can be read from the passed ParameterContainer instance. Please have a look at the various generic scripts available in the Database.
Include
The Include script types can be included from other scripts and contain often used functions which can be re-used from Generic scripts or directly through the Shell. Generic scripts can include specific include files through the
#import Script Name;
command, like #import Mesh Utilities;
Many Include files are also used to provide functionality for the Shell. Functions like "cd" or "dir" or "printpc", which are available in the Shell, exist in Include files. To make functions available for the Shell, the Include file needs to contain a
void registerFunctions( void )
{
}
function. This function is responsible for registering the functions inside the Include file (and macros for these functions) to the Shell. On each Shell startup, the Shell parses all available Include files and registers all functions and macros.
See ScriptContext::registerFunctionDesc() and ScriptContext::registerMacro() for more information on how to register your functions and macros.
Tool
Tool PlugIn scripts cannot be run directly by the user like Generic scripts but are displayed in the Tool Browser. From within RaySupreme you cannot differentiate if a given Tool is native C++ tool or a Script PlugIn tool. To make this possible, Tool scripts support an undo / redo mechanism. A tool script looks like this:
class Tool_Test_Tool
{
void onParameterContainer( ScriptContext &ctx, ParameterContainer &pc )
{
}
void onUndo( void )
{
}
void onRedo( void )
{
}
void onApplyContext( ScriptContext &ctx, ParameterContainer &pc )
{
}
string onSupportsContext( ScriptContext &ctx )
{
}
string onCategory( void )
{
}
};
string onCategory( void );
Returns the category of the Tool, examples are: "Tool.Object.Creator", "Tool.Object.Modifier", "Tool.Mesh.Modifier", "Tool.Object.Importer", "Tool.Object.Exporter", etc.
string onSupportsContext( ScriptContext &ctx );
Returns the mode supported by the script for the given context. Mostly scripts check the NodeGraph of the currrently selected objects (if any), using ctx.selected(), to see if the script supports all of them. If the script does not support the context, it should return an empty string (i.e. ""), otherwise it should return any combination of "Vertex", "Edge", "Face", "Object" to indicate RaySupreme which modes are supported.
void onApplyContext( ScriptContext &ctx, ParameterContainer &pc );
Inside this function, the script should store all needed information to local class variables which than get used inside the undo() and redo() calls. Note that you should not store references to the selected objects but store their ids, as the objects themselves might get newly allocated during undo / redo operations. See the "Object Align" example. Immediately after onApplyContext() is called, redo() is called to actually execute the script. onApplyContext() is only called once per script instance, undo() / redo() can be called multiple times depending on user interaction.
void redo();
Perform the action of the script tool using the context variables stored in onApplyContex()
void undo();
Performs an undo action using the context variables stored in onApplyContex(). It is guaranteed that the Objects are in the same state as after the last redo() call.
void onParameterContainer( ScriptContext &ctx, ParameterContainer &pc );
This function is the same as in Generic scripts, it builds the UI of the script. The user filled out ParameterContainer is than passed to onApplyContext() so that its state can be stored.
An easy to understand example for a Tool PlugIn script is the "Object Align" Script tool.
Scripts are also used in Templates. You can write scripts which create an object from scratch or modify the NodeGraph. Script based Adjectives can also be implemented. All this is done via the
void instanceScript( Instance &instance, InstanceContext &context, NodeGraph &graph )
{
}
function. The Instance class provides some basic support routines, like Instance::print() or Instance::year() which returns the current year set in the NLP context. The InstanceContext class provides access to Variables defined in adjectives for the template. The NodeGraph points to the graph of the instantiated template which will need to be filled with nodes or modified.
1.8.4
