IntelliJ survival guide

IntelliJ IDEA has hundreds of features, but you only need about a dozen to write plugins comfortably. This page teaches those: finding your way around the window, letting IntelliJ finish your code, fixing red errors with one key, reading Paper's own documentation, and running your test server. Learn these and the editor starts doing half the typing for you.

A tour of the window

Open any plugin project (File›Open, then pick the project's folder, the one that contains build.gradle.kts). The first time, IntelliJ may ask whether you trust the project; choose Trust Project, because Gradle needs to run to set it up. Wait for the progress bar at the bottom right to finish.

These are the parts you will use, and the keys that open them. Each tool window opens and closes with the same shortcut, and you can also click its icon on the window's edge.

For the rest of this page, open the practice project: download it, unzip it, and open the folder in IntelliJ. It is a small plugin with one listener, so you can try every shortcut on real plugin code. Here is the listener you will work on:

1package com.example.intellijtipspractice;2 13import org.bukkit.entity.Player;4import org.bukkit.event.EventHandler;5import org.bukkit.event.Listener;6import org.bukkit.event.player.PlayerJoinEvent;7 28public final class GiftListener implements Listener {9 10    @EventHandler311    public void onJoin(PlayerJoinEvent event) {12        Player player = event.getPlayer();413        player.sendRichMessage("<green>Welcome! <gray>A gift is waiting for you.");14    }15}

Autocomplete: let IntelliJ type for you

Autocomplete (IntelliJ calls it code completion) is the feature you will use most. As you type, IntelliJ shows a list of everything that fits at that spot. Pick an entry with the arrow keys and press Enter or Tab, and IntelliJ writes the full name, correctly spelled.

Type a dot to discover what something can do

This is the trick that makes the Paper API learnable. In onJoin, start a new line under the sendRichMessage line and type player. (with the dot). IntelliJ lists everything a Player can do: getHealth, setGameMode, teleport, giveExpLevels, hundreds of methods (the named actions an object can do). Keep typing to filter the list: player.give shows only the methods with "give" in them.

Each entry shows the method's name, the values it needs in brackets, and on the right what it gives back. You do not need to memorize the Paper API. You need to know which object to ask (the player, the event, the server), then type a dot and read.

• Ctrl+Space opens the list on purpose, for example when you closed it or want suggestions before typing anything.
• Ctrl+P, with the cursor inside a method's brackets, shows which values (parameters) that method expects, and highlights the one you are typing now.
• Ctrl+Q on a selected entry shows its documentation, so you can read what a method does before you pick it.

Autocomplete works for event names too. Type PlayerJoin in a method's brackets and IntelliJ offers PlayerJoinEvent, and when you pick it, it also adds the import line at the top of the file for you.

Red squiggles and Alt+Enter

IntelliJ checks your code while you type. When something is wrong, it underlines it:

• Red: an error. The plugin will not compile until you fix it.
• Yellow or gray: a warning or a suggestion. The code compiles, but something could be better, such as a variable you never use.
• Strikethrough (a line through a name): the method or class is deprecated, meaning there is a newer way and the old one may disappear. In Paper 26.3 you will see this on old tutorial code such as ChatColor. Use the modern way that this guide teaches.

Hover the underlined code to read the problem in a tooltip, or press F2 to jump to the next error in the file.

The magic key: Alt+Enter

Put the cursor on anything underlined and press Alt+Enter. IntelliJ shows a short list of quick fixes and, most of the time, the first one is exactly what you need. The three you will use constantly:

Here is the most common red error of all. This code uses Sound without importing it:

1player.giveExpLevels(5);2player.playSound(player, Sound.ENTITY_EXPERIENCE_ORB_PICKUP, 1.0f, 1.0f);

IntelliJ underlines Sound in red right away. If you build anyway, the compiler stops with this message:

> Task :compileJava FAILEDC:\Users\jacec\IdeaProjects\intellij-tips-practice\src\main\java\com\example\intellijtipspractice\GiftListener.java:15: error: cannot find symbol        player.playSound(player, Sound.ENTITY_EXPERIENCE_ORB_PICKUP, 1.0f, 1.0f);                                 ^  symbol:   variable Sound  location: class GiftListener1 errorFAILURE: Build failed with an exception.

"Cannot find symbol" means "I do not know this name". Either it is misspelled or it is not imported. Press Alt+Enter on Sound, choose Import class, and pick org.bukkit.Sound.

Navigation: read the API like a book

The best documentation for Paper is Paper's own code, and IntelliJ lets you jump straight into it.

When you Ctrl+click a Paper class, IntelliJ may first show a "decompiled" version, rebuilt from the compiled bytecode without any descriptions. If you see a banner at the top with Download Sources, click it: IntelliJ fetches the real Paper source code, with every description (called Javadoc) that the Paper developers wrote. Those descriptions are often the best explanation of a method anywhere.

Refactoring and tidying

Refactoring means changing how code is organized without changing what it does: renaming things, moving them, cleaning them up. IntelliJ does it safely, everywhere at once.

Gradle inside IntelliJ

IntelliJ reads your Gradle files to learn where the Paper API is and which Java to use. When you change a build file (build.gradle.kts, settings.gradle.kts or gradle.properties), IntelliJ does not reread it on its own. A small floating button with the Gradle elephant appears in the editor: click it, or press Ctrl+Shift+O, to load the Gradle changes.

The Gradle tool window (the elephant icon on the right) lists every task the project knows. The two you care about are Tasks > build > build (builds the jar) and Tasks > Run Paper > runServer (starts the test server). Double-click a task to run it. The reload button at the top of this window (two circling arrows) does the same as Ctrl+Shift+O.

When Gradle sync goes wrong

If every Paper name is suddenly red (JavaPlugin, Player, everything), IntelliJ has lost track of the Paper API. Work through these in order, and stop as soon as it is fixed:

1. Reload the Gradle project (Ctrl+Shift+O, or the reload button in the Gradle window) and read the Build window at the bottom. A real error there, such as a typo in build.gradle.kts or no internet connection, is the actual cause.
2. Check you opened the right folder: the one with build.gradle.kts in it, not its parent.
3. Check the Gradle JVM: File›Settings›Build, Execution, Deployment›Build Tools›Gradle, and set Gradle JVM to your Java 25.
4. As a last resort: File›Invalidate Caches..., tick nothing extra, and click Invalidate and Restart. IntelliJ throws away its memory of the project and rebuilds it. It takes a while, which is why it is the last step, not the first.

Run configurations: run and debug your server

A run configuration is a saved "what to run" choice. The guide's projects (and the paper-templates on Jace's PC) come with two, in the drop-down at the top right of the window:

• Run Paper Server runs the Gradle task runServer. It downloads Paper 26.3 the first time, builds your plugin, and starts a real server in the project's run folder with your plugin already installed. Join it from Minecraft 26.3 at localhost.
• Build Plugin Jar runs the Gradle task build. The jar lands in build\libs, ready to copy to another server.

Next to the drop-down are three buttons: the green arrow Run (Shift+F10), the bug Debug (Shift+F9) and the red square Stop (Ctrl+F2).

While the server runs, the Run window at the bottom is its console. You can type server commands there (without the slash), such as op Steve or plugins, and press Enter.

Debug starts the same server, but lets you pause your plugin at any line. Click in the gray margin left of a line number to set a red dot, a breakpoint, then join the server. When that line is about to run, the server pauses and IntelliJ shows every variable's value at that moment. It is the best way to understand why code does something unexpected. Debugging like a pro teaches it step by step.

Shortcut cheat sheet

All shortcuts are for Windows with IntelliJ's default keymap. If you forget one, press Ctrl+Shift+A (Find Action) and type what you want to do, such as Reload All Gradle Projects or Invalidate Caches; the shortcut is shown next to each result.

Common beginner traps

Editing files outside src/main

Your plugin is made only from what is inside src/main. Two other folders look tempting but are generated:

• build is Gradle's output. Anything you change there is overwritten by the next build.
• run is the test server. Its plugins folder holds a copy of your plugin's files. If your plugin saves a config.yml, the server's copy lives in run\plugins\YourPlugin\config.yml. Editing the one in src/main/resources later does not change that copy, because a plugin only writes its default config when none exists yet. Delete the server's copy to get the new default.

Wrong JDK selected

If IntelliJ complains about the Java version ("release version 25 not supported", or modern Java code underlined in red although it builds fine with Gradle), check two settings:

• File›Project Structure›Project: SDK should be a Java 25 JDK (IntelliJ calls a JDK an SDK, software development kit). If 25 is not in the list, choose Add SDK > JDK and pick the Temurin 25 folder.
• File›Settings›Build, Execution, Deployment›Build Tools›Gradle: Gradle JVM should be Java 25 too.

Files not saved

IntelliJ saves automatically: when you run something, switch to another program, or after a short pause. So you rarely need Ctrl+S. The trap is the other direction: if you edit a project file in another program (Notepad, File Explorer), IntelliJ may still show the old version for a moment. Edit project files in IntelliJ only, and if you did change something outside, use File›Reload All from Disk.

plugin.yml in the wrong folder

The server only finds plugin.yml if it ends up at the top of the jar, and it only gets there from src/main/resources:

With plugin.yml anywhere else, the server refuses to load the jar with an error that it does not contain a plugin.yml. To be sure, right-click src/main/resources in the project tree and create the file there with New›File.

Opening the wrong folder

If you open a folder that contains several projects (for example all of paper-templates, or your whole IdeaProjects), IntelliJ does not find a build.gradle.kts at the top, so nothing gets set up and all the code stays red. Close it with File›Close Project and open the single project folder instead.

1package com.example.intellijtipsexercise;2 13import org.bukkit.Sound;4import org.bukkit.entity.Player;5import org.bukkit.event.EventHandler;6import org.bukkit.event.Listener;7import org.bukkit.event.player.PlayerJoinEvent;8 9public final class GiftListener implements Listener {10 11    @EventHandler12    public void onJoin(PlayerJoinEvent event) {13        Player player = event.getPlayer();14        player.sendRichMessage("<green>Welcome! <gray>A gift is waiting for you.");215        player.giveExpLevels(5);316        player.playSound(player, Sound.ENTITY_EXPERIENCE_ORB_PICKUP, 1.0f, 1.0f);417        player.sendRichMessage("<gold>You received 5 experience levels!");18    }19}

Recap

• Know the window: project tree (Alt+1), editor, run toolbar, Run window (Alt+4), Gradle window, terminal (Alt+F12), Problems (Alt+6).
• Type an object and a dot to see everything it can do; Ctrl+Space and Ctrl+P help further.
• Red means error. Alt+Enter fixes most of them, especially missing imports; check you picked the right package.
• Ctrl+click opens the Paper source and its descriptions; Ctrl+Q shows them in a popup.
• Rename with Shift+F6 (then check plugin.yml), tidy with Ctrl+Alt+L and Ctrl+Alt+O.
• Load Gradle changes after editing build files; Invalidate Caches is the last resort.
• Run Paper Server starts a test server with your plugin; stop it by typing stop. Debug lets you pause at breakpoints.
• Only edit files in src/main, keep plugin.yml in src/main/resources, and use Java 25 as the project SDK and Gradle JVM.

Quick quiz

Next steps

• Your first plugin, step by step: use everything from this page to write and run your first plugin.
• Anatomy of a plugin project: what every file in the project tree is for.