Back to HomeThe En LSL Framework is a free, open-source set of libraries, snippets, and utilities used as a framework for the Linden Scripting Language.
¶ Releases
CLICK HERE for the latest version of En (via GitHub).
You can also browse the repository directly on GitHub.
¶ Installation
En is not compiled; it can be imported directly from the repository. Follow the instructions on the GitHub page to set it up with your Second Life viewer.
¶ Importing to Scripts
The following is New Script translated to En, which serves as a good starting point for a template:
#define EN_STATE_ENTRY
#define EN_TOUCH_START
#include "en-lsl-framework/libraries.lsl"
en_state_entry()
{
llSay(0, "Hello, Avatar!");
}
en_touch_start(integer total_number)
{
llSay(0, "Touched.");
}
default
{
#include "en-lsl-framework/event-handlers.lsl"
}
When compiled, the above script will inject code to do the only thing that En scripts must always do - stop immediately on state_entry or on_rez if the "stop" linkset data pair is set to a truthy value. This is used to allow En scripts to be safely added to updater tools.
En scripts are organized as follows:
¶ Options
Options are set using preprocessor #define directives. There are several types of options.
¶ Feature Flags
Feature flags are options that are enabled when defined, regardless of value:
#define ENCLEP_ENABLE_LEP
These flags cause En to add code to support a specific feature, and/or change the operation of an existing feature. For example, if ENCLEP_ENABLE_LEP is defined, En adds special routines on compilation that encapsulate link_message Extension Protocol (LEP) messages via the Chat link_message Extension Protocol (CLEP) using the enLEP and enCLEP libraries. Some libraries, like enLEP, are only added if explicitly enabled using flags, like ENLEP_ENABLE. (Each library's page explains how to enable it, if required.)
¶ Event Flags
Event flags are like feature flags, but also cause En to call the flag (in lowercase) as a function to report the corresponding LSL event:
#include "en-lsl-framework/libraries.lsl"
en_state_entry()
{
// Your code here
}
These flags are required because the LSL preprocessor cannot detect if you have defined en_state_entry as a function. They cause En to pass a specific LSL-generated event through to a script-defined function of the same name, but lowercase. For example, if EN_STATE_ENTRY is defined, En will pass all state_entry events - after active En libraries process them - through to a script-defined function named en_state_entry. Events with parameters also pass those parameters through without modification, except in limited circumstances (for example, enLEP will immediately return the event if it detects that a link_message event uses LEP).
¶ Callback Flags
Callback flags are a combination of feature flags and event flags - they tell En to inject code to enable certain features, and they cause the appropriate library to call the flag (in lowercase) as a function to report the corresponding En-triggered "event":
#include "en-lsl-framework/libraries.lsl"
enlep_message(
integer source_link,
string source_script,
string target_script,
integer flags,
list parameters,
string data
)
{
// Your code here
}
These flags cause En to pass a specific En-generated event through to a script-defined function of the same name, but lowercase. This can also implicitly enable certain library code in event handlers. For example, if ENLEP_MESSAGE is defined, enLEP will add code to the link_message event handler that calls enlep_message(integer source_link, string source_script, string target_script, integer flags, list parameters, string data) with incoming LEP traffic. (If ENLEP_MESSAGE is not defined, En omits the LEP processing code on compilation to save script time and memory, and the link_message event handler will be omitted completely if nothing else requires it.)
¶ Overrides
Overrides are options that have a default value, but can be overridden by being defined in the script:
In this example, the integer constant changes the maximum number of UUIDs stored by enObject if object UUID history is enabled. If left undefined, it is 2 (the current and previous UUID, which is required for some En libraries).
While you can add comments to flags, do not add comments to overrides. All text after the override name will be injected into the script. This will cause the comment to be injected in-line and will break the script.
¶ Libraries
All En libraries must be included after overrides. This can be done with the following line:
If you use any other preprocessor libraries, include them immediately after En.
¶ Script-Defined Functions
Script-defined functions (both En passthroughs/callbacks and general user-defined functions) must be placed after including the libraries. Note that event and callback flags cannot be placed with their associated functions, because the preprocessor needs to know which are defined when including the libraries, but the libraries also need to be defined before any En constants (like TRACE) can be used.
¶ State
Since it is impossible to determine the active state without custom code, En scripts typically only have the default state, in which the generic event handlers are included:
default
{
#include "en-lsl-framework/event-handlers.lsl"
}
While state switching is useful in highly limited circumstances, it is generally not recommended in lieu of a global for En scripts unless absolutely necessary, since all states must have the same event handlers anyway.
¶ Package Structure
En contains the following components:
¶ Event Handlers
The event-handlers directory contains indivdual .lsl files for each event in LSL.
En only imports an event handler if it is required by an invoked En library or the EN_EVENT_NAME preprocessor flag, which triggers the associated en_event_name(...) function defined in the script. For example, the New Script in En passes through the state_entry and touch_start events.
Event handlers can also automatically log events via enLog_TraceParams if both EN_EVENT_NAME_TRACE and EN_EVENT_NAME_TRACE are defined. For example, by adding the following line to the En New Script:
#define EN_TOUCH_START_TRACE
#include "en-lsl-framework/libraries.lsl"
en_touch_start(integer total_number)
{
llSay(0, "Touched.");
}
Clicking the prim will log something similar to the following via OwnerSay if the enLog loglevel has been set to TRACE:
[20:47:15.61] (28% d0fb @214) New Script
🚦 touch_start(
num = 1
)
Then, En will call en_touch_start(...) and, by extension, llSay.