If Conditional Effects

One of the most powerful effects in Firebot is the conditional effect. You can find it by looking for “conditional” in the “Select New Effect” box. Alternatively, you can find it by looking through the “ALL”, “Common”, “Advanced”, and “Scripting” tabs. In order to use it in a command you will need to switch from simple mode to advanced mode so that you can search through effects. We will start with an explanation of all the things you can find in a conditional effect, followed by a simple guide for how to use them.

In brief the conditional effect allows you to choose if you want to run an effect or not based on conditions that you set. If you are familiar with any form of code it is essentially the same as an if statement in any coding language.

This is the menu for a conditional effect. It starts with the “If” condition tab open.

1. At the top you can see a plus sign with “If all ⌄ of the following conditions pass:”. This is where you add the conditions to decide if an effect will run or not. You can add more than one condition by clicking on the plus sign multiple times. You can also click on the ⌄ chevron and change “all” to “any”. This will mean that instead of having to meet every condition you set here, you can meet any of the conditions you set here and trigger the effects in this list.
2. It’s then followed by an effects list where you can add the effects that will run when the conditions you set are passed.
3. Below that you can see “Add Else IF Clause”. Here you can add additional conditional effects that will run only if the first condition you set fails to pass AND it now passes the new conditions you set. You can add as many of these as you like. They will only run if all previous conditional effects have failed to pass.
4. Finally, we reach the “Otherwise” tab. You can open this to see a new effects list. You can add effects to this list that will run only when all other conditions have failed to pass.

When you click on the plus sign to add a new condition you will be given this menu here. There are three options you can alter: TYPE, COMPARATOR, and EXPECTED VALUE.

TYPE is used to choose what kind of data you are comparing against. If you click on “Username” it will give you this dropdown menu. It gives you these options to choose from: “Username”, “Custom”, “Viewer’s Roles”, “Command Args Count” and “Follow Check”. Each with a little “?” next to them that you can hover the mouse over to see a tooltip that explains how they work.

Very quickly:

Username means that this will compare against the username of the person who triggers the command. So, if you have a chat command that any of your viewers can trigger this will check to see if the username of the person who triggers the command matches the data in the “EXPECTED VALUE” section. The EXPECTED VALUE section allows the use of variables. This allows the comparators “is”, “is not”, “contains” and “matches regex”.

Custom will allow you to compare against a value that you set yourself. This is possibly the most useful setting, and it allows you to use custom variables and the built-in set of variable commands. This has many different possible comparators. They are generally self-explanatory, but there is a small difference between “is”, “is strictly” and “is not” and “is not strictly” that will not be obvious. Sometimes in code for convenience things that can be annoying to convert to different formats can be seen as similar to each other. For example, sometimes “0” can be considered the same as “null”, because math expressions that equal 0 can be used in the same manner as null (nothing exists here), but converting an integer (0) to “null” is an extra and unnecessary step when you can simply consider 0 to be null. So “is” and “is not” can consider “0” as “null”, despite them being different types of data. However, in other applications this can cause issues. So, we also have the comparators “is strictly” and “is not strictly”. In this case it will compare against the exact data it is presented with. So “0” will not be the same as “null” and vice versa. If you are unsure which to use it is generally safer to use “is strictly” and “is not strictly”.

Viewer’s Roles compares any roles that you have assigned to your viewers. This will bring up a dropdown menu in the EXPECTED VALUE selection that allows you to select which of the viewer roles you want to use to compare against. The comparator here will allow you to choose “has role” and “doesn’t have role”.

Command Args Count will check to see how many separate words are used in the message that triggered the command. The EXPECTED VALUE here should be a number. The comparator here will allow you to use “is”, “is not”, “is greater than” and “is less than”.

Follow Check allows you to see if the person who triggers the command follows someone on Twitch. This is a very useful check to see if someone follows your channel on Twitch. You add the username of the Twitch streamer you want to check for in the EXPECTED VALUE option. You can add multiple streamers by adding each username separated by a comma. This only allows the “follows” comparator.

COMPARATOR is where you choose what kind of comparison you will make. This will be a dropdown menu with several choices to decide how Firebot will compare the TYPE against the EXPECTED VALUE. This will change based on the TYPE as discussed above. If you use a Username TYPE it will give the options “is”, “is not”, “contains” and “matches regex”. If you choose “is” then it will check to see if the username of the person who triggered the command matches the EXPECTED VALUE. If you choose “is not” it will make sure it doesn’t match. If you choose “contains” it will check to see if the EXPECTED VALUE is found anywhere in the username. And if you use “matches regex” it will allow you to enter a regular expression to check against. A regular expression is essentially a code or filter that you can construct from special characters, when you compare a string of text or numbers against the regex it will return whatever passes through the filter. I would recommend asking in the discord if you need help with regex, it can be extremely complex.

Finally, there is the EXPECTED VALUE section. This is where you enter the data you want to check against.

As mentioned previously, if you choose the Viewer’s Roles TYPE then it will give you a dropdown menu of the different roles available to your viewers. Viewer roles can be found in the “VIEWER ROLES” tab above settings to the left on the Firebot home screen. You can add custom roles and you can use the Twitch or Firebot assigned roles.

If you choose the Command Args Count TYPE then the expected value should be a number.

All other TYPEs allow the use of variables, you can find Firebot pre-programmed variables by clicking on the small blue $vars button that you can find in the input box. You can see it in the image above. It also allows you to use any custom variables that you have set in a custom variable effect. You can access these by either using the $customVariable[name] variable that you can find with the $vars button. You simply replace “name” with the name you chose to call the custom variable in the custom variable effect, or you can use $$name using two $ symbols to call on the custom variable. Again replace “name” with whatever you called the custom variable previously.

How To Use a Conditional Effect Basic Example

Let’s start with a very basic example, you want to create a personal command for a valued viewer that only they can use. Let’s call it “!mine”.

• In the “Commands” tab click on “New Custom Command” in blue on the top left of the screen. If this opens up a box that shows “Switch to Advanced Mode” in blue at the bottom then click on this to open up the advanced options.
• Set the trigger for the command, you can find this option at the top next to “Trigger”. In here you enter !mine. Now whenever anyone enters !mine into your chat they will trigger any effects associated with this command.
• Scroll down the options until you come across the “Base Effects” section, and under “Effects” click on “Add New Effect”. This will bring up the “Select New Effect” search box. Make sure the category to the left is set to “All” and in the search bar type “cond” (short for conditional). Then select the “Conditional Effects” option.
• This brings up the previously described Conditional Effects options. Here we click on the plus sign that can be found in the “If” section. We leave the TYPE as “Username” and the COMPARATOR as “is” and in the EXPECTED VALUE section we add the username of the person we want to be able to use this command. Let’s call them “Bob”. Remember that this must match their username exactly. For example, my username is “oshimia_”. If you were to miss the underscore “_” at the end of my username then this would not match against me.
• Now that we have set the condition we can set the other effects to run. You can add anything in here that you like, but for now we will just add a chat effect. Select “Add New Effect”, type “chat” into the search bar and select “Chat” from the options available. In the message to send we will just add the message “Hi Bob!”.

You now have a personal message for Bob, that will only trigger when Bob and only Bob types !mine into your chat. As a bonus we could also:

• Click on the “Otherwise” tab. In the effects here click “Add New Effect”, add a chat effect like before but instead of saying hello to Bob we can instead write something like: “YOU’RE NOT BOB, WHAT DID YOU DO WITH BOB? BRING BACK BOB NOW!” This will trigger if anyone types !mine into chat who doesn’t match the username for Bob.

Make sure you Click on “Add” in blue at the bottom right of the Add New Effect box, and “Save Changes” also in blue and at the bottom right of the “Edit Command” box and not cancel to save all your changes.

How To Use a Conditional Effect Complex Example

If you need help setting up a complex Conditional Effect please don’t hesitate to ask in the #questions tab of the Firebot Discord. It is a very helpful community.

Let’s say you want to reward viewers for participation in the stream. You decide that you will allow them to trigger a specific effect if they have sent more than X number of messages in your chat.

Go through the previous steps to create a new conditional effect and click on the plus sign to create a new condition in the If section.

• This is where things will change. We are going to change the TYPE to “Custom”. In the TYPE input box we are going to add the variable $chatMessages[username] and change “username” to the variable $username by adding the $ selector at the start. This will now equal the number of chat messages sent by the person using that username since you started using Firebot in your streams.
• Change the COMPARATOR to “is greater than or equal to” (or you could just use “is greater than” if you prefer.
• Now in EXPECTED VALUE enter the number of messages someone needs to have sent before they are allowed to trigger the effects in this list, for example we could use 10 to make sure they’ve at least had a conversation with you/others in your chat.

We have now created a filter that allows only people who have been active in your chat to trigger certain effects. But, to really use the full capability of the Conditional Effect we are going to add another Conditional Effect inside the If Effects list you are currently working on. Conditional Effects can be stacked many layers deep, allowing you to create complex chains of logic that trigger only under specific conditions.

We are also going to assume that you have already created a Custom Variable using a Custom Variable effect. A (very quick) breakdown for how to create a suitable custom variable for this is: Go to the events tab, create a new event that triggers on Firebot start, in the event use a custom variable effect to create a new variable, lets call it “powerUsers” and set that to a high number like 100. We can then use this number and the previously mentioned $chatMessages[username] variable in many different conditional effects to check for “power users”, but be able to change the number of messages (for example if your viewership grows and 100 becomes to small a number of messages to be considered a power user) in a single location without having to find and change every location that depends on that number. There are multiple ways to create this variable, such as using metadata or saving it to a text file, but this guide is focused on conditional effects, so we will ignore those for now.

So, we now have the basic if conditional effect that triggers if someone has sent more than 10 messages in your chat, inside that we have a second if conditional effect that we haven’t configured yet and we have a custom variable that is a number called “powerUsers”. If someone has sent more than 10 messages in your chat it will trigger any effects in the basic conditional effect and the new conditional effect that we are about to configure will make another check.

• In the new Conditional Effect click on the plus sign in the If section.
• Select the “Custom” TYPE. In here we’re going to add $chatMessages[$username] to see how many messages the person who has triggered this command has sent.
• For the COMPARATOR we’re going to select “is greater than or equal to”.
• In EXPECTED VALUE we are going to put $$powerUsers
• Click “Save”.
• Add any effects that you want only your power users to be able to trigger to the effects list under the If section.

So, to summarize:

We now have a conditional effect that checks to see if someone has been active in your chat and allows them to trigger specific effects using a command.

It also checks to see if the number of messages they have sent is equal to or greater than a variable called “powerUsers” and if they have sent more messages than the number saved to the variable allows them to trigger some extra effects reserved only for them.