SmeltStack Docs

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.

  1. What a Plugin Actually Is — a jar the server loads, and plugin.yml as its manifest
  2. Your Main Class — extending JavaPlugin, and what onEnable and onDisable are for
  3. One Instance, Many Callers — the plugin as a singleton, and state that belongs to it
  4. Logging Instead of Println — getLogger(), log levels, and output you can actually find
  5. Reading plugin.yml Properly — main, api-version, depend vs softdepend

Part 2 — Events

The mechanism behind almost every plugin feature.

  1. What an Event Is — the event bus, and who fires what
  2. Writing a Listener — Listener, @EventHandler, and registering it
  3. Reading Event Data — event getters, getPlayer(), and what is safe to change
  4. Cancelling Events — Cancellable, setCancelled, and events where it does nothing
  5. Event Priority — the six priorities, and why MONITOR must not modify anything
  6. Async Events and Threads — what "async" forbids, and how to get back to the main thread

Part 3 — Commands, Permissions, Messages

  1. Declaring Commands — names, aliases, usage, and permissions in plugin.yml
  2. Handling a Command — CommandExecutor, the args array, and the return value
  3. Tab Completion — TabCompleter, and suggestions that match the typed argument
  4. Permissions — permission nodes, hasPermission, and why op is not a permission
  5. Sending Messages — sendMessage, legacy color codes vs Adventure components

Part 4 — Game Objects

  1. The Player Object — the Player interface and the getters you will use daily
  2. ItemStack Basics — materials, amounts, and why stacks are shared and mutable
  3. Item Meta — display names, lore, enchantments, unbreakable items
  4. Inventories and GUIs — creating a menu, opening it, and reading clicks
  5. Locations, Blocks, Worlds — coordinates with a world attached, and chunk boundaries
  6. Feedback: Sounds and Particles — confirming an action without spamming chat

Part 5 — Time and State

  1. Scheduling Tasks — delayed, repeating, and async tasks, and how to cancel them
  2. Saving Data — PersistentDataContainer vs YAML files, and when each is right
  3. 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.

On this page