SugarString and value functions
format()
format("Health: {$health}")
format("{} found {}", ACTOR.name, reward)
format("{2} challenged {1}", rival.name, ACTOR.name)Returns formatted text without producing message output. Named placeholders accept variable names and property paths, not arbitrary expressions. Positional placeholders use {} from left to right or one-based indexes such as {1}. Use {{ and }} for literal braces.
upper()
upper(value)Converts a value to uppercase text. upper("hello") returns "HELLO".
lower()
lower(value)Converts a value to lowercase text. lower("READY") returns "ready".
pluralize()
pluralize(count, singular, plural)Returns the singular form when count is 1. Otherwise, it returns the optional plural form. When plural is omitted, Sugar applies basic English pluralization, including changing a consonant plus y to ies.
pluralize(2, "try")
pluralize(2, "person", "people")Returns "tries" and "people".
ordinal()
ordinal(number)Returns ordinal text such as "1st", "2nd", "3rd", or "11th". Decimal input is truncated to a whole number.
contains()
contains(text, substring)Returns true when text contains substring. Matching is case-insensitive. Empty input returns false.
join()
join(separator, a, b, c...)Converts the provided values to text and joins non-empty entries with separator.
join(" / ", "Truth", "Dare", "Double Dare")Returns "Truth / Dare / Double Dare".
concat()
concat(a, b, c...)Joins non-empty values with one space between them.
concat(3, pluralize(3, "time"))Returns "3 times".
showIf()
showIf(condition, value)Returns value as text when the condition is true, otherwise empty text. The value must be text or a number.
empty()
empty(value)Returns true for empty text or an empty list, otherwise false.
exists()
exists(value)Returns whether a value exists. Use it when an optional value may be absent or None.
Math functions
abs()
abs(number)Returns the absolute value. abs(-8) returns 8.
ceil()
ceil(number)Rounds upward to the nearest whole number.
floor()
floor(number)Rounds downward to the nearest whole number.
round()
round(number)Rounds to the nearest whole number.
sqrt()
sqrt(number)Returns the square root.
log()
log(number)Returns the natural logarithm.
log2()
log2(number)Returns the base-2 logarithm.
log10()
log10(number)Returns the base-10 logarithm.
min()
min(a, b, c...)Returns the smallest provided number.
max()
max(a, b, c...)Returns the largest provided number.
clamp()
clamp(value, minimum, maximum)Returns value limited to the inclusive range. The minimum cannot exceed the maximum.
clamp() does not assign anything automatically:
health = clamp(health + 20, 0, maxHealth);Random and ID namespaces
Rand::pick()
Rand::pick(range)
Rand::pick(a, b, c...)Returns one randomly selected value. Pass a range to choose any whole number in it, or pass two or more arguments to choose between those exact values. At least one value is required.
Rand::pick(1..=20)
Rand::pick("Truth", "Dare")Rand::weighted()
Rand::weighted(
weight => value,
weight => value,
...
)Returns one value using the relative numeric weights on the left of =>. Weights may be number expressions, must be non-negative and finite, and do not need to add up to 100. At least one weight must be greater than zero. An entry with weight 0 cannot be selected.
Rand::weighted(
7 => "COMMON",
2 => "UNCOMMON",
1 => "RARE",
)Rand::chance()
Rand::chance(percent)Returns a random boolean with the requested percentage chance. Values are constrained from 0 through 100.
Rand::roll()
Rand::roll(expression)
Rand::roll(expression, embed)Rolls a dice expression and returns its numeric total. embed defaults to true and adds JOI’s dice embed.
Rand::roll("1d20")
Rand::roll("2d6+3", false)
Rand::roll("2d20k1 + 1d6-2")Supported dice are d2, d4, d6, d8, d10, d12, and d20. One dice expression may roll up to 10 dice. It may keep or drop dice with k, kl, d, and dl, and use modifiers up to 1000.
One Sugar program may make up to 10 dice calls and roll up to 50 dice across those calls. Automations must pass false as the second argument.
Id::new()
Id::new()Returns a new UUID as text.
Id::short()
Id::short()Returns a compact 21-character Nano ID using URL-safe characters.
Time functions
dayOfWeek()
dayOfWeek()Returns "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", or "Sunday".
This function is deprecated. New code should use Date::now().weekday, which returns the lowercase weekday name.
timeOfDay()
timeOfDay()Returns "morning" from 5:00 through 11:59, "afternoon" from 12:00 through 16:59, "evening" from 17:00 through 20:59, and "night" at other times.
Item actions and Boops use participant 1’s timezone when available and Pacific Time otherwise. Automations use their declared timezone or the creator’s detected timezone.
Collection functions
len()
len(listOrObject)Returns the number of list entries or own object properties.