Project: Welcome kit

In this project you build a complete plugin from an empty folder: when a new player joins your server, they see a title, hear a sound and receive a starter kit, and every text, sound and item can be changed in a config file without touching the code.

What you will build

Many servers greet new players with a short welcome and a few useful items. You will build exactly that, and you will build it the way real plugins are built: small classes that each do one job, and settings that live in a file the server owner can edit.

When a player joins the server for the very first time, three things happen. They see a message in chat:

A big title appears in the middle of their screen, and a sound plays:

And four items are waiting in their hotbar (the row of slots at the bottom of the screen):

The next time Steve joins, he only gets a quiet "welcome back" line. The title, the sound and the kit are only for first joins, otherwise players would collect a free kit every time they log in.

The plan

Before writing code, a good developer writes a plan: what must the plugin do, and which piece of the Paper API does each job? Here is ours. Every row links to the chapter that explains that piece in depth, so you can read more whenever something feels new.

And here are the steps. Each one gives you something you can run and test before you move on, which is the best habit a beginner can learn: build a little, test a little, and you always know which step broke things.

1. Create the project and plugin.yml

   The files Paper needs to recognize your plugin, and a first console line.

2. Greet every player in chat

   Your first listener, with the text typed straight into the code.

3. Move the settings into config.yml

   Messages, title, sound and kit become editable.

4. Add the title and the sound

   Show the title and play the configured sound.

5. Detect the first join

   Only new players get the big welcome.

6. Give the starter kit

   Turn config entries into real items in the inventory.

7. Test it properly

   A checklist, including how to become a "new player" again.

The finished project is in the download if you want to compare your work, but try to type the code yourself first. Typing is how it sticks.

Step 1: create the project and plugin.yml

You need a plugin project that builds and starts on a test server. If you already followed Your first plugin, copy that project and rename it. If you have the paper-templates folder on your PC, the quickest way is the helper script, which copies a ready-made project and renames everything for you:

Whichever way you start, the project layout is the same: a build.gradle.kts, and under src/main a java folder for code and a resources folder for files such as plugin.yml and config.yml. This project uses the package com.example.projectwelcome. (The small step-by-step files on this page sit in folders with a number in the package name, like projectwelcomestep1, so they can be downloaded separately. In your own project, use com.example.projectwelcome everywhere.) If you use another package name, that is fine, but the main: line in plugin.yml must always match your main class exactly.

The plugin.yml file is Paper's name tag for your plugin. Without it, Paper does not even look at your code:

11name: WelcomeKit2version: '1.0.0'23main: com.example.projectwelcome.WelcomeKitPlugin34api-version: '26.3'5description: Greets new players with a title, a sound and a starter kit, all set in config.yml.

The main class is also needed now, even if it does almost nothing yet. This version only prints one line to the console, which proves that Paper loaded the plugin:

1package com.example.projectwelcomestep1;2 3import org.bukkit.plugin.java.JavaPlugin;4 15public final class WelcomeKitPlugin extends JavaPlugin {6 7    @Override28    public void onEnable() {39        getServer().getPluginManager().registerEvents(new WelcomeListener(), this);410        getLogger().info("WelcomeKit is ready.");11    }12}

This file mentions a WelcomeListener that does not exist yet, so IntelliJ shows a red error. That is expected, and the next step fixes it. Learning to read red errors as "the next thing to write" is a big part of programming.

Step 2: greet every player in chat

Time for the first useful code. A listener class waits for the join event and sends a message. This is the same pattern as in Events and listeners, with one new tool: a placeholder.

1package com.example.projectwelcomestep1;2 3import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;4import org.bukkit.entity.Player;5import org.bukkit.event.EventHandler;6import org.bukkit.event.Listener;7import org.bukkit.event.player.PlayerJoinEvent;8 19final class WelcomeListener implements Listener {10 211    @EventHandler312    public void onJoin(PlayerJoinEvent event) {413        Player player = event.getPlayer();14        player.sendRichMessage(515            "<green>Welcome to the server, <yellow><name></yellow>!",616            Placeholder.unparsed("name", player.getName()));17    }18}

Build the plugin and run the server (see Build, install and test), join, and you see:

Check the server console as well. You should see this line, and it is your proof that onEnable ran:

[14:02:11 INFO]: [WelcomeKit] Enabling WelcomeKit v1.0.0[14:02:11 INFO]: [WelcomeKit] WelcomeKit is ready.

Step 3: move the settings into config.yml

Right now, to change "Welcome to the server" you must edit the code, rebuild the plugin and restart. A server owner who just downloaded your plugin cannot do that. The solution is a config file: a text file next to the plugin that the owner can edit with Notepad. Paper's name for this file is config.yml, and it is written in a format called YAML.

Think of it like the options screen of a game: the game's code stays the same, but you change the values. Here is our whole config:

11messages:22  first-join: "<green>Welcome to the server, <yellow><name></yellow>! Your starter kit is in your inventory."3  returning: "<gray>Welcome back, <yellow><name></yellow>."4 5title:46  enabled: true7  main: "<gold><bold>Welcome!"8  sub: "<gray>Have fun, <name>"39  stay-seconds: 310 11sound:12  enabled: true513  name: "entity.player.levelup"14  volume: 1.015  pitch: 1.016 17kit:618  items:19    sword:720      material: STONE_SWORD21      amount: 1822      name: "<aqua>Starter Sword"23    pickaxe:24      material: STONE_PICKAXE25      amount: 126      name: "<aqua>Starter Pickaxe"27    food:28      material: COOKED_BEEF29      amount: 1630    torches:31      material: TORCH32      amount: 32

Texts are wrapped in quotation marks. They are not always required, but they keep characters that YAML treats as special, like : and #, from breaking the file. Wrap every text in quotes and you never have to think about it.

Turning the file into Java objects

Reading getConfig().getString("title.main") in ten different places gets messy fast. Instead we read the file once, when the plugin starts, and keep the results in one small object. A Java record is made for exactly this: a class that only holds values. You list the values in parentheses and Java builds the class for you, including methods like titleText() that read each value back. (Records are explained in Enums, records and modern Java.)

112record WelcomeSettings(13    String firstJoinMessage,14    String returningMessage,15    boolean titleEnabled,16    String titleText,17    String subtitleText,18    int titleStaySeconds,19    Sound sound,20    float soundVolume,21    float soundPitch,222    List<KitEntry> kit) {23 324    static WelcomeSettings from(ConfigurationSection config, Logger logger) {25        return new WelcomeSettings(426            config.getString("messages.first-join", "<green>Welcome, <name>!"),27            config.getString("messages.returning", "<gray>Welcome back, <name>."),528            config.getBoolean("title.enabled", true),29            config.getString("title.main", "<gold>Welcome!"),30            config.getString("title.sub", "<gray>Have fun, <name>"),631            config.getInt("title.stay-seconds", 3),832            loadSound(config, logger),733            (float) config.getDouble("sound.volume", 1.0),34            (float) config.getDouble("sound.pitch", 1.0),35            loadKit(config, logger));36    }

The main class now loads the settings and hands them to the listener. It also calls saveDefaultConfig(), which copies config.yml out of the plugin jar into plugins/WelcomeKit/ the first time the plugin runs. If the file is already there, it is left alone, so the owner's edits are never overwritten.

1package com.example.projectwelcome;2 3import org.bukkit.plugin.java.JavaPlugin;4 5public final class WelcomeKitPlugin extends JavaPlugin {6 7    @Override8    public void onEnable() {19        saveDefaultConfig();210        WelcomeSettings settings = WelcomeSettings.from(getConfig(), getLogger());311        getServer().getPluginManager().registerEvents(new WelcomeListener(settings), this);412        getLogger().info("WelcomeKit is ready with " + settings.kit().size() + " kit items.");13    }14}

The listener from step 2 must now receive these settings. Change the top of WelcomeListener so it keeps them in a field, and replace each typed-in text with a value from the settings (you will see the finished onJoin in step 5):

15final class WelcomeListener implements Listener {16 117    private static final MiniMessage MINI_MESSAGE = MiniMessage.miniMessage();18 219    private final WelcomeSettings settings;20 321    WelcomeListener(WelcomeSettings settings) {422        this.settings = settings;23    }

Step 4: add the title and the sound

A title is a Title object made of two pieces of text and three timings. Titles, action bars, boss bars and sounds explains each part; here is how our listener uses it. The method receives the name placeholder, so the title can greet the player too.

41private void showTitle(Player player, TagResolver name) {142    if (!settings.titleEnabled()) {43        return;44    }245    player.showTitle(Title.title(346        MINI_MESSAGE.deserialize(settings.titleText(), name),47        MINI_MESSAGE.deserialize(settings.subtitleText(), name),448        Title.Times.times(49            Duration.ofMillis(500),50            Duration.ofSeconds(settings.titleStaySeconds()),51            Duration.ofSeconds(1))));52}

Playing a sound safely

Sounds are the one setting a server owner can easily get wrong: one typo in entity.player.levelup and there is no sound at all. We cannot stop typos, but we can notice them. When the settings load, loadSound looks the name up in the sound registry, the server's list of every sound that exists. If the name is not in the list, we print a warning once, at startup, instead of failing silently on every join.

38private static Sound loadSound(ConfigurationSection config, Logger logger) {139    if (!config.getBoolean("sound.enabled", true)) {40        return null;41    }42    String name = config.getString("sound.name", "entity.player.levelup");243    NamespacedKey key = NamespacedKey.fromString(name);344    Sound sound = key == null ? null : Registry.SOUNDS.get(key);45    if (sound == null) {546        logger.warning("Unknown sound '" + name + "' in config.yml, so no sound will play.");47    }48    return sound;49}

Playing the sound is then simple. The listener only checks that a sound exists:

54private void playSound(Player player) {155    if (settings.sound() == null) {56        return;57    }258    player.playSound(player.getLocation(), settings.sound(), settings.soundVolume(), settings.soundPitch());59}

If the owner mistypes the sound, this is what the console shows when the server starts:

[14:02:11 WARN]: [WelcomeKit] Unknown sound 'entity.player.levelop' in config.yml, so no sound will play.

Step 5: detect the first join

Now the heart of the plugin: who is new? Every player object has a method hasPlayedBefore(). It answers true if the server remembers this player from an earlier visit, and false during their very first join. Here is the whole join handler:

25@EventHandler26public void onJoin(PlayerJoinEvent event) {27    Player player = event.getPlayer();128    TagResolver name = Placeholder.unparsed("name", player.getName());29 230    if (player.hasPlayedBefore()) {31        player.sendRichMessage(settings.returningMessage(), name);332        return;33    }34 35    player.sendRichMessage(settings.firstJoinMessage(), name);436    showTitle(player, name);37    playSound(player);38    giveKit(player);39}

Step 6: give the starter kit

The config describes each kit item with a material, an amount and an optional name. We need one object per item, so here is the small record for it, plus the method that turns it into a real ItemStack, the stack of items you hold in a slot:

1package com.example.projectwelcome;2 3import net.kyori.adventure.text.minimessage.MiniMessage;4import org.bukkit.Material;5import org.bukkit.inventory.ItemStack;6 17record KitEntry(Material material, int amount, String name) {8 9    private static final MiniMessage MINI_MESSAGE = MiniMessage.miniMessage();10 11    ItemStack createItem() {212        ItemStack item = ItemStack.of(material, amount);313        if (name != null && !name.isBlank()) {414            item.editMeta(meta -> meta.itemName(MINI_MESSAGE.deserialize(name)));15        }16        return item;17    }18}

Next, loadKit walks through the kit.items section of the config and builds one KitEntry per item. It is the longest method in the plugin, so read it in pieces:

51private static List<KitEntry> loadKit(ConfigurationSection config, Logger logger) {152    List<KitEntry> kit = new ArrayList<>();253    ConfigurationSection items = config.getConfigurationSection("kit.items");54    if (items == null) {55        return kit;56    }357    for (String id : items.getKeys(false)) {58        ConfigurationSection entry = items.getConfigurationSection(id);59        if (entry == null) {760            continue;61        }562        Material material = Material.matchMaterial(entry.getString("material", ""));663        if (material == null || !material.isItem()) {64            logger.warning("Kit item '" + id + "' has an unknown material, so it is skipped.");65            continue;66        }867        int amount = Math.clamp(entry.getInt("amount", 1), 1, material.getMaxStackSize());68        kit.add(new KitEntry(material, amount, entry.getString("name")));69    }70    return kit;71}

The last piece gives the items to the player. addItem puts each stack into the first free slots, filling the hotbar first. If the inventory is full, it cannot place everything, and it returns the leftovers in a map instead of throwing them away. We drop those on the ground so nothing is lost:

61private void giveKit(Player player) {162    for (KitEntry entry : settings.kit()) {263        Map<Integer, ItemStack> leftovers = player.getInventory().addItem(entry.createItem());364        for (ItemStack leftover : leftovers.values()) {465            player.getWorld().dropItemNaturally(player.getLocation(), leftover);66        }67    }68}

That finishes the code. The finished project has five files, and none of them is longer than a screen or two:

Step 7: test it properly

"It compiled" is not the same as "it works". Players find the bugs you did not test for, so go through a checklist like this one every time you finish a plugin. Start the server with Run Paper Server and tick off each line:

• The console shows WelcomeKit is ready with 4 kit items. and no warnings or red errors.
• A first join shows the chat message, the title and the sound, and the four items land in the hotbar.
• Leave and join again: only the "welcome back" line appears, and no new items.
• Fill your inventory completely, become new again, and join: the kit items fall on the ground at your feet.
• Edit run/plugins/WelcomeKit/config.yml: change a message, set sound.enabled to false, and remove one kit item. Restart and check that each change took effect.
• Break the config on purpose: mistype a material name and a sound name. The console should warn about both, and nothing else should break.

How to become a new player again

The first-join code only runs once per player, so to test it again you must make the server forget you. Stop the server first. Then delete your player file, which is named after your UUID (your player's unique id), from the world's player data folder. In Paper 26.x that folder is run/world/players/data; on older versions it was called playerdata. Start the server again and join: you are new.

Here is what the console should look like when everything works, including the two warnings from the "break it on purpose" test:

[14:20:03 WARN]: [WelcomeKit] Unknown sound 'entity.player.levelop' in config.yml, so no sound will play.[14:20:03 WARN]: [WelcomeKit] Kit item 'torches' has an unknown material, so it is skipped.[14:20:03 INFO]: [WelcomeKit] WelcomeKit is ready with 3 kit items.

Mistakes to avoid

• Tabs in the YAML file. YAML only allows spaces for indentation. A Tab character gives a loading error that names the exact line.
• Forgetting saveDefaultConfig(). Without it, no config.yml is created, and every setting silently falls back to its default.
• Editing src/main/resources/config.yml and expecting the running server to change. That file is only the template inside the jar. The live copy is in run/plugins/WelcomeKit/config.yml, and it is never overwritten once it exists. Delete the live copy to get the new template.
• Gluing a player's name into the message text. Always use a placeholder, so text that comes from players or files can never add MiniMessage tags to your message. Minecraft names rarely contain such characters, but chat text and nicknames can, and the habit costs nothing.
• Trusting the owner's input. Mistyped materials, sounds and amounts happen. Check values when loading and warn, instead of letting the plugin crash on the first join.

Exercises

1package com.example.projectwelcomeexercise;2 3import net.kyori.adventure.text.minimessage.MiniMessage;4import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;5import org.bukkit.Bukkit;6import org.bukkit.entity.Player;7import org.bukkit.event.EventHandler;8import org.bukkit.event.Listener;9import org.bukkit.event.player.PlayerJoinEvent;10 11final class NewPlayerAnnouncer implements Listener {12 13    private static final MiniMessage MINI_MESSAGE = MiniMessage.miniMessage();14 15    private final String announcement;16 17    NewPlayerAnnouncer(String announcement) {18        this.announcement = announcement;19    }20 21    @EventHandler22    public void onJoin(PlayerJoinEvent event) {23        Player player = event.getPlayer();124        if (player.hasPlayedBefore()) {25            return;26        }227        Bukkit.broadcast(MINI_MESSAGE.deserialize(announcement, Placeholder.unparsed("name", player.getName())));28    }29}

1messages:2  announcement: "<gold><name></gold> <gray>joined for the first time. Say hello!"

1snack:2  material: GOLDEN_APPLE3  amount: 34  name: "<gold>Emergency Snack"

Extension ideas

When you finish the main project, these are good next steps. Each one uses something from a chapter you can read at any time:

• A reload command. Add /welcomekit reload that rebuilds the settings without a restart (you need to keep the listener's settings in a place that can change). Builds on Brigadier commands, and the next project, /heal and /feed, shows a real command class.
• Armor in the kit. Equip leather armor straight onto the player with player.getInventory().setHelmet(...). See Inventories.
• A kit per permission. Give donors a bigger kit using player.hasPermission(...). See Permissions.
• A delayed welcome. Show the title two seconds after joining, so the player has finished loading in. See The scheduler.
• A custom join message. Replace the yellow "joined the game" line with your own using event.joinMessage(...), as in Events and listeners.

You can also open the finished plugin in the Compile Lab, change it and compile it right in your browser.

Recap

• A plugin is built from small classes that each do one job: a main class, a settings class, a listener and a record for one kit item.
• PlayerJoinEvent runs your code when a player joins; hasPlayedBefore() separates new players from returning ones.
• saveDefaultConfig() copies config.yml from the jar once; getConfig() reads it. Always give getString, getInt and the others a default value.
• Read the config once at startup into a record, and check every value that the owner can get wrong. Warn in the console instead of crashing.
• Placeholders such as <name> insert player names into MiniMessage text safely.
• addItem returns the items that did not fit; drop them on the ground so nothing disappears.
• Test with a checklist, including the failure cases.

Quick quiz

Next steps

• Project: /heal and /feed: your first project with real commands, permissions and cooldowns.
• Configuration files: everything about config.yml, lists, sections and saving.
• Practice Arena: short challenges that train the skills from this project.