About Hitoshina - Language

Hitoshina - Language is a programming language for Second Life.
In line with Hitoshina’s philosophy of “contributing to a better Second Life”,
it aims to consolidate optimization know-how such as memory reduction and performance improvements, so that anyone can benefit from them without having to think about it.
When built, it outputs code in the scripting language LSL (Linden Scripting Language).

Features

• Optimization — Automatic optimizations including constant folding, inlining, and dead code elimination.
• Function and Procedure Separation — Syntactically distinguishes pure functions from procedures with side effects.
• Testing support — Unit testing and mock functionality for functions.
• Static analysis — Detects semantic errors such as missing receivers for sent channels.

Second Life Basic Concepts

Understanding the following Second Life concepts will help you learn Hitoshina - Language.

• Object: A 3D model that exists in the world. Composed of one or more prims (parts); linked prims are called a linkset.
• Script: A program embedded in an object. It operates in response to events (initialization, touch, message reception, etc.).
• Avatar: A player’s character. Uniquely identified by a UUID.
• Channel: A numbered message bus for inter-script communication. Channel 0 is world chat.
• Prim: An individual part that makes up an object. Identified by link number within a linkset. The prim declaration in HL corresponds to this concept.

Quick Start

Minimal .hl File Example

script main;

main #init {
    "Hello, World!" -> world;
}

• script main; — Declares a script instance named main. When compiled, it is output as output/main.lsl.
• main #init { ... } — The initialization event handler for the main script. Executed once when the script starts.
• "Hello, World!" -> world; — Sends a string to world chat (public chat on channel 0). -> is the message send operator, and world is the destination.

Compiling this script generates output/main.lsl corresponding to the script main; declaration:

default {
    state_entry() {
        llSay(0, "Hello, World!");
    }
}

Compilation Steps

# Compile (generate LSL from .hl file)
hl main.hl

# Output: output/main.lsl

Place the generated .lsl file into a Second Life object to use it.

Creating a Project

# Create a project directory
hl new my_project

The following directory structure is created:

my_project/
├── lib/       # Library files (.hlib)
├── prc/       # Procedure library files (.hprc)
├── msg/       # Message handler files (.hmsg)
├── output/    # Output files (.lsl)
├── tests/     # Test files (.hltest)
└── main.hl    # Main script (initial template)

The role of each directory and file is as follows:

• lib/ — Stores functions and constants shared across multiple scripts as .hlib files. Loaded with import math_lib;.
• prc/ — Stores reusable procedures (operations with side effects) as .hprc files. Loaded with include common_proc;.
• msg/ — Separates and defines processing to be executed when messages are received between scripts. Specified from the main file in the format -> sub @handler_name when sending messages.
• output/ — LSL files are generated here when you compile with hl main.hl. Place these files in Second Life.
• tests/ — Write unit tests in .hltest files. Run them with the hl test command.
• main.hl — The main script that serves as the project’s entry point. It is generated with the following initial template:

script main;

main #init {
    "Hello, World!" -> world;
}

Grammar Overview

This chapter provides a brief introduction to the overall structure of Hitoshina - Language. For detailed syntax specifications on each topic, refer to the subsequent sections.

Program Structure

An HL program is centered around a main file (.hl). The main file contains script definitions, event handlers, and the processing logic.

script main;               // Script instance declaration
prim btn;                  // Prim declaration

const int CH = 100;        // Constant definition

main #init {               // Initialization event
    "Ready" -> owner;      // Send message to owner
}

Data Types

The basic types are int, float, str, bool, key (UUID), vec (3D vector), and rot (rotation). Lists can be safely manipulated using typed lists such as ilist and slist. See Type System for details.

Variables and Constants

int count = 0;                     // Variable definition
const int MAX_COUNT = 100;         // Constant definition (uppercase naming)

Functions and Procedures

HL clearly distinguishes between functions and procedures.

• Functions: Compute and return a value. Composed of expressions only.
• Procedures: Execute operations with side effects(※). Use block syntax.

※A side effect is any operation that affects state outside the function itself, such as sending a message (->) or modifying a global variable. Because HL functions cannot have side effects, they are guaranteed to return the same result for the same input, regardless of where they are called.

script main;

// Function: returns a value via expression
int add(int a, int b) = a + b;

// Procedure: describes processing in a block
#greet |str name| {
    "Hello, " + name -> world;
}

main #init {
    add(5, 3) -> owner;    // "8"
    #greet|"World"|;       // "Hello, World"
}

See Basic Syntax for details.

Event-Driven Model

Scripts in Second Life operate on an event-driven basis. In HL, you can define event handlers such as #init (initialization), #timer (timer), #listen (message reception), and #touch_start (touch).

script main;

main #listen :0 |str msg| {        // Receive messages on channel 0
    msg -> owner;                  // Forward to owner
}

See Basic Syntax — Event Handlers for details.

Sending and Receiving Messages

The -> operator sends messages. Destinations can be world (public chat), owner (owner), or user-defined scripts and avatars.

script main;
script sub;

main #init {
    "Public message" -> world;          // World chat
    "Secret message" -> owner;          // Owner only
    "Data":100 -> sub;                  // To sub script on channel 100
}

sub #linkmsg :100 |str msg| {           // Receive messages on channel 100
    msg -> owner;
}

See Message Sending for details.

Conditionals and Loops

script main;

main #init {
    int count = 7;

    if 10 < count {
        "Large" -> owner;
    } elif 5 < count {
        "Medium" -> owner;
    } else {
        "Small" -> owner;
    }

    slist items = ["Apple", "Banana", "Cherry"];
    for str item in items {
        item -> owner;
    }
}

See Block Syntax for details.

File Organization

Code can be split into files by purpose.

See File Types for details.

File Types

Hitoshina - Language uses five file types, each serving a different purpose.

Main File (.hl)

The main file serves as the entry point for generating LSL scripts.

Definable elements:

• script/avatar/prim definitions (script main;, avatar player = "UUID";, etc.).
• Event handlers (#init, #timer, #listen, #touch, #linkmsg, etc.).
• Procedure definitions (#proc { ... } format).
• Function definitions (int add(int a, int b) = a + b; format).
• Constant definitions (const int MAX = 100; format).
• context definitions (structs for global state management).
• Property definitions (#attachable, #animable, #cache_linknum, #memory_limit_kb).
• import statements (referencing .hlib files).
• include statements (referencing .hprc files).

Elements that cannot be defined:

• ref statements (exclusive to .hmsg files).
• test definitions (exclusive to .hltest files).

Important: Block syntax is used within event handlers and procedures of the main file. Function calls can be used as expressions, but void functions (functions with no return value) do not exist. Use procedures for operations with side effects.

Example:

project/
└── main.hl

script main;

const int MAX_COUNT = 10;

context @main {
    int counter = 0;
}

#debug |str msg| {
    msg -> owner;
}

main #init |context ctx| {
    "Hello" -> world;
    ctx.counter += 1;
    #debug|"Initialized"|;
}

main #listen:0 |str msg, context ctx| {
    if ctx.counter < MAX_COUNT {
        ctx.counter += 1;
        "Count: " + ctx.counter -> owner;
    }
}

Library File (.hlib)

Library files define reusable functions and constants.

Definable elements:

• Function definitions (int add(int a, int b) = a + b;).
• Constant definitions (const int MAX_VALUE = 100;).
• Importing other libraries.

Elements that cannot be defined:

• script/avatar/prim definitions
• Event handlers
• Procedure definitions
• Property definitions

Example:

project/
└── lib/
    └── math_utils.hlib

const int MAX_VALUE = 100;

int add(int a, int b) = a + b;
int clamp(int x, int max) = max < x ? max : x;

Procedure Library File (.hprc)

Procedure library files define reusable procedures.

Definable elements:

• Procedure definitions (#proc_name { ... } or #proc_name|params| { ... }).
• Importing other libraries.
• Including other procedure libraries.

Elements that cannot be defined:

• script/avatar/prim definitions
• Event handlers
• Function definitions
• Constant definitions
• Property definitions

Example:

project/
└── prc/
    └── greet.hprc

#say_hello |str name| {
    "Hello, " + name -> world;
}

Message Handler File (.hmsg)

Message handler files separate and define processing that is invoked when messages are sent.

Definable elements:

• ref statements (specifying the referenced script file).
• import statements.
• include statements (referencing .hprc files).
• Constant definitions.
• Function definitions.
• Procedure definitions.
• linkmsg event handlers.

Elements that cannot be defined:

• script/avatar/prim definitions.
• context definitions.
• Other event handlers (#init, #timer, #listen, #touch, etc.).

Example:

project/
├── main.hl
└── msg/
    └── greeting.hmsg

script main;
script sub;

main #init {
    "Hello":100 -> sub @ greeting;  // Invoke msg/greeting.hmsg and send to sub script
}

ref main;

sub #linkmsg :100 |str msg| {
    msg -> world;
}

Using context parameters:

Within linkmsg handlers in .hmsg files, you can access context fields defined in the parent .hl file via the context parameter.

script main;
script dialog;

context @dialog {
    str dialog_part = "";
}

main #init {
    "menu":100 -> dialog @ menu;
}

ref main;

dialog #linkmsg :100 |str msg, context ctx| {
    ctx.dialog_part = msg;  // Access fields of context @dialog from parent .hl
}

Test File (.hltest)

Test files are used for writing unit tests.

Definable elements:

• import statements.
• Test expressions (comparison expression format).
• Mock definitions.

Elements that cannot be defined:

• script/avatar/prim definitions
• Event handlers
• Function definitions
• Procedure definitions and calls
• Constant definitions
• Message sending
• context definitions
• Property definitions

Example:

project/
├── lib/
│   └── math_utils.hlib
└── tests/
    └── math_utils_test.hltest

The target library and test examples:

int add(int a, int b) = a + b;
int clamp(int x, int max) = max < x ? max : x;

import math_utils as m;

// Test the add function
m::add(1, 2) == 3;
m::add(-1, 1) == 0;

// Test the clamp function
m::clamp(50, 100) == 50;
m::clamp(150, 100) == 100;

Test results:

✅ m::add(1, 2) == 3
✅ m::add(-1, 1) == 0
✅ m::clamp(50, 100) == 50
✅ m::clamp(150, 100) == 100

test result: ok. 4 passed; 0 failed

File Type Reference Table

This is a list of syntax available in each file type.

Basic Syntax

This chapter explains in detail the fundamental syntax elements that make up an HL program.

import Statement

import <library_name>;
import <library_name> as <alias>;

Makes functions and constants defined in an external library file (.hlib) available in the current file.

Example:

int add(int a, int b) = a + b;

import math_utils;

script main;

main #init {
    int result = math_utils::add(5, 3);
    result -> owner;  // Displays "8"
}

include Statement

include <library_name>;
include <library_name> as <alias>;

Makes procedures defined in an external procedure library file (.hprc) available in the current file.

Example:

#say_hello |str name| {
    "Hello, " + name -> world;
}

include greet;

script main;

main #init {
    #greet::say_hello|"World"|;
}

Identifier Naming Rules

Regular Identifiers (variable names, function names, script names, etc.)

• Only lowercase letters, digits, and underscores are allowed.
• Cannot start with a digit.
• Examples: main, my_variable, count_items, user_id_123.

Constant Identifiers

• Only uppercase letters, digits, and underscores are allowed.
• Cannot start with a digit.
• Examples: MAX_COUNT, DEFAULT_MESSAGE, CH_PUBLIC, API_KEY_1.

script/avatar/prim Definitions

Declares instances corresponding to Second Life entities.

• script: Corresponds to an LSL script. script main; generates output/main.lsl. A single .hl file can generate code for multiple scripts (e.g., script main; script sub; generates output/main.lsl and output/sub.lsl).
• avatar: A player character. Identified by specifying a UUID at definition time (UUID required).
• prim: An individual prim (part) within a linkset. Identified by link number, and serves as a target for operations like color changes and touch detection.

script <identifier>;
avatar <identifier> = "<UUID_string>";
prim <identifier>;

// Multiple instances can be declared at once with comma separation
prim <identifier>, <identifier>, ...;
script <identifier>, <identifier>, ...;

prims Definition (Prim Grouping)

Groups multiple prims using a wildcard pattern.

import standard as std;

script main;
main #cache_linknum;

prim btn123;
prim btn456;
prim btn789;

// prims group definition (the number of `*` wildcards represents the character count)
prims btn*** = btn123, btn456, btn789;  // Groups prims with btn + 3 characters = 6-character names

// Method calls on a prims group are expanded to each prim
main #init {
    #btn***.set_color|std::ALL_SIDES, <1,0,0>, 1.0|;
    // Expands to:
    // #btn123.set_color|std::ALL_SIDES, <1,0,0>, 1.0|;
    // #btn456.set_color|std::ALL_SIDES, <1,0,0>, 1.0|;
    // #btn789.set_color|std::ALL_SIDES, <1,0,0>, 1.0|;
}

// Touch event for prims group (generates conditions via pattern matching)
btn*** #touch_start @main |prim obj| {
    obj.name() -> owner;  // Identifier name of the touched prim
    obj.desc() -> owner;  // Description of the touched prim
}

Constraints:

• Wildcards are suffix-only (btn*** is valid, ***btn is not).
• Assignment is required at declaration (prims btn***; alone is not valid).
• All prims matching the pattern must be assigned.
• prim and prims types are not interconvertible.

Event Handlers

Scripts in Second Life operate on an event-driven basis. In HL, event handlers are defined in the format script_identifier #event_name.

init Event

Executed once when the script starts (on reset or attachment).

<script_identifier> #init {
    // Processing
}

<script_identifier> #init|context <variable>| {
    // Processing (with context access)
}

<script_identifier> #init|bool <variable>| {
    // Processing (the bool variable distinguishes the startup context)
}

<script_identifier> #init|bool <variable>, context <variable>| {
    // Processing (bool variable + context access)
}

bool parameter (optional): For scripts with #attachable, the body of #init is expanded to both the LSL state_entry and attach(key id) handlers. Declaring a bool parameter exposes a variable that evaluates to false on the state_entry path and true on the attach path, so logic that should run only on attachment can branch on it. When #attachable is not specified, the bool variable is always false.

script main;
main #attachable;

main #init|bool is_attach| {
    if is_attach {
        "attached!" -> owner;
    } else {
        "started" -> owner;
    }
}

timer Event

Executed repeatedly at the configured interval. Set the timer using the standard procedure set_timer().

<script_identifier> #timer {
    // Processing
}

<script_identifier> #timer|context <variable>| {
    // Processing (with context access)
}

listen Event

Receives chat messages on the specified channel. Channel 0 is world chat (public chat), and other numbers are used for inter-script communication.

// No parameters
<script_identifier> #listen :<channel_number> {
    // Processing
}

// Message only
<script_identifier> #listen :<channel_number> |str msg| {
    // Processing
}

// All parameters
<script_identifier> #listen :<channel_number> |str name, key id, str msg| {
    // Processing (name: sender name, id: sender UUID, msg: message)
}

// With context access
<script_identifier> #listen :<channel_number> |str msg, context ctx| {
    // Processing (context accessible)
}

// With owner filter
<script_identifier> #listen :<channel_number> + owner |str msg| {
    // Processing (receives from owner only)
}

Parameters (all optional, fixed order):

• str <variable> — Sender name
• key <variable> — Sender UUID
• str <variable> — Message body
• context <variable> — Context access (specified at the end)

Valid combinations:

• |str name, key id, str msg| — sender name, UUID, and message
• |str name, key id| — sender name and UUID
• |str name, str msg| — sender name and message
• |key id, str msg| — UUID and message
• |key id| — UUID only
• |str msg| — message only
• omitted
• , context <variable> can be appended to any of the above

※ A single str parameter is interpreted as the message body.

Channel number:

• Literal value: #listen :0, #listen :123.
• Constant name: #listen :PUBLIC_CHANNEL.
• Library constant: #listen :const::CH_PUBLIC.

Owner filter (+ owner):

• Receives messages only from the owner.

linkmsg Event

Executed when a link message is received from another script within the same object.

<script_identifier> #linkmsg :<channel_number> |str msg| {
    // Processing
}

// With context access
<script_identifier> #linkmsg :<channel_number> |str msg, context ctx| {
    // Processing (context accessible)
}

touch_start Event

Executed once at the moment a player clicks (touches) a prim. The target prim is specified by its identifier, and bound to a script with @.

<prim_identifier> #touch_start @ <script_identifier> {
    // Processing
}

<prim_identifier> #touch_start :<face> @ <script_identifier> {
    // Processing (executed only when a specific face is touched)
}

// prim parameter (retrieve information about the touched prim)
<prim_identifier> #touch_start @ <script_identifier> |prim <variable>| {
    <variable>.name() -> owner;  // Identifier name of the prim
    <variable>.desc() -> owner;  // Description of the prim
}

// Combination of prim parameter and context parameter
<prim_identifier> #touch_start @ <script_identifier> |prim <variable>, context <ctx_variable>| {
    // Processing
}

// Same applies to prims groups (generates conditions via pattern matching)
<prims_group_identifier> #touch_start @ <script_identifier> |prim <variable>| {
    <variable>.name() -> owner;  // Identifier name of the individual touched prim
}

Prim parameter methods:

• <variable>.name(): Gets the identifier name of the prim (str type).
• <variable>.desc(): Gets the Description of the prim (str type).

LSL conversion expansion example:

// obj.name() → llGetLinkName($link_num)
// obj.desc() → llList2String(llGetObjectDetails(llGetLinkKey($link_num), [OBJECT_DESC]), 0)

• If a method is not referenced within the block, the corresponding code is not generated (optimization).

touch Event

Executed continuously while the player is touching the prim. The parameters are the same as #touch_start.

// Basic
<prim_identifier> #touch @ <script_identifier> {
    // Processing
}

// Face specification
<prim_identifier> #touch :<face> @ <script_identifier> {
    // Processing
}

// prim parameter (retrieve information about the touched prim)
<prim_identifier> #touch @ <script_identifier> |prim <variable>| {
    <variable>.name() -> owner;  // Prim identifier name
    <variable>.desc() -> owner;  // Prim Description
}

// Combination of prim parameter and context
<prim_identifier> #touch @ <script_identifier> |prim <variable>, context <ctx_variable>| {
    // Processing
}

Differences from #touch_start:

sensor Event

Executed when a sensor started by the standard procedures sensor_repeat() / sensor() detects objects or agents.

<script_identifier> #sensor |int <num_detected_variable>| {
    // <num_detected_variable>: number of detected entities (int type)
}

<script_identifier> #sensor |int <num_detected_variable>, context <ctx_variable>| {
    // Can also be combined with context parameter
}

no_sensor Event

Executed when the sensor detects nothing.

<script_identifier> #no_sensor {
    // Processing
}

<script_identifier> #no_sensor |context <ctx_variable>| {
    // Can also be combined with context parameter
}

run_time_permissions Event

Executed when the permission requested by the standard procedure request_permissions() is granted or denied. The permission variable (int type) is a bitmask representing the granted permissions.

<script_identifier> #run_time_permissions |int <permission_variable>| {
    // <permission_variable>: bitmask of granted permissions (int type)
}

<script_identifier> #run_time_permissions |int <permission_variable>, context <ctx_variable>| {
    // Can also be combined with context parameter
}

dataserver Event

Executed when an asynchronous data request such as the standard library functions request_agent_data() / get_notecard_line() completes. The query ID variable (key type) identifies the request, and the data variable (str type) holds the returned data.

<script_identifier> #dataserver |key <queryid_variable>, str <data_variable>| {
    // <queryid_variable>: query ID identifying the request (key type)
    // <data_variable>: returned data (str type)
}

<script_identifier> #dataserver |key <queryid_variable>, str <data_variable>, context <ctx_variable>| {
    // Can also be combined with context parameter
}

changed Event

Executed when the object changes in some way (inventory added, link changed, region crossed, etc.). The int variable receives a bitfield describing the kind of change.

<script_identifier> #changed |int <change_flags_variable>| {
    // <change_flags_variable>: bitfield describing the kind of change (int type)
    //   Bitwise OR of CHANGED_INVENTORY, CHANGED_COLOR, CHANGED_SHAPE, CHANGED_SCALE,
    //   CHANGED_TEXTURE, CHANGED_LINK, CHANGED_ALLOWED_DROP, CHANGED_OWNER,
    //   CHANGED_REGION, CHANGED_TELEPORT, CHANGED_REGION_START, CHANGED_MEDIA,
    //   CHANGED_RENDER_MATERIAL
}

<script_identifier> #changed |int <change_flags_variable>, context <ctx_variable>| {
    // Can also be combined with context parameter
}

LSL conversion:

changed(integer change)
{
    // Block contents
}

on_rez Event

Executed when the object is rezzed in-world or when an avatar attaches it. The int variable receives the start_param value passed by llRezObject() or similar; for manual rez from a user or another object it is typically 0.

<script_identifier> #on_rez |int <start_param_variable>| {
    // <start_param_variable>: start_param value at rez time (int type)
}

<script_identifier> #on_rez |int <start_param_variable>, context <ctx_variable>| {
    // Can also be combined with context parameter
}

LSL conversion:

on_rez(integer start_param)
{
    // Block contents
}

Difference Between Procedures and Functions

Procedure Definition

// Without parameters
#<procedure_name> {
    // Processing
}

// With parameters
#<procedure_name> |<argument_list>| {
    // Processing
}

Example:

script main;

#debug_print |str message| {
    message -> world;
}

main #init {
    #debug_print|"Hello"|;
}

Procedure Invocation

#<procedure_name>;
#<procedure_name>|<arguments>|;

Function Definition

Functions are used to compute and return values. They can be defined in .hl, .hlib, and .hmsg files.

<return_type> <function_name>(<argument_list>) = <expression>;

Example:

script main;

int add(int a, int b) = a + b;

main #init {
    int result = add(5, 3);
    result -> owner;  // Displays "8"
}

Important: Function bodies consist of expressions only. The following syntax cannot be used:

• Variable definitions and reassignments.
• Procedure calls.
• Message sending.
• Control syntax (if statements, while statements, for each statements).

Function-Only Expressions

In function bodies, the following special expressions can be used in addition to regular expressions. These are only available within function definitions and cannot be used in block syntax (event handlers or procedures).

Ternary Operator

Returns a value based on a condition.

script main;

str status(bool flag) = flag ? "yes" : "no";
str classify(int x) = 10 < x ? "big" : "small";

main #init {
    status(true) -> owner;   // "yes"
    status(false) -> owner;  // "no"
    classify(15) -> owner;   // "big"
    classify(3) -> owner;    // "small"
}

match Expression

Performs pattern matching on a value and returns the result corresponding to the matched pattern.

script main;

// Basic form: value ? pattern1 => result1 ? pattern2 => result2 : default
str status(int code) = code
    ? 0 => "success"
    ? 1 => "error"
    : "unknown";

main #init {
    status(0) -> owner;  // "success"
    status(1) -> owner;  // "error"
    status(9) -> owner;  // "unknown"
}

Variable binding with the as clause:

You can name the target value of a match expression and reference it in the pattern result expressions.

script main;

str check(str code) = code.substr(0, 0) as c
    ? "A" => "admin:" + c
    ? "U" => "user:" + c
    : "unknown:" + c;

main #init {
    check("A01") -> owner;  // "admin:A"
    check("U99") -> owner;  // "user:U"
    check("X00") -> owner;  // "unknown:X"
}

map Expression

Transforms each element of a collection (list type or str type) and returns a new list. For str types, iteration occurs character by character.

script main;

// Basic form: map type variable in list : transform_expression
ilist increment(ilist numbers) = map int n in numbers : n + 1;

// With index: use the index keyword to get the index
slist with_index(slist items) = map str s in items index i : s + i.to_str();

// Range form: map int variable = start to end : transform_expression
// Variable must be int type. Range is inclusive (start <= variable <= end)
ilist make_range() = map int i = 0 to 2 : i + 10;

// str type collection: transforms character by character
slist chars(str text) = map str c in text : c + "!";

main #init {
    increment([1, 2, 3]).join(", ") -> owner;    // "2, 3, 4"
    with_index(["a", "b"]).join(", ") -> owner;  // "a0, b1"
    make_range().join(", ") -> owner;            // "10, 11, 12"
    chars("hi").join(", ") -> owner;             // "h!, i!"
}

find Expression

Searches a list for the first element matching a condition and returns the corresponding value. Two syntaxes are supported: a pattern match form and a ternary operator form.

script main;

// Pattern match form: find type variable in list : compared_value ? pattern => result : default
// Classify by the first character of each element and return the result for the first match
str classify_first(slist codes) =
    find str c in codes : c.substr(0, 0)
    ? "A" => "admin: " + c
    ? "U" => "user: " + c
    : "unknown";

// Pattern match form (as rebinding): find type variable in list : compared_value as identifier ? pattern => result : default
// Binds the evaluated compared_value to a new identifier so it can be referenced in subsequent patterns
// (equivalent to as rebinding in match expressions). If the as identifier has the same name as the loop
// variable, it shadows the loop variable.
str classify_upper(slist names) =
    find str item in names : item.to_upper() as item
    ? "ALICE" => "is_alice"
    : "none";

// Ternary operator form: find type variable in list : condition ? true_value : false_value
// Return the first message that contains the given keyword
str find_with_keyword(slist messages, str keyword) =
    find str msg in messages : 0 <= msg.index_of(keyword) ? msg : "not found";

// Range form: find int variable = start to end : ternary form
// Variable must be int type. Range is inclusive (start <= variable <= end)
// Return the first integer in 1..10 that is a multiple of divisor
str first_multiple_of(int divisor) =
    find int i = 1 to 10 : i % divisor == 0 ? "first: " + i.to_str() : "none";

main #init {
    classify_first(["X01", "U99", "A02"]) -> owner;                            // "user: U99"
    classify_upper(["bob", "alice", "carol"]) -> owner;                        // "is_alice"
    find_with_keyword(["hello world", "test code", "say hi"], "hi") -> owner;  // "say hi"
    first_multiple_of(3) -> owner;                                             // "first: 3"
}

fold Expression

Aggregates each element of a collection (list type or str type) into a single value. For str types, iteration occurs character by character.

script main;

// Basic form: fold type variable in list : aggregation_expression
int sum_all(ilist numbers) = fold int n in numbers : n;
str concat_all(slist words) = fold str w in words : w;

// str type collection: aggregates character by character
str separate(str text) = fold str c in text : c + ",";

// Range form: fold int variable = start to end : aggregation_expression
// Variable must be int type. Range is inclusive (start <= variable <= end)
int sum_range() = fold int i = 0 to 2 : i;

// Accumulator form: adds a variable to track independent state across loop iterations
// Syntax: fold type variable = start to end, accumulator_type accumulator = initial_value : aggregation_expression, update_expression
// Collection form: fold type variable in list, accumulator_type accumulator = initial_value : aggregation_expression, update_expression
// Each iteration: 1) evaluates the aggregation expression and accumulates the result, 2) updates the accumulator with the update expression
str fx() = fold int i = 0 to 2, int acc = 0 : (i + acc).to_str(), i + 1;

// str type collection + accumulator: joining with separator
str join_chars(str text) = fold str c in text, str sep = "" : sep + c, ",";

main #init {
    sum_all([1, 2, 3]) -> owner;           // 6  (1 + 2 + 3)
    concat_all(["a", "b", "c"]) -> owner;  // "abc"
    separate("abc") -> owner;              // "a,b,c,"
    sum_range() -> owner;                  // 3  (0 + 1 + 2)
    fx() -> owner;                         // "024"
    join_chars("abc") -> owner;            // "a,b,c"
}

Constant Definition

const <type> <CONSTANT_IDENTIFIER> = <constant_expression>;

Constant expressions can use literal values, references to other constants, and arithmetic expressions involving them. Non-constant expressions such as variable references, function calls, and method calls cannot be used (E0602 error).

If the result of an integer constant expression exceeds the int range (-2147483648 to 2147483647), an E0308 error is reported. Besides expressions of literals only (const int BAD = 2147483647 + 1;), expressions referencing non-library constants in the same file (const int MAX = 2147483647; const int BAD = MAX + 1;) are also detected. Because the check runs at compile time (constant folding), LSL generation is skipped for files containing an overflow. Overflow through library constants (lib::MAX) is not detected at this time. The check is not limited to constant definitions; it also applies to integer constant expressions inside ordinary statements (e.g. int x = 2147483647 + 1;).

Example:

const int MAX_COUNT = 10;
const str DEFAULT_MESSAGE = "hello";
const int CH_PUBLIC = 0;
const str GREETING = DEFAULT_MESSAGE + " world";
const int DOUBLED = MAX_COUNT * 2;

Variable Definition

// New variable definition
<type> <identifier> = <expression>;

// Variable reassignment
<identifier> = <expression>;

Example:

script main;

main #init {
    int count = 10;
    str message = "hello";
    count += 1;
    message -> owner;
}

Bitwise Operators

Performs bitwise operations on integers (int type). Used in Second Life permission handling and similar contexts.

script main;

main #init {
    int a = 12;               // 0b1100
    int b = 10;               // 0b1010
    int and_result = a & b;   // 8  (0b1000)
    int or_result  = a | b;   // 14 (0b1110)
    int xor_result = a ^ b;   // 6  (0b0110)
}

Note: When using | for button grouping in dialog syntax, the bitwise OR operator conflicts with the syntax, so expressions must be wrapped in parentheses.

int a = 12;
int b = 10;

// NG: the | in a | b is indistinguishable from the button delimiter — causes an error
a | b | "OK" | @owner:1 -> world;

// OK: wrap in parentheses
(a | b) | "OK" | @owner:1 -> world;

context Definition

Defines per-script context information. The owning script is specified with @script_name. Defining multiple contexts for the same script results in an E1003 error. If the script specified by @script_name is not defined with a script statement, an E1004 error occurs.

context @<script_name> {
    <type> <field_name> = <initial_value>;
    <type> <field_name>;
    ...
}

Field initializers can specify the following:

• Literals (int / float / str / key / bool / vec / rot / list)
• Constant references (CONST or lib::CONST)
• Arithmetic expressions combining the above (+, -, *, /, %, bitwise & / ^ / |, logical, comparison, unary !, parentheses)

When omitted, the type’s zero value is used (int=0, str="", bool=false, etc.). Function calls and variable references are not allowed (E0602 InvalidConstExpression). At LSL generation, these initializers are constant-folded and emitted as a single literal value (because LSL’s global variable initializers cannot reference other global variables).

Example:

const int MAX_COUNT = 100;
const int BASE = 10;

context @main {
    int menu = 1;
    str text = "default";
    int max_value = MAX_COUNT;  // Constant reference
    int answer = 1 + 2 * 3;     // Arithmetic expression -> 7
    int offset = BASE + 5;       // Arithmetic with constant reference -> 15 (folded at LSL generation)
    float value;                // No initial value (zero value)
}

script main;

main #init|context ctx| {
    ctx.menu = 2;
    ctx.text = "updated";
    int current = ctx.menu;
    current -> owner;
}

Property Definitions

// attachable definition (also executes #init and #animable processing on attachment)
<script_identifier> #attachable;

// animable definition (automatically requests animation permission)
<script_identifier> #animable;

// cache_linknum definition (caches prim link numbers)
<script_identifier> #cache_linknum;

// memory_limit_kb definition (sets memory limit in KB)
<script_identifier> #memory_limit_kb <integer_value_or_const_reference>;

When #cache_linknum is specified, a _cache_linknum() function is generated to cache the link numbers of prim instances. This function is automatically called at the beginning of the state_entry and attach event handlers. At the start of the function, all existing caches with the $ prefix are deleted using llLinksetDataDeleteFound("^\\$", "") before re-caching, so it handles prim name changes correctly.

When a prims group is defined, prims belonging to the group are processed using prefix + length pattern matching conditions instead of individual name comparisons. This reduces memory usage of the generated code. Prims not belonging to any group are processed with individual name comparisons as before.

When #memory_limit_kb is specified, llSetMemoryLimit is called at the beginning of state_entry. The value is specified in KB and multiplied by 1024 to convert to bytes. In addition to literal values, you can also reference constants defined with const int.

script main;

const int MEM_KB = 32;

main #memory_limit_kb MEM_KB;  // → llSetMemoryLimit(32768);

main #init {
    "Ready" -> owner;
}

Prim Method Calls

Methods can be called on prim instances.

set_color Method

Sets the color of a prim.

#<prim_identifier>.set_color|<face>, <color>, <alpha>|;

Parameters:

• face: Face number (int). Use ALL_SIDES to specify all faces.
• color: Color (vec). Format <R, G, B> (each value from 0.0 to 1.0).
• alpha: Opacity (float). 0.0 to 1.0.

Usage example:

import standard as std;

script main;
main #cache_linknum;
prim obj1;
prim obj2;

main #attachable;

main #init {
    #obj1.set_color|std::ALL_SIDES, <1.0, 0.0, 0.0>, 1.0|;  // Red, opaque
    #obj2.set_color|0, <0.0, 1.0, 0.0>, 0.5|;               // Face 0, green, semi-transparent
}

desc Method

Gets the Description of a prim.

str description = #<prim_identifier>.desc();

Return value: str type (the prim’s description string)

Usage example:

script main;
main #cache_linknum;
prim btn;

main #init {
    #btn.desc() -> world;  // Output prim description to chat
}

Note: The #cache_linknum attribute is required to use prim methods.

Early Return Statement

end;

Terminates execution of an event handler or procedure early. Cannot be used in functions.

Type System

Basic Types

• bool: Boolean type (true/false). Converted to integer type in LSL (true=1, false=0).
• int: Integer type (32-bit signed, range -2147483648 to 2147483647). A constant expression whose result exceeds this range is a compile error (E0308).
• float: Floating-point number type.
• str: String type.
• key: UUID type.
• vec: Vector type (3-dimensional).
• rot: Rotation type (4-dimensional quaternion).

Typed Lists

The following typed list types are supported for type-safe list operations:

• ilist: Integer list type (element type: int).
• flist: Float list type (element type: float).
• slist: String list type (element type: str).
• vlist: Vector list type (element type: vec).
• rlist: Rotation list type (element type: rot).
• klist: Key list type (element type: key).

Example:

ilist numbers = [1, 2, 3];
slist names = ["Alice", "Bob"];
vlist positions = [<0,0,0>, <1,1,1>];

int first = numbers.at(0);     // Type is inferred as int
str name = names.at(1);        // Type is inferred as str

Type Compatibility Rules

Allowed Implicit Conversions

Prohibited Implicit Conversions

Expressions and Operators

Expression Structure

Terms

• Literal values (numbers, strings, lists, etc.).
• Identifiers.
• Function calls: <func_name>(<arg_list>).
• Library function calls: <alias>::<func_name>(<arg_list>).
• Method calls: <prim>.<method_name>(<arg_list>).
• Field access: <prim>.<field_name>.
• Library constant access: <alias>::<const_name>.
• Increment/decrement: ++<var>, <var>++, --<var>, <var>--.
• Parenthesized expressions: (<expr>).

Operators (by precedence)

1. High precedence: *, /, %
2. Addition/subtraction: +, -
3. Comparison: <, <=, >, >= (return type: bool)
4. Equality: ==, != (return type: bool)
5. Logical: &&, || (return type: bool)
6. Bitwise: &, |, ^
7. Assignment: +=, -=, *=, /=, %=

Unary Operators

• Logical negation: !<expr>.

Literals

// Numbers
123, -456              // Integer
123.45, -67.89         // Floating-point

// Strings
"string content"

// Keys (UUIDs)
"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

// Vectors
<x, y, z>

// Rotations
<x, y, z, s>

// Lists
[element1, element2, element3]

String escape sequences:

• \": double quote.
• \\: backslash.
• \/: slash.
• \n: newline.
• \r: carriage return.
• \t: tab.
• \b, \f: not converted, because LSL does not support them; output as the two characters \b / \f.
• \uXXXX: Unicode character (4-digit hexadecimal). Not converted, because LSL does not support it.

Methods

Method Calls and Chaining

<prim>.<method_name>(<arg_list>)
<prim>.<method1>(<arg>).<method2>(<arg>)

Example:

str text = "hello world";
str result = text.substr(0, 5).replace("l", "x");   // "hexxo"

int number = 123;
str formatted = number.to_str().replace("1", "X");  // "X23"

Built-in Methods

str Type Methods

str text = "Hello, World!";
text.len()                  // 13
text.substr(0, 5)           // "Hello"
text.index_of("World")      // 7
text.replace("World", "SL") // "Hello, SL!"
text.to_lower()             // "hello, world!"
text.split(", ")            // ["Hello", "World!"]
text.insert(5, "!!")        // "Hello!!, World!"
text.delete(5, 7)           // "Hello World!"

"123".to_int()              // 123

Typed List Methods (Common)

Methods available for all typed lists (ilist, flist, slist, vlist, rlist, klist).

slist names = ["Alice", "Bob", "Charlie"];
names.at(1)                  // "Bob"
names.len()                  // 3
names.index_of("Charlie")    // 2
names.exists("Alice")        // true
names.join(", ")             // "Alice, Bob, Charlie"
names.slice(0, 1)            // ["Alice", "Bob"]
names.delete(1, 1)           // ["Alice", "Charlie"]

ilist nums = [10, 20, 30];
nums.at(0)                   // 10
nums.len()                   // 3

int Type Methods

int num = 42;
num.to_str()                 // "42"

key Type Methods

float Type Methods

float val = 3.14;
val.to_int()                 // 3 (decimal part truncated)
val.to_str()                 // "3.14"

vec Type Methods

rot Type Methods

Field Access

vec Type Fields

rot Type Fields

Example:

vec position = <1.0, 2.0, 3.0>;
float x = position.x;    // 1.0

rot rotation = <0.0, 0.0, 0.0, 1.0>;
float s = rotation.s;    // 1.0

// Method chaining after field access
int x_int = position.x.to_int();

Block Syntax

Available Statements

Syntax elements available within a block {}:

• Variable definition statements
• Variable reassignment statements
• Message sending statements
• Procedure call statements
• Conditional branching statements (if/elif/else)
• switch statements
• for to loop statements
• for each loop statements
• Early return statements

Control Flow

if/elif/else

if <condition> {
    // statements
} elif <condition> {
    // statements
} else {
    // statements
}

while

while <condition> {
    // statements
}

for to

for int <var_name> = <start> to <end> {
    // statements
}

Example:

script main;

main #init {
    for int i = 1 to 10 {
        i -> owner;
    }
}

for each

for <type> <var_name> in <collection> {
    // statements
}

// With index
for <type> <var_name> in <collection> index <index_var> {
    // statements
}

A list type (ilist, slist, flist, etc.) or str type can be specified as the collection. When the str type is used, iteration occurs character by character.

Example:

script main;

main #init {
    slist my_list = ["apple", "banana", "cherry"];
    for str item in my_list {
        item -> owner;
    }
}

Example with str type collection:

script main;

main #init {
    // str type collection (iterates character by character)
    for str c in "hello" {
        c -> world;
    }
}

switch

switch <expr> {
    <pattern1> => <stmt_or_block>;
    <pattern2> => {
        // Multiple statements
    }
}

The following can be used as a single statement: message sending, variable definition, variable reassignment, procedure call, prim method call.

Example:

script main;

#greet {
    "Hello!" -> world;
}

#farewell {
    "Goodbye!" -> world;
}

main #listen:0 |str msg| {
    switch msg {
        "hello" => #greet;
        "bye" => {
            #farewell;
            "See you" -> world;
        }
    }
}

Default pattern _:

Using _ (wildcard) allows you to define processing for cases that do not match any pattern.

switch face {
    0 => #btn0.set_color|1, <1.0, 0.0, 0.0>, 1.0|;
    1 => #btn1.set_color|1, <0.0, 1.0, 0.0>, 1.0|;
    _ => #btn0.set_color|0, <1.0, 1.0, 1.0>, 1.0|;
}

Early Return

Terminates execution of an event handler or procedure early. Cannot be used in functions.

end;

Example:

script main;

#greet |str name| {
    // Do nothing if name is empty
    if name == "" {
        end;
    }
    ("Hello, " + name + "!") -> owner;
}

main #init {
    #greet|"Alice"|;
    #greet|""|;     // exits via end;
}

Standard Library

Usage

To use a standard library function, import the standard library and call it with its prefix.

import standard as std;

script main;

str get_value() = std::read_from_lsd("key");  // OK
// str get_value() = read_from_lsd("key");    // Error

Each function entry uses the signature form return_type function_name(arg_type arg_name, …) (the same form as a Hitoshina Language declaration).

Math functions

int abs(int value)

Returns the absolute value.

• Parameters:
  • value (int): Target integer value
• Returns: int — the absolute value

float fabs(float value)

Returns the absolute value of a floating-point number.

• Parameters:
  • value (float): Target floating-point value
• Returns: float — the absolute value of a floating-point number

float sin(float value)

Returns the sine.

• Parameters:
  • value (float): Target floating-point value
• Returns: float — the sine

float cos(float value)

Returns the cosine.

• Parameters:
  • value (float): Target floating-point value
• Returns: float — the cosine

float tan(float value)

Returns the tangent.

• Parameters:
  • value (float): Target floating-point value
• Returns: float — the tangent

float asin(float value)

Returns the arc sine.

• Parameters:
  • value (float): Target floating-point value
• Returns: float — the arc sine

float acos(float value)

Returns the arc cosine.

• Parameters:
  • value (float): Target floating-point value
• Returns: float — the arc cosine

float atan2(float y, float x)

Returns the two-argument arc tangent.

• Parameters:
  • y (float): Y component
  • x (float): X component
• Returns: float — the two-argument arc tangent

float log(float value)

Returns the natural logarithm.

• Parameters:
  • value (float): Target floating-point value
• Returns: float — the natural logarithm

float log10(float value)

Returns the base-10 logarithm.

• Parameters:
  • value (float): Target floating-point value
• Returns: float — the base-10 logarithm

float pow(float base, float exponent)

Returns the value raised to the given power.

• Parameters:
  • base (float): Base
  • exponent (float): Exponent
• Returns: float — the value raised to the given power

float sqrt(float value)

Returns the square root.

• Parameters:
  • value (float): Target floating-point value
• Returns: float — the square root

int ceil(float value)

Ceiling function (rounds up).

• Parameters:
  • value (float): Target floating-point value
• Returns: int — (rounds up)

int floor(float value)

Floor function (rounds down).

• Parameters:
  • value (float): Target floating-point value
• Returns: int — (rounds down)

int round(float value)

Rounds to the nearest integer.

• Parameters:
  • value (float): Target floating-point value
• Returns: int — to the nearest integer

float frand(float range)

Returns a random number in the range [0, range).

• Parameters:
  • range (float): Upper bound (returns a value less than this)
• Returns: float — a random number in the range [0, range)

int mod_pow(int a, int b, int c)

Computes the modular exponentiation (a^b) mod c.

• Parameters:
  • a (int): Base
  • b (int): Exponent
  • c (int): Modulus
• Returns: int — the remainder of (a raised to the power b) divided by c

String functions

int string_length(str text)

Returns the length of the string.

• Parameters:
  • text (str): Target string
• Returns: int — the length of the string

str get_sub_string(str source, int start, int end)

Returns a substring.

• Parameters:
  • source (str): Source string
  • start (int): Start index (0-based)
  • end (int): End index (0-based; negative values count from the end)
• Returns: str — a substring

str string_trim(str text, int type)

Removes leading and trailing whitespace from the string.

• Parameters:
  • text (str): Target string
  • type (int): Flag value specifying the kind
• Returns: str — string

str to_lower(str text)

Converts the string to lowercase.

• Parameters:
  • text (str): Target string
• Returns: str — the string to lowercase

str to_upper(str text)

Converts the string to uppercase.

• Parameters:
  • text (str): Target string
• Returns: str — the string to uppercase

int substring_index(str source, str pattern)

Searches for the position of a substring.

• Parameters:
  • source (str): Source string
  • pattern (str): Search pattern string
• Returns: int — for the position of a substring

str insert_string(str dst, int pos, str src)

Inserts a string into another.

• Parameters:
  • dst (str): Destination string
  • pos (int): Insertion position (0-based index)
  • src (str): Source string
• Returns: str — a string into another

str delete_sub_string(str src, int start, int end)

Deletes a substring.

• Parameters:
  • src (str): Source string
  • start (int): Start index (0-based)
  • end (int): End index (0-based; negative values count from the end)
• Returns: str — a substring

str replace_sub_string(str src, str pattern, str replacement, int count)

Replaces a substring.

• Parameters:
  • src (str): Source string
  • pattern (str): Search pattern string
  • replacement (str): Replacement string
  • count (int): Number of replacements (0 for all)
• Returns: str — a substring

slist parse_string(str src, slist separators, slist spacers)

Splits a string into a list.

• Parameters:
  • src (str): Source string
  • separators (slist): List of separator strings
  • spacers (slist): List of spacer strings (kept as separators in the result)
• Returns: slist — a string into a list

slist parse_string_keep_nulls(str src, slist separators, slist spacers)

Splits a string into a list (preserving empty elements).

• Parameters:
  • src (str): Source string
  • separators (slist): List of separator strings
  • spacers (slist): List of spacer strings (kept as separators in the result)
• Returns: slist — a string into a list (preserving empty elements)

slist csv_to_list(str src)

Converts CSV text to a list.

• Parameters:
  • src (str): Source string
• Returns: slist — CSV text to a list

str list_to_csv(slist src)

Converts a list to CSV text.

• Parameters:
  • src (slist): Source list
• Returns: str — a list to CSV text

str dump_list_to_string(slist src, str separator)

Joins a list into a single string.

• Parameters:
  • src (slist): Source list
  • separator (str): Separator string
• Returns: str — a list into a single string

str char(int val)

Generates a character from a Unicode code point.

• Parameters:
  • val (int): Unicode code point to generate the character from
• Returns: str — the generated single-character string

int ord(str val, int index)

Returns the Unicode code point of the character at the given position in a string.

• Parameters:
  • val (str): Target string
  • index (int): Character position to get the code point of (0-based)
• Returns: int — the Unicode code point of the character at the given position

List functions

int get_list_length(ilist list)

Returns the length of the list (deprecated: use the .len() method).

• Parameters:
  • list (ilist): Target integer list
• Returns: int — the length of the list (deprecated: use the .len() method)

int list_find(slist src, slist test)

Searches a list within a list.

• Parameters:
  • src (slist): Source list
  • test (slist): Search target list
• Returns: int — a list within a list

slist list_sort(slist src, int stride, int ascending)

Sorts a list.

• Parameters:
  • src (slist): Source list
  • stride (int): Stride (processing unit)
  • ascending (int): 1 for ascending, 0 for descending
• Returns: slist — a list

slist list_random(slist src, int stride)

Randomises a list.

• Parameters:
  • src (slist): Source list
  • stride (int): Stride (processing unit)
• Returns: slist — a list

slist list_insert(slist dst, slist src, int pos)

Inserts one list into another.

• Parameters:
  • dst (slist): Destination list
  • src (slist): Source list
  • pos (int): Insertion position (0-based index)
• Returns: slist — one list into another

slist list_replace(slist dst, slist src, int start, int end)

Replaces elements in a list.

• Parameters:
  • dst (slist): Destination list
  • src (slist): Source list
  • start (int): Start index (0-based)
  • end (int): End index (0-based; negative values count from the end)
• Returns: slist — elements in a list

int get_list_entry_type(slist src, int index)

Returns the type of a list element.

• Parameters:
  • src (slist): Source list
  • index (int): Index within the list (0-based)
• Returns: int — the type of a list element

int list_to_int(slist src, int index)

Reads an integer from a list.

• Parameters:
  • src (slist): Source list
  • index (int): Index within the list (0-based)
• Returns: int — an integer from a list

float list_to_float(slist src, int index)

Reads a floating-point number from a list.

• Parameters:
  • src (slist): Source list
  • index (int): Index within the list (0-based)
• Returns: float — a floating-point number from a list

str list_to_string(slist src, int index)

Reads a string from a list.

• Parameters:
  • src (slist): Source list
  • index (int): Index within the list (0-based)
• Returns: str — a string from a list

key list_to_key(slist src, int index)

Reads a key from a list.

• Parameters:
  • src (slist): Source list
  • index (int): Index within the list (0-based)
• Returns: key — a key from a list

vec list_to_vec(slist src, int index)

Reads a vector from a list.

• Parameters:
  • src (slist): Source list
  • index (int): Index within the list (0-based)
• Returns: vec — a vector from a list

rot list_to_rot(slist src, int index)

Reads a rotation from a list.

• Parameters:
  • src (slist): Source list
  • index (int): Index within the list (0-based)
• Returns: rot — a rotation from a list

float list_statistics(int operation, flist src)

Computes statistics over a list.

• Parameters:
  • operation (int): Statistical operation kind (use std::LIST_STAT_* constants)
  • src (flist): Source list
• Returns: float — statistics over a list

slist list_slice(slist src, int start, int end, int stride, int slice_index)

Extracts a slice from a list in stride units.

• Parameters:
  • src (slist): List to slice
  • start (int): Start index of the extraction
  • end (int): End index of the extraction
  • stride (int): Stride (size of each element group)
  • slice_index (int): Index of the element to extract within each stride
• Returns: slist — a list of the extracted elements

slist list_strided(slist src, int start, int end, int stride)

Returns a sub-list of a list in stride units.

• Parameters:
  • src (slist): List to extract the sub-list from
  • start (int): Start index of the extraction
  • end (int): End index of the extraction
  • stride (int): Stride (size of each element group)
• Returns: slist — the sub-list extracted by stride

int list_find_next(slist src, slist test, int instance)

Finds the position of the specified instance of a match in a list.

• Parameters:
  • src (slist): List to search
  • test (slist): List to search for
  • instance (int): Instance number of the match to return (0-based, -1 for the last)
• Returns: int — the start index of the match (-1 if not found)

int list_find_strided(slist src, slist test, int start, int end, int stride)

Finds the position of a match in a list at stride boundaries.

• Parameters:
  • src (slist): List to search
  • test (slist): List to search for
  • start (int): Start index of the search
  • end (int): End index of the search
  • stride (int): Stride (interval between boundaries where a match is allowed)
• Returns: int — the start index of the match (-1 if not found)

slist list_sort_strided(slist src, int stride, int stride_index, int ascending)

Sorts a list in stride units.

• Parameters:
  • src (slist): List to sort
  • stride (int): Stride (size of each element group)
  • stride_index (int): Index within the stride to use as the sort key
  • ascending (int): TRUE for ascending order, FALSE for descending order
• Returns: slist — the sorted list

Type conversion functions

int str_to_int(str text)

Converts a string to an integer.

• Parameters:
  • text (str): Target string
• Returns: int — a string to an integer

float str_to_float(str text)

Converts a string to a floating-point number.

• Parameters:
  • text (str): Target string
• Returns: float — a string to a floating-point number

str int_to_str(int value)

Converts an integer to a string.

• Parameters:
  • value (int): Target integer value
• Returns: str — an integer to a string

str float_to_str(float value)

Converts a floating-point number to a string.

• Parameters:
  • value (float): Target floating-point value
• Returns: str — a floating-point number to a string

Detection functions

Functions that retrieve detection information for use in sensor or touch events. The num argument specifies the detection index within the event (0-based).

int detected_face(int num)

Returns the touched face number.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: int — the touched face number

str detected_name(int num)

Returns the name of the detected avatar/object.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: str — the name of the detected avatar/object

key detected_key(int num)

Returns the key of the detected avatar/object.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: key — the key of the detected avatar/object

vec detected_pos(int num)

Returns the position of the detected avatar/object.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: vec — the position of the detected avatar/object

rot detected_rot(int num)

Returns the rotation of the detected avatar/object.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: rot — the rotation of the detected avatar/object

vec detected_vel(int num)

Returns the velocity of the detected avatar/object.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: vec — the velocity of the detected avatar/object

vec detected_grab(int num)

Returns the detected grab offset.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: vec — the detected grab offset

int detected_type(int num)

Returns the type of the detected avatar/object.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: int — the type of the detected avatar/object

key detected_group(int num)

Returns the group key of the detected avatar/object.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: key — the group key of the detected avatar/object

key detected_owner(int num)

Returns the owner key of the detected object.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: key — the owner key of the detected object

int detected_link_number(int num)

Returns the detected link number.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: int — the detected link number

vec detected_touch_st(int num)

Returns the touched texture coordinate (ST).

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: vec — the touched texture coordinate (ST)

vec detected_touch_uv(int num)

Returns the touched texture coordinate (UV).

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: vec — the touched texture coordinate (UV)

vec detected_touch_normal(int num)

Returns the normal of the touched face.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: vec — the normal of the touched face

vec detected_touch_binormal(int num)

Returns the binormal of the touched face.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: vec — the binormal of the touched face

vec detected_touch_pos(int num)

Returns the touched world coordinate.

• Parameters:
  • num (int): Detection index within the event (0-based)
• Returns: vec — the touched world coordinate

Prim property functions

key get_owner()

Returns the owner key of the prim.

• Parameters: none
• Returns: key — the owner key of the prim

key get_owner_key(key id)

Returns the owner key of the specified object.

• Parameters:
  • id (key): Target key (UUID)
• Returns: key — the owner key of the specified object

key get_key()

Returns the key of the prim.

• Parameters: none
• Returns: key — the key of the prim

str get_prim_name()

Returns the name of the prim.

• Parameters: none
• Returns: str — the name of the prim

int get_link_num()

Returns the link number of the prim containing the script.

• Parameters: none
• Returns: int — the link number of the prim containing the script

str link_name(int linknum)

Returns the link name corresponding to the link number.

• Parameters:
  • linknum (int): Link number (LINK_* constants also work)
• Returns: str — the link name corresponding to the link number

vec get_pos()

Returns the world position of the prim.

• Parameters: none
• Returns: vec — the world position of the prim

rot get_rot()

Returns the world rotation of the prim.

• Parameters: none
• Returns: rot — the world rotation of the prim

vec get_scale()

Returns the scale of the prim.

• Parameters: none
• Returns: vec — the scale of the prim

vec get_local_pos()

Returns the local position of the prim.

• Parameters: none
• Returns: vec — the local position of the prim

rot local_rot()

Returns the local rotation of the prim.

• Parameters: none
• Returns: rot — the local rotation of the prim

vec get_root_pos()

Returns the position of the root prim.

• Parameters: none
• Returns: vec — the position of the root prim

rot get_root_rot()

Returns the rotation of the root prim.

• Parameters: none
• Returns: rot — the rotation of the root prim

float get_alpha(int face)

Returns the alpha of the prim.

• Parameters:
  • face (int): Face number (-1 for all faces)
• Returns: float — the alpha of the prim

vec get_color(int face)

Returns the color of the prim.

• Parameters:
  • face (int): Face number (-1 for all faces)
• Returns: vec — the color of the prim

str get_texture(int face)

Returns the texture name.

• Parameters:
  • face (int): Face number (-1 for all faces)
• Returns: str — the texture name

str get_object_desc()

Returns the description of the object.

• Parameters: none
• Returns: str — the description of the object

key get_creator()

Returns the creator key of the object.

• Parameters: none
• Returns: key — the creator key of the object

int get_number_of_prims()

Returns the number of prims in the link set.

• Parameters: none
• Returns: int — the number of prims in the link set

int get_number_of_sides()

Returns the number of faces on the prim.

• Parameters: none
• Returns: int — the number of faces on the prim

key get_link_key(int linknum)

Returns the key for the given link number.

• Parameters:
  • linknum (int): Link number (LINK_* constants also work)
• Returns: key — the key for the given link number

int get_object_prim_count(key id)

Returns the number of prims in the object.

• Parameters:
  • id (key): Target key (UUID)
• Returns: int — the number of prims in the object

float get_mass()

Returns the mass of the prim.

• Parameters: none
• Returns: float — the mass of the prim

float get_object_mass(key id)

Returns the mass of the object.

• Parameters:
  • id (key): Target key (UUID)
• Returns: float — the mass of the object

slist get_link_prim_params(int linknum, ilist rules)

Returns the parameter list for a link prim.

• Parameters:
  • linknum (int): Link number (LINK_* constants also work)
  • rules (ilist): Rule list (sequence of prim parameter constants)
• Returns: slist — the parameter list for a link prim

slist get_object_details(key id, ilist params)

Returns detailed information about the object.

• Parameters:
  • id (key): Target key (UUID)
  • params (ilist): Parameter list
• Returns: slist — detailed information about the object

slist get_bounding_box(key object)

Returns the bounding box of an object.

• Parameters:
  • object (key): Key of the object to get the bounding box of
• Returns: slist — a list of two vectors: the minimum corner and the maximum corner

vec get_center_of_mass()

Returns the center of mass of the object.

• Parameters: none
• Returns: vec — the world coordinates of the center of mass of the object

vec get_geometric_center()

Returns the geometric center of the object.

• Parameters: none
• Returns: vec — the geometric center offset relative to the root prim

int get_link_number_of_sides(int link)

Returns the number of faces of a linked prim.

• Parameters:
  • link (int): Target link number or LINK constant
• Returns: int — the number of faces (sides) of the linked prim

float get_mass_mks()

Returns the mass of the object in MKS units (kg).

• Parameters: none
• Returns: float — the mass of the object (kg)

float get_max_scale_factor()

Returns the maximum factor by which the object can be enlarged.

• Parameters: none
• Returns: float — the maximum enlargement ratio

float get_min_scale_factor()

Returns the minimum factor by which the object can be shrunk.

• Parameters: none
• Returns: float — the minimum shrinking ratio

slist get_primitive_params(slist params)

Returns the list of prim parameters.

• Parameters:
  • params (slist): List of PRIM_* constant specifiers to get
• Returns: slist — a list of values for the requested PRIM_* parameters

int scale_by_factor(float scaling_factor)

Resizes the whole object by a factor.

• Parameters:
  • scaling_factor (float): Factor by which to scale the whole object
• Returns: int — a status indicating whether the resize succeeded (TRUE on success)

vec get_texture_offset(int face)

Returns the texture offset of a face.

• Parameters:
  • face (int): Target face number (ALL_SIDES for all faces)
• Returns: vec — the texture offset of the face (U/V vector)

float get_texture_rot(int face)

Returns the texture rotation of a face.

• Parameters:
  • face (int): Target face number (ALL_SIDES for all faces)
• Returns: float — the texture rotation angle of the face (radians)

vec get_texture_scale(int face)

Returns the texture scale of a face.

• Parameters:
  • face (int): Target face number (ALL_SIDES for all faces)
• Returns: vec — the texture scale of the face (U/V vector)

slist get_prim_media_params(int face, slist params)

Returns the media parameters of a face.

• Parameters:
  • face (int): Target face number
  • params (slist): List of PRIM_MEDIA_* constants to get
• Returns: slist — a list of values for the requested media parameters

int set_prim_media_params(int face, slist params)

Sets the media parameters of a face.

• Parameters:
  • face (int): Target face number
  • params (slist): Parameter list of PRIM_MEDIA_* constants and values
• Returns: int — a status indicating whether the setting succeeded (STATUS_OK, etc.)

int clear_prim_media(int face)

Clears the media of a face.

• Parameters:
  • face (int): Face number to clear the media of
• Returns: int — a status indicating whether the clearing succeeded (STATUS_OK, etc.)

slist get_link_media(int link, int face, slist params)

Returns the media parameters of a face of a linked prim.

• Parameters:
  • link (int): Target link number or LINK constant
  • face (int): Target face number
  • params (slist): List of PRIM_MEDIA_* constants to get
• Returns: slist — a list of values for the requested media parameters

int set_link_media(int link, int face, slist params)

Sets the media parameters of a face of a linked prim.

• Parameters:
  • link (int): Target link number or LINK constant
  • face (int): Target face number
  • params (slist): Parameter list of PRIM_MEDIA_* constants and values
• Returns: int — a status indicating whether the setting succeeded (STATUS_OK, etc.)

int clear_link_media(int link, int face)

Clears the media of a face of a linked prim.

• Parameters:
  • link (int): Target link number or LINK constant
  • face (int): Face number to clear the media of
• Returns: int — a status indicating whether the clearing succeeded (STATUS_OK, etc.)

Inventory functions

int get_inventory_type(str name)

Returns the type of the inventory item with the given name.

• Parameters:
  • name (str): Target name
• Returns: int — the type of the inventory item with the given name

int get_inventory_num(int type)

Returns the number of inventory items of the given type.

• Parameters:
  • type (int): Flag value specifying the kind
• Returns: int — the number of inventory items of the given type