Package dev.objz.commandbridge.api

Interface CommandBridgeAPI

public interface CommandBridgeAPI
Primary interface for interacting with the CommandBridge network from a third-party plugin.

Obtain an instance via CommandBridgeProvider.get(). Use channel(Class) to obtain typed message channels, server() and connectionState() to query the current server's identity and connection status, and onServerConnected(ServerEventListener) or onServerDisconnected(ServerEventListener) to subscribe to server lifecycle events on the Velocity proxy.

Methods returning Optional are available only on the Velocity proxy and return Optional.empty() on backend servers.

See Also:

  • Method Details

    • channel

      <T extends ChannelPayload> MessageChannel<T> channel(Class<T> type)
      Obtains a typed MessageChannel for the given payload type.
      Type Parameters:
      T - the payload type; must extend ChannelPayload
      Parameters:
      type - the Class token identifying the payload type; used for channel routing
      Returns:
      the message channel for sending and receiving payloads of type T
      See Also:

    • server

      Platform.ServerTarget server()
      Returns the identity of the server this API instance is running on.
      Returns:
      the Platform.ServerTarget of the current server, containing its configured identifier and platform type

    • connectionState

      ConnectionState connectionState()
      Returns the current connection state of this server to the CommandBridge network.
      Returns:
      the current ConnectionState
      See Also:

    • connectedServers

      Optional<Set<String>> connectedServers()
      Returns the identifiers of all servers currently connected to the bridge network.

      This method is available only on the Velocity proxy. On backend servers, it returns Optional.empty().

      Returns:
      an Optional containing a snapshot of the connected server IDs if called on the Velocity proxy, or an empty Optional on backend servers
      See Also:

    • playerLocator

      Optional<PlayerLocator> playerLocator()
      Returns the player location service for resolving which server a player is connected to.

      This method is available only on the Velocity proxy. On backend servers, it returns Optional.empty().

      Returns:
      an Optional containing the PlayerLocator if called on the Velocity proxy, or an empty Optional on backend servers
      See Also:

    • onServerConnected

      Optional<Subscription> onServerConnected(ServerEventListener listener)
      Subscribes to server connection events.

      This method is available only on the Velocity proxy. On backend servers, it returns Optional.empty() and the listener is not registered.

      Parameters:
      listener - the listener to invoke when a backend server connects to the bridge network; must not be null
      Returns:
      an Optional containing the Subscription on the proxy, or an empty Optional on backends
      See Also:

    • onServerDisconnected

      Optional<Subscription> onServerDisconnected(ServerEventListener listener)
      Subscribes to server disconnection events.

      This method is available only on the Velocity proxy. On backend servers, it returns Optional.empty() and the listener is not registered.

      Parameters:
      listener - the listener to invoke when a backend server disconnects from the bridge network; must not be null
      Returns:
      an Optional containing the Subscription on the proxy, or an empty Optional on backends
      See Also:

    • onConnectionStateChanged

      Subscription onConnectionStateChanged(Consumer<ConnectionState> listener)
      Subscribes to connection state changes on this server.

      Available on all platforms, unlike the server event methods. The listener is invoked on every state transition.

      Parameters:
      listener - the consumer to call with the new ConnectionState on each transition; must not be null
      Returns:
      a Subscription that can be cancelled to stop receiving state change events
      See Also: