Tutorials
An ongoing, concept-first series on Spigot and Paper plugin development — one API concept per lesson, each with a companion video.
This is an ongoing series, not a finished course. Every lesson teaches one Spigot or Paper API concept, with a small snippet you can drop into a plugin you already have.
:::note A new doc is published each time a new video goes live — the written lesson and the video arrive together. The roadmap below fills in as the series progresses. :::
Follow along
Each lesson ships with a companion video on YouTube. Subscribe to catch the next one:
Watch the series on YouTube →How the series works
- One concept per lesson. If a topic needs two ideas, it becomes two lessons.
- No project scaffolding. No Gradle walkthroughs, no "now add a second class" detours. You add one feature and see it work.
- Each lesson ends with an exercise. The point is to change the code, not to read it.
- Every idea includes its failure mode — the bug you will actually hit, and why.
What's coming
The series runs 25 lessons across five parts.
Part 1 — Foundations
What a plugin is made of, before any gameplay APIs.
- What a Plugin Actually Is — a jar the server loads, and
plugin.ymlas its manifest - Your Main Class — extending
JavaPlugin, and whatonEnableandonDisableare for - One Instance, Many Callers — the plugin as a singleton, and state that belongs to it
- Logging Instead of Println —
getLogger(), log levels, and output you can actually find - Reading plugin.yml Properly —
main,api-version,dependvssoftdepend
Part 2 — Events
The mechanism behind almost every plugin feature.
- What an Event Is — the event bus, and who fires what
- Writing a Listener —
Listener,@EventHandler, and registering it - Reading Event Data — event getters,
getPlayer(), and what is safe to change - Cancelling Events —
Cancellable,setCancelled, and events where it does nothing - Event Priority — the six priorities, and why
MONITORmust not modify anything - Async Events and Threads — what "async" forbids, and how to get back to the main thread
Part 3 — Commands, Permissions, Messages
- Declaring Commands — names, aliases, usage, and permissions in
plugin.yml - Handling a Command —
CommandExecutor, theargsarray, and the return value - Tab Completion —
TabCompleter, and suggestions that match the typed argument - Permissions — permission nodes,
hasPermission, and why op is not a permission - Sending Messages —
sendMessage, legacy color codes vs Adventure components
Part 4 — Game Objects
- The Player Object — the
Playerinterface and the getters you will use daily - ItemStack Basics — materials, amounts, and why stacks are shared and mutable
- Item Meta — display names, lore, enchantments, unbreakable items
- Inventories and GUIs — creating a menu, opening it, and reading clicks
- Locations, Blocks, Worlds — coordinates with a world attached, and chunk boundaries
- Feedback: Sounds and Particles — confirming an action without spamming chat
Part 5 — Time and State
- Scheduling Tasks — delayed, repeating, and async tasks, and how to cancel them
- Saving Data —
PersistentDataContainervs YAML files, and when each is right - Organizing Without a Framework — packages, managers, and config holders
Looking for the old tutorials?
The previous 313 project-based tutorials have been retired. They remain in the repository under archive/tutorials/ but are no longer published.
Press ⌘ + K to search the site.