Copy page

Units your code controls

The Paper and Velocity helper

Module	What it is
common	contract client (reads /zaroz/*.json, signal socket and long-polls), Units API client (authenticates with /zaroz/credentials/token, re-reading it on 401), webhook signature verifier, typed events
paper	a plugin for Paper servers
velocity	a plugin for Velocity proxies

Paper

• Signals ready after ServerLoadEvent.
• Signals busy on the first join and idle after idle_grace_seconds with no players (configurable).
• Signals accepting false at your configured capacity and true below it.
• Registers a ZarozUnit service (Bukkit ServicesManager) with the key, labels, user_data and allocation, and fires UnitAllocatedEvent when an allocation arrives.
• On the draining notice it sends a configurable message and asks the proxy to move players to a lobby before SIGTERM.

World persistence stays yours: download on start, upload on SIGTERM, to your own bucket.

Code
ZarozUnit unit = Bukkit.getServicesManager().load(ZarozUnit.class);
getServer().getPluginManager().registerEvents(new Listener() {
    @EventHandler
    void onAllocated(UnitAllocatedEvent e) {
        Match match = Match.fromJson(e.userData());   // the roster you sent to allocate
        startMatch(match);
    }
}, this);

Velocity

• Keeps the proxy's server list in sync with one or more Workloads: it lists ready units and follows the event long-poll (unit.ready adds <key>.<workload>, unit.draining and unit.destroyed remove it).
• Balances joins across accepting lobbies.
• A duel API for your plugins: allocate on a configured Workload with the party in user_data, then it sends the players when unit.allocation_delivered arrives.
• A plot API: create by key with start: true, and wait for unit.ready.

The proxy's Workload needs a service principal with units.control on the Workloads it creates units in and units.read on the ones it only watches.

See the example-game-network repository for a complete network built with it.