Reading the Spigot docs¶

Spigot is far too big for any wiki to cover, so the most useful thing you can learn is how to look things up yourself. In this lesson you'll learn to find a method in the Spigot docs, read what it needs, and turn it into Lua, and you'll finish by writing a command with a method you found on your own.

Part 1: Find the docs¶

The Spigot docs are a website that lists everything your plugin can do, and you can find it here. The people who make Spigot call these pages the Javadocs, since they're built from Java code.

Everything in the docs is grouped into packages, which are like folders, and every page shows its package at the top. The Player type is in the package org.bukkit.entity. Player events, like PlayerJoinEvent, are in org.bukkit.event.player. A few important things, like GameMode, are in org.bukkit. You don't need to memorize any of that, because the search box finds things for you.

Try it now. Open the docs and type Player into the search box at the top right. The results are grouped, and the packages come first, so the highlighted top result is the package for player events, which isn't the page you want. Scroll down to Classes and Interfaces and click Player, the one that says it's an interface in the package org.bukkit.entity. If you'd rather skip the search, here's the direct link.

At the top of that page is a short description and a line called "All Superinterfaces", which we'll come back to in Part 3. Further down is the Method Summary, a table with one row for every method. A method is something you can call, like player:sendMessage(...). You'll see some tabs above the table, but you can ignore those for now.

On the left side, just under the top bar, there's a Contents box with a search of its own. The search box at the top right looks through all of the docs, but this one only looks at the page you're on. Type part of a method's name into it, like walk, and the list below narrows down to the matching methods. Click one to jump straight to it. On a long page like this one, that's the quickest way to find a method.

Part 2: Read a method¶

Every row in the Method Summary has three columns: a type on the left, the method in the middle, and a description on the right. Here are four real rows from the Player page:

You read every row the same way. The left column is what you get back. The middle column is the method's name, followed by brackets, and whatever is inside the brackets is what you have to give it. Empty brackets mean you give it nothing, and (String msg) means you give it some text, where msg is just a label.

So the first row says "getName needs nothing and gives you text", and the last row says "chat needs some text and gives you nothing". In Lua, those four look like this:

local name = player:getName()           -- gives back text
local level = player:getLevel()         -- gives back a number
local canFly = player:getAllowFlight()  -- gives back true or false
player:chat("Hello!")                   -- needs text, gives back nothing

Anything after -- is a comment. Lua ignores it, so it's a good place to leave notes for yourself. When a method gives you something back, you can save it with local, and when it needs something, you put it between the brackets.

The left column uses Java's names for things, so here's what they mean in Lua:

Now let's use those same four methods in a command:

plugin.addCommand({
    name = "stats",
    description = "Show some facts about you",
    usage = "/stats"
}, function(event)
    local sender = event.getSender()

    if event.isPlayerSender() then
        sender:sendMessage("Name: " .. sender:getName())
        sender:sendMessage("Level: " .. sender:getLevel())
        sender:sendMessage("Can fly: " .. tostring(sender:getAllowFlight()))
        sender:chat("I just checked my stats!")
    else
        sender:sendMessage("Only players can use this command.")
    end
end)

Text and numbers join straight onto a message with ... A true or false can't, so tostring turns it into text first.

When the left column isn't one of the simple types, like Location, it's a Spigot thing, and in the docs it's a link. Click it, and you land on its own page with its own list of methods. Following links like this is how you find your way around, and it's how we found getBlockX() in the last lesson.

Part 3: Where did the method go?¶

Now try something that trips up almost everyone. Go back to the Player page and look for setHealth. It isn't in the Method Summary.

That's because a player is also a living thing, and a living thing is an entity, so Player gets many of its methods from the types above it. Those methods aren't listed in the main table. Instead, further down the page, you'll find sections called "Methods inherited from..." with a list of names under each one.

Search the page for setHealth and you'll find it under Damageable, which is one of those parent types. Click it, and you land on the Damageable page, where it's described in full. The top of the Player page also has a line called "All Superinterfaces", which lists every parent type, so you know where to look.

Part 4: When a method wants a Spigot thing¶

Sometimes a method asks for something that isn't text or a number. For example, here's the line for changing a game mode:

void setGameMode(GameMode mode)

It wants a GameMode, which is a Spigot thing, and you can't get one from a player. This is where import comes in. Click GameMode in the docs, and the top of its page tells you its package, which is org.bukkit. You use that to bring it into your plugin:

local GameMode = import("org.bukkit.GameMode")

plugin.addCommand({
    name = "creative",
    description = "Switch to creative mode",
    usage = "/creative"
}, function(event)
    local sender = event.getSender()

    if event.isPlayerSender() then
        sender:setGameMode(GameMode.CREATIVE)
        sender:sendMessage("You are now in creative mode.")
    else
        sender:sendMessage("Only players can change their game mode.")
    end
end)

import takes the package and the name, joined with a dot, and gives you the thing so you can use it. Names are case sensitive, so GameMode works and gamemode doesn't. As a shortcut, $ stands for org.bukkit, so import("$.GameMode") does the same job.

The page for GameMode also lists its values, which you'll find under "Enum Constants". That's where CREATIVE, SURVIVAL and the others come from. They have a dot, like GameMode.CREATIVE, because they're values you read, not methods you call.

You only need import when a method asks for a Spigot thing that you can't get from something you already have. Most of the time you can just follow a call, like player:getLocation().

Part 5: Do it yourself¶

Now you try one on your own. Make a /fast command that makes you walk faster. Open the Player page and see if you can find the method that does it.

Here are some hints, in case you get stuck:

1. On the Player page, type walk into the Contents box on the left, and click the method that does what you want.
2. Read its row, as in Part 2. What does it want to be given? Is it text, a number, or something else?
3. Read its details to find out which numbers are allowed, and what the normal speed is. Then pick a bigger one.

Once you've had a go, here's one answer:

plugin.addCommand({
    name = "fast",
    description = "Walk faster",
    usage = "/fast"
}, function(event)
    local sender = event.getSender()

    if event.isPlayerSender() then
        sender:setWalkSpeed(0.4)
        sender:sendMessage("You walk faster now!")
    else
        sender:sendMessage("Only players can walk faster.")
    end
end)

The method is void setWalkSpeed(float value). It wants a number from -1 to 1, and anything outside that range causes an error. It gives nothing back, and the normal speed is 0.2, so 0.4 is double. Try it, and then try making a /normal command that puts it back.

Handy links¶

• The Spigot docs, where you can search for anything
• Player, everything a player can do
• Damageable, where setHealth lives
• The event list, which lists every event you can listen to

Next up is config files.