Отладка плагина

When bugs in your plugin’s code are hard to pinpoint, you are tired of recompiling after every single change and logger outputs are cluttering your code, debugging can be very tedious. Therefore, this section will explain how to set up your plugin to utilize Java’s debugging capabilities.

Подготовка рабочего пространства

Since we will be running both Sponge and your plugin from within your IDE, you’ll need to import either SpongeForge or SpongeVanilla, depending on which you want to use, as a project into your workspace. The instructions to do so are found on the respective project’s GitHub page. Follow those instructions carefully before proceeding here.

Now you need to make sure your plugin project is visible to the SpongeForge/SpongeVanilla project you just created. The steps necessary depend on your IDE.

Intellij IDEA

In IntelliJ, every project has its own workspace(s). To make your project visible to the Sponge(Vanilla) project, it needs to be a Module. Assuming you already created your project as described in Настройка IntelliJ IDEA, import it using the following steps.

  • Откройте проект SpongeVanilla/SpongeForge.

  • Нажмите File, затем New, далее Module from Existing Sources....

  • Перейдите в папку вашего проекта с плагином.

    • Если вы используете Gradle, выберите файл build.gradle и в следующем диалоговом окне поставьте галочку Use auto-import и подтвердите.

    • В противном случае выберите весь каталог и нажмите Finish.

  • Нажмите Finish.

Совет

Если вы ещё не создали плагин, вместо Module from Existing Sources... нажмите Module..., после чего в следующем диалоговом окне создайте проект.

Eclipse

Просто создайте свой проект, как описано здесь: Настройка Eclipse. Пока он находится в том же рабочем пространстве, что и ваш SpongeVanilla/SpongeForge проект, он будет виден.

Adding Plugin to Sponge classpath

The idea behind this is that we’ll launch Sponge from within your IDE, like normal. However, the difference is that we’ll be adding your plugin to the classpath. Since Sponge will per default load all plugins found in the classpath, adding the plugin project to Sponge’s classpath will rid you of the necessity to rebuild and copy the artifact file into your server directory after every change.

Сначала убедитесь, что вы надлежащим образом установили вашу(и) конфигурацию(и) Run/Debug, как показано в проекте Sponge README.md

Then you’ll need to edit that Run/Debug Configuration so that it will include your project on the class path. How to do this, depends on your IDE again:

Intellij IDEA

  • Откройте структуру проекта.

    • Нажмите File, затем Project Structure....

    • ИЛИ щёлкните по значку Project Structure в верхнем правом углу IDE рядом со значком поиска.

  • Click Modules. Expand the SpongeForge or SpongeVanilla group (depending on what you chose).

  • Make sure SpongeForge_main or SpongeVanilla_main is selected.

  • On the right column, select the Dependencies tab.

  • Click the + symbol (Add) on the bottom of the column, and select Module Dependency.

  • Выберите yourplugin_main.

  • Do NOT check the Export option on the module, after it is added to the list.

Предупреждение

Due to a bug in IntelliJ (IDEA-194641), any dependencies that your plugin has (e.g. the Kotlin standard library, or Gson) will not be added to the classpath using the above method. This results in a ClassNotFoundException when your plugin tries to access one of these classes, even though it successfully compiled against that class.

This issue only affects running your plugin from IntelliJ as a module. Your final built plugin jar will run normally in both IntelliJ and a production server.

If your plugin has external dependencies, you’ll need to follow these steps in order to run it directly from IntelliJ:

  • Create a new Java module with File -> New -> Module.... Name it SpongeForgeContainer.

  • Open the module settings for SpongeForgeContainer as described above

  • In the dependency settings for SpongeForgeContainer, add a module dependency on SpongeForge_main

  • Edit your server run configuration. Change Use classpath of module: from SpongeForge_main to SpongeForgeContainer

You can leave all of your settings unchanged, including SpongeForge_main’s dependency on your plugin module. Now, all of your plugin’s dependencies should be added to the classpath when you run the server.

Eclipse

  • Find your Run/Debug Configuration

    • Нажмите Run, затем Run Configurations...

    • OR, click the drop-down arrow beside the Run/Debug icons and then Run Configurations... or Debug Configurations..., respectively.

  • Select your Run/Debug Configuration for Sponge (Server) on the left side.

  • Switch to the Classpath tab.

  • Select User Entries, followed by the Add Projects... button.

  • Выберите подходящий проект для вашего плагина.

  • Нажмите кнопку OK.

  • Нажмите кнопку Apply в правом нижнем углу.

Running the Configuration

After you’ve followed the previous steps, you should be ready to start debugging. If you start your server from your IDE, its working directory will be the run directory in your SpongeForge/SpongeVanilla project. All the files usually created by a server (worlds, configs etc.) will be stored in that run directory and persist over multiple runs of your local test server, just as if you manually copied a server .jar to the run directory and started it from there.

Intellij IDEA

Rather than pressing the Green right-pointing arrow to run your Run/Debug configuration, click the Green icon to the right of it, Debug.

Eclipse

Rather than pressing the green right-pointing arrow to run your Run/Debug configuration, click the drop-down arrow of the Debug icon (the one displaying a bug) and click your Test (Server) configuration. If it doesn’t appear in the drop-down menu, click Debug Configurations. Select Test (Server) configuration and hit the Debug button on the bottom left.

Using the Debugger

Now that your server (and your Plugin) are running in the Debugger, you can make use of the features it holds. The most prominently used are explained below in short, though they are not features of Sponge, but the Java Debugger your IDE makes use of.

Контрольные точки

Контрольные точки - это полезный инструмент для внимательного рассмотрения кода. Контрольную точку можно устанавливать в начале строки кода или функции. При достижении контрольной точки, отладчик остановит исполнение кода и ваш IDE откроет вам окно, позволяющее наблюдать за содержанием всех переменных в текущей области. Исполнение кода не возобновится, пока вы не нажмёте соответствующую клавишу в вашем IDE-окне отладки.

Контрольные точки также можно добавлять, удалять или временно отключать во время работы отладки.

Совет

Once a single server tick takes more than a given amount of time, the watchdog will consider the server crashed and forcefully shut it down. When working with breakpoints this might occur, so it is recommended that you edit your test environments server.properties file and set the value of max-tick-time to either a very large number (the amount of milliseconds a tick may take) or -1 (to disable the Watchdog completely).

Intellij IDEA

Чтобы добавить или удалить контрольную точку, просто нажмите левой клавишей на пустом пространстве слева от редактора.

Или когда ваш курсор находится на строке, в которую вы хотите добавить или удалить контрольную точку, нажмите на Run, а потом на Toggle Line Breakpoint.

Eclipse

Чтобы добавить или удалить контрольную точку, нажмите правой клавишей на пустом пространстве слева от вашего редактора и нажмите Toggle Breakpoint.

Или когда курсор находится на строке, в которую вы хотите добавить или убрать контрольную точку, нажмите на Run, а потом на Toggle Breakpoint.

Code Hotswapping

The other major feat of the debugger is that you will not have to restart your server for every small change you make, thanks to code hotswapping. This means that you can just recompile portions of your code while it is running in the debugger. However, there are a couple of limitations, the most important of which are:

  • You cannot create or remove methods.

    • Changes to methods are limited to code within the method. You cannot modify its signature (that means its name, return type and parameter types)

  • You cannot remove classes.

    • You cannot modify a class“ name, superclass or the list of interfaces it implements.

    • You can add classes. However, once it’s been built and hotswapped, the class follows the above rules.

You can test this functionality: Introduce a simple command to your plugin that just writes a word, like Sponge Then save it and start the server as described above. Run the command. It will output Sponge. Now change the command to write a different word to console, save the file. After a change, do as follows to hotswap the changes to the running program:

Intellij IDEA

  • Open the Run menu, from the top of the IDE.

  • Below the first category break, click Reload Changed Classes.

Eclipse

No action needed. As soon as you save the file, it will be rebuilt and automatically hotswapped with the currently running debug. Unless you changed this particular default behavior, you will not have to trigger a manual hotswap.