Variables and types

Plugins are full of values: a player's health, their coins, their name, whether they are flying. On this page you will learn how Java stores values in variables, which type fits which job, how to turn text into numbers, and you will build a plugin with /mystats and /setfood commands.

What a variable is

A variable is a named place that holds one value. You give it a name, put a value in, read the value later, and replace it with a new value whenever you like.

Here is a variable in action. Run it, then read the notes:

1void main() {12    int coins = 50;23    IO.println("You start with " + coins + " coins.");4 35    coins = 80;6    IO.println("After selling wheat: " + coins + " coins.");7 48    coins = coins + 25;59    IO.println("After a quest reward: " + coins + " coins.");10}

Every declaration has the same parts:

Declaring first, filling later, and copying

You can create a variable without a value and fill it later. And when you put one variable into another, Java copies the value, so the two chests are independent afterwards:

1void main() {12    int kills;23    kills = 3;4 35    int bestKills = kills;46    kills = kills + 1;7 8    IO.println("Kills now: " + kills);9    IO.println("Best before this fight: " + bestKills);10}

Variables in plugin code

Plugins use variables constantly, mostly to hold answers the server gives you. Each line below asks the server for something and keeps the answer in a variable with the right type:

11Player player = event.getPlayer();22String name = player.getName();33double health = player.getHealth();44int foodLevel = player.getFoodLevel();55boolean flying = player.isFlying();

Why store the answer instead of asking again each time? It makes the next lines shorter, it gives the value a clear name, and you know the value will not change halfway through your code.

Types: which chest for which value

Java needs to know each variable's type before the program runs. That lets the compiler catch mistakes early: if you try to put text into a number variable, your code does not even compile. Java has eight basic types built in, called primitive types. They are all written in lowercase:

Here are most of them at once, holding a player's stats:

1void main() {12    String name = "Steve";23    double health = 20.0;34    int foodLevel = 20;5    int coins = 1250;46    float walkSpeed = 0.2f;57    boolean isFlying = false;68    long playTimeMillis = 7_200_000L;79    char rankLetter = 'A';10 11    IO.println("Name: " + name);12    IO.println("Health: " + health);13    IO.println("Food: " + foodLevel);14    IO.println("Coins: " + coins);15    IO.println("Walk speed: " + walkSpeed);16    IO.println("Flying: " + isFlying);17    IO.println("Play time (ms): " + playTimeMillis);18    IO.println("Rank: " + rankLetter);19}

Want to see the exact limits? Each number type has a MIN_VALUE and MAX_VALUE you can print:

1void main() {2    IO.println("byte:  " + Byte.MIN_VALUE + " to " + Byte.MAX_VALUE);3    IO.println("short: " + Short.MIN_VALUE + " to " + Short.MAX_VALUE);14    IO.println("int:   " + Integer.MIN_VALUE + " to " + Integer.MAX_VALUE);5    IO.println("long:  " + Long.MIN_VALUE + " to " + Long.MAX_VALUE);26    IO.println("double can hold up to about " + Double.MAX_VALUE);7}

Why health is a double and coins an int

Choose the type by asking: "Can this value have decimals?"

• Health can. A zombie hit can leave you at 17.5 health, and armor reduces damage by fractions of a point. So health is a double.
• Coins usually cannot. Nobody owns 12.75 diamonds. Whole numbers are simpler and exact, so coins, levels and item amounts are int.
• Yes-or-no questions are always boolean. Do not use the numbers 0 and 1 for that.
• Times in milliseconds are huge numbers, far beyond 2.1 billion, so they need a long.

In plugins, you rarely choose: Paper already decided. Every method tells you what type it gives back, and your variable must match. Hover a method in IntelliJ, or press Ctrl+Q, to see its type. These are the types Paper uses for common player values:

Notice the naming habit: methods that answer a yes-or-no question start with is or has (isFlying, hasPlayedBefore) and return a boolean. Methods that give a value start with get. Name your own variables the same way: isFlying, hasKit, coins.

String: text

Text is stored in a String (a "string of characters"). A String value is written between double quotes. Unlike the primitive types, String starts with a capital S, because it is a class: a richer type that comes with its own methods, such as length().

1void main() {12    String name = "Alex";23    String greeting = "Welcome back, " + name + "!";34    String nickname = null;5 6    IO.println(greeting);47    IO.println("Letters in the name: " + name.length());58    IO.println("Nickname: " + nickname);9}

null matters a lot in plugins. Paper returns null when there is nothing to give you, for example player.getKiller() when a player fell to their death, or Bukkit.getPlayerExact("Steve") when Steve is offline. Calling a method on null, such as nickname.length(), crashes with a NullPointerException. You will learn to check for it in Making decisions and Null, exceptions and stack traces. The full toolbox for text is in Working with text.

var: let Java work out the type

Inside a method, you can write var instead of the type, and Java fills in the type from the value. This is called type inference:

1void main() {12    var coins = 50;23    var health = 20.0;34    var name = "Steve";45    var isFlying = true;6 7    coins = coins + 10;8    IO.println(name + " has " + coins + " coins, " + health + " health, flying: " + isFlying);9}

var does not mean "any type". The type is still fixed forever; you just did not type it out. Putting a decimal into coins later fails:

1void main() {2    var coins = 50;13    coins = 12.5;4}

While you are learning, write the real type. int coins = 50; tells you, and anyone reading, exactly what the chest holds. With var player = event.getPlayer(); you have to know what getPlayer() returns to understand the line. You will see var in other people's plugins, and it is fine once types feel natural.

final variables and constants

Put final in front of a variable and it can be assigned only once. Trying to change it is a compile error:

1void main() {12    final int maxHomes = 3;3    IO.println("You can set " + maxHomes + " homes.");24    maxHomes = 5;5}

Values that are the same for the whole program, like limits and settings, are called constants. You declare them outside any method with static final, and name them in UPPER_SNAKE_CASE so they stand out:

11static final int MAX_HOMES = 3;22static final int TICKS_PER_SECOND = 20;33static final String SERVER_NAME = "Skyblock Island";4 5void main() {6    IO.println("Welcome to " + SERVER_NAME + "!");47    IO.println("Every player may set " + MAX_HOMES + " homes.");8    IO.println("The server runs " + TICKS_PER_SECOND + " ticks per second.");9}

Plugins use constants the same way, written at the top of a class. You will see this line in the plugin later on this page:

11private static final int MAX_FOOD_LEVEL = 20;

Why bother instead of typing 20? Because a bare 20 in the middle of code could mean 20 food, 20 health, 20 ticks or 20 coins. MAX_FOOD_LEVEL can only mean one thing, and if the value ever changes, you change it in one place. Values that server owners should be able to change go even further, into a config file (see Configuration files).

Converting between types

Between number types: casting

Java converts a smaller number type into a bigger one automatically, because nothing can be lost. Going the other way, from double to int, would throw away the decimals, so Java makes you say so with a cast: the target type in parentheses.

1void main() {2    int foodLevel = 17;13    double asDouble = foodLevel;4    IO.println("int 17 as a double: " + asDouble);5 6    double health = 7.9;27    int wholeHealth = (int) health;8    IO.println("(int) 7.9 = " + wholeHealth);9 10    double damage = -2.7;311    IO.println("(int) -2.7 = " + (int) damage);12 413    double hearts = health / 2;514    int fullHearts = (int) hearts;15    IO.println(health + " health is " + hearts + " hearts, " + fullHearts + " of them full");16}

If you forget the cast, the compiler refuses with "possible lossy conversion". This is one of the errors you will meet most, because Paper gives you a double for health but many things you calculate from it need to be int:

1void main() {2    double health = 19.5;13    int roundedHealth = health;4}

Between text and numbers: parsing

Text that looks like a number is still text. "64" is two characters, not the number 64. To do math with it, parse it into a number. To go the other way, turn a number into text with String.valueOf:

1void main() {12    String typedAmount = "64";23    int amount = Integer.parseInt(typedAmount);4    IO.println("Doubled: " + (amount * 2));5 6    String typedSpeed = "0.5";37    double speed = Double.parseDouble(typedSpeed);8    IO.println("Speed plus one: " + (speed + 1));9 10    int level = 30;411    String levelText = String.valueOf(level);12    IO.println("As text the level has " + levelText.length() + " characters");13 514    IO.println("Text glued: " + typedAmount + typedAmount);15}

If the text is not a number, parsing fails at runtime with a NumberFormatException:

1void main() {2    String typedAmount = "ten";13    int amount = Integer.parseInt(typedAmount);4    IO.println("You asked for " + amount);5}

This is not just theory. When a player types a command like /setfood 15, your plugin receives the 15 as a String, always. You parse it, and you must be ready for players who type /setfood lots. The plugin below shows how.

A plugin full of variables

This plugin adds two commands. /mystats reads your stats into variables of the right types and prints them. /setfood 15 turns the text 15 into a number and sets your hunger bar. Commands get a whole chapter later (Commands, part 1); here, focus on the variables.

1package com.example.javavariablestypesstats;2 3import io.papermc.paper.command.brigadier.BasicCommand;4import io.papermc.paper.command.brigadier.CommandSourceStack;5import org.bukkit.entity.Player;6 17public final class StatsCommand implements BasicCommand {8 29    private static final int MAX_FOOD_LEVEL = 20;10 11    @Override312    public void execute(CommandSourceStack source, String[] args) {413        if (!(source.getExecutor() instanceof Player player)) {14            source.getSender().sendRichMessage("<red>Only players can use /mystats.");15            return;16        }17 518        String name = player.getName();619        double health = player.getHealth();20        int foodLevel = player.getFoodLevel();721        float saturation = player.getSaturation();22        int level = player.getLevel();823        boolean flying = player.isFlying();924        long firstPlayed = player.getFirstPlayed();25 1026        int fullHearts = (int) (health / 2);27 1128        player.sendRichMessage("<gold>Stats for " + name);29        player.sendRichMessage("<gray>Health: <red>" + health + " <gray>(" + fullHearts + " full hearts)");30        player.sendRichMessage("<gray>Food: <green>" + foodLevel + "/" + MAX_FOOD_LEVEL);31        player.sendRichMessage("<gray>Saturation: <yellow>" + saturation);32        player.sendRichMessage("<gray>Level: <aqua>" + level);33        player.sendRichMessage("<gray>Flying: <white>" + flying);34        player.sendRichMessage("<gray>First joined: <white>" + firstPlayed + " <gray>ms after 1970");35    }36}

Here is what a player sees after typing /mystats:

The second command turns typed text into a number, keeps it in range, and uses it:

1package com.example.javavariablestypesstats;2 3import io.papermc.paper.command.brigadier.BasicCommand;4import io.papermc.paper.command.brigadier.CommandSourceStack;5import org.bukkit.entity.Player;6 7public final class SetFoodCommand implements BasicCommand {8 9    private static final int MAX_FOOD_LEVEL = 20;10 11    @Override12    public void execute(CommandSourceStack source, String[] args) {13        if (!(source.getExecutor() instanceof Player player)) {14            source.getSender().sendRichMessage("<red>Only players can use /setfood.");15            return;16        }117        if (args.length != 1) {18            player.sendRichMessage("<red>Type one number after the command, like /setfood 20.");19            return;20        }21 222        String typed = args[0];323        int amount;24        try {425            amount = Integer.parseInt(typed);526        } catch (NumberFormatException exception) {27            player.sendRichMessage("<red>That is not a whole number. Try /setfood 20.");28            return;29        }30 631        int newFoodLevel = Math.clamp(amount, 0, MAX_FOOD_LEVEL);732        player.setFoodLevel(newFoodLevel);33        player.sendRichMessage("<green>Your food level is now " + newFoodLevel + ".");34    }35 36    @Override837    public String permission() {38        return "variablestats.setfood";39    }40}

The main class registers both commands when the plugin starts:

1package com.example.javavariablestypesstats;2 3import io.papermc.paper.plugin.lifecycle.event.types.LifecycleEvents;4import org.bukkit.plugin.java.JavaPlugin;5 6public final class VariableStatsPlugin extends JavaPlugin {7 8    @Override9    public void onEnable() {110        getLifecycleManager().registerEventHandler(LifecycleEvents.COMMANDS, event -> {211            event.registrar().register("mystats", "Shows your health, food, level and more", new StatsCommand());12            event.registrar().register("setfood", "Sets your food level from 0 to 20", new SetFoodCommand());13        });14    }15}

1name: VariableStats2version: '1.0.0'3main: com.example.javavariablestypesstats.VariableStatsPlugin4api-version: '26.3'5description: Shows how plugin values fit Java types with /mystats and /setfood.6permissions:17  variablestats.setfood:8    description: Lets a player change their own food level with /setfood.29    default: op

Download this plugin as a Gradle project to run it on your test server.

Common mistakes

Reading a variable before it has a value

1void main() {12    int coins;23    IO.println("Coins: " + coins);4}

Going past the limit: overflow

When an int goes past its maximum, it does not stop or crash. It wraps around to the most negative number. This is called overflow, and it has caused real money bugs on servers:

1void main() {12    int coins = Integer.MAX_VALUE;3    IO.println("Coins: " + coins);4 25    coins = coins + 1;6    IO.println("One more coin: " + coins);7 38    long bigCoins = Integer.MAX_VALUE;9    bigCoins = bigCoins + 1;10    IO.println("With a long: " + bigCoins);11}

If a number could ever grow past two billion (total blocks mined on a big server, money that players can farm forever, milliseconds), use long.

Comparing decimals exactly

Computers store decimals in binary, so some values are stored very slightly off. The tiny error shows up when you compare with ==:

1void main() {12    double total = 0.1 + 0.2;3    IO.println("0.1 + 0.2 = " + total);24    IO.println("Is it exactly 0.3? " + (total == 0.3));35    IO.println("Is it close to 0.3? " + (Math.abs(total - 0.3) < 0.0001));6}

In plugins this bites when you check health or coordinates, such as player.getHealth() == 20.0 after healing. Prefer comparisons like >=, or check whether the values are close. For money, many plugins store whole cents in a long instead of a double, so the math is always exact.

Writing the wrong kind of value

1void main() {12    float walkSpeed = 0.2;3}

The same rule gives you the plugin version of this error. Paper's getHealth() returns a double, so this line does not compile:

1int health = player.getHealth();

Either use double health = player.getHealth();, or cast if you really want a whole number: int health = (int) player.getHealth();.

Practice

1void main() {2    String name = "Alex";3    IO.println("=== " + name + " ===");4}

1static final int MAX_FOOD_LEVEL = 20;2 3void main() {4    String name = "Alex";5    double health = 15.5;6    int foodLevel = 18;7    int level = 27;18    long coins = 3_000_000_000L;9    boolean isFlying = false;10 211    int fullHearts = (int) (health / 2);12 13    IO.println("=== " + name + " ===");14    IO.println("Health: " + health + " (" + fullHearts + " full hearts)");15    IO.println("Food: " + foodLevel + "/" + MAX_FOOD_LEVEL);16    IO.println("Level: " + level);17    IO.println("Coins: " + coins);18    IO.println("Flying: " + isFlying);19 20    coins = coins + 500;21    level = level + 1;22    IO.println("After the quest: level " + level + ", " + coins + " coins");23}

1int xpPercent = (int) (player.getExp() * 100);2player.sendRichMessage("<gray>XP to next level: <aqua>" + xpPercent + "%");

More short challenges are waiting in the Practice Arena.

Recap

• A variable is a named, typed place for one value. Declare it once (int coins = 50;), then read it by name and change it with =.
• Pick the type by the value: int for whole numbers, long for huge ones, double for decimals, boolean for yes or no, String for text.
• In plugins, match the type that Paper's method returns: double for health, int for food and levels, float for saturation and yaw.
• null means "nothing here". Calling a method on it crashes.
• var lets Java infer the type, but the type is still fixed.
• final stops a variable from changing. Constants are static final and named in UPPER_SNAKE_CASE.
• Cast with (int) to drop decimals. Parse text with Integer.parseInt, and turn numbers into text with String.valueOf. Command arguments always arrive as text.

Quick quiz

Next steps

• Operators and math: calculate damage, chances, distances and ticks.
• Working with text: everything you can do with a String.
• Working with players: many more values you can read and change on a player.