Moved

The documenation has been moved and can now be found at asl.andre601.ch.
This page in particular can be found at asl.andre601.ch/api/.

API¶

AdvancedServerList v2 introduced a new API that plugins can hook into to use.
It provides a way for your plugin to provide its own placeholders that should be parsed by AdvancedServerList and also an event to modify the server list.

Add dependency¶

Add the following to your build.gradle or pom.xml file to use the API:

Maven Gradle Gradle (KTS)

pom.xml

<repositories>
  <repository>
    <id>jitpack</id>
    <url>https://jitpack.io/</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>ch.andre601.asl-api</groupId>
    <artifactId>api</artifactId>
    <version>{version}</version>
    <scope>provided</scope>
  </dependency>

  <!-- Optional platform dependencies -->
  <dependency>
    <groupId>ch.andre601.asl-api</groupId>
    <artifactId>platform-bukkit</artifactId>
    <version>{version}</version>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>ch.andre601.asl-api</groupId>
    <artifactId>platform-bungeecord</artifactId>
    <version>{version}</version>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>ch.andre601.asl-api</groupId>
    <artifactId>platform-velocity</artifactId>
    <version>{version}</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

build.gradle

repositorories {
    maven { url = 'https://jitpack.io/' }
}

dependencies {
    compileOnly 'ch.andre601.asl-api:api:{version}'

    // Optional platform dependencies
    compileOnly 'ch.andre601.asl-api:platform-bukkit:{version}'
    compileOnly 'ch.andre601.asl-api:platform-bungeecord:{version}'
    compileOnly 'ch.andre601.asl-api:platform-velocity:{version}'
}

build.gradle.kts

repositories {
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("ch.andre601.asl-api:api:{version}")

    // Optional platform dependencies
    compileOnly("ch.andre601.asl-api:platform-bukkit:{version}")
    compileOnly("ch.andre601.asl-api:platform-bungeecord:{version}")
    compileOnly("ch.andre601.asl-api:platform-velocity:{version}")
}

Adding your own Placeholders¶

This requires the main api module

The API allows you to add your own placeholders which would be available through the ${<identifier> <values>} placeholder Pattern in a Server List profile.

To add your own placeholders, follow these steps:

1. Create a Placeholder class¶

You should first create a new class and make it extend the abstract PlaceholderProvider. This class includes a constructor and a method you need to add, so do that:

public class MyPlaceholders extends PlaceholderProvider {

    public MyPlaceholders(String identifier) {
        super(identifier);
    }

    @Override
    public String parsePlaceholder(String placeholder, GenericPlayer player, GenericServer server) {
        return null;
    }
}

Tip

You can replace the Constructor with a String argument with a no-args constructor and set the identifier directly in the super:

public MyPlaceholders() {
    super("myplaceholders");
}

The parsePlaceholder(String, GenericPlayer, GenericServer) method is used by AdvancedServerList to replace a matching placeholder with a value.
What you return is completely up to you. Just keep in mind that returning null will be treated as an invalid placeholder by AdvancedServerList, resulting in the placeholder being returned as-is without any changes.

Example of final class

public class MyPlaceholders extends PlaceholderProvider {

    public MyPlaceholders() {
        super("myplaceholders");
    }

    @Override
    public String parsePlaceholder(String placeholder, GenericPlayer player, GenericServer server) {
        if(placeholder.equalsIgnoreCase("hello"))
            return "Hello " + player.getName();

        return null;
    }
}

2. Register the Placeholders¶

Next step should be to register the placeholder. To achieve this, first obtain an instance of the AdvancedServerListAPI by using the static get() method. After that call addPlaceholderProvider(PlaceholderProvider placeholderProvider).
Your code may look similar to this:

Registering PlaceholderProvider class

public class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        AdvancedServerListAPI api = AdvancedServerListAPI.get();

        api.addPlaceholderProvider(new MyPlaceholders());
    }
}

This should register your PlaceholderExpansion as long as it is valid, meaning that the identifier...

...is not null
...is not containing spaces
...is not using a name already registered by the plugin

3. 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:

Spigot Paper BungeeCord Velocity

SoftdependDepend

plugin.yml

name: "MyPlugin"
author: "author"
version: "1.0.0"

main: "com.example.plugin.ExamplePlugin"

softdepend:
  - AdvancedServerList

plugin.yml

name: "MyPlugin"
author: "author"
version: "1.0.0"

main: "com.example.plugin.ExamplePlugin"

depend:
  - AdvancedServerList

SoftdependDepend

paper-plugin.yml

name: "MyPlugin"
author: "author"
version: "1.0.0"

main: "com.example.plugin.ExamplePlugin"

dependencies:
  server:
    AdvancedServerList:
      load: BEFORE
      required: false # Default, not required

paper-plugin.yml

name: "MyPlugin"
author: "author"
version: "1.0.0"

main: "com.example.plugin.ExamplePlugin"

dependencies:
  server:
    AdvancedServerList:
      load: BEFORE
      required: true

SoftdependDepend

bungee.yml

name: "MyPlugin"
author: "author"
version: "1.0.0"

main: "com.example.plugin.ExamplePlugin"

softDepends:
  - AdvancedServerList

bungee.yml

name: "MyPlugin"
author: "author"
version: "1.0.0"

main: "com.example.plugin.ExamplePlugin"

depends:
  - AdvancedServerList

Softdepend (File)Depend (File)Softdepend (Annotation)Depend (Annotation)

velocity-plugin.json

{
  "id": "myplugin",
  "name": "MyPlugin",
  "version": "1.0.0",
  "authors": [
    "author"
  ],
  "main": "com.example.plugin.ExamplePlugin",
  "dependencies": [
    {
      "id": "advancedserverlist",
      "optional": true
    }
  ]
}

velocity-plugin.json

{
  "id": "myplugin",
  "name": "MyPlugin",
  "version": "1.0.0",
  "authors": [
    "author"
  ],
  "main": "com.example.plugin.ExamplePlugin",
  "dependencies": [
    {
      "id": "advancedserverlist",
      "optional": false
    }
  ]
}

MyPlugin.java

@Plugin(
  id = "myplugin",
  name = "MyPlugin",
  version = "1.0.0",
  authors = {"author"},
  dependencies = {
    @Dependency(
      id = "advancedserverlist",
      optional = true
    )
  }
)
public class MyPlugin {

  // ...

}

MyPlugin.java

@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¶

This requires the platform specific dependencies

AdvancedServerList provides an Event that your plugin can listen for.
The event is called PreServerListSetEvent and provides the following methods to use:

getEntry() - Gets the currently set ProfileEntry.
setEntry(ProfileEntry) - Sets a new ProfileEntry to use.
isCancelled() - Gets the current cancelled state of the event.
setCancelled(boolean) - Sets the current cancelled state.

Setting the event's cancelled state to true will result in AdvancedServerList not altering the Server list.

Please check the server/proxy's documentation on how to listen for events with your plugin.

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.

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.