LSL standard library: core modules
lux, math, bigint, json, lconf, env, time and random. All are bundled with
LSL 0.10.2 (load NAME). lsl man NAME shows the offline manual of a module.
lux
Core module with small helpers.
| Export | Description |
|---|---|
lux.version |
version String of the module |
lux.name |
language name, "Lux Simple Lang" |
lux.identity(value) |
returns the value unchanged |
lux.clamp(value, low, high) |
clamp into <low, high> |
lux.is_empty(collection) |
True if the collection is empty |
Note (0.10.2): the reference also lists lux.l(value) (alias of type), but the shipped
lux.lsl does not define it – use type(value). The shipped lux.version still says "0.7.8";
use lsl version for the real compiler version.
math
Mathematical constants and numeric functions in pure LSL. Errors: MathError (domain errors,
invalid arguments), ValueError, OverflowError (gcd/lcm).
| Export | Description |
|---|---|
math.PI, math.TAU, math.E |
Float64 constants |
math.pi(decimal_places) |
π as a decimal String with the requested number of places |
math.floor(x), math.ceil(x) |
Int; NaN/Infinity/out of Int range raise ValueError |
math.round(x, digits=None) |
half away from zero; without digits returns Int, with digits Float (negative digits round to tens, hundreds...) |
math.trunc(x, digits=None) |
toward zero |
math.sign(x), math.clamp(x, lower, upper), math.lerp(start, stop, amount) |
sign, clamp, linear interpolation |
math.degrees(r), math.radians(d) |
angle conversion |
math.gcd(a, b), math.lcm(a, b) |
greatest common divisor / least common multiple |
math.factorial(n) |
factorial in Int64 |
math.factorial_big(n) |
factorial as bigint.BigInt |
math.exp(x), math.log(x), math.log2(x), math.log10(x) |
exponential and logarithms |
math.sin(x), math.cos(x), math.tan(x) |
trigonometry in radians |
math.hypot(x, y) |
hypotenuse without overflow |
math.sigmoid(x), math.tanh(x), math.relu(x), math.softplus(x), math.swish(x) |
activation functions |
math.is_close(a, b, relative_tolerance, absolute_tolerance) |
approximate equality |
math.mean(values), math.median(values) |
mean and median |
math.variance(values), math.standard_deviation(values) |
population variance and standard deviation |
math.round(2.675, 2) is 2.68: digits are counted from the decimal text of the value as
printed by String(x).
load math
print math.gcd(48, 36) # 12
print math.sigmoid(0) # 0.5
print math.mean([1, 2, 3, 4]) # 2.5
print math.pi(5) # 3.14159
print math.round(2.675, 2) # 2.68
bigint
Arbitrary-precision integers, a separate type so that normal Int64 keeps native speed.
load bigint
number = bigint.BigInt("123456789012345678901234567890")
print number.power(2).text()
BigInt (and the compatible alias SuperInt) methods: text, add, subtract, multiply,
floor_divide, divide, modulo, power, compare, equals, negate, absolute,
is_zero and checked to_int. power(exponent) uses exponentiation by squaring and returns
a new BigInt; the exponent must be a non-negative Int (x.power(0) is 1, also 0.power(0)),
negative raises ValueError.
json
| Function | Description |
|---|---|
json.encode(value) |
serialize to a compact JSON String |
json.decode(text) |
parse JSON into LSL values (null → None); 4 MiB input limit; errors raise JsonError |
json.pretty(value) |
like encode (currently compact plus a newline) |
load json
data = json.decode("{\"name\": \"Ada\", \"values\": [1, 2, 3]}")
print data["name"], json.encode({"ok": True, "items": [1, None]})
# Ada {"ok":true,"items":[1,null]}
lconf
Codec for the dependency manifest config.lconf (used for .lux package archives).
| Function | Description |
|---|---|
lconf.decode(text) |
parse manifest text, return {apt, lux, lsl} Lists |
lconf.encode(manifest) |
serialize back to text (one kind: name line per entry) |
lconf.parse(text, path) |
like decode, path is used in error messages |
load lconf
deps = lconf.decode("apt: curl, git\nlux: myapp\nlsl: textkit\n")
# {'apt': ['curl', 'git'], 'lux': ['myapp'], 'lsl': ['textkit']}
env
load env reads process environment variables and (since 0.8.9) automatically loads a .env
file at run time – values are never compiled into the binary.
lsl program.lsl:.envnext to the script (even when started from another directory).- A program built with
lsl compile:.envnext to the executable. - Interactive mode / stdin source:
.envin the working directory.
A missing .env is fine; an unreadable or invalid one raises an error. Parent directories are
not searched. Exported process variables win, even when empty. Values from .env live only
inside the env module and are not exported to child processes. env is not available in pure
lsl config mode.
| Function | Description |
|---|---|
env.get(name, default=None) |
process variable, else .env value, else default (None since 0.10.2 when omitted) |
env.has(name) |
True if the variable exists |
env.require(name) |
value, or raise an error when missing |
env.load_dotenv(path=None) |
explicitly load another file, or reload the default |
.env format: NAME=value, optional export, # comments (at line start or after
whitespace), "double quotes" with \n \r \t \" \\ escapes, 'single quotes' literal, LF or
CRLF, UTF-8, last occurrence wins, max 1 MiB, no multi-line values, no shell expansion. Errors
report path and line number, never the content.
load env
token = env.require("LUX_AI_API")
debug = env.get("DEBUG", "false") == "true"
time
| Function | Description |
|---|---|
time.time() / time.now() |
Unix timestamp (Float seconds, wall clock) |
time.monotonic() / time.perf_counter() |
monotonic seconds for intervals, timeouts, benchmarks |
time.sleep(seconds) |
sleep (Float seconds, clock_nanosleep) |
time.utc(seconds=None) |
Dictionary year, month, day, hour, minute, second, microsecond, weekday (Monday = 0), yearday |
time.iso8601(seconds=None, digits=6) |
ISO-8601 UTC timestamp, e.g. 2026-10-09T04:01:53.833305+00:00 (fraction truncated) |
time.strftime(format, seconds=None) |
UTC formatting: %Y %y %m %d %e %H %I %p %M %S %f %j %a %A %b %B %u %w %F %T %s %z %Z %% (unknown directive: ValueError) |
time.parse_iso8601(text) |
YYYY-MM-DDTHH:MM:SS[.frac] with Z or ±HH:MM (space allowed instead of T) → Unix time |
Supported years 1–9999. No local time zones or DST – store times in UTC. Measure intervals with
monotonic/perf_counter, never with wall-clock time or clock().
load time
start = time.monotonic()
call time.sleep(0.1)
print time.monotonic() - start # ~0.1
print time.strftime("%d. %m. %Y %H:%M")
random
Python-style random numbers (bundled since 0.7.8), pure LSL MT19937 with SHA-512 seeding.
Module functions share one generator; random.Random(seed) has its own state;
random.SystemRandom() uses Linux getrandom (ignores seed, rejects getstate/setstate).
MT19937 is not cryptographically secure – for tokens or keys use
random.SystemRandom().randbytes(n).
| Function / method | Description |
|---|---|
seed(a=None, version=2) |
seed from Int, Bool, Float, String, ByteArray or BigInt; None uses OS entropy |
random() |
Float in [0, 1) with 53 random bits |
getstate() / setstate(state) |
snapshot / restore the generator |
getrandbits(k) |
0–63 bits → Int, 64–4096 bits → BigInt |
randbytes(n) |
new ByteArray of n bytes |
randrange(start, stop=None, step=1) |
element of a half-open range (negative step allowed) |
randint(a, b) |
integer including both bounds |
choice(seq) |
one element of a non-empty sequence |
choices(population, weights=None, cum_weights=None, k=1) |
k picks with replacement |
sample(population, k, counts=None) |
picks without replacement |
shuffle(x) |
shuffle a mutable sequence in place, returns None |
uniform, triangular, normalvariate, gauss, lognormvariate, expovariate, gammavariate, betavariate, vonmisesvariate, paretovariate, weibullvariate, binomialvariate |
distributions |
Sequences: List, Tuple, String and typed arrays (a Dictionary is not a sequence – use
keys()/values()/items()). Errors are catchable; last_error() contains RandomError and
the cause. Limits: 1 MiB of seed bytes, 4096 bits per getrandbits/range, 1,048,576 bytes per
randbytes and per k/n.
load random
call random.seed(42)
print random.randint(1, 6)
rng = random.Random("my experiment")
data = [rng.normalvariate(mu=0, sigma=1) for i in rang(20)]
call rng.shuffle(data)
print rng.sample(data, 3)