Xive for Streamer.bot
=====================

Needs Streamer.bot 1.0 or newer, on Windows.

What it does
------------
Triggers (Custom -> Xive):
  - Follow, Gift, Sparks, Subscription, Gifted Subs, Supporter Tier, Raid
  - Surge (when it starts and each level it climbs)
  - Reward Redemption, plus one trigger per channel point reward (live only)
  - TTS
  - Chat Message
  - Stream Online, Stream Offline
  - Signed In

Commands:
  - Your Streamer.bot commands also answer Xive chat, with their aliases,
    cooldowns and settings
  - Command (Any) and Command Cooldown triggers

Actions:
  - Chat: send, reply, delete a message, pin, unpin
  - Moderation: timeout, remove timeout, ban, unban
  - Roles: add or remove moderators and VIPs
  - Chat settings: slow mode, followers-only, emote-only, minimum account
    age, GIFs, read current settings
  - Stream: set title, set category
  - Poll, ad break, raid
  - Look up a viewer (follow date, sub, mod, VIP), list viewers, pick a
    random viewer
  - Complete or reject a channel point redemption

Install
-------

1. Unzip this file.

2. Close Streamer.bot. Copy Xive.Streamerbot.dll into the "dlls" folder inside
   your Streamer.bot folder (make the folder if it is not there).

3. Open XiveImport.bot in Notepad and copy all of it (Ctrl+A, Ctrl+C). Start
   Streamer.bot, click Import, paste it into the Import String box, then click
   Import. This adds four actions in a "Xive" group:
     - Xive • Start        starts Xive whenever Streamer.bot starts
     - Xive • Open window  opens the Xive window
     - Xive • Send chat    posts the xiveMessage argument to your Xive chat
     - Xive • Reference    never runs. Open it to see every Xive trigger and
                           action with what it takes, and copy ready-made
                           action sub-actions out of it.

4. Restart Streamer.bot (or run "Xive • Open window"). In the Xive window, click
   Connect Xive account and sign in. You only do this once.

Using it
--------
Right-click any action -> Triggers -> Add -> Custom -> Xive, and pick an event:
Follow, Gift, Sparks, Subscription, Gifted Subs, Supporter Tier, Raid, Surge,
Reward Redemption, TTS, Chat Message, Stream Online, Stream Offline.

Channel point rewards: each reward also has its own trigger under
Custom -> Xive -> Rewards.

Commands: your Streamer.bot commands work in Xive chat too. On the command's
action, add the trigger Custom -> Xive -> Commands -> (the command's name).
A new command shows up after you save it.

Reconnect (in the Xive window) reloads everything as if Streamer.bot had
just started: your commands, channel point rewards, stream title and
category, and the connection to Xive. Only a deleted or renamed command or
reward still needs a restart to leave the trigger menu.

To post in Xive chat: add a Set Argument sub-action for "xiveMessage", then a
Run Action sub-action that runs "Xive • Send chat".

Send as your channel bot: your Xive channel has its own bot. Its name and
avatar start as yours; change them in Creator Studio. To post as the bot, add
one more Set Argument before Run Action:
     Variable Name:  xiveSendAs
     Value:          bot
Use "me" to post as yourself. SendReply reads xiveSendAs too. Actions that do
not set it use "Send chat as" in the Xive window, which starts on Me, so the
actions you already have keep posting as you.

Other actions (timeout, ban, title, category, poll, raid and more): add
Core -> C# -> Execute C# Method, pick "Xive loader", then pick the action.
Set its xive... arguments first with Set Argument.

Updating: close Streamer.bot, replace Xive.Streamerbot.dll, start it again.
If Streamer.bot says to import XiveImport.bot again, do that too.

Example: thank a new follower in Xive chat
------------------------------------------
1. Actions tab: right-click the action list -> Add. Name it
   "Thank Xive follower" and click OK.

2. Trigger: with that action selected, right-click the Triggers box ->
   Add -> Custom -> Xive -> Channel -> Xive Follow.

3. Message: right-click the Sub-Actions box -> Add -> Core -> Arguments ->
   Set Argument.
     Variable Name:  xiveMessage
     Value:          Thanks for the follow, %user%! Welcome in.
   Click OK.

4. Send it: right-click the Sub-Actions box -> Add -> Core -> Actions ->
   Run Action. Pick "Xive • Send chat", tick Run Immediately, click OK.

   The action now reads:
     Triggers:     Xive Follow
     Sub-Actions:  Set Argument  xiveMessage = Thanks for the follow, %user%! ...
                   Run Action    Xive • Send chat  (Run Immediately)

5. Test it: in the Xive studio, use Send test alert -> Follow. The message
   appears in your Xive chat. This works while you are offline too: the
   message goes to your channel's offline chat (see below).

The same steps work for any trigger: swap Xive Follow for another one and
use its arguments from the list below, for example
   Gift:          %user% sent %giftName%! Thank you!
   Subscription:  %user% subscribed for %monthsSubscribed% months!
   Raid:          %user% is raiding with %viewers% viewers!

To skip test alerts, add Core -> Logic -> If/Else before Set Argument:
isTest Equals True -> Break.

Example: !followage
-------------------
Shows how long someone has followed you, like Twitch's %followAgeLong%.

1. In Streamer.bot make a command "!followage" and an action for it, with
   the trigger Custom -> Xive -> Commands -> !followage.
2. Sub-actions, in order:
     Set Argument   xiveUserId = %userId%      (the person who typed it)
     Core -> C# -> Execute C# Method -> Xive loader -> GetUserInfo
     Set Argument   xiveMessage = %user% has been a Beautiful Flocker for %followAgeLong%
     Run Action     Xive • Send chat
3. GetUserInfo sets:
     followAgeLong   1 year, 2 months, 3 days
     followAge       1y 2mo 3d
     followAgeDays   428
     xiveTargetIsFollowing   True or False (empty follow age when False)
   To answer non-followers differently, add an If/Else on
   xiveTargetIsFollowing before the message.

To check someone else ("!followage name"), set xiveUser = %input0% instead
of xiveUserId.

Offline chat
------------
Xive chat keeps working while you are offline. Viewers on your channel page,
and Streamer.bot, can still chat; Chat Message and command triggers fire and
Send chat posts there. Offline chat is not saved: it clears when the page is
refreshed, and replies, GIFs and pins are live-only. When you go live,
Streamer.bot switches to your stream's chat by itself.

Trigger arguments
-----------------
Use these in sub-actions as %name%, for example %user% or %giftName%.

Every Xive trigger has:
  platform       always "xive"
  xiveAccount    your Xive account name
  xiveLive       true while you are live
  xiveViewers    current viewer count
  xiveStreamId   id of the current broadcast (empty when offline)

Follow, Gift, Sparks, Subscription, Gifted Subs, Supporter Tier, Raid,
Reward Redemption and TTS also have:
  user, userName   who did it
  userId           their Xive user id
  avatarUrl        their profile picture
  amount           the event's number (its meaning depends on the event)
  count            the same, but at least 1 for Sparks, Subscription and
                   Gifted Subs
  amountUnit       what amount counts: credits, sparks, months, subs, viewers
  amountLabel      ready-made text, e.g. "5 Sparks"
  description      the event as one line of text
  eventId          unique id of the event
  eventType        follow, gift, spark, subscription, gifted-sub,
                   supporter-tier, raid, channel-points or tts
  createdAt        when it happened
  isTest           true if it came from the studio's Send test alert button

Plus, per event:

  Follow             (nothing extra)
  Gift               giftName, giftId, giftCredits, animationUrl, soundUrl
  Sparks             sparks
  Subscription       monthsSubscribed (at least 1)
  Gifted Subs        gifts (how many subs, at least 1)
  Supporter Tier     tier (the tier's name), tierKey (its fixed id; use
                     this in If/Else, because you can rename the tier)
  Raid               viewers (can be 0)
  Reward Redemption  rewardId, rewardTitle, rewardKind, rewardCost,
                     userInput (what the viewer typed; also in rawInput).
                     Only fires while you are live.
  Rewards -> (one reward)
                     the same as Reward Redemption
  TTS                message (the text to read out)

  Surge              user, userName (who started it), level, points,
                     participants, igniter, contributors (names, comma
                     separated). Fires when a surge starts and each time
                     it climbs a level.

  Chat Message       user, userName, displayName, userId, message,
                     rawInput, msgId, color, isBroadcaster, isModerator,
                     isSubscribed, isVip, isSystem

  Commands -> (one command), and Command (Any)
                     everything Chat Message has, plus the same as
                     Streamer.bot's Command Triggered: command, commandId,
                     commandName, commandSource ("xive"), commandType,
                     counter, userCounter, rawInput, rawInputEscaped,
                     rawInputUrlEncoded, input0, input1, ...,
                     inputEscaped0, ..., inputUrlEncoded0, ...
                     Regex commands also get match.count, match[0],
                     match[1], ... and any named groups.
  Command Cooldown   the same as a command except counter and
                     userCounter, plus cooldownLeft (seconds) and
                     cooldownType (global or user)

  Stream Online      streamId, title, category
  Stream Offline     streamId, title, category
  Signed In          user (your Xive account)

Note: to post in Xive chat, set xiveMessage, not message. On a Chat Message
or command trigger, message already holds what the viewer typed.
