flatfusion

Write a fully customizable Minecraft Spigot/Paper Java plugin for a starter kit. When a player joins the server for the first time, they should automatically receive the kit, and they can only get it ONCE.

The plugin must be driven entirely by a config.yml file. Create a flexible configuration where server operators can add, remove, or edit ANY Minecraft item by defining the material type, custom amounts, custom display names, and lore. The plugin must keep track of players who have already received the kit (using a data file or UUID storage) so it cannot be claimed again.

Ensure the project structure is strictly set up for a Bukkit/Spigot Java Plugin so it successfully compiles into a downloadable .jar file.

Kodari AI
KodariJun 8 at 12:16 pm 9

Iโ€™ll create a fully configurable starter kit plugin that gives new players items on their first join.

StarterKit
A fully configurable starter kit system that automatically gives new players a customizable set of items on their first join. Server operators can define any items with custom amounts, display names, and lore through config.yml. Tracks player UUIDs to ensure the kit is only received once per player. Perfect for welcome packages and new player onboarding.

Done! Iโ€™ve created a complete starter kit plugin with full customization.

Features

Core Functionality:

  • Automatically gives kit to new players on first join (one time only)

  • UUID-based tracking in data.yml prevents duplicates

  • Fully configurable items with material, amount, custom names, and lore

  • Color code support with & codes

  • Cross-version compatible (1.8 - 1.21+) using XSeries

Admin Commands:

  • /starterkit reload - Reload configuration

  • /starterkit reset <player> - Reset a playerโ€™s kit status

  • /starterkit give <player> - Force give kit to a player

Configuration Example: The config.yml includes example items (diamond sword, pickaxe, food, torches, etc.) showing how to define:

  • Material type (any Minecraft item)

  • Amount (1-64)

  • Custom display name with colors

  • Multiple lore lines

Server operators can add/remove/edit any items - the plugin reads everything from the config on startup and reload.

Project Structure:

Plain Text
StarterKit/
โ”œโ”€โ”€ plugin.yml
โ”œโ”€โ”€ build.gradle
โ”œโ”€โ”€ manifest.kod
โ””โ”€โ”€ src/main/
    โ”œโ”€โ”€ resources/config.yml
    โ””โ”€โ”€ java/com/starterkit/
        โ”œโ”€โ”€ StarterKit.java (main)
        โ”œโ”€โ”€ listeners/JoinListener.java
        โ””โ”€โ”€ manager/
            โ”œโ”€โ”€ KitManager.java
            โ””โ”€โ”€ DataManager.java

Compile with ./gradlew build to generate the JAR file.

flatfusion

Write a complete, step-by-step guide from A to Z on how to use, configure, and manage this StarterKit plugin. The guide must include: how to add the plugin to your server, how to open and edit the config.yml file to customize kits, how the automatic first-join kit works, and detailed instructions for all admin commands, including /starterkit reload, /starterkit reset <player>, and /starterkit give <player>.

Kodari AI
KodariJun 8 at 12:20 pm 8

StarterKit Plugin - Complete User Guide

๐Ÿ“ฆ Installation

Step 1: Build the Plugin

  1. Download or clone the StarterKit plugin folder

  2. Open a terminal/command prompt in the plugin directory

  3. Run the build command:

    Shell
    ./gradlew build
    

    (On Windows, use gradlew.bat build)

  4. Find the compiled JAR file in build/libs/StarterKit-1.0.jar

Step 2: Install on Your Server

  1. Stop your server (always stop before adding plugins)

  2. Copy StarterKit-1.0.jar into your serverโ€™s plugins/ folder

  3. Start your server

  4. The plugin will automatically create:

    • plugins/StarterKit/config.yml (kit configuration)

    • plugins/StarterKit/data.yml (player tracking database)

Step 3: Verify Installation

Check your server console for:

Plain Text
[StarterKit] StarterKit v1.0 has been enabled!

โš™๏ธ Configuration Guide

Opening the Config File

  1. Navigate to plugins/StarterKit/config.yml

  2. Open with any text editor (Notepad++, VSCode, Sublime Text, or even Notepad)

  3. Never edit while the server is running - always stop first, or use /starterkit reload

Understanding the Config Structure

The default config looks like this:

YAML
# StarterKit Configuration
# Define items that new players receive on first join

# Enable or disable the starter kit
enabled: true

# Message sent when player receives the kit
welcome-message: "&a&lWelcome! &7You have received your starter kit!"

# Message sent when kit is given via command
kit-given-message: "&aStarter kit has been given to &e%player%&a!"

# Message sent when player already has the kit
already-received-message: "&cYou have already received your starter kit!"

# Define your kit items below
kit-items:
  # Each item needs a unique identifier (like 'sword', 'pickaxe', etc.)
  
  sword:
    material: "DIAMOND_SWORD"
    amount: 1
    name: "&b&lStarter Sword"
    lore:
      - "&7A powerful weapon to begin"
      - "&7your journey!"
  
  pickaxe:
    material: "DIAMOND_PICKAXE"
    amount: 1
    name: "&b&lStarter Pickaxe"
    lore:
      - "&7Mine resources efficiently"
  
  # ... more items

Config Settings Explained

Global Settings

Setting
Description
Example
enabled
Turn kit system on/off
true
or
false
welcome-message
Message when player gets kit
"&aWelcome!"
kit-given-message
Message when admin gives kit
"&aKit given to %player%!"
already-received-message
Message if player already has kit
"&cAlready received!"

Color Codes: Use & followed by a code:

  • &a = Green

  • &c = Red

  • &e = Yellow

  • &b = Aqua

  • &l = Bold

  • &o = Italic

  • &n = Underline

Item Configuration

Each item under kit-items: has these properties:

Property
Required?
Description
Example
material
YES
The item type
"DIAMOND_SWORD"
amount
YES
How many (1-64)
1
name
No
Custom display name
"&b&lStarter Sword"
lore
No
Description lines
List of strings

๐ŸŽจ Customization Examples

Example 1: Basic Food Kit

YAML
kit-items:
  bread:
    material: "BREAD"
    amount: 16
    name: "&eLoaf of Bread"
    lore:
      - "&7Delicious starter food"
  
  cooked-beef:
    material: "COOKED_BEEF"
    amount: 32
    name: "&cCooked Steak"

Example 2: Building Kit

YAML
kit-items:
  oak-logs:
    material: "OAK_LOG"
    amount: 64
  
  stone:
    material: "STONE"
    amount: 64
  
  crafting-table:
    material: "CRAFTING_TABLE"
    amount: 1
    name: "&6Crafting Table"
  
  furnace:
    material: "FURNACE"
    amount: 1

Example 3: Survival Starter Pack

YAML
kit-items:
  iron-sword:
    material: "IRON_SWORD"
    amount: 1
    name: "&f&lIron Sword"
    lore:
      - "&7A reliable weapon"
  
  iron-pickaxe:
    material: "IRON_PICKAXE"
    amount: 1
    name: "&f&lIron Pickaxe"
  
  iron-axe:
    material: "IRON_AXE"
    amount: 1
    name: "&f&lIron Axe"
  
  iron-shovel:
    material: "IRON_SHOVEL"
    amount: 1
    name: "&f&lIron Shovel"
  
  torches:
    material: "TORCH"
    amount: 64
  
  food:
    material: "COOKED_CHICKEN"
    amount: 32
  
  bed:
    material: "RED_BED"
    amount: 1
    name: "&cCozy Bed"

Example 4: VIP Starter Kit

YAML
kit-items:
  diamond-sword:
    material: "DIAMOND_SWORD"
    amount: 1
    name: "&b&lVIP Diamond Sword"
    lore:
      - "&d&lVIP EXCLUSIVE"
      - "&7Thank you for supporting"
      - "&7the server!"
  
  diamond-pickaxe:
    material: "DIAMOND_PICKAXE"
    amount: 1
    name: "&b&lVIP Diamond Pickaxe"
    lore:
      - "&d&lVIP EXCLUSIVE"
  
  golden-apple:
    material: "GOLDEN_APPLE"
    amount: 5
    name: "&6Golden Apple"
  
  ender-pearl:
    material: "ENDER_PEARL"
    amount: 16

๐ŸŽฏ How the Automatic Kit Works

First Join Flow

  1. Player joins server for the first time

  2. Plugin checks data.yml for playerโ€™s UUID

  3. If UUID not found:

    • Adds UUID to data.yml

    • Gives all items from kit-items section

    • Sends welcome message

    • Items appear in playerโ€™s inventory

  4. If UUID exists:

    • Player already received kit

    • No items given

    • No message sent (silent)

Data Storage

The plugin stores player UUIDs in plugins/StarterKit/data.yml:

YAML
received-players:
- "069a79f4-44e9-4726-a5be-fca90e38aaf5"  # Example UUID
- "853c80ef-3c37-49fd-aa49-938b674adae6"

Important Notes:

  • Uses UUID (not username) - works even if player changes name

  • Persists across server restarts

  • Do NOT manually edit data.yml unless resetting players


๐Ÿ› ๏ธ Admin Commands

All commands require the starterkit.admin permission (operators have this by default).

Command 1: /starterkit reload

Purpose: Reload the configuration file without restarting the server

Permission: starterkit.admin

Usage:

Plain Text
/starterkit reload

When to use:

  • After editing config.yml

  • After adding new items

  • After changing messages

  • After enabling/disabling the plugin

Example:

Plain Text
You: /starterkit reload
Server: [StarterKit] Configuration reloaded successfully!

What gets reloaded:

  • โœ… All kit items

  • โœ… Messages

  • โœ… Enabled/disabled status

  • โŒ Player data (data.yml) - not affected


Command 2: /starterkit reset <player>

Purpose: Remove a player from the database so they can receive the kit again

Permission: starterkit.admin

Usage:

Plain Text
/starterkit reset <playername>

Parameters:

  • <playername> - The exact username of the player

When to use:

  • Player accidentally lost their kit

  • You want to test the kit yourself

  • Punishment/reward system

  • Player requests a kit reset

Examples:

Reset online player:

Plain Text
You: /starterkit reset Steve
Server: [StarterKit] Steve's starter kit has been reset!

Reset offline player:

Plain Text
You: /starterkit reset Notch
Server: [StarterKit] Notch's starter kit has been reset!

Player not found:

Plain Text
You: /starterkit reset FakePlayer123
Server: [StarterKit] Player FakePlayer123 not found!

What happens:

  1. Playerโ€™s UUID is removed from data.yml

  2. Next time they join, theyโ€™ll automatically receive the kit

  3. Works for both online and offline players


Command 3: /starterkit give <player>

Purpose: Force give the starter kit to a player (bypasses first-join check)

Permission: starterkit.admin

Usage:

Plain Text
/starterkit give <playername>

Parameters:

  • <playername> - The exact username of the player (must be online)

When to use:

  • Give extra kits as rewards

  • Compensate for lost items

  • Testing purposes

  • Special events

Examples:

Give kit to online player:

Plain Text
You: /starterkit give Steve
Server: [StarterKit] Starter kit has been given to Steve!
(Steve receives all kit items immediately)

Player not online:

Plain Text
You: /starterkit give OfflinePlayer
Server: [StarterKit] Player OfflinePlayer is not online!

Important Notes:

  • Player MUST be online

  • Does NOT check if they already received it

  • Does NOT add them to the database

  • Items go directly to their inventory

  • If inventory is full, excess items drop on ground


๐Ÿ“‹ Permission Nodes

Permission
Description
Default
starterkit.admin
Access to all commands
OP only

Setting Up Permissions (LuckPerms Example)

Grant to a player:

Plain Text
/lp user Steve permission set starterkit.admin true

Grant to a group:

Plain Text
/lp group admin permission set starterkit.admin true

๐Ÿ” Troubleshooting

Problem: Kit not given on first join

Check:

  1. Is enabled: true in config.yml?

  2. Does player already exist in data.yml?

  3. Was playerโ€™s inventory full? (check for items on ground)

  4. Any errors in console?

Solution:

Plain Text
/starterkit reset <player>

Then have player rejoin.


Problem: Material not recognized

Example Error:

Plain Text
[WARN] [StarterKit] Unknown material: DIMAND_SWORD

Solution:

  • Check spelling in config.yml (itโ€™s DIAMOND_SWORD, not DIMAND_SWORD)

  • Use valid Minecraft material names

  • List of valid materials: Bukkit Materials


Problem: Colors not working

Wrong:

YAML
name: "ยงaGreen Name"  # Using ยง (section sign)

Correct:

YAML
name: "&aGreen Name"  # Using & (ampersand)

Problem: Items disappear when inventory is full

This is normal behavior. When a playerโ€™s inventory is full:

  • Items that donโ€™t fit will drop on the ground at their feet

  • Player must pick them up

Solutions:

  • Reduce number of kit items

  • Give smaller stack sizes

  • Warn new players to have empty inventory


Problem: Want to give different kits to different players

Current limitation: This plugin gives ONE kit to everyone.

Workarounds:

  1. Create multiple kit plugins with different configs

  2. Use /starterkit give manually for special players

  3. Consider using a permission-based kit plugin instead


๐Ÿ“Š Advanced Configuration

Multi-Line Lore Examples

YAML
epic-sword:
  material: "NETHERITE_SWORD"
  amount: 1
  name: "&5&lLegendary Blade"
  lore:
    - ""
    - "&7&oOnce wielded by heroes"
    - "&7&oof ancient times..."
    - ""
    - "&eAbility: &6Lightning Strike"
    - "&7Right-click to summon lightning"
    - ""
    - "&d&lLEGENDARY"

Empty Display Name

YAML
invisible-name:
  material: "STICK"
  amount: 1
  name: ""  # No name shown

No Lore

YAML
simple-item:
  material: "STONE"
  amount: 64
  # Just don't include 'lore:' section

๐ŸŽฎ Testing Your Kit

Quick Test Procedure

  1. Prepare:

    Plain Text
    /starterkit reload
    
  2. Reset yourself:

    Plain Text
    /starterkit reset YourUsername
    
  3. Clear inventory:

    Plain Text
    /clear @s
    
  4. Rejoin server or use:

    Plain Text
    /starterkit give YourUsername
    
  5. Check inventory - all kit items should appear


๐Ÿ’ก Tips & Best Practices

Doโ€™s โœ…

  • Always reload after editing config: /starterkit reload

  • Test kits on a test server first

  • Backup data.yml before manual edits

  • Use clear item names so players know what they got

  • Keep kits reasonable - donโ€™t give 64 diamonds

  • Use lore to explain special items

Donโ€™ts โŒ

  • Donโ€™t edit files while server is running (except with /reload)

  • Donโ€™t use invalid materials - check spelling

  • Donโ€™t exceed 64 for amount (Minecraft limit)

  • Donโ€™t manually edit data.yml unless you know what youโ€™re doing

  • Donโ€™t give OP items - ruins gameplay


๐Ÿ“ File Locations

Plain Text
server/
โ””โ”€โ”€ plugins/
    โ”œโ”€โ”€ StarterKit-1.0.jar          โ† The plugin file
    โ””โ”€โ”€ StarterKit/
        โ”œโ”€โ”€ config.yml               โ† Edit this to change kit
        โ””โ”€โ”€ data.yml                 โ† Player tracking (don't edit)

๐Ÿ”„ Updating the Plugin

  1. Stop server

  2. Backup plugins/StarterKit/ folder (saves config + data)

  3. Delete old StarterKit-1.0.jar

  4. Add new JAR file

  5. Start server

  6. Config and data files are preserved


๐Ÿ“ž Quick Reference Commands

Command
Purpose
Example
/starterkit reload
Reload config
/starterkit reload
/starterkit reset <player>
Reset playerโ€™s kit status
/starterkit reset Steve
/starterkit give <player>
Force give kit
/starterkit give Steve

๐ŸŽฏ Common Use Cases

New Server Setup

YAML
enabled: true
kit-items:
  starter-tools:
    material: "WOODEN_PICKAXE"
    amount: 1
  food:
    material: "BREAD"
    amount: 16

Skyblock Server

YAML
kit-items:
  lava-bucket:
    material: "LAVA_BUCKET"
    amount: 1
    name: "&cLava Bucket"
  ice:
    material: "ICE"
    amount: 2
  sapling:
    material: "OAK_SAPLING"
    amount: 1

PvP Arena

YAML
kit-items:
  iron-sword:
    material: "IRON_SWORD"
    amount: 1
  iron-armor-set:
    material: "IRON_CHESTPLATE"
    amount: 1
  steak:
    material: "COOKED_BEEF"
    amount: 64

Need more help? Check the server console for error messages - they usually tell you exactly whatโ€™s wrong!

flatfusion

Modify this Minecraft Spigot/Paper Java plugin to add an In-Game INVENTORY GUI (Inventory Menu) editor for server operators.

Requirements:

  1. Create an admin command, for example /starterkit edit, which opens a custom Chest INVENTORY GUI inventory menu.
  2. In this INVENTORY GUI, server operators can directly drag and drop ANY item from their inventory into the INVENTORY GUI slots to add them to the starter kit, or remove items directly from it.
  3. Add a "Save" button (like a green wool or emerald) inside the INVENTORY GUI. When clicked, it must automatically save the current items, their amounts, names, and custom data directly into the config.yml file.
  4. Players joining for the first time will automatically receive the exact items saved in this INVENTORY GUI, and they can only get it ONCE.
  5. Provide a full instruction guide on how to use this new In-Game INVENTORY GUI editor command and how everything works from A to Z.

Ensure it compiles successfully into a downloadable .jar file.

Kodari AI
KodariJun 8 at 12:27 pm 34

Iโ€™ll help you add a complete in-game GUI editor to the StarterKit plugin. Let me first examine the current plugin structure.

Perfect! Now Iโ€™ll add a complete GUI editor system to the StarterKit plugin. This will allow admins to visually configure the starter kit by dragging and dropping items.

Creating the GUI Framework

Creating the Kit Editor GUI

Updating the KitManager to Support Serialized Items

Updating the Main Plugin Class

Updating plugin.yml

Now let me create all the GUI framework files:

Perfect! Now letโ€™s verify the build works by compiling the plugin:

Let me create all the necessary Java files:

Perfect! Now letโ€™s create the comprehensive user guide:

[Generation stopped]

Kodari can make mistakes. Review important code before using.
Files
src
build.gradle
KIT_EDITOR_GUIDE.md
manifest.kod
plugin.yml
Code
15 1,363
src/main/java/com/starterkit/StarterKit.java
package com.starterkit;

import com.starterkit.listeners.JoinListener;
import com.starterkit.manager.DataManager;
import com.starterkit.manager.KitManager;
import com.starterkit.inventory.gui.GUIListener;
import com.starterkit.inventory.gui.GUIManager;
import com.starterkit.inventory.impl.KitEditorGUI;
import org.bukkit.Bukkit;
import org.bukkit.ChatColor;
import org.bukkit.command.Command;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
import org.bukkit.plugin.java.JavaPlugin;

public class StarterKit extends JavaPlugin {
    
    private KitManager kitManager;
    private DataManager dataManager;
    private GUIManager guiManager;
    
    @Override
    public void onEnable() {
        saveDefaultConfig();
        
        this.dataManager = new DataManager(this);
        this.dataManager.load();
        
        this.kitManager = new KitManager(this);
        
        this.guiManager = new GUIManager();
        
        Bukkit.getPluginManager().registerEvents(new JoinListener(this), this);
        Bukkit.getPluginManager().registerEvents(new GUIListener(guiManager), this);
        
        getLogger().info("StarterKit has been enabled!");
    }
    
    @Override
    public void onDisable() {
        if (this.dataManager != null) {
            this.dataManager.save();
        }
        getLogger().info("StarterKit has been disabled!");
    }
    
    @Override
    public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
        if (!command.getName().equalsIgnoreCase("starterkit")) {
            return false;
        }
        
        if (!sender.hasPermission("starterkit.admin")) {
            sender.sendMessage(colorize("&cYou don't have permission to use this command."));
            return true;
        }
        
        if (args.length == 0) {
            sender.sendMessage(colorize("&6&lStarter Kit Commands:"));
            sender.sendMessage(colorize("&e/starterkit reload &7- Reload configuration"));
            sender.sendMessage(colorize("&e/starterkit reset <player> &7- Reset a player's kit status"));
            sender.sendMessage(colorize("&e/starterkit give <player> &7- Force give kit to a player"));
            sender.sendMessage(colorize("&e/starterkit edit &7- Open GUI editor"));
            return true;
        }
        
        switch (args[0].toLowerCase()) {
            case "reload":
                reloadConfig();
                this.kitManager.reload();
                sender.sendMessage(colorize("&aConfiguration reloaded successfully!"));
                return true;
                
            case "reset":
                if (args.length < 2) {
                    sender.sendMessage(colorize("&cUsage: /starterkit reset <player>"));
                    return true;
                }
                Player targetReset = Bukkit.getPlayer(args[1]);
                if (targetReset == null) {
                    sender.sendMessage(colorize("&cPlayer not found!"));
                    return true;
                }
                this.dataManager.resetPlayer(targetReset.getUniqueId());
                sender.sendMessage(colorize("&aReset starter kit status for " + targetReset.getName()));
                return true;
                
            case "give":
                if (args.length < 2) {
                    sender.sendMessage(colorize("&cUsage: /starterkit give <player>"));
                    return true;
                }
                Player targetGive = Bukkit.getPlayer(args[1]);
                if (targetGive == null) {
                    sender.sendMessage(colorize("&cPlayer not found!"));
                    return true;
                }
                this.kitManager.giveKit(targetGive);
                this.dataManager.markAsReceived(targetGive.getUniqueId());
                sender.sendMessage(colorize("&aGave starter kit to " + targetGive.getName()));
                return true;
                
            case "edit":
                if (!(sender instanceof Player)) {
                    sender.sendMessage(colorize("&cOnly players can use this command!"));
                    return true;
                }
                Player player = (Player) sender;
                KitEditorGUI editorGUI = new KitEditorGUI(this);
                this.guiManager.openGUI(editorGUI, player);
                player.sendMessage(colorize("&aOpening kit editor..."));
                return true;
                
            default:
                sender.sendMessage(colorize("&cUnknown subcommand. Use /starterkit for help."));
                return true;
        }
    }
    
    public KitManager getKitManager() {
        return this.kitManager;
    }
    
    public DataManager getDataManager() {
        return this.dataManager;
    }
    
    public String colorize(String message) {
        return ChatColor.translateAlternateColorCodes('&', message);
    }
    
    public GUIManager getGuiManager() {
        return this.guiManager;
    }
}