Package dev.adlin.vts4j

Interface VTSClient

All Known Implementing Classes:
VTSClientImpl
public interface VTSClient
The primary high-level client interface for interacting with the VTube Studio Public API.

Provides full control over the connection lifecycle, token authentication, request dispatching, and event subscription management workflows.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    @NonNull CompletableFuture<String>
    authenticate(@NonNull PluginMeta pluginMeta)
    Requests a brand new authentication token from VTube Studio for the specified plugin metadata.
    void
    authenticate(@NonNull PluginMeta pluginMeta, @NonNull String authenticationToken)
    Authenticates the plugin session instantly using a previously saved existing authentication token.
    VTSClient
    awaitConnect()
    Establishes a synchronous connection to the remote server, blocking the calling thread indefinitely until the connection handshake completes or fails.
    VTSClient
    awaitConnect(long timeout, @NonNull TimeUnit timeUnit)
    Establishes a synchronous connection to the remote server, blocking the calling thread up to the specified timeout interval.
    void
    awaitDisconnect()
    Synchronously tears down the active socket session, blocking the calling thread until the close handshake is acknowledged.
    VTSClient
    connect()
    Initiates a non-blocking background connection routine to the remote VTube Studio server.
    void
    disconnect()
    Initiates an asynchronous, non-blocking disconnection routine to close the socket session.
    void
    registerEventListener(@NonNull Listener listener)
    Registers an event listener object within the client's internal event bus.
    CompletableFuture<Response>
    sendRequest(@NonNull Request request)
    Serializes and dispatches an asynchronous request packet to the server over the active socket session.
    CompletableFuture<Response>
    subscribe(@NonNull Class<? extends Event> eventClass)
    Subscribes the current plugin session to a specific system event type using default configurations.
    CompletableFuture<Response>
    subscribe(@NonNull Class<? extends Event> eventClass, @NonNull com.google.gson.JsonObject eventConfig)
    Subscribes the current plugin session to a specific system event type using extended configuration arguments.
    CompletableFuture<Response>
    unsubscribe(@NonNull Class<? extends Event> eventClass)
    Unsubscribes the current plugin session from all instances of the specified system event type.
    CompletableFuture<Response>
    unsubscribe(@NonNull Class<? extends Event> eventClass, @NonNull com.google.gson.JsonObject eventConfig)
    Unsubscribes the current plugin session from a specific system event matching the provided configuration filters.

  • Method Details

    • connect

      VTSClient connect()
      Initiates a non-blocking background connection routine to the remote VTube Studio server.
      Returns:
      this client instance for fluent method chaining

    • awaitConnect

      VTSClient awaitConnect()
      Establishes a synchronous connection to the remote server, blocking the calling thread indefinitely until the connection handshake completes or fails.
      Returns:
      this client instance for fluent method chaining

    • awaitConnect

      VTSClient awaitConnect(long timeout, @NonNull TimeUnit timeUnit)
      Establishes a synchronous connection to the remote server, blocking the calling thread up to the specified timeout interval.
      Parameters:
      timeout - the maximum duration to wait for a connection handshake
      timeUnit - the time unit of the timeout argument
      Returns:
      this client instance for fluent method chaining

    • disconnect

      void disconnect()
      Initiates an asynchronous, non-blocking disconnection routine to close the socket session.

    • awaitDisconnect

      void awaitDisconnect()
      Synchronously tears down the active socket session, blocking the calling thread until the close handshake is acknowledged.

    • authenticate

      @NonNull CompletableFuture<String> authenticate(@NonNull PluginMeta pluginMeta)
      Requests a brand new authentication token from VTube Studio for the specified plugin metadata.

      This will trigger a pop-up confirmation window inside the VTube Studio UI for the end-user.

      Parameters:
      pluginMeta - the metadata configuration of the plugin requesting access
      Returns:
      a CompletableFuture that resolves to the newly issued unique authentication token string

    • authenticate

      void authenticate(@NonNull PluginMeta pluginMeta, @NonNull String authenticationToken)
      Authenticates the plugin session instantly using a previously saved existing authentication token.
      Parameters:
      pluginMeta - the metadata configuration of the plugin
      authenticationToken - the pre-issued token string to authenticate with

    • sendRequest

      CompletableFuture<Response> sendRequest(@NonNull Request request)
      Serializes and dispatches an asynchronous request packet to the server over the active socket session.
      Parameters:
      request - the request packet structure to be transmitted
      Returns:
      a CompletableFuture containing the server's asynchronous Response package

    • subscribe

      CompletableFuture<Response> subscribe(@NonNull Class<? extends Event> eventClass, @NonNull com.google.gson.JsonObject eventConfig)
      Subscribes the current plugin session to a specific system event type using extended configuration arguments.

      Re-subscribing to an already active event type will seamlessly overwrite its previous parameters. For details regarding available event names and payloads, see the VTube Studio Events Guide.

      Parameters:
      eventClass - the class type of the target Event to subscribe to
      eventConfig - custom JSON configuration properties and filters specific to the event type
      Returns:
      a CompletableFuture containing the server response acknowledgment indicating operation status

    • subscribe

      CompletableFuture<Response> subscribe(@NonNull Class<? extends Event> eventClass)
      Subscribes the current plugin session to a specific system event type using default configurations.
      Parameters:
      eventClass - the class type of the target Event to subscribe to
      Returns:
      a CompletableFuture containing the server response acknowledgment indicating operation status

    • unsubscribe

      CompletableFuture<Response> unsubscribe(@NonNull Class<? extends Event> eventClass, @NonNull com.google.gson.JsonObject eventConfig)
      Unsubscribes the current plugin session from a specific system event matching the provided configuration filters.
      Parameters:
      eventClass - the class type of the target Event to unsubscribe from
      eventConfig - custom JSON configuration parameters to match for removal
      Returns:
      a CompletableFuture containing the server response acknowledgment indicating operation status

    • unsubscribe

      CompletableFuture<Response> unsubscribe(@NonNull Class<? extends Event> eventClass)
      Unsubscribes the current plugin session from all instances of the specified system event type.
      Parameters:
      eventClass - the class type of the target Event to unsubscribe from
      Returns:
      a CompletableFuture containing the server response acknowledgment indicating operation status

    • registerEventListener

      void registerEventListener(@NonNull Listener listener)
      Registers an event listener object within the client's internal event bus.

      The registered instance will intercept notifications for any system events that have been activated using the subscribe methods.

      Parameters:
      listener - an instance of a custom class implementing the marker Listener interface