Menu
Lumberyard
User Guide (Version 1.14)

Twitch ChatPlay Lua Reference

You can use Lua scripting functions to add Twitch ChatPlay features to your game project.

For information about event buses that Lumberyard uses, see Working with the Event Bus (EBus) System.

ChatPlayRequestBus

Use ChatPlayRequestBus.Broadcast.MethodName(parameters) to make requests on this EBus.

Address policy: Single

Handler policy: Single

CreateChannel

Creates a chat channel using the specified value for channelName. Returns true if the chat channel is created successfully. Returns false if the chat channel is not created.

Parameters

string channelName

Return type

Boolean

DestroyChannel

Destroys the chat channel for the specified channel name.

Parameters

string channelName

Return type

Void

DisconnectAll

Disconnects all chat channels.

Parameters

None

Return type

Void

RegisterCredentials

Registers the specified user name and authentication token pair with Twitch ChatPlay. This pair is used when sending whispers.

Parameters

string username, string oauthToken

Return type

Void

UnregisterCredentials

Unregisters the credentials for the specified user name.

Parameters

string username

Return type

Void

UnregisterAllCredentials

Unregisters all stored credentials.

Parameters

None

Return type

Void

SendWhisper

Sends a whisper that includes a specified message from a specified sender to the specified recipient. You must register the sender credentials before using this method. See RegisterCredentials.

Returns a token that is checked against the token that is passed to the OnWhisperSent callback. See ChatPlayNotificationBus.

Parameters

string sender, string recipient, string message

Return type

Number

CreateVote

Creates Twitch ChatPlay voting functionality for the specified vote ID. You can use any unique string for the vote ID. Returns true if the voting functionality is created successfully. Returns false if the voting functionality is not created.

Parameters

string voteID

Return type

Boolean

DestroyVote

Destroys the Twitch ChatPlay voting functionality for the specified vote ID.

Parameters

string voteID

Return type

Void

ChatPlayNotificationBus

Use ChatPlayNotificationBus.Connect(self) to connect the handler and implement one or more methods in the Lua script.

Address policy: Single

Handler policy: Multiple

OnWhisperSent

Called when a whisper sends successfully. The sentToken token is associated with the whisper that was sent.

Parameters

number sentToken

Return type

Void

The following is an example of OnWhisperSent:

function MyLuaScript:OnWhisperSent(sentToken) if (sentToken == myWhisperToken) then -- My Whisper was sent successfully! end end

ChatPlayChannelRequestBus

Use ChatPlayChannelRequestBus.Event.MethodName(channelName, parameters) to make requests on this EBus.

Address policy: By ID (Twitch channel name)

Handler policy: Multiple

Connect

Connects to the channel's Twitch chat.

Parameters

None

Return type

Void

Disconnect

Disconnects the specified chat channel from Twitch chat.

Parameters

None

Return type

Void

GetConnectionState

Returns the connection state for the specified chat channel. See ConnectionState.

Parameters

None

Return type

ConnectionState

The following is an example of GetConnectionState:

connectionState = ChatPlayChannelRequestBus.Event.GetConnectionState(self.Properties.Channel); if (connectionState == ConnectionState.Disconnected) then Debug.Log("Disconnected"); elseif (connectionState == ConnectionState.Connecting) then Debug.Log("Connecting"); elseif (connectionState == ConnectionState.Connected) then Debug.Log("Connected"); elseif (connectionState == ConnectionState.Error) then Debug.Log("Error"); elseif (connectionState == ConnectionState.Failed) then Debug.Log("Failed"); end

ChatPlayChannelNotificationBus

Use ChatPlayChannelNotificationBus.Connect(self, channelName) to connect the handler and implement one or more methods in the Lua script.

Address policy: By ID (Twitch channel name)

Handler policy: Multiple

OnConnectionStateChanged

Called when the connection state for the chat channel changes. See ConnectionState.

Parameters

ConnectionState state

Return type

Void

OnKeywordMatched

Called when a registered keyword is matched.

  • keyword – Original registered keyword or regex that was matched against.

  • match – Actual matched string.

  • username – Name of the user who triggered the match.

Parameters

string keyword, string match, string username

Return type

Void

ChatPlayVoteRequestBus

Use ChatPlayVoteRequestBus.Event.MethodName(voteID, parameters) to make requests on this EBus.

Address policy: By ID (unique vote name/string)

Handler policy: Single

AddOption

Adds a vote option for the specified keyword (or regex) to the vote. Returns true if the vote option is added successfully. Returns false if the vote option is not added.

Parameters

string keyword

Return type

Boolean

RemoveOption

Removes the vote option that has the specified keyword.

Parameters

string keyword

Return type

Void

ConfigureOption

Configures the vote option using the specified keyword, and sets the vote count and enabled state.

Parameters

string keyword, number count, bool enabled

Return type

Void

OptionExists

Returns true if a vote option with the specified keyword exists. Returns false if a vote option with the specified keyword does not exist.

Parameters

string keyword

Return type

Boolean

GetOptionCount

Returns the vote count for the option with the specified keyword.

Parameters

string keyword

Return type

Number

SetOptionCount

Sets the vote count for the option with the specified keyword.

Parameters

string keyword, number count

Return type

Void

GetOptionEnabled

Returns true if a vote option with the specified keyword is enabled for voting or matching. Returns false if a vote option with the specified keyword is disabled for voting or matching.

Parameters

string keyword

Return type

Boolean

SetOptionEnabled

Sets the enabled state for the option with the specified keyword.

Parameters

string keyword, bool enabled

Return type

Void

SetChannel

Sets the associated Twitch channel for the ChatPlayVote to the specified channel name. This creates a chat channel using the specified value for channelName, if a chat channel doesn't already exist. Returns true if the chat channel is created successfully. Returns false if the chat channel is not created.

Parameters

string channelName

Return type

Boolean

ClearChannel

Clears the associated Twitch channel from the ChatPlayVote.

Parameters

None

Return type

Void

SetEnableStateAll

Sets the enabled state for all options in the ChatPlayVote.

Parameters

bool enabled

Return type

Void

SetCountAll

Sets the vote count for all options in the ChatPlayVote.

Parameters

number count

Return type

Void

SetVoterLimiting

Sets voter limiting. If true, only the first vote from each user contributes to the option count. If false, all votes from each user contributes to the option count.

Parameters

bool limiting

Return type

Void

ResetVotedList

Resets the list of users who have voted. This allows user votes to be counted again.

Parameters

None

Return type

Void