Interface ClientLauncher

public interface ClientLauncher

Launches, stops and watches game clients through the BotWithUs launcher's background service. A ManagementScript reaches it through ManagementContext.clientLauncher().

Every call is a round trip to the service. A call that fails throws LauncherException; its code is what to branch on. Two codes are raised by the host itself, because no service answered: LauncherException.SERVICE_UNAVAILABLE (the service is not running, is restarting, or did not answer in time) and LauncherException.SERVICE_STOPPED (the user stopped it from the tray). The host never starts the service; it keeps reconnecting while it runs.

Scope. A script that does not manage the whole host sees only the accounts and clients its targets cover. Unlike the ClientOrchestrator, which answers an out-of-scope call with a failed result, this interface throws LauncherException.NOT_PERMITTED: every other failure here is an exception too, so one more kind of refusal is reported the same way. A script paused on a group may still see and stop that group's clients, but may not launch one.

After the service comes back (a LauncherEvent.ServiceRestored event), events sent while it was away are gone and none are replayed. Call clients() to see where things stand.

Method Summary

Modifier and Type	Method	Description
List<LauncherAccount>	accounts()	The launcher's accounts this script may launch.
List<LaunchedClient>	clients()	The clients the service manages that this script may see.
default LaunchHandle	launch(String accountId)	launch(String, LaunchOptions) with LaunchOptions.defaults().
LaunchHandle	launch(String accountId, LaunchOptions options)	Asks the service to launch a client on accountId.
AutoCloseable	onEvent(Consumer<LauncherEvent> listener)	Registers a listener for launcher events.
void	stop(String clientId, StopMode mode)	Stops a client.
static ClientLauncher	unavailable()	A launcher whose every call throws LauncherException.SERVICE_UNAVAILABLE: what a host that does not talk to the launcher service offers.

Method Details

accounts

List<LauncherAccount> accounts()

The launcher's accounts this script may launch.

Returns:

the accounts, in the service's order; never null

launch

LaunchHandle launch(String accountId,
 LaunchOptions options)

Asks the service to launch a client on accountId. Returns once the launch is queued. The host attaches to the client when the service reports it injected, and LaunchHandle.outcome() says how that went.

Parameters:

accountId - an id from accounts()

options - launch options

Returns:

the queued launch

Throws:

LauncherException - rate_limited (see LauncherException.retryAfterMs()), session_limit, concurrency_cap, not_permitted, or another code

launch

default LaunchHandle launch(String accountId)

launch(String, LaunchOptions) with LaunchOptions.defaults().

Parameters:

accountId - an id from accounts()

Returns:

the queued launch

stop

void stop(String clientId,
 StopMode mode)

Stops a client. Returns once the stop is issued; a LauncherEvent.ClientExited follows.

Parameters:

clientId - a LaunchedClient.clientId()

mode - how to stop it

clients

List<LaunchedClient> clients()

The clients the service manages that this script may see.

Returns:

the clients; never null

onEvent

AutoCloseable onEvent(Consumer<LauncherEvent> listener)

Registers a listener for launcher events. It runs on a thread of its own, never on the thread reading the service, and with this script's logging context. Close the returned handle to stop listening.

Parameters:

listener - receives each event in order

Returns:

closes the subscription

unavailable

static ClientLauncher unavailable()

A launcher whose every call throws LauncherException.SERVICE_UNAVAILABLE: what a host that does not talk to the launcher service offers.

Returns:

a new unavailable launcher