Package dev.qixils.crowdcontrol

Class CrowdControl

  • All Implemented Interfaces:
    RequestManager, ServiceManager, Respondable, SocketManager
    @AvailableSince("1.0.0")
public final class CrowdControl
extends Object
implements SocketManager, RequestManager
    API for receiving effect requests from a Crowd Control service (a streamer) via the SimpleTCPConnector or SimpleTCPClientConnector.

    Creating an instance

    To create an instance of this class, use either the client() or server() methods.

    • client() creates a client instance that can be used to connect to a central Crowd Control instance. It corresponds with the SimpleTCPConnector in your project's .cs file. In this mode, your project will only be able to connect to one streamer, although multiple instances of your project will all be able to connect to this streamer at the same time. This mode is ideal for single-player games.
    • server() creates a server instance that can be used to connect to multiple Crowd Control clients. It corresponds with the SimpleTCPClientConnector. This allows you to receive requests from multiple streamers, making this ideal for multiplayer games.

    You should only ever create one instance of this class. If you must recreate this instance, remember to call shutdown(String) first.

    Registering effect handlers

    Effect handlers process incoming effect Requests, apply them to players or environments as appropriate, and then return a Response that informs the client of whether the effect was successfully applied.

    To start handling incoming effects, you much register handlers for each effect you want to handle using one of registerHandler(String, Consumer), registerHandler(String, Function), or registerHandlers(Object).

    Registering checks

    Checks allow you to block an effect from being processed if certain conditions are not met. This is typically used to ensure effects are not run before the game has loaded into a world. You can register checks using registerCheck(Supplier) or registerCheck(Function).

    Since:
    1.0.0

    • Method Detail

      • client

        @AvailableSince("3.0.0")
public static CrowdControlClientBuilder client()
        Returns a builder for a new CrowdControl instance operating in client mode. It will connect to a singular Crowd Control server instance.
        Returns:
        a new client builder
        Since:
        3.0.0

      • server

        @AvailableSince("3.0.0")
public static CrowdControlServerBuilder server()
        Returns a builder for a new CrowdControl instance operating in server mode. It will allow numerous Crowd Control clients to connect.
        Returns:
        a new server builder
        Since:
        3.0.0

      • getIP

        @AvailableSince("1.0.0")
@Nullable
@CheckReturnValue
public @Nullable InetAddress getIP()
        Returns the IP that the SocketManager will listen on or bind to. May be null for servers to bind to all local IPs.
        Specified by:
        getIP in interface ServiceManager
        Returns:
        IP if available
        Since:
        1.0.0

      • getPassword

        @AvailableSince("3.0.0")
@Nullable
@CheckReturnValue
public @Nullable String getPassword()
        Returns the password required for clients to connect to this server as a SHA-512 encrypted, hexadecimal string. If running in client mode, this will be null.
        Specified by:
        getPassword in interface ServiceManager
        Returns:
        password required to connect
        Since:
        3.0.0

      • registerHandlers

        @AvailableSince("1.0.0")
public void registerHandlers​(@NotNull
                             @NotNull Object object)
        Registers method handlers within a class. These methods must:
        Parameters:
        object - class instance to register
        Since:
        1.0.0

      • registerHandler

        @AvailableSince("1.0.0")
public void registerHandler​(@Nullable
                            @Nullable String effect,
                            @NotNull
                            @NotNull Function<Request,​Response> handler)
        Registers a function to handle an effect.
        Parameters:
        effect - name of the effect to handle
        handler - function to handle the effect
        Since:
        1.0.0
        See Also:
        registerHandler(String, Consumer)

      • registerHandler

        @AvailableSince("2.0.0")
public void registerHandler​(@Nullable
                            @Nullable String effect,
                            @NotNull
                            @NotNull Consumer<Request> handler)
        Registers an effect handler which does not immediately return a Response. It is expected to call Response.send() on its own.
        Parameters:
        effect - name of the effect to handle
        handler - function to handle the effect
        Since:
        2.0.0
        See Also:
        registerHandler(String, Function)

      • registerCheck

        @AvailableSince("3.2.1")
public void registerCheck​(@NotNull
                          @NotNull Function<Request,​CheckResult> check)
        Registers a check which will be called for every incoming Request. A resulting value of CheckResult.DISALLOW will result in a FAILURE response packet.

        This is used for validating that your service is accepting requests, and should return CheckResult.DISALLOW if, for example, the game has not fully initialized or no players are connected.

        Parameters:
        check - global check to register
        Since:
        3.2.1

      • registerCheck

        @AvailableSince("3.2.1")
public void registerCheck​(@NotNull
                          @NotNull Supplier<CheckResult> check)
        Registers a check which will be called for every incoming Request. A resulting value of CheckResult.DISALLOW will result in a FAILURE response packet.

        This is used for validating that your service is accepting requests, and should return CheckResult.DISALLOW if, for example, the game has not fully initialized or no players are connected.

        Parameters:
        check - global check to register
        Since:
        3.2.1

      • hasHandler

        @AvailableSince("3.3.0")
public boolean hasHandler​(@NotNull
                          @NotNull String effect)
        Determines if the given effect has a registered handler.
        Parameters:
        effect - effect to check
        Returns:
        true if the effect has a registered handler
        Since:
        3.3.0

      • handle

        @AvailableSince("1.0.0")
@Internal
public void handle​(@NotNull
                   @NotNull Request request)
        Handles an incoming Request by executing the relevant handler.
        Specified by:
        handle in interface RequestManager
        Parameters:
        request - an incoming request
        Since:
        1.0.0

      • shutdown

        @AvailableSince("3.1.0")
public void shutdown​(@Nullable
                     @Nullable String reason)
        Shuts down the internal connection to the Crowd Control server and sends a corresponding error message to the streamer(s).
        Specified by:
        shutdown in interface SocketManager
        Parameters:
        reason - the reason for shutting down
        Since:
        3.1.0

      • shutdown

        @AvailableSince("3.1.0")
public void shutdown​(@Nullable
                     @Nullable Request cause,
                     @Nullable
                     @Nullable String reason)
        Shuts down the internal connection to the Crowd Control server and sends a corresponding error message to the streamer(s).
        Specified by:
        shutdown in interface SocketManager
        Parameters:
        cause - cause for shutting down
        reason - the reason for shutting down
        Since:
        3.1.0