Class CrowdControl
- java.lang.Object
-
- dev.qixils.crowdcontrol.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 theSimpleTCPConnector
orSimpleTCPClientConnector
.Creating an instance
To create an instance of this class, use either the
client()
orserver()
methods.-
client()
creates a client instance that can be used to connect to a central Crowd Control instance. It corresponds with theSimpleTCPConnector
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 theSimpleTCPClientConnector
. 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
Request
s, apply them to players or environments as appropriate, and then return aResponse
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)
, orregisterHandlers(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)
orregisterCheck(Function)
.- Since:
- 1.0.0
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addConnectListener(@NotNull Consumer<@NotNull SocketManager> consumer)
Sets a consumer to be called when a newCrowd Control instance
connects.@NotNull Response.Builder
buildResponse()
static CrowdControlClientBuilder
client()
Returns a builder for a newCrowdControl
instance operating in client mode.@NotNull List<? extends SocketManager>
getConnections()
@NotNull String
getDisplayName()
@Nullable String
getIP()
Returns the IP that theSocketManager
will listen on.@Nullable String
getPassword()
Returns the password required for clients to connect to this server as a SHA-512 encrypted, hexadecimal string.int
getPort()
Returns the port that theSocketManager
will listen on.@NotNull Set<Request.Source>
getSources()
void
handle(@NotNull Request request)
Handles an incomingRequest
by executing the relevant handler.boolean
hasHandler(@NotNull String effect)
Determines if the given effect has a registered handler.boolean
isClosed()
void
registerCheck(@NotNull Function<Request,CheckResult> check)
Registers a check which will be called for every incomingRequest
.void
registerCheck(@NotNull Supplier<CheckResult> check)
Registers a check which will be called for every incomingRequest
.void
registerHandler(@NotNull String effect, @NotNull Consumer<Request> handler)
Registers an effect handler which does not immediately return aResponse
.void
registerHandler(@NotNull String effect, @NotNull Function<Request,Response> handler)
Registers a function to handle an effect.void
registerHandlers(@NotNull Object object)
Registers method handlers within a class.static CrowdControlServerBuilder
server()
Returns a builder for a newCrowdControl
instance operating in server mode.void
shutdown()
Deprecated.providing error messages viashutdown(String)
is recommendedvoid
shutdown(@Nullable Request cause, @Nullable String reason)
Shuts down the internal connection to the Crowd Control server and sends a corresponding error message to the streamer(s).void
shutdown(@Nullable String reason)
Shuts down the internal connection to the Crowd Control server and sends a corresponding error message to the streamer(s).void
write(@NotNull Response response)
-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface dev.qixils.crowdcontrol.socket.SocketManager
getSource
-
-
-
-
Method Detail
-
client
@AvailableSince("3.0.0") public static CrowdControlClientBuilder client()
Returns a builder for a newCrowdControl
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 newCrowdControl
instance operating in server mode. It will allow numerous Crowd Control clients to connect.- Returns:
- a new server builder
- Since:
- 3.0.0
-
buildResponse
public @NotNull Response.Builder buildResponse()
- Specified by:
buildResponse
in interfaceRespondable
- Specified by:
buildResponse
in interfaceSocketManager
-
getIP
@AvailableSince("1.0.0") @Nullable @CheckReturnValue public @Nullable String getIP()
Returns the IP that theSocketManager
will listen on. If running in server mode, this will be null.- Specified by:
getIP
in interfaceServiceManager
- Returns:
- IP if available
- Since:
- 1.0.0
-
getPort
@AvailableSince("1.0.0") @CheckReturnValue public int getPort()
Returns the port that theSocketManager
will listen on.- Specified by:
getPort
in interfaceServiceManager
- Returns:
- IP port
- 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 interfaceServiceManager
- Returns:
- password required to connect
- Since:
- 3.0.0
-
addConnectListener
@AvailableSince("3.4.0") public void addConnectListener(@NotNull @NotNull Consumer<@NotNull SocketManager> consumer)
Sets a consumer to be called when a newCrowd Control instance
connects.- Specified by:
addConnectListener
in interfaceSocketManager
- Parameters:
consumer
- consumer to be called- Since:
- 3.4.0
-
registerHandlers
@AvailableSince("1.0.0") public void registerHandlers(@NotNull @NotNull Object object)
Registers method handlers within a class. These methods must:- be public
- have the
Subscribe
annotation with a non-null effect name - only one parameter, which has the type
Request
- a return type of one of the following:
Response
Response.Builder
- Void (assumes you will call
Response.send()
yourself)
- Parameters:
object
- class instance to register- Since:
- 1.0.0
-
registerHandler
@AvailableSince("1.0.0") 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 handlehandler
- function to handle the effect- Since:
- 1.0.0
- See Also:
registerHandler(String, Consumer)
-
registerHandler
@AvailableSince("2.0.0") public void registerHandler(@NotNull @NotNull String effect, @NotNull @NotNull Consumer<Request> handler)
Registers an effect handler which does not immediately return aResponse
. It is expected to callResponse.send()
on its own.- Parameters:
effect
- name of the effect to handlehandler
- 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 incomingRequest
. A resulting value ofCheckResult.DISALLOW
will result in aFAILURE
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 incomingRequest
. A resulting value ofCheckResult.DISALLOW
will result in aFAILURE
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 incomingRequest
by executing the relevant handler.- Specified by:
handle
in interfaceRequestManager
- Parameters:
request
- an incoming request- Since:
- 1.0.0
-
shutdown
@AvailableSince("1.0.0") @Deprecated public void shutdown()
Deprecated.providing error messages viashutdown(String)
is recommendedShuts down the internal connection to the Crowd Control server.- Specified by:
shutdown
in interfaceSocketManager
- Since:
- 1.0.0
- See Also:
shutdown(String)
,shutdown(Request, String)
-
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 interfaceSocketManager
- 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 interfaceSocketManager
- Parameters:
cause
- cause for shutting downreason
- the reason for shutting down- Since:
- 3.1.0
-
getSources
@NotNull public @NotNull Set<Request.Source> getSources()
- Specified by:
getSources
in interfaceSocketManager
-
getConnections
@NotNull public @NotNull List<? extends SocketManager> getConnections()
- Specified by:
getConnections
in interfaceSocketManager
-
isClosed
public boolean isClosed()
- Specified by:
isClosed
in interfaceSocketManager
-
write
public void write(@NotNull @NotNull Response response) throws IOException
- Specified by:
write
in interfaceSocketManager
- Throws:
IOException
-
getDisplayName
@NotNull public @NotNull String getDisplayName()
- Specified by:
getDisplayName
in interfaceSocketManager
-
-