Stream Connect Guide - besteon/Ironmon-Tracker GitHub Wiki

Stream Connect Guide

What is Stream Connect?

Stream Connect is a feature of the Ironmon Tracker that allows the Tracker to communicate with external programs, such as Streamerbot. It does so using a custom built network framework.

With Stream Connect, you and your stream viewers can use:

  • Chat Commands: Viewers can use chat commands to get data from the Tracker
  • Channel Point Redeems: Viewers can redeem rewards on your channel for fun Tracker effects
  • In-Game Events: Build custom Streamerbot triggers using a Tracker extension to respond to in-game changes, like defeating a Gym Leader

Install and Setup: Text Mode

For now, the only supported network connection mode is through Text.

Install Streamerbot

  1. Download:
    1. If you haven't already, download the Streamerbot application on your computer. Download link
    2. When you do, avoid putting Streamerbot in a folder that syncs to the cloud, such as OneDrive or Dropbox.
    3. The Text mode makes frequent updates to text files on your computer; if you have them syncing to the cloud this can 1) prevent the network from working and 2) use a lot of data on your internet connection.
    4. If you can't avoid putting it on a cloud-sync folder, you can define an override for the Tracker to use instead.
  2. Extract:
    1. After you download and extract the zip file, you can open the Streamerbot application, Streamer.bot.exe, from the extracted folder.
    2. Take note of the other folders nearby, we'll come back to these later.
  3. Login:
    1. Connect your Twitch or Youtube account to Streamerbot by logging in through the application.
    2. Click the "Platforms" tab near the top, then "Twitch" or "Youtube", then "Accounts".
    3. If you have a Twitch bot account, connect that too. Learn more about setting up a secondary bot account here.

Streamerbot-Accounts

Setup Stream Connect on Streamerbot

  1. Open Stream Connect:
    1. On Bizhawk with your Tracker open, click the Tracker settings gear icon -> Streaming -> Stream Connect.
  2. Import Code:
    1. Under the Status tab, click "Get Streamerbot Code" and copy the entire code string that appears.
    2. Then on Streamerbot, near the top of the application, click the big "Import" button.
    3. Paste the code string into the top-most box. Then click Import / OK.
    4. Be sure to restart Streamerbot after importing. This is required each time you import code from the Tracker.
  3. Link-up Connection Folder:
    1. Back on the Tracker, next to the "Connection Folder" section, click the "Set" button.
    2. Then locate the "data" folder found inside your Streamerbot folder.
    3. Click on any .json file in that folder and hit OK.
    4. Example: \Documents\Streamer.bot-x64-0.1.19\data\

Stream-Connect-Overlay

Connect the Tracker

Finally, on the Stream Connect's Status tab, click the "Connect" button near the top.

If done correctly, the Tracker should establish a connection after a few seconds.

  • If clicking the Connect button still shows a red "X" and "Offline", then the Connection Folder still needs to be "Set".
  • If the status stays yellow "Online: Waiting for connection...", then the Connection Folder is set to the wrong folder, or the Streamerbot application is not currently open and running (try restarting it).

Note: By default, the Tracker will automatically try and connect each time it starts up. You can disable this by unchecking the "Auto-connect on startup" option. If you do, however, then the Tracker will not connect when you load a new game through the New Runs Tracker feature.

Steam-Connected

List of Commands

  • ✔️: Commands that usually require a parameter to use (e.g. a Pokémon name or route name) will use contextual information if available (e.g. the 1st Pokémon on the team or the route the player is on)
  • ❌: Commands that require a parameter to use, as they need information that cannot be assumed contextually
Command Contextual Parameters Description
pokemon ✔️ name Pokémon Info: Displays useful game info for a Pokémon.
bst ✔️ name Pokémon BST: Displays the base stat total (BST) for a Pokémon.
weak ✔️ name Pokémon Weaknesses: Displays the weaknesses for a Pokémon.
move ✔️ name Move Info: Displays game info for a move.
ability ✔️ name Ability Info: Displays game info for a Pokémon's ability.
trainer ✔️ name id Trainer Info: Displays info about the most recent trainer fought, or for a specific trainer. Params: "name" for a trainer's common name, or "id" for a specific trainer id number.
route ✔️ name Route Info: Displays trainer and wild encounter info for a route or area.
dungeon ✔️ name Dungeon Info: Displays info about which trainers have been defeated for an area.
unfought dungeon sevii Unfought Trainers: Displays a list of areas ordered by lowest-level, undefeated trainers. Params: "dungeon" will check partially completed dungeons, "sevii" will check trainers on Sevii Islands, "nodoubles" will exclude double battles.
pivots ✔️ safari Pivots Seen: Displays known early game wild encounters for an area. Params: "safari" will show high-level encounters from Safari Zone areas (4 per area).
revo ✔️ name target-evo Pokémon Random Evolutions: Displays randomized evolution possibilities for a Pokémon. Params: "target-evo" if more than one natural evo available (e.g. Eevee > Espeon).
coverage ✔️ type-list fully evolved Move Coverage Effectiveness: For a list of move types, checks all Pokémon matchups for effectiveness. Params: "fully evolved" will only check against Pokémon that cannot evolve.
heals hp pp status berries Heals in Bag: Displays all healing items in the bag, or only those for a specified "category". Params: "hp" for HP healing items, "pp" for PP, "status" for status, "berries" for berry items.
tms gym hm # TM Lookup: Displays all TMs in the bag, or only those for a specified "category" or "TM #". Params: "gym" displays only TMs from Gym leaders, "hm" for acquired HMs, "#" for a single TM number.
search ❌ name Search Tracked Info: Search tracked info for a Pokémon, move, or ability "name".
searchnotes ❌ word(s) Search Notes on Pokémon: Displays a list of Pokémon with any matching "word(s)".
favorites Favorite Starters: Displays the list of favorites used for picking a starter.
theme ✔️ name Theme Export: Displays the name and code string for a Tracker theme. Params: the "name" of a theme available in the Theme Library.
gamestats Game Stats: Displays fun stats for the current game.
progress sevii Game Progress: Displays fun progress percentages for the current game. Params: "sevii" will count trainers on Sevii Islands.
log Log Randomizer Settings: If the log has been opened, displays shareable randomizer settings from the log for current game.
ballqueue Ball Queue: Displays the size of the ball queue and the current pick, if any.
about About the Tracker: Displays info about the Ironmon Tracker and game being played.
help ✔️ command Command Help: Displays a list of all commands, or help info for a specified "command".

Command Options

  • Role Permissions: Use this to individually select which user are allowed to use the Tracker Commands based on their role(s). By default, all users ("Everyone") can use the commands. These settings apply to all commands; it's not currently possible to adjust role permissions on a per-command basis.
  • Show Ball Queue info on startup: When the Tracker starts up and at the start of each new game, this will display the current Ball Queue in chat.

List of Rewards

Reward Options Description
Pick Starter Ball (One Try) left middle right random Let's the viewer pick the lab starter ball. Works for only a single attempt against the lab rival.
Pick Starter Ball (Until Out) left middle right random Let's the viewer pick the lab starter ball. Stays active until the player wins the lab rival battle.
Change Starter Favorite: #1 name Let's the viewer change the Pokémon favorite in slot 1.
Change Starter Favorite: #2 name Let's the viewer change the Pokémon favorite in slot 2.
Change Starter Favorite: #3 name Let's the viewer change the Pokémon favorite in slot 3.
Change Starter Favorite: # NAME slot name Let's the viewer change the Pokémon favorite in a specified slot "#". Must provide both
Change Tracker Theme name code Changes the Tracker theme: supply a theme code or a name of an existing theme.
Change Tracker Language language Changes the Tracker's language. Options are: English, French, German, Italian, Spanish

Reward Options

  • Send chat message if successful: After the reward is completed in full, this will display an informative message in chat
  • Auto-complete the redeem: After the reward is completed in full, this will remove/complete it from the Twitch reward queue. (NOTE: This will only work for rewards created through Streamerbot.)

Manage Events

The Tracker uses "events" to send information back to your stream's chat, as well as change what's shown on the Tracker itself. Any external source (e.g. Streamerbot) or internal source (e.g. custom Tracker extensions) can trigger an event on the Tracker.

Example Events:

  • Someone on your stream uses a channel point redeem to pick the left starter ball in the lab.
  • Someone enters the chat command !ability to see info about you lead Pokémon's ability, displayed as text in chat.
  • Someone enters the chat command !heals to see all of the healing items in your bag, displayed as text in chat.

Commands

This screen shows all available chat commands commands that your stream viewers can use to communicate with the Tracker. The command description is on top (e.g. "Ability Info") while the command itself is below it (e.g. "!ability")

  • You can enable/disable any individual command by clicking the checkbox on the left. Disabled commands won't be processed by the Tracker, and no response will be given if anyone tries to use it.
  • You can rename any command if you want, but it's recommended to leave them as default. Renaming can be helpful if you have other chatbots with similar command names.
    • Note: A command must start with the character !, followed by any alpha-numeric combination; no spaces.
  • Click the "Role Permissions" button to change who is allowed to use your commands. By default, everyone can use them, however for larger streams you may find restricting commands to only a certain sub-group of chat viewers is ideal.

Commands

Rewards

NOTE: Rewards are only available on Twitch.

This screen shows all available channel point redeems that your stream viewers can use to interact with the Tracker. The reward description and function is on top (e.g. "Change Tracker Theme"), and the Twitch channel redeem it's linked up to on your channel will be shown below it.

Reward events are optional to use; add as few or as many as you like. In order to use these Rewards events, you'll first need to link them to your Twitch Channel Rewards. In this way, when a stream viewer redeems a reward, the Tracker will detect that event and perform the associated action or change.

  • To link a reward, click the "Add" button next to the reward event you want to use. Then select your Twitch channel point redeem to link it to. If you don't have one yet you want to use, simply create one through Twitch dashboard or Streamerbot "Channel Point Rewards"
    • Note: It's recommended to create or move your existing Twitch rewards to Streamerbot if you want automatically fulfill/cancel redeems for you.
  • You can enable/disable any individual reward by clicking the checkbox on the left. Disabling a reward on the Tracker won't disable it on your Twitch rewards list, so you may want to disable it there too.
  • You can also change the "Options" for each individual reward, such as sending a message if the reward was successfully completed or allowing Streamerbot to fulfill or cancel the Twitch redemption for you.

Rewards

Game Triggers

Unlike chat commands or channel rewards, game events are triggered from the Pokémon game itself. At the moment, there aren't any game events available by default.

They can, however, be added through custom Tracker extensions. See the Integrating with Tracker Extensions section below.

Game

Developer Section

The Stream Connect feature offers a handful of developer options for those knowledgeable with Tracker Code or who are more familiar with Streamerbot. Read more about them below.

Integrating with Tracker Extensions

Custom Tracker extensions can add new Stream Connect events to enhance your stream viewers experience.

How it works

flowchart LR
    subgraph Tracker
        direction TB
        t1[Extension Code] --> t2[Trigger Game Event]
        t2 --> t3[Send Global Variable](/besteon/Ironmon-Tracker/wiki/Send-Global-Variable)
    end
    subgraph Streamerbot
        direction TB
        s1[Global Variable Updated](/besteon/Ironmon-Tracker/wiki/Global-Variable-Updated) --> s2[Do Actions]
    end
    g1[Pokémon Game] --> Tracker
    Tracker --> Streamerbot

Write Tracker extension code to watch for conditions to occur in the game. When they do, trigger your custom Game event to send information to Streamerbot; info is sent/received through Global Variables.

Code Usage

To add a new event, add code to your extension's startup function:

  • For chat commands or stream rewards, use EventHandler.addNewEvent(event)
  • For game triggers, use EventHandler.addNewGameEvent(eventKey, fulfillFunc, name)

You'll also want to remove this event when the extension is disabled. To do so, simply add this code to your extensions unload function: EventHandler.removeEvent(eventKey)

Command and Reward events will trigger automatically when a stream viewer uses them. For Game events, the Tracker extension will need to trigger these itself, based on whatever conditions you decide on. To trigger game events, use: EventHandler.triggerEvent(eventKey, input)

For more information on these Tracker code functions, check out the code documentation on Github.

Example Tracker Extension

My Custom In-Game Events: CustomStreamEvents.lua (Download Link)

Example Streamerbot Trigger

The Tracker sends information to Streamerbot by updating Global Variables on Streamerbot. To watch for this change, add a new Action and a Trigger for "Global Variable Updated" with the criteria being the name of the Global Variable to watch for. Then add any Sub-Actions you want, which will perform Streamerbot tasks such as playing a sound effect or changing your stream overlay.

StreamerbotTrigger

Connection Folder Override

Note: This override is completely optional. You don't need to use it unless you want to change which folder the Tracker & Streamerbot use to communicate with each other.

By default, the Streamerbot application folder contains a "data" folder which is used to share data between Streamerbot and the Tracker. If you want to use a different folder located elsewhere on your computer, you can create an Action in Streamerbot to override this. The below import code will create a new Action for you with a trigger and a sub-action.

Note: You may have this override action already, if so, you can skip the steps 1-2 below.

Setup

  1. On Streamerbot, click the "Import" button near the top
  2. Copy/paste the below import code, then click "Import"
  3. Click the newly created "Connection Data Folder" action
  4. Double-click the "Set global" sub-action to change the override value
  5. Replace the text "NONE" with the full folder path to the folder you wish to use
  6. Finally, restart Streamerbot for the change to take effect

Subactions

Import the below code into Streamerbot:

U0JBRR+LCAAAAAAABACNU8uO0zAU3SPxD1bWk8p5dNKyQwwDbDoSGkACzcKxb1oLxw6OPZ1q1H/HdpI26QOxSeR77vOce1/fvkEoegbdciWjdyi7CQZeN0qb7wdz2plrLnlt66M9wrN0lkQ9CoY426t/uKckNXiXR03ob9DoXgnmfg+umOYMuiDnR6zZKO09vz3e/ST0ABy7ipIZnuEDwKClmjemB39sQCKQpBTAbtCWC4FUXwSZDSAGFbHCIKqkBOqjUNX1YlRwUBJQ2wDlFQeGuAzG1pYxCd6RL7vvZmRkMmPn0DrLr86CBijAnPn+YJGxFMgiBsKSOE/KKl6SAsdlkpCCFMsCqnSYLYT9sWA9ddIKMbb3MzrEaAsT5IUKy+Beq/ozb43SuwtOgyAfjjzcuXF6YSYdrLWyzVi8L9LAWpNAx9iRiC3ZtV+tvFBPE8lU/Z72OlVEtBPc6UGt1iDNJdRovl67DRhze8LviOO8KJYl5EmcLXIS5+4blxgXcQbzChdVXuLydtx4V2LXeEIKfHuKXGX64tBjeH98PE2IOt+US9O41TZckp4yfFr5mWjuO1v1Uh5X2it5LmQIavwdtebqOK2ymvp0yXk5ERYxWj2sPp7l7Zhncww0kJ7k1H2KPF5UiaOfUMjmdDHHy+wsdAt8vfGyu7O+okqSpqfIsJUndxGwfyvGJYMXX+7/pfrkiwW9nqZLKwRpWmAjfID7hIN/d8eTFC68rt1ZTI2G1/2ih1Quzf4vbS0tFJgFAAA=