For Paper 26.3 and Java 25
Learn to code Minecraft plugins, one line at a time.
A beginner's guide to Java and Paper plugins. Every example compiles on a real Paper 26.3 API, runs on your PC, and explains itself word by word.
Hover any word in the code to see what it does. Click it to pin the explanation.
Where this file livesevents-first-listenersrcmainjavacomexampleeventsfirstlistenerWelcomeListener.java
The package com.example.eventsfirstlistener is the folder path com/example/eventsfirstlistener inside src/main/java: every dot in the package name is one folder. IntelliJ creates these folders for you when you make a new package.
- events-first-listener/
- src/main/
- java/com/example/eventsfirstlistener/Package com.example.eventsfirstlistener
- FirstListenerPlugin.javaMain class: Paper starts here (named as main in plugin.yml)
- WelcomeListener.javayou are hereListener: reacts to events
- resources/Files copied into the jar as they are
- plugin.ymlTells Paper the plugin's name, version and main class
- java/com/example/eventsfirstlistener/Package com.example.eventsfirstlistener
- build.gradle.ktsThe build recipe: Paper 26.3 API, Java 25, how the jar is made
- gradle.propertiesVersion numbers used by the build
- gradlew.batRuns Gradle on Windows without installing it
- settings.gradle.ktsThe project's name
- src/main/
Gray files come with the project template; you rarely edit them. Open the whole project in the Compile Lab, or download it from the project page.
10@EventHandler11public void onJoin(PlayerJoinEvent event) {12 Player player = event.getPlayer();13 player.sendRichMessage("<green>Welcome to the server!");14}When Steve joins the server, he sees:
Welcome to the server!
Your path
Work through the parts in order, or jump to what you need. Mark pages as done to earn XP and level up, the same way Minecraft counts experience.
Tools for when you are stuck
Describe an idea, paste code you do not understand, or paste an error. These tools answer in plain English and point you to the right chapter.
- Plugin Idea ClassifierDescribe a plugin in your own words and get the events, API pieces, chapters and starter code it needs.
- Code ExplainerPaste any Java or Paper code and read what every line does.
- Error DoctorPaste a console error or build failure and get the cause and the fix.
- Event FinderSearch all 465 Paper events in plain English, with listener code to copy.
- Names LookupExact names for materials, sounds, particles, mobs, effects and more.
- MiniMessage StudioType colored text and see it the way players will see it in chat.
- Compile LabEdit any example plugin in the browser and compile it against Paper 26.3.
- Test ServerStart a real Paper server with the guide's plugins and use its console here.
- plugin.yml BuilderFill in a form and get a valid plugin.yml.
- Tick CalculatorTurn seconds into ticks and get the scheduler code.
Practice by writing plugins
Reading is not enough. The Practice Arena gives you small plugin tasks with real tests: greet a player, cancel a block break, write a /heal command. Write the code in your browser, press Check, and see exactly what works and what does not.
Open the Practice ArenaRun code for real
Opened as plain files, the guide shows the output each example produced when it was built. To run your own edits, compile plugins and check practice challenges, start the guide in live mode:
- Open the Paper Plugin Guide folder on your Desktop.
- Double-click
Start Guide.cmd. It finds Java 25 and opens the guide in your browser. - The badge at the top right changes from File mode to Live. Keep the black window open while you learn; close it when you are done.