Scripting actions with Arabesque
The Arabesque scripting system allows the execution of macros specified by the user. These scripts may carry out any function on the unit that does not require administrative access, as well as play sounds, start and stop pre-recorded animation programs, and command the unit to say or act in a certain way. Each line of the script specifies an action to execute. Be aware that the unit can only run one script at a time, and that additional power is expended in the process of executing these scripts.
In addition to the commands available to the user via remote access (see Remote access), Arabesque scripts may contain the following verbs:
To include a comment in an Arabesque script, start the line with a hash sign (#).
Like other system scripting languages, Arabesque supports environment variables, which can be substituted into text as needed. When inserting the value of a variable into a string, prefix the name with $, %, or @ indicating text, integer number, or real number datatype, respectively. As of Companion 8.4.4, the following variables are automatically defined:
Variable names are parsed in a space-separated manner, so that say /me $username's robot is here! will not work, but say $username is this unit's best friend. will. To get around this, the ^H and H^ control sequences are provided. These eliminate spaces before and after the tokens, respectively, and are parsed in a separate pass. Thus, say Is your name really "H^ $username ^H?" will parse correctly.
If you need to insert $, @, or % at the start of a word and not have that word parsed as a variable, double it, e.g. by writing $$, @@, or %%. This is not necessary in the middle of a word, due to the behavior outlined in the previous paragraph.
Normal Arabesque scripts use the filename prefix “a_”, and can be activated from the perform menu, or via the do command. There are two variant types of Arabesque scripts that do not begin with a_. These are e_ and px_ scripts. e_ scripts are executed automatically in response to certain system events, such as connecting to a charger or turning on the system. px_ scripts are executed when a persona is activated; i.e., px_default corresponds to the default persona.
The supported e_ scripts are:
For testing purposes, e_ event scripts can also be activated using the trigger command.
Only one script can be running at a time. Starting a new script (of any type) will interrupt any currently running script. This can be useful if you want to stop a long script, and indeed the included a_stop file can be used to do this. However, be warned that in Companion 8.4 there is no animation stack, so animations will continue playing afterwards unless explicitly stopped.
Arabesque has very limited memory and little in the way of branching facilities. As a result, you may find it difficult to accomplish anything significant with it. However, while the language is not Turing-complete due to its inability to emulate the proverbial 'tape,' it is still very useful as an intermediary utility for coordinating messages with other attachments and generating non-branching or minimally branching behavior.
Commands
In addition to the commands available to the user via remote access (see Remote access), Arabesque scripts may contain the following verbs:
| command | action | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| override <command> | New in Companion 8.6.3. Executes a system command as though the script had been invoked by the unit's owner. This is necessary for changing settings like gender and name via Arabesque scripts. | ||||||||||||||||||||||||||||
| start <animation> | This begins the specified animation, which must be included in the writeable memory of the unit alongside the script. | ||||||||||||||||||||||||||||
| stop <animation> | This stops the specified animation. | ||||||||||||||||||||||||||||
| sound <sound> | This plays the specified sound, which must either be loaded onto the audio processor or referred to directly by UUID. | ||||||||||||||||||||||||||||
| sound vox <sound> | This plays one of the messages from the included voice notification pack. See Sound for more information on voice notifications. | ||||||||||||||||||||||||||||
| remark <message> | This reports a message privately to the unit. | ||||||||||||||||||||||||||||
| say <message> | This causes the unit to say something. The message may contain speech-processor-level commands such as bang commands, dot commands, or emotes. (See articles on input and commands and speech modification with vox.) This will operate even if the unit’s mind is disabled (i.e., even if the cortex prohibits free speech), since it is not spontaneous speech generated by the unit. | ||||||||||||||||||||||||||||
| wait <duration> | Pauses execution for <duration> seconds. | ||||||||||||||||||||||||||||
| disable <subsystem> | Disables subsystem number <subsystem>. | ||||||||||||||||||||||||||||
| enable <subsystem> | Enables subsystem number <subsystem>. Subsystem numbers are as follows:
| ||||||||||||||||||||||||||||
| set <variable> <value> | Sets the indicated variable <variable> to the specified value <value>. This can only be used to store integers. | ||||||||||||||||||||||||||||
| randset <variable> <max> | Sets the indicated variable <variable> to a random integer between 0 and <value> – 1. The variable must be an integer. | ||||||||||||||||||||||||||||
| unset <type> <variable> | Deletes the specified variable from memory. <type> must be int, integer, str, string, or float. | ||||||||||||||||||||||||||||
| report <variable> | Causes the unit to speak the name and value of the specified variable. | ||||||||||||||||||||||||||||
| ifeq <value_1> <value_2> <expression> | Executes the specified expression (a complete line of code, possibly including more of these keywords) if <value_1> and <value_2> are equal. The first value must be an integer variable with its % prefix removed; the second value may be either an integer literal or an integer variable. | ||||||||||||||||||||||||||||
| ifexists <filename> <expression> | Executes the specified expression (as above) if a file called <filename> exists in user memory. |
To include a comment in an Arabesque script, start the line with a hash sign (#).
Variables
Like other system scripting languages, Arabesque supports environment variables, which can be substituted into text as needed. When inserting the value of a variable into a string, prefix the name with $, %, or @ indicating text, integer number, or real number datatype, respectively. As of Companion 8.4.4, the following variables are automatically defined:
| variable | type | description |
|---|---|---|
| $user | string | The key of the avatar who activated the Arabesque script. |
| $username | string | The name of the avatar who activated the Arabesque script. |
| $color | string | The current system color in space-separated floating point (e.g. "1.0 0.5 0.0" for orange—see chapter on identity options) |
| $name | string | The unit's current callsign, e.g. "vict0r" |
| $model | string | The unit's model, e.g. "NS-304" |
| %serial | integer | The unit's serial number without punctuation, e.g. 999123456 |
| $serial_display | string | The unit's serial number with punctuation, e.g. "999-12-3456" |
| @power | float | The current power level (0.0–1.0) |
| $persona | string | The name of the active persona |
| $version | string | The system version |
| $p_abs | string | Physical absolute pronoun ("theirs") |
| $p_pos | string | Physical possessive pronoun ("their") |
| $p_subj | string | Physical subject pronoun ("they") |
| $p_obj | string | Physical object pronoun ("them") |
| $p_refl | string | Physical reflexive pronoun ("itself") |
| $p_gender | string | Physical gender ("inanimate") |
| $m_abs | string | Mental absolute pronoun ("theirs") |
| $m_pos | string | Mental possessive pronoun ("their") |
| $m_subj | string | Mental subject pronoun ("they") |
| $m_obj | string | Mental object pronoun ("them") |
| $m_refl | string | Mental reflexive pronoun ("itself") |
| $m_gender | string | Mental gender ("inanimate") |
Variable names are parsed in a space-separated manner, so that say /me $username's robot is here! will not work, but say $username is this unit's best friend. will. To get around this, the ^H and H^ control sequences are provided. These eliminate spaces before and after the tokens, respectively, and are parsed in a separate pass. Thus, say Is your name really "H^ $username ^H?" will parse correctly.
If you need to insert $, @, or % at the start of a word and not have that word parsed as a variable, double it, e.g. by writing $$, @@, or %%. This is not necessary in the middle of a word, due to the behavior outlined in the previous paragraph.
Script types
Normal Arabesque scripts use the filename prefix “a_”, and can be activated from the perform menu, or via the do command. There are two variant types of Arabesque scripts that do not begin with a_. These are e_ and px_ scripts. e_ scripts are executed automatically in response to certain system events, such as connecting to a charger or turning on the system. px_ scripts are executed when a persona is activated; i.e., px_default corresponds to the default persona.
The supported e_ scripts are:
- e_charge-start: Triggered when charging begins.
- e_charge-end: Triggered when charging ends.
- e_boot: Triggered when the system is powered on. (Formerly known as _init.) Not triggered by activation of auxiliary power.
- e_shutdown: Triggered when the system is shut down using the off or shutdown -h commands, or through the main menu, regardless of auxiliary power settings.
For testing purposes, e_ event scripts can also be activated using the trigger command.
Limitations
Only one script can be running at a time. Starting a new script (of any type) will interrupt any currently running script. This can be useful if you want to stop a long script, and indeed the included a_stop file can be used to do this. However, be warned that in Companion 8.4 there is no animation stack, so animations will continue playing afterwards unless explicitly stopped.
Arabesque has very limited memory and little in the way of branching facilities. As a result, you may find it difficult to accomplish anything significant with it. However, while the language is not Turing-complete due to its inability to emulate the proverbial 'tape,' it is still very useful as an intermediary utility for coordinating messages with other attachments and generating non-branching or minimally branching behavior.