# El helper para Paper y Velocity

:::caution
Fase 2, **en desarrollo**. Esta página describe el diseño de `zaroz-minecraft-helper` (Java 21, Gradle, MIT). Los nombres y opciones pueden cambiar hasta la primera versión `1.x`, que se versiona con la versión mayor del contrato.
:::

| Módulo | Qué es |
|---|---|
| `common` | cliente del contrato (lee `/zaroz/*.json`, socket de señales y long-polls), cliente de la API de Units (se autentica con `/zaroz/credentials/token`, releyéndolo ante un `401`), verificador de firmas de webhooks, eventos tipados |
| `paper` | un plugin para servidores Paper |
| `velocity` | un plugin para proxies Velocity |

## Paper

- Señala `ready` tras `ServerLoadEvent`.
- Señala `busy` en el primer ingreso e `idle` tras `idle_grace_seconds` sin jugadores (configurable).
- Señala `accepting false` al llegar a tu capacidad configurada y `true` por debajo.
- Registra un servicio `ZarozUnit` (`ServicesManager` de Bukkit) con la clave, etiquetas, `user_data` y asignación, y lanza `UnitAllocatedEvent` cuando llega una asignación.
- Con el aviso de drenaje envía un mensaje configurable y pide al proxy que mueva a los jugadores a un lobby antes de SIGTERM.

La persistencia del mundo sigue siendo tuya: descargar al arrancar, subir con SIGTERM, a tu propio bucket.

```java
ZarozUnit unit = Bukkit.getServicesManager().load(ZarozUnit.class);
getServer().getPluginManager().registerEvents(new Listener() {
    @EventHandler
    void onAllocated(UnitAllocatedEvent e) {
        Match match = Match.fromJson(e.userData());   // la lista que enviaste a allocate
        startMatch(match);
    }
}, this);
```

## Velocity

- Mantiene la lista de servidores del proxy sincronizada con uno o más Workloads: lista las unidades listas y sigue el [long-poll de eventos](/es/guides/units-api/events) (`unit.ready` añade `<clave>.<workload>`, `unit.draining` y `unit.destroyed` lo quitan).
- Reparte los ingresos entre los lobbies que aceptan jugadores.
- Una API de duelos para tus plugins: `allocate` en un Workload configurado con el grupo en `user_data`, y envía a los jugadores cuando llega `unit.allocation_delivered`.
- Una API de parcelas: crear por clave con `start: true` y esperar `unit.ready`.

El Workload del proxy necesita un [principal de servicio](/es/guides/units-api/principals) con `units.control` sobre los Workloads donde crea unidades y `units.read` sobre los que solo observa.

Mira el repositorio `example-game-network` para una red completa construida con él.