1Eggdrop Twitch Tcl Commands 2Last revised: April 25, 2020 3 4=========================== 5Eggdrop Twitch Tcl Commands 6=========================== 7 8This is an exhaustive list of all the Twitch-specific Tcl commands added to 9Eggdrop. These commands are held separate from the traditional tcl-commands.doc 10due to the unique nature of Twitch and the fact that these commands WILL NOT 11work on a normal IRC server. Again, if you try and use these commands on a 12normal IRC server they will, at best, not work and possibly have unintended 13consequences. 14 15This list is accurate for Eggdrop v1.9.0, the minimum version for which Twitch 16functionality is possible. 17 18Commands 19-------- 20 21^^^^^^^^^^^^^^^^^^^^^^^^ 22twcmd <chan> <cmd> [arg] 23^^^^^^^^^^^^^^^^^^^^^^^^ 24 25 Description: sends cmd to the server, prefixed with a '/'. This is replicates 26 the web UI functionality of sending commands such as /vip or /subscribers. Do 27 not include a '/' in the cmd. arg, if required, is a single argument, so 28 enclose multiple strings in quotes. Example: twcmd timeout "badguy 100" 29 30 Returns: 0 if command is successfully sent to the Twitch server, 1 on failure 31 32^^^^^^^^^^^^^^^^^^^ 33userstate <channel> 34^^^^^^^^^^^^^^^^^^^ 35 36 Description: provides current userstate for the Eggdrop on the given channel. 37 38 Returns: a dict containing key/value pairs for userstate values. 39 40^^^^^^^^^^^^^^^^^^^ 41roomstate <channel> 42^^^^^^^^^^^^^^^^^^^ 43 44 Description: provides current roomstate of a channel Eggdrop is on. 45 46 Returns: a dict containing key/value pairs for roomstate values. 47 48^^^^^^^^^^^^^^^^^^^^ 49twitchmods <channel> 50^^^^^^^^^^^^^^^^^^^^ 51 52 Description: maintains a list of usernames provided by Twitch as those that have moderator status on the provided channel. This list is refreshed upon join, or can manually be refreshed by using the Tcl ``twcmd`` to issue a /mods Twitch command. This list is a comprehensive list, the user does not need to be present on the channel to be included on this list. 53 54 Returns: A list of usernames designated as having moderator status by Twitch. 55 56^^^^^^^^^^^^^^^^^^^^ 57twitchvips <channel> 58^^^^^^^^^^^^^^^^^^^^ 59 60 Description: maintains a list of usernames provided by Twitch as those that have VIP status on the provided channel. This list is refreshed upon join, or can manually be refreshed by using the Tcl ``twcmd`` to issue a /vips Twitch command. This list is a comprehensive list, the user does not need to be present on the channel to be included on this list. 61 62 Returns: A list of usernames designated as having VIP status by Twitch. 63 64^^^^^^^^^^^^^^^^^^^^^^ 65ismod <nick> [channel] 66^^^^^^^^^^^^^^^^^^^^^^ 67 68 Description: checks if a user is on the moderator list maintained by Twitch (the same list accessible by the /mods command entered via the Twith web GUI). This differs from the other "normal" is* Eggdrop Tcl cmds, as this does NOT check if the user is currently on the channel (that status is unreliable on Twitch IRC). 69 70 Returns: 1 if someone by the specified nickname is on the moderator list for the channel (or any channel if no channel name is specified); 0 otherwise. 71 72^^^^^^^^^^^^^^^^^^^^^^ 73isvip <nick> [channel] 74^^^^^^^^^^^^^^^^^^^^^^ 75 76 Description: checks if a user is on the VIP list maintained by Twitch (the same list accessible by the /vips command entered via the Twith web GUI). This differs from the other "normal" is* Eggdrop Tcl cmds, as this does NOT check if the user is currently on the channel (that status is unreliable on Twitch IRC). 77 78 Returns: 1 if someone by the specified nickname is on the VIP list for the channel (or any channel if no channel name is specified); 0 otherwise. 79 80 81Binds 82----- 83 84You can use the 'bind' command to attach Tcl procedures to certain events. The 85binds listed here are in addition to the binds listed in tcl-commands.doc. 86 87Because Twitch offers an IRC gateway that significantly reduces traditional IRC 88functionality, the following binds listed in tcl-commands.doc are not 89compatible with Twitch. If they are in an existing script you are running that 90is fine, they just likely won't do anything. 91 92To remove a bind, use the 'unbind' command. For example, to remove the 93bind for the "stop" msg command, use 'unbind msg - stop msg:stop'. 94 95^^^^^ 96Flags 97^^^^^ 98Most of the following binds have "flags" listed as an argument for the bind. Flags represents a flagmask that the user, if found, must match in order for the bind to trigger. Example flag masks are: 99 100+-------+---------------------------------------------------------------------------------------+ 101| \- | Matches any user existing in Eggdrop's internal user list (added to the bot) | 102+-------+---------------------------------------------------------------------------------------+ 103| \* | Matches any user, doesn't need to be added to Eggdrop | 104+-------+---------------------------------------------------------------------------------------+ 105| +o | Matches a user with the global 'o' flag added to their handle on the Eggdrop | 106+-------+---------------------------------------------------------------------------------------+ 107| \|+f | Matches a user with the 'f' flag added on a channel to their handle on the Eggdrop | 108+-------+---------------------------------------------------------------------------------------+ 109| +m|+m | Matches a user with the 'm' flag added either globally or on a channel on the Eggdrop | 110+-------+---------------------------------------------------------------------------------------+ 111 112^^^^^^^^^^ 113Bind Types 114^^^^^^^^^^ 115 116The following is a list of bind types and how they work. Below each bind type is the format of the bind command, the list of arguments sent to the Tcl proc, and an explanation. 117 118#. CCHT (CLEARCHAT) 119 120 bind ccht <flags> <mask> <proc> 121 122 procname <nick> <chan> 123 124 Description: Called when the chat history for the channel or a user on the channel is cleared. The value of ``mask`` specified in the bind is matched against ``#channel nick!nick@nick.tmi.twitch.tv`` and can use wildcards. If a user is found that matches ``mask``, they must also match the ``flags`` mask. If the CLEARCHAT is only targeted at a specific user and not the channel, that user's nickname will appear in ``nick``, otherwise ``nick`` is empty. ``chan`` will contain the channel the CLEARCHAT was used on. 125 126#. CMSG (CLEARMSG) 127 128 bind cmsg <flags> <command> <proc> 129 130 procname <nick> <chan> <msgid> <msg> 131 132 Description: Called when a specific message on the channel is cleared. The value of ``mask`` specified in the bind is matched against ``#channel nick!nick@nick.tmi.twitch.tv`` and can use wildcards. If a user is found that matches ``mask``, they must also match the ``flags`` mask. ``nick`` contains the user's nickname, and ``chan`` will contain the channel the CLEARMSG was used on. 133 134#. HTGT (HOSTTARGET) 135 136 bind htgt <flags> <mask> <proc> 137 138 procname <target> <chan> <viewers> 139 140 Description: Called when a broadcaster starts or stops hosting another Twitch channel. ``mask`` is in the format "#channel target", where #channel is the hosting channel and target is the name of the broadcaster being hosted by #channel. Similarly for the proc, ``target`` is the name of the Twitch channel being hosted by ``chan``. A value of ``-`` in ``target`` indicates that the broadcaster has stopped hosting another channel. ``viewers`` contains the number of viewers in ``chan`` that are now watching ``target`` when hosting starts, but has been found to not be reliably provided by Twitch (often arbitrarily set to 0). 141 142#. WSPR (WHISPER) 143 144 bind wspr <flags> <command> <proc> 145 146 procname <nick> <userhost> <handle> <msg> 147 148 Description: Called when Eggdrop received a whisper from another Twitch user. The first word of the user's msg is matched against ``command``, and the remainder of the text is passed to ``msg``. ``nick`` is populated with the login name of the user messaging the Eggdrop, ``userhost`` contains nick's userhost in the format nick!nick@nick.tmi.twitch.tv. ``handle`` will match the user's handle on the bot if present, otherwise it will return a ``*``. 149 150#. WSPM (WHISPER) 151 152 bind wspr <flags> <mask> <proc> 153 154 procname <nick> <userhost> <handle> <msg> 155 156 Description: Called when Eggdrop received a whisper from another Twitch user. The msg is matched against ``mask``, which can contain wildcards. ``nick`` is populated with the login name of the user messaging the Eggdrop, ``userhost`` contains nick's userhost in the format nick!nick@nick.tmi.twitch.tv. ``handle`` will match the user's handle on the bot if present, otherwise it will return a ``*``. The full text of the whisper is stored in ``msg``. 157 158#. RMST (ROOMSTATE) 159 160 bind rmst <flags> <mask> <proc> 161 162 procname <chan> <tags> 163 164 Description: Called when Eggdrop receives a ROOMSTATE message. ``mask`` is in the format of ``#channel keys`` and can use wildcards. For example, to trigger this bind on #eggdrop for any change, you would use ``#eggdroptest *`` as the mask, or to trigger on #eggdrop specifically for the emote-only setting, you would use ``"#eggdrop *emote-only*"`` as the mask. Due to the nature of multiple keys per roomstate and uncertainty of ordering, it is recommended to use multiple binds if you wish to specify multiple key values. ``chan`` is the channel Eggdrop received the ROOMSTATE message for, and ``tags`` is a list of key/value pairs provided by the ROOMSTATE message, suitable for use as a Tcl dict. ``flags`` is ignored. 165 166#. USST (USERSTATE) 167 168 bind usst <flags> <mask> <proc> 169 170 procname <chan> <tags> 171 172 Description: Called when Eggdrop receives a USERSTATE message. ``mask`` is in the format of ``#channel keys`` and can use wildcards (see the RMST bind for additional details on format). ``chan`` is the channel Eggdrop received the USERSTATE message for, and ``tags`` is a list of key/value pairs provided in the USERSTATE message, suitable for use as a Tcl dict. ``flags`` is ignored. 173