Tutorial by: Goose

A Guide to learning List Variables

1) What are list variables?
2) Why should I use list variables?
3) Usage of List Variables
4) List of Examples
5) Summary

[ What are list variables? ]

To explain it simply, list variables are variables which can hold multiple values. List variables look like {variable::*} and can have values added and removed using vanilla add and remove effects. They can also be deleted and can be overwritten with the set effect.

[ Why should I use list variables? ]

You should use list variables because they provide access to more features, these features include looping, sorting, mass deletion, etc. Even if you think that it's a situation where you don't need to use list variables, you should still use them anyway because it'll be very helpful down the road. Here is a quick example of a list variable's use.

on first join:
    add player to {joined::*}
    # Now the list variable {joined::*} contains both the player and anybody else who has joined before them.
    # Let's say there were three players that have joined: Steve, Notch and Alex, this variable now holds these players.

command /allplayers:
    permission: admin.allplayers
        send "%{joined::*}%" # This would send a list of people that had joined, if only Steve, Notch and Alex had joined, it would return "Steve, Notch and Alex".

[ Usage of List Variables ]

List variables are like rooms full of cardboard boxes, where every cardboard box represents a variable.

[ Index ]

List variables has two halves, their name and their index. Let's imagine a list variable's name is the name of a room full of cardboard boxes, and an index is one of the cardboard boxes in that room. Let's start by learning how to put cardboard boxes in that room.

add the player to {room::*}

Let's continue with this cardboard box example. This line of code creates a cardboard box that holds the player, and you may notice we never told Skript what to call this variable but instead we told it to put it in the room called {room::*}. Skript names these boxes by number, and it starts at 1 and works its way up to Infinity. This means that the variable actually holding the player is called {room::1}. This works pretty well if we don't care what the box is called, but only the fact that the room is called {room::*}. For example, let's say we had a variable that held all the players that have ever joined the server, it doesn't matter if it's player 1, player 2 or player 128, only that they are in the list. However, in many cases you will wan[ t to have the ability to name every single box in the room so you know where to get it when you want it's contents.

All you need to do is set the name (The part after the two colons) in the variable. You can write it yourself or even use expressions to do it for you, here is an example:

set {player.%player%} to true # The old method
set {player.list::%player%} to true # The new method

delete {player.list::%player%} # This refers to the entire room when deleting, rather than a single box. You can also delete specific boxes in the room with the following example:
delete {player.list::UntitledGoose} # This would delete the box that holds the player UntitledGoose

[ Looping ]

To start looping a list variable, you would start it with:

loop {list::*}

What this line does is check every single cardboard box in that room, one by one.

At this point, you have a couple of values that you can use:

Now you can deal with every value in the room as it loops through every box.

[ List of Examples ]

    # This is a simple queue skript.
    command /queue:
            if {queue::*} contains player:
                remove player from {queue::*}
                send "&cYou have left the queue!"
            else if {queue::*} doesn't contain player:
                add player to {queue::*}
                send "&aYou have joined the queue!"

    command listqueue:
        permission: admin.listqueue
            send "&7Players in queue:"
            loop all players in {queue::*}:
                send "&c- %loop-player%"
    # StaffChat Skript
    on join:
        if player has permission "sight.staffchat":
            if {staff::*} doesn't contain player:
                add player to {staff::*}

    command staffchat [<text>]:
        permission: staffchat.use
        aliases: /sc
        usage: &c/sc (message)
            if arg-text isn't set:
                if {staffchat::%player%} is true:
                    delete {staffchat::%player%}
                    send "&7[&cStaffChat&7] You have toggled staffchat off!"
                    set {staffchat::%player%} to true
                    send "&7[&cStaffChat&7] You have toggled staffchat on!"
                send "&cStaffChat &7>> &c%player's display name%&8: &f%arg-text%" to {staff::*}

on chat:
    if {staffchat::%player%} is true:
        cancel event
        send "&cStaffChat &7>> &c%player's display name%&8: &f%message%" to {staff::*}

[ Summary ]

List variables are very useful because they allow for features that you couldn't get with normal variables (ex. looping, mass deletion, sorting, etc.) In a way, they are like YAML because you can make arrays/lists yet also have values.

Did you find Goose's tutorial helpful?

You must be logged in to comment