The Enforcer Command Reference

This set of pages describes use and programming of The Enforcer.  This document describes Version 1.1 of The Enforcer.

Overview of The Enforcer

The Enforcer manages one or more CHAOS Communications Hubs within a region.  For those managed Hubs, it can monitor the users currently logged in, and can bridge messages from one Hub to another, but it's main purpose is to respond to events signaled by the Hubs.

Events can be generated by a Hub itself (for example, the Hub obtains a new URL after a sim restart), but most events are caused by the activity of a Mesmerizer that's connected to the Hub.  Once The Enforcer is associated with a Hub, it will be sent every event that the Hub generates or receives, and can be programmed to respond to those events to enforce such things as curfews, sim bans, automatic application or removal of RLV constraints, running trances, automatic teleporting or force-sitting - since it can send Mesmerizer commands to the user that generated the event, it can be programmed to do anything that their Mesmerizer can do.

There are several advantages to using The Enforcer to perform complex programming, as opposed to programming the Mesmerizer via triggers.  While the Mesmerizer's triggers do offer a lot of functionality, they are stored in script memory, which is a finite and limited resource, and the response time of the Mesmerizer decreases with the number of triggers that are set.  The Enforcer's programs, by contrast, are stored in notecards, which can be effectively unlimited in number.  Also, the conditional capabilities of Mesmerizer triggers are somewhat limited, compared to the capabilities of The Enforcer scripting language.  Finally, The Enforcer allows for centralized programming that can be shared between multiple subs, and can be developed, tested and deployed while the sub is not online.

Setting up The Enforcer

Before it will do anything, The Enforcer has to be connected to at least one CHAOS Communications Hub.  If you run multiple Hubs, you should give each Hub a unique name - this will make things much less confusing.  To connect to a Hub, click on The Enforcer to get its menu, and choose "Connect...".  The Enforcer will look within the sim for CHAOS Communications Hubs and offer a list from which you can pick one to connect to.  Choosing "Connections" from the menu will show the Hubs that are currently connected.

At this stage, The Enforcer will begin to receive events from the Hub(s) that you've connected it to.  However, it has not been told what to do with these events, so it will just ignore them.  Before discussing how to respond to events, we'll take a look at a couple of other menu choices.

The "Status" button lets you see the memory usage of the most important scripts within The Enforcer, as well as some statistics about the events that are currently being processed.  Using the "Stats On" or "Stats Off" button will allow you to choose whether to display the most important statistics above The Enforcer as hovertext.

"Cur Users" and "All Users" show the logged in users, and the complete set of users on all connected Hubs.  

The remaining buttons will be discussed in the sections describing the functions they control.

Responding to events

When it receives an event from a Hub, The Enforcer will look in its inventory for a notecard that will tell it how to respond.   Each event has a name that specifies what kind of event it is.  For example, the "Login" event is generated by a sub's Mesmerizer when they put on the Mesmerizer or log in to SL.  Events also have "qualifiers" - typically the first qualifier is the legacy name of the user whose Mesmerizer generated the event, although for events generate by a Hub, the first qualifier is the name of the Hub (which is why it's important to give distinct names to your Hubs if you have more than one).  Not all events have a second qualifier, but for those that do it's typically the name of the sim in which the user was when they generated the event.

When The Enforcer receives an event of type "Event1", with qualifiers "Q1" and "Q2", it will look in its inventory, for the following notecards:

  • Event1:Q1:Q2
  • Event1:Q1:*
  • Event1:*:Q2
  • Event1:*:*
  • Event1

The first matching notecard it finds will be used to create a response to the event, by executing the script contained within the notecard.

As a more concrete example, consider the "Location" event, which is generated when a Mesmerizer enters a sim.  The qualifiers for the Location event are the user's legacy name, and the sim they're in.  So if Jane Doe is wearing a Mesmerizer that's connected to a Hub that's being monitored by The Enforcer, and Jane teleports into the "Sleepy Hill" sim, her Mesmerizer will generate a Location event, which will cause The Enforcer to look for one of the following notecards:

  • Location:Jane Doe:Sleepy Hill
  • Location:Jane Doe:*
  • Location:*:Sleepy Hill
  • Location:*:*
  • Location
The first of these that it finds will be executed.

A few events such as Location are predefined.  A full list of the predefined events can be found here.  Mesmerizers can also generate custom events with arbitrary names, using the Mesmerizer signal command:

signal eventname parameter

This will generate an event called "eventname" with a qualifier of the name of the Mesmerizer wearer.  The second argument, "parameter" here, will be passed to the notecard script that The Enforcer picks to respond to the event as a variable called "data".

Enforcer Script 

Types of instruction

Once The Enforcer has selected a response notecard, it will open the notecard and proceed to execute each line of that notecard as an instruction.  Instructions are divided into types, according to the first character of the line:
  • Lines beginning with a # character are considered comments, and ignored
  • Lines beginning with a ^ character are considered to be Mesmerizer commands, and are sent to the Mesmerizer that generated the event.
  • Lines beginning with @ or & are "Calls", that will invoke a second notecard, pausing the current notecard until the second one has completed execution.  The difference between @ and & relates to namespaces and variables, which are discussed below.
  • Lines beginning with a ! character are Enforcer Script lines, and the possible commands are detailed below.
  • All other lines are considered to be "Debugging info", and will be sent to the owner of The Enforcer.  This allows you to create a script that would send commands to a Mesmerizer, but initially omit the leading ^ from those lines.  When the notecard is executed, you will be able to see the lines that would have been sent to the event generator's Mesmerizer.  Once you're happy with them, you can just add back the ^ character to "activate" the Mesmerizer commands.

Namespaces and Variables

Before any other processing takes place on a notecard line, variable expansion is performed.  Variables have a name and a value, and to obtain the value of a variable, you precede the name of the variable with a $ symbol.  So if there is a variable called x that holds the value 42, and The Enforcer executes an instruction that contains the substring $x, then this substring will be replaced by 42.  The exception to this is if the variable name is preceded by a double-$ symbol, for example "$$x" - in this case, the $$ is replaced with a single $, and no variable expansion is performed.  This is necessary if you want to send a command that contains a $ symbol to a Mesmerizer (typically to perform variable substitution inside the Mesmerizer, rather than in The Enforcer).

Variables can be created by some Enforcer Script commands, and some standard variables are pre-defined.   For example, within a notecard that's executing for a Location event, the variables location, sim, x, y, and z are all predefined.

Variables live within namespaces.  A namespace is simply a collection of variable definitions.  Whenever The Enforcer responds to event (by choosing and executing a notecard), it will create a namespace for that event instance.  Once the notecard terminates, the namespace will be deleted.  The fact that each event instance is given its own namespace means that two events can't "collide" in their use of variables.

Calling subprograms

Usually, you don't have to care about namespaces.  But when you invoke a subprogram notecard from another notecard, using the @ or & instructions, you can choose whether the subprogram notecard gets its own namespace (@) or shares the same namespace as the calling notecard (&).  In general, @ is preferable, since it means that the subprogram is completely self-contained, and it can't overwrite any variables that the original notecard might be using.  But if the subprogram needs to return some value to its caller, then an &-call that shares the same namespace allows it to do that - variables set by the subprogram will be visible in the calling program after the subprogram terminates.

Enforcer Script Commands

Enforcer Script commands begin with a ! character, and can be thought of in two groups: single-line commands, and commands whose effect stretches across multiple lines.   Most fall into the first group.

Some Enforcer Script commands take parameters.  Parameters are separated from one another by double-colons "::".  For example, the command to set the value of a variable - !setvar - takes two parameters:  the name of the variable, and the value to set it to.  So to set variable x to the value 42, you would say:

!setvar x::42

The various Enforcer Script commands are documented below, according to functional group.






No comments:

Post a Comment

Subscribe to: Comments (Atom)