Skip to content

Commit 178401e

Browse files
Alemiz112Alemiz112
committed
Improve the content
1 parent 953dbe1 commit 178401e

21 files changed

Lines changed: 1543 additions & 444 deletions

‎docs/.vitepress/config.js‎

Lines changed: 22 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -66,18 +66,20 @@ export default defineConfig({
6666
text: 'Entry Level Plugin API Guide',
6767
link: '/entry-level-plugin-api-guide/prerequisites',
6868
},
69-
{ text: 'Plugins', link: '/plugins/introduction' },
69+
{ text: 'Plugin API', link: '/plugins/introduction' },
7070
{
7171
text: 'Integration',
7272
link: '/integration/integrating-with-slappers-npcs',
7373
},
7474
],
7575
},
7676
{
77-
text: 'StarGate Guides',
77+
text: 'Suggested Plugins & Extensions',
7878
items: [
79-
{ text: 'StarGate Commons', link: '/stargate-commons/stargate-modules' },
80-
{ text: 'StarGate Plugins', link: '/stargate-plugins/server-setup' },
79+
{ text: 'Introduction', link: '/extensions/introduction' },
80+
{ text: 'StarGate Modules', link: '/stargate-commons/stargate-modules' },
81+
{ text: 'StarGate: Server Setup', link: '/stargate-plugins/server-setup' },
82+
{ text: 'StarGate: Client Setup', link: '/stargate-plugins/client-setup' },
8183
],
8284
},
8385
{ text: 'Main Site', link: 'https://waterdog.dev' },
@@ -101,18 +103,20 @@ export default defineConfig({
101103
items: [
102104
{ text: 'Prerequisites', link: '/entry-level-plugin-api-guide/prerequisites' },
103105
{ text: 'Maven Setup', link: '/entry-level-plugin-api-guide/maven-setup' },
106+
{ text: 'Your First Plugin', link: '/entry-level-plugin-api-guide/first-plugin' },
104107
],
105108
},
106109
{
107-
text: 'Plugins',
110+
text: 'Plugin API',
108111
collapsed: false,
109112
items: [
110113
{ text: 'Introduction', link: '/plugins/introduction' },
114+
{ text: 'Working with Players', link: '/plugins/players-guide' },
111115
{ text: 'Commands Guide', link: '/plugins/commands-guide' },
112116
{ text: 'Events Guide', link: '/plugins/events-guide' },
113117
{ text: 'Fallback & Join Handler', link: '/plugins/fallback-join-handler' },
118+
{ text: 'Scheduling Tasks', link: '/plugins/scheduling-task' },
114119
{ text: 'Proxy Communication', link: '/plugins/proxy-communication' },
115-
{ text: 'Scheduling Task', link: '/plugins/scheduling-task' },
116120
],
117121
},
118122
{
@@ -126,18 +130,19 @@ export default defineConfig({
126130
],
127131
},
128132
{
129-
text: 'StarGate Commons',
130-
collapsed: true,
131-
items: [
132-
{ text: 'StarGate Modules', link: '/stargate-commons/stargate-modules' },
133-
],
134-
},
135-
{
136-
text: 'StarGate Plugins',
137-
collapsed: true,
133+
text: 'Suggested Plugins & Extensions',
134+
collapsed: false,
138135
items: [
139-
{ text: 'Server Setup', link: '/stargate-plugins/server-setup' },
140-
{ text: 'Client Setup', link: '/stargate-plugins/client-setup' },
136+
{ text: 'Introduction', link: '/extensions/introduction' },
137+
{
138+
text: 'StarGate',
139+
collapsed: true,
140+
items: [
141+
{ text: 'StarGate Modules', link: '/stargate-commons/stargate-modules' },
142+
{ text: 'Server Setup', link: '/stargate-plugins/server-setup' },
143+
{ text: 'Client Setup', link: '/stargate-plugins/client-setup' },
144+
],
145+
},
141146
],
142147
},
143148
],

‎docs/entry-level-plugin-api-guide/first-plugin.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: Your First Plugin
3+
---
4+
5+
# Your First Plugin
6+
7+
With the [Maven project set up](./maven-setup), you can now write a real plugin.
8+
This page builds the smallest plugin that does something, and explains every
9+
piece so you understand *why* it works.
10+
11+
## The main class
12+
13+
Every plugin has one **main class** that extends
14+
`dev.waterdog.waterdogpe.plugin.Plugin`. The proxy creates one instance of it
15+
and calls its lifecycle methods.
16+
17+
Create `src/main/java/com/example/myplugin/MyPlugin.java`:
18+
19+
```java
20+
package com.example.myplugin;
21+
22+
import dev.waterdog.waterdogpe.plugin.Plugin;
23+
24+
public class MyPlugin extends Plugin {
25+
26+
@Override
27+
public void onEnable() {
28+
// Called when the proxy enables your plugin. Put your setup here:
29+
// register commands, subscribe to events, start tasks, etc.
30+
this.getLogger().info("MyPlugin has been enabled!");
31+
}
32+
33+
@Override
34+
public void onDisable() {
35+
// Called on proxy shutdown or when the plugin is disabled.
36+
// Clean up here: close connections, save data, cancel tasks.
37+
this.getLogger().info("MyPlugin has been disabled!");
38+
}
39+
}
40+
```
41+
42+
### The plugin lifecycle
43+
44+
The `Plugin` class gives you three methods you can override. Only `onEnable()`
45+
is required.
46+
47+
| Method | When it runs | Typical use |
48+
| --- | --- | --- |
49+
| `onStartup()` | After the plugin is loaded, **before** it is enabled (and before the proxy has finished starting). | Load critical data or open connections that must exist before other plugins enable. Most plugins don't need this. |
50+
| `onEnable()` *(required)* | Once the proxy startup is complete and plugins are being enabled. | Register commands and events, schedule tasks, read config — your main setup. |
51+
| `onDisable()` | On proxy shutdown, or when the plugin is disabled. | Clean up: save data, close connections, cancel tasks. |
52+
53+
> **Why `onEnable()` and not the constructor?** When your constructor runs, the
54+
> plugin is not fully initialised yet — helpers like `getProxy()` and
55+
> `getLogger()` are not available. Always do your setup in `onEnable()`.
56+
57+
### Useful methods you inherit
58+
59+
Because you extend `Plugin`, these are available via `this.`:
60+
61+
| Method | Returns | Description |
62+
| --- | --- | --- |
63+
| `getProxy()` | `ProxyServer` | The proxy instance — your gateway to almost everything (players, servers, scheduler, events, commands). See the [Plugin API introduction](/plugins/introduction). |
64+
| `getLogger()` | `Logger` | A logger that prefixes messages with your plugin name. Use `info()`, `warn()`, `error()`. |
65+
| `getDataFolder()` | `File` | Your plugin's own folder (`plugins/<name>/`), created automatically. Store your files here. |
66+
| `getConfig()` | `Configuration` | Loads `config.yml` from your data folder (copying it from your jar on first run). |
67+
| `saveResource(String)` | `boolean` | Copies a file bundled in your jar into the data folder. |
68+
| `getResourceFile(String)` | `InputStream` | Reads a file bundled inside your jar. |
69+
| `getName()` | `String` | Your plugin's name from `plugin.yml`. |
70+
71+
## The `plugin.yml`
72+
73+
The proxy needs a descriptor to know how to load your plugin. Create
74+
`src/main/resources/plugin.yml`:
75+
76+
```yaml
77+
name: MyPlugin
78+
version: 1.0.0
79+
author: YourName
80+
main: com.example.myplugin.MyPlugin
81+
```
82+
83+
The fields are:
84+
85+
| Field | Required | Description |
86+
| --- | --- | --- |
87+
| `name` | **yes** | The plugin's name. Also used for the data folder and logger prefix. |
88+
| `main` | **yes** | The fully-qualified name of your main class (package + class name). This **must** match your class exactly. |
89+
| `version` | recommended | Your plugin's version string. |
90+
| `author` | optional | Your name. |
91+
| `depends` | optional | A list of other plugin names that must load before yours. See below. |
92+
93+
> WaterdogPE also accepts the file named `waterdog.yml`. `plugin.yml` is the
94+
> conventional choice and is what most examples use.
95+
96+
### Depending on another plugin
97+
98+
If your plugin needs another plugin to be loaded first, list it under `depends`:
99+
100+
```yaml
101+
name: MyPlugin
102+
version: 1.0.0
103+
main: com.example.myplugin.MyPlugin
104+
depends:
105+
- SomeOtherPlugin
106+
```
107+
108+
WaterdogPE loads dependencies before your plugin and detects circular
109+
dependencies. To grab another loaded plugin instance from code:
110+
111+
```java
112+
Plugin other = this.getProxy().getPluginManager().getPluginByName("SomeOtherPlugin");
113+
if (other != null && other.isEnabled()) {
114+
// safe to use it
115+
}
116+
```
117+
118+
## Build and run
119+
120+
1. Build the jar: `mvn clean package`.
121+
2. Copy `target/MyPlugin-1.0.0.jar` into your proxy's `plugins/` folder.
122+
3. Start the proxy. You should see your `onEnable()` log line:
123+
`[MyPlugin] MyPlugin has been enabled!`
124+
125+
If the plugin doesn't load, double-check that the `main` field in `plugin.yml`
126+
exactly matches your class's package and name.
127+
128+
## Where to go next
129+
130+
Your plugin works — now make it *do* something:
131+
132+
- [Plugin API Introduction](/plugins/introduction) — the `ProxyServer` object and
133+
how the pieces fit together.
134+
- [Working with Players](/plugins/players-guide) — message, transfer and manage
135+
players.
136+
- [Commands Guide](/plugins/commands-guide) — add your own `/commands`.
137+
- [Events Guide](/plugins/events-guide) — react to joins, chat, transfers and more.
138+
- [Scheduling Tasks](/plugins/scheduling-task) — run delayed and repeating tasks.
139+
140+
You can also browse complete, working examples in the
141+
[Example-Plugins repository](https://github.com/WaterdogPE/Example-Plugins).

0 commit comments

Comments
 (0)