Kray3 SDK/Script basics

From Kray
Jump to: navigation, search
Language ›

Script Basics

Welcome to Kray3 Script! Kray script is scripting language that allows you to control Kray render engine. It is very easy to use it so anyone can try it, although any previous programming background experience will come handy.

All you need to start writing Kray scripts is a text editor. I recomend one with code highlighting like Notepad++.

When writing scripts you should make sure you always end your lines with semicolon ';'. Without semicolon Kray will report an error.

You can always lookup the built in help system by using help <command name> command.

Data Types

In this first section we will explore basic data types and operations that you can use in Kray Script. You can use all the standard data types in Kray. Here is just a quick description of each of them:


Strings can be used by wrapping them in singe ' or double " quote marks. For example:

"this is string";
'this is also string';


Double is a type of number that contains twice as many binary digits. You will mostly use this type of number.


double pi, 3.14159;
echo pi;



Vectors are used to define position in space. Whenever you need to use vectors in Kray script you need to declare them with vector command in round brackets: (x,y,z)


vector myvector, (1,2,3);



Orientation matrix or axes defines orientation in space with heading, pitch and bank values. You declare orientation with 'axes' command and values (degrees) in angled brackets:


axes south, <180,0,0>;


Orientation is rotation matrix of x,y and z vector. You can lookup each of the vectors like this:


echo <0,0,0>.x // returns X vector in the matrix: (1,0,0)
echo <0,0,0>.y // returns Y vector in the matrix: (0,1,0)
echo <0,0,0>.z // returns Z vector in the matrix: (0,0,1)


Variable length blocks

Variable length block contains multiple values of given data type. It looks in Kray reference like that:

<syntaxhighlight> {<xyz> position,...} // one or more XYZ vector required {<double> mask,...} // one or more DOUBLE required </syntaxhighlight>

If you need to put multiple values inside variable length block you need to surround them with { } and separate values with ,. When single value is entered { } can be skipped.

Multiple position vectors are ofter use to express object movement during camera shutter time (motion blur). If you want to enable motion blur for an object use following syntax for describing its position:

<syntaxhighlight> {(1,0,0),(2,0,0),(3,0,0),(4,0,0)} </syntaxhighlight>

This will move object from position (1,0,0) to (4,0,0) with 4 steps.

When you don't need motion blur and object position is fixed during frame use this: <syntaxhighlight> (2.5,0,0) </syntaxhighlight>

Note that object movement during shutter time (motion blur in a single render frame) is not the same as object animation (object changes its position in every render frame).

Standard Functions and Operations

Several standard operations can be used on data types. Please see the following section for details.

Arithmetic Operations

Logic operations

Other operations


Declaring variables in Kray Script is much like in any other language. The following commands are available for each of the data types:


// String variable:
string sometext, "we just declared a string";
// Double variable:
double somenumber, 3.14159;
// Vector variable:
vector somevector, (1,0,1);
// Orientation variable:
axes northwest, (-45,0,0);



Kray Script allows you to write your own functions. Functions are small parts of the code that can be called and executed at will. Think of it like part of the code that you can call with a single command.

To create a function you have to give it a name and wrap it in curly braces:


function MyFirstFunction(){ 
 // ... here we will write some code


Function can also optionaly take some arguments. You define arguments that script can take by defining it's data type and name inside the round brackets:

<include highlight="kray3" src="/pub/kray3_script/functions/function.kray"></include>{{#ifeq: 1|1|

Run in KrayLive|}}

Variables defined inside function are so called "local variables". This means they can only be called from within the function.

<include highlight="kray3" src="/pub/kray3_script/functions/function2.kray"></include>{{#ifeq: 1|1|

Run in KrayLive|}}

Conditional statements and Loops

You can use if and while statements inside Kray Script.


Executes code if condition is true. <syntaxhighlight> if (some condition){

... execute this lines ...

} </syntaxhighlight> Example:

<include highlight="kray3" src="/pub/kray3_script/commands/if.kray"></include>{{#ifeq: 1|1|

Run in KrayLive|}}


Executes code as long as condition is true. <syntaxhighlight> while (some condition is true){

... execute this lines ...

} </syntaxhighlight> Example:

<include highlight="kray3" src="/pub/kray3_script/commands/while.kray"></include>{{#ifeq: 1|1|

Run in KrayLive|}}

Common commands


Displays value of given expression on screen. Example:

<include highlight="kray3" src="/pub/kray3_script/commands/echo.kray"></include>{{#ifeq: 1|1|

Run in KrayLive|}}


Include is very useful command when dealing with large scripts. It allows you to import other script files into your main script. This way you can break your script apart into several files so it's more manageable.

<include highlight="kray3" src="/pub/kray3_script/commands/include.kray"></include>{{#ifeq: 1|1|

Run in KrayLive|}}

You can probably see how this could come handy. For example you can have several scripts each defining one part of scene i.e. one for background, one for render settings, one for geometry etc. This way you can reuse your scripts in different file simply by linking them with include script.


Help command is used to display short help and prototype for the command.

<include highlight="kray3" src="/pub/kray3_script/commands/help.kray"></include>{{#ifeq: 1|1|

Run in KrayLive|}}


You can also generate the list of all the commands in either plain text or html format.

<syntaxhighlight> commandsprotos 0,1,"all_commmands.txt"; // will create txt file with all the available commands commandsprotos 1,1,"all_commmands.html"; // will create html file with all the available commands

openurl "all_commmands.html"; // will open created file in browser </syntaxhighlight>