Working with players¶

Most plugins end up doing something to players, like checking where they are or moving them around. In this lesson you'll learn how to read things about a player and how to change them, and you'll finish with a few handy admin commands.

Part 1: Read things about a player¶

You already know how to find a player by name. Once you have one, you can ask them all sorts of questions. This command tells you where someone is:

main.lua

plugin.addCommand({
    name = "whereis",
    description = "Show where a player is",
    usage = "/whereis <player>",
    minArgs = 1,
    maxArgs = 1
}, function(event)
    local sender = event.getSender()
    local args = event.getArgs()
    local target = plugin.getServer():getPlayer(args[1])

    if target then
        local location = target:getLocation()
        sender:sendMessage(target:getName() .. " is at " .. location:getBlockX() .. ", " .. location:getBlockY() .. ", " .. location:getBlockZ())
    else
        sender:sendMessage("That player isn't online.")
    end
end)

target:getLocation() gives you the player's position, and then getBlockX(), getBlockY() and getBlockZ() give you its three coordinates as whole numbers. Lua happily joins numbers and text with .., so the message comes out like Steve is at 120, 64, -35.

Try /whereis with your own name and compare it with the coordinates on your screen.

Part 2: Change a player's game mode¶

Some things you change need a bit of Minecraft's own vocabulary, like the game modes. To use them, you first bring them into your plugin with import:

main.lua

local GameMode = import("$.GameMode")

local modes = {
    survival = GameMode.SURVIVAL,
    creative = GameMode.CREATIVE,
    adventure = GameMode.ADVENTURE,
    spectator = GameMode.SPECTATOR
}

plugin.addCommand({
    name = "gm",
    description = "Change your game mode",
    usage = "/gm <survival|creative|adventure|spectator>",
    permission = "admintools.gm",
    minArgs = 1,
    maxArgs = 1
}, function(event)
    local sender = event.getSender()
    local args = event.getArgs()
    local mode = modes[string.lower(args[1])]

    if not event.isPlayerSender() then
        sender:sendMessage("Only players can change their game mode.")
    elseif mode then
        sender:setGameMode(mode)
        sender:sendMessage("Your game mode is now " .. string.lower(args[1]) .. ".")
    else
        sender:sendMessage("Pick survival, creative, adventure or spectator.")
    end
end)

import("$.GameMode") brings in Spigot's GameMode, which holds the four modes. The $ is a shortcut that stands for org.bukkit, where Spigot keeps it. GameMode.CREATIVE has a dot because it's a value you read, not a method you call.

The modes table lines up what the player types with the real game mode, so modes["creative"] gives you GameMode.CREATIVE. If they type something that isn't in the table, like /gm banana, the answer is nil. We use string.lower so Creative and CREATIVE work too.

The if has three outcomes: the console can't have a game mode, a valid mode changes yours, and anything else gets a hint. That's why we didn't need return here.

The permission line means only players with that permission can use the command, which keeps regular players from making themselves creative. Server operators can use it, and you can give it to others with a permissions plugin.

Try /gm creative and then /gm survival.

Part 3: Teleport players¶

Teleporting works by handing a location to teleport. Here are two commands that use it. The first sends you to the world's spawn point:

main.lua

plugin.addCommand({
    name = "spawn",
    description = "Go to the world's spawn point",
    usage = "/spawn"
}, function(event)
    local sender = event.getSender()

    if event.isPlayerSender() then
        local spawnPoint = sender:getWorld():getSpawnLocation()
        sender:teleport(spawnPoint)
        sender:sendMessage("Teleported to spawn!")
    else
        sender:sendMessage("Only players can teleport.")
    end
end)

sender:getWorld() is the world you're in, :getSpawnLocation() is where that world's spawn point is, and sender:teleport(spawnPoint) moves you there.

The second brings another player to you:

main.lua

plugin.addCommand({
    name = "bring",
    description = "Teleport a player to you",
    usage = "/bring <player>",
    permission = "admintools.bring",
    minArgs = 1,
    maxArgs = 1
}, function(event)
    local sender = event.getSender()
    local args = event.getArgs()
    local target = plugin.getServer():getPlayer(args[1])

    if not event.isPlayerSender() then
        sender:sendMessage("Only players can use this command.")
    elseif target then
        target:teleport(sender:getLocation())
        sender:sendMessage("Brought " .. target:getName() .. " to you.")
    else
        sender:sendMessage("That player isn't online.")
    end
end)

This time we find the target with getPlayer, then target:teleport(sender:getLocation()) sends them to wherever you're standing.

Try /spawn, and with a friend online, /bring their name.

Putting it together¶

Combined, your main.lua is a small set of admin tools:

main.lua

local GameMode = import("$.GameMode")

local modes = {
    survival = GameMode.SURVIVAL,
    creative = GameMode.CREATIVE,
    adventure = GameMode.ADVENTURE,
    spectator = GameMode.SPECTATOR
}

plugin.addCommand({
    name = "whereis",
    description = "Show where a player is",
    usage = "/whereis <player>",
    minArgs = 1,
    maxArgs = 1
}, function(event)
    local sender = event.getSender()
    local args = event.getArgs()
    local target = plugin.getServer():getPlayer(args[1])

    if target then
        local location = target:getLocation()
        sender:sendMessage(target:getName() .. " is at " .. location:getBlockX() .. ", " .. location:getBlockY() .. ", " .. location:getBlockZ())
    else
        sender:sendMessage("That player isn't online.")
    end
end)

plugin.addCommand({
    name = "gm",
    description = "Change your game mode",
    usage = "/gm <survival|creative|adventure|spectator>",
    permission = "admintools.gm",
    minArgs = 1,
    maxArgs = 1
}, function(event)
    local sender = event.getSender()
    local args = event.getArgs()
    local mode = modes[string.lower(args[1])]

    if not event.isPlayerSender() then
        sender:sendMessage("Only players can change their game mode.")
    elseif mode then
        sender:setGameMode(mode)
        sender:sendMessage("Your game mode is now " .. string.lower(args[1]) .. ".")
    else
        sender:sendMessage("Pick survival, creative, adventure or spectator.")
    end
end)

plugin.addCommand({
    name = "spawn",
    description = "Go to the world's spawn point",
    usage = "/spawn"
}, function(event)
    local sender = event.getSender()

    if event.isPlayerSender() then
        local spawnPoint = sender:getWorld():getSpawnLocation()
        sender:teleport(spawnPoint)
        sender:sendMessage("Teleported to spawn!")
    else
        sender:sendMessage("Only players can teleport.")
    end
end)

plugin.addCommand({
    name = "bring",
    description = "Teleport a player to you",
    usage = "/bring <player>",
    permission = "admintools.bring",
    minArgs = 1,
    maxArgs = 1
}, function(event)
    local sender = event.getSender()
    local args = event.getArgs()
    local target = plugin.getServer():getPlayer(args[1])

    if not event.isPlayerSender() then
        sender:sendMessage("Only players can use this command.")
    elseif target then
        target:teleport(sender:getLocation())
        sender:sendMessage("Brought " .. target:getName() .. " to you.")
    else
        sender:sendMessage("That player isn't online.")
    end
end)

You now have four commands: /whereis, /gm, /spawn and /bring.

Quick reference¶

These are some of the things you can do with a player. Call them with a colon, like player:getName(). The Spigot docs for Player list everything else a player can do.

Call	What it does
`player:getName()`	Gets the player's name
`player:getUniqueId()`	Gets the player's unique ID, which never changes even if they change their name
`player:sendMessage(text)`	Sends the player a message
`player:getHealth()` and `player:setHealth(number)`	Reads or changes their health
`player:getFoodLevel()` and `player:setFoodLevel(number)`	Reads or changes their hunger
`player:getLocation()`	Gets where they are
`player:teleport(location)`	Moves them to a location
`player:getWorld()`	Gets the world they're in
`player:getGameMode()` and `player:setGameMode(mode)`	Reads or changes their game mode
`player:getAllowFlight()` and `player:setAllowFlight(true or false)`	Reads or changes whether they can fly
`player:hasPermission(node)`	Checks whether they have a permission
`player:isOp()`	Checks whether they're a server operator
`player:getInventory()`	Gets their inventory

Next up is reading the Spigot docs.