Note: This is version 0.3.1 of the ARES command reference. It may not match the version provided by your onboard help command. See here for updating instructions.

Advanced Research Encapsulation System
System Manual

Last updated: 10-Feb-2024

System commands: ax, db, device, exec, filter, fs, help, id, input, menu, nav, persona, pkg, power, policy, proc, security, vox
exec Shell built-in commands: alias, do, echo, exit, from, if, jump, say, set, service, to
Daemons (call with service): baseband, effector, hardware, interface, io, repair, status, variatype
System extensions (available separately): dive, domain, lust, restraint, uplink, warrior
Other topics: arena, autoexec, autonomy, basics, combat, expressions, interference, monitor, kernel, public, rules, sources, subsystems, trigger
Meta: license, quickref

Please select a topic with help <topic> or click a link above if using the online help viewer.

If the help command returns the wrong page, or skips the start of the page, then the manual may need to be reindexed. Type help reindex to begin the process.

If you are unsure of where to start, try the topic basics.

Some commonly-used system commands are actually aliases (shortcuts) for other commands. See alias for a list of default aliases.

After release, the latest version of this document will always be available at http://support.nanite-systems.com/ARES
license
ARES System Manual: ARES Software Copyright Licenses (ASCL)

In the text below, <YEAR> is 2022-2024. Substitute this value when including attribution in any distributions.

This version of ARES is copyright <YEAR> by Nanite Systems Corporation (hereafter, the Corporation). It is proprietary software. Its use is subject to the terms of the Nanite Systems EULA ( http://support.nanite-systems.com/?id=216 ).

Preamble. To facilitate community involvement in the ARES ecosystem, we have included the source code for some ARES utilities and system components. These individual files are provided under various terms, described below.

Section 1. Files marked 'ASCL-i' are to be considered proprietary. They are offered to you on a limited basis to facilitate modification and customization.

You may distribute modified ASCL-i files to other ARES users provided they remain full-permissions, are offered free of charge, and retain proper copyright markings. You may not create other derivative works of ASCL-i programs.

The Corporation reserves the right to collect, alter, and distribute such modifications covered by this section, including by adding them to the standard distribution.

We may also take action (as outlined in the EULA) against abusive, harmful, or misleading modifications, as we police other third-party products that represent potential or real harms to the community or the Corporation.

By releasing a modification to code covered under this section, you are donating your work to the Corporation and to its customers.

The Corporation may elect to withdraw ASCL-i licensing for new versions of a file (see 'Unforeseeable futures', below), but this does not affect previously-released versions.

Section 2. Files marked 'ASCL-ii' are provided under a modified copyleft license. Although they appear here in ARES as part of commercial software, they may be used as the basis of derivative, non-profit works that retain a compatible license.

Derivative works of ASCL-ii software must retain proper attribution in documentation and source code, such as: Based on <FILENAME> from Nanite Systems ARES. Copyright <YEAR> Nanite Systems Corporation. Licensed under ASCL-ii.

Additionally, ASCL-ii derivative products must be distributed free of charge and with legible source code. (LSL scripts need not be full permissions; a copy/transfer notecard is sufficient.) A copy of this copyright license must be included.

ASCL-ii code may be used in GNU General Public License (GPL) projects, provided the above attribution is preserved.

Section 3. Files marked 'ASCL-iii' are provided under a 'BSD-style' license. They may be redistributed or used as the basis of commercial, closed-source products so long as the following terms are abided. The ARES SDK uses this license.

Based on code from Nanite Systems ARES. Copyright <YEAR> Nanite Systems Corporation.

i. Redistributions of source code must retain a copy of these conditions, the above copyright notice, and the disclaimer below.
ii. Redistributions in binary form must include the copyright notice in the documentation and/or other materials provided with the distribution as defined above.
iii. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

The ASCL-iii license is intended to be compatible with a three-clause BSD license.

Section 4. Files marked 'ASCL-iv' are closed-source, proprietary, commercial code. Aside from the following disclaimer and the copyright text, you may not distribute them under any circumstance for the foreseeable future.

Section 5. Unforeseeable futures. The Corporation retains full control over ASCL-i and -iv code. It may, at any time and at its sole discretion, elect to release this code under a different license.

For example, ASCL-i coverage may be withdrawn to protect trade secrets in new versions of relevant code, or to convert ARES into a copyleft project in the event that the Corporation cannot continue to operate on a commercial basis.

Section 6. Disclaimer. The following must be included with all ASCL-licensed code:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.

IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DAMAGES HOWEVER CAUSED ON ANY THEORY OF LIABILITY ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This is an abridged version of the BSD disclaimer. The text is interchangeable with that disclaimer.

Section 7. Further Information. Additional insight regarding Nanite Systems copyrights can be obtained by e-mailing support@nanite-systems.com. The latest version of this license can be obtained by visiting http://nanite-systems.com/ASCL.
permalink return to top
basics
ARES System Manual: Basics


Booting Up


To boot up your ARES installation, you need the following:

1. A main controller unit (battery socket).
2. A copy of ARES itself.
3. A battery.
4. An RLVa-compatible viewer. As of this writing, the only compatible viewers are:

    Alchemy
    Black Dragon - obsolete/deprecated (no setsphere support)
    Catznip
    Firestorm
    Genesis
    Singularity

  Please note that Marine Kelley's RestrainedLove viewer (and its derivatives) will not work.

Once these requirements are met, attach ARES, the main controller, and the battery, in that order.

If done correctly, you should hear the sound of the battery sliding into the socket and connecting. If the battery does not automatically connect, you may need someone else to touch it. This is normal.

Finally, you can power the system on by typing '@on' in local chat.


Customizing ARES


Most of the system's user-accessible files are stored in linked prim #3, which is the model badge in the middle of the bottom of the screen.

To edit your ARES files, press Ctrl-3 to open the Edit tool, and then Ctrl-Shift-E to enable 'Edit linked' mode. Then, click on the model badge. The 'Content' tab of the editor window should then display all the application files.

Link 2 contains the system services, as well as the graphics assets used by the interface daemon. You can access Link 2 by first selecting Link 3, then pressing Ctrl-Comma to cycle to the previous link.
permalink return to top
quickref
ARES System Manual: Quick Reference

When the unit is self-operating, every command must start with @. To control a unit in local chat, start each command with /1??, where ?? is the first two letters of the unit's unprefixed name.

So, if an entry in this manual says to type fs, then a unit named 'CX b0b' would type @fs, and its owner would type /1b0 fs

Commands are used without prefixes inside shell scripts (see input), when using a remote console, or when using terminal mode.


System Software


ax: lists installed software packages
db: reports status of LinksetData (LSD) database
fs: lists all files
id: summarizes the unit's identity
persona: lists available personas
power: reports current power status
security: reports current users, guests, and bans
vox: reports status of chat filtering system
db <entry> <value>: modifies a database entry
db delete <entry>: removes a database entry
db drop <section>: deletes an entire database section
device probe: reconnects all devices
exec do <file>: executes a shell script
fs match <pattern> (ls): lists files matching a pattern
fs open <file>: opens a file (requires a file association based on the extension)
fs refresh: updates the filesystem (triggered automatically on local changes - but see sources)
<entry>"><entry>: lists help pages (this command!)
id chime load <scheme>: loads a chime (startup and shutdown sound) scheme
id color load <scheme>: loads a color scheme
id name <new name>: updates the unit's name
id volume cycle: changes the volume of interface sounds
input say <message>: parses text as though entered by the unit
nav add <name> here|<slurl>: add a bookmark
nav follow [<key>]: follows the specified object (or you)
nav remove <name>: remove a bookmark
nav tp|warp|jump <name>|<slurl>|me: TPs to a bookmark or SLURL
persona <persona>: activates a persona
pkg close <archive>: closes a package archive
pkg extract <archive> <file>: extracts a file from an opened package archive
pkg open <archive>: opens a package archive
power reboot 30: reboots the unit in 30 seconds (see power for more examples)
power video on: turns on the video subsystem (see power for more examples)
proc tasks detail (ps): lists all running processes
proc unstick <program> (reset): resets a program in user memory
security <rule> <value>: changes a security rule (see rules)
security ban <UUID>: bans an avatar
security forget <UUID>: removes everything associated with an avatar
security guest <UUID>: makes an avatar into a guest
security rules: lists security rules (see rules)
security user <UUID>: makes an avatar into a user (see security for other ranks)
type <filename>: prints the contents of a text file
vox input on: enables filtering of unit hearing
vox output on: enables filtering of unit speech
wiz clear: closes the wizard interface (see wiz)
xset <variable> <...>: stores output of the command <...> in env.<variable> for later use


Common Software Packages


ARES does not come with any of these programs installed by default, and not all of them will be available at launch. However many can be installed from the ax servers in Eisa. (see ax)

ai: sends a message to OpenAI for processing with ChatGPT (gpt-3.5-turbo) (API key required)
spy <uuid>: reports various metrics about the target object or avatar, including any (non-HUD) attachments
toot: posts a message on the social network Mastodon (some setup required)
fortune: retrieves a GNU fortune message from myNanite
land: multitool for various land-related functions in SL
lslisp: LSLisp programming language interpreter
mail: sends email
news: displays alerts whenever a new item is posted to an RSS or Atom feed
tell: sends a message directly to a UUID on any channel
restraint: RLV relay
calc <numeric expression>: performs arithmetic
define: looks up wiki definitions
domain: downloads and synchronizes settings with a domain server
hookup: directory listing of ARES users, organized by interests
lore: looks up information on a local RP wiki
mantra: assistant for meditation and hypnosis
scidb: looks up information in various chemical and biomedical databases
wander: teleports you to a random landmark submitted by other users (remember StumbleUpon?)
web: helper utility for downloading web pages
permalink return to top
kernel
ARES System Manual: psyche Microkernel

Psyche is the task scheduling module that powers the current version of Nanite Systems ARES. Its main purpose is to allow interprocess communication. It also queues messages and ensures their timely delivery for sleeping programs.


ARES Interprocess Communication


In Companion, OpenCollar, and most other large LSL software, scripts in a single linkset communicate primarily through a high-speed interface called link messages. These have no size limit and are efficient for small projects.

However, link messages are hard to filter out. Every script in the target prim is notified when a link message occurs. In Companion 8.4 this meant that every message could trigger 20 or more scripts.

ARES instead uses chat channels as much as possible, the same way scripts in different prims communicate. Each script has its own channel, and each listener only responds to messages from the kernel and from system services.

As a result, idle programs are truly idle and use zero script time, even when waiting for messages.


Kernel Debug Commands


To debug the kernel, send linked message 0x1000 (4096) to prim 1. The following commands are supported:

- a: Dump process address lookup table
- d: Dump daemon info table
- da: Dump daemon address lookup table
- e: Dump event hooks table
- f: List free and used memory
- m: Dump module info table
- q: List waiting job messages
- reset: Reinitialize the kernel
- t: Dump timers table

If the kernel was compiled with debug mode enabled, additional commands may be available:

- s: Toggle verbose message logging. ('Strong' debugging.)

All message output is via the echo() macro (llOwnerSay).

The =ddt built-in of input sends this message, e.g. typing =ddt m will cause the kernel to dump the module info table.

See also monitor, a utility for restarting and swapping kernels.
permalink return to top
monitor
ARES System Manual: Kernel Monitor

The monitor is a program in ring 1 (the linkset root) that provides quality-of-life functions for managing the kernel. It may safely be deleted, but it is of value to most users, as it resets the kernel in case of a crash.

(This module was previously called 'hypervisor'. In Companion, the term 'hypervisor' was sometimes used loosely to refer to both the package manager and the user memory delegate; this program and its duties are unrelated to either.)

The monitor is not part of the OS and cannot be invoked with a system command. Instead it may be accessed by right-clicking on ARES in the unit's inventory and choosing 'Touch'. This will present the unit with a text prompt.

To send a debug command to the kernel (as described in kernel), enter 4096 <command>, e.g. 4096 reset to instruct the kernel to restart itself if possible. This is equivalent to the input built-in =ddt reset.

To change kernels, type k <kernel>, e.g. k _psyche to load the default Psyche kernel image. Inactive kernels consume no resources.

If the kernel is non-responsive, the 4096 reset command will not be received. If this occurs, use the k command to reload the current kernel.


Logging


The kernel monitor also provides system event logging functionality.

The command l will toggle direct logging of all incoming kernel calls.

The command s will enable advanced logging, which captures events after the kernel parses them and provides additional context about the kernel's decisions. This requires the verbose logging (_psyche.debug2) kernel.


Standard Kernels


This version of ARES includes the following kernels:

- _psyche is a production kernel.
- _psyche.debug includes standard logging by default and will report certain events, such as timer triggers and stuck jobs.
- _psyche.debug2 has 'strong' (verbose) logging enabled by default and will provide detailed information about each instance of message-passing. This should only be used on a minimal install, as it has very high overhead.
- _psyche.lpo is an experimental production kernel. It was compiled using LSL-PyOptimizer and mcpp, giving it extra free memory and reducing the chance of long-term crashes.
permalink return to top
combat
ARES System Manual: Combat

As an operating system for both military and civilian robots, ARES includes a fully-featured damage meter, referred to as system integrity, and a heat model which supports receiving environmental data from a regional weather station.

The combat system is designed to be fun, safe, and highly resistant to abuse. To that end, it includes two protective modes:

- Typing service repair dqd will toggle 'degreelessness mode', which prevents the unit's integrity from being modified. This is also a convenient way to disable auto-repair for roleplaying damaged states.
- Typing service repair ooc will toggle 'out-of-character mode', which prevents integrity changes, blocks all interference, and (if installed) automatically rejects sexual stimulation.

For convenience, these can be accessed with the default aliases @nsdqd and @ooc, respectively.

To keep combat balanced, all characters currently have 100 maximum integrity points, although future updates will allow values from 25 to 400.

When damaged, the unit will start to repair itself automatically after 10 seconds. The auto-repair function has its limits, however, and will only restore 90% of damage taken. However, it will always restore the unit to at least 40% of its maximum.

Proper repair can be obtained by having someone else use a hand-held repair tool, by visiting an ARC or ExARC repair station, or using a diagnostic or repair bed. Many models are available for purchase.

A destroyed unit is eligible for reclamation, which is a special repair process that restores it to 25% of its maximum integrity over the course of 20 seconds. Afterward the unit can boot by typing @on, as normal.

Heat, cold, and extreme pressure can also cause damage. A unit trapped in a low-pressure environment will rapidly overheat.


Damage Sources


In typical combat, ARES only accepts damage by detecting collisions.

ATOS projectiles are named ATOS:<x>, where <x> is the number of integrity points that the unit should lose when damaged. Negative amounts are allowed, for repair.

This approach is also used by the VICE and LBA combat systems. All NS combat systems recognize VICE and LBA projectiles. Additionally, high-speed projectiles will cause damage based on their relative velocity at time of impact.

Further documentation on supported projectiles can be found at http://develop.nanite-systems.com/combat.


Damage Folders


ARES looks in #RLV/~ARES/damage for folders named 0, 20, 40, 60, 80, and 100. It will attach and detach these folders as the unit is damaged. The current folder is always the highest number that is within your current percentage.

For example, a unit that has 21/25 integrity points is actually at 84% integrity. ARES will therefore attach the folder ~ARES/damage/80. After repairs to full strength, it will switch to ~ARES/damage/100.

For efficiency, it is recommended to keep these folders as basic as possible; typically the 100 folder should contain nothing.

The ~ARES prefix can be changed by setting the env.rlv database entry. See db for more information.
permalink return to top
arena
ARES System Manual: ATOS Arena Protocol

ATOS/A (Arena) is a planned server product intended for use in setting up designated combat areas. It will provide scoreboard functionality for various classic first person shooter game modes, like team deathmatch and capture the flag.

ARES sends and receives some ATOS/A messages to report kills to other ATOS clients. Disabling baseband.arena will prevent the receipt of these messages.

See combat for more information on the ATOS combat system used by ARES and other NS products.
permalink return to top
autonomy
ARES System Manual: Autonomy Control Systems Protocol

Autonomy Control Systems is a robotics company whose protocols have formed the basis of an ad-hoc standard for robot communication. ARES implements ACS-compatible messages for charging, electromagnetic interference, and version-checking.

Not all charging uses the ACS protocol. Environmental charging is an NS-specific technology that uses the public bus instead. See public.

ACS handshaking and superficial communications like interference occur on channel 360. The majority of the protocol occurs on a private channel negotiated by the host.

ACS protocol handling is governed by the baseband daemon.

ARES does not fully support interoperability with ACS devices, as the majority of them have idiosyncratic purposes that make no sense in the context of an NS unit. However, all NS units are designed to use ACS chargers.

Certain scanners and handshaking devices do use the ACS protocol, including the NanoCom Region Monitor, which is a Nanite Systems product.

The ACS protocol is also used to implement electromagnetic jamming signals. See interference for more information.

Documentation on the published portions of the ACS protocol is available at http://develop.nanite-systems.com/resources/ACS-charging.pdf or directly from Autonomy Control Systems.
permalink return to top
public
ARES System Manual: Public Bus

The public bus is a network interface used by ARES, Companion, and other NS operating systems to control and interact with units. It differs from the private bus (which is not supported in ARES) in that it always uses the same channel, -9999999.

The public bus's main purpose is to allow reception of system commands. Under ARES these are parsed directly as command invocations, provided the command comes from an object owned by a user with the 'remote' permission (see security).

Several important non-command signals are also sent through the public bus. They include:

- Environmental charging. Many charging sources, including NS SitAnywhere Chargers and Wireless Charging Nodes, use environmental charging.
- All forms of external repair, such as repair tools, ARCs, and diagnostic beds.
- Ping and identify (IFF) messages.
- Navigation for path-following.
- Event triggers. These allow execution of exec scripts (.as) when certain events occur, such as connecting to a charger.
- Chorus.

A complete list of messages specific to the public bus can be found at http://develop.nanite-systems.com/public
permalink return to top
trigger
ARES System Manual: Triggers

Triggers allow the unit to react to specific verbal commands issued in local chat by automatically executing system commands. Each trigger must be defined separately in the trigger database section.

In Companion and Clockwork, triggers were called reactions.


Creating Triggers


To create a trigger, use the db command:

db set trigger.<name> <action>

Trigger actions are fully preset: they do not accept arguments. However, the syntax exec <...> can be used to allow other forms of environment variable substitution (see input), for example:

    db set trigger.greet_me exec say Hello, \$user!

...will cause the unit to say 'Hello, <name>!' when triggered. (Be mindful of the backslash before the $ sign: otherwise variable substitution will occur immediately when creating the trigger, substituting *your* name instead.)

Underscores in <name> correspond to spaces in the verbal command. Triggers must be defined with lower-case names.


Triggering Triggers


First, make sure the trigger subservice is started:

(exec) @service baseband start trigger

Thereafter, anyone other than the unit may speak:

    <prefix>: <action>

For example, 'dolly: go home' will instruct a unit named 'Dolly' to run the command stored in trigger.go_home, if it is defined. The colon in the example above may be replaced with a comma or omitted entirely.

When invoking a trigger, the command is case-insensitive.

Only users with the 'local' permission (see rules) may activate triggers.

The trigger prefix is specified by the baseband.trigger-prefix database setting. If undefined, the unit's name (id.name) will be cached. In case of a name change, you must restart the trigger subservice manually to update the trigger prefix.


Example Triggers


    db set trigger.greet_me exec say Hello, \$user!
    db set trigger.go_home nav tp home (make sure you create a 'home' bookmark first)
    db set trigger.sleep power off
    db set trigger.be_normal persona default
    db set trigger.initiate_self_destruct exec detonate (device commands must be routed through exec in this manner)
permalink return to top
interference
ARES System Manual: Interference

Electromagnetic interference (EMI) is a general term for any form of radiation that adversely affects system operation.

In general use, 'interference' more specifically indicates any unexpected signals that cause behavior contrary to design parameters, but for legal reasons, NS units are designed to specifically accept five bands of EMI.

- C-band radiation ('hard' X rays in the range 80 to 105 keV) interferes with cognition and thought generation. Common sources include faster-than-light travel (teleport) wakes and nuclear fission.
- M-band radiation (ultra high frequency (UHF) radio at 10 micro eV, or 2.449 GHz) interferes with motor control. Microwave ovens emit frequencies in this band.
- N-band radiation (gamma rays in the range 1.1 to 1.2 MeV) interferes with memory access, impairing GPS and identification. Common sources include airport scanners, gamma-ray bursts, and nuclear fission.
- S-band radiation ('soft' X rays in the range 3 to 7 keV) interferes with speech production. Most S-band radiation comes from medical scanning equipment.
- Y-band radiation (extremely high frequency (EHF) radio at 413 meV, or 99.93 GHz) interferes with sensory input. Teleport wakes, short-range radar, and active denial weapons emit this frequency.

Although no system is perfectly reliable at preventing the undesirable effects of EMI, radiation mitigation is an active area of research, and there are several robust solutions available, including Meissner-effect shields and the Jovian ECM suite.

See combat for further information on avoiding interference.
permalink return to top
device
ARES System Manual: Device Management Utility

device probe: searches for available devices
device [info] <address>: shows information about the specified device
device <address> eject: turns off, forgets, and unbolts the specified device
device <address> peek: send specified device's status information to current user (if supported)
device <address> poke: open specified device's control interface (if supported)
device <address> restart: starts a device probe, but only for the specified device
device <address> <message>: sends a raw light bus message to the specified device

The device management utility, _device, is the user-facing front end of the hardware daemon.
permalink return to top
hardware
ARES System Manual: hardware Daemon

(input) @service hardware probe: probes for connected light bus devices
(input) @service hardware debug [off|on|toggle]: displays incoming messages in the console
(input) @service hardware restart: restarts the hardware manager
(input) @service hardware <address> [<action>]: sends a message to the indicated address

The ARES hardware daemon serves as the primary point of contact for light bus devices. A device is any attachment or rezzed object designed to interface with ARES using one of these protocols.

Note: The device utility is recommended as an interface for the hardware daemon.

The equivalent of the hardware daemon in Companion was called puppet.


Light Bus Devices


The majority of devices designed to interface with ARES and Companion do so primarily or exclusively via the light bus, which originated as a control system for lighting attachments.

Devices using the light bus can access a wide range of information about the unit, including its name and color settings. However, a device must register with the device manager before it can modify anything.

Unregistered devices are not displayed in the interface, and the system may not be aware of their presence. Consequently they are also known as 'passive' devices, whereas devices that use registration are considered 'active' devices.

Certain devices originally designed for Companion depend on messages that trigger internal functions of that operating system. These devices cannot be understood by ARES and must be updated by the manufacturer.

Documentation on the light bus protocol is available at http://develop.nanite-systems.com/light_bus or in the ARES SDK.
permalink return to top
io
ARES System Manual: io Daemon

input purge: Empties stale pipes.
input debug: Reports status of the io daemon.
input restart: Restarts the io daemon.

The io daemon manages a text forwarding system known as 'pipes.' Pipes are modelled on the same concept in POSIX (Unix, Linux, etc.) systems.

Whenever an application in ring 3 (user memory) needs to receive chat messages, send chat messages, or forward text to another ring 3 program, it does so by creating a rule with the io daemon, called a pipe.

Users rarely need to interact with the io daemon directly, but it can be useful to understand how it functions for debugging purposes. The command input debug will list the current pipes.

Typical output of input debug might look as follows:

· 00000000-0000-0000-0000-000000000010 · 0 · 2 ·  ·
· 00000000-0000-0000-0000-000000000020 · 0 · 2 ·  ·
· 00000000-0000-0000-0000-000000000100 · 0 · 2 ·  ·
· 43524553-5841-4e41-4455-434c49454e54 · 7 · 1 · ax · 00000000-0000-0000-0000-000000000000
· 00000000-0000-0000-0000-000000000001 · 14 · 1 · _input · d69ca06e-aa22-49e4-86e1-42677e26f3f5
· 5b196468-a47b-ad5d-87f4-e463ecc8e006 · 0 · 3 · filter bimbo · 00000000-0000-0000-0000-000000000a02
· 7e3a8ca1-e8b1-1f3d-30df-a22c46ddb409 · 0 · 3 · filter mumble 11 · 5b196468-a47b-ad5d-87f4-e463ecc8e006
· 00000000-0000-0000-0000-000000000a01 · 0 · 3 · filter replace honey · 7e3a8ca1-e8b1-1f3d-30df-a22c46ddb409
· 00000000-0000-0000-0000-000000000a02 · 0 · 4 · _input output · d69ca06e-aa22-49e4-86e1-42677e26f3f5

The first column indicates the pipe's unique identifier. These are sometimes randomly-generated, but many system functions use predetermined keys such as 00000000-0000-0000-0000-000000000001, which is the unit's chat input redirect.

The third column indicates the pipe's type:

- Type 1 indicates an input pipe, which listens for chat on a predetermined channel number and sends results to the specified command in the fourth column.
- Type 2 indicates an output pipe, which forwards chat to a UUID on a specific channel. If no UUID is listed in the fourth column, the result is sent to the whole region. The first three pipes in the example are used for whisper/say/shout output.
- Type 3 indicates a non-volatile invoke pipe. Messages passed to these pipes will trigger command executions akin to running system commands normally, but with the input stream set to the pipe UUID.
- Type 4 indicates a non-volatile notify pipe. These are similar to invoke pipes but are used for specific function calls; in the example above, NOTIFY _input output informs the input program that vox is done parsing an outgoing chat message.
- Type 5 indicates a file pipe. These are used by fs to provide data to user applications upon request. File pipes are volatile.
- Type 6 is a volatile invoke pipe. These are created to pass data when chaining commands, e.g. with the xset program.
- Type 7 is a volatile notify pipe. These are typically used by programs making calls with the requests API, such as receiving data from the web.
- Type 8 is a non-volatile transport pipe. These simply forward messages to the next pipe in the chain. vox pipelines use a transport pipe when the chain is enabled but no filters are active.
- Type 9 is a volatile transport pipe. These are not currently used by any program.

The distinction between volatile and non-volatile pipes is that volatile pipes are assumed to serve a temporary purpose and will be destroyed when ARES is rezzed (i.e., the next time it is re-attached or the unit logs in.)

Programs will naturally attempt to close their input and output pipes when they are done processing invoke messages. This is only successful if the pipes are volatile.

The equivalent of the io daemon in Companion was an experimental module called transceiver.
permalink return to top
interface
ARES System Manual: interface Daemon

(input) @service interface

Generates the majority of the HUD (heads-up display). The HUD provides real-time information to the unit during normal operation.

For performance, the actual updating of the bars on the HUD is accomplished directly by other daemons. Most of the bars are managed by status, but baseband handles integrity display.

The menu-related functions of the HUD are handled by the variatype daemon.


Settings


The HUD is highly configurable and makes use of several settings, stored in the interface section:

interface.sound.volume (default: 1.0): volume of sounds for the interface to play
interface.sound.go (default ef4504ea-3705-c972-4b34-4709c5656fee): sound to play when navigating the menu
interface.sound.deny (default c797d938-7333-b064-bb43-301e5bfbdfdd): sound to play when menu navigation is rejected
interface.sound.act (default 46aa7a95-f60c-a1cf-aec0-8964d74679ab): sound to play when activating a menu item
interface.sound.menu-open (default 0caefdf3-9e65-b3ed-388c-86892958cd4b): sound to play when opening the menu
interface.sound.menu-close (default ea675f3a-7595-8c28-c89c-5531d436541a): sound to play when closing the menu
interface.sound.shield-down (default 348fcd3d-7993-54fb-720c-c5ebc42de505): alarm to play when shield is at 0 power
interface.sound.env-alarm (default 5db9d9d6-6eda-485e-6436-e97dfdc1983c): alarm to play when temperature is dangerous
interface.sound.damage (default d248834e-ae0d-a844-8a98-de6cdaa67760): sound to play when unit loses integrity
interface.sound.repair (default 5b93518c-2a6d-baef-3fc2-ee3af6cf74a4): sound to play when unit gains integrity
interface.sound.alert (default 6cd918e0-2170-26f3-0706-5b3b10b4d0df): sound to play when an alert is shown
interface.sound.alert-dismiss (default 08d80c61-8c9e-3a3b-7855-4f8d17ccc791): sound to play when an alert is cleared or expires
interface.sound.test (default 971afde2-73e2-5dd8-6c8a-6c7ee25c7411): sound to play when adjusting interface volume
interface.compass.enabled (default 1): display the compass at the top of the screen?
interface.compass.offset (default <0, 0, 470>): offset for displaying the compass widget
interface.gauges.offset (default <0, 0, -468>): offset for main HUD bars and badge
interface.height (default 1008): height of camera viewport (in pixels), measured from bottom of menu bar to bottom of window
interface.height-mlook (default 1027): height of camera viewport when in mouselook, measured from bottom of caption bar to bottom of window
interface.devices.offset (default <0, -860, 0>): offset for devices panel
interface.devices.scale (default 2): scale multiplier for devices panel
interface.altimeter.enabled (default 1): display the altimeter widget?
interface.altimeter.offset (default <0, 380, 0>): position of altimeter widget
interface.speedometer.enabled (default 1): display the speedometer widget?
interface.speedometer.offset (default <0, 408, -226>): position of speedometer widget
interface.crosshair (default 3): crosshair to show from i_crosshair (0 = hide, 16 = artillery)
interface.sexuality.offset (default <0, 0, -404>): position of sexuality widget
interface.warning.offset (default <0, 768, 384>): position of static warning messages
interface.menu.offset (default <0, -540, 448>): position of menu system (used by the variatype daemon)
interface.alert.offset (default <0, 768, 416>): position of the alert widget (used by the variatype daemon)
interface.alert.time (default 10): timeout for alerts that don't require user input
interface.sitrep.enabled (default 1): display sitrep? (bars below warning messages)
interface.sitrep.offset (default <0, 839, 237>): position of sitrep bars
interface.fov (default 60): field of view in degrees, used for positioning nav lock and target markers
interface.badge (not undefined by default): UUID to override model badge (should be 256x128 transparent white)
interface.devices.icons: specify HUD icons for devices (see interface.db for more explanation)

The offset values above are LSL vectors scaled to pixel dimensions. The middle of the screen is <0, 0, 0>. Because Second Life uses right-handed vector algebra with an x-facing forward direction, the interpretation is a little unintuitive:

- The first number is the depth coordinate. Interface elements with higher depths are placed farther away from the screen.
- The second number is the horizontal coordinate. Higher values are further left.
- The third number is the vertical cordinate. Higher values are further up.

The bundled db utility can be used to adjust these settings. The included file interface.db contains the above defaults and can be loaded with @db load interface.db.
permalink return to top
status
ARES System Manual: status Daemon

(input) @service status

System status manager. Manages the battery, fan speed, and internal temperature.

status did not have a direct equivalent in Companion. It combines parts of power and sentinel.

(input) @service status update: Instructs the daemon to reload settings (see below).


Settings


status.bolts (default 0): may the unit detach the system and associated hardware? (see policy)
status.capacity: exact battery charge limit, determined by querying battery device
status.charge: exact battery charge level, determined by querying battery device
status.charge-ratio (0.0-1.0): fractional battery charge level
status.cost-fan (default 100): power draw of cooling system at full strength (scales dynamically)
status.cost-fly (default 500): power draw caused by flying
status.cost-jump (default 500): power draw caused by jumping
status.cost-run (default 300): power draw caused by running (added to walking, below)
status.cost-walk (default 200): power draw caused by walking
status.drainprotect (default 1): refuse environmental charging messages with negative values?
status.draw (default 670): current power usage of all subsystems
status.load (default {}): current external power loads caused by devices
status.on (default 1): whether the system is currently powered on
status.state (default 4194303): a bitmask representing which subsystems are currently enabled
status.temp-units (default 0): whether to display temperatures in degrees Celsius (0), degrees Fahrenheit (1), or Kelvin (2)

The bundled db utility can be used to adjust these settings. If the status section is damaged, consult the default.db and power.db files for factory defaults.
permalink return to top
effector
ARES System Manual: effector Daemon

(input) @service effector

System RLV manager. Manages subsystem restrictions, visual and sound effects, interference, damage folder loading (see combat), and external teleports.

Most features of effector are controlled through the power program.

As effector's main purpose is to track active RLV restrictions, it is similar to the bonds script from Companion.

(input) @service effector restart: Restarts the daemon. This is not recommended as it may create an inconsistent state for RLV relay and power restrictions.
permalink return to top
baseband
ARES System Manual: baseband Daemon

(input) @service baseband

Controls integrity, repair, charging, and various types of networking.

baseband did not have a direct equivalent in Companion. It combines features of coil, sentinel, bonds, and others.

(input) @service baseband: Displays the status of all supported network services.
(input) @service baseband <network service> start|stop|restart: Controls the status of the specified network service.
(input) @service baseband charge <action>: sends a message to the current ACS charger (if connected)


ARES Network Services


Like the POSIX inetd daemon, the ARES baseband daemon provides a uniform management interface for several built-in network services that would otherwise require their own individual binaries.

baseband includes:

arena: interactions with the ATOS/A protocol (see arena)
autonomy (channel 360): Autonomy Control Systems charging and interference (see autonomy)
lca (channel adjustable; default 1): local command access, similar to OpenCollar's /1<prefix> commands
orix (channel -15180925): ORIX ping response, used by Autonomy Control Systems facilities
public (channel -9999999): standard NS public bus (see public)
stargate: (channel -900000): external FTL support using the Alteran Stargate protocol (required for NS Telos pads)
trigger (channel 0): detects and executes verbal commands spoken in chat by authorized users (see trigger)
weather: client to query environmental information about current temperature, humidity, and air pressure from an NSMS Weather Station in the same region


Settings


baseband.arena (default 1): enable ATOS Arena protocol
baseband.lca_channel (default 1): channel to listen on for prefixed local command input; 0 = disabled
baseband.lca_prefix (no default): prefix to use for local commands; if unspecified, takes first two letters from id.name setting
baseband.orix (default 1): enable receipt of ORIX messages (pings only)
baseband.public (default 1): enable receipt of NS public bus commands (see above)
baseband.stargate: (default 1): enable Alteran Stargate external FTL protocol (required for NS Telos pads)
baseband.trigger (default 1): enable verbal triggers on channel 0 (also known as 'reactions')
baseband.weather: (default 1): enable NS meteorology protocol

The bundled db utility can be used to adjust these settings. If the baseband section is damaged, consult the default.db file for factory defaults.
permalink return to top
repair
ARES System Manual: repair Daemon

(input) @service repair [status]: Reports current integrity values and repair status.

The repair daemon tracks damage and mediates the repair process.

(input) @service repair ooc: toggles OOC mode, disabling DQD if active
(input) @service repair dqd: toggles DQD mode, disabling OOC if active
(input) @service repair inflict [projectile|crash|heat|cold|special] <amount>: damages the unit
(input) @service repair restart: restarts the daemon


Settings


repair.autorepair (default 1): enable self-repairing
repair.reclamation (default 1): enable self-reclamation

repair.autorepairing (default 0): whether the unit is currently repairing itself
repair.ext-repair (default 0): whether the unit is currently being repaired by an external source
repair.integrity (0.0-1.0): current system integrity
repair.max (0.4-1.0): current maximum integrity (lowered by autorepair)
repair.dqd (default 0): whether degreelessness mode is enabled
repair.ooc (default 0): whether out-of-character (OOC) mode is enabled

As with most other daemons, repair must be restarted for changes to these values to take effect. Using the input handler, type @service repair restart (otherwise, exec service repair restart)
permalink return to top
variatype
ARES System Manual: variatype Daemon

(input) @service variatype

Provides the VariaType text engine. This is used by the on-screen menu system and for displaying detailed alert messages.

Developer documentation for displaying alerts can be found in api.h.lsl in the ARES SDK.

See interface for information on the settings supposed by the variatype daemon.

variatype did not have a direct equivalent in Companion.
permalink return to top
db
ARES System Manual: db Utility

db [status]: lists extant sections and the current status of the LSD system.
db u|usage: lists all sections and pipe buffers, and their sizes.
db show <section>[.<key>]: prints contents of the specified section or key.
db [set] <section>[.<key>] <value>: modifies the specified section or key to contain a new value. The set keyword is mandatory if writing to a whole section.
db append <section>.<key> <value>: as set, but appending to existing contents.
db drop <section>: delete an entire section.
db delete|remove <section>.<key>: delete only the specified key.
db toggle <section>.<key>: alternates a key's value between 0 and 1.
db load <file>: load a text file from the file system (see fs) and add its entries to the database, overwriting any conflicts.
db clone <section>[.<key>] <section>[.<key>]: copy data from one section or key to another, overwriting existing contents.

If no recognized command is specified, the behavior depends on whether or not a space is present in the command. If a space is present, set is assumed. Otherwise, show is assumed.

The db utility provides tools for managing the system's LSD store (linkset datastore), which a shared memory heap used for message pipes, system and application settings, reading files, and more.

Unlike Companion, ARES has no database daemon. The LSD API allows programs to directly access and manipulate LSD data with synchronous calls, which is much more efficient.

When an LSD entry is used to store configuration settings, it is referred to as a 'section'. Sections are stored in the JSON file format and contain multiple 'keys', which represent individual settings.

Keys may be structured hierarchically depending on the data involved. For example, vox.output.enabled is a subkey of vox.output, which is a key that resides in the section vox.

Note that Linden Lab uses the word 'key' to refer to all string identifiers, such as JSON entries, LSD entries, items in the experience datastore, the UUIDs of SL objects, etc.

LSD entries that begin with fs: are filesystem listings. See fs.

LSD entries that begin with m: are menus. They use the same format as other db sections. See menu.

LSD entries that begin with p: are pipe buffers. These are only visible in the db command when issuing db usage, and are usually deleted after reading. If you see a pipe buffer lingering, delete it with input purge.


Loading database entries


ARES comes with some sample database files which can be loaded in case of a serious mistake, or to restore the system to factory defaults:

- badge.db specifies the default badges shown for various system models on the HUD interface
- default.db covers the sections baseband, id, input, nav, status (partially), and trigger
- font.db defines the default variatype fonts
- fs.db covers the default filesystem settings
- interface.db covers the interface section
- menu.db covers the standard system menus
- power.db covers the sections power and status (partially)
- security.db covers the security system
- vox.db covers the vox and filter sections

These can be loaded with the command db load <name>, e.g. db load default.db. As with other system files, they are overwritten during an update, so make your own .db file if you wish to store your settings in this format.

db can  read a few special directives when loading .db files:
    SET <section>.<key> <value> sets the specified value, creating the section and key if necessary. (This is the default behavior - you may omit SET for brevity)
    APPEND <section>.<key> <value> will assume the entry is a JSON list ([]) and append a new <value> to the end.
    DELETE <section>.<key> will delete the entry.
    CREATE <section>.<key> will create the entry only if it does not exist.
    DROP <section> will delete an entire section.
    MERGE <section>.<key> <json> will iterate over the keys of <json> and add them to the existing data in <section>.<key>. This is a shallow copy only; nested values will not be merged properly.

These directives are case-insensitive. Aside from DROP they also have abbreviations:

    SET is =
    APPEND is ++
    DELETE is -
    CREATE is +
    MERGE is +=

Similar directives are also used during database upgrades when new ARES versions are installed.

For more information on the JSON file format, see https://en.wikipedia.org/wiki/JSON

The database daemon in Companion was called balance.
permalink return to top
censor
ARES System Manual: filter Text Filter Utilities

filter censor <flags>: Removes words considered objectionable.

Flags format: Specify the subkey of censor within the filter database section which contains an array of words to censor. Entries should be in lower case.

By default, the database includes one list of censor words, profanity.

An owner can create new lists with a command such as

    db filter.censor.dog ["walk", "vet"]

which can then be loaded with filter censor dog or by entering dog into the filter configuration menu.

censor is a layer 0 (semantic) filter. It will be applied to the text before any filters of a higher layer.
permalink return to top
slang
ARES System Manual: filter Text Filter Utilities

filter slang <flags>: Inserts randomly-selected words and phrases into text to affect a style of speaking.

Flags format: Specify the subkey of slang within the filter database section which contains 'pre', 'mid', and 'post' arrays, each containing words to inject.

By default, the database includes one list of censor words, airhead.

Run the command db filter.slang.airhead to see how this is set up. Each sentence will be modified with one entry from each of the three lists.

slang is a layer 0 (semantic) filter. It will be applied to the text before any filters of a higher layer.
permalink return to top
replace
ARES System Manual: filter Text Filter Utilities

filter replace <flags>: Performs single-word substitutions, preserving capitalization as much as possible.

Flags format: Specify the subkey of replace within the filter database section which contains an associative array of words to replace.

By default, the database includes one list of word replacements, stanley.

An owner can create a new list of words with a command such as

    db filter.replace.honey {"you": "you, honey", "i": "i, darling", "him": "that sweet little boy"}

which can then be loaded with filter replace honey.

Limitations: Currently, replace can only alter single words, though the substitutions may be multiple words long. It treats apostrophes as punctuation, so words like 'don't' and 'can't' cannot be substituted.

replace is a layer 0 (semantic) filter. It will be applied to the text before any filters of a higher layer.
permalink return to top
nonverbal
ARES System Manual: filter Text Filter Utilities

filter nonverbal <flags>: Replaces all words with a single predefined syllable, varying only in length.

Flags format: Specify the prefix, repeat, and suffix for the new word, separated by spaces. For example, 'ny a n' converts nyan nyaaan nyan 'nyan'.

nonverbal is a layer 1 (linguistic) filter. It will be applied to the text after layer 0 filters but before any filters of a higher layer.
permalink return to top
translate
ARES System Manual: filter Text Filter Utilities

filter translate <flags>: Sends messages to mymemory.translated.net for language translation.

Flags format: Specify the origin and destination languages as two-letter codes separated by a colon. For example, 'en:it' converts English to Italian.

An exhaustive list of two-letter language codes can be found in ISO 639-1: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes (not all are supported.)

The mymemory.translated.net service is free to use, but contains human-submitted translations, some of which may be erroneous.

The translate filter also cannot perform language auto-detection. It is for entertainment purposes only and is not a substitute for a dedicated translator product. (But if you'd like to submit patches, we're certainly open to them.)

translate is a layer 1 (linguistic) filter. It will be applied to the text after layer 0 filters but before any filters of a higher layer.
permalink return to top
serpentine
ARES System Manual: filter Text Filter Utilities

filter serpentine <flags>: Exaggerates S and Z sounds.

Flags format: Specify the severity as 0 (no snek) to 100 (extreme ssssnek).

serpentine is a layer 2 (apraxic) filter. It will be applied to the text after layer 0 and layer 1 filters but before any filters of a higher layer.
permalink return to top
stutter
ARES System Manual: filter Text Filter Utilities

filter stutter <flags>: Randomly reduplicates consonants and syllables.

Flags format: Specify the severity as 0 (no stutter) to 100 (extreme st-stutter).

stutter is a layer 2 (apraxic) filter. It will be applied to the text after layer 0 and layer 1 filters but before any filters of a higher layer.
permalink return to top
lisp
ARES System Manual: filter Text Filter Utilities

filter lisp <flags>: Converts alveolar sibilants into alveolar fricatives.

Flags format: Specify the severity as 0 (no lisp) to 100 (alwayth lithp).

lisp is a layer 3 (phonemic) filter. It will be applied to the text after layer 0-2 filters but before any filters of a higher layer.
permalink return to top
mumble
ARES System Manual: filter Text Filter Utilities

filter mumble: Simulates blocked or muffled lips. This filter has no user-configurable settings.

mumble is a layer 4 (obstructive) filter. It will be applied to the text after layer 0-3 filters but before any filters of a higher layer.
permalink return to top
caps
ARES System Manual: filter Text Filter Utilities

filter caps: Converts text to all upper-case. This filter has no user-configurable settings.

caps is a layer 5 (orthographic) filter. It will be applied to the text after layer 0-4 filters but before any filters of a higher layer.
permalink return to top
rot13
ARES System Manual: filter Text Filter Utilities

filter rot13: Encrypts text in rot13. This filter has no user-configurable settings.

rot13 is a layer 5 (orthographic) filter. It will be applied to the text after layer 0-4 filters but before any filters of a higher layer.
permalink return to top
slow
ARES System Manual: filter Text Filter Utilities

filter slow: Exaggerates spaces between words.

Flags format: Number of extra spaces to add, from 0 (normal) to 15 (extreme).

slow is a layer 5 (orthographic) filter. It will be applied to the text after layer 0-4 filters but before any filters of a higher layer.
permalink return to top
bimbo
ARES System Manual: filter Text Filter Utilities

filter bimbo: Remaps the basic Latin alphabet to stylish Unicode approximations. This filter has no user-configurable settings.

bimbo is a layer 6 (typographic) filter. It will be applied to the text after layer 0-5 filters but before any layer 7 filters.
permalink return to top
superscript
ARES System Manual: filter Text Filter Utilities

filter superscript: Remaps the basic Latin alphabet, numerals, and some punctuation to superscripted letters. This filter has no user-configurable settings.

superscript is a layer 6 (typographic) filter. It will be applied to the text after layer 0-5 filters but before any layer 7 filters.
permalink return to top
corrupted
ARES System Manual: filter Text Filter Utilities

filter corrupted: Simulates various speech processor malfunctions.

Flags format: Level of corruption, from 0 (no corruption) to 100 (illegible).

corrupted is a layer 7 (decorative) filter. It will be applied to the text last.
permalink return to top
glitch
ARES System Manual: filter Text Filter Utilities

filter glitch: Adds combining diacritics to affect the appearance of a noisy transmission.

Flags format: Level of corruption, from 0 (no Zalgo) to 100 (HE COMES).

glitch is a layer 7 (decorative) filter. It will be applied to the text last.
permalink return to top
filter
ARES System Manual: filter Text Filter Utilities

filter install|remove
filter <name> <flags>
filter <name> help

Transforms text provided on the input pipe and returns it to the output pipe.

Supported filters in this version:
    censor (layer 0): Removes words considered objectionable.
        flags: Specify the subkey of censor within the filter database section which contains an array of words to censor. Entries should be in lower case.

    replace (layer 0): Replaces single words with alternatives.
        flags: Specify the subkey of replace within the filter database section which contains a dictionary of words to replace, e.g. filter.replace.pacifism {'hate':'love'} can be loaded with vox <chain> replace love.
       
        replace is good at preserving punctuation and capitalization, but it can only replace single words; it is not suitable for more complex grammatical changes.

    slang (layer 0): Injects spurious clauses.
        flags: Specify the subkey of slang within the filter database section which contains the arrays 'pre', 'mid', and 'post' of words to inject into sentences.

    nonverbal (layer 1): Replaces all words with a single predefined syllable, varying only in length.
        flags: Specify the prefix, repeat, and suffix for the new word, separated by spaces. For example, 'ny a n' converts nyan nyaaan nyan 'nyan'.

    translate (layer 1): Sends messages to mymemory.translated.net for language translation.
        flags: Specify the origin and destination languages as two-letter codes separated by a pipe. For example, 'en|it' converts English to Italian.

    serpentine (layer 2): Exaggerates S and Z sounds.
        flags: Specify the severity as 0 (no snek) to 100 (extreme ssssnek).

    stutter (layer 2): Randomly reduplicates consonants and syllables.
        flags: Specify the severity as 0 (no stutter) to 100 (extreme st-stutter).

    lisp (layer 3): Converts alveolar sibilants into alveolar fricatives.
        flags: Specify the severity as 0 (no lisp) to 100 (alwayth lithp).

    mumble (layer 4): Simulates blocked or muffled lips.
        flags: None.

    caps (layer 5): Converts text to all upper-case.
        flags: None.

    rot13 (layer 5): Encrypts text in rot13.
        flags: None.

    slow (layer 5): Exaggerates spaces between words.
        flags: Number of extra spaces to add, from 0 (normal) to 15 (extreme).

    bimbo (layer 6): Remaps letters to stylish Unicode approximations.
        flags: None.

    superscript (layer 6): Remaps letters to superscript variants.
        flags: None.

    corrupted (layer 7): Simulates various speech processor malfunctions.
        flags: Level of corruption, from 0 (no corruption) to 100 (illegible).

    glitch (layer 7): Adds combining diacritics to affect the appearance of a noisy transmission.
        flags: Level of corruption, from 0 (no Zalgo) to 100 (HE COMES).

See the entry vox for information on how to set up automatic filtering of chat.

The layer number indicates the order in which filters will be applied when used combination. Each layer corresponds to a stage in human verbal or textual communication, and thus also in the robot's model of speech production:

- Layer 0 (semantic) filters change the meaning of each modified sentence.
- Layer 1 (linguistic) filters change the way in which sentences are converted into utterances.
- Layer 2 (apraxic) filters concern the ability of the robot to choose what sounds to make, and when to make them.
- Layer 3 (phonemic) filters concern the ability of the robot to correctly produce the sounds it has chosen.
- Layer 4 (obstructive) filters concern the ability of the robot to transmit sounds clearly.
- Layer 5 (orthographic) filters change how words are represented in text.
- Layer 6 (typographic) filters change how the text is intended to look.
- Layer 7 (decorative) filters add ornamental characters or transmission errors.

For detail on how to configure each filter, see the individual manual entries for each filter.
permalink return to top
vox
ARES System Manual: vox Filtering

Configuration utility for vox chains.

Vox chains are special pipelines comprised of pipe-centric filter programs (see filter). They are primarily used to alter chat messages.

vox: Reports the overall status of the vox system.
vox <chain>: Reports the status of the specified vox chain.
vox <chain> on|off|toggle: Enables or disables a vox chain.
vox <chain> <filter> remove|add|<flags>: Adds, removes, or configures a filter within a vox chain.

The standard chains are input and output.

See filter for the standard pack of system filters and how to configure them. The vox command will also report which filters are active.
permalink return to top
id
ARES System Manual: id Utility

id
id name [<value>]
id authority [<value>]
id model [<value>]

Modifies the unit's identification information.

id color <slot> <spec>
id color load|save|delete <scheme>

Manages the unit's current lighting colors. See color for more information.

id chime: Lists current chime settings (boot and halt sound effects).
id chime boot|halt clear|<uuid>: Sets or disables the boot or halt sounds.
id chime save|load|delete <scheme>: Manages chime schemes.

id regen

Regenerates the unit's serial number (id.serial) based on its current model and avatar UUID and updates the callsign. This is recommended after changing the prefix; see below.

id volume cycle|mute|<value>|up|down

Adjusts the interface volume. <value> should be a number from 1 to 100. cycle will increase the volume by 10% until it reaches maximum, then mute the audio. up and down also adjust in increments of 10%.

The interface volume is also used for noises emitted by the standard main controller firmware. Run device probe to update the controller's cached copy of the interface sound settings.

id interface <setting> toggle|<value>

Adjusts any interface setting to have a new value. To see a list of supported interface settings, check the interface help page. toggle switches the value '0' to '1' and all other values to '0'.


Settings


The id database section is used to store the unit's identifying information. (See db for an explanation of the database system.) Many useful values can only be updated by modifying it directly.

id.authority: The unit's authority, i.e. the name of its controlling organization. Can be deleted if not appropriate.
id.callsign: The unit's callsign, which is the combination of its name and prefix. The callsign is automatically refreshed whenever the unit's name is changed with the id name command, above.
id.color: An array of color vectors in RGB unit-length color space (fractions ranging from 0 to 1), with the punctuation removed. See color for more information.
id.gender: The unit's gender settings; see gender.
id.model: The controller's model identifier. Will be passed to other devices upon request. Unlike in Companion, this is not required for screen geometry or battery socket calibration.
id.name: The unit's name, which should be a short string uniquely identifying it.
id.prefix: The prefix to add to the name when updating the callsign, usually either 'NS' or some derivation of the model name. To remove the prefix entirely, delete the database entry (@db delete id.prefix).
id.scheme: A list of saved color scheme presets.
id.serial: The unit's serial number, which uniquely identifies it. By convention this should consist of nine numeric digits, but it may be styled to include other punctuation such as letters and hyphens that can be removed as needed.
id.chime.boot: The UUID of the current boot chime (startup sound effect). If absent, no sound will be played.
id.chime.halt: The UUID of the current halt chime (shutdown sound effect). If absent, no sound will be played.
id.chime.scheme: Saved schemes of boot and halt chimes.
permalink return to top
gender
ARES System Manual: id Utility

id gender [<aspect> <value> [<pronouns>]]

Views and updates the unit's gender settings. Gender is used to select pronouns and speech markers (chat tones).

The gender aspects are:
- physical: How the system will refer to the unit in descriptions (in scripts and preset messages).
- mental: How the unit will refer to itself when speaking (in scripts and preset messages).
- voice: Which set of noises to play when the unit speaks. These sounds change depending on which persona is loaded.
- all: Set all of the above simultaneously.

The system notification voice is not related to the unit's gender, and is managed separately. See baseband.

To set the mental or physical gender value, use one of the following:

    c: custom (use provided pronouns)
    f: female (she/herself)
    i: inanimate (it/itself)
    m: male (he/himself)
    n: neuter (they/themself)

To limit the scope of work required for creating personas, voice gender only allows n, f, and m options. Other values will be interpreted as n.

To provide custom pronouns, fill out the following template, taking care to ensure no typos are created:

@id gender all c neuter,they,them,their,theirs,themself

Then apply the same for physical instead of mental.

For example:

Spivak: @id gender all c nonbinary,xe,xem,xyr,xyrs,xemself
Fae: @id gender all c fae,fae,faer,faer,faers,faerself
Piercy: @id gender all c individual,per,per,pers,pers,perself
Elverson: @id gender all c nonbinary,ey,em,eir,eirs,eirself
Philologus: @id gender all c nonbinary,ve,ver,vis,vis,verself
Net: @id gender all c hermaphrodite,sie,hir,hir,hirs,hirself

These forms are known as the gender name (which should be usable as an adjective), subject, object, genitive, possessive, and reflexive.
permalink return to top
color
ARES System Manual: id Utility

(input) @color <slot> <spec>
(input) @color load|save|delete <scheme>
(input) @color swatch <swatch> <spec>
(input) @color swatch delete <swatch>

Where:
- <slot> is one of a, b, c, d, or all
- <spec> is a six-digit hexadecimal code prefixed with # (e.g. #ff00ff for magenta), or an <r g b> triple in eight-bit (0-255) or fractional (0.0-1.0) format, or <swatch>
- <scheme> is a short name identifying the color preset for user convenience (e.g. 'pastel' or 'sad')
- <swatch> is a short name identifying an individual predefined color for user convenience (e.g. 'cherry' or 'company')

This is a default shell alias (see alias) that resolves to id color. It is used to control the unit's lighting color and to manage presets.

If the color alias has been removed, or if the command must be invoked from outside of a shell context, refer to it as id color instead of color.


Color Slots


ARES units have four color options that can be managed independently, referred to as 'slots', and identified with the letters 'a' through 'd'. These slots have no intrinsic meaning, but instead are used by attachments for various purposes.

For example, the NS Tetrad Collar uses all four lighting colors simultaneously to indicate different parts of its hardware. Conversely, most controllers will display certain slots depending on circumstance.

The conventional assignment between color slots and function is:

Slot a: primary color; displayed in the absence of special circumstances
Slot b: positive color; indicates charging, repairing, gratification, etc.
Slot c: negative color; indicates damage, low battery, overheating, etc.
Slot d: main HUD color and alert color; used on attachments to indicate a situation that requires attentiveness but is not problematic

A color scheme consists of its name, and assignments for each of the 4 slots.


Color Specifications


ARES accepts the same color formats as Companion (hex, byte, or fraction) and most of the same color names.

Hex colors must be six digits in length, and are identified by a preceding hash ('#') character. Shorter codes (e.g. #f70 for orange) will be padded with zeros (becoming #000f70, a dark blue).

RGB triples consist of three decimal values separated by spaces. If any of the values are greater than 1, the whole number will be interpreted as being in base 255. Otherwise the code will be parsed as fractional (in the range 0.0-1.0).

For example, the RGB triple 1 0 0 is interpreted as bright red, but 1.1 0 0 is interpreted as nearly black. This processing is only done during input; all colors are stored in the native format (fractions).

The list of available color name presets varies from version to version. This version includes:

    acid, amber, arctic, beige, blackberry, blue, business, cherry, clay, company, crimson, cyan, daffodil, forest, goldenrod, gray, green, ice, indigo, magenta, mint, ocean, orange, primrose, red, rosy, silver, violet, white, yellow, zooties.
permalink return to top
name
ARES System Manual: id Utility

(input) @name

This is a default shell alias (see alias) that resolves to id name. See id for more information.
permalink return to top
do
ARES System Manual: exec Shell

(input) @do <script>

Interprets and runs the specified script file. exec scripts typically have the file extension .as and consist of a series of commands to send through exec with the @ sign removed.

Some exec built-in commands are only meaningful inside a script: exit and jump.

Shell built-in command: This command is part of the exec shell and does not have a corresponding system binary. It must be used shell scripts without a preceding @ and cannot be called directly with the system invoke() API.

To run an exec shell script with invoke(), use the syntax exec do <script>.

By default, exec will also check filename extensions for registered handlers, so for familiar filenames, do can be omitted, leaving just exec <script> or @<script>. See fs for more information on file type associations.
permalink return to top
echo
ARES System Manual: exec Shell

(input) @echo [-c|-d] <message>

Prints the specified message to the current output stream. Not to be confused with echo(), which wraps llOwnerSay.

If -c is specified, output will be sent directly to the console (llOwnerSay).

If -d is specified, output will be sent directly to DEBUG_CHANNEL.

Shell built-in command: This command is part of the exec shell and does not have a corresponding system binary. It must be used shell scripts without a preceding @ and cannot be called directly with the system invoke() API.

To use this command with invoke(), use the syntax exec echo [-c|-d] <message>.
permalink return to top
exit
ARES System Manual: exec Shell

(exec script) exit

Terminates execution of the current script. See do.

Shell built-in command: This command is part of the exec shell and does not have a corresponding system binary. It must be used shell scripts without a preceding @ and cannot be called directly with the system invoke() API.
permalink return to top
expressions
ARES System Manual: exec Shell

Two built-in commands from the exec shell, if and set, allow for parsing of mathematical operations, called expressions.

For example:

    set x = $x + 1

    if $y / 2 == 2 then jump my_label

Expressions in exec code permit the following operators: !=, ==, <, >, <=, >=, +, -, *, and /.

To compare strings, use is:

    if $arg.1 is abort then exit

As with other exec commands, $ can be used to retrieve the value of a variable from the env section of the database. See set.

There is no operator precedence; expressions are parsed from left to right. Structure your equations accordingly, and use a temporary variable via set for more complex procedures.

Expressions use floating-point evaluation but comparisons will clamp to integer values within ±0.001.

For more sophisticated mathematical facilities, see the lslisp and calc programs.
permalink return to top
from
ARES System Manual: exec Shell

(input) @from <pipe> <...>

Executes the specified command <...>, substituting <pipe> as its input stream.

Shell built-in command: This command is part of the exec shell and does not have a corresponding system binary. To replace the input stream during an invoke() system call, simply replace the third argument (ins).
permalink return to top
if
ARES System Manual: exec Shell

(input) @if [not] <expression> then <...>
(input) @if [not] <str1> is <str2> then <...>
(input) @if [not] <needle> in <haystack> then <...>
(input) @if [not] exists <file> then <...>

Evaluates <expression> and executes the command <...> if the result was non-zero.

The word then is used to mark the end of the expression in the if statement, and has no significance outside this context.

The word is can be used to test for string equality. This is not currently very reliable, as variables are substituted before evaluation and are not escaped.

The word in can be used to check if a key <needle> is present in a JSON object <haystack>. It does not work for strings, arrays, or any other datatype.

The word exists can be used to check if a file <file> is present in local storage. For a more general solution that includes remote storage, try xset <var> fs info <file> followed by if not $<var> is %undefined then <...>. See xset.

The word not may be added directly after if to negate the evaluation.

See expressions for more information.

Shell built-in command: This command is part of the exec shell and does not have a corresponding system binary. It must be used shell scripts without a preceding @ and cannot be called directly with the system invoke() API.

To use this command with invoke(), use the syntax exec if <expression> then <...>.
permalink return to top
jump
ARES System Manual: exec Shell

(exec script) jump <label>

If inside a script (see do), looks for a line @<label>: and moves execution to the line after it.

The label destination must start with an @ sign and end in a colon.

Shell built-in command: This command is part of the exec shell and does not have a corresponding system binary. It must be used shell scripts without a preceding @ and cannot be called directly with the system invoke() API.
permalink return to top
say
ARES System Manual: exec Shell

(input) @say <message>

Sends <message> as normal input to the input parser. Mainly useful inside scripts or when terminal mode is active (see input).

Shell built-in command: This command is part of the exec shell and does not have a corresponding system binary. It must be used shell scripts without a preceding @ and cannot be called directly with the system invoke() API.

To use this command with invoke(), use the syntax input say <message>.
permalink return to top
set
ARES System Manual: exec Shell

(input) @set <variable> <string>
(input) @set <variable> %key
(input) @set <variable> %keys <JSON>
(input) @set <variable> %undefined
(input) @set <variable> %count lines|chars|words|keys in <string>
(input) @set <variable> %line|%char|%word <index> in <string>
(input) @set <variable> %index <key> of <JSON>
(input) @set <variable> = <expression>

Sets a shell environment variable to the specified value. Variable names should start with letters. They are case-sensitive. They may contain underscores, hyphens, and numbers.

The special value %key can be used to set a variable to a new randomly-generated UUID.

The value %undefined can be used to remove a variable.

The %count syntax counts the number of lines, characters, or words in a string, or keys in a JSON object. For example, set n %count chars in ARES sets the environment variable n to 4.

The %line, %char, and %word syntaxes extract individual parts from a string. For example, set w %word 3 in One, Two, Three, Four! sets w to Four! (Indexes start at 0.)

The %keys syntax (not to be confused with %key) will return a space-separated list of keys in the JSON object <JSON>, which can then be iterated over with %word and %count words.

The %index syntax will extract part of a JSON object. It supports . notation for nested objects (but not JSON arrays). For example, set fruit %index alpha in {"alpha":"apple","beta":"banana"} will yield 'apple'.

To use an environment variable, type $ and the variable name. For example, @set x = $x + 1 will modify the variable x by adding 1 to its current value.

To remove variables you no longer need, use set <name> %undefined. It is good practice to clean up after yourself at the end of a script that uses temporary environment variables.

Variable substitutions may be used in any exec invocation, i.e. commands that can be called with @ from input.

Environment variables are stored in the env section of the database and can be reviewed with @db show env.

Environment variables may be set to the output from running a system command by using the bundled program xset.

Shell built-in command: This command is part of the exec shell and does not have a corresponding system binary. It must be used shell scripts without a preceding @ and cannot be called directly with the system invoke() API.

To use this command with invoke(), use the syntax exec set <variable> <value> or manipulate the env database section directly with setdbl("env", [<variable>], <value>).
permalink return to top
service
ARES System Manual: exec Shell

(input) @service <service> <message>

Sends a command to the specified daemons. Most daemons may be accessed this way (see list on the main page). However, to control the io daemon, see the vox command.

Shell built-in command: This command is part of the exec shell and does not have a corresponding system binary. It must be used shell scripts without a preceding @ and cannot be called directly with the system invoke() API.

To call daemons directly from within programs, use the call() API function as defined in ARES/api/api.h.lsl.
permalink return to top
to
ARES System Manual: exec Shell

(input) @to <pipe> <...>

Executes the specified command <...>, substituting <pipe> as its output stream.

Shell built-in command: This command is part of the exec shell and does not have a corresponding system binary. It must be used shell scripts without a preceding @ and cannot be called directly with the system invoke() API.

To use this command with invoke(), change the second parameter (outs) to the desired output pipe.
permalink return to top
exec
ARES System Manual: exec Shell

exec <filename>: Runs the specified file using extension associations.
exec do <filename>: Interprets the specified text file as a shell script.
exec <...>: Runs the specified command <...>.
(input) @<...>: Triggers exec.

exec is the main ARES shell. When the user attempts to run a command that starts with @, the @ sign is removed and the rest of the command is sent to exec for further processing. exec also runs .as (ARES Shell) script files.

In this manual, whenever a command syntax definition begins with '(input) @...', it is a call to the default system shell implemented by exec.

The system shell may be changed by modifying the database value input.shell and restarting input.

Several useful commands are built-in to exec, and are used to controlling scripts and perform other system functions; see: alias, do, echo, exit, from, if, jump, say, set, service, to.

In Companion, exec's closest equivalent was called arabesque. However, ARES Shell scripts are not generally compatible with Arabesque scripts.


Variable Substitution


exec allows variables to be substituted with $<varname>, where <varname> corresponds to a key in the env section of the database. $ can be escaped as \$ to prevent substitution, e.g. when defining commands.

To create or modify a variable, use the set built-in. Note that the environment is global: any command run on your system shares the same pool of variables, with the exception of certain built-ins:

The following variable names are reserved and will always return special values regardless of how they are set in env:

- $name always returns the display name of the avatar that triggered input.
- $user always returns the UUID of the avatar that triggered input.
- $self always returns the UUID of the avatar that owns the system.
- $me always returns id.callsign (the full name of the system).

Variable substitutions are only parsed within system command calls; they cannot be used in direct speech or aliases. To work around this, use say, e.g. @say =alias lastmsg echo $msg - which will cache the current value of $msg.
permalink return to top
alias
ARES System Manual: exec Shell

(input) @alias [<name> [<...>]]: shows, creates, or alters aliases for the exec command <...>.
(input) @alias delete <name>: deletes an alias.

An alias is an alternative name for a command. Aliases are interpreted before commands are run by exec. For example, the default ps alias resolves to proc tasks detail (see proc). This can simply be called by the unit with @ps.

Arguments to aliases are allowed. For example, mapping the alias name to id name can be used to set the unit's name with @name <new-name> instead of @id name <new-name>.


Default Aliases


The following aliases are defined in the input database section. They can be restored by running db load default.db, which will also restore several other core parameters to their factory values.

- baseband: service baseband (controls network services)
- charge: service baseband charge (see charge)
- color: id color (see color)
- device: service hardware (hardware manager)
- iddqd: service baseband dqd (see combat)
- kill: proc kill force (stops a program from running)
- name: id name (see name)
- nsdqd: service baseband dqd (see combat)
- off: power off (shuts down the systtem)
- on: power on (boots the system)
- ooc: service baseband ooc (see combat)
- ps: proc tasks detail (displays detailed process info)
- reset: proc unstick (resets a program)
- status: power (displays power info)
- env: db env (lists all environment variables)

For more information on database maintenance, see db.
permalink return to top
input
ARES System Manual: input Parser

input
input say <message>: handle <message> as if typed by unit into the chat hook
input reset: reset shell (rebuilds chat hook)
input restart: restart io daemon
input purge: clear any stuck pipes
input debug: report status of io daemon pipes

The standard parser in ARES, input is responsible for translating input into chat messages and calling the shell.


Sending Chat


To send chat normally, simply type it, e.g. Hello world!

To whisper, prefix w and a space: w Hello world!

To shout, prefix s and a space: s Hello world!

If you have personas installed, then you can access their built-in cortex bypass messages (see persona) by prefixing a dot: .hi will resolve to: persona .hi


Running System Commands


System commands are used to perform the vast majority of functions under ARES, by calling other programs (LSL scripts) to accomplish specific tasks. For example, to check the unit's power settings, you would call the power program.

To run a system command, prefix an @ before the command's name, e.g. @help input to see this message. These are passed to the current shell (as defined in input.shell), which is usually exec.

If a program's filename starts with _, you do not need to include it to execute that program. This simply marks the program as a system component.


Bang Commands


Any message that starts with ! will be redirected to the effector daemon for processing. The supported bang commands are as follows:

- !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: Enables working effects and shows the disk throbber.
- !done: 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.


Built-in Commands


The input parser also has several built-in commands, which start with =. These commands are for adjusting the shell and debugging.

- =chat: disables =terminal (see below)
- =ddt <option>: sends debug command to kernel. Valid options are listed in the kernel help page.
- =terminal: enables terminal mode, in which all input is assumed to start with @. Use say or a single double quote to speak normally. Disable with =chat.
- =alert 0/1/2/3: responds to a HUD alert message with the F2/F3/F4/F5 response.

In Companion, the main functions of input were contained in the cortex module.
permalink return to top
persona
ARES System Manual: persona Application

persona: shows current persona status and lists available personas
persona <name>|default: loads the specified persona
persona .<action>: generates a suitable chat message
persona set <field> <value>: sets a persona trait

The ARES persona system is a roleplay enhancement tool that allows the unit to enter into special personality 'modes' or states of mind on command.

Persona files (which use the .p extension) typically specify a speech marker (chat sound), an #RLV outfit folder to load (typically stored in #RLV/~ARES/persona) and an arbitrary number of preset messages. These are called persona traits.

As persona files in ARES are implemented as shell scripts, each line that sets up a trait must be prefixed appropriately, e.g.:

persona set marker <neuter> <female> <male> specifies the UUIDs for each gender's speech marker (see gender)
persona set path $rlv/persona/<folder-name> specifies the #RLV folder to load while in the persona
persona set action {}: clears the list of preset messages (recommended at the start of each persona)
persona set action.<action> <message>: sets a persona preset message

Persona preset messages can be called directly by typing .<action> (as described on the input manual page.) This is a convenient way to convey the gist of a persona in roleplay, and the unit's only way of chatting when its mind is turned off.

Many persona messages sound more natural if the unit is able to refer to itself with the correct pronouns. To do this optimally, use the say command, as in these examples:

persona set action.use? @say This unit offers \$pm.refl to assist.
persona set action.mind @say This unit cannot comply while \$pm.gen cortex is disabled.

These examples use \$pm.refl and \$pm.gen to substitute the reflexive and genitive pronouns (see gender) at time of invocation (see input). Had the persona simply specified:

persona set action.use? This unit offers $pm.refl to assist.
persona set action.mind This unit cannot comply while $pm.gen cortex is disabled.

...then the pronoun values would be fixed when the persona was loaded, slightly inconveniencing anyone who wants to roleplay gender-shifting during a scene.


Embedding Commands


Since a .p file is technically a shell script, any system command can be embedded in it - just strip off the @ sign from the start. For example, a persona might change color schemes:

id color load pastels

Or change power settings:

power optics off

Or simply send a message:

say The S-Blade has a Hackblood charge!

However, remember that there is no script that gets executed when a persona is removed, so if you modify a persona to include a state change, you will want to add counterparts to the rest of your personas as well.
permalink return to top
ax
ARES System Manual: ax Software Manager

The AX (ARES Xanadu) client is the primary way of managing software installed locally on the unit.

ax: lists all installed packages and available upgrades
ax available: lists all known packages that are not installed
ax update|refresh: searches for new package versions from trusted sources in region
ax upgrade: installs new package versions (do after ax update)
ax servers: lists servers in the region
ax sources: lists trusted sources and their locations
ax connect <uuid>: adds server <uuid> to the list of trusted sources
ax disconnect <uuid>: removes a server from the list of trusted sources
ax info <package>: retrieves and displays package info for <package> (must be available on a trusted source in the region)
ax download <file>: retrieves <file> from a server in the region
ax install|remove|upgrade <package>: performs tasks on a package


Terminology


.pkg: A package script, executed by exec. Every package script is based on a standard template that provides install, reinstall, update (remove only files), remove, cache, and uncache commands, described below.
.parc: A package data archive, rezzed by pkg as directed by the package script.
.spkg: A special package script that contains different logic for installing OS updates.
.sparc: A self-extracting package data archive, rezzed by spkg and usually used for OS updates.
AX: ARES Xanadu, the protocol and infrastructure for managing packages in ARES.
AX client: The package manager itself, invoked with ax.
AX server: An object that provides packages and data archives on request.
(trusted) source: An AX server that your AX client has been configured to access. By default, there is one trusted source: axtest:0 (UUID ce9f7786-7f44-da63-bdbf-ff9d1ae3a304), located in Eisa.


Finding Software


AX servers featuring several simple programs are available in NS's home region, Eisa. The ax list and ax info commands can be used to browse their contents, which can be downloaded using ax download.

In the system menus, settings... > software... > servers... will provide a similar experience in later updates.

More information about ARES software management can be found in the pkg article.
permalink return to top
pkg
ARES System Manual: pkg Package Manager

pkg is a backend program that assists ax in managing installed software. Quite unlike the _xanadu-client package manager in Companion, pkg is designed to rely heavily on the input shell for sequencing commands.

IMPORTANT: Every AX package is a shell script with full execution privileges. Never install packages from servers or creators you don't recognize.


User Commands


pkg index: updates the index of package metadata

Control Commands

pkg local [<package>]: lists versions of installed packages
pkg clean: delete all .parc, .sparc, .pkg, and .spkg files from local memory
pkg open <archive>: opens a package archive (rezzes an object from the unit's inventory), retrieving it first from a server in the region if it is not found
pkg close|detach <archive>: closes a package archive (sends the rezzed object a command to self-destruct)
pkg extract <archive> <file>: copies <file> from <archive> to the local filesystem (ring 3) (instructs the rezzed object to send the file)
pkg inject <archive> <file>: copies <file> from the local filesystem (ring 3) to <archive> (archive must be rezzed; PARC version 2.0 and later only)
pkg erase <archive> <file>: removes <file> from <archive> (archive must be rezzed; PARC version 2.0 and later only)
pkg list <archive>: lists files in <archive> (archive must be rezzed; PARC version 2.0 and later only)
pkg sideload|attach <archive>: searches for a package archive that is already attached to your avatar (see Sideloading, below)


Managing Packages


Once a package is downloaded, you may run it with do <package>.pkg as with other shell scripts. Standard package scripts provide actions, which are read as command-line arguments:

- do <package>.pkg install: Installs the package from scratch.
- do <package>.pkg remove: Removes the package's files and deletes any associated settings.
- do <package>.pkg reinstall: Removes the package's files, then installs them again.
- do <package>.pkg update: Removes the package's files without removing settings. This is also known as 'prepping' or 'preparing' a package for installing an upgrade.
- do <package>.pkg cache: Downloads the package archive so that the installation may be completed later.
- do <package>.pkg uncache: Removes the package archive and the package.

During both remove and update, the package file and script are deleted. To upgrade a package to a new version, use update to remove the old version and then install to add the new version.

The settings... > software... > downloaded... menu can be used to the same effect.


Creating New Packages


The package sample.pkg is available from official NS servers. It provides instructions, as well as a template package archive (sample.ax.parc) and minimal example application, which can be used to create and package your own software.

The ARES SDK contains a number of header files which are required to create ARES programs. Visit http://develop.nanite-systems.com/ for information on ARES application development.

Make sure you fully understand the ARES software copyright license (see license) before distributing your work.


Sideloading


The pkg sideload command is equivalent to pkg open and only prepares the attached package for installation; to complete the installation process you will still need to type the relevant pkg extract commands (or have a script do it for you).

However, if the package archive's filename ends in .sparc, then it is (probably) a self-extracting package archive that will autonomously complete the installation process without guidance from ARES.

Sideloading SPARCs is the standard method of distribution for unbundled ARES software products, like Sexuality and Warrior.


Repacking


Most packages are created by using the typical SL tools to edit the contents of the PARC, but you can also use pkg's inject, erase, and list commands. This is convenient if you have many files in your package but only need to update a few.

However, be aware that there is no way to put a rezzed object back into the file system of your ARES installation. To repack, you must first sideload the package from your own inventory, NOT open it from ARES. Otherwise any changes will be lost!

Repacking is only possible with PARC 2.0 (compiled Nov 12 2023) and later. The original PARC 1.0 files (compiled Jun 23 2023) cannot be modified this way. SPARCs cannot be repacked.
permalink return to top
power
ARES System Manual: power Module

power: reports current system power state
power <subsystem>|all on|off|toggle: adjusts subsystem configuration
power load|save|delete <profile>: loads, saves, or deletes a power profile (preset configuration of subsystems)
power on|off <delay>: turns the system on or off after <delay> seconds (default 0, minimum 10)
power cycle|reboot <delay>: reboots the system after <delay> seconds (default 0, minimum 10)
power zap [<amount>]: sends <amount> kJ to each unit within 20 m (default: 240 kJ)

The ARES subsystem management interface allows for precise adjustments to the unit's power usage when certain functions are not required.

All subsystem definitions are stored in the power section of the database, and can be replaced. See subsystems for more information.
permalink return to top
subsystems
ARES System Manual: Subsystems

The default definitions are as follows:

base (30 W): no intrinsic functions; required for all other subsystems
video (20 W): ability to parse video signals; required for hud and optics; requires base
lidar (10 W): ability to judge distances; requires base; required for teleport
hud (5 W): ability to see the ARES HUD; requires video and base
optics (50 W): ability to see visible light; requires video and base
hearing (10 W): ability to receive incoming chat messages; requires base
identify (20 W): ability to see names and hovertext; requires base and optics
radio (30 W): no intrinsic functions; required for location, teleport, receive, transmit, and wifi; requires base
location (5 W): ability to see map location; required for teleport; requires base and radio
teleport (120 W): ability to teleport or be teleported; requires base, lidar, radio, and location
receive (10 W): ability to receive IMs; requires base and radio
transmit (10 W): ability to send IMs; requires base and radio
wifi (10 W): ability to connect to remote devices; requires base and radio
motors (60 W): ability to touch nearby objects; required for movement subsystems (locomotion, athletics, flight, reach), speech, and amplifier; requires base
locomotion (40 W): ability to walk and sit; required for athletics and flight; requires base and motors
athletics (30 W): ability to run and jump; requires base, motors, and locomotion
flight (50 W): ability to fly; requires base, motors, and locomotion
reach (20 W): ability to touch objects more than 2.5 m away; requires base and motors
voice (20 W): ability to talk (at a whisper); required for speech, amplifier, and mind; requires base
speech (20 W): ability to talk (at normal volume); requires base, motors, and voice
amplifier (30 W): ability to shout; requires base, motors, voice, and speech
mind (70 W): ability to speak messages other than those defined by persona; requires base and voice

If the optics subsystem is disabled but video and lidar are enabled, the unit's video feed will present LiDAR data, showing nearby objects in white and the distance in black.

Various system functions will draw further power; by default these costs are:

- Flying: 500 W
- Jumping: 500 J
- Walking: 200 W
- Running: 500 W (Walking + 300 W)
- Cooling: up to 100 W

These costs are defined in the status section.

Certain power costs cannot be redefined. These are:

    - Teleporting expends anywhere from 12 kJ to 240 kJ from a dedicated capacitor, which must be fully recharged between teleports.
    - The CPU draws 2 J for every microsecond of script time used by ARES. This replaces Companion's behavior of charging per character when speaking.
    - Reclamation (resurrection) always costs 10000 J.
    - Autorepair costs 1000 W.


Custom Subsystems


To create or modify a subsystem, it is best to make a fresh copy of the power.db notecard from ARES user memory and then edit it. When you are done making changes, load it with db load <filename>.db.

Each subsystem has 5 parts: name, notify, req, rlv, and draw.

The name should be a single word in lower-case letters.
The req field is a JSON array (e.g. [1,2,3]) that indicates which other subsystems this one requires. If any of them are off or disabled, this subsystem will also be disabled. If no requirements exist, specify [].
The notify field indicates the ways in which the system's scripts should be affected. A single subsystem may contain multiple notify directives, as can be seen in the EPS definition at the bottom of power.db.
The rlv field indicates the RLV messages that should be enforced when the subsystem is off. All subsystems are disabled when the unit is off. A reference for RLV is available at https://wiki.secondlife.com/wiki/LSL_Protocol/RestrainedLoveAPI.
The draw field indicates the cost in watts of the subsystem.

In the notify and rlv fields above, ? is automatically replaced with n or y.

All subsystems listed in req should have numbers smaller than the current subsystem. power.subsystem.0.req [1] will not work properly.

Finally, you will need to add a menu item for your subsystem, and reset the _power script. See the m:power section of the menu.db file for the format to follow.

The EPS (emergency power system) is a special subsystem activated when the unit is powered down. Its implementation is similar to the others, but it is loaded separately by _power as needed.


Caveats


The overlay images shown when the unit cannot see or is powered down cannot currently be customized.

The teleport subsystem should not be renamed, or it will not be disabled properly after an externally-powered teleport (i.e., Stargating).

A special exception is made for the sendchat RLV restriction. If rlv for a subsystem uses it, then that subsystem cannot contain any other RLV commands. However, multiple subsystems may use it.

The various notify directives do the following when disabled:

- _input voice ? prevents the unit from speaking.
- _input mind ? limits the unit to pre-set '.' messages from the persona (see persona)
- _input speech ? limits the unit to whispering.
- _input amplifier ? prevents the unit from shouting (with the 's ' prefix; see input)
- _input hearing ? prevents the unit from hearing.
- _power wifi ? prevents remote devices (including menus) from working.
- _power locomotion ? prevents the unit from moving and from standing up if already sitting.
- _power lidar ? enables distance mapping if optics are disabled.
- _power optics ? disables normal vision.
- _power hud ? hides the HUD.
- _power motors ? plays the s_frozen animation.
- nav teleport ? prevents teleporting to bookmarks (see nav)
- nav location ? prevents all navigation.
permalink return to top
proc
ARES System Manual: proc Module

proc [tasks [detail]]: Report status of all running and known programs.
proc hooks: Report status of all current event hooks.
proc daemons: Report status of all known system daemons.
proc kill [force] <program>: Kills specified program. An underscore is prefixed if the program does not exist.

The proc module is a key system component that provides a number of system functions such as initializing other programs and recovering from kernel resets.

The functions of proc were managed by songbird in Companion.
permalink return to top
fs
ARES System Manual: fs Module

The fs module provides a uniform interface for file system access, allowing other programs to request parts of notecards and interact with networked file storage. It can also be invoked directly to browse and modify the file system.

fs [list] [<view>|<source>]: List available files (if no view or source specified, lists all files).
fs view <name> [delete|<spec>]: Create, modify, or delete a view (filtered list of files).
fs source <name> [delete|<URL>]: Create, modify, or delete a remote (web) source.
fs [open|read] <filename>: Open a file using the file association defined in LSD:fs.open
fs refresh: Regenerate the index of local files, remote files, and rules.
fs delete|remove|rm <filename>: Deletes a file.
fs menu <view>: If the view has an associated menu, refreshes that menu.
fs match <spec>: Lists all filenames that match the pattern specification <spec>.
fs info <filename>: Reports the source for <filename> (or JSON_INVALID if the file does not exist).

The functions of fs were managed by songbird in Companion.


Filename Pattern Specifications ('specs')


A <spec> is a simple filename-matching pattern, or a list of filename patterns separated by vertical bars (|). Each pattern is of the format:

<0+ characters>*<0+ characters>

For example, p_*_1 finds all filenames that start with p_ and end in _1, while *.ls|*.as finds all files with the extensions .ls and .as.

Spec patterns may contain no more than one asterisk. No other wildcards are supported.


Views and Sources


For information on creating and managing remote sources, see the help entry sources.

Views create a list of files based on a particular filename search pattern. For example, the persona view's spec is *.p. The persona program consults the view output to determine what personas are available.

Views may also specify the name of a menu (as LSD:fs.view.<view>.menu), which fs will populate with the view's output. These menu entries require a file association in LSD:fs.open. The standard persona view demonstrates this, also.
permalink return to top
sources
ARES System Manual: Remote File Systems

A remote source is a directory on the Internet which is indexed by the fs module. When properly configured, remote sources allow the unit to seamlessly access files stored online from the controller.

Only text files can be accessed from a remote source; LSL programs and other assets must still be installed via in-world packages. For many types of post-market add-on however, remote sources can be a convenient alternative.

To add a remote source to your controller, you will need the URL of that source. For example, http://my.nanite-systems.com/<;version>/info is installed by default as the ns1-info source, where <version> is the current system version number.

To re-add and update the 'ns1-info' source, use the following commands:

1. fs source ns1-info http://my.nanite-systems.com/<;version>/info/ (you must replace <version> with your current version number)
2. fs refresh

To remove the ns1-info source, use:

1. fs source ns1-info delete
2. fs refresh

The path to the source must end with / or it will fail.


Creating Remote Sources


All sources are served over HTTP or HTTPS. They must support the following syntax, specified as query strings (GET parameters):

1. No query string: List the filenames in the source, separated by line feeds (0x10)
2. A query string consisting of a filename: List the size of the file. Any slash characters ('/') should be replaced by underscores ('_').

Furthermore:

1. The above must be returned with the 'text/plain' MIME type, as Second Life will reject almost any other value.
2. All files in the directory must also be returned with this MIME type. This may require reconfiguration of your web server; many versions of Apache will attempt to auto-detect filetype based on extension, unhelpfully.

Following is the complete PHP source code for a remote source. Name it index.php and place it in a directory on a compatible webserver with the files to provide. The server must have PHP installed.

<?php
    header('Content-Type: text/plain');

    if(!isset($queryString))
        $queryString = $_SERVER['QUERY_STRING'];
   
    if($queryString != '') {
        $queryString = str_replace('/', '_', $queryString);
        echo(filesize($queryString));
        return;
    }

    $items = scandir(getcwd());
    array_splice($items, array_search('.htaccess', $items), 1);
    array_splice($items, array_search('index.php', $items), 1);
    array_splice($items, array_search('..', $items), 1);
    array_splice($items, array_search('.', $items), 1);
    echo implode('\n', $items);
?>
permalink return to top
security
ARES System Manual: security Module

security yes|no|trust|block <key>: Respond to a consent prompt. (Unit only.)

security user|manager|owner <key>: Add or update a user.
security guest|ban <key> [<time>]: Add a ban or guest, either permanently or for <time> seconds.
security forget <key>: Remove a user, guest, or ban.

security reset|runaway: Clear the unit's user list. Existing owners will be notified.
security audit: Check for missing name entries and assign self-ownership if the unit has no owner.

security rules: List all security rules. See rules for more detail.
security <rule> 0-6: Modify a security rule. (See below.)

The new value for a security rule can be specified with a mnemonic instead of a number. The rule values are:

0 (nobody): no one may do this
1 (all): consent is not required to do this
2 (consent): guests and all users may do this
3 (user): all users may do this
4 (manager): managers and owners may do this
5 (owner): only owners may do this
6 (self): only the unit may do this (no rank required)

ARES has no consent timeout. Requests stay in the system until the unit answers them.


User Ranks


ARES has the same privilege levels as Companion: bans, the public, guests, users, managers, and owners. For the most part, the privileges afforded to these roles are defined by customizable rules.

Guests can be admitted by the unit itself, typically in response to access attempts. Higher ranks can only be assigned by users with sufficient permissions.

By default:

- No consent is required to trigger arousal, but anyone the unit has banned from consent will not be able to arouse the unit.
- The unit may consent to guests who wish to chat through the unit, access its menus, modify its voice or persona settings, or run local commands.
- User rank is required for running commands remotely, and users may remove themselves from the unit's user list.
- Manager rank is required to delete files, add users, change identity settings, use the settings or access control menus, or force the unit to teleport from another sim. Managers may also create more managers.
- Owner rank is required to remove managers once created, and to add new owners.
- Whatever the unit's rank, even if completely banned from its own system, it may trigger the 'safeword' program to break RLV restraints, initiate a run away from all users, and demote owners.


Primary Owner


Although ARES fully supports multiple owners, some tasks and protocols require that a single individual be nominated as the unit's owner. In these cases the unit's 'primary' or 'identified' owner is used.

Typical examples of situations where a single owner identifier is required include: the public bus ping message, performing maintenance tasks on a diagnostic bed, and resetting the user list.

The primary owner is normally the owner that was configured first, although if this user is demoted or removed, one will be selected arbitrarily from the remaining owners (whoever has the largest UUID).

The current primary owner is indicated by the id.owner database entry, and may be changed at any time using the db utility. If it is missing, devices and programs that rely on it should assume the unit is self-owned.


Policies


This is a catch-all term for miscellaneous restrictions that can be applied to the unit. Typically these are things unrelated to power consumption, but are popular among RLV enthusiasts.


Tips


To stop guests from accessing the system entirely, ensure all rules require 3 or higher.

To make the system public access, switch all values to 1.

The ban list always takes priority, except for rules with the value 6. You can deny self-access to the unit by adding it to the ban list.

See rules for more information about each rule and recommended values for them.

In Companion, the security system was spread between submission and various other modules.
permalink return to top
rules
ARES System Manual: security Rules

Rules are how ARES determines what privileges to grant each rank of user. (See security for a basic introduction.) Most privileges are cumulative, meaning a user of a high rank also has the privileges of a user with a lower rank.

The ranks are:

1 (strangers), 2 (guests with consent), 3 (users), 4 (managers), 5 (owners)

If you see a rule with the setting of 0, that means no one may ever take the action in question. If you see a rule with the setting of 6, that means the action is reserved for the unit alone, even if banned.

If a rule requires rank 2, then any stranger who attempts to perform such an action will generate a consent prompt, which the unit must answer before the action will be completed. Consent prompts have no timeout.

The rules in the current version of ARES are as follows:

add manager: give someone the rank of manager unless they already have the rank of owner.
add owner: give someone the rank of owner.
add user: give someone the rank of user, unless they are already a manager or owner.
arouse: trigger sexual arousal events (requires the Sexuality add-on)
chat: make the unit send chat messages.
database: permission to use the db program (some features are always restricted to owner only)
delete file: remove any file from ring 3 using the fs delete command.
demote manager: reduce a manager to user rank, or to remove a manager entirely.
demote owner: reduce an owner in rank, or to remove an owner entirely.
demote self: remove oneself from the user list, or reduce one's own rank; this supersedes other rank requirements.
identity: change the unit's name, gender, or color settings.
local: run commands when within chat range (20m) of the unit; activate verbal commands (see trigger) at any range.
manage: access the 'settings' and 'access control' menus, use the 'pkg' program to add or remove software, and similar.
menu: access the menu.
persona: change the unit's persona.
remote: run commands from anywhere in the current region.
run-away: use the security reset command to clear the user list and restore self-ownership.
safeword: if restraint is installed, use the restraint safeword command to abort RLV relay interactions.
vox: adjust vox filtering settings. (See vox)
yank: automatically teleport the unit when sending a teleport invite.

As ARES develops, more rules will be added as needed.
permalink return to top
policy
ARES System Manual: policy Facility

policy lock: Lock the console and menus immediately.
policy unlock [<password>]: Unlock the console and menus, with the specified <password> if one is set.
policy password <password>: Sets or clears the lock password.
policy autolock on|off|toggle: Enables or disables Auto-Lock. (Not yet implemented.)
policy autolock time <seconds>: Sets Auto-Lock to occur after the specified time. Minimum 15, default 120.
policy beacon <...>: Adjust distress beacon settings. (Not yet implemented.)
policy bolts auto|on|off|cycle: Sets the power state of the anti-theft safety bolts.
policy radio cycle|receive|transmit|open|closed: Specify what IMs should be allowed to non-users: receiving, transmitting, open communications (all), or closed communications (none). (Not yet implemented.)
policy curfew on|off|toggle: Require the unit to be near a certain location at a certain time of day. (Not yet implemented.)
policy curfew home [set|SLURL]: Set the curfew home location. (Not yet implemented.)
policy curfew time <hhnn>: Set the curfew time (24-hour format with no punctuation, e.g. 1630 for 4:30 PM SLT)
policy apparel on|off|toggle: Prevent the unit from changing its outfit.
permalink return to top
charge
ARES System Manual: baseband Daemon

(input) @charge <...>

Sends a command <...> to the charger that the unit is standing on. Available commands depend on the charger model.

Typical commands include:

(input) @charge help: Retrieves help information from the charger.
(input) @charge abort: Ends charging immediately.
(input) @charge disconnect: Disconnects from the charger.
(input) @charge start: Begins charging.
(input) @charge speed <kW>: Sets the charging speed.

The @charge command will not work unless the charger in question specifically implements it. As of May 2023, the only chargers with this feature are NS products that use the ACS protocol (Charger 4, ARC, ExARC, Cartouche Charger, and outlets.)

@charge is a default alias that maps to @service baseband charge.
permalink return to top
autoexec
ARES System Manual: autoexec Scripts

Autoexec scripts are a way of distributing self-loading configuration changes for ARES users, especially to configure ARES to work with a specific main controller model.

Whenever the fs program detects that a file named autoexec.as has been added to your ARES local files, it will offer a prompt to run this script for you. Your options are as follows:

Run the script: This is usually safe, especially if you installed the autoexec.as file with your main controller. Despite the name, autoexec files do not actually run automatically.

Delete the script: If you do not wish to run the autoexec script, you may simply delete it. Well-formed autoexec scripts should call fs delete $arg.0 when finished.

If you select 'help' or 'ignore' when prompted, you will not be alerted again to the presence of the script until fs restarts.
permalink return to top