Craft

Expression functions

Each entry below comes from the function tables that run expressions, so the names and argument counts are exactly what an expression accepts. Functions are called by name, floor(x). Methods are called on a list or on text, $self.tags.join(", "). There are no others: anything not listed is refused when the schema is saved.

Lists and text also have .length, read like a field: $self.inventory.length, $self.name.length.

A method called on null gives null. Functions passed to methods are written in place, e => e.weight; see the expression language.

Numbers

floor()

Rounds a number down to a whole number. Anything that isn't a number gives null.

Arguments: 1.

floor(($self.dexterity - 10) / 2)

ceil()

Rounds a number up to a whole number. Anything that isn't a number gives null.

Arguments: 1.

ceil($self.level / 2)

round()

Rounds a number to the nearest whole number; a half rounds up. Anything that isn't a number gives null.

Arguments: 1.

round($self.gold * 1.1)

abs()

A number without its sign: abs(-3) is 3. Anything that isn't a number gives null.

Arguments: 1.

abs($self.alignmentScore)

sqrt()

The square root of a number. A negative number, or anything that isn't a number, gives null.

Arguments: 1.

sqrt($self.area)

pow()

A number raised to a power, the same as **: pow(2, 3) is 8. A result that isn't a finite number gives null.

Arguments: 2.

pow(2, $self.tier)

min()

The smallest of its numbers, given one by one or as one list. Nulls and anything that isn't a number are skipped; with nothing left it gives null.

Arguments: 1 or more.

min($self.strength, $self.dexterity)
min($self.party.map(p => load(p)?.level ?? 1))

max()

The largest of its numbers, given one by one or as one list. Nulls and anything that isn't a number are skipped; with nothing left it gives null.

Arguments: 1 or more.

max($self.activeEffects.map(e => load(e)?.bonus ?? 0))

clamp()

Keeps a number between a low and a high bound: clamp(n, low, high). If any of the three is null, it gives null.

Arguments: 3.

clamp($self.hp ?? 0, 0, $self.maxHp ?? 0)

Totals over a list

sum()

Adds up a list's numbers, or with a function, what the function gives for each item. Nulls and anything that isn't a number count as 0. A value that isn't a list gives null.

Arguments: 1 to 2; the 2nd is a function (x => …) with up to 2 parameters.

sum($self.inventory, e => (load(e.item)?.weight ?? 0) * (e.quantity ?? 1))

avg()

The average of a list's numbers, or with a function, of what it gives for each item. Nulls and anything that isn't a number are skipped; with nothing left, or a value that isn't a list, it gives null.

Arguments: 1 to 2; the 2nd is a function (x => …) with up to 2 parameters.

avg($self.ratings)

count()

How many items of a list aren't null, or with a function, how many items it says yes to. A value that isn't a list gives null.

Arguments: 1 to 2; the 2nd is a function (x => …) with up to 2 parameters.

count($self.quests, q => q.done)

Converting values

number()

Turns a value into a number: a number stays as it is, true is 1 and false is 0, and text is read as a number (number("3") is 3). Text that isn't a number, empty text and anything else give null.

Arguments: 1.

number($self.ageText) + 1

string()

Turns a value into text. Lists and objects become compact JSON; null stays null.

Arguments: 1.

string($self.level) + "th level"

boolean()

Whether a value counts as true. false, 0, "" and null are false; everything else, empty lists and objects included, is true.

Arguments: 1.

boolean($self.companion)

Objects

keys()

An object's keys, as a list. A value that isn't an object gives an empty list.

Arguments: 1.

keys($self.skillProficiencies).length

values()

An object's values, as a list. A value that isn't an object gives an empty list.

Arguments: 1.

sum(values($self.coins))

entries()

An object's keys and values, as a list of { key, value } objects. A value that isn't an object gives an empty list.

Arguments: 1.

entries($self.skillProficiencies).filter(e => e.value).map(e => e.key)

has()

Whether an object has a key, given as text: has($self.resourceState, "rage").

Arguments: 2.

has($self.resourceState, "rage") ? "Can rage" : "No rage"

Other files

load()

The content of the file a reference points at, with that file's own computed fields worked out, plus $id, $name, $title, $image, $coverImage and $fileTypeSlug. Takes a reference field's value (or a reference id). A slug, a missing file or null gives null.

Arguments: 1.

load($self.armor)?.bonus ?? 0
$self.party.map(p => load(p)?.$name).join(", ")

See load() for what it returns and the one-level rule.

List methods

list.map()

A new list with what the function gives for each item.

Arguments: 1; the 1st is a function (x => …) with up to 2 parameters.

$self.knownSpells.map(s => load(s)?.school)

list.filter()

A new list of the items the function says yes to.

Arguments: 1; the 1st is a function (x => …) with up to 2 parameters.

$self.inventory.filter(e => e.equipped)

list.find()

The first item the function says yes to, or null when there is none.

Arguments: 1; the 1st is a function (x => …) with up to 2 parameters.

$self.weapons.find(w => w.equipped)?.name ?? "Unarmed"

list.findIndex()

The position of the first item the function says yes to, counting from 0, or -1 when there is none.

Arguments: 1; the 1st is a function (x => …) with up to 2 parameters.

$self.stages.findIndex(s => !s.done)

list.some()

Whether the function says yes to at least one item.

Arguments: 1; the 1st is a function (x => …) with up to 2 parameters.

$self.conditions.some(c => load(c)?.$name === "Poisoned")

list.every()

Whether the function says yes to every item. True for an empty list.

Arguments: 1; the 1st is a function (x => …) with up to 2 parameters.

$self.objectives.every(o => o.done)

list.includes()

Whether the list holds a value. Lists and objects compare by their contents.

Arguments: 1.

$self.tags.includes("undead")

list.indexOf()

The position of a value in the list, counting from 0, or -1 when it isn't there. Lists and objects compare by their contents.

Arguments: 1.

["novice", "adept", "master"].indexOf($self.rank)

list.at()

The item at a position, counting from 0. A negative position counts from the end: at(-1) is the last item. Out of range gives null.

Arguments: 1.

$self.history.at(-1)

list.slice()

The items from a start position up to, but not including, an end position. Both are optional, and negative ones count from the end.

Arguments: 0 to 2.

$self.log.slice(-3)

list.concat()

A new list with the given lists' items added at the end. A value that isn't a list is added as one item.

Arguments: 1 or more.

$self.innateSpells.concat($self.learnedSpells)

list.flat()

A new list with the lists inside it opened up, one level deep unless a depth is given.

Arguments: 0 to 1.

$self.groups.map(g => g.members).flat()

list.flatMap()

Like map, but when the function gives a list, its items are added one by one.

Arguments: 1; the 1st is a function (x => …) with up to 2 parameters.

$self.party.flatMap(p => load(p)?.languages ?? [])

list.join()

The items as one piece of text, with a separator between them (a comma when none is given). Nulls become empty text.

Arguments: 0 to 1.

$self.titles.join(", ")

list.reduce()

Folds the list into one value: the function takes the value so far and each item, and gives the next value. The starting value is required.

Arguments: 2; the 1st is a function (x => …) with up to 3 parameters.

$self.rolls.reduce((best, r) => r > best ? r : best, 0)

list.toSorted()

A sorted copy of the list. With no function, a list of only numbers or only text sorts in order, with nulls last; a mixed list gives null. With a function (a, b) =>, a negative result puts a first.

Arguments: 0 to 1; the 1st is a function (x => …) with up to 2 parameters.

$self.skills.toSorted((a, b) => b.rank - a.rank).at(0)?.name

list.toReversed()

A copy of the list in reverse order.

Arguments: 0.

$self.log.toReversed()

list.unique()

A copy of the list with repeats taken out, keeping each first one. Lists and objects compare by their contents.

Arguments: 0.

$self.preparedSpells.map(s => load(s)?.school).filter(s => s).unique()

Text methods

text.toUpperCase()

The text in capital letters.

Arguments: 0.

$self.name.toUpperCase()

text.toLowerCase()

The text in small letters.

Arguments: 0.

$self.element.toLowerCase()

text.trim()

The text without spaces and line breaks at the start and end.

Arguments: 0.

$self.nickname.trim()

text.includes()

Whether the text contains another piece of text.

Arguments: 1.

$self.description.includes("cursed")

text.startsWith()

Whether the text begins with another piece of text.

Arguments: 1.

$self.code.startsWith("NPC-")

text.endsWith()

Whether the text ends with another piece of text.

Arguments: 1.

$self.name.endsWith("the Bold")

text.slice()

The characters from a start position up to, but not including, an end position. Both are optional, and negative ones count from the end.

Arguments: 0 to 2.

$self.name.slice(0, 1)

text.split()

The text cut into a list at each separator: "a, b".split(", ") is ["a", "b"].

Arguments: 1.

$self.aliases.split(", ")

text.replace()

The text with the first match of one piece of text replaced by another. Matches plain text only.

Arguments: 2.

$self.title.replace("Sir ", "")

text.replaceAll()

The text with every match of one piece of text replaced by another. Matches plain text only.

Arguments: 2.

$self.motto.replaceAll("-", " ")

text.padStart()

The text made up to a length by adding a fill (a space unless one is given) at the start: "7".padStart(3, "0") is "007".

Arguments: 1 to 2.

string($self.roomNumber).padStart(3, "0")

text.padEnd()

The text made up to a length by adding a fill (a space unless one is given) at the end.

Arguments: 1 to 2.

$self.label.padEnd(12, ".")