Chapter 17
Scripting

INScore saves its state to files containing textual OSC messages. These files can be edited or created from scratch using any text editor. In order to provide users with a scripting language, the OSC syntax has been extended at textual level.

17.1 Statements

An INScore file is a list of textual expressions. A script expression is:

expression PICT

Messages and variables declarations must be followed by a semicolon, used as statements separator.

17.2 Messages

Messages are basically OSC messages that support the address extension scheme described in section 16 p.157 and relative addresses that are described below. Messages parameters can be replaced by variables that are evaluated at parsing level. Variables are described in section 17.4.

Using the address extension scheme, a script may be designed to initialize an INScore scene and external applications as well, including on remote hosts.

EXAMPLE
Initializing a score and an external application listening on port 12000 and running on a remote host named host.adomain.net.

/ITL/scene/score set gmnf ’myscore.gmn’;
host.adomain.net:12000/run 1;

Relative addresses have been introduced to provide more flexibility in the score design process. A relative address starts with ’./’. It is evaluated in the context of the message receiver: a legal OSC address is dynamically constructed using the receiver address that is used to prefix the relative address.

EXAMPLE

the relative address ./score
addressed to      /ITL/scene/layer
will be evaluted as   /ITL/scene/layer/score

The receiver context may be:

EXAMPLE
Using a set of messages in different contexts:

score = (
  ./score set gmn ’[a f g]’,
  ./score scale 2.
);
/ITL/scene/l1 eval $score;
/ITL/scene/l2 eval $score;

NOTE
Legal OSC addresses that are given as argument of an eval message are not affected by the evaluation.

17.3 Types

Using OSC, the message parameters are typed by the OSC protocol. With their textual version, any parameter is converted to an OSC type (i.e. int32, float or string) at parsing level. A special attention must be given to strings in order to discriminate addresses and parameters. Strings intended as parameters must:

EXAMPLE
Different string parameter

/ITL/scene/text set txt "Hello world"; ! string including a space must be quoted
/ITL/scene/img set file ’anImage.png’; ! dots must be quoted too
/ITL/scene/foo set txt no_quotes_needed;

17.4 Variables

A variable declaration associates a name with a list of parameters or a list of messages. Parameters must follow the rules given in section 17.3. They may include previously declared variables. A message list must be enclosed in parenthesis and a comma must be used as messages separator.

variabledecl PICT

EXAMPLE
Variables declarations

color = 200 200 200;
colorwithalpha = $color 100; ! using another variable
msgsvar= (       ! a variable refering to a message list
    localhost:7001/world "Hello world",
    localhost:7001/world "how are you ?" );

A variable may be used in place of any message parameter. A reference to a variable must have the form $ident where ident is a previously declared variable. A variable is evaluated at parsing level and replaced by its content.

EXAMPLE
Using a variable to share a common position:

x = 0.5;
/ITL/scene/a x $x;
/ITL/scene/b x $x;

Variables can be used in interaction messages as well, which may also use the variables available in the interaction context (see section 16.5 p.167). To differentiate between a script and an interaction variable, the latter must be quoted to be passed as strings and to prevent their evaluation by the parser.

EXAMPLE
Using variables in interaction messages: $sx is evaluated at event occurrence and $y is evaluated at parsing level.

y = 0.5;
/ITL/scene/foo watch mouseDown (/ITL/scene/foo "$sx" $y);

17.5 Environnement variables

Environnement variables are predefined variables available in a script context. They provide information related to the current context. Current environment variables are:

NOTE
There is nothing to prevent overriding of an environment variable. It’s the script responsibility to handle variable names collisions.

17.6 Message based parameters

Similarly to message based variables (see section 16.5.5 p.170), a message parameter may also use the result of a get message as parameters specified like a message based variable. The message must be enclosed in parameters with a leading $ sign.

msgparam PICT

EXAMPLE
Displaying INScore version using a message parameter:

/ITL/scene/version set txt "INScore version is" $(/ITL get version);

NOTE
Message based parameters are evaluated by the parser. Thus when the system state is modified by a script before a message parameter, these modifications won’t be visible at the time of the parameter evaluation because all the messages will be processed by the next time task. For example:

/ITL/scene/obj x 0.1;
/ITL/scene/foo x $(/ITL/scene/foo get x);

x position of /ITL/scene/foo will be set to x position of /ITL/scene/obj at the time of the script evaluation (that may be different to 0.1).

17.7 Languages

INScore supports Javascript and Lua as scripting languages. Javascript is embedded by default (using the Qt Javascript engine). INScore needs to be recompiled to embed the Lua engine1 . A script section is indicated similarly to a Javascript section in html i.e. enclosed in an opening <? and a closing ?>.

script PICT

The principle of using an embedded programming language in script files is the following: javascript or lua sections are given to the corresponding engine and are expected to produce INScore messages on output. These messages are then parsed as if replacing the corresponding script section.

Note that INScore variables are exported to the current language environment.

EXAMPLE

<?javascript
"/ITL/scene/version set ’txt’ ’Javascript v." + version() + "’;";
?>

A single persistent context is created at application level and shared to each scene.

NOTE Lua support is going to be deprecated and should be removed in a future release.

17.7.1 The Javascript object

The Javascript engine is available at runtime at the address /ITL/scene/javascript. It has a run method that takes a javascript string as parameter.

javascript PICT

The run method evaluates the code. Similarly to javascript sections in scripts, the output of the evaluation is expected to be a string containing valid INScore messages that are next executed. Actually, including a javascript section in a script is equivalent to send the run message with the same code as parameter to the javascript object.

The Javascript engine is based on the Qt5 Javascrip engine, extended with additional functions:

EXAMPLE 1

<?javascript
post ("/ITL/scene/obj", "dalpha", -1);";
# The message /ITL/scene/obj dalpha -1
# will be evaluated by the next time task.
?>

EXAMPLE 2

<?javascript
# declare a function foo()
function foo(arg) {
  return "/ITL/scene/obj set txt foo called with " + arg + ";";
}
?>

# call the foo function
<?javascript foo(1)?>

# or call the foo function using the run message
/ITL/scene/javascript run "foo(1)";