From 9cc61808455782fe9ff30642b3a627912a996069 Mon Sep 17 00:00:00 2001 From: MennoMax Date: Tue, 29 Oct 2019 19:13:22 +0100 Subject: [PATCH] version changed to 0.1.0, added chat queue, handling of twitch restarts, changed tag-value mappings, minor improvements, added documentation in README.md --- Gift.gd | 64 +++++++++----- README.md | 181 +++++++++++++++++++++++++++++++++++++++ addons/gift/gift_node.gd | 62 ++++++++++---- addons/gift/plugin.cfg | 4 +- 4 files changed, 269 insertions(+), 42 deletions(-) create mode 100644 README.md diff --git a/Gift.gd b/Gift.gd index ad3dab7..3592dc8 100644 --- a/Gift.gd +++ b/Gift.gd @@ -4,50 +4,69 @@ func _ready() -> void: connect("cmd_no_permission", self, "no_permission") connect_to_twitch() yield(self, "twitch_connected") - authenticate_oauth(, ) - join_channel() - # Adds a command with a specified permission flag. Defaults to PermissionFlag.EVERYONE - # All implementation must take at least one arg for the command data. + # 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("", "") + if(yield(self, "login_attempt") == false): + print("Invalid username or token.") + return + join_channel("") + + # Adds a command with a specified permission flag. + # All implementations must take at least one arg for the command info. + # Implementations that recieve args requrires two args, + # the second arg will contain all params in a PoolStringArray # This command can only be executed by VIPS/MODS/SUBS/STREAMER - add_command("test", self, "command_test", PermissionFlag.NON_REGULAR) - # This command can be executed by everyone - add_command("helloworld", self, "hello_world", PermissionFlag.EVERYONE) - # This command can only be executed by the streamer - add_command("streamer_only", self, "streamer_only", PermissionFlag.STREAMER) - # Command that requires exactly 1 arg. - add_command("greet", self, "greet", PermissionFlag.EVERYONE, 1, 1) - # Command that prints every arg seperated by a comma (infinite args allowed), at least 2 required - add_command("list", self, "list", PermissionFlag.EVERYONE, -1, 2) + add_command("test", self, "command_test", 0, 0, PermissionFlag.NON_REGULAR) + # These two commands can be executed by everyone + add_command("helloworld", self, "hello_world") + add_command("greetme", self, "greet_me") + + # This command can only be executed by the streamer + add_command("streamer_only", self, "streamer_only", 0, 0, PermissionFlag.STREAMER) + + # Command that requires exactly 1 arg. + add_command("greet", self, "greet", 1, 1) + + # Command that prints every arg seperated by a comma (infinite args allowed), at least 2 required + add_command("list", self, "list", -1, 2) + # Adds a command alias add_alias("test","test1") add_alias("test","test2") add_alias("test","test3") + # Or do it in a single line + # add_aliases("test", ["test1", "test2", "test3"]) # Remove a single command remove_command("test2") + # Now only knows commands "test", "test1" and "test3" remove_command("test") # Now only knows commands "test1" and "test3" - + # Remove all commands that call the same function as the specified command purge_command("test1") # Now no "test" command is known - # Send a chat message to the only connected channel ("mennomax") + # Send a chat message to the only connected channel () # Fails, if connected to more than one channel. chat("TEST") - # Send a chat message to channel "mennomax" - chat("TEST", "mennomax") - # Send a whisper to user "mennomax" - whisper("TEST", "mennomax") + + # Send a chat message to channel + chat("TEST", "") + + # Send a whisper to target user + whisper("TEST", "") -# The cmd_data array contains [, , +# Check the CommandInfo class for the available info of the cmd_info. func command_test(cmd_info : CommandInfo) -> void: print("A") -# The cmd_data array contains [, , func hello_world(cmd_info : CommandInfo) -> void: chat("HELLO WORLD!") @@ -60,5 +79,8 @@ func no_permission(cmd_info : CommandInfo) -> void: func greet(cmd_info : CommandInfo, arg_ary : PoolStringArray) -> void: chat("Greetings, " + arg_ary[0]) +func greet_me(cmd_info : CommandInfo) -> void: + chat("Greetings, " + cmd_info.sender_data.tags["display-name"] + "!") + func list(cmd_info : CommandInfo, arg_ary : PoolStringArray) -> void: chat(arg_ary.join(", ")) \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..d562032 --- /dev/null +++ b/README.md @@ -0,0 +1,181 @@ +# GIFT +Godot IRC For Twitch addon + +- [Examples](https://example.com) +- [API](https://example.com) + - [Exported Variables](https://example.com) + - [Signals](https://example.com) + - [Functions](https://example.com) + - [Utility Classes](https://example.com) + +*** + +### Examples + +The following code is also [included](https://github.com/MennoMax/gift/blob/master/Gift.gd) in this repository. +```gdscript +extends Gift + +func _ready() -> void: + connect("cmd_no_permission", self, "no_permission") + connect_to_twitch() + yield(self, "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(, ) + if(yield(self, "login_attempt") == false): + print("Invalid username or token.") + return + join_channel() + + # Adds a command with a specified permission flag. + # All implementations must take at least one arg for the command info. + # Implementations that recieve args requrires two args, + # the second arg will contain all params in a PoolStringArray + # This command can only be executed by VIPS/MODS/SUBS/STREAMER + add_command("test", self, "command_test", 0, 0, PermissionFlag.NON_REGULAR) + + # These two commands can be executed by everyone + add_command("helloworld", self, "hello_world") + add_command("greetme", self, "greet_me") + + # This command can only be executed by the streamer + add_command("streamer_only", self, "streamer_only", 0, 0, PermissionFlag.STREAMER) + + # Command that requires exactly 1 arg. + add_command("greet", self, "greet", 1, 1) + + # Command that prints every arg seperated by a comma (infinite args allowed), at least 2 required + add_command("list", self, "list", -1, 2) + + # Adds a command alias + add_alias("test","test1") + add_alias("test","test2") + add_alias("test","test3") + # Or do it in a single line + # add_aliases("test", ["test1", "test2", "test3"]) + + # Remove a single command + remove_command("test2") + + # Now only knows commands "test", "test1" and "test3" + remove_command("test") + # Now only knows commands "test1" and "test3" + + # Remove all commands that call the same function as the specified command + purge_command("test1") + # Now no "test" command is known + + # Send a chat message to the only connected channel () + # Fails, if connected to more than one channel. + chat("TEST") + + # Send a chat message to channel + chat("TEST", ) + + # Send a whisper to target user + whisper("TEST", ) + +# Check the CommandInfo class for the available info of the cmd_info. +func command_test(cmd_info : CommandInfo) -> void: + print("A") + +func hello_world(cmd_info : CommandInfo) -> void: + chat("HELLO WORLD!") + +func streamer_only(cmd_info : CommandInfo) -> void: + chat("Streamer command executed") + +func no_permission(cmd_info : CommandInfo) -> void: + chat("NO PERMISSION!") + +func greet(cmd_info : CommandInfo, arg_ary : PoolStringArray) -> void: + chat("Greetings, " + arg_ary[0]) + +func greet_me(cmd_info : CommandInfo) -> void: + chat("Greetings, " + cmd_info.sender_data.tags["display-name"] + "!") + +func list(cmd_info : CommandInfo, arg_ary : PoolStringArray) -> void: + chat(arg_ary.join(", ")) + +``` + +*** + +## API + +### Exported Variables +- **command_prefix**: PoolStringArray - 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. +- **get_badges** : bool - Wether or not badges should be downloaded and cached in RAM. +- **get_emotes** : bool - Wether or not emotes should be downloaded and cached in RAM. +- **disk_cache** : bool - If true, badges and emotes will be cached on the disk instead. +- **disk_cache_path** : String - Path to the cache folder on the hard drive. + +*** + +### 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.| +|chat_message|sender_data(SenderData), message(String), channel(String)|User sent a message in chat.| +|whisper_message|sender_data(SenderData), message(String), channel(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(PoolStringArray)|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(PoolStringArray)|A command has been called by a chater without having the required permissions.| +|pong|-|A ping from Twitch has been answered with a pong.| + +*** + +### 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.| +|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.| +|whisper|message(String), target(String)| Sends a whisper message to the specified user.| +|add_command|cmd_name(String), instance(Object), instance_func(String), max_args(int), min_args(int), permission_level(int), where(int)| Registers a command with a function to call on a specified object. You can also set min/max args allowed and where (whisper or chat) the command execution should be allowed to be requested.| +|remove_command|cmd_name(String)|Removes a single command or alias from the command registry.| +|purge_command|cmd_name(String)| Removes all commands that call the same function on the same object as the specified command.| +|add_alias|cmd_name(String), alias(String)|Registers a command alias.| +|add_aliases|cmd_name(String), aliases(PoolStringArray)|Registers all command aliases in the array.| +|join_channel|channel(String)|Joins a channel.| +|leave_channel|channel(String)|Leaves a channel.| + +*** + +### Utility Classes + +*** + +#### CommandData +##### Data required to store, execute and handle commands properly. +- **func_ref** : FuncRef - 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. +- **where** : int - Where the command should be received (0 = Chat, 1 = Whisper) + +*** + +#### CommandInfo +##### Info about the command that was executed. +- **sender_data** : SenderData - Associated data with the sender. +- **command** : String - Name of the command that has been called. +- **whisper** : bool - true if the command was sent as a whisper message. + +*** + +#### SenderData +##### Data of the sender +- **user** : String - The lowercase username of the sender. Use tags["display-name"] for the case sensitive name. +- **channel** : String - The channel in which the data was sent. +- **tags** : Dictionary - Refer to the Tags documentation; https://dev.twitch.tv/docs/irc/tags + diff --git a/addons/gift/gift_node.gd b/addons/gift/gift_node.gd index d1e1c3d..88c5f2a 100644 --- a/addons/gift/gift_node.gd +++ b/addons/gift/gift_node.gd @@ -3,10 +3,12 @@ class_name Gift # The underlying websocket sucessfully connected to twitch. signal twitch_connected -# The connection has been closed. +# The connection has been closed. Not emitted if twitch announced a reconnect. signal twitch_disconnected # The connection to twitch failed. signal twitch_unavailable +# Twitch requested the client to reconnect. (Will be unavailable until next connect) +signal twitch_reconnect # The client tried to login. Returns true if successful, else false. signal login_attempt(success) # User sent a message in chat. @@ -23,13 +25,19 @@ signal cmd_no_permission(cmd_name, sender_data, cmd_data, arg_ary) signal pong # Messages starting with one of these symbols are handled. '/' will be ignored, reserved by Twitch. -export(Array, String) var command_prefixes = ["!"] +export(PoolStringArray) var command_prefixes : Array = ["!"] +# Time to wait after each sent chat message. Values below ~0.31 will lead to a disconnect after 100 messages. +export(float) var chat_timeout = 0.32 -# Mapping of channels to their channel info, like currently connected users. -var channels : Dictionary = {} -var commands : Dictionary = {} var websocket : WebSocketClient = WebSocketClient.new() var user_regex = RegEx.new() +var twitch_restarting +# Twitch disconnects connected clients if too many chat messages are being sent. (At about 100 messages/30s) +var chat_queue = [] +onready var chat_accu = chat_timeout +# Mapping of channels to their channel info, like available badges. +var channels : Dictionary = {} +var commands : Dictionary = {} # Required permission to execute the command enum PermissionFlag { @@ -69,6 +77,11 @@ func connect_to_twitch() -> void: func _process(delta : float) -> void: if(websocket.get_connection_status() != NetworkedMultiplayerPeer.CONNECTION_DISCONNECTED): websocket.poll() + if(!chat_queue.empty() && chat_accu >= chat_timeout): + send(chat_queue.pop_front()) + chat_accu = 0 + else: + chat_accu += delta # Login using a oauth token. # You will have to either get a oauth token yourself or use @@ -80,13 +93,12 @@ func authenticate_oauth(nick : String, token : String) -> void: send("NICK " + nick.to_lower()) request_caps() -func request_caps(caps : Array = [":twitch.tv/commands", ":twitch.tv/tags", ":twitch.tv/membership"]) -> void: - for cap in caps: - send("CAP REQ " + cap) +func request_caps(caps : String = "twitch.tv/commands twitch.tv/tags twitch.tv/membership") -> void: + send("CAP REQ :" + caps) # Sends a String to Twitch. func send(text : String, token : bool = false) -> void: - assert(websocket.get_peer(1).put_packet(text.to_utf8()) == OK) + websocket.get_peer(1).put_packet(text.to_utf8()) if(OS.is_debug_build()): if(!token): print("< " + text.strip_edges(false)) @@ -97,9 +109,9 @@ func send(text : String, token : bool = false) -> void: func chat(message : String, channel : String = ""): var keys : Array = channels.keys() if(channel != ""): - send("PRIVMSG " + ("" if channel.begins_with("#") else "#") + channel + " :" + message + "\r\n") + chat_queue.append("PRIVMSG " + ("" if channel.begins_with("#") else "#") + channel + " :" + message + "\r\n") elif(keys.size() == 1): - send("PRIVMSG #" + channels.keys()[0] + " :" + message + "\r\n") + chat_queue.append("PRIVMSG #" + channels.keys()[0] + " :" + message + "\r\n") else: print_debug("No channel specified.") @@ -115,13 +127,13 @@ func data_received() -> void: message = msg[1] for tag in msg[0].split(";"): var pair = tag.split("=") - tags[pair[0]] = Array(pair[1].split(",")) + tags[pair[0]] = pair[1] if(OS.is_debug_build()): print("> " + message) handle_message(message, tags) # Registers a command on an object with a func to call, similar to connect(signal, instance, func). -func add_command(cmd_name : String, instance : Object, instance_func : String, permission_level : int = PermissionFlag.EVERYONE, max_args : int = 0, min_args : int = 0, where : int = WhereFlag.CHAT) -> void: +func add_command(cmd_name : String, instance : Object, instance_func : String, max_args : int = 0, min_args : int = 0, permission_level : int = PermissionFlag.EVERYONE, where : int = WhereFlag.CHAT) -> void: var func_ref = FuncRef.new() func_ref.set_instance(instance) func_ref.set_function(instance_func) @@ -146,7 +158,7 @@ func add_alias(cmd_name : String, alias : String) -> void: if(commands.has(cmd_name)): commands[alias] = commands.get(cmd_name) -func add_aliases(cmd_name : String, aliases : Array) -> void: +func add_aliases(cmd_name : String, aliases : PoolStringArray) -> void: for alias in aliases: add_alias(cmd_name, alias) @@ -168,10 +180,13 @@ func handle_message(message : String, tags : Dictionary) -> void: var sender_data : SenderData = SenderData.new(user_regex.search(msg[0]).get_string(), msg[2], tags) handle_command(sender_data, msg) emit_signal("chat_message", sender_data, msg[3].right(1)) + print("TAGS: " + str(tags)) "WHISPER": var sender_data : SenderData = SenderData.new(user_regex.search(msg[0]).get_string(), msg[2], tags) handle_command(sender_data, msg, true) emit_signal("whisper_message", sender_data, msg[3].right(1)) + "RECONNECT": + twitch_restarting = true _: emit_signal("unhandled_message", message, tags) @@ -201,18 +216,18 @@ func get_perm_flag_from_tags(tags : Dictionary) -> int: var flag = 0 var entry = tags.get("badges") if(entry): - for badge in entry: + for badge in entry.split(","): if(badge.begins_with("vip")): flag += PermissionFlag.VIP if(badge.begins_with("broadcaster")): flag += PermissionFlag.STREAMER entry = tags.get("mod") if(entry): - if(entry[0] == "1"): + if(entry == "1"): flag += PermissionFlag.MOD entry = tags.get("subscriber") if(entry): - if(entry[0] == "1"): + if(entry == "1"): flag += PermissionFlag.SUB return flag @@ -231,8 +246,17 @@ func connection_established(protocol : String) -> void: emit_signal("twitch_connected") func connection_closed(was_clean_close : bool) -> void: - print_debug("Disconnected from Twitch.") - emit_signal("twitch_disconnected") + if(twitch_restarting): + print_debug("Reconnecting to Twitch") + emit_signal("twitch_reconnect") + connect_to_twitch() + yield(self, "twitch_connected") + for channel in channels.keys(): + join_channel(channel) + twitch_restarting = false + else: + print_debug("Disconnected from Twitch.") + emit_signal("twitch_disconnected") func connection_error() -> void: print_debug("Twitch is unavailable.") diff --git a/addons/gift/plugin.cfg b/addons/gift/plugin.cfg index e12e110..f72b0f2 100644 --- a/addons/gift/plugin.cfg +++ b/addons/gift/plugin.cfg @@ -3,5 +3,5 @@ name="Godot IRC For Twitch" description="Godot websocket implementation for Twitch IRC." author="MennoMax" -version="0.0.1" -script="gift.gd" \ No newline at end of file +version="0.1.0" +script="gift.gd"