Plugin API
Your own plugins can read the network through the Atlas API. They see every running server with its players and metadata, publish metadata about their own server, and hear when servers come and go. The full reference is on javadoc.io.
Add the dependency
A Paper, Velocity or BungeeCord plugin compiles against atlas-api and gets it from the Atlas plugin at runtime, so it's a compile-only dependency:
dependencies {
compileOnly("gg.getatlas:atlas-api:0.1.1-beta.5")
}Both libraries are on Maven Central, so you need no extra repository.
Minestom servers
A Minestom server adds atlas-minestom instead, which brings atlas-api along. The Atlas plugin shows how to start it.
Get the API
On Paper, depend on the Atlas plugin in plugin.yml with depend: [Atlas] and load the API from the services manager:
Atlas atlas = this.getServer()
.getServicesManager()
.load(Atlas.class); On Velocity and BungeeCord, the Atlas plugin's own instance hands it out through atlas(). On Minestom, AtlasMinestom.start() returns it.
Servers
servers() is a live view of every running server in the network. It follows the panel by itself.
for (AtlasServer server : atlas.servers().inGroup("lobby")) {
int online = server.players().online();
this.getLogger().info(server.name() + ": " + online + " players");
} Each AtlasServer has its id, its name, its group, its private address, its players and its metadata. Find one server with byId or named, or list them all with all().
This server
self() is the server your plugin runs on. Its id is empty until the worker first connects, and connected() says whether the worker is there right now.
Map setup
setup() holds the map setup on a setup server and is empty everywhere else. map() is the map's name as the builder typed it, and finish() saves the setup files into the draft, sends the builder back and stops the server. Calling finish() twice saves nothing new. See Map deploys.
Metadata
A server publishes named values about itself, like the map it runs. Every server in the network can read them, and the panel shows them.
atlas.self().metadata().set("map", "dunes"); A key is up to 64 lowercase letters, digits, dots, dashes or underscores, and a value is up to 256 characters. One server holds at most 64 keys.
To change several values at once, pass them to update. The network sees every change together or none of them, so no server ever reads half an update.
atlas.self().metadata().update(changes -> changes
.set("map", "dunes")
.set("alive", 2)
.remove("winner")
.phase(GamePhase.IN_ROUND)); Numbers are stored as text, so set("alive", 2) holds "2". When one change breaks a rule, update throws and nothing changes.
Game phase
A minigame tells Atlas where it is in its round. Atlas never stops a server that is in a round, so a scale-down waits until the round is over.
atlas.self().phase(GamePhase.IN_ROUND); The phases are WAITING, IN_ROUND and ENDING. A server that sets none counts as waiting.
Events
Listen for ServerAdded, ServerUpdated and ServerRemoved, or for ServerEvent to hear all three:
Subscription joined = atlas.events().on(ServerAdded.class, event ->
this.getLogger().info(event.server().name() + " joined")); Events arrive one at a time, in the order they happened, on Atlas's own thread. Hand slow work to your platform's scheduler, and close the subscription when your plugin stops.