SimpleJSON Structure Reference

Optional fields that are not included in a message may be omitted or set to null. Compliant implementations must support both forms. Client implementations must be prepared to receive messages with additional fields that are not documented here, and should ignore any fields they do not recognize.

Effect Requests (Crowd Control-Initiated)

When a viewer purchases an effect on Crowd Control, an effect request is sent over the channel as a UTF-8 string containing a JSON payload.

Name	Type	Value	Notes
id	uint	The request ID, all responses to this request should contain the same ID value.	These are not guaranteed to be sequential or increasing.
code	string?	The identifier of the requested effect.	Only present on request types 0 (Test), 1(Start) and 2 (Stop).
message	string?	A secondary text value associated with the request.	Contains flavortext on effect requests but may also be used for login information.
parameters	object?[]?		This field contains any non-quantity parameters that the user has selected, if applicable.
quantity	uint?		This field contains the quantity that the user has selected, if applicable.
targets	Target?[]?	For packs on multiplayer servers, contains Target structures indicating which player should be targeted by an effect request.
duration	long?	The requested duration of the effect, in milliseconds.	An option to report this value as decimal seconds (double?) will be available in a future release.
viewer	string?	The displayable name of the viewer who requested the effect.	Returns “the crowd” if multiple viewers are present.
viewers[]	Target?[]?	Contains Target structures indicating which viewer(s) requested the effect.
cost	int?	The price that the viewer(s) paid for the effect, in coins.
type	RequestType (int)	The type of message. See RequestType enum below.	This is EffectStart and appears as an integer value.

Effect Responses (Game-Initiated)

Name	Type	Value	Notes
id	uint	The request ID, all responses to a request should contain the same ID value.	This should be 0 for game-initiated messages.
code	string?	The identifier of the requested effect.
status	EffectStatus	Indicates the status of the effect request or class.
message	string?	A secondary text value associated with the request.	Used for login information, omitted otherwise.
messageID	StandardErrors?	A standard error code associated with the message, if applicable.	This field is encoded as a camel-case string value and is only present when an error occurs. In future releases, the error message corresponding to this value will take precidence over the message field when displaying errors to non-English-language users.
timeRemaining	long?	The requested duration of the effect, in milliseconds.	An option to report this value as decimal seconds (double?) will be available in a future release.
type	ResponseType (int)	Indicates the type of message. See ResponseType enum below.	This is EffectStart and appears as an integer value.

Data Requests (Crowd Control-Initiated)

Name	Type	Value	Notes
id	uint	The request ID, all responses to this request should contain the same ID value.	These are not guaranteed to be sequential or increasing.
key	string	The key of the data to request.	This should be a string that identifies the data you want to retrieve.
type	RequestType (int)	The type of message. See RequestType enum below.	This is DataRequest and appears as an integer value.

Data Responses (Game-Initiated)

Name	Type	Value	Notes
id	uint	The request ID, all responses to a request should contain the same ID value.	This should be 0 for game-initiated messages.
key	string	The key corresponding to the requested value.	This matches the key from the data request.
value	object?	The value returned by the client.	This can be any JSON value, including null.
status	EffectStatus	The status of the request.	Uses the same status values as effect responses.
timeRemaining	long?	The due time of the request, if applicable, in milliseconds.	This is milliseconds, not seconds.
message	string?	The message from the client, if any.	Omitted when not needed.
type	ResponseType (int)	Indicates the type of message. See ResponseType enum below.	This is DataRequest and appears as an integer value.

Generic Event Requests (Crowd Control-Initiated)

Name	Type	Value	Notes
id	uint	The request ID.	These are not guaranteed to be sequential or increasing.
eventType	string	The type of event.
data	object?	The data associated with the event.	This is a JSON object containing event-specific fields.
internal	bool	Indicates that this event is locally-generated.
type	RequestType (int)	The type of message. See RequestType enum below.	This is GenericEvent and appears as an integer value.

Generic Event Responses (Game-Initiated)

Name	Type	Value	Notes
id	uint	The request ID associated with the message, if any.	For game-initiated messages this is typically 0 or omitted.
eventType	string	The type of event.
data	object?	The data associated with the event.	This is a JSON object containing event-specific fields.
internal	bool	Indicates that this event is locally-generated.	Serialized using the JSON property name internal.
type	ResponseType (int)	Indicates the type of message. See ResponseType enum below.	This is GenericEvent and appears as an integer value.

Game State Requests (Crowd Control-Initiated)

Asks the game whether it's ready for effects and if not why.

Name	Type	Value	Notes
id	uint	The request ID.	These are not guaranteed to be sequential or increasing.
type	RequestType (int)	The type of message. See RequestType enum below.	This is GameUpdate and appears as an integer value.

Game State Updates (Game-Initiated)

Name	Type	Value	Notes
id	uint	The request ID associated with the message, if any.	For game-initiated messages this is typically 0 or omitted.
state	GameState (string)	The current state of the game.	See Game State Enumeration below.
message	string?	The message from the client, if any.	Omitted when not needed.
type	ResponseType (int)	Indicates the type of message. See ResponseType enum below.	This is GameUpdate and appears as an integer value.

Login Requests (Crowd Control-Initiated)

Name	Type	Value	Notes
id	uint	The request ID.	These are not guaranteed to be sequential or increasing.
login	string?	The login name of the user.
password	string?	The password of the user.
type	RequestType (int)	The type of message. See RequestType enum below.	This is Login and appears as an integer value.

Game State Enumeration

Name	Description	Notes
unknown	The game state is unknown.	Used when the game is not running or the state cannot be determined due to effect pack or connector problems.
ready	The game is running and is ready to receive effects.	This is the only game state where effects can be processed.
error	The game is in an errored or crashed state.
unmodded	The game does not have the required mod(s) installed.
badGameSettings	The current game settings are not compatible with Crowd Control.
wrongVersion	The game is the wrong version.
notFocused	The game is not focused.
loading	The game is in a loading state.
paused	The game is paused.
wrongMode	The game is in a state that is not compatible with Crowd Control.	Used for states such as a title menu or alternate game mode.
safeArea	The game is in a safe area.	Used for areas such as a town or hub.
untimedArea	The game is in an untimed area.	Used for areas such as a cutscene or tutorial.
cutscene	The game is in a cutscene.
badPlayerState	The player is not in a state to receive effects.	For example, the player may be dead or stunned.
menu	The game is in a menu other than the pause menu.
map	The game is in a map state such as a world map or overworld.	Use this only when the game is in a map scene and should not be; otherwise return Ready.
inCombat	The game is in a combat state such as a boss fight or enemy encounter.	Use this only when the game is in a combat scene and should not be; otherwise return Ready.
notInCombat	The game is in a non-combat scene such as a cutscene or tutorial.	Use this only when the game is not in a combat scene and should be; otherwise return Ready.
pipelineBusy	The game message queue is busy or full and cannot process any more messages.

RequestType Enumeration

Name	Value	Description	Notes
EffectTest	0x00	Respond as with a normal request but don't actually activate the effect.
EffectStart	0x01	A standard effect request. A response (see above) is always required.
EffectStop	0x02	A request to stop all instances of the requested effect code.
GenericEvent	0x10	Generic event callback.
DataRequest	0x20	Request for game metadata.
RpcResponse	0xD0	Response to an RPC request from the game.
PlayerInfo	0xE0	Information about the player.
Login	0xF0	Indicates that this is a login request or response.
GameUpdate	0xFD	Request for updated game state information.
KeepAlive	0xFF	Can be used in either direction to keep connections open or test connection status. Responses are neither expected nor given.

ResponseType Enumeration

Name	Value	Description	Notes
EffectRequest	0x00	A response to an effect request.	The response ID should match the request ID. Multiple responses with the same ID are allowed in the case of timed effects.
EffectStatus	0x01	A status update on a type of effect.	These messages concern the specified effect in general, not a specific instance.
GenericEvent	0x10	Generic event callback.
LoadEvent	0x18	Event callback for the player loading a game save.
SaveEvent	0x19	Event callback for the player saving a game save.
DataResponse	0x20	Response to a metadata request.
RpcRequest	0xD0	RPC request to the Crowd Control client.
Login	0xF0	Indicates that this is a login request or response.	Whether this represents a request or response depends on the value of AuthenticationMode (see below).
LoginSuccess	0xF1	Indicates the login was successful.
GameUpdate	0xFD	Game state information update.
Disconnect	0xFE	Disconnect with an optional message.
KeepAlive	0xFF	Can be used in either direction to keep connections open or test connection status. Responses are neither expected nor given.	Request ID will be 0.

EffectStatus Enumeration

Effect Instance Messages

Name	Value	Description	Notes
Success	0x00	The effect executed successfully.
Failure	0x01	The effect failed to trigger, but is still available for use. Viewer(s) will be refunded.
Unavailable	0x02	Same as Failure but the effect is no longer available for use for the remainder of the game.
Retry	0x03	The effect cannot be triggered right now, try again in a few seconds.	This is the "normal" failure response.
Queue	0x04	The effect has been queued for execution after the current one ends.	INTERNAL USE ONLY
Running	0x05	The effect triggered successfully and is now active until it ends.	INTERNAL USE ONLY
Paused	0x06	The timed effect has been paused and is now waiting.
Resumed	0x07	The timed effect has been resumed and is counting down again.
Finished	0x08	The timed effect has finished.
Wait	0x09	The effect cannot be triggered right now. Wait for the specified time period for a followup response. Does not reschedule the request.
RemoteScheduled	0x0A	The effect is being managed by a remote scheduler. Wait indefinitely.

Effect Class Messages

Name	Value	Description	Notes
Visible	0x80	The effect should be shown in the menu.
NotVisible	0x81	The effect should be hidden in the menu.
Selectable	0x82	The effect should be selectable in the menu.
NotSelectable	0x83	The effect should be unselectable in the menu.

System Status Messages

Name	Value	Description	Notes
NotReady	0xFF	The processor isn't ready to start or has shut down.

Target Structure

Name	Type	Value	Notes
id	string?	The service identifier of the player/viewer.	This is always a string.
name	string?	The display name of the player/viewer.
login	string?	The login name of the player/viewer.	This field may not be available on all services.
avatar	string?	The avatar name of the player/viewer.	This field may not be available on all services.
service	ServiceType (int)	RESERVED	RESERVED This field will appear in a future release.Appears as an integer value. See RequestType enum.

StandardErrors Enumeration

Name	Description	Notes
General Errors
Unknown	An unknown error occurred.
ExceptionThrown	An exception was thrown while attempting to run the effect.
Bad Request Errors
BadRequest	The request was invalid.
EffectUnknown	The effect was not available.
EffectDisabled	The effect was disabled.
AlreadyFailed	The effect has already failed.
CannotParseNumber	A supplied parameter could not be parsed.
UnknownSelection	A supplied parameter was unknown.
Connector Errors
ConnectorError	An unknown connector error occurred.
ConnectorReadFailure	The connector could not read from the game.
ConnectorWriteFailure	The connector could not write to the game.
ConnectorNotConnected	The connector could not connect to the game.
ConnectorNotSupported	The connector does not support the requested effect.
TCP Connector Errors
NoResponse	The connector received no response from the game.
Settings Errors
SettingsError	An error occurred while processing the pack settings.
CooldownPerEffect	The effect is on cooldown.
CooldownGlobal	Effects are on cooldown.
RetryMaxTime	The maximum retry time was exceeded.
RetryMaxAttempts	The maximum number of retry attempts was exceeded.
Session Errors
NoSession	No active game session.
SessionEnding	The game session ended before the effect could be run.
Game State Errors
BadGameState	The game state was not ready.
Game State Errors - Missing Objects
GameObjectNotFound	A required game entity was not found.
PlayerNotFound	The player was not found.
CharacterNotFound	The character or party member was not found.
EnemyNotFound	The enemy was not found.
ObjectNotFound	The object was not found.
PrerequisiteNotFound	A required object was not found.
Game State Errors - Object State
ObjectStateError	A required game entity was not in the correct state.
AlreadyInState	The character or object was already in the target state.
AlreadyAcquired	The item or object was already acquired.
AlreadyFinished	The selected objective was already finished.
NoEmptyContainers	There are no empty containers or slots available.
PartyFull	The player's group or party is full.
InvalidArea	The selected effect is not applicable or not allowed in the current area.
InvalidTarget	The selected target is not valid for the effect.
NoValidTargets	No valid targets were found.
SpawnNotAllowedHere	The selected object or enemy cannot be spawned here.
Game State Errors - Range Limits
RangeError	A value range error occurred.
AlreadyMinimum	The value was already at the minimum.
AlreadyMaximum	The value was already at the maximum.
Game Pack Errors
EffectNotImplemented	The effect is not implemented.
PackResourceMissing	A required pack resource was missing.
Emulator Errors
EmulatorNotSupported	The emulator does not support this effect.
EmulatorInvalidSetting	The emulator was not properly configured.
Game Pack State Errors
ConflictingEffectRunning	A conflicting effect is already running.
UnqueueablePending	This effect cannot be queued and another instance is already running.