PLAYER_ONLINE_EVENT

When applyGrant answers RETRYABLE_FAILURE / CHARACTER_OFFLINE, the gateway parks the command in WAITING_PLAYER and stops. It does not poll the game server. This event is what wakes it.

CHARACTER_OFFLINE is the only error code with an event to wake it. Every other RETRYABLE_FAILURE — including a grant that needs its target offline — is retried on a backoff capped at five minutes, and escalates to RECONCILIATION_REQUIRED after 24 hours of failing.

The event resumes only commands whose account name and character id both match. Other waiting commands are left alone.

{
  "protocolVersion": 1,
  "messageId": "7ef143bc-5810-4b10-9507-820e72b13ce1",
  "gameServerId": "834a9e80-607b-46b4-8952-cb27d2a476c9",
  "sentAt": "2026-07-30T12:00:00.000Z",
  "type": "event.player_online",
  "payload": {
    "normalizedAccountName": "admin",
    "characterId": 268473216
  }
}

normalizedAccountName must use the same normalisation as LIST_ACCOUNT_CHARACTERS and the delivery capabilities. A mismatch means the command never wakes.

Implementing it

Required. Without it a delivery held for an offline character never resumes, so the server is hidden from players rather than accepting purchases it will not hand over.

The connector core exposes the call:

PortalConnector.getInstance().playerOnline(accountName, characterId);

Place it once the character is spawned into the live world and can actually receive a grant — aCis calls it right after player.spawnMe(), Mobius after player.setEnteredWorld(). It is a no-op while the WebSocket is disconnected, so it is safe to call unconditionally.

Advertise PLAYER_ONLINE_EVENT only once the hook is installed. Announcing it without the call is worse than not announcing it: the platform will let the server serve players, and every held delivery will wait forever.

Verification

There is no probe for this. Connector check cannot make a player log in, so it is confirmed during integration. One prerequisite: the purchase dialog offers only the characters the declared delivery window can reach, and the default for DELIVER_ITEM_GRANT is online — so a purchase for an offline character has to be made possible first:

Set DeliveryWindow.DELIVER_ITEM_GRANT=both in config/portal.properties and restart the game server.
Buy something for an offline character. The bridge answers CHARACTER_OFFLINE and the command parks as waiting.
Log that character in and watch the delivery complete without you touching anything.
Afterwards, set the window back to what your pack really does. Keeping both is itself a choice: purchases for offline characters stay sellable and deliver at the next login — which is exactly the behaviour this event provides.

PLAYER_ONLINE_EVENT

Implementing it

Verification

On this page