HyperScript
Docs

← All of the Docs Working with values

Lists

expressionsorted <list>

Ascending copy: numbers first, then text A-Z ignoring case · 1, 3, 5, 9

set {_names} to sorted server.players
Try it
expressionreversed <list>

Copy in reverse order · 1, 9, 3, 5

set {_newest_first} to reversed {winners}
Try it
expressionreversed sorted <list>

Descending copy · 9, 5, 3, 1

set {_top} to reversed sorted {scores}
Try it
expressionfilter <list> where <condition>

Elements for which the condition holds; it is the element · filter {_nums} where it > 4 gives 5, 9

set {_rich} to filter {_top} where it >= 500
Try it
expressionsize of <list>

Number of elements (or characters, for text) · 4

set {_count} to size of {_words}
Try it
expressionitem <n> of <list>

The n-th element, counting from 1; unset if there is none · item 2 of {_nums} gives 3

set {_a} to item 1 of {_players}
Try it
expression{_list.<n>}since 1.4.0

The same, for a list in a local variable; handy inside text as %{_nums.2}% · {_nums.2} gives 3

set {_parts} to split "Coins:500" by ":"
send "You have %{_parts.2}% coins"
Try it
condition<list> contains <value>

Whether the value is in the list · {_nums} contains 9 is true

if {winners} contains player.name:
    send "You already won."
Try it
expression<list> + <value>

Copy with the value at the end · 5, 3, 9, 1, 7

set {_everyone} to server.players + "Console"
Try it
expressionrandom item of <list>since 1.5.2

One element picked at random; unset for an empty list · random item of {_nums}

send random item of ["Hello!", "Hi there!", "Welcome!"]
Try it
expressionrandom <n> of <list>since 1.7.59

That many different elements, in no order; all of them if the list has fewer · random 3 of server.players

command /pickthree:
    trigger:
        set {_lucky} to random 3 of server.players
        send "&6Winners: &f%{_lucky}%" to all players
Try it
effectappend <value> to <variable>

Add to the end. An unset variable becomes a one-element list.

append player.name to {winners}
Try it
effectset item <n> of <variable> to <value>since 1.7.2

Replace one element, counting from 1. The list must already have that many

set {podium} to ["Steve", "Alex", "Bob"]
set item 1 of {podium} to player.name
send "&6First place: &f" + item 1 of {podium}
Try it
effectadd <value> to <variable>

Same as append if the variable already holds a list; otherwise arithmetic

add 1 to {_slot}
Try it
effectremove <value> from <variable>

Remove the first matching element

remove player.name from {winners}
Try it
expressionitems <a> to <b> of <list>since 1.5.7

A part of the list, counting from 1, both ends included · items 1 to 5 of {_ranked}

set {_top} to items 1 to 5 of reversed sorted {scores}
Try it
expressionindex of <value> in <list>since 1.5.7

Where the value is; unset if it is not there · index of player.name in {queue}

set {_place} to index of player.name in {queue}
Try it
expressionclosest match of <text> in <list>since 1.7.60

The element most like the text, for "did you mean": a letter or two off, or what it begins with. Unset if nothing is close · closest match of arg.1 in keys of {warp}

command /kit <name>:
    trigger:
        set {_kits} to ["starter", "miner", "builder"]
        if {_kits} contains arg.1:
            send "&aHere is your %arg.1% kit."
            stop
        set {_meant} to closest match of arg.1 in {_kits}
        if {_meant} is set:
            send "&cThere is no kit %arg.1%. Did you mean &f%{_meant}%&c?"
Try it
expression<list> as sentencesince 1.7.60

The elements as people write a list: Steve, Alex and Bob · server.players as sentence

command /who:
    trigger:
        set {_names} to server.players as sentence
        send "&7Online: &f%{_names}%"
Try it
expressionrandom item of <list>since 1.5.2

One element, picked at random · random item of {announcements}

send random item of ["Hello!", "Hi there!", "Welcome!"]
Try it
expressionrandom item of <list> weighted by <list>since 1.7.15

The same, but not evenly: the second list gives each element its chance, so [70, 25, 5] makes the first fourteen times as likely as the last. Unset if every chance is 0 · random item of {loot} weighted by {chances}

command /crate:
    trigger:
        set {_prizes} to ["bread", "gold_ingot", "diamond"]
        set {_prize} to random item of {_prizes} weighted by [70, 25, 5]
        give player 1 "%{_prize}%"
        send "&aYou won &f%{_prize}%&a!"
Try it
expressionfirst <n> of <list> / last <n> of <list>since 1.7.0

The beginning or the end of a list · first 3 of {queue}

set {_shout} to uppercase (first 20 characters of {_note})
Try it
expressionnumbers from <a> to <b>since 1.7.0

A list of whole numbers, counting up or down · numbers from 1 to 5

for each {_n} in numbers from 3 to 1:
    send "&e%{_n}%..."
Try it
expressioncount of <value> in <list>since 1.7.0

How many times it occurs; works on text too · count of "a" in {letters}

set {_votes} to count of "yes" in {votes}
Try it
expressionmin of <list> / max of <list>since 1.7.0

The smallest or largest number in it · max of {scores}

set {_best} to max of {scores}
Try it
expression<list> without <value>since 1.7.1

The list with the first such value taken out · server.players without player.name

for each {_other} in server.players without player.name:
    send "&7%player.name% says hi" to {_other}
Try it
expression<list> sorted by {<name>}since 1.7.1

Player names ordered by each one's own variable, highest first · server.players sorted by {coins}

set {_richest} to server.players sorted by {coins}
send "&6Richest online: &e" + item 1 of {_richest}
Try it
expression<list> sorted by <value>since 1.7.59

Ordered by anything that can be said of one element, which is loop-value there: lowest first, or highest first when that is written behind it. Text is ordered by the alphabet · {_words} sorted by length of loop-value

command /longest:
    trigger:
        set {_words} to ["banana", "kiwi", "apple"]
        set {_ordered} to {_words} sorted by length of loop-value highest first
        send "&7%{_ordered}%"
Try it
expressionmap each <list> to <expression>since 1.7.1

A new list, each element changed the same way; it is the element · map each {prices} to it * 2

set {_shouted} to map each ["red", "blue"] to uppercase it
Try it
expressionrandom playersince 1.5.9

The name of a random online player; unset if nobody is on · give 1 diamond to random player

set {_winner} to random player
broadcast "&6%{_winner}% wins the draw!"
Try it
expressionshuffled <list>since 1.5.9

The same elements in a random order · shuffled server.players

set {_order} to shuffled server.players
Try it
expressionunique <list>since 1.5.9

Without repeats; the first of each is kept · unique {visitors}

set {_once} to unique ["a", "b", "a"]
Try it
expressionsum of <list> / average of <list>since 1.5.9

Its numbers added up, or their mean · sum of {donations}

set {_total} to sum of [10, 20, 30]
set {_mean} to average of [10, 20, 30]
Try it
expressionplayers within <n> blocks of <location>since 1.5.9

The names of the players that close, nearest first · players within 10 blocks of player

for each {_near} in players within 10 blocks of player:
    send "&7%player.name% waves at you." to {_near}
Try it
expressionblocks within <n> blocks of <location>since 1.7.57

The location of every block that close, nearest first; block at says what is there · blocks within 3 blocks of player

command /stones:
    trigger:
        set {_n} to 0
        loop blocks within 4 blocks of player where block at loop-value is "stone":
            add 1 to {_n}
        send "&7Stone around you: &f%{_n}%"
Try it
expressionblocks from <location> to <location>since 1.7.57

The location of every block in the box between two opposite corners · blocks from {_a} to {_b}

command /floor:
    trigger:
        set {_a} to player's location offset by -2, -1, -2
        set {_b} to player's location offset by 2, -1, 2
        loop blocks from {_a} to {_b}:
            set block at loop-value to glass
Try it
expressionentities within <n> blocks of <location>since 1.7.44

The creatures that close, nearest first, players not among them. Each can be given to anything that takes a creature · entities within 10 blocks of player

set {_left} to size of entities within 20 blocks of player
Try it
expressionentities of <kind> within <n> blocks of <location>since 1.7.44

The same for one kind of creature · entities of zombie within 20 blocks of player

for each {_mob} in entities of zombie within 20 blocks of player:
    kill {_mob}
Try it
expressionnearest block of <type> within <n> blocks of <location>since 1.7.60

Where the closest block of that kind is, as a location; unset if there is none that close · nearest block of diamond ore within 10 blocks of player

command /findore:
    trigger:
        set {_ore} to nearest block of diamond ore within 12 blocks of player
        if {_ore} is set:
            send "&bDiamonds at &f%{_ore}%"
        else:
            send "&7Nothing close by."
Try it
expressionnearest player to <location>since 1.7.44

The name of the player closest to a place, in that world; unset if nobody is there. nearest other player to player leaves out the player the trigger runs for · nearest other player to player

set {_who} to nearest player to player's location
if {_who} is set:
    send "&7Closest: &f%{_who}%"
Try it
expressionnearest entity to <location>since 1.7.44

The closest creature that is not a player, up to 256 blocks away; a kind may be named instead of entity · nearest zombie to player

set {_any} to nearest entity to player's location
Try it
expressionwords of <text>since 1.7.44

The words of a text as a list · words of "one two three"

for each {_word} in words of "red green blue":
    send "&7%{_word}%"
Try it
expressionkeys of {<table>}since 1.5.7

The names under a table; see Records and tables · keys of {warp}

for each {_name} in keys of {warp}:
    send "&7 - &b%{_name}%"
Try it
Guide and examples
set {_nums} to [5, 3, 9, 1]
set {_names} to ["Steve", "Alex"]
set {_empty} to []
SyntaxResultExample with {_nums} = [5, 3, 9, 1]
sorted <list>Ascending copy: numbers first, then text A-Z ignoring case1, 3, 5, 9
reversed <list>Copy in reverse order1, 9, 3, 5
reversed sorted <list>Descending copy9, 5, 3, 1
filter <list> where <condition>Elements for which the condition holds; it is the elementfilter {_nums} where it > 4 gives 5, 9
size of <list>Number of elements (or characters, for text)4
item <n> of <list>The n-th element, counting from 1; unset if there is noneitem 2 of {_nums} gives 3
{_list.<n>}The same, for a list in a local variable; handy inside text as %{_nums.2}%{_nums.2} gives 3
<list> contains <value>Whether the value is in the list{_nums} contains 9 is true
<list> + <value>Copy with the value at the end5, 3, 9, 1, 7
random item of <list>One element picked at random; unset for an empty listrandom item of {_nums}
random <n> of <list>That many different elements, in no order; all of them if the list has fewerrandom 3 of server.players

Statements that change a list variable:

StatementEffect
append <value> to <variable>Add to the end. An unset variable becomes a one-element list.
set item <n> of <variable> to <value>Replace one element, counting from 1. The list must already have that many
add <value> to <variable>Same as append if the variable already holds a list; otherwise arithmetic
remove <value> from <variable>Remove the first matching element
append player.name to {winners}
set {_top} to reversed sorted {scores}
set {_rich} to filter {_top} where it >= 500
send "Best: %{_top}% (of which %{_rich}% are 500 or more)"
if {winners} contains player.name:
    send "You already won."
  • A list prints as its elements joined by , .
  • Lists can be stored in global and player variables and are saved like any other value.
  • Operations never modify a list in place; they produce a new one. set {_b} to {_a} followed by a change to {_b} leaves {_a} alone.
  • More ways to take a list apart:
SyntaxResultExample
items <a> to <b> of <list>A part of the list, counting from 1, both ends includeditems 1 to 5 of {_ranked}
index of <value> in <list>Where the value is; unset if it is not thereindex of player.name in {queue}
closest match of <text> in <list>The element most like the text, for "did you mean": a letter or two off, or what it begins with. Unset if nothing is closeclosest match of arg.1 in keys of {warp}
<list> as sentenceThe elements as people write a list: Steve, Alex and Bobserver.players as sentence
random item of <list>One element, picked at randomrandom item of {announcements}
random item of <list> weighted by <list>The same, but not evenly: the second list gives each element its chance, so [70, 25, 5] makes the first fourteen times as likely as the last. Unset if every chance is 0random item of {loot} weighted by {chances}
first <n> of <list> / last <n> of <list>The beginning or the end of a listfirst 3 of {queue}
numbers from <a> to <b>A list of whole numbers, counting up or downnumbers from 1 to 5
count of <value> in <list>How many times it occurs; works on text toocount of "a" in {letters}
min of <list> / max of <list>The smallest or largest number in itmax of {scores}
<list> without <value>The list with the first such value taken outserver.players without player.name
<list> sorted by {<name>}Player names ordered by each one's own variable, highest firstserver.players sorted by {coins}
<list> sorted by <value>Ordered by anything that can be said of one element, which is loop-value there: lowest first, or highest first when that is written behind it. Text is ordered by the alphabet{_words} sorted by length of loop-value
map each <list> to <expression>A new list, each element changed the same way; it is the elementmap each {prices} to it * 2
random playerThe name of a random online player; unset if nobody is ongive 1 diamond to random player
shuffled <list>The same elements in a random ordershuffled server.players
unique <list>Without repeats; the first of each is keptunique {visitors}
sum of <list> / average of <list>Its numbers added up, or their meansum of {donations}
players within <n> blocks of <location>The names of the players that close, nearest firstplayers within 10 blocks of player
blocks within <n> blocks of <location>The location of every block that close, nearest first; block at says what is thereblocks within 3 blocks of player
blocks from <location> to <location>The location of every block in the box between two opposite cornersblocks from {_a} to {_b}
entities within <n> blocks of <location>The creatures that close, nearest first, players not among them. Each can be given to anything that takes a creatureentities within 10 blocks of player
entities of <kind> within <n> blocks of <location>The same for one kind of creatureentities of zombie within 20 blocks of player
nearest block of <type> within <n> blocks of <location>Where the closest block of that kind is, as a location; unset if there is none that closenearest block of diamond ore within 10 blocks of player
nearest player to <location>The name of the player closest to a place, in that world; unset if nobody is there. nearest other player to player leaves out the player the trigger runs fornearest other player to player
nearest entity to <location>The closest creature that is not a player, up to 256 blocks away; a kind may be named instead of entitynearest zombie to player
words of <text>The words of a text as a listwords of "one two three"
keys of {<table>}The names under a table; see Records and tableskeys of {warp}
  • keys of {warp} looks at every saved variable whose name starts with warp. and gives the next part of each name: with {warp.spawn} and {warp.arena} set, it is the list arena, spawn. That is how a script loops over a table it has built. It works for a player's own tables as well: keys of {%player%.homes}.
  • filter reads to the end of the condition, including any and / or. Wrap it in parentheses to use the result in a larger expression: size of (filter {_nums} where it > 4).