From 5f13ecae34c7f5701184e71b0c88949cf3797674 Mon Sep 17 00:00:00 2001 From: issork Date: Wed, 15 Feb 2023 17:07:26 +0100 Subject: [PATCH] updated README --- Gift.gd | 4 +-- README.md | 74 +++++++++++++++++++++++++--------------- addons/gift/gift_node.gd | 3 +- 3 files changed, 50 insertions(+), 31 deletions(-) diff --git a/Gift.gd b/Gift.gd index 252e6b0..17aac0a 100644 --- a/Gift.gd +++ b/Gift.gd @@ -75,8 +75,8 @@ func _ready() -> void: # Send a whisper to target user # whisper("TEST", initial_channel) -func on_follow(data) -> void: - print(data) +func on_follow(data : Dictionary) -> void: + print("%s followed your channel!" % data["user_name"]) func on_chat(data : SenderData, msg : String) -> void: %ChatContainer.put_chat(data, msg) diff --git a/README.md b/README.md index f1b3ef3..9b79898 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # GIFT Godot IRC For Twitch addon +To use this plugin, you need to create a new application on dev.twitch.tv to get a client ID and a client secret. + If you require help, feel free to join my >[Discord Server](https://discord.gg/28DQbuwMM2)< and ask your questions <3 - [Examples](https://github.com/MennoMax/gift#Examples) @@ -23,35 +25,31 @@ The following code is also [included](https://github.com/MennoMax/gift/blob/mast extends Gift func _ready() -> void: - super._ready() cmd_no_permission.connect(no_permission) chat_message.connect(on_chat) + channel_follow.connect(on_follow) # I use a file in the working directory to store auth data # so that I don't accidentally push it to the repository. # Replace this or create a auth file with 3 lines in your # project directory: - # - # + # + # # var authfile := FileAccess.open("./auth", FileAccess.READ) - var botname := authfile.get_line() - var token := authfile.get_line() + client_id = authfile.get_line() + client_secret = authfile.get_line() var initial_channel = authfile.get_line() - connect_to_twitch() - await(twitch_connected) - - # Login using your username and an oauth token. - # You will have to either get a oauth token yourself or use - # https://twitchapps.com/tokengen/ - # to generate a token with custom scopes. - authenticate_oauth(botname, token) - request_caps() - if(await(login_attempt) == false): - print("Invalid username or token.") - return - join_channel(initial_channel) + # When calling this method, a browser will open. + # Log in to the account that should be used. + await(authenticate(client_id, client_secret)) + var success = await(connect_to_irc()) + if (success): + request_caps() + join_channel(initial_channel) + events.append("channel.follow") + await(connect_to_eventsub()) # Adds a command with a specified permission flag. # All implementations must take at least one arg for the command info. @@ -101,6 +99,9 @@ func _ready() -> void: # Send a whisper to target user # whisper("TEST", initial_channel) +func on_follow(data : Dictionary) -> void: + print("%s followed your channel!" % data["user_name"]) + func on_chat(data : SenderData, msg : String) -> void: %ChatContainer.put_chat(data, msg) @@ -131,7 +132,6 @@ func list(cmd_info : CommandInfo, arg_ary : PackedStringArray) -> void: msg += arg_ary[arg_ary.size() - 1] chat(msg) - ``` *** @@ -139,9 +139,11 @@ func list(cmd_info : CommandInfo, arg_ary : PackedStringArray) -> void: ## API ### Exported Variables -- **command_prefix**: PackedStringArray - Prefixes for commands. Every message that starts with one of these will be interpreted as one. +- **command_prefix**: Array[String] - Prefixes for commands. Every message that starts with one of these will be interpreted as one. - **chat_timeout** : float - Time to wait before sending the next chat message. Values below ~0.31 will lead to a disconnect at 100 messages in the queue. -- **disk_cache** : bool - If true, badges and emotes will be cached on the disk instead. +- **scopes** : Array[String] - Scopes to request when creating your user token. Check https://dev.twitch.tv/docs/authentication/scopes/ for a list of all available scopes. +- **events** : Array[String] - Events to subscribe to with the EventSub. Full list available at https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/ +- **disk_cache** : bool - If true, badges and emotes will be cached on the disk instead of only in RAM. - **disk_cache_path** : String - Path to the cache folder on the hard drive. *** @@ -149,24 +151,40 @@ func list(cmd_info : CommandInfo, arg_ary : PackedStringArray) -> void: ### Signals: |Signal|Params|Description| |-|-|-| -|twitch_connected|-|The underlying websocket successfully connected to Twitch.| -|twitch_disconnected|-|The connection has been closed. Not emitted if Twitch announced a reconnect.| -|twitch_unavailbale|-|Could not establish a connection to Twitch.| -|twitch_reconnect|-|Twitch requested the client to reconnect. (Will be unavailable until next connect)| -|login_attempt|success(bool) - wether or not the login attempt was successful|The client tried to login.| +|twitch_connected|-|The underlying websocket successfully connected to Twitch IRC.| +|twitch_disconnected|-|The connection has been closed. Not emitted if Twitch IRC announced a reconnect.| +|twitch_unavailbale|-|Could not establish a connection to Twitch IRC.| +|twitch_reconnect|-|Twitch IRC requested the client to reconnect. (Will be unavailable until next connect)| +|-|-|-| +|user_token_received|token_data(Dictionary)|User token from Twitch has been fetched.| +|user_token_valid|-|User token has been checked and is valid.| +|user_token_invalid|-|User token has been checked and is invalid.| +|login_attempt|success(bool) - wether or not the login attempt was successful|The client tried to login to Twitch IRC. Returns true if successful, else false.| +|-|-|-| |chat_message|sender_data(SenderData), message(String)|User sent a message in chat.| |whisper_message|sender_data(SenderData), message(String)|User sent a whisper message.| |unhandled message|message(String), tags(Dictionary)|Unhandled message from Twitch.| |cmd_invalid_argcount|cmd_name(String), sender_data(SenderData), cmd_data(CommandData), arg_ary(PackedStringArray)|A command has been called by a chatter with an invalid amount of args.| |cmd_no_permission|cmd_name(String), sender_data(SenderData), cmd_data(CommandData), arg_ary(PackedStringArray)|A command has been called by a chatter without having the required permissions.| |pong|-|A ping from Twitch has been answered with a pong.| +|-|-|-| +|events_connected|-|The underlying websocket sucessfully connected to Twitch EventSub.| +|events_unavailable|-|The connection to Twitch EventSub failed.| +|events_disconnected|-|The underlying websocket disconnected from Twitch EventSub.| +|events_id(id)|id(String))|The id has been received from the welcome message.| +|events_reconnect|-|Twitch directed the bot to reconnect to a different URL.| +|events_revoked|event(String), reason(String)|Twitch revoked a event subscription| +Events from EventSub are named just like their subscription name, with all '.' replaced by '_'. +Example: channel.follow emits the signal channel_follow(data(Dictionary)) *** ### Functions: |Function|Params|Description| |-|-|-| -|authenticate_oauth|nick(String) - the accoutns username, token(String) - your oauth token|Authenticate yourself to use the Twitch API. Check out https://twitchapps.com/tokengen/ to generate a token.| +|authenticate|client_id(String), client_secret(String)|Request a OAUTH token from Twitch with your client_id and client_secret| +|connect_to_irc|-|Connect to Twitch IRC. Make sure to authenticate first.| +|connect_to_eventsub|url(String) - only used when Twitch requests a reconnect to a specific URL|Connect to Twitch EventSub. Make sure to authenticate first.| |request_caps|caps(String) - capabilities to request from twitch|Request capabilities from Twitch.| |send|text(string) - the UTF8-String that should be sent to Twitch|Sends a UTF8-String to Twitch over the websocket.| |chat|message(String), channel(String) - DEFAULT: Only connected channel|Sends a chat message to a channel.| @@ -187,7 +205,7 @@ func list(cmd_info : CommandInfo, arg_ary : PackedStringArray) -> void: #### CommandData ##### Data required to store, execute and handle commands properly. -- **func_ref** : FuncRef - Function that is called by the command. +- **func_ref** : Callable - Function that is called by the command. - **permission_level** : int - Permission level required by the command. - **max_args** : int - Maximum number of arguments this command accepts. cmd_invalid_argcount is emitted if above this number. - **min_args** : int - Minimum number of arguments this command accepts. cmd_invalid_argcount is emitted if below this number. diff --git a/addons/gift/gift_node.gd b/addons/gift/gift_node.gd index d06c00b..33f0993 100644 --- a/addons/gift/gift_node.gd +++ b/addons/gift/gift_node.gd @@ -40,7 +40,7 @@ signal events_disconnected # The id has been received from the welcome message. signal events_id(id) # Twitch directed the bot to reconnect to a different URL -signal events_reconnect() +signal events_reconnect # Twitch revoked a event subscription signal events_revoked(event, reason) @@ -426,6 +426,7 @@ func connect_to_irc() -> bool: connected = true return success +# Connect to Twitch EventSub. Make sure to authenticate first. func connect_to_eventsub(url : String = "wss://eventsub-beta.wss.twitch.tv/ws") -> void: eventsub = WebSocketPeer.new() eventsub.connect_to_url(url)