Crowd Control SimpleTCP
Crowd Control Simple TCP is one of several methods available for pack developers to connect games to Crowd Control. It allows mods to receive purchased effects from a socket and respond with information about the execution (i.e. whether the effect was applied successfully). It uses a JSON-based message protocol and enables communication across TCP or WebSockets.
Connection Methods
The Simple TCP connector system allows for game clients to connect via one of multiple methods. There are two main settings to decide:
- TCP vs WebSocket: Determines which internet protocol the app and game mod should use to connect.
- TCP: Utilizes raw TCP sockets. Messages are encoded as null terminated UTF-8 strings (i.e. delimited by 0x00 NUL).
- WebSocket: Messages are encoded per the WebSocket standard (UTF-8 with WebSocket framing).
- Client vs Server: Determines whether the game mod or the app will host the TCP/WebSocket server.
- Client: The game mod hosts a server for the Crowd Control app to connect to. Used mostly by multiplayer games with dedicated servers.
- Server: The Crowd Control app hosts a server for the game mod to connect to. The most common choice.
Thus the available connectors are SimpleTCPClientConnector, SimpleTCPServerConnector, SimpleWebsocketClientConnector, and SimpleWebsocketServerConnector.
Further options, such as ports and authentication, are detailed here.
Protocol
Messages incoming from the Crowd Control app are considered Request objects, while messages outgoing to the Crowd Control app are considered Response objects.
The class definitions can be found here, while the written documentation can be found here.
Most Requests are expected to trigger an accompanying Response within 5 seconds, or else the Request is assumed to have failed. Some Requests do not expect a Response, such as KeepAlives, PlayerInfos, etc.
Most Requests are identified by a field id which the accompanying Response is expected to include as well. This is necessary for the app to know which Request you are Responding to.
An example of a common request would look like {"id":123,"type":1,"code":"kill_player"}. This indicates that you should start (type 1) the effect with ID kill_player. If you are successfully able to do, you should respond with something like {"id":123,"type":0,"status":0}, meaning that effect (type 0) #123 was successful (status 0).
Timed effects will have an extra property duration on the Request, representing time in integer/long milliseconds. A Response is expected up-front to state whether the effect has successfully began, along with a timeRemaining field that should initially match the duration field. Further Responses denoting if the effect gets paused (status 6) or resumed (status 7), i.e. due to the game being paused or loading, are optionally allowed, and each should include an updated timeRemaining field to keep the game and overlay in sync. Finally, a Response when the effect finishes (status 8) is not required but is allowed.