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.
- a message: basically a textual OSC message extended to support URL like addresses and variables as parameters.
- a variable declaration.
- a foreign language script that may generate messages as output.
- an end marker 'END' to declare a script end. After the marker, the remaining part of the script will be ignored.
Messages and variables declarations must be followed by a semicolon, used as statements separator.
Messages are basically OSC messages that support the address extension scheme described in section interaction 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 scriptvar.
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.
the relative address ./score addressed to /ITL/scene/layer will be evaluted as /ITL/scene/layer/score
The receiver context may be:
- the INScore application address (i.e. /ITL) for messages enclosed in a file loaded at application level (using the load message addressed to the application) or for files dropped to the application or given as arguments of the INScoreViewer application.
- a scene address for messages enclosed in a file loaded at scene level (using the load message addressed to a scene) or for files or messages dropped to a scene window.
- any object address when the messages are passed as arguments of an eval message (see section miscmsgs).
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.
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:
- be quoted, using single or double quotes. Note that an ambiguous quote included in a string can be escaped using a '\'.
- or make use of the following characters set: [-a-zA-Z0-9]+ or [_a-zA-Z][_a-zA-Z0-9]*.
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;
A variable declaration associates a name with a list of parameters or a list of messages. Parameters must follow the rules given in section scripttypes. They may include previously declared variables. A message list must be enclosed in parenthesis and a comma must be used as messages separator.
Example Variables declarations
color = 200 200 200; colorwithalpha = $color 100; # using another variable msgsvar= ( # a variable referring 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 interactvar). 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);
Environnement variables are predefined variables available in a script context. They provide information related to the current context. Current environment variables are:
- OSName: gives the current operating system name. The value is among "MacOS", "Windows", "Linux", "Android" and "iOS".
OSId : gives the current operating system as a numeric identifier. Returned value is (in alphabetic order):
1 for Android
- 2 for iOS.
- 3 for Linux,
- 4 for MacOS,
- 5 for Windows,
Note: There is nothing to prevent overriding of an environment variable. It's the script responsibility to handle variable names collisions.
Message based parameters
Similarly to message based variables (see section msgvar), 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.
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).
Note that INScore variables are exported to the current language environment.
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.
- readfile(file) : read a file and returns its content as a string. The file name could be specified as an absolute or relative path. When relative, the file is searched in the application current rootPath (see section applmgmt).
- post(address [,...]) : build an OSC message and post it for delayed processing i.e. to be processed by the next time task. address is an OSC or an extended OSC address. Optional arguments are the message parameters.
- osname() : gives the current operating system name. Returned value is among "MacOS", "Windows", "Linux", "Android" and "iOS".
osid() : gives the current operating system as a numéric identifiant. Returned value is (in alphabetic order):
1 for Android
- 2 for iOS.
- 3 for Linux,
- 4 for MacOS,
- 5 for Windows,