The ARES input handling system is one of the most complicated pieces of technology ever implemented in LSL scripts. Understanding it fully takes time and patience.

Entering messages into the chat pipeline

For ARES to understand that you are attempting to send a message or command, it must first be able to recognize that a command is actually being sent. There are several different ways this is accomplished:

• The chat redirect: Normally, everything the unit types into local chat is captured by the chat redirect. The system daemon _io actively listens on a specific channel (by default, 7770) for chat messages generated by your avatar. RLVa is used to ensure inputs go to this channel. These messages are passed on to the input handler, _input. The redirect is enabled whenever you type /1capture in local chat and disabled when you type !release into the chat redirect itself. Starting with ARES 0.5.6.2, the operating system ships with convenience gestures /release and /capture, which provide a veneer of consistency over these two irregular commands.
• Device and public bus commands: The system daemons _hardware and _baseband both provide remote control functionality to varying degrees on certain channels. In the former case, commands must be passed through by an active (registered) light bus device. (Public bus support for command entry is largely a legacy feature.)
• Local command access: Imitating OpenCollar, commands may be entered with the syntax /1avcommand, where av is the first two letters of the unit's name, and command is any raw system command. The channel number may be changed, but this will also affect the /1capture predicate used by the chat redirect.
• Command triggers: Specific commands may be set up to use the syntax name: event on channel 0, where both name and event are custom values specified by the unit's owner. For example, robot: go home might be configured to teleport the unit to a specific location immediately. Triggers of this sort cannot have dynamic parameters and all their behaviors must be hardcoded expressly.

System extensions such as the UPLINK web console service provide yet more ways to issue commands.

The redirect

To change the channel that the chat redirect operates on, edit the database setting input.channel and restart the _baseband daemon:

@db input.channel 6969 @service baseband restart

It is not possible to make ARES process commands entered on channel 0, unless they are verbal command triggers (see below).

Commands from devices

In addition to commands provided by devices, devices may also call commands with the light bus message command <user> <outs> <command>; this is the method used by ARemote, among other devices. Device commands use the local security rule if the source device and avatar are both present on the sim within 20 meters of the unit, or remote otherwise.

Device commands are sent raw. See how commands are parsed, later in this document, for more information.

Public bus commands

Any message sent to the public bus which is not recognized by the public bus handler (part of the baseband daemon) will be parsed as a system command (always using the local security rule), provided the OS is booted. Conversely, device commands (above) can be processed while the OS is powered down.

Public bus commands are sent raw. See how commands are parsed, later in this document, for more information.

The public bus has a handful of exceptions and unique predicates, some of which have their own security permissions:

public bus input	system command	permission	effect
charge <amount>	n/a	none	adds <amount> kW to the system
ping <ch>	n/a	none	sends a civilian identification message to channel <ch>; see details
identify <ch>	n/a	none	sends a military IFF message to channel <ch>; see details
repair <...>	n/a	none	controls repair functions
menu <...>	@menu <...>	none	accesses the menu system
navigate <...>	@nav <...>	navigate	accesses the navigation system
trigger <event>	@exec trigger <event>	device	activates a command trigger (described below); see relevant command reference page
unlock <password>	@policy unlock <password>	local	attempts to unlock a password-protected unit
policy <...>	@policy <...>	local	see @policy
— commands above this line work while the unit is locked —
say <...>	@input say <...>	chat	simulates unit text input
remark <...>	@exec echo -c <...>	local	sends text to llOwnerSay()

The public bus listens on channels -9999999 and -9999998, which are baseband subservices public and public-alt, respectively. These can be disabled entirely with:

@db baseband.public 0 @db baseband.public-alt 0 @service baseband stop public @service baseband stop public-alt

and re-enabled with:

@db baseband.public 1 @db baseband.public-alt 1 @service baseband start public @service baseband start public-alt

Local command access

OpenCollar users are familiar with a specific command invocation syntax:

/1avcommand

where 1 is a channel number, av is a prefix derived from the target's username, and command is one or more words instructing the system on what to do.

ARES also supports this behavior, and it is enabled by default. It is called local command access, or LCA. Commands issued in this way use the local security rule.

Unlike device commands and public bus commands, LCA commands are parsed by the interpreter named in input.shell, which is typically _exec. See how commands are parsed, later in this document, for more information.

The LCA channel can be changed or even disabled using the following:

@db baseband.lca-channel 2 @service baseband restart

This will affect the channel used by /1capture as well; in the above example, the command is now /2capture, and the /capture gesture (included with ARES 0.5.6.2 redeliveries and later) will need to be updated to match.

Disabling LCA entirely is accomplished by setting lca-channel to 0. This is not recommended, as it will make it difficult or impossible to reactivate the chat redirect.

The LCA prefix defaults to the first two letters of the unit's name as defined in id.name. For example, the prefix av would be automatically generated for a unit named DAX/2 av4tar. LCA prefixes are always expected to be lowercase. To override this behavior, use:

@db baseband.lca-prefix @ @service baseband restart

where @ is the new prefix. Using the examples above, the unit's full LCA command prefix is now /2@ instead of /1av.

To revert to automatic prefix generation, delete the database entry:

@db delete baseband.lca-prefix @service baseband restart

Command triggers

The _baseband daemon also listens to local chat (channel 0) at all times for messages starting with a specific word, which by default is the unit's name (as defined in id.name.) If this word is encountered followed by a colon, comma, or null, and then a space, then the rest of the message is evaluated for the possibility that it might be one of the preset command trigger phrases.

For example, a unit named dolly could be configured with a command trigger called go home, in which case _baseband would listen for one of the messages:

dolly: go home dolly, go home dolly go home

...whereupon ARES would execute whatever system command was associated with that trigger.

To override the name recognized by triggers, add the database entry baseband.trigger-prefix:

@db baseband.trigger-prefix slutbot @service baseband restart

To restore default behavior of using the unit's name, delete the entry:

@db delete baseband.trigger-prefix @service baseband restart

Triggers are defined by the database section trigger. The name of each entry in the section is the command to be used, with the spaces replaced by underscores. The value of each entry is the command to invoke:

@db trigger.greet_me exec say Hello, $name! @db set trigger.sleep power off db set trigger.be_normal persona default

This would define triggers that can be called as follows:

dolly, greet me dolly sleep dolly: be normal

Both triggers and the names that precede them are case-insensitive. Executing a trigger uses the local security rule. Trigger commands are handled as raw commands; see next section.

As in previous examples, the @db command may be used to remove a trigger, e.g. with:

@db delete trigger.sleep

...to remove a trigger called sleep.

It is not necessary to restart any programs after adding, modifying, or removing trigger definitions.

Trigger support is disabled with:

@db baseband.trigger 0 @service baseband stop trigger

And reenabled with:

@db baseband.trigger 1 @service baseband start trigger

How commands are parsed

ARES uses two programs to interpret messages, called _input and _exec. These work together to direct specific behavioral responses to various strings of text.

The _input program is the one you are "talking to" through the chat redirect. It looks for a special control prefix character, such as @, !, or =, and directs the rest of the text to the appropriate destination. If no control prefix is found, then the text is interpreted as a chat message and sent to the output chat filtering chain.

Most commands starting with @ are forwarded directly to the target application with no further processing. For example, the command @id color will invoke the id program with the arguments id color, exactly as it would on UNIX or another conventional operating system. However, there are many useful commands that are built-in to the _exec shell, such as say, which do not correspond to any binary in the operating system. Many forms of command invocation, such as those used by triggers, are in the raw system command format—they do not call the system shell automatically. To ensure a command is processed, pass it as an argument to _exec:

exec say hi

In general, this distinction is only of concern to developers and those doing heavy customization. Both ARemote and local command access process commands through the shell specified by input.shell.

Input directives and built-ins

The following special keywords are recognized by _input independently of any other system component:

command	effect
=ddt ...	Sends a message to the kernel monitor
=prefix <char>	Changes the standard system command prefix (default: @) This must not be a character already in use for another purpose, such as !, =, or /. For safety reasons it is reset in the event _input is restarted.
=terminal	Enables terminal mode: strings are assumed to be system commands unless prefixed; chat messages begin with "
=chat	Disables terminal mode. (See above.)
=alert <num>	Responds to the current alert message with the specified choice (values of 0 through 3 map to hotkeys F2 through F5)
=switch ...	Forwards a command to the WARRIOR weapon switcher
=MSD ...	Forwards a command to the WARRIOR master system display
.text	Invokes a persona preset message; see Personas
!light <message>	Sends a message directly over the light bus, e.g. !light probe to reprobe for devices
!broken	Enables broken effects
!fixed	Cancels broken effects
!working [<reason>]	Enables working effects and shows the disk throbber
!done [<reason>]	Cancels working effects and hides the disk throbber
!lamp on|off	Controls light emission from the controller
!repair	Starts repair effects
!reclaim	Starts reclamation (resurrection) effects
!repaired	Ends repair and reclaim effects
!spark	Plays a spark effect
!fault	Plays a series of spark effects
!release	Disables the chat redirect until the next login; type /1capture to restore normal operation
w <message>	Whispers a message in local chat
s <message>	Shouts a message in local chat
:<message>	Sends a /me message, MU*-style; disabled in most versions of ARES
"<message>	If terminal mode is enabled, removes the leading " and parses the rest as a chat message; otherwise, sends the whole thing as a chat message
anything else	Assumed to be a chat message, unless terminal mode is enabled

The exec shell

The system program _exec is the main dispatch for system commands. It interprets its arguments as a series of space-separated tokens and then instructs the kernel to run the indicated program with those tokens as parameters. For example, the command:

@exec id color

will generally yield identical results to simply calling:

@id color

Importantly, however, exec provides several two features that make it preferable to running raw system commands: built-in commands, device commands, substitutions, and aliases.

Built-in commands

These commands only exist within the exec environment. They are typically called with the standard command prefix, i.e. @ for local usage or using ARemote, or /1xx when using LCA, where xx is the unit's dedicated LCA prefix.

built-in command	description
runaway	Resets all user information (calls @security runaway, bypassing restrictions on normal self-access)
safeword	If restraint is installed, breaks out of any applicable RLV restraints.
alias	Shows a list of defined aliases.
alias <name> <effect>	Defines or redefines an alias. <name> may not be delete.
alias <name>	Reports the current definition of the specified alias.
alias delete <name>	Deletes an alias.
trace [on|off]	If support is compiled, enables or disables logging when executing shell scripts.
to <uuid> <command>	Runs a command (via exec) with a specific output pipe.
from <uuid> <command>	Runs a command (via exec) with a specific input pipe.
do <file> [<args ...>]	Executes a shell script.
nudge	If running a shell script, skips waiting for the current step to finish and begins running the next line.
exit	Aborts the current shell script.
say <message>	Sends text to _input (see above).
jump <label>	If running a shell script, jumps to the line beginning with @label:.
echo <message>	Sends <message> to the user.
echo -c <message>	Sends <message> to the unit using llOwnerSay().
echo -d <message>	Sends <message> to the unit on DEBUG_CHANNEL.
set <variable> <string>	Sets LSD:env.variable to <string>. See Scripting ARES for more information on the features of set.
set <variable> = <expression>	Sets LSD:env.variable to the result of calculating <expression>. See Scripting ARES for more information on the features of set.
set <variable> %undefined	Deletes LSD:env.variable, if it exists.
if <expression> then <command>	Executes <command> if <expression> is true. See Scripting ARES for more information.
service <name> <args>	Sends <args> to the specified system daemon (ring 2) using the SIGNAL_CALL message.
any other text	Interpreted as a command invocation

Command invocation

When _exec is unable to resolve input to a built-in command, even after de-aliasing, the text is assumed to be a command invocation. The command name is matched to an executable through the following steps:

1. First, _exec will check to see if a matching device command exists; if this is the case, a suitable instruction is sent via io_tell() over the light bus.
2. Second, if a program binary is present in ring 3 with a matching name but with a leading underscore, that program will be targeted for execution with SIGNAL_INVOKE. Thus if your user memory has both spam and _spam, the input @spam will always call _spam, never spam.
3. Thirdly, if a program binary is present in ring 3 with a matching name, the command is dispatched appropriately with SIGNAL_INVOKE.
4. Fourthly, if the name contains a period (.), a file with matching name is known to exist in LSD:fs:root, and there is a defined file association handler (see Filesystem Introduction), then exec will attempt to invoke that handler and pass it the filename provided.
5. If none of the above conditions are met, the invocation is a failure and an error message is printed to the user as appropriate.

Most, though not all, ARES programs take arguments as a sequence of straightforward English words, the meaning of which is generally intuitable to the reader:

@db set example-section.example-key example-value @id color a cherry @power all on @set a = 1 + 1

A handful of programs use UNIX-style switches, which use the format -X, where X is a single character. Examples include calc, the _exec built-in command echo, and the unbundled applications ai and corrado. In general, this convention is used when plain, text arguments would be hard to distinguish from other input; these programs generally expect to be fed an entire string of text to parse rather than a series of keywords.

When UNIX-style switches are used, however, they can never be combined into one term and must each be specified as separate arguments.

Substitutions

A substitution is a special keyword that can be used to insert a previously-stored value at a given place in an _exec call. See section in Scripting ARES for more information.

Aliases

An alias is a nickname for a frequently-used command, optionally including parameters. See section in Scripting ARES for more information.

Shell scripts

A shell script is a series of commands stored in a text file for later retrieval and execution. See Scripting ARES for more information.

Chat filtering

Modifying chat messages is called chat filtering. ARES fully supports programmatic alteration of both received and sent messages via the vox facility. These are called the input chain and output chain, respectively. As of version 0.5.7, 16 filter algorithms are included with ARES, including several generic filters that can be configured to perform custom word or sound substitutions.

To set up a chat filter:

1. Open the chat filtering menu
2. Toggle either filter output (to alter what the unit says) or filter input (to alter what the unit hears) to the on state
3. Select a filter from the output filters or input filters submenu
4. Check the help item to determine what flags the filter accepts, if any
5. Activate the filter
6. If the filter accepts flags, choose the configure option and enter a suitable value
7. Go back twice to return to the main chat filtering menu
8. Check output status or input status as appropriate to ensure that the filter and chain are both enabled

The equivalent of the above done using the command line is:

@vox <chain> on @help <filter> @vox <chain> <filter> <flags> @vox <chain>

where <chain> is output or input as appropriate, filter is the name of the filter from the list of available filters, and flags are the configuration options described in the filter's help page.

To remove a filter, repeat steps 1, 3, 5, 7, and 8, but click deactivate instead of activate, or use @vox <chain> <filter> remove.

To disable a chat filtering chain from the command line, use @vox <chain> off.

The standard filters

(TBD)