Functions

All built-in functions available to Loreline scripts.

Each public method corresponds to a function that script authors can call directly. Use bindAll() to register every function into a name-to-function map so the interpreter can look them up.

Instance Members #

Registers all built-in functions into the given map, making them callable by name from Loreline scripts.

Rounds a number down to the nearest whole number.

floor(3.7) returns 3, floor(-1.2) returns -2.

val = floor(3.7)
You need $val gold coins to enter. // "You need 3 gold coins to enter."

Rounds a number up to the nearest whole number.

ceil(3.2) returns 4, ceil(-1.8) returns -1.

days = ceil(hours / 24)
The journey takes at least $days days.

Rounds a number to the nearest whole number.

round(3.5) returns 4, round(3.4) returns 3.

score = round(raw_score)
Your final score is $score.

Returns the positive version of a number, removing any negative sign.

abs(-5) returns 5, abs(3) returns 3.

diff = abs(your_score - target_score)
You were off by $diff points.

Returns the smaller of two values.

min(3, 7) returns 3.

damage = min(attack_power, enemy_health)

Returns the larger of two values.

max(3, 7) returns 7.

health = max(health - damage, 0)

Keeps a value within a given range. If the value is too low, returns the minimum; if too high, returns the maximum; otherwise returns it unchanged.

clamp(10, 0, 5) returns 5, clamp(3, 0, 5) returns 3.

health = clamp(health + healing, 0, max_health)

Raises a number to the given power.

pow(2, 3) returns 8 (2 x 2 x 2). pow(9, 0.5) returns 3 (square root).

area = pow(side_length, 2)
The room is $area square meters.

Returns a random whole number between min and max, including both ends.

roll = random(1, 6)
You rolled a $roll!

Returns true with a 1-in-n probability. Useful for occasional random events.

chance(3) has roughly a 33% chance of being true.

if chance(4)
  You find a rare gem on the ground!

Sets the random seed so that all future random results follow a predictable sequence. Calling seed_random with the same value always produces the same results for random, chance, random_float, array_pick, and array_shuffle.

seed_random(42)
// From here, the sequence of random values is always the same.

Returns a random decimal number from min up to (but not including) max.

random_float(0, 1) might return 0.7341....

temperature = round(random_float(15, 30))
It's $temperature degrees outside today.

Pauses the script for the given number of seconds before continuing.

The ground begins to shake...
wait(2)
A massive boulder crashes through the wall!

Converts a value to a number. Strings like "3.14" are parsed; true becomes 1, false becomes 0. Returns 0 if conversion fails.

price = float("9.99")

Converts any value to text.

label = string(42)   // "42"

Converts a value to true or false:

• Numbers: 0 is false, everything else is true
• Strings: empty "" is false, non-empty is true
• Arrays: empty is false, non-empty is true
• null: false

if bool(item_count)
  You are carrying items.

Returns the number of characters in a string.

name = "Alice"
Your name has $string_length(name) letters.

Converts all letters to uppercase.

string_upper("hello") returns "HELLO".

title = string_upper(player_name)
The crowd chants: $title! $title!

Converts all letters to lowercase.

string_lower("HELLO") returns "hello".

Checks if a string contains a given piece of text.

string_contains("hello world", "world") returns true.

if string_contains(message, "help")
  Someone needs assistance!

Replaces every occurrence of a piece of text with something else.

string_replace("hello world", "world", "there") returns "hello there".

censored = string_replace(message, "darn", "****")

Splits a string into an array of pieces at each occurrence of a separator.

string_split("a,b,c", ",") returns ["a", "b", "c"].

words = string_split(sentence, " ")
The sentence has $length(words) words.

Removes any spaces or whitespace from the beginning and end of a string.

string_trim(" hello ") returns "hello".

Finds where a piece of text first appears inside a string. Returns the position (starting from 0), or -1 if not found.

string_index("hello", "ll") returns 2.

pos = string_index(clue, "treasure")
if pos >= 0
  The clue mentions a treasure!

Extracts a portion of a string starting at position start (0-based) for length characters.

string_sub("ABCDEF", 0, 3) returns "ABC". string_sub("ABCDEF", 2, 3) returns "CDE".

code = "ABCDEF"
prefix = string_sub(code, 0, 3)
// prefix is "ABC"

Checks if a string begins with the given prefix.

string_starts("hello world", "hello") returns true.

if string_starts(name, "Sir")
  You bow before the knight.

Checks if a string ends with the given suffix.

string_ends("hello world", "world") returns true.

if string_ends(reply, "?")
  It sounds like a question.

Repeats the text the given number of times.

string_repeat("ab", 3) returns "ababab".

divider = string_repeat("-", 20)
// divider is "--------------------"

Returns singular when count is 1, plural_form otherwise. Useful for both noun plurals and verb conjugation. The writer provides both forms, so this works in any language.

items = 3
You found $items $plural(items, "coin", "coins").
// "You found 3 coins."

boxes = 1
There $plural(boxes, "is", "are") $boxes $plural(boxes, "box", "boxes") here.
// "There is 1 box here."

Returns the number of elements in an array.

items = [1, 2, 3]
You carry $array_length(items) items.

Adds an element to the end of an array.

items = ["sword", "shield"]
array_add(items, "potion")
// items is now ["sword", "shield", "potion"]

Removes the last element from an array and returns it. Returns null if the array is empty.

last = array_pop(items)
You drop the $last.

Adds an element to the beginning of an array.

queue = ["Bob", "Carol"]
array_prepend(queue, "Alice")
// queue is now ["Alice", "Bob", "Carol"]

Removes the first element from an array and returns it. Returns null if the array is empty.

next_in_line = array_shift(queue)
$next_in_line steps forward.

Finds and removes the first occurrence of a value from an array. Returns true if the value was found and removed, false if not found.

array_remove(inventory, "old key")
The old key crumbles to dust.

Finds the position of a value in an array (starting from 0). Returns -1 if the value is not in the array.

pos = array_index(suspects, "Butler")

Checks if an array contains a given value.

if array_has(inventory, "golden key")
  You unlock the ancient door.
else
  The door won't budge without the right key.

Sorts the array in place and returns it. Numbers are sorted from smallest to largest; other values are sorted alphabetically.

scores = [30, 10, 20]
array_sort(scores)
// scores is now [10, 20, 30]

Reverses the array in place and returns it.

steps = ["first", "second", "third"]
array_reverse(steps)
// steps is now ["third", "second", "first"]

Combines all elements of an array into a single string, placing a separator between each element.

array_join(["a", "b", "c"], ", ") returns "a, b, c".

guests = ["Alice", "Bob", "Carol"]
The guests are: $array_join(guests, ", ").

Returns a random element from an array. Returns null if the array is empty. Affected by seed_random.

greetings = ["Hello!", "Hey there!", "Welcome!"]
barista: $array_pick(greetings)

Shuffles the array in place and returns it. Affected by seed_random.

deck = ["Ace", "King", "Queen", "Jack"]
array_shuffle(deck)
You draw the $deck[0].

Returns a shallow copy of the array.

original = [1, 2, 3]
backup = array_copy(original)
array_sort(original)
// original is now [1, 2, 3] sorted, backup is unchanged

Returns the number of keys in a map.

state
  stats: { strength: 10, agility: 8 }
The map has $map_length(stats) entries.

Returns an array containing all the keys of a map.

state
  stats: { strength: 10, agility: 8 }
all_stats = map_keys(stats)
// all_stats is ["strength", "agility"]

Checks if a map contains a given key.

if map_has(inventory_counts, "potion")
  You have potions available.

Gets the value stored under a key in a map. Returns null if the key doesn't exist.

count = map_get(inventory_counts, "arrows")
You have $count arrows left.

Stores a value under a key in a map. Overwrites any previous value for that key.

map_set(inventory_counts, "arrows", 20)

Removes a key and its value from a map. Returns true if the key was found and removed, false otherwise.

map_remove(inventory_counts, "broken_sword")
You discard the broken sword.

Returns a shallow copy of a map.

state
  stats: { strength: 10, agility: 8 }
backup = map_copy(stats)
map_set(stats, "strength", 20)
// stats.strength is 20, backup.strength is still 10

Returns the name of the beat that is currently running.

beat TavernScene
  where = current_beat()
  // where is "TavernScene"

Checks whether a beat with the given name exists and can be reached from where you are. This includes nested beats defined inside the current beat or any of its parent beats, as well as all top-level beats.

if has_beat("SecretEnding")
  choice
    Try the secret path -> SecretEnding

Returns how many times a beat has been entered.

beat_visits() returns the visit count of the current beat. beat_visits("BeatName") or beat_visits(BeatName) returns the visit count of the named beat. BeatName.visits() is also supported via dot notation.

if beat_visits() == 1
  First time here
else
  You've been here before

if beat_visits(Dungeon) >= 3
  You know this place well now

Returns an array of text strings for all enabled choice options evaluated so far (during option condition evaluation) or all enabled options (inside the chosen option's body).

Returns a new array each time (safe to modify in scripts). Returns an empty array outside of a choice context.

choice
  - Ask about menu
  - Ask about specials
  Say something if !choices()

Returns an array of text strings for all disabled choice options evaluated so far (during option condition evaluation) or all disabled options (inside the chosen option's body).

Returns a new array each time (safe to modify in scripts). Returns an empty array outside of a choice context.

choice
  Option A if someCondition
  Option B if array_length(choices_disabled()) > 0

Returns an array of text strings for all choice options evaluated so far, in original order, regardless of enabled/disabled state.

Returns a new array each time (safe to modify in scripts). Returns an empty array outside of a choice context.

choice
  Option A
  Option B if array_length(choices_all()) > 0

Private Members #

Metadata #