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

@@ -4,50 +4,69 @@ func _ready() -> void:
 	connect("cmd_no_permission", self, "no_permission")
 	connect_to_twitch()
 	yield(self, "twitch_connected")
-	authenticate_oauth(<username>, <oauth_token>)
-	join_channel(<channel_name>)
 	
-	# 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("<account_name>", "<oauth_token>")
+	if(yield(self, "login_attempt") == false):
+	  print("Invalid username or token.")
+	  return
+	join_channel("<channel_name>")
+	
+	# 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 (<channel_name>)
 	# 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 <channel_name>
+	chat("TEST", "<channel_name>")
+	
+	# Send a whisper to target user
+	whisper("TEST", "<target_name>")
 
-# The cmd_data array contains [<sender_data (Array)>, <command_string (String)>, <whisper (bool)>
+# 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 [<sender_data (Array)>, <command_string (String)>, <whisper (bool)>
 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(", "))

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(<account_name>, <oauth_token>)
+  if(yield(self, "login_attempt") == false):
+    print("Invalid username or token.")
+    return
+  join_channel(<channel_name>)
+  
+  # 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 (<channel_name>)
+  # Fails, if connected to more than one channel.
+  chat("TEST")
+  
+  # Send a chat message to channel <channel_name>
+  chat("TEST", <channel_name>)
+  
+  # Send a whisper to target user
+  whisper("TEST", <target_name>)
+
+# 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
+

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.")

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"
+version="0.1.0"
+script="gift.gd"