API¶
AdvancedServerList offers an API that other plugins can use to add their own placeholder to the plugin, listen for specific events or even modify Server List Profiles on the fly.
Add dependency¶
Add the following to your pom.xml
, build.gradle
or build.gradle.kts
depending on what you use:
<repositories>
<repository>
<id>codeberg</id>
<url>https://codeberg.org/api/packages/Andre601/maven/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>ch.andre601.asl-api</groupId>
<artifactId>api</artifactId>
<version>{apiVersion}</version>
<scope>provided</scope>
</dependency>
<!-- Optional platform dependencies -->
<dependency>
<groupId>ch.andre601.asl-api</groupId>
<artifactId>platform-bukkit</artifactId>
<version>{apiVersion}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>ch.andre601.asl-api</groupId>
<artifactId>platform-bungeecord</artifactId>
<version>{apiVersion}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>ch.andre601.asl-api</groupId>
<artifactId>platform-velocity</artifactId>
<version>{apiVersion}</version>
<scope>provided</scope>
</dependency>
</dependencies>
repositorories {
maven { url = 'https://codeberg.org/api/packages/Andre601/maven/' }
}
dependencies {
compileOnly 'ch.andre601.asl-api:api:{apiVersion}'
// Optional platform dependencies
compileOnly 'ch.andre601.asl-api:platform-bukkit:{apiVersion}'
compileOnly 'ch.andre601.asl-api:platform-bungeecord:{apiVersion}'
compileOnly 'ch.andre601.asl-api:platform-velocity:{apiVersion}'
}
repositories {
maven("https://codeberg.org/api/packages/Andre601/maven/")
}
dependencies {
compileOnly("ch.andre601.asl-api:api:{apiVersion}")
// Optional platform dependencies
compileOnly("ch.andre601.asl-api:platform-bukkit:{apiVersion}")
compileOnly("ch.andre601.asl-api:platform-bungeecord:{apiVersion}")
compileOnly("ch.andre601.asl-api:platform-velocity:{apiVersion}")
}
Tutorials¶
Dedicated pages to explain aspects of the API are available:
Declare AdvancedServerList as (soft)depend¶
The final thing you should make sure is to define AdvancedServerList as a depend or soft-depend for your plugin, to make sure it loads after AdvancedServerList.
Below are example setups for Spigot, Paper, BungeeCord and Velocity:
name: "MyPlugin"
author: "author"
version: "1.0.0"
main: "com.example.plugin.ExamplePlugin"
dependencies:
server:
AdvancedServerList:
load: BEFORE
required: false # Default, not required
name: "MyPlugin"
author: "author"
version: "1.0.0"
main: "com.example.plugin.ExamplePlugin"
dependencies:
server:
AdvancedServerList:
load: BEFORE
required: true
name: "MyPlugin"
author: "author"
version: "1.0.0"
main: "com.example.plugin.ExamplePlugin"
softDepends:
- AdvancedServerList
name: "MyPlugin"
author: "author"
version: "1.0.0"
main: "com.example.plugin.ExamplePlugin"
depends:
- AdvancedServerList
{
"id": "myplugin",
"name": "MyPlugin",
"version": "1.0.0",
"authors": [
"author"
],
"main": "com.example.plugin.ExamplePlugin",
"dependencies": [
{
"id": "advancedserverlist",
"optional": true
}
]
}
{
"id": "myplugin",
"name": "MyPlugin",
"version": "1.0.0",
"authors": [
"author"
],
"main": "com.example.plugin.ExamplePlugin",
"dependencies": [
{
"id": "advancedserverlist",
"optional": false // Default, not required
}
]
}
@Plugin(
id = "myplugin",
name = "MyPlugin",
version = "1.0.0",
authors = {"author"},
dependencies = {
@Dependency(
id = "advancedserverlist",
optional = true
)
}
)
public class MyPlugin {
// ...
}
@Plugin(
id = "myplugin",
name = "MyPlugin",
version = "1.0.0",
authors = {"author"},
dependencies = {
@Dependency(
id = "advancedserverlist",
optional = false // Default, not required
)
}
)
public class MyPlugin {
// ...
}
4. You're done!¶
Your plugin should now hook into AdvancedServerList and register its own custom placeholders to use.
Listening for events¶
AdvancedServerList provides Events that your plugin can listen for specific situations.
PreServerListSetEvent¶
This event is called before AdvancedServerList starts handling the PingEvent of the Server/Proxy.
It allows you to get and alter the ProfileEntry used in the PingEvent, or even outright cancel the event itself.
The event offers the following methods:
getEntry()
- Gets the currently setProfileEntry
.setEntry(ProfileEntry)
- Sets a newProfileEntry
to use.isCancelled()
- Gets the current cancelled state of the event.setCancelled(boolean)
- Sets the current cancelled state.
Please check the server/proxy's documentation on how to listen for events with your plugin.
PostServerListSetEvent¶
This event is called after AdvancedServerList has completed its handling of the Server's/Proxy's PingEvent.
It provides a method to retrieve the ProfileEntry used during the PingEvent.
Do note that this ProfileEntry is not a representation of what is actually displayed in the server list, but rather what has been used by AdvancedServerList. It may also be null
should the event handling get cancelled for any reason.
ProfileEntry¶
The ProfileEntry record is the core class used within the PreServerListSetEvent
. It sets what values (MOTD, Favicon, Players, etc.) should be displayed.
Note that the record is - by nature - immutable and that the Builder
class should be used to create a new ProfileEntry instance to use.
A convenience method (builder()
) exists to create a Builder
instance from an existing ProfileEntry
in case you only want to alter certain options while everything else should remain unchanged.
This allows you to customize the Server list using your plugin. Just keep in mind that other plugins may also do the same, overriding your changes.