CrowdControl
Inherits: Object
A client for interacting with the CrowdControl API natively in Blazium.
Description
The CrowdControl singleton allows you to connect your Blazium game to the CrowdControl interactivity service. Using this module, streamers can allow their viewers to trigger in-game effects either instantly or over a timed duration.
CrowdControl uses WebSockets for real-time interaction and HTTP polling as a fallback or auxiliary authentication context.
You must register your application on the CrowdControl Developer Portal to obtain an App ID and Secret.
Tutorials
Methods
Signals
authenticated(token: String, cc_uid: String, username: String) 🔗
Emitted when the authentication flow successfully finishes and the user is logged in. Provides the access token, unique cc_uid, and display username.
authentication_url_ready(url: String) 🔗
Emitted after requesting authentication. The game must display or open this url for the player to log in via their browser.
connection_closed(code: int, reason: String) 🔗
Emitted when the persistent WebSocket connection closes. Includes the status code and string reason.
connection_error(error: String) 🔗
Emitted when the WebSocket connection to the CrowdControl PubSub servers encounters an error.
connection_established() 🔗
Emitted when connect_to_crowdcontrol() successfully establishes a WebSocket connection.
effect_requested(effect_data: Dictionary) 🔗
Emitted when a viewer triggers an effect. The effect_data dictionary contains properties like reqId, code, and parameters. Check the code to determine which effect to apply, and respond using respond_to_effect_instant() or respond_to_effect_timed().
game_session_started(session_id: String) 🔗
Emitted when a game session has been successfully created. Effects can now be requested by viewers.
game_session_stopped() 🔗
Emitted when a game session ends.
interact_link_received(link: String) 🔗
Emitted after request_interact_link() finishes with the link players can give viewers to interact with the current game state via the browser.
rpc_error(method: String, error: String) 🔗
Emitted when an RPC call receives an error payload.
Enumerations
enum EffectStatus: 🔗
EffectStatus STATUS_SUCCESS = 0
There is currently no description for this enum. Please help us by contributing one!
EffectStatus STATUS_FAILURE = 1
There is currently no description for this enum. Please help us by contributing one!
There is currently no description for this enum. Please help us by contributing one!
EffectStatus STATUS_RETRY = 3
There is currently no description for this enum. Please help us by contributing one!
EffectStatus STATUS_QUEUE = 4
There is currently no description for this enum. Please help us by contributing one!
EffectStatus STATUS_TIMED_BEGIN = 5
There is currently no description for this enum. Please help us by contributing one!
EffectStatus STATUS_TIMED_PAUSE = 6
There is currently no description for this enum. Please help us by contributing one!
EffectStatus STATUS_TIMED_RESUME = 7
There is currently no description for this enum. Please help us by contributing one!
EffectStatus STATUS_TIMED_END = 8
There is currently no description for this enum. Please help us by contributing one!
enum EffectReportStatus: 🔗
There is currently no description for this enum. Please help us by contributing one!
There is currently no description for this enum. Please help us by contributing one!
There is currently no description for this enum. Please help us by contributing one!
There is currently no description for this enum. Please help us by contributing one!
Method Descriptions
void close() 🔗
Closes the active CrowdControl WebSocket connection and stops polling.
Error connect_to_crowdcontrol(url: String = "wss://pubsub.crowdcontrol.live/") 🔗
Initiates the WebSocket connection to the CrowdControl PubSub servers. By default, it uses the production wss url. Emits connection_established on success.
String get_auth_token() const 🔗
Returns the current authentication token obtained after a successful login. It can be cached and restored later using set_auth_token().
String get_authentication_url() const 🔗
Returns the URL that the player must visit to authorize the game with CrowdControl. Usually emitted via authentication_url_ready.
Returns the CrowdControl unique identifier for the authenticated user.
String get_connection_id() const 🔗
Returns the active WebSocket connection ID.
String get_game_session_id() const 🔗
Returns the ID of the currently active game session, or an empty string if no session is active.
String get_refresh_token() const 🔗
Returns the refresh token, if any, that can be used to seamlessly renew an expired authentication session via refresh_token().
Returns the display name of the authenticated user.
bool is_authenticated() const 🔗
Returns true if a valid authentication token is currently held.
bool is_websocket_connected() const 🔗
Returns true if the underlying WebSocket is currently connected to the PubSub servers.
void poll() 🔗
Polls the underlying WebSocket connections and message queues. You must call this every frame (e.g., in Node._process()) to ensure CrowdControl receives and processes messages.
Error refresh_token(refresh_token: String = "") 🔗
Attempts to seamlessly renew the current authentication session using a previously cached refresh token, or the provided refresh_token.
Error report_effects(effect_ids: PackedStringArray, status: EffectReportStatus, identifier_type: String = "effect") 🔗
Informs the CrowdControl service that the specified effects are now available, unavailable, visible, or hidden based on their status. Useful for dynamic game states (e.g., hiding a "Spawn Enemy" effect while the player is in a safe-zone).
Error request_authentication_http(scopes: Array = [], packs: Array = []) 🔗
Requests an authentication session through traditional HTTP polling. Use this as an alternative to request_authentication_websocket(). Wait for the authentication_url_ready signal for the authorization link.
Error request_authentication_websocket(scopes: Array = [], packs: Array = []) 🔗
Requests an authentication session through the active WebSocket. Wait for the authentication_url_ready signal, which provides a link you must present to the player to authorize the game.
CrowdControl.request_authentication_websocket()
var url = await CrowdControl.authentication_url_ready
print("Please authorize: ", url)
await CrowdControl.authenticated
print("Authenticated!")
void request_interact_link() 🔗
Requests a public interactivity link that viewers can visit to interact with the game. Connect to interact_link_received to get the generated link.
Error respond_to_effect_instant(request_id: String, status: EffectStatus, message: String = "") 🔗
Responds to an immediate effect request triggered by effect_requested. Send STATUS_SUCCESS if the effect fired, or STATUS_FAILURE if it failed.
func _on_effect_requested(data):
var req_id = data["reqId"]
var code = data["code"]
if code == "givecoins":
# give coins
CrowdControl.respond_to_effect_instant(req_id, CrowdControl.STATUS_SUCCESS, "Coins given!")
Error respond_to_effect_timed(request_id: String, status: EffectStatus, time_remaining: int, message: String = "") 🔗
Responds to a timed effect request (an effect that lasts for time_remaining milliseconds). Start the effect with STATUS_TIMED_BEGIN, and when the time expires, call this again with STATUS_TIMED_END.
# Start the effect
CrowdControl.respond_to_effect_timed(req_id, CrowdControl.STATUS_TIMED_BEGIN, 30000, "Invert Controls started.")
# Later, when the effect wears off
CrowdControl.respond_to_effect_timed(req_id, CrowdControl.STATUS_TIMED_END, 0, "Controls restored.")
void set_auth_token(token: String, refresh_token: String = "") 🔗
Restores a previously saved authentication session. This allows your game to remember the user's login without requiring them to authorize in their browser again.
void set_credentials(app_id: String, secret: String) 🔗
Configures the CrowdControl client with your Developer app ID and Secret. Must be called before connecting or authenticating.
void set_http_base_url(url: String) 🔗
Overrides the default REST HTTP base URL (which defaults to https://openapi.crowdcontrol.live).
Error start_game_session(game_pack_id: String) 🔗
Notifies the server that a new game session has begun, bound to the specified game_pack_id (which dictates the available effects).
Stops the currently active game session.