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.
En is under active and ongoing development; many functions are undocumented and have not been fully tested. Do not use this framework in your projects until this message is removed! It is experimental and highly unstable!
¶ Releases
CLICK HERE for the latest version of En (via GitHub).
You can also browse the repository directly - En is open-source!
¶ Installation
En is not compiled; it is imported directly from your computer after downloading it from the repository and unpacking it. Follow the instructions here to set it up with your Second Life viewer.
¶ Overview
For an overview of how En works, check out the following pages:
TODO
¶ Library Reference
En consists of the following libraries:
- enAvatar: functions to read avatar properties (name, group, etc.)
- enCLEP: reference implementation of the GSI Chat link_message Extension Protocol
- enDate: functions to manipulate dates and times
- enEnvironment: functions to manage the SL environment (sun, moon, sky, etc.)
- enFloat: various float-related functions
- enHTTP: HTTP request queue
- enInteger: various integer-related functions
- enInventory: functions to manage object inventory
- enKey: various key-related functions
- enKVS: basic in-memory key-value store
- enLEP: reference implementation of the GSI link_message Extension Protocol
- enList: various list-related functions
- enLog: flexible logging functions
- enLSD: reference implementation of the GSI linkset_data Scoped Naming Scheme
- enObject: functions to manipulate object properties (link numbers, hovertext, UUID history, etc.)
- enRotation: various rotation-related functions
- enString: various string-related functions
- enTimer: timer library with multiple concurrent one-shot and/or periodic timers
- enVector: various vector-related functions
¶ 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 "northbridge-sys/en-lsl-framework/libraries.lsl"
en_state_entry()
{
llSay(0, "Hello, Avatar!");
}
en_touch_start(integer total_number)
{
llSay(0, "Touched.");
}
default
{
#include "northbridge-sys/en-lsl-framework/event-handlers.lsl"
}
When compiled, the above script will only inject code to 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 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.
¶ 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 "northbridge-sys/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 "northbridge-sys/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.)
In short, the main difference to be aware of between event and callback flags is that callback flags add a significant amount of processing code and may impact performance or memory usage if used.
¶ 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 "northbridge-sys/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 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 "northbridge-sys/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.
¶ Libraries
The libraries directory contains subdirectories for each library that contains a function.lsl and macros.lsl file for each. The macros.lsl files for all libraries are loaded first, then all function.lsl files are loaded, to allow libraries to cross-reference each others' macros.
Like event handlers, En only imports the functions defined by libraries if they are called, assuming you have set up your preprocessor correctly.
Some libraries can log function calls via enLog_TraceParams if EN_LIBRARY_NAME_TRACE is defined.
¶ Snippets
The snippets directory contains importable LSL code snippets that are typically incorporated into event/callback functions manually. These snippets can perform certain basic routine operations, such as respond to pings received via en_lep_message.
¶ Utilities
The utilities directory contains full LSL scripts that perform certain utility functions. For example, SetLoglevel.lsl can be used to set the loglevel of any object it is added to by creating a script that imports it:
#include "northbridge-sys/en-lsl-framework/utilities/SetLoglevel.lsl"
Then rename the script such that its inventory name ends in your desired loglevel (FATAL, ERROR, WARN, INFO, DEBUG, or TRACE; such as "SetLoglevel.lsl TRACE") and add it to an object to automatically change its loglevel.