HyperScript
Docs

← All of the Docs Working with values

Math

expression+

Add · 7 + 2 · 9

set {%player%.coins} to {%player%.coins} + 50
Try it
expression-

Subtract, or negate · 7 - 2 · 5

set {_left} to {%player%.coins} - 50
Try it
expression*

Multiply · 7 * 2 · 14

set {_double} to {%player%.coins} * 2
Try it
expression/

Divide · 7 / 2 · 3.5

set {_average} to {%player%.total} / {%player%.games}
Try it
expression%

Modulo (remainder) · 7 % 2 · 1

if {%player%.blocks} % 50 == 0:
    send "&bAnother 50 blocks mined!"
Try it
expression( )

Grouping · (7 + 2) * 2 · 18

set {_total} to ({_price} + {_tax}) * {_amount}
Try it
expressionrandom integer between A and B

Whole number, both ends included · random integer between 1 and 10 · 1..10

set {_roll} to random integer between 1 and 6
Try it
expressionrandom number between A and B

Decimal number · random number between 0 and 1 · e.g. 0.4217

set {_chance} to random number between 0 and 1
Try it
functionmin(a, b, ...) / max(a, b, ...)since 1.5.7

The smallest / largest; also takes one list · max(1, {%player%.level})

set {_level} to max(1, {%player%.level})
set {_cheapest} to min([30, 12, 45])
Try it
functionabs(n)since 1.5.7

Without its sign · abs(-7) gives 7

set {_apart} to abs(player.y - 64)
Try it
functionround(n)since 1.5.7

The nearest whole number · round(2.5) gives 3

set {_whole} to round(2.5)
Try it
functionfloor(n) / ceil(n)since 1.5.7

Rounded down / up · ceil(2.1) gives 3

set {_pages} to ceil(size of {warps} / 9)
Try it
expressionrounded up <n> / rounded down <n>since 1.5.7

The same two, in words · rounded up 2.1 gives 3

set {_minutes} to rounded up ({_seconds} / 60)
Try it
functionsqrt(n)since 1.5.7

Square root · sqrt(25) gives 5

set {_side} to sqrt(25)
Try it
functionpow(a, b)since 1.7.0

a to the power of b · pow(2, 10) gives 1024

set {_cost} to 100 * pow(2, {%player%.upgrades})
Try it
functionround(n, places)since 1.7.0

Rounded to that many decimal places · round(3.14159, 2) gives 3.14

set {_ratio} to round({%player%.kills} / max(1, {%player%.deaths}), 2)
Try it
functionpercent(part, whole)since 1.7.0

What percentage the first is of the second · percent(3, 12) gives 25

set {_done} to percent({%player%.quests_done}, 20)
send "&7Quests: &f%{_done}%%"
Try it
functioncommas(n)since 1.7.0

A number with thousands separators, as text · commas(1234567) gives 1,234,567

set {_shown} to commas({%player%.coins})
send "&6Balance: &e%{_shown}% coins"
Try it
functionordinal(n)since 1.7.0

1st, 2nd, 3rd, ... · ordinal(22) gives 22nd

set {_place} to ordinal(rank of player by {coins})
send "&7You are in &f%{_place}% &7place."
Try it
functionplural(n, word)since 1.7.57

The number with the word, in the plural unless it is 1. A third value is the word for many, where an s is not it · plural(5, "coin") gives 5 coins; plural(2, "wolf", "wolves") gives 2 wolves

command /homes:
    trigger:
        set {_n} to size of {%player%.homes}
        set {_said} to plural({_n}, "home")
        send "&7You have &f%{_said}%&7."
Try it
functionroman(n)since 1.7.0

Roman numerals, 1 to 3999 · roman(14) gives XIV

set {_level} to roman({%player%.prestige})
send "&dPrestige %{_level}%"
Try it
functionformat(n, pattern)since 1.7.3

The number written the way the pattern says: 0 is a digit that is always shown, # one that is shown only if needed · format(3.14159, "0.00") gives 3.14

set {_ratio} to {%player%.kills} / max({%player%.deaths}, 1)
send "&7K/D: &f" + format({_ratio}, "0.00")
Try it
functionclamp(n, least, most)since 1.7.1

The number, kept within the two · clamp(120, 0, 100) gives 100

set {%player%.mana} to clamp({%player%.mana} + 5, 0, 100)
Try it
functionlerp(from, to, t)since 1.7.44

The number that far along from the one to the other: t is 0 at the start and 1 at the end · lerp(10, 20, 0.25) gives 12.5

set {_height} to lerp(60, 80, 0.5)
send "&7Half way up is %{_height}%."
Try it
functionrandom(a, b)since 1.7.1

A random number from a to b; whole if both are whole · random(1, 6)

set {_roll} to random(1, 6)
send "&7You rolled a &f%{_roll}%"
Try it
functionduration(seconds)since 1.5.7

A number of seconds as a duration, which reads as words in a message · duration(90) gives 1 minute 30 seconds

set {_left} to duration({%player%.ready} - server.time)
send "&cWait %{_left}%."
Try it
functionshort(n)since 1.7.50

A large number in a few characters: k for thousands, then M, B, T · short(1250) gives 1.3k, short(3400000) gives 3.4M

send "&7You have &6%short({%player%.coins})% &7coins."
Try it
functionmoney(n)since 1.7.52

An amount of money, with commas and two decimals, the way money-format in config.yml says: "$%amount%" unless changed · money(1250.5) gives $1,250.50

send "&7Balance: &a%money({%player%.coins})%"
Try it
functionlerp(a, b, t)since 1.7.54

With two colours, the colour t of the way from the one to the other; with two locations, the place. With numbers it is the number, as before · lerp("#ff0000", "#0000ff", 0.5) gives #800080

set {_colour} to lerp("#ff0000", "#00ff00", player.health / 20)
spawn particle "dust" colored {_colour} count 10 at player
Try it
functionmix(a, b)since 1.7.54

The colour between two; a third value says how much of the second, from 0 to 1 · mix("#ff0000", "#0000ff") gives #800080

set {_purple} to mix("#ff0000", "#0000ff")
Try it
functionlighten(colour, amount)since 1.7.54

The colour that far towards white, from 0 to 1; 0.2 if left out · lighten("#ff0000", 0.5) gives #ff8080

set {_pale} to lighten("#336699", 0.5)
Try it
functiondarken(colour, amount)since 1.7.54

The colour that far towards black · darken("#ff0000", 0.5) gives #800000

set {_deep} to darken("#336699", 0.5)
Try it
functionrainbow(t)since 1.7.54

A colour of the rainbow: red at 0, green at a third, blue at two thirds, red again at 1, and round again from there · rainbow(0.33) is green

every 2 ticks for all players:
    add 0.02 to {_turn}
    spawn particle "dust" colored rainbow(server.time / 5) at player
Try it
functionrgb(red, green, blue)since 1.7.54

A colour from three numbers, 0 to 255 each · rgb(255, 136, 0) gives #ff8800

set {_orange} to rgb(255, 136, 0)
Try it
functionsin(angle), cos(angle), tan(angle)since 1.7.55

The sine, cosine and tangent of an angle in degrees, as the game's own angles are · sin(90) gives 1

set {_x} to cos(45) * 3
set {_z} to sin(45) * 3
spawn particle "flame" at player's location offset by {_x}, 1, {_z}
Try it
functionasin(n), acos(n), atan(n)since 1.7.55

The angle, in degrees, that has that sine, cosine or tangent · atan(1) gives 45

set {_angle} to atan(1)
send "&7That slope is %{_angle}% degrees."
Try it
expressionatan2(up, along)since 1.7.55

The angle of a slope that goes that far up over that far along; right all the way round · atan2(1, 1) gives 45

set {_angle} to atan2(1, 1)
Try it
expressiondistance between <a> and <b>since 1.5.7

Blocks between two locations; unset if they are in different worlds · distance between player's location and {spawn}

if distance between player's location and {spawn} > 100:
    send "&7You are far from spawn."
Try it
expressionhorizontal distance between <a> and <b>since 1.7.44

The same on the map alone, whatever the two heights · horizontal distance between player's location and {spawn}

set {_far} to horizontal distance between player's location and {_spot}
Try it
Guide and examples
OperatorMeaningExampleResult
+Add7 + 29
-Subtract, or negate7 - 25
*Multiply7 * 214
/Divide7 / 23.5
%Modulo (remainder)7 % 21
( )Grouping(7 + 2) * 218
random integer between A and BWhole number, both ends includedrandom integer between 1 and 101..10
random number between A and BDecimal numberrandom number between 0 and 1e.g. 0.4217

*, / and % bind tighter than + and -, as usual.

FunctionResultExample
min(a, b, ...) / max(a, b, ...)The smallest / largest; also takes one listmax(1, {%player%.level})
abs(n)Without its signabs(-7) gives 7
round(n)The nearest whole numberround(2.5) gives 3
floor(n) / ceil(n)Rounded down / upceil(2.1) gives 3
rounded up <n> / rounded down <n>The same two, in wordsrounded up 2.1 gives 3
sqrt(n)Square rootsqrt(25) gives 5
pow(a, b)a to the power of bpow(2, 10) gives 1024
round(n, places)Rounded to that many decimal placesround(3.14159, 2) gives 3.14
percent(part, whole)What percentage the first is of the secondpercent(3, 12) gives 25
commas(n)A number with thousands separators, as textcommas(1234567) gives 1,234,567
ordinal(n)1st, 2nd, 3rd, ...ordinal(22) gives 22nd
plural(n, word)The number with the word, in the plural unless it is 1. A third value is the word for many, where an s is not itplural(5, "coin") gives 5 coins; plural(2, "wolf", "wolves") gives 2 wolves
roman(n)Roman numerals, 1 to 3999roman(14) gives XIV
format(n, pattern)The number written the way the pattern says: 0 is a digit that is always shown, # one that is shown only if neededformat(3.14159, "0.00") gives 3.14
clamp(n, least, most)The number, kept within the twoclamp(120, 0, 100) gives 100
lerp(from, to, t)The number that far along from the one to the other: t is 0 at the start and 1 at the endlerp(10, 20, 0.25) gives 12.5
random(a, b)A random number from a to b; whole if both are wholerandom(1, 6)
duration(seconds)A number of seconds as a duration, which reads as words in a messageduration(90) gives 1 minute 30 seconds
short(n)A large number in a few characters: k for thousands, then M, B, Tshort(1250) gives 1.3k, short(3400000) gives 3.4M
money(n)An amount of money, with commas and two decimals, the way money-format in config.yml says: "$%amount%" unless changedmoney(1250.5) gives $1,250.50
lerp(a, b, t)With two colours, the colour t of the way from the one to the other; with two locations, the place. With numbers it is the number, as beforelerp("#ff0000", "#0000ff", 0.5) gives #800080
mix(a, b)The colour between two; a third value says how much of the second, from 0 to 1mix("#ff0000", "#0000ff") gives #800080
lighten(colour, amount)The colour that far towards white, from 0 to 1; 0.2 if left outlighten("#ff0000", 0.5) gives #ff8080
darken(colour, amount)The colour that far towards blackdarken("#ff0000", 0.5) gives #800000
rainbow(t)A colour of the rainbow: red at 0, green at a third, blue at two thirds, red again at 1, and round again from thererainbow(0.33) is green
rgb(red, green, blue)A colour from three numbers, 0 to 255 eachrgb(255, 136, 0) gives #ff8800
sin(angle), cos(angle), tan(angle)The sine, cosine and tangent of an angle in degrees, as the game's own angles aresin(90) gives 1
asin(n), acos(n), atan(n)The angle, in degrees, that has that sine, cosine or tangentatan(1) gives 45
atan2(up, along)The angle of a slope that goes that far up over that far along; right all the way roundatan2(1, 1) gives 45
distance between <a> and <b>Blocks between two locations; unset if they are in different worldsdistance between player's location and {spawn}
horizontal distance between <a> and <b>The same on the map alone, whatever the two heightshorizontal distance between player's location and {spawn}
set {%player%.coins} to {%player%.coins} + 50
set {_rand} to random integer between 1 and 10
set {_tax} to ({%player%.coins} - 100) * 0.05
add 5 to {%player%.coins}            # shorthand for set ... to ... + 5
subtract {_tax} from {%player%.coins}  # shorthand for set ... to ... - {_tax}

Details:

  • + adds when both sides are numbers and joins text otherwise: "Level " + 5 is Level 5. Text that looks like a number counts as a number, so arg.1 + 1 adds.
  • Numbers print without a trailing .0; other decimals are shown to at most 4 places.
  • Dividing (or taking a modulo) by zero, or doing math on non-numeric text, stops the trigger and logs a warning with the script name and line.
  • These functions come with the language, so a script cannot define a function called min, round and so on.
  • duration(...) is how a number of seconds becomes readable: set {_left} to duration({%player%.ready} - server.time) then send "Wait %{_left}%." says "Wait 9 minutes 30 seconds." In math it still counts as seconds.
  • The upper bound of random ... between A and B extends to the end of the arithmetic, so random integer between 1 and 10 + 5 means 1 to 15. Use parentheses to say otherwise: (random integer between 1 and 10) + 5.