Skip to content

Documenting event system and world multithreading. General improvements. #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Janmm14 wants to merge 15 commits into
base: master
Choose a base branch
from
Open

Documenting event system and world multithreading. General improvements. #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
ee10602
Start documenting event system
Janmm14 Dec 5, 2020
9ba61a1
Small fixes based on omniboy's feedback
Janmm14 Dec 5, 2020
77f6b6c
wip
Janmm14 Feb 13, 2021
1b244d6
Create plugin-world-restriction.md
Janmm14 Feb 14, 2021
5b82c15
Update getting-started.md
Janmm14 Feb 14, 2021
276a7a7
Update getting-started.md
Janmm14 Feb 14, 2021
6a3b164
Update creating-a-first-plugin.md
Janmm14 Feb 14, 2021
44e3ca3
Update creating-your-first-event-listener.md
Janmm14 Feb 14, 2021
747cff8
Update creating-your-first-event-listener.md
Janmm14 Feb 14, 2021
ee19ef9
Merge branch 'master' into patch-1
Janmm14 Feb 14, 2021
0485895
Update creating-your-first-event-listener.md
Janmm14 Feb 14, 2021
2962656
Update creating-your-first-command.md
Janmm14 Feb 14, 2021
c591e03
stuff
Janmm14 Feb 15, 2021
36d2848
ignore intellij idea files
Janmm14 Feb 15, 2021
6549b73
Update documentation to latest changes in world multithreading PR.
Janmm14 Mar 1, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,6 @@
npm-debug.log*
yarn-debug.log*
yarn-error.log*

.idea/
*.iml
11 changes: 0 additions & 11 deletions docs/api/api-creating-a-first-plugin.md
View file
Open in desktop

This file was deleted.

32 changes: 0 additions & 32 deletions docs/api/api-getting-started.md
View file
Open in desktop

This file was deleted.

157 changes: 39 additions & 118 deletions docs/development/creating-a-first-plugin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,126 +6,28 @@ sidebar_label: Creating Your First Plugin

## Prerequisites

1. Follow the ["API Getting Started" guide](/docs/api/api-getting-started) and
install the API into your classpath.
2. An understanding of the Java programming language is necessary.
3. A test plugin has been created in the GoMint repository and can be browsed [here](https://github.com/gomint/GoMint/tree/master/gomint-test-plugin/src/main/java/io/gomint/testplugin) for another example of what we will be creating.

### pom.xml Setup

Before you begin writing a plugin, you will need a ```pom.xml``` for the plugin. It is pertinent that this file be included.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<!-- Here is where you will substitute your plugin's information -->
<groupId>io.gomint.testplugin</groupId>
<artifactId>gomint-testplugin</artifactId>
<version>1.0-SNAPSHOT</version>

<!-- Here is where you will substitute your plugin's name and description -->
<name>GoMint Test Plugin</name>
<description>A plugin to test and see GoMint's API design</description>

<dependencies>
<!-- This is the GoMint API Maven Library which is necessary to create a plugin -->
<dependency>
<groupId>io.gomint</groupId>
<artifactId>gomint-api</artifactId>
<version>1.0.0-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
</dependencies>

<build>
<resources>
<resource>
<directory>${pom.basedir}/src/main/resources</directory>
<filtering>true</filtering>
<includes>
<include>*.*</include>
</includes>
</resource>
</resources>

<!-- Needed for GoMint to load plugin external dependencies -->
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.1.2</version>
<executions>
<execution>
<id>copy-dependencies-netty-codecs</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-dependencies</goal>
</goals>
<configuration>
<includeArtifactIds>netty-codec-http,netty-codec-http2,netty-handler-proxy</includeArtifactIds>
<outputDirectory>${project.build.directory}/classes/dependency</outputDirectory>
</configuration>
</execution>
<execution>
<id>copy-dependencies-discord</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-dependencies</goal>
</goals>
<configuration>
<excludeScope>provided</excludeScope>
<excludeGroupIds>io.netty</excludeGroupIds>
<outputDirectory>${project.build.directory}/classes/dependency</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>

<!-- Include the snapshot repository we are currently on for latest master builds -->
<repositories>
<repository>
<id>central</id>
<url>https://repo1.maven.org/maven2</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
<repository>
<id>ossrh</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
<releases>
<enabled>true</enabled>
</releases>
</repository>
</repositories>
</project>
```
1. An understanding of the Java programming language is necessary.
2. Follow the [Getting Started guide](getting-started.md) to set up the project in your Java IDE (like IntelliJ IDEA or Eclipse).

A test plugin has been created in the GoMint repository and can be browsed [here](https://github.com/gomint/GoMint/tree/master/gomint-test-plugin/src/main/java/io/gomint/testplugin) for another example of what we will be creating.

## Step One - The ```Plugin``` Type

All plugins for the GoMint server contain a class extending ```io.gomint.plugin.Plugin```
All plugins for the GoMint server contain a class extending [```io.gomint.plugin.Plugin```](https://janmm14.de/static/gomint/index.html?gomint.api/io/gomint/plugin/Plugin.html)
where the initialization and cleanup of the plugin will take place, as well as the
registration of event handlers, new logic, etc. In lieu of a ```main()``` method, the plugin management system handles the initialization of plugins, so it is important that the annotations and types are setup correctly.

:::info
The class in your plugin extending `Plugin` is often also referred to as *main class* of your plugin.
:::

```java
package me.plugincrafter.demo;

import io.gomint.plugin.Plugin;

// The class MUST extend Plugin. It is common for new users to write
// 'JavaPlugin', as they are coming from Bukkit/Spigot.
// 'JavaPlugin', as they are coming from Bukkit/Spigot, but here it is just 'Plugin'.
public class TestPlugin extends Plugin {}
```

Expand All @@ -135,11 +37,11 @@ Rather than use a configuration file that is packed into the JAR file to describ

Annotations:

| Annotation | Type | Value | See Also |
|------------|-----------------|---------------------------|---------------------------------------------------------------------------------------|
| PluginName | String | Your plugin's name | |
| Version | int, int | ```major```, ```minor``` | |
| Startup | StartupPriority | See Enums | [JavaDoc](https://janmm14.de/static/gomint/index.html?gomint.api/module-summary.html) |
| Annotation | Type | Value |
|------------|-----------------|---------------------------------------------------------------------------------------------------------------------|
| PluginName | String | Your plugin's name |
| Version | int, int | ```major```, ```minor``` |
| Startup | StartupPriority | See Enum in [JavaDoc](https://janmm14.de/static/gomint/index.html?gomint.api/io/gomint/plugin/StartupPriority.html) |

```java
package me.plugincrafter.demo;
Expand All @@ -156,21 +58,40 @@ import io.gomint.plugin.Version;
public class TestPlugin extends Plugin {}
```

## Step Three - GoMint API philosophies and differences to other server software

GoMint is one of the first Minecraft server softwares which have built in world multithreading - each world has its own main thread.
This means that many actions to worlds and entites need to run in the world's thread.

Additionally GoMint provides easy-to-use API for plugins to handle the world multithreading and [restrict plugins to certain worlds](../get-started/plugin-world-restriction.md), which **every** plugin should obey to.

## ```Plugin``` Available Methods

The following methods are inherited from ```Plugin``` and can be used to install event handlers, listeners, and setup your plugin:
The following methods are inherited from [```Plugin```](https://janmm14.de/static/gomint/index.html?gomint.api/io/gomint/plugin/Plugin.html) and can be used to install event handlers, listeners, and setup your plugin:

* ```onInstall()``` - Invoked when the plugin enters the runtime stage.
* ```onStartup()``` - Invoked when the plugin has been installed.
* ```onUninstall()``` - Invoked when the plugin has been uninstalled.
* ```onInstall()``` - Invoked when the plugin enters the runtime stage. Meant to be overriden.
* ```onUninstall()``` - Invoked when the plugin has been uninstalled. Meant to be overriden.
* ```onStartup()``` - Invoked when the plugin has been installed. Can be overridden if needed.
* ```isInstalled()``` - Can be invoked to determine if the plugin has been installed yet.
* ```registerCommand(io.gomint.command.Command)``` - Invoke to register your own commands.
* ```registerListener(io.gomint.event.EventListener)``` - Invoke to register your own event listeners.
* ```registerActiveWorldsListener(io.gomint.event.EventListener)``` - Invoke to register your own event listeners, limited to the [worlds your plugin should be active in](../get-started/plugin-world-restriction.md).
* ```registerListener(io.gomint.event.EventListener)``` - Invoke to register your own global event listeners.
* ```registerListener(io.gomint.event.EventListener, Predicate<io.gomint.event.Event>)``` - Invoke to register your own custom-limited event listeners.
* ```unregisterListener(io.gomint.event.EventListener)``` - Invoke to remove an event listener.
* ```activeInWorld(io.gomint.world.World)``` - Returns whether the plugin should be active in the given world.
* ```eventInActiveWorlds(io.gomint.event.Event)``` - Returns whether the plugin should be active in the given world.
* ```activeWorldsSnapshot()``` - Returns a set of _currently_ loaded worlds where the plugin should be active in. Do **not** save it for later use.
* ```activeWorldsPlayers()``` - Returns a set of players in your plugin's active worlds
* ```activeWorldsPlayers(Consumer<io.gomint.entity.EntityPlayer>)``` - Calls the given consumer for every player in your plugin's active worlds on the world's thread
* ```dataFolder()``` - Returns the data folder for this plugin as a File object.
* ```pluginManager()``` - Returns the plugin manager of the GoMint server.
* ```name() ``` - Returns the name of this plugin.
* ```version()``` - Returns the version of this plugin.
* ```logger()``` - Returns the Logger of this plugin.
* ```scheduler()``` - Returns the plugin scheduler.
* ```server()``` - Returns an instance of the GoMint server.

## Next up

[Create your first command](creating-your-first-command.md)
[Create your first event listener](creating-your-first-event-listener.md)
Loading