Rez Standard Library
Matt Mower
- Introduction
- JavaScript Type Extensions
- Boolean
- Object
- Array
- String
- Set
- Number
- Math
- Math.perc(p)
- Math.div(n, d)
- Math.div_mod(n, d)
- Math.range(from, to, step)
- Math.dist_round(v)
- Math.rand_int(lim)
- Math.rand_int_between(min, max)
- Math.rand_f_between(min, max)
- Math.cl_rand_f_between(min, max, rounds)
- Math.cl_rand_int(lim)
- Math.cl_rand_int_between(lo, hi)
- Math.clamped_sub(value, sub, min)
- Math.clamped_add(value, add, max)
- Math.alter(value, change, min, max)
- Template Filters
- Components
- Built-in Scenes and Cards
Introduction
The Rez Standard Library automatically extends JavaScript’s built-in types with additional methods and provides template filters, components, and built-in game elements. This documentation covers all the extensions and utilities available in every Rez game.
The standard library includes:
-
JavaScript Type Extensions: Additional methods for Boolean, Object, Array, String, Set, Number, and Math
-
Template Filters: Functions for transforming values in template expressions
-
Components: Reusable template elements for common UI patterns
-
Built-in Game Elements: Pre-defined scenes and cards for common functionality
JavaScript Type Extensions
Boolean
Boolean.rand()
Returns true
|false
with an equal probability.
> Array.nOf(50, Boolean.rand) > [true, true, true, false, false, true, false, false, false, true, true, true, false, true, false, true, > true, true, false, false, true, true, true, false, true, true, false, true, false, false, true, false, > true, true, false, true, true, true, true, true, true, false, true, false, true, true, false, true, > false, false]
Object
copy()
Returns a deep-copy of the given object.
> const a = {a: 1, b: 2, c: 'frog', d: false}; > const b = a.copy(); > a["a"] = 0; > `${a["a"]},${b["a"]}` > '0,1'
objMap(f)
where f(v, k)`
Returns a new object containing the same keys as this object where the values are the values of this object passed through f
.
> ({a: 1, b: 2, c: 4}).objMap((v) => 2*v) > {a: 2, b: 4, c: 8} > ({a: 1, b: 2, c: 3, d: 4, e: 5}).objMap((v, k) => ["a", "e", "i", "o", "u"].includes(k) ? v * 2 : v) > {a: 2, b: 2, c: 3, d: 4, e: 10}
Array
Array.equals(l1, l2)
Returns true if l1
and l2
are both arrays of the same length and have the same value at each index.
> Array.equals([1, 2, 3], [1, 2, 3]) > true > Array.equals([3, 2, 1], [1, 2, 3]) > false
Array.nOf(number, value)
Returns a new array containing number
elements of value
. If value
is a function the array will contain the results of calling the function.
> Array.nOf(10, "a") > ['a', 'a', 'a', 'a', 'a', 'a', 'a', 'a', 'a', 'a'] > > Array.nOf(10, Math.random) > [0.834213541355117, 0.9961046067554495, 0.3864732125663226, 0.2319465459145894, 0.8445399411663749, > 0.875849725396377, 0.7146237562228359, 0.3918156859145241, 0.503402748321524, 0.7664109620436144]
Array.zip(arr1, arr2)
The zip method creates pairs of elements from two arrays based on their position. The resulting array will have the same length as the first array (array1). If the second array is shorter, undefined values will be paired with the remaining elements from the first array. If the second array is longer, the extra elements are ignored.
> names = ['Alice', 'Bob', 'Charlie']; > ages = [25, 30, 35]; > Array.zip(names, ages); > [['Alice', 25], ['Bob', 30], ['Charlie', 35]]
max()
Returns the maximum value of the elements of this array.
> [23, 16, 88, 45, 39, 42, 51].max() > 88
min()
Returns the minimum value of the elements of this array.
> [23, 16, 88, 45, 39, 42, 51].min() > 16
englishList()
Returns a string formatted list of the array that makes sense for 1, 2, or many items.
> [].englishList() > '' > [1].englishList() > '1' > [1, 2].englishList() > '1 and 2' > [1, 2, 3].englishList() > '1, 2, and 3' > ["a", "b", "c", "d", "e"].englishList() > 'a, b, c, d, and e'
remove(elem)
Modifies this array to remove the specified element.
> ["a", "b", "c", "d", "e"].remove("c") > ['a', 'b', 'd', 'e']
fyShuffle()
Randomizes the elements of this array using the Fisher-Yates Shuffle.
> ["a", "b", "c", "d", "e", "f", "g"].fyShuffle() > ['b', 'e', 'a', 'g', 'f', 'c', 'd']
randomElement()
Returns a randomly selected element of this array.
> ["a", "b", "c", "d"].randomElement() > 'c'
randomIndex()
Returns the index position of a randomly selected element of this array.
> ["a", "b", "c", "d"].randomIndex() > 0
frequencies()
Returns a map containing the elements of this array as keys and the number of times that element appears in the array as value.
> [1, 1, 2, 2, 2, 3, 4, 4, 5, 5, 5, 5].frequencies() > {1: 2, 2: 3, 3: 1, 4: 2, 5: 4} > ['t','h','e',' ','q','u','i','c','k',' ','b','r','o','w','n',' ','f','o','x',' ','j','u','m','p','e','d',' ','o','v','e','r',' ','t','h','e',' ','l','a','z','y',' ','d','o','g'].frequencies() > {"t" => 2, "h" => 2, "e" => 4, " " => 8, "q" => 1, "u" => 2, "i" => 1, > "c" => 1, "k" => 1, "b" => 1, "r" => 2, "o" => 4, "w" => 1, "n" => 1, > "f" => 1, "x" => 1, "j" => 1, "m" => 1, "p" => 1, "d" => 2, "v" => 1, > "l" => 1, "a" => 1, "z" => 1, "y" => 1, "g" => 1}
sum()
Returns the sum of the numeric elements of this array.
> [1, 2, 3, 4, 5].sum() > 15
startsWithSequence(lst)
Returns true if this array starts with the elements contained in the lst
parameter.
> [1, 2, 3, 4].startsWithSequence([1, 2]) > true > [2, 3, 4, 5].startsWithSequence([1, 2]) > false
take(n)
Removes the first n
elements of this array, returning them in a new array.
> const a = [1, 2, 3, 4, 5]; > const b = a.take(2); > a > [3, 4, 5] > b > [1, 2]
refs()
Given an array of Rez element ids, return a new array containing the objects with those ids.
> ["game", "player"].refs() > [RezGame, RezActor]
ids()
Given an array of Rez element objects, return a new array containing the ids of those elements.
> [$("game"), $("player")].ids() > ['game', 'player']
sample(p)
Returns an array containing a sample of the elements of this array. The size of the sample will be
approximately p%
of the size of this array.
> Array.nOf(100, (e, i) => i).sample(10) > [32, 8, 24, 43, 34, 58, 5, 51, 78, 88] > (3).times(() => console.log(Array.from({length: 26}, (_, i) => String.fromCharCode(97 + i)).sample(25))) > ['u', 'm', 'n', 'k', 'y', 'e', 'c'] > ['v', 's', 'f', 'e', 'w', 'l', 'j'] > ['v', 'i', 'b', 'g', 'c', 'f', 'n']
splitWith(pred)
Returns a new array containing two sub-arrays formed of the elements of this array. The first sub-array
contains all the elements for which pred(e)
returns true
and the second sub-array those which
return false
.
> [1,2,3,4,5,5,6,7,8,8].splitWith((f) => f % 2 == 0) > [[2,4,6,8,8],[1,3,5,5,7]]
to_pairs()
Converts this array into pairs by grouping every two consecutive elements.
> [1, 2, 3, 4, 5, 6].to_pairs() > [[1, 2], [3, 4], [5, 6]] > ["name", "Alice", "age", 25, "city", "London"].to_pairs() > [["name", "Alice"], ["age", 25], ["city", "London"]]
String
beginsWithConsonant()
Returns true
if this string begins with a consonant letter.
> "fox".beginsWithConsonant() > true > "apple".beginsWithConsonant() > false
beginsWithVowel()
Returns true
if this string begins with a vowel letter.
> "apple".beginsWithVowel() > true > "fox".beginsWithVowel() > false
toTitleCase()
Returns a new string with the first letter of each word capitalized.
> "the quick brown fox".toTitleCase() > 'The Quick Brown Fox'
possessive()
Returns a possessive form of this string by adding 's or just ' as appropriate.
> "fox".possessive() > "fox's" > "foxes".possessive() > "foxes'"
toCamelCase()
Converts this string from snake_case or kebab-case to camelCase.
> "snake_case_string".toCamelCase() > 'snakeCaseString' > "kebab-case-string".toCamelCase() > 'kebabCaseString'
toPascalCase()
Converts this string from snake_case or kebab-case to PascalCase (like camelCase but with first letter capitalized).
> "snake_case_string".toPascalCase() > 'SnakeCaseString' > "kebab-case-string".toPascalCase() > 'KebabCaseString'
toKebabCase()
Converts this string from any case (camelCase, PascalCase, snake_case) to kebab-case.
> "camelCaseString".toKebabCase() > 'camel-case-string' > "PascalCaseString".toKebabCase() > 'pascal-case-string' > "snake_case_string".toKebabCase() > 'snake-case-string'
toSnakeCase()
Converts this string from camelCase or PascalCase to snake_case.
> "camelCaseString".toSnakeCase() > 'camel_case_string' > "PascalCaseString".toSnakeCase() > 'pascal_case_string'
parseTime()
Parses a time string and returns an array of [hour, minutes].
> "10:30".parseTime() > [10, 30] > "2:15p".parseTime() > [2, 15]
String.randomId()
Static method that generates a random hexadecimal ID string.
> String.randomId() > 'a3f7b2c1'
dqWrap()
Returns this string wrapped in double quotes.
> "hello".dqWrap() > '"hello"'
Note: This method was listed under Object but applies to strings.
wrapWith(prefix, suffix)
Returns a string formed of the current strip wrapped with a prefix and a suffix.
> "bar".wrapWith("*") > '*bar*' > "bar".wrapWith("[", "]") > '[bar]'
indefiniteArticle()
Returns the appropriate indefinite article ("a" or "an") for the this string.
> "fox".indefiniteArticle() > 'a' > "object".indefiniteArticle() > 'an'
Set
union(otherSet)
Returns a new Set
containing the elements of this set and the otherSet
.
> a = new Set(["a", "b", "c", "d"]) > b = new Set(["c", "d", "e", "f"]) > a.union(b) > Set("a", "b", "c", "d", "e", "f")
intersection(otherSet)
Returns a new Set
containing the elements of this set that also exist in the otherSet
.
> a = new Set(["a", "b", "c", "d"]) > b = new Set(["c", "d", "e", "f"]) > a.intersection(b) > Set("c", "d")
difference(otherSet)
Returns a new Set
containing the elements of this set that do not exist in the otherSet
.
> a = new Set(["a", "b", "c", "d"]) > b = new Set(["c", "d", "e", "f"]) > a.difference(b) > Set("a", "b") > b.difference(a) > Set("e", "f")
equals(otherSet)
Return true
iff this Set
has the same elements as the otherSet
.
> a = new Set(["a", "b", "c"]) > b = new Set(["b", "c", "d"]) > c = new Set(["a", "b", "c"]) > a.equals(b) > false > a.equals(c) > true
hasSubset(otherSet)
Returns true
iff this Set
has every element of the otherSet
.
> a = new Set(["a", "b", "c", "d"]) > b = new Set(["b", "c"]) > c = new Set(["d", "e"]) > a.hasSubset(b) > true > a.hasSubset(c) > false
Number
ordinal()
Returns this number as an ordinal string (1st, 2nd, 3rd, 4th, etc.).
> (1).ordinal() > '1st' > (2).ordinal() > '2nd' > (3).ordinal() > '3rd' > (4).ordinal() > '4th' > (21).ordinal() > '21st'
roundp(precision)
Rounds this number to the specified number of decimal places.
> (3.14159).roundp(2) > 3.14 > (123.456).roundp(1) > 123.5
cl_avg(rounds)
Returns a central limit approximation by averaging rounds
random selections (defaults to 2). Creates a more bell-curve distribution than straight random.
> (6).cl_avg(2) // Roll 2 six-sided dice and average > 3 > (6).cl_avg(3) // Roll 3 six-sided dice and average > 4
r2nh()
Rounds this number to the nearest half (0.5).
> (3.3).r2nh() > 3.5 > (3.7).r2nh() > 4.0 > (3.25).r2nh() > 3.0
dist_round()
Randomly rounds this number up or down to avoid bias in repeated rounding operations.
> (3.5).dist_round() > 3 // or 4, randomly chosen
round_to_nearest(n)
Rounds this number to the nearest multiple of n
.
> (17).round_to_nearest(5) > 15 > (18).round_to_nearest(5) > 20
times(f)
Executes function f
this many times, passing the current iteration index (starting from 0).
> (3).times((i) => console.log(`Iteration ${i}`)) > Iteration 0 > Iteration 1 > Iteration 2
Math
Math.perc(p)
Returns true
if a random number is less than or equal to the percentage p
(0-100).
> Math.perc(75) // 75% chance of returning true > true > Math.perc(25) // 25% chance of returning true > false
Math.div(n, d)
Returns the integer division of n
divided by d
(equivalent to Math.floor(n/d)
).
> Math.div(17, 5) > 3 > Math.div(20, 6) > 3
Math.div_mod(n, d)
Returns both the integer division and remainder as an array [div, mod]
.
> Math.div_mod(17, 5) > [3, 2] > Math.div_mod(20, 6) > [3, 2]
Math.range(from, to, step)
Creates an array of numbers from from
to to
(inclusive) with optional step
(defaults to 1).
> Math.range(1, 5) > [1, 2, 3, 4, 5] > Math.range(0, 10, 2) > [0, 2, 4, 6, 8, 10] > Math.range(5, 1) // Arguments are swapped if from > to > [1, 2, 3, 4, 5]
Math.dist_round(v)
Randomly rounds v
up or down to avoid bias. Same as Number.dist_round()
but as a static method.
> Math.dist_round(3.5) > 3 // or 4, randomly chosen
Math.rand_int(lim)
Returns a random integer from 0 to lim-1
.
> Math.rand_int(6) // Simulates a die roll (0-5) > 3 > Math.rand_int(10) > 7
Math.rand_int_between(min, max)
Returns a random integer between min
and max
(inclusive).
> Math.rand_int_between(1, 6) // Simulates a die roll (1-6) > 4 > Math.rand_int_between(10, 20) > 15
Math.rand_f_between(min, max)
Returns a random floating-point number between min
and max
.
> Math.rand_f_between(1.0, 2.0) > 1.7384521 > Math.rand_f_between(0, 100) > 42.8391
Math.cl_rand_f_between(min, max, rounds)
Returns a random floating-point number between min
and max
using central limit approximation (averages rounds
random values, defaults to 2).
> Math.cl_rand_f_between(0, 10, 2) > 5.2 // More likely to be near the center
Math.cl_rand_int(lim)
Returns a random integer from 0 to lim-1
using central limit approximation (averages 2 random values).
> Math.cl_rand_int(6) > 2 // More likely to be 2 or 3 than 0 or 5
Math.cl_rand_int_between(lo, hi)
Returns a random integer between lo
and hi
using central limit approximation.
> Math.cl_rand_int_between(1, 6) > 3 // More likely to be 3 or 4 than 1 or 6
Math.clamped_sub(value, sub, min)
Subtracts sub
from value
but doesn’t go below min
.
> Math.clamped_sub(10, 3, 5) > 7 > Math.clamped_sub(10, 8, 5) > 5 // Would be 2, but clamped to minimum of 5
Math.clamped_add(value, add, max)
Adds add
to value
but doesn’t go above max
.
> Math.clamped_add(10, 3, 15) > 13 > Math.clamped_add(10, 8, 15) > 15 // Would be 18, but clamped to maximum of 15
Math.alter(value, change, min, max)
Applies change
to value
but keeps the result between min
and max
.
> Math.alter(10, 5, 0, 20) > 15 > Math.alter(10, -15, 0, 20) > 0 // Would be -5, but clamped to minimum of 0 > Math.alter(10, 15, 0, 20) > 20 // Would be 25, but clamped to maximum of 20
Template Filters
Template filters are used in template expressions to transform values. They use the pipe syntax: ${value | filter_name}
or ${value | filter_name: argument}
.
Comparison Filters
eq
Tests if two values are equal.
${player.level | eq: 5} // true if player.level == 5
ne
Tests if two values are not equal.
${player.health | ne: 0} // true if player.health != 0
gt, gte, lt, lte
Numeric comparison filters (greater than, greater than or equal, less than, less than or equal).
${player.score | gt: 1000} // true if score > 1000 ${player.level | gte: 10} // true if level >= 10 ${enemy.health | lt: 50} // true if health < 50 ${player.mana | lte: 25} // true if mana <= 25
Selection Filters
bsel
Boolean selection - returns the first array element if true, second if false.
${player.alive | bsel: ["alive", "dead"]} // Returns "alive" if player.alive is true, "dead" if false
sel
Index selection - returns the array element at the given index.
${difficulty_level | sel: ["Easy", "Medium", "Hard", "Expert"]} // Returns the difficulty name based on difficulty_level index
Arithmetic Filters
add, sub, mul, div, mod
Basic arithmetic operations.
${player.score | add: 100} // Add 100 to score ${enemy.health | sub: damage} // Subtract damage from health ${base_cost | mul: 2} // Multiply cost by 2 ${total_points | div: 4} // Divide points by 4 ${turn_number | mod: 10} // Get remainder when divided by 10
abs, neg, inc, dec
Other numeric operations.
${velocity | abs} // Absolute value ${profit | neg} // Negate value ${counter | inc} // Add 1 ${lives | dec} // Subtract 1
round
Round to specified decimal places.
${pi | round: 2} // 3.14 ${percentage | round: 0} // Round to whole number
ordinal
Convert number to ordinal string.
${place | ordinal} // "1st", "2nd", "3rd", etc.
String Filters
string
Convert any value to a string.
${player.level | string} // Convert number to string
append, prepend
Add text to beginning or end of string.
${player.name | append: " the Great"} // "Arthur the Great" ${item.name | prepend: "Golden "} // "Golden Sword"
trim, capitalize, upcase, downcase
Text formatting.
${input | trim} // Remove whitespace ${title | capitalize} // Capitalize Each Word ${shout | upcase} // CONVERT TO UPPERCASE ${whisper | downcase} // convert to lowercase
to_camel_case
Convert to camelCase.
${attribute_name | to_camel_case} // "attributeName"
to_title_case
Convert to Title Case (capitalize each word).
${title | to_title_case} // "The Quick Brown Fox"
pluralize
Convert to plural form.
${item_type | pluralize} // "sword" -> "swords"
possessive
Add possessive form.
${player.name | possessive} // "Arthur's"
split
Split string into array.
${tags | split: ","} // Split comma-separated values
starts_with, ends_with, contains
String testing.
${filename | starts_with: "temp"} // true/false ${filename | ends_with: ".txt"} // true/false ${text | contains: "magic"} // true/false
quoted, dquoted
Wrap in quotes.
${message | quoted} // 'Hello World' ${message | dquoted} // "Hello World"
i_article
Add indefinite article.
${item.name | i_article} // "an apple", "a sword"
char_at
Get character at index.
${word | char_at: 0} // First character
Array Filters
length
Get array length.
${items | length} // Number of items
take
Take first n elements.
${high_scores | take: 10} // Top 10 scores
Rendering Filters
render
Render a template attribute.
${card | render: "description": $block} // Renders the description attribute of card as a template
event
Create an event link (deprecated - use link syntax instead).
${"Click Here" | event: "button_clicked"} // Creates: <a href='javascript:void(0);' class='event' data-event='button_clicked'>Click Here</a>
dyn_link
Create a dynamic link (deprecated - use components instead).
${card | dyn_link: "can_use"} // Creates a link based on the card's can_use handler
Components
Components are reusable template elements that can be used in card content and scene layouts.
embed_card
Embeds one card within another.
<.embed_card card="sidebar_info"> </.embed_card> // or <.embed_card card="#sidebar_info"> </.embed_card>
The component accepts:
- card
: Either a string ID or a card object reference
img
Displays an image asset with proper sizing and attributes.
<.img name="player_portrait" width="100" height="150" class="character-image"> </.img>
The component accepts:
- name
: Asset ID (required)
- width
, height
: Dimensions (optional, uses asset dimensions if not provided)
- Any other HTML attributes (class, alt, etc.)
Built-in Scenes and Cards
$load_game Scene
A built-in scene that provides game loading functionality.
-
Scene ID:
$load_game
-
Initial Card:
$load_game_form
-
Purpose: Handles file-based game loading
$load_game_form Card
A built-in card that provides a file upload form for loading saved games.
-
Card ID:
$load_game_form
-
Content: File input form with submit button
-
Event Handler:
on_load_form
- processes the uploaded save file