Package dev.qixils.crowdcontrol

Class CrowdControl

  • All Implemented Interfaces:
    SocketManager
    public final class CrowdControl
extends Object
implements SocketManager
    API for interacting with Crowd Control 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 server. 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 singleplayer 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).

    • Constructor Detail

      • CrowdControl

        public CrowdControl​(@Nullable
                    @Nullable String IP,
                    int port,
                    @Nullable
                    @Nullable String password,
                    @NotNull
                    @NotNull Function<@NotNull CrowdControl,​@NotNull SocketManager> socketManagerCreator)
        Creates a new Crowd Control client or server instance.

        You should generally be using server() or client() instead. This constructor's parameters are prone to changes.

        Parameters:
        IP - IP address to connect to (if applicable)
        port - port to listen on or connect to
        password - password required to connect (if applicable)
        socketManagerCreator - creator of a new SocketManager

    • Method Detail

      • isCause

        public static boolean isCause​(@NotNull
                              @NotNull Class<? extends Throwable> potentialCause,
                              @Nullable
                              @Nullable Throwable exception)
        Helper method for determining if a provided exception class is part of an exception's stacktrace.
        Parameters:
        potentialCause - class to search for in stacktrace
        exception - exception to be searched
        Returns:
        true if the exception class is found

      • client

        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

      • server

        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

      • getIP

        @Nullable
@CheckReturnValue
public @Nullable String getIP()
        Returns the IP that the SocketManager will listen on. If running in server mode, this will be null.
        Returns:
        IP if available

      • getPort

        @CheckReturnValue
public int getPort()
        Returns the port that the SocketManager will listen on.
        Returns:
        IP port

      • getPassword

        @Nullable
@CheckReturnValue
public @Nullable String getPassword()
        Returns the password required for clients to connect to this server as a SHA-512 encrypted, Base64-encoded string. If running in client mode, this will be null.
        Returns:
        password required to connect

      • registerHandlers

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

      • registerHandler

        public void registerHandler​(@NotNull
                            @NotNull 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
        See Also:
        registerHandler(String, Consumer)

      • registerHandler

        public void registerHandler​(@NotNull
                            @NotNull 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
        See Also:
        registerHandler(String, Function)

      • registerCheck

        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 an 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

      • registerCheck

        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 an 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

      • handle

        public void handle​(@NotNull
                   @NotNull Request request)
        Handles an incoming Request by executing the relevant handler.
        Parameters:
        request - an incoming request

      • shutdown

        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

      • shutdown

        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