How code reads

Before you can write plugins, you need to read code the way Java reads it. On this page you will run your first Java program, learn what every symbol on a line means, read and fix real error messages, and see how the same ideas show up inside a Paper plugin.

What a program is

A program is a list of instructions for the computer. The computer does exactly what the instructions say, one after another, from the top of the list to the bottom. It never guesses what you meant. If an instruction is missing, it does not happen. If two instructions are in the wrong order, they run in the wrong order.

You write those instructions as text in files that end with .java. That text is called source code. People can read source code, but the computer cannot run it directly. Two steps turn your text into something that runs:

1. Compile. A tool called the compiler (its name is javac) reads your .java files, checks that they follow Java's grammar rules, and translates them into bytecode: compact instructions stored in .class files. If something is wrong, the compiler stops and tells you where.
2. Run. The Java Virtual Machine (the JVM, started with the java command) reads the bytecode and carries out the instructions.

Why two steps? Because compiling catches many mistakes before anything runs. A typo in a plugin is much better found on your PC than on a live server with 50 players. It also means the same compiled plugin jar runs on Windows, Linux and macOS servers, because each of them has a JVM that understands bytecode.

For plugins, you will rarely type javac yourself. Gradle (see Your toolbox) runs the compiler for you, packs the .class files into a jar, and the Paper server, which is itself a Java program running on a JVM, loads that jar. Same two steps, just automated.

Your first program

Here is a complete Java program. Press Run (or the green arrow next to void main) and look at the output below the code.

11void main() {22    IO.println("Hello, Minecraft!");33    IO.println("This is my first Java program.");44}

The output is exactly the two pieces of text inside the quotes, in the same order as the lines. The quotes themselves are not printed: they only mark where the text starts and stops.

Running it on your own PC

You can run the same file outside this guide in two ways:

• In IntelliJ: create a plain Java project (File›New›Project..., choose Java and JDK 25), add a file called Hello.java, paste the code, and click the green arrow that appears next to void main. The output shows in the Run window at the bottom.
• In a terminal: go to the folder with the file and run java Hello.java. For a single file, the java command compiles it in memory and runs it right away.

$ java Hello.javaHello, Minecraft!This is my first Java program.

Reading a line of code

Look at the line IO.println("Hello, Minecraft!"); again. It has five parts, and almost every line you will write in a plugin has the same parts:

Now read this line from a real plugin. You already know how to read it, even though you have never seen it before:

11player.sendRichMessage("<green>Welcome!");

Some actions need no input, but the parentheses are still there: player.getName() asks the player for their name and needs nothing extra. Some actions need several inputs, separated by commas. You will see both all the time.

The classic way to write main

Java 25 lets you start a program with a short void main(). Older Java needed more ceremony, and you will see this longer form in almost every tutorial and Stack Overflow answer online. It does exactly the same thing:

11public class ClassicHello {22    public static void main(String[] args) {33        System.out.println("Hello, Minecraft!");4        System.out.println("This is my first Java program.");45    }6}

The Java pages in this guide use the short form, because it lets you focus on the idea being taught. Plugins always use full classes, and you will read plenty of them below.

Statements, semicolons and blocks

Statements run from top to bottom

Each complete instruction is called a statement. Statements run in order, one at a time. This little program pretends to start a server:

1void main() {12    IO.println("Loading world...");23    IO.println("Spawning villagers...");4    IO.println("Opening the doors...");35    IO.println("Server is ready!");6}

Order matters in plugins too. If your plugin sends a player a message and then teleports them, they read the message at the old spot. Swap the two lines and they read it after arriving. Same instructions, different result.

Semicolons end statements; indentation is for humans

Java does not care about line breaks or spaces between statements. It looks for the semicolon to know where one statement ends. This program is badly laid out, but it runs perfectly:

1void main() {12IO.println("Line one");23        IO.println("Line two");   IO.println("Line three");4    IO.println(5        "Line four"6    );7}

So why do the other examples look so tidy? Because people read code far more often than they write it. Consistent indentation (four spaces per level) shows at a glance which lines belong together. In IntelliJ, press Ctrl+Alt+L to reformat a file neatly. Do it often.

Braces make blocks

A pair of curly braces { } groups statements into a block. Blocks can sit inside other blocks, like boxes inside boxes. A plugin's main class is a big block, and each method inside it is a smaller block with its own statements:

Every { needs a matching }. When you forget one, the compiler gets confused and often reports the problem far below where it really is, with a message such as "reached end of file while parsing". IntelliJ highlights the matching brace when you click next to one, which makes it easy to check.

Text and numbers

The quotes matter a lot. Text inside double quotes is printed exactly as written. Without quotes, Java treats what you wrote as code and works it out first. Run this and compare each line of code with its output:

1void main() {12    IO.println("2 + 3");23    IO.println(2 + 3);34    IO.println(64 * 3);45    IO.println("One stack holds " + 64 + " items.");56    IO.println("Three stacks hold " + (64 * 3) + " items.");7}

You will use this all the time in plugins, for example "You have " + coins + " coins". The next pages explain numbers and text properly: Variables and types, Operators and math and Working with text.

Names and capital letters

Java is case sensitive: capital and small letters are different letters. IO, Io and io are three different names, and only IO exists. This is the single most common reason a beginner's code does not compile.

The names you choose yourself, for classes, methods and stored values, are called identifiers. They follow a few rules:

• Use letters, digits, _ and $ only. No spaces, no dashes, no dots.
• Do not start with a digit: player2 is fine, 2player is not.
• Do not use a Java keyword such as class or void as a name.

On top of the rules, every Java developer follows the same naming habits, called naming conventions. Java does not force them, but every Paper class follows them, so following them too makes your code look like everyone else's and helps you guess names:

The conventions are a superpower when reading code. In Material.DIAMOND_SWORD you can tell from the capitals alone that Material is a type and DIAMOND_SWORD is a fixed value. In player.getName(), the small letters and parentheses tell you player is a stored value and getName is an action.

Keywords

Keywords are words that Java reserves for its own grammar. IntelliJ shows them in a different color. There are about 50 of them, and you do not need to learn them now: each one gets explained on the page where you first need it. These are the ones you will see in almost every plugin:

One more thing you will meet in code online: notes for humans called comments. A line starting with //, or text between /* and */, is ignored by the compiler. This guide keeps its code free of comments and explains everything in the numbered notes instead, so the code you copy stays clean.

When code goes wrong

Mistakes are normal, even for experts. What matters is reading the error message, because it nearly always tells you exactly where to look. There are two kinds of errors, and they happen at different times.

Compile errors: Java cannot understand you

A compile error means the code breaks Java's grammar rules, so the compiler refuses to translate it. Nothing runs at all. This program forgot one semicolon:

1void main() {12    IO.println("Welcome to the server!")3    IO.println("Have fun!");4}

Read the error from left to right:

• MissingSemicolon.java: the file with the problem.
• :2: the line number. Go to line 2.
• error: ';' expected: what Java wanted but did not find.
• The line underneath shows your code, and the ^ points at the exact spot.

Here is the case-sensitivity mistake from earlier, written io instead of IO:

1void main() {12    io.println("Welcome to the server!");3}

"cannot find symbol" means "you used a name I do not know". The symbol: variable io line tells you which name. When you see this, check the spelling and the capital letters first, and then check whether you forgot an import (see Packages and imports).

In IntelliJ you rarely need to compile to see these errors: the editor underlines the problem in red as you type, and hovering the red line shows the same message.

Runtime errors: Java understood, but something failed

A runtime error happens while the program runs. The grammar was fine, so it compiled, but one instruction asked for something impossible. Java stops and throws an exception: an error report with a name. This program tries to share 12 diamonds among 0 players:

1void main() {12    int diamonds = 12;23    int players = 0;34    IO.println("Splitting " + diamonds + " diamonds...");45    IO.println("Each player gets " + diamonds / players);56    IO.println("Done!");7}

The first line of output proves that line 4 ran. Then comes the error report, called a stack trace:

• java.lang.ArithmeticException: the name of the problem (a math problem).
• / by zero: the details.
• at SplitDiamonds.main(SplitDiamonds.java:5): where it happened: in main, in the file SplitDiamonds.java, on line 5.

Plugins crash the same way, and the stack trace appears in the server console. If a join listener divided by zero, a player joining would print something like this. Notice that the "at" line names your class, your method and the exact line:

[14:06:03 INFO]: Steve joined the game[14:06:03 ERROR]: Could not pass event PlayerJoinEvent to HowCodeReads v1.0.0java.lang.ArithmeticException: / by zero    at com.example.javahowcodereadsplugin.GreetingListener.onJoin(GreetingListener.java:14) ~[HowCodeReads-1.0.0.jar:?]

The good news: one crashing event handler does not crash the server. Paper catches the exception, prints it, and carries on. The bad news: your feature silently stops working for that event, so always keep an eye on the console while testing. Null, exceptions and stack traces teaches stack traces in depth, and the Error Doctor explains any error you paste into it.

How plugin code is different

Everything so far started at main and ran to the end. A plugin has no main at all. Instead, the Paper server is the program that is running, and it calls your code at the right moments:

• When the server starts, Paper calls your plugin's onEnable method.
• When something happens in the game, such as a player joining, Paper calls the matching event handler in your plugin.
• When the server stops, Paper calls your onDisable method.

Inside each of those methods, your statements still run top to bottom, exactly like in the programs above. You just do not decide when the method starts. That is the server's job.

This small plugin makes the order visible. Read it with what you now know: things, dots, actions, inputs, semicolons and blocks.

11package com.example.javahowcodereadsplugin;2 23import org.bukkit.plugin.java.JavaPlugin;4 35public final class HowCodeReadsPlugin extends JavaPlugin {6 47    @Override58    public void onEnable() {69        getLogger().info("Step 1: the server called onEnable.");10        getLogger().info("Step 2: registering the join listener.");711        getServer().getPluginManager().registerEvents(new GreetingListener(), this);812        getLogger().info("Step 3: setup is done. Waiting for players...");13    }14 15    @Override916    public void onDisable() {17        getLogger().info("The server is stopping. Goodbye!");18    }19}

1package com.example.javahowcodereadsplugin;2 3import org.bukkit.entity.Player;4import org.bukkit.event.EventHandler;5import org.bukkit.event.Listener;6import org.bukkit.event.player.PlayerJoinEvent;7 18public final class GreetingListener implements Listener {9 210    @EventHandler311    public void onJoin(PlayerJoinEvent event) {412        Player player = event.getPlayer();513        player.sendRichMessage("<gold>Hello, " + player.getName() + "!");614        player.sendRichMessage("<gray>This message came from your plugin.");715        player.sendRichMessage("<gray>Your plugin ran these lines in order, top to bottom.");16    }17}

And plugin.yml tells the server which class is the main class:

1name: HowCodeReads2version: '1.0.0'13main: com.example.javahowcodereadsplugin.HowCodeReadsPlugin24api-version: '26.3'5description: Logs its startup steps and greets players, to show the order code runs in.

When you start the server, join, and stop the server again, the console shows each step in order:

[14:05:10 INFO]: [HowCodeReads] Enabling HowCodeReads v1.0.0[14:05:10 INFO]: [HowCodeReads] Step 1: the server called onEnable.[14:05:10 INFO]: [HowCodeReads] Step 2: registering the join listener.[14:05:10 INFO]: [HowCodeReads] Step 3: setup is done. Waiting for players...[14:05:42 INFO]: Steve joined the game[14:09:00 INFO]: [HowCodeReads] Disabling HowCodeReads v1.0.0[14:09:00 INFO]: [HowCodeReads] The server is stopping. Goodbye!

And Steve sees this in chat when he joins:

You can download this plugin as a Gradle project, open it in IntelliJ and run it with Run Paper Server, as shown in Your first plugin.

Practice

1void main() {2    IO.println("Welcome to my server!");3}

=== Welcome to Skyblock Island ===Rule 1: Be kind in chat.Rule 2: No griefing.Starter kit: 80 ender pearls

1void main() {2    IO.println("=== Welcome to Skyblock Island ===");3    IO.println("Rule 1: Be kind in chat.");4    IO.println("Rule 2: No griefing.");5    IO.println("Starter kit: " + (5 * 16) + " ender pearls");6}

1void main() {2    IO.println("The shop is open!")3    Io.println("Diamonds cost 5 coins.");4    IO.println("Have fun shopping!");5}

1void main() {2    IO.println("The shop is open!");3    Io.println("Diamonds cost 5 coins.");4    IO.println("Have fun shopping!");5}

1void main() {2    IO.println("The shop is open!");3    IO.println("Diamonds cost 5 coins.");4    IO.println("Have fun shopping!");5}

1getLogger().info("A double chest holds " + (54 * 64) + " items.");

Want more? The Practice Arena has short challenges for this chapter that check your answer with real tests.

Recap

• A program is a list of instructions that run from top to bottom, in order.
• Java is compiled first (javac turns .java into .class bytecode) and then run by the JVM. Gradle does both steps for plugins.
• Most lines read as "thing, dot, action, input in parentheses, semicolon": player.sendRichMessage("Hi");.
• Statements end with ;. Braces { } group statements into blocks. Indentation is only for humans.
• Java is case sensitive. Classes use PascalCase, methods and variables use camelCase, constants use UPPER_SNAKE_CASE.
• Compile errors stop the code from building; runtime errors (exceptions) stop it while it runs. Both tell you the file and line.
• Plugins have no main. The server calls onEnable, your event handlers and onDisable, and each of them runs top to bottom.

Quick quiz

Next steps

• Variables and types: store numbers, text and true/false values, such as a player's health and coins.
• IntelliJ survival guide: the shortcuts that catch mistakes before you even compile.
• Java cheat sheet: everything on one page once you have learned it.