From f11ca94c36ede607713b856fb700aa70010c386e Mon Sep 17 00:00:00 2001 From: Oshimia <120189186+Oshimia@users.noreply.github.com> Date: Fri, 21 Feb 2025 00:54:33 +0700 Subject: [PATCH 1/8] Adding a guide for evalJs effect and variable. --- .../v5/guides/evaluate-javascript/page.mdx | 46 +++++++++++++++++++ src/navigation.ts | 1 + 2 files changed, 47 insertions(+) create mode 100644 src/app/v5/guides/evaluate-javascript/page.mdx diff --git a/src/app/v5/guides/evaluate-javascript/page.mdx b/src/app/v5/guides/evaluate-javascript/page.mdx new file mode 100644 index 0000000..d2dbb37 --- /dev/null +++ b/src/app/v5/guides/evaluate-javascript/page.mdx @@ -0,0 +1,46 @@ +## Evaluate JavaScript effects and variables. + +Firebot will allow you to run JS (JavaScript) code to process information more programmatically than using the UI and built in effects. The JS code will run in a limited sandbox to make sure it doesn't affect any other Firebot systems, and will only run for a maximum of 5 seconds, after which point it will terminate. This means that it's very useful but cannot be used to, for example, run a HTTP request to contact an API, or process extremely large amounts of data. These limitations aside it is very useful for processing text and information more directly and easily than working with the Firebot UI. + +There are two methods for using evalJs. You can use an Evaluate JavaScript effect, like a chat effect or play sound effect that you may be more familiar with, or you can use an evalJs variable, like the `$user` or `$chatMessage` variables that you may be using already. We'll explain the effect first, and then the variable afterwards. + +**Evaluate JavaScript Effect** +To use an Evaluate JavaScript effect click "Add New Effect" in any effect list. Remember that for commands you will need the UI set to "Advanced" to access this. When the "Select New Effect" menu pops up make sure your category is set to "All" or "Advanced" and in the search bar at the top type "eval". This should bring up the Evaluate Javascript effect for you to select. + +Once you select this it should bring up the Edit Effect UI. You will have a large text box for Code, and a separate section for Parameters. In order to get information into the effect you will save it as a parameter. You can use variables in parameters, which means you can pass custom data saved as custom variables, you can learn more about them here: https://docs.firebot.app/v5/guides/custom-variables. For now we're just going to save something very basic, click on the `+` sign underneath Parameters and when it asks you to add text just add the number `1`. You should now have this saved as `parameters[0]`. Let's add one more parameter by again clicking on the plus sign and this time saving `2`. We now have `parameters[0]` and `parameters[1]`. + +Now lets access that data in the code section. At the top of the code section (where it's easy to find if you need to edit it later) write the following +``` +let firstNum = parameters[0]; +let secondNum = parameters[1]; +``` +This means we have now saved the data in the parameters into the code section, and can access it by using the `firstNum` and `secondNum` variables. so let's write some basic code to process it, in this case we'll just write `let sum = firstNum + secondNum;` which will add the firstNum and secondNum variables together and save it as a third variable `sum`. + +Now we need to get the data out of the effect, and to do this we need to use `return` to tell the code what data to return to Firebot. So our code section now looks like this: +``` +let firstNum = parameters[0]; +let secondNum = parameters[1]; + +let sum = firstNum + secondNum; + +return sum +``` + +1+2=3 so this will return 3, now we just need to access this. At the very bottom of the Edit Effect UI you can see `[→ Outputs` in blue if we click on this we can see `$effectOutput[jsResult]`. This is a variable that we can use elsewhere in Firebot. We can also click on the little edit symbol to edit what it's called. If you plan on using multiple evalJs effects it's a good idea to rename this to avoid multiple effects accidentally saving data over each others effects. so let's call this one "sum". Edit the name to "sum", click save, and now you will see it's called `$effectOutput[sum]`. You can now write this into any text box in Firebot that accepts variables, and it will convert to the result of the Evaluate JavaScript effect, in this case `3`. + +**evalJs variable** +You can also write JS into any text box that will accept the evalJs variable. You can find this by clicking on the blue `$vars` button that you can find in almost all the text boxes in Firebot and typing "eval" into the search bar that comes up. It will show you `$evalJs[`` code ``, ...parameters]`. This works in a very similar way to the Evaluate JavaScript effect, you write the JS code between the two bacticks, and you add the data at the end of variable as parameters. So our little script will look like this: +``` +$evalJs[`` +let firstNum = parameters[0]; +let secondNum = parameters[1]; + +let sum = firstNum + secondNum; + +return sum`` +, 1, 2] +``` + +This will give us exactly the same result as the effect we made earlier, but this will do it in place. Meaning we do not need to use the `$effectOutput[jsResult]` variable. It will replace the evalJs variable with whatever we return from that variable. + +The evalJs effect and variable are very powerful ways to process data, they can cut out a lot of other effects (like multiple conditional effects that can all be written into a simple JS script) and simplify your commands and effects a lot. They will be more useful for people who already know a bit of code, and Firebot has many alternatives to almost anything you can do in a sandboxed JS script if you are not comefortable with coding. \ No newline at end of file diff --git a/src/navigation.ts b/src/navigation.ts index 0a9ad55..a3a4392 100644 --- a/src/navigation.ts +++ b/src/navigation.ts @@ -31,6 +31,7 @@ export const nav: Array = [ { title: 'Conditional Effects', href: '/v5/guides/conditional-effects' }, { title: 'Time Variables', href: '/v5/guides/time-variable' }, { title: 'Custom Variables', href: '/v5/guides/custom-variables' }, + { title: 'Evaluate JavaScript', href: '/v5/guides/evaluate-javascript' }, { title: 'Manual Restore', href: '/v5/guides/manual-restore' }, ], }, From 56c7d8f2c30352649bf086c99c0c93d3c25dafef Mon Sep 17 00:00:00 2001 From: Oshimia <120189186+Oshimia@users.noreply.github.com> Date: Sat, 1 Mar 2025 02:18:07 +0700 Subject: [PATCH 2/8] Correcting syntax for object walkpath in guide --- src/app/v5/guides/custom-variables/page.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/app/v5/guides/custom-variables/page.mdx b/src/app/v5/guides/custom-variables/page.mdx index 292d386..da79099 100644 --- a/src/app/v5/guides/custom-variables/page.mdx +++ b/src/app/v5/guides/custom-variables/page.mdx @@ -21,11 +21,11 @@ This is used for accessing or modifying specific parts of complex data structure Access "banana" with `$$myArray[1]`. - **Object Example:** `{"fruit":"apple", "color":"red"}` - Access "apple" with `$$myObject.fruit`. + Access "apple" with `$$myObject[fruit]`. - **Array of Objects Example:** `[{"fruit":"apple"}, {"fruit":"banana"}]` - Access "apple" with `$$myArray[0].fruit`. + Access "apple" with `$$myArray[0, fruit]`. You can use the Property Path field to update a specific part of the variable without overwriting the entire structure. From 2a6a7dc4dfcc34af50ecd3e8ae653f6683802bcb Mon Sep 17 00:00:00 2001 From: Oshimia <120189186+Oshimia@users.noreply.github.com> Date: Wed, 16 Apr 2025 03:27:31 +0700 Subject: [PATCH 3/8] Adding Commands documentation to Core Concepts --- src/app/v5/core/commands/page.mdx | 141 ++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 src/app/v5/core/commands/page.mdx diff --git a/src/app/v5/core/commands/page.mdx b/src/app/v5/core/commands/page.mdx new file mode 100644 index 0000000..8161404 --- /dev/null +++ b/src/app/v5/core/commands/page.mdx @@ -0,0 +1,141 @@ +# Commands + +Commands, or chat commands, are a way for your viewers to interact with Firebot. Commands can be triggered by typing a specific keyword or phrase in chat, and can be used to run effects, send messages, or perform other actions. + +They can be found in the **Commands** tab of Firebot on the left of the UI under "Triggers". + +Commands are a great way to engage with your viewers and add interactivity to your stream. You can create commands for fun effects, games, or even to provide information about your stream or channel. + +# Custom Commands + +Custom commands are commands that you create yourself. They can be triggered by a specific keyword or phrase, and can be used to run effects, send messages, or perform other actions. + +You can make a new custom command by clicking the blue **"New Custom Command"** button in the top left of the commands tab. This will open a new window where you can enter the command trigger and effects. + +There are two ways to view the Add New Command UI: **Simple Mode** and **Advanced Mode**. You can switch between these at any time by using the blue "Switch to Advanced/Simple Mode ->" link at the bottom of the UI, but be aware that only Advanced mode has an effects list and switching to simple mode will remove effects in that effects list. + +## Simple Mode + +Simple Mode is the default view, with the following settings: + +* **Trigger**: + * A trigger is the keyword or phrase that will activate the command. For example, if you create a command with the trigger `!hello`, viewers can type `!hello` in chat to activate the command. + * Triggers can be any combination of letters, numbers, and symbols, but they must be unique to each command. + * You can also use phrases as triggers, such as `"hello world"`, but these are not recommended as they can be easily confused with other messages in chat. + * It is common to use an exclamation mark `!` at the start of a trigger to indicate that it is a command. You can also use other symbols, such as `?`, but these are less common. + +* **Cooldowns**: + * Cooldowns are a way to timeout a command. You have two options: + * **Global Cooldown**: A timer that applies to all users, meaning that once the command is used, no one can use it again until the cooldown expires. + * **User Cooldown**: A timer that applies to each individual user, meaning that once a user uses the command, they cannot use it again until the cooldown expires. + * Cooldowns are useful for preventing spam and ensuring that commands are used at a reasonable rate. You can set the cooldown in seconds. + +* **Permissions**: + * Permissions are a way to limit who can use the command. You can set permissions so that: + * Everyone can trigger a command. + * Subs Only can trigger a command. + * Mods Only can trigger a command. + +* **Response Text**: + * Response text is the message that will be sent in chat when the command is triggered. This can be a simple message, such as "Hello World". + * If you want to use more complex effects, you will want to switch to advanced mode. + +## Advanced Mode + +Advanced Mode is a more complex view with additional settings. You can switch to Advanced Mode by clicking the blue "Switch to Advanced Mode ->" link at the bottom of the UI. + +Below is a description of each setting in Advanced Mode: + +* **Trigger**: + * This acts exactly like the trigger setting from the Simple Mode UI, but also allows for two more optional settings: + * **Auto Delete Trigger**: Automatically deletes the trigger message from chat after the command is run. This is useful for commands that are meant to be used once, such as a trivia game or a giveaway. + * **Scan Whole Message**: Scans the entire message for the trigger. This is useful for commands that are meant to be used in a sentence, such as "I love Firebot". If this option is not selected, only the first word of the message will be scanned for the trigger. + +* **Description**: + * A short text that explains what the command does. + * Descriptions are optional, but recommended for clarity. + * These cannot be seen directly in the stream, but viewers will be able to find them when they use `!commands` in chat, which provides a link displaying all available and non-hidden commands. + +* **Aliases**: + * Alternative triggers that can be used to activate the command. For example, if you create a command with the trigger `!hello`, you can add an alias `!hi`. + * Aliases are optional but useful for providing multiple ways to access the same command. + * You can add as many aliases as you like, but keep them short and relevant. + +* **Cooldowns**: + * This acts exactly like the cooldown setting from the Simple Mode UI, but will also allow for two more options (details not specified in the original text). + +* **Stats**: + * Tracks how many times a specific command has been used in your chat, useful for seeing command popularity. + +* **Restrictions**: + * Limit who can use the command based on roles (e.g., all users, subscribers, moderators, streamers, custom roles). + * Useful for commands meant for specific user groups. + * Roles can be managed in the "ROLES & RANKS" tab. + * To set a restriction, click the "+" and select the restriction type. Multiple restrictions can be set. + +* **Settings**: + * **Enabled**: Determines if the command is active. If "off", the command won't trigger in chat. Useful for temporarily disabling commands. + * **Hidden**: Hides the command from the list generated by `!commands`. Useful for moderator commands or commands under testing. + * **Treat quoted text as single argument**: When enabled, text inside quotes (e.g., `"Hello World"`) is treated as one argument (e.g., in `!command add !hello "Hello World"`). If disabled, quoted text is split into multiple arguments. + +* **Ignore**: + * Allows the command to ignore triggers from specific accounts or sources: + * **Streamer Account** + * **Bot Account** + * **Whispers** + * Useful if you want users to trigger a command (e.g., `!hello`) but not the bot or streamer account itself. + +* **Shared Chat**: + * Configure how commands react to shared chat messages: + * **Allow**: Reacts to shared chat messages as if they came from your own chat. + * **Ignore**: Ignores shared chat messages. + * **Inherit**: Uses the global setting from `Settings > Triggers > Allow Shared Chat`. + +## Base Effects + +This is where you add actions to your command. You can find out more about effects here: [Firebot Effects](https://docs.firebot.app/v5/core/effects). + +* Add effects by clicking the blue **"Add Effect"** button in the bottom right of the UI. +* Select the desired effect from the new window. +* Multiple effects can be added and will run in the order they appear. +* Remove effects by clicking the three dots on the effect bar and selecting "Delete". + +## Subcommands + +Subcommands allow you to trigger different effects based on arguments (words/numbers) provided after the main command trigger. + +* They trigger different effects *instead* of the main command's effects list. +* Click the **"+"** symbol to add an argument for a new subcommand. +* Clicking the subcommand opens a UI identical to the main command UI for configuring its specific effects and settings. +* You can add multiple subcommands, but you cannot add a subcommand to another subcommand. +* For more complex conditional logic, consider using [conditional effects](https://docs.firebot.app/v5/guides/conditional-effects). + +# System Commands + +System commands are built-in commands available in all Firebot installations. You can find them by swapping to the **"SYSTEM COMMANDS"** tab (top left, above the "New Custom Command" button). + +These include basic commands like `!commands` (provides a link to the commands page) and `!uptime` (shows stream duration), as well as commands specific to Firebot currencies that are automatically created when you add a new currency in the "Currencies" tab. + +Below is an example of commands automatically created for a "gold" currency: + +| Name | !Trigger | Description | Usage | +|-------------------|----------|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **gold Management** | !gold | Allows management of the "gold" currency. | `!gold` — See your balance.
`!gold @username` — Gets the currency of the specified user.
`!gold add [@user] [amount]` — Adds currency for a given user.
`!gold remove [@user] [amount]` — Removes currency for a given user.
`!gold give [@user] [amount]` — Gives currency from one user to another user.
`!gold set [@user] [amount]` — Sets currency to the amount.
`!gold addall [amount]` — Adds currency to all online users.
`!gold removeall [amount]` — Removes currency from all online users. | + +Below is a list of all standard system commands available in Firebot. These can be enabled or disabled in the commands tab. + +| Name | !Trigger | Description | Usage | +|-------------------------|--------------------|--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Bid** | !bid | Allows viewers to participate in the Bid game. | `!bid start [currencyAmount]` — Starts the bidding at the given amount.
`!bid stop` — Manually stops the bidding. Highest bidder wins.
`!bid [currencyAmount]` — Joins the bidding at the given amount. | +| **Command List** | !commands | Displays a link to your profile page with all available commands. | `!commands` | +| **Command Management** | !command | Allows custom command management via chat. | `!command add [!trigger or "phrase"] [message]` — Adds a new command with a given response message.
`!command response [!trigger or "phrase"] [message]` — Updates the response message for a command. Only works for commands that have 1 or less chat effects.
`!command setcount [!trigger or "phrase"] count#` — Updates the commands usage count.
`!command cooldown [!trigger or "phrase"] [globalCooldownSecs] [userCooldownSecs]` — Change the cooldown for a command.
`!command restrict [!trigger or "phrase"] [All/Sub/Mod/Streamer/Custom Group]` — Update permissions for a command.
`!command remove [!trigger or "phrase"]` — Removes the given command.
`!command description [!trigger or "phrase"]` — Updates the description for a command.
`!command enable [!trigger or "phrase"]` — Enables the given custom command.
`!command disable [!trigger or "phrase"]` — Disables the given custom command.
`!command addalias [!trigger or "phrase"] !alias` — Adds the specified alias to the given custom command.
`!command removealias [!trigger or "phrase"] !alias` — Removed the specified alias from the given custom command. | +| **Create Stream Marker** | !marker | Create a stream marker. | `!marker [marker name]` | +| **Custom Role Management** | !role | Allows management of viewer's custom roles from chat. | `!role add @viewer roleName` — Adds a custom role to a viewer.
`!role remove @viewer roleName` — Removes a custom role from a viewer.
`!role list [@viewer]` — List all custom roles, or just roles a viewer has. | +| **Follow Age** | !followage | Displays how long the user has been following the channel. | `!followage` | +| **Heist** | !heist | Allows viewers to play the Heist game. | `!heist` — Starts/joins the heist with the default wager amount, if one is set.
`!heist [wagerAmount]` — Starts/joins the heist with the given amount. | +| **Quotes Management** | !quote | Allows quote management via chat. | `!quote` — Display a random quote
`!quote [quoteId]` — Displays the quote with the given ID.
`!quote add [@username] [quoteText]` — Adds a new quote.
`!quote remove [quoteId]` — Removes a quote using its id.
`!quote edittext [quoteId] [newText]` — Edit the text given quote.
`!quote edituser [quoteId] [newUsername]` — Edit the user of the given quote.
`!quote editgame [quoteId] [newGame]` — Edit the game of the given quote.
`!quote editdate [quoteId] [newDate]` — Edit the date of the given quote.
`!quote list` — Gives a link that lists out all quotes.
`!quote search [searchTerm]` — Gives a random quote using the search term(s).
`!quote searchuser @username` — Gives a random quote said by the given user.
`!quote searchdate DD MM YYYY` — Gives a random quote at the given date.
`!quote searchgame [searchTerm]` — Gives a random quote at the given game. | +| **Spam Raid Protection** | !spamraidprotection| Toggles protective measures such as follow-only mode, slow mode, etc.| `!spamraidprotection off` — Turn off the protection command. | +| **Spin (Slots)** | !spin | Allows viewers to play the Slots game. | `!spin [currencyAmount]` — Spins the slot machine with the given amount | +| **Steam Search** | !steam | Displays information about a game on Steam. | `!steam [game name]` | +| **Trivia** | !trivia | Allows viewers to play trivia | `!trivia [wager]` — Triggers trivia for the given wager amount | +| **Uptime** | !uptime | Displays how long the stream has been live in chat. | `!uptime` | From d911c75c028bbaf622ac678a50954631acb0b5ea Mon Sep 17 00:00:00 2001 From: Oshimia <120189186+Oshimia@users.noreply.github.com> Date: Wed, 16 Apr 2025 03:27:31 +0700 Subject: [PATCH 4/8] Adding Commands documentation to Core Concepts --- src/app/v5/core/commands/page.mdx | 141 ++++++++++++++++++++++++++++++ src/navigation.ts | 2 +- 2 files changed, 142 insertions(+), 1 deletion(-) create mode 100644 src/app/v5/core/commands/page.mdx diff --git a/src/app/v5/core/commands/page.mdx b/src/app/v5/core/commands/page.mdx new file mode 100644 index 0000000..8161404 --- /dev/null +++ b/src/app/v5/core/commands/page.mdx @@ -0,0 +1,141 @@ +# Commands + +Commands, or chat commands, are a way for your viewers to interact with Firebot. Commands can be triggered by typing a specific keyword or phrase in chat, and can be used to run effects, send messages, or perform other actions. + +They can be found in the **Commands** tab of Firebot on the left of the UI under "Triggers". + +Commands are a great way to engage with your viewers and add interactivity to your stream. You can create commands for fun effects, games, or even to provide information about your stream or channel. + +# Custom Commands + +Custom commands are commands that you create yourself. They can be triggered by a specific keyword or phrase, and can be used to run effects, send messages, or perform other actions. + +You can make a new custom command by clicking the blue **"New Custom Command"** button in the top left of the commands tab. This will open a new window where you can enter the command trigger and effects. + +There are two ways to view the Add New Command UI: **Simple Mode** and **Advanced Mode**. You can switch between these at any time by using the blue "Switch to Advanced/Simple Mode ->" link at the bottom of the UI, but be aware that only Advanced mode has an effects list and switching to simple mode will remove effects in that effects list. + +## Simple Mode + +Simple Mode is the default view, with the following settings: + +* **Trigger**: + * A trigger is the keyword or phrase that will activate the command. For example, if you create a command with the trigger `!hello`, viewers can type `!hello` in chat to activate the command. + * Triggers can be any combination of letters, numbers, and symbols, but they must be unique to each command. + * You can also use phrases as triggers, such as `"hello world"`, but these are not recommended as they can be easily confused with other messages in chat. + * It is common to use an exclamation mark `!` at the start of a trigger to indicate that it is a command. You can also use other symbols, such as `?`, but these are less common. + +* **Cooldowns**: + * Cooldowns are a way to timeout a command. You have two options: + * **Global Cooldown**: A timer that applies to all users, meaning that once the command is used, no one can use it again until the cooldown expires. + * **User Cooldown**: A timer that applies to each individual user, meaning that once a user uses the command, they cannot use it again until the cooldown expires. + * Cooldowns are useful for preventing spam and ensuring that commands are used at a reasonable rate. You can set the cooldown in seconds. + +* **Permissions**: + * Permissions are a way to limit who can use the command. You can set permissions so that: + * Everyone can trigger a command. + * Subs Only can trigger a command. + * Mods Only can trigger a command. + +* **Response Text**: + * Response text is the message that will be sent in chat when the command is triggered. This can be a simple message, such as "Hello World". + * If you want to use more complex effects, you will want to switch to advanced mode. + +## Advanced Mode + +Advanced Mode is a more complex view with additional settings. You can switch to Advanced Mode by clicking the blue "Switch to Advanced Mode ->" link at the bottom of the UI. + +Below is a description of each setting in Advanced Mode: + +* **Trigger**: + * This acts exactly like the trigger setting from the Simple Mode UI, but also allows for two more optional settings: + * **Auto Delete Trigger**: Automatically deletes the trigger message from chat after the command is run. This is useful for commands that are meant to be used once, such as a trivia game or a giveaway. + * **Scan Whole Message**: Scans the entire message for the trigger. This is useful for commands that are meant to be used in a sentence, such as "I love Firebot". If this option is not selected, only the first word of the message will be scanned for the trigger. + +* **Description**: + * A short text that explains what the command does. + * Descriptions are optional, but recommended for clarity. + * These cannot be seen directly in the stream, but viewers will be able to find them when they use `!commands` in chat, which provides a link displaying all available and non-hidden commands. + +* **Aliases**: + * Alternative triggers that can be used to activate the command. For example, if you create a command with the trigger `!hello`, you can add an alias `!hi`. + * Aliases are optional but useful for providing multiple ways to access the same command. + * You can add as many aliases as you like, but keep them short and relevant. + +* **Cooldowns**: + * This acts exactly like the cooldown setting from the Simple Mode UI, but will also allow for two more options (details not specified in the original text). + +* **Stats**: + * Tracks how many times a specific command has been used in your chat, useful for seeing command popularity. + +* **Restrictions**: + * Limit who can use the command based on roles (e.g., all users, subscribers, moderators, streamers, custom roles). + * Useful for commands meant for specific user groups. + * Roles can be managed in the "ROLES & RANKS" tab. + * To set a restriction, click the "+" and select the restriction type. Multiple restrictions can be set. + +* **Settings**: + * **Enabled**: Determines if the command is active. If "off", the command won't trigger in chat. Useful for temporarily disabling commands. + * **Hidden**: Hides the command from the list generated by `!commands`. Useful for moderator commands or commands under testing. + * **Treat quoted text as single argument**: When enabled, text inside quotes (e.g., `"Hello World"`) is treated as one argument (e.g., in `!command add !hello "Hello World"`). If disabled, quoted text is split into multiple arguments. + +* **Ignore**: + * Allows the command to ignore triggers from specific accounts or sources: + * **Streamer Account** + * **Bot Account** + * **Whispers** + * Useful if you want users to trigger a command (e.g., `!hello`) but not the bot or streamer account itself. + +* **Shared Chat**: + * Configure how commands react to shared chat messages: + * **Allow**: Reacts to shared chat messages as if they came from your own chat. + * **Ignore**: Ignores shared chat messages. + * **Inherit**: Uses the global setting from `Settings > Triggers > Allow Shared Chat`. + +## Base Effects + +This is where you add actions to your command. You can find out more about effects here: [Firebot Effects](https://docs.firebot.app/v5/core/effects). + +* Add effects by clicking the blue **"Add Effect"** button in the bottom right of the UI. +* Select the desired effect from the new window. +* Multiple effects can be added and will run in the order they appear. +* Remove effects by clicking the three dots on the effect bar and selecting "Delete". + +## Subcommands + +Subcommands allow you to trigger different effects based on arguments (words/numbers) provided after the main command trigger. + +* They trigger different effects *instead* of the main command's effects list. +* Click the **"+"** symbol to add an argument for a new subcommand. +* Clicking the subcommand opens a UI identical to the main command UI for configuring its specific effects and settings. +* You can add multiple subcommands, but you cannot add a subcommand to another subcommand. +* For more complex conditional logic, consider using [conditional effects](https://docs.firebot.app/v5/guides/conditional-effects). + +# System Commands + +System commands are built-in commands available in all Firebot installations. You can find them by swapping to the **"SYSTEM COMMANDS"** tab (top left, above the "New Custom Command" button). + +These include basic commands like `!commands` (provides a link to the commands page) and `!uptime` (shows stream duration), as well as commands specific to Firebot currencies that are automatically created when you add a new currency in the "Currencies" tab. + +Below is an example of commands automatically created for a "gold" currency: + +| Name | !Trigger | Description | Usage | +|-------------------|----------|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **gold Management** | !gold | Allows management of the "gold" currency. | `!gold` — See your balance.
`!gold @username` — Gets the currency of the specified user.
`!gold add [@user] [amount]` — Adds currency for a given user.
`!gold remove [@user] [amount]` — Removes currency for a given user.
`!gold give [@user] [amount]` — Gives currency from one user to another user.
`!gold set [@user] [amount]` — Sets currency to the amount.
`!gold addall [amount]` — Adds currency to all online users.
`!gold removeall [amount]` — Removes currency from all online users. | + +Below is a list of all standard system commands available in Firebot. These can be enabled or disabled in the commands tab. + +| Name | !Trigger | Description | Usage | +|-------------------------|--------------------|--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Bid** | !bid | Allows viewers to participate in the Bid game. | `!bid start [currencyAmount]` — Starts the bidding at the given amount.
`!bid stop` — Manually stops the bidding. Highest bidder wins.
`!bid [currencyAmount]` — Joins the bidding at the given amount. | +| **Command List** | !commands | Displays a link to your profile page with all available commands. | `!commands` | +| **Command Management** | !command | Allows custom command management via chat. | `!command add [!trigger or "phrase"] [message]` — Adds a new command with a given response message.
`!command response [!trigger or "phrase"] [message]` — Updates the response message for a command. Only works for commands that have 1 or less chat effects.
`!command setcount [!trigger or "phrase"] count#` — Updates the commands usage count.
`!command cooldown [!trigger or "phrase"] [globalCooldownSecs] [userCooldownSecs]` — Change the cooldown for a command.
`!command restrict [!trigger or "phrase"] [All/Sub/Mod/Streamer/Custom Group]` — Update permissions for a command.
`!command remove [!trigger or "phrase"]` — Removes the given command.
`!command description [!trigger or "phrase"]` — Updates the description for a command.
`!command enable [!trigger or "phrase"]` — Enables the given custom command.
`!command disable [!trigger or "phrase"]` — Disables the given custom command.
`!command addalias [!trigger or "phrase"] !alias` — Adds the specified alias to the given custom command.
`!command removealias [!trigger or "phrase"] !alias` — Removed the specified alias from the given custom command. | +| **Create Stream Marker** | !marker | Create a stream marker. | `!marker [marker name]` | +| **Custom Role Management** | !role | Allows management of viewer's custom roles from chat. | `!role add @viewer roleName` — Adds a custom role to a viewer.
`!role remove @viewer roleName` — Removes a custom role from a viewer.
`!role list [@viewer]` — List all custom roles, or just roles a viewer has. | +| **Follow Age** | !followage | Displays how long the user has been following the channel. | `!followage` | +| **Heist** | !heist | Allows viewers to play the Heist game. | `!heist` — Starts/joins the heist with the default wager amount, if one is set.
`!heist [wagerAmount]` — Starts/joins the heist with the given amount. | +| **Quotes Management** | !quote | Allows quote management via chat. | `!quote` — Display a random quote
`!quote [quoteId]` — Displays the quote with the given ID.
`!quote add [@username] [quoteText]` — Adds a new quote.
`!quote remove [quoteId]` — Removes a quote using its id.
`!quote edittext [quoteId] [newText]` — Edit the text given quote.
`!quote edituser [quoteId] [newUsername]` — Edit the user of the given quote.
`!quote editgame [quoteId] [newGame]` — Edit the game of the given quote.
`!quote editdate [quoteId] [newDate]` — Edit the date of the given quote.
`!quote list` — Gives a link that lists out all quotes.
`!quote search [searchTerm]` — Gives a random quote using the search term(s).
`!quote searchuser @username` — Gives a random quote said by the given user.
`!quote searchdate DD MM YYYY` — Gives a random quote at the given date.
`!quote searchgame [searchTerm]` — Gives a random quote at the given game. | +| **Spam Raid Protection** | !spamraidprotection| Toggles protective measures such as follow-only mode, slow mode, etc.| `!spamraidprotection off` — Turn off the protection command. | +| **Spin (Slots)** | !spin | Allows viewers to play the Slots game. | `!spin [currencyAmount]` — Spins the slot machine with the given amount | +| **Steam Search** | !steam | Displays information about a game on Steam. | `!steam [game name]` | +| **Trivia** | !trivia | Allows viewers to play trivia | `!trivia [wager]` — Triggers trivia for the given wager amount | +| **Uptime** | !uptime | Displays how long the stream has been live in chat. | `!uptime` | diff --git a/src/navigation.ts b/src/navigation.ts index a3a4392..bf614ee 100644 --- a/src/navigation.ts +++ b/src/navigation.ts @@ -12,7 +12,7 @@ export const nav: Array = [ title: 'Core concepts', links: [ { title: 'Effects', href: '/v5/core/effects' }, - { title: 'Commands', href: '/commands' }, + { title: 'Commands', href: '/v5/core/commands' }, { title: 'Events', href: '/events' }, { title: 'Timers', href: '/timers' }, { title: 'Channel Rewards', href: '/channel-rewards' }, From 4855f6b2cad3d1bf7312930b22064d6538f5e52e Mon Sep 17 00:00:00 2001 From: Oshimia <120189186+Oshimia@users.noreply.github.com> Date: Mon, 8 Sep 2025 15:56:30 +0700 Subject: [PATCH 5/8] Adding "events" documentation to core concepts. --- src/app/v5/core/events/page.mdx | 148 ++++++++++++++++++++++++++++++++ src/navigation.ts | 2 +- 2 files changed, 149 insertions(+), 1 deletion(-) create mode 100644 src/app/v5/core/events/page.mdx diff --git a/src/app/v5/core/events/page.mdx b/src/app/v5/core/events/page.mdx new file mode 100644 index 0000000..d0f535e --- /dev/null +++ b/src/app/v5/core/events/page.mdx @@ -0,0 +1,148 @@ +# Events + +Events in Firebot are automatic triggers that run a list of effects in response to specific activities on your stream, such as new followers, subscribers, cheers, or chat messages. This allows you to create dynamic and interactive alerts and responses without any manual input. They will often have specific variables associated with the event, so if you're trying to recreate an effect from a command and it isn't working it is worth checking to make sure that you are using the correct variables. For example, sub events do *not* have an associated `$chatMessage` variable, as there is no chat message associated with the event. If you want to capture the message associated with a sub then you would instead use the `$subMessage` variable. You can check available variables anywhere you can see the blue `$vars` button. + +You can manage all your events from the **Events** tab, located in the main navigation sidebar under the "Triggers" category. + +Events are a good way to acknowledge and reward your community's engagement, making your stream more interactive and professional. + +## General Events vs. Event Sets + +Firebot organizes events into two main categories: + +* **General Events:** This is where you can create and set effects for general events that you want to react to. They are perfect for alerts that you want to be available at all times, like standard follow or subscription notifications. +* **Event Sets:** These are groups of events that you can activate or deactivate as a whole. This is useful for creating different themes of alerts for specific games, holidays, or special stream occasions. For example, you could have a "Horror Game" event set with spooky alerts that you only activate when playing horror games. + +## Creating a New Event +In the top left of the screen is a blue button with `+ New Event` as the label. To create a new event simply click on this button. + +## Configuring an Event + +Whether you're creating a new event or editing an existing one, the configuration process is the same. + +### **Trigger On** +This is the core of your event. Here you select the specific activity that will trigger the effects. Firebot provides a wide range of triggers from various sources: + +* **Twitch:** Includes follows, subs, raids, cheers, channel point redemptions, and more. +* **Integrations:** If you have linked services like Streamlabs, StreamElements, or others, their specific events (like donations) will appear here. +* **Firebot:** Internal events such as chat connections or when a custom variable expires. + +* **Others:** Custom scripts can sometimes add custom events. +* A complete list of triggers will be added to the bottom of the document. + +### **Name** +Give your event a descriptive name (e.g., "New Follower Alert," "Tier 2 Sub Thank You"). This helps you stay organized, especially as you create more events. + +### **Filters** +Filters allow you to add specific conditions that must be met for the event to trigger. This lets you create targeted responses. + +**Example**: You could create a "Sub" event but add a filter for "Sub Tier" -> "is" -> "Tier 3". This event would then *only* trigger for Tier 3 subscriptions, allowing you to have a special alert just for them. + +You can add multiple filters and choose whether **all** of them must be met or if **any** of them can be met for the event to trigger. + +### **Settings** + +* **Is Enabled:** A simple toggle to turn the event on or off without deleting it. +* **Custom Cooldown:** This prevents the event from triggering too frequently. You can set a cooldown in seconds and specify if it applies globally (to all viewers) or per user. This is useful for events like "First Time Chat" to prevent it from firing multiple times if a new chatter sends several messages in quick succession. + +### **Effects** +This is where you define what happens when the event is triggered. You can add one or more effects that will run in sequence. + +* Click the **"Add New Effect"** button to open the effect selector. +* Choose any effect, such as **Play Sound**, **Show Image/GIF**, or **Chat**. +* Configure each effect as needed. You can use event-specific variables (like `$user` for the person who triggered the event) to personalize the response. +* Find out more about effects here: [Effects](../effects/page.mdx) + +## Event Sets + +Event Sets are useful for managing different themes of alerts. + +* **Creating a Set:** In the Events tab, click the plus icon next to the "Event Sets" header. Give your set a name, and it will appear in the list. +* **Activating/Deactivating:** Each Event Set has a status dot next to its name. A green dot indicates it's active; a gray dot means it's inactive. Click the three-dot menu next to the set's name to activate or deactivate it. You can also use the **Toggle Event Set** effect to control this automatically. +* **Managing Events:** Click on an Event Set to view and manage the events within it, just as you would with General Events. + +## Simulating Events + +To test your events without waiting for a real stream activity, you can use the "Simulate Event" button located in the toolbar. This opens a modal where you can select any event type and fill in placeholder data (like a username or sub tier) to see how your effects will behave. This is an excellent way to fine-tune your alerts. + +--- + +## **Example: Creating a Custom Raid Alert** + +**Premise:** You want to create a special alert that plays a sound and shows a GIF when your channel gets raided. + +1. **Create a New Event:** In the **Events** tab, click the **"New Event"** button. + +2. **Configure the Trigger:** + * For **Trigger On**, select `Twitch` as the source and `Raid` as the event. + * Give it a **Name**, like "Raid Alert". + +3. **Add Effects:** + * **Play Sound:** Add a "Play Sound" effect and choose a sound file from your computer that you want to play when you get raided. + * **Show Image/GIF:** Add a "Show Image/GIF" effect and select a GIF to display on your overlay. Configure its position and duration. + * **Chat Message:** Add a "Chat" effect to thank the raider and welcome their viewers. + * **Message:** `Welcome raiders from $user's channel! Thanks so much for the raid, hope you enjoy your stay!` + +4. **Save the Event:** Click "Save" and your new raid alert is ready to go! + +--- + +## Events List + +### **Firebot Events** + +* **Chat Connected:** Triggers when Firebot successfully connects to Twitch chat. +* **Overlay Connected:** Activates when a Firebot overlay is connected. +* **View Time Update:** Runs when a viewer's watch time is updated. +* **Currency Update:** Triggers when a viewer's currency amount changes. +* **Viewer Created:** Activates when a new viewer is added to the database, typically after their first chat message. +* **Firebot Started:** Triggers when Firebot is launched and running. +* **Custom Variable Expired:** Activates when a custom variable's set duration expires. +* **Custom Variable Created:** Triggers when a new custom variable is created. +* **Chat Message Spotlight:** Activates when a chat message is spotlighted, for example, to be displayed on an overlay. +* **Category Changed:** Triggers when the stream category is changed in the Firebot dashboard. +* **Effect Queue Cleared:** Activates when an effect queue has finished and is cleared. +* **Before Firebot Closed:** Triggers just before Firebot shuts down. +* **Viewer Rank Updated:** Activates when a viewer's rank changes. +* **Viewer Metadata Updated:** Triggers when a viewer's metadata is updated. + +### **Twitch Events** + +* **Raid:** Triggers when another channel raids yours. +* **Follow:** Activates when someone follows your channel. +* **Sub:** Triggers for new subscriptions and re-subscriptions. +* **Prime Sub Upgraded:** Activates when a viewer upgrades their Prime Gaming subscription to a paid one. +* **Sub Gifted:** Triggers when a viewer gifts a subscription to another user. +* **Community Subs Gifted:** Activates when a viewer gifts multiple subscriptions to the community. +* **Gift Sub Upgraded:** Triggers when a viewer upgrades their gifted subscription to a paid one. +* **Cheer:** Activates when a viewer sends Bits. +* **Bits Badge Unlocked:** Triggers when a viewer unlocks a new Bits badge tier. +* **Viewer Arrived:** Activates when a viewer sends their first message in a stream. +* **Chat Cleared:** Triggers when the chat is cleared. +* **Chat Message:** Activates for every new chat message. +* **Chat Message Deleted:** Triggers when a chat message is deleted. +* **First Time Chat:** Activates when a viewer chats for the first time ever in your channel. +* **Announcement:** Triggers when a moderator sends an announcement. +* **Viewer Banned:** Activates when a viewer is banned from the channel. +* **Viewer Unbanned:** Triggers when a viewer is unbanned. +* **Viewer Timeout:** Activates when a viewer is timed out. +* **Channel Reward Redemption:** Triggers when a viewer redeems a channel point reward. +* **Channel Reward Redemption Approved:** Activates when a channel point redemption is approved. +* **Channel Reward Redemption Rejected:** Triggers when a channel point redemption is rejected. +* **Whisper:** Activates when you or your bot account receives a whisper. +* **Chat Mode Changed:** Triggers when a moderator changes chat modes (e.g., emote-only, sub-only). +* **Channel Poll Started/Progress/Ended:** Activates at the start, during, and at the end of a Twitch poll. +* **Channel Goal Started/Progress/Ended:** Activates at the start, during, and at the end of a channel goal. +* **Channel Prediction Started/Progress/Locked/Ended:** Triggers at the start, during, when locked, and at the end of a channel prediction. +* **Hype Train Started/Progress/Ended:** Activates at the start, during, and at the end of a Hype Train. +* **Stream Started/Ended:** Triggers when your stream goes live or ends. +* **Charity Campaign Started/Donation/Progress/Ended:** Triggers for events related to a charity campaign on your channel. +* **Shoutout Sent/Received:** Activates when you send or receive a shoutout. +* **Category Changed:** Triggers when your stream category changes on Twitch. +* **Title Changed:** Activates when your stream title changes on Twitch. +* **Scheduled Ad Break Starting Soon:** Triggers when a scheduled ad break is about to start. +* **Ad Break Started/Ended:** Activates at the start and end of an ad break. + +### **Integration Events** + +* **Streamlabs, StreamElements, TipeeeStream, Extra Life:** These integrations have their own set of events, primarily for donations and follows, which will appear as "Trigger On" options when the respective service is linked to Firebot. \ No newline at end of file diff --git a/src/navigation.ts b/src/navigation.ts index bf614ee..5f5182c 100644 --- a/src/navigation.ts +++ b/src/navigation.ts @@ -13,7 +13,7 @@ export const nav: Array = [ links: [ { title: 'Effects', href: '/v5/core/effects' }, { title: 'Commands', href: '/v5/core/commands' }, - { title: 'Events', href: '/events' }, + { title: 'Events', href: '/v5/core/events' }, { title: 'Timers', href: '/timers' }, { title: 'Channel Rewards', href: '/channel-rewards' }, { title: 'Preset Effect Lists', href: '/preset-effect-lists' }, From 42e0ad5a4365325e82ad926c5b28014256d7a370 Mon Sep 17 00:00:00 2001 From: Oshimia Date: Fri, 14 Nov 2025 21:08:16 +0700 Subject: [PATCH 6/8] Adding effect queue guide and timer docs --- src/app/v5/core/timers/page.mdx | 118 +++++++++++++++++++++++ src/app/v5/guides/effect-queues/page.mdx | 46 +++++++++ src/navigation.ts | 4 +- 3 files changed, 166 insertions(+), 2 deletions(-) create mode 100644 src/app/v5/core/timers/page.mdx create mode 100644 src/app/v5/guides/effect-queues/page.mdx diff --git a/src/app/v5/core/timers/page.mdx b/src/app/v5/core/timers/page.mdx new file mode 100644 index 0000000..53cf77f --- /dev/null +++ b/src/app/v5/core/timers/page.mdx @@ -0,0 +1,118 @@ +# Timers and scheduled effects + +## **Timers** + +Timers in Firebot are a crucial feature for automating various actions on your stream at set intervals. They allow you to schedule regular messages in chat, trigger effects, or perform other tasks, ensuring consistent engagement even when you're focused on gameplay or conversation. + +You can access and manage all your timers from the **TIME-BASED** tab, located in the main navigation sidebar under "Triggers". This tab is dedicated to "Time-Based" events, allowing you to schedule actions to occur automatically. + +Timers are an good way to remind your viewers about important information, promote your social media, or even run mini-games without constant manual intervention. + +## **Creating a Timer** +To create a new time click on the blue button in the top right labeled `+ New Timer` of the Time-Based tab. This will bring up four options, name, interval, required chat lines and "Only Run When Live", as well as an effects list when you can add the effects to be run on the timer. + +* **Name** + This is where you can name your timer. It is generally a good idea to give it a descriptive name so you don't forget what it's for. +* **interval** + This is where you decide how long an interval Firebot waits before triggering the effects list. This is measured in seconds, so if you wanted to wait 30 minutes you would use 1800 seconds. +* **Required Chat Lines** + This is the minimum number of lines in chat since the last time this interval timer ran. So if nobody has said anything in chat this timer will not trigger until the some people have commented in chat enough to reach this minimum. + +**Example**: If you set `Interval` to `900` seconds (15 minutes) and `Required Chat Lines` to `25`, the timer will only send a message if 25 or more lines of chat have occurred in the last 15 minutes. This prevents messages from repeating in an empty channel. + +* **Only Run When Live** +This checkbox determines whether the timer should operate only when your stream is actively live. + * **Enabled (checked):** The timer will only run its effects when your stream is online. This is generally recommended for most chat-based timers. + * **Disabled (unchecked):** The timer will run its effects even when your stream is offline. This might be useful for very specific, non-stream-dependent automation. + +### **Effects** +This is where you define the actions that the timer will perform when it triggers. You can add one or more effects that will run in the order they appear. + +* **Add effects:** Click the blue **"Add New Effect"** button to open the effect selector. +* **Select effects:** Choose any effect, such as **Chat**, **Play Sound**, or **Run Random Effect**. +* **Configure effects:** Each added effect has its own settings that you can customize. +* **Order of execution:** Multiple effects will run sequentially. +* **Random or Sequential Effects:** For timers that display chat messages, it's often useful to use the **Run Random Effect** or **Run Sequential Effect** within your effects list. This allows you to set up multiple chat messages, and the timer will rotate through them or pick one at random each time it fires, preventing repetitive messages. +--- + + +## Timer Example: Promoting Social Media + +You want to periodically remind your viewers about your social media channels in chat, but only when chat is active. + +1. **Create a New Timer:** + * Navigate to the **Timers** tab. + * Click the blue **"+ New Timer"** button. + * **Name**: `"Social Media Plug"` + * **Interval (secs)**: `"600"` (This means the timer will try to run every 10 minutes). + * **Required Chat Lines**: `"5"` (The timer will only run if there have been at least 5 lines of chat in the last 10 minutes). + * **Only Run When Live**: Ensure this is **checked**. + +2. **Add Effects:** + * Add a **Run Sequential Effect**. + * Inside this sequential effect, add multiple **Chat** effects. + * **Chat Effect 1 Message**: `"Don't forget to follow me on Twitter! $twitter[handle]"` + * **Chat Effect 2 Message**: `"Join our Discord server for more fun! $discord[invite]"` + * **Chat Effect 3 Message**: `"Check out my latest YouTube video! $youtube[latestvideo]"` + +3. **Save the Timer**: Click **"Save"**. + +Now, every 10 minutes (provided there's been at least 5 lines of chat), Firebot will post one of your social media messages in chat, rotating through them sequentially. + +--- +## **Scheduled Effect List** + +Scheduled Effect Lists in Firebot allow you to automate actions at specific times or recurring schedules, independent of chat activity or stream status. This is ideal for daily greetings, weekly reminders, or seasonal events. + +You can create and manage all your Scheduled Effect Lists from the **TIME-BASED** tab, located in the main navigation sidebar under "Triggers", by selecting the **"SCHEDULED EFFECT LISTS"** sub-tab. + +Scheduled Effect Lists are perfect for automating consistent stream elements, such as reminding viewers about an upcoming weekly show, a daily poll, or even a monthly giveaway announcement. + +## **Creating a Scheduled Effect List** +To create a new Scheduled Effect List, click on the blue button labeled `+ New Scheduled Effect List` in the top right of the "SCHEDULED EFFECT LISTS" sub-tab. This will open a new window with several options, including name, schedule, and an effects list. + +* **Name** + This is where you name your Scheduled Effect List. A descriptive name helps you quickly identify its purpose, especially if you have multiple schedules. +* **Schedule** + This is the core of a Scheduled Effect List, defining exactly when your effects will run. You have two options: + * **Simple Schedule**: Choose from predefined options like "Every Minute," "Every Hour," "Every Day," "Every Month," or "Every Weekday." This is straightforward for common recurring tasks. + * **Advanced Schedule**: For more complex timing, you can use a [crontab expression](https://crontab.guru/). This allows for highly specific schedules (e.g., "every Monday at 8 AM" or "the last day of every month"). + * When you add a crontab expression to the input field, a "friendly name" will appear, translating your cron expression into a human-readable format to help you verify your schedule. +* **Only Run When Live** + This checkbox determines whether the Scheduled Effect List should operate only when your stream is actively live. + * **Enabled (checked):** The effects will only run when your stream is online. This is generally recommended for most alerts or chat messages. + * **Disabled (unchecked):** The effects will run even when your stream is offline. This might be useful for behind-the-scenes tasks or messages intended for your community outside of live hours. + +### **Effects** +This is where you define the actions that the Scheduled Effect List will perform when it triggers. You can add one or more effects that will run in the order they appear. + +* **Add effects:** Click the blue **"Add New Effect"** button to open the effect selector. +* **Select effects:** Choose any effect, such as **Chat**, **Play Sound**, or **Run Command**. +* **Configure effects:** Each added effect has its own settings that you can customize. +* **Order of execution:** Multiple effects will run sequentially. +* **Random or Sequential Effects:** For chat messages, using **Run Random Effect** or **Run Sequential Effect** can prevent repetitive messages by rotating through a list of predefined messages or selecting one randomly. + +--- + +## Scheduled Effect List Example: Weekly Stream Reminder + +You want to automatically post a reminder in chat every Sunday at 3 PM (your local time) about your upcoming stream, but only if you are live. + +1. **Create a New Scheduled Effect List:** + * Navigate to the **TIME-BASED** tab and select the **"SCHEDULED EFFECT LISTS"** sub-tab. + * Click the blue **"+ New Scheduled Effect List"** button. + * **Name**: `"Weekly Stream Reminder"` + * **Schedule**: + * Select **"Advanced Schedule"**. + * Enter the cron expression: `"0 15 * * SUN"` (This translates to "At 3:00 PM, only on Sunday"). + * Verify the "friendly name" matches your intention. + * **Only Run When Live**: Ensure this is **checked**. + * **Enabled**: Ensure this is **checked**. + +2. **Add Effects:** + * Add a **Chat** effect. + * **Message**: `"Don't forget, my stream is coming up this week! Get ready for some fun at [Your Stream Link]"` + +3. **Save the Scheduled Effect List**: Click **"Save"**. + +Now, every Sunday at 3 PM, if your stream is live, Firebot will automatically post your stream reminder message in chat. \ No newline at end of file diff --git a/src/app/v5/guides/effect-queues/page.mdx b/src/app/v5/guides/effect-queues/page.mdx new file mode 100644 index 0000000..2685b80 --- /dev/null +++ b/src/app/v5/guides/effect-queues/page.mdx @@ -0,0 +1,46 @@ +# **Effect Queues** + +The Effect Queues in Firebot are a feature that helps manage and display alerts on your stream in an organized manner. It allows you to add separate effects lists to a queue, meaning that you can play lists of effects one after another, preventing overlap and ensuring that each effect list gets its moment in the spotlight. + +You can find queues in two locations. First in the **Effect Queues** tab, located in the main navigation sidebar under the "Management" category. You can also find them by looking at the top right of any effects list just underneath **QUEUE**. If you haven't set a queue yet, click on the `V` symbol next to "Not set" to add your effects to a queue, or create a new queue. If you already added the effects to a queue then "Not set" will become the name of the queue, you can still click on the `V` to change the queue. + +## **Creating an Effect Queue** +If you are in the Effect Queues management tab then click on the blue button labeled `+ New Effect Queue`. If you want to create a queue from the drop down menu for an effects list then select "Create new queue". + +## **Configuring an Effect Queue** +When creating a new queue you will be given two options, name and mode. + +### **Name** +This is where you create the name for your queue, it is generally good practice to use a descriptive name that will make it obvious what the queue is for when you come to look at it later. + +### **Mode** + +Here you have three options: + +* **Custom** + This will wait a custome amount of time between effects, meaning you can set a specific time before it moves onto the next effect. When you select a custom effect queue from the effect list drop down menu two options will appear next to it, "EFFECTS DURATION", which is the total duration (in seconds) the queue should wait after triggering the effect list before triggering the next one. And "QUEUE PRIORITY", if an effect list has priority it will get added in front of other lists in that queue that do not have priority. +* **Sequential** + This will run effects lists in the queue sequentially, priority items will be addded before non-priority. There is an optional additional delay that you can add between effects lists, that will default to 0 seconds. When you select this option while creating the queue it will give you a new third option "INTERVAL/DELAY (SECS)", where you can optionally add the delay time between effect lists. When you add a list to this queue the option to give the effect list priority will appear to the left of the queue drop down menu. +* **Interval** + This runs effects lists after a set interval. When you select this option this will give you the third "INTERVAL/DELAY (SECS)" option. When you add an effects list it will also give you the option to make the effects list a priority for that queue. +--- +## **Example: Managing Multiple Donations with a Queue** + +You want to ensure that every donation, regardless of how quickly they come in, gets a distinct on-stream alert without overlapping. + +1. **Create a New Effect Queue:** + * Navigate to the **Effect Queues** tab in Firebot. + * Click the blue **"+ New Effect Queue"** button. + * Name your queue: `"Donation Alerts"` + * Select **Mode**: `"Sequential"` (This ensures alerts play one after another). + * Click **"Save"**. + +2. **Configure a Donation Event to use the Queue:** + * Go to the **Events** tab. + * Find or create an event that triggers on `"Twitch"` -> `"Cheer"` (for Bits) and another for `"Streamlabs"` -> `"Donation"`. + * For each of these events, in the event's "Effects" section: + * Add your desired effects (e.g., **Play Sound**, **Show Image/GIF**, **Chat Message**). + * In the top right corner of the effects list, next to **"QUEUE"**, click the `V` symbol. + * Select your newly created `"Donation Alerts"` queue from the dropdown. + +Now, whenever you receive multiple donations close together, Firebot will add each associated effects list to the "Donation Alerts" queue. Each alert will play fully, ensuring no alerts overlap and every donor is properly acknowledged. \ No newline at end of file diff --git a/src/navigation.ts b/src/navigation.ts index 5f5182c..9736ba0 100644 --- a/src/navigation.ts +++ b/src/navigation.ts @@ -14,7 +14,7 @@ export const nav: Array = [ { title: 'Effects', href: '/v5/core/effects' }, { title: 'Commands', href: '/v5/core/commands' }, { title: 'Events', href: '/v5/core/events' }, - { title: 'Timers', href: '/timers' }, + { title: 'Timers And Scheduled Effects', href: '/v5/core/timers' }, { title: 'Channel Rewards', href: '/channel-rewards' }, { title: 'Preset Effect Lists', href: '/preset-effect-lists' }, { title: 'Hotkeys', href: '/hotkeys' }, @@ -27,7 +27,7 @@ export const nav: Array = [ { title: 'Guides', links: [ - { title: 'Alert Queues', href: '/guides/alert-queues' }, + { title: 'Effect Queues', href: '/v5/guides/effect-queues' }, { title: 'Conditional Effects', href: '/v5/guides/conditional-effects' }, { title: 'Time Variables', href: '/v5/guides/time-variable' }, { title: 'Custom Variables', href: '/v5/guides/custom-variables' }, From 893f96fb355494719654fae782fba757678606a6 Mon Sep 17 00:00:00 2001 From: Oshimia Date: Fri, 14 Nov 2025 21:33:42 +0700 Subject: [PATCH 7/8] Adding metadata guide and navigation entry --- src/app/v5/guides/metadata/page.mdx | 73 +++++++++++++++++++++++++++++ src/navigation.ts | 1 + 2 files changed, 74 insertions(+) create mode 100644 src/app/v5/guides/metadata/page.mdx diff --git a/src/app/v5/guides/metadata/page.mdx b/src/app/v5/guides/metadata/page.mdx new file mode 100644 index 0000000..c80bef3 --- /dev/null +++ b/src/app/v5/guides/metadata/page.mdx @@ -0,0 +1,73 @@ +# **Metadata Effects** + +Metadata allows you to store viewer specific data for use in Firebot. + +You can use metadata by using the **Set User Metadata** and **Remove User Metadata** effects, found in the “Select New Effect” box when adding a new effect. They’re listed under the “ALL” and “Scripting” tabs. Metadata works by storing data (basically text) associated with a specific viewer's username. + +Using Metadata you can tailor interactive experiences to individual viewers like tracking stats, preferences, or progress within a game or loyalty system. It works similarly to [Custom Variables](/v5\guides\custom-variables\page.mdx), but custom variables are not associated with a single viewer, and unless you have changed the settings do not persist when you close Firebot, meaning that when you close Firebot all data is deleted. Metadata on the other hand is stored for each user persistently and can be used across Firebot sessions. + +## **Configuring Metadata Effects** + +### **Username** + +Specify the username for whom you want to configure or modify the metadata. This should generally be the `$user` variable to affect the user triggering the event. + +### **Metadata Key** + +This is where you define the name of the specific piece of information you want to store. Choose a descriptive key without spaces (e.g., `favoriteColor`, `level`, `totalPoints`). A common practice is using camelCase. + +### **Data** + +This is the actual value you want to store under the specified Metadata Key. This can be static text, numbers, or any other data, or you can reference Firebot's built-in variables using the `$vars` button to create dynamic values. + +### **Advanced (Optional)** + +You can click on the blue "Advanced" text to open up this section, which enables you to directly access or modify specific parts of complex data structures, such as arrays or objects, associated with the Metadata key. This is designed for advanced users already familiar with property paths. +Most users can skip this section. + +This is used for accessing or modifying specific parts of complex data structures like arrays or objects. Most users can skip this section, but here’s a quick overview: + +- **Array Example:** `["apple", "banana", "cherry"]` + Access "banana" with `$$myArray[1]`. + +- **Object Example:** `{"fruit":"apple", "color":"red"}` + Access "apple" with `$$myObject[fruit]`. + +- **Array of Objects Example:** + `[{"fruit":"apple"}, {"fruit":"banana"}]` + Access "apple" with `$$myArray[0, fruit]`. + +You can use the Property Path field to update a specific part of the variable without overwriting the entire structure. + + + **Example**: To change the color of a fruit from red to yellow in `{"fruit":"apple", "color":"red"}`, set `Variable Name` to your object’s name, `Variable Data` to `yellow`, and `Property Path` to `color`. + + +## **Accessing and Using Metadata** + +Metadata is accessed using the `$userMetadata` replace variable. + +* `$userMetadata[key]` +* `$userMetadata[key, propertyPath]` + + + **Example:** Once you have used a `Set User Metadata` effect to set the user data for one of your viewers you can use `$userMetadata[key]` to display a viewer's favorite color, if for example you saved the metadata as "favouriteColor" you would set `Key` to `favoriteColor`, and use `$userMetadata[favoriteColor]` in a chat message or overlay effect. + + +## Example: Tracking Viewer Stats + +**Premise:** Suppose you want to keep track of how many times a viewer has checked into your stream. + +1. **Add Set User Metadata Effect to Check In:** Set up your check in, either with a new command or a channel reward, and add a "Set User metadata" effect. +2. **Set Up The Metadata Effect:** + + * `Username`: `$user` (This ensures the metadata is stored for the user who triggered the command/reward) + * `Metadata Key`: `checkInCount` + * `Data`: `$numberMath[$userMetadata[checkInCount] + 1]` + + Every time this event is triggered, the user's `checkInCount` will increase by one. +3. **Display the Stat:** In a chat message or overlay effect, use the following: + + * `$userMetadata[$username, checkInCount]` + + This will display the number of times the user has triggered the command or reward. \ No newline at end of file diff --git a/src/navigation.ts b/src/navigation.ts index 9736ba0..ef7cf2f 100644 --- a/src/navigation.ts +++ b/src/navigation.ts @@ -33,6 +33,7 @@ export const nav: Array = [ { title: 'Custom Variables', href: '/v5/guides/custom-variables' }, { title: 'Evaluate JavaScript', href: '/v5/guides/evaluate-javascript' }, { title: 'Manual Restore', href: '/v5/guides/manual-restore' }, + { title: 'Metadata', href: '/v5/guides/metadata' }, ], }, { From a8576a5e8b1183fd4e3f77a4f1a8688610274c77 Mon Sep 17 00:00:00 2001 From: Oshimia Date: Fri, 14 Nov 2025 21:33:42 +0700 Subject: [PATCH 8/8] Adding metadata guide and navigation entry --- src/app/v5/guides/metadata/page.mdx | 77 +++++++++++++++++++++++++++++ src/navigation.ts | 1 + 2 files changed, 78 insertions(+) create mode 100644 src/app/v5/guides/metadata/page.mdx diff --git a/src/app/v5/guides/metadata/page.mdx b/src/app/v5/guides/metadata/page.mdx new file mode 100644 index 0000000..301f2d4 --- /dev/null +++ b/src/app/v5/guides/metadata/page.mdx @@ -0,0 +1,77 @@ +# **Metadata Effects** + +Metadata allows you to store viewer specific data for use in Firebot. + +You can use metadata by using the **Set User Metadata** and **Remove User Metadata** effects, found in the “Select New Effect” box when adding a new effect. They’re listed under the “ALL” and “Scripting” tabs. Metadata works by storing data (basically text) associated with a specific viewer's username. + +Using Metadata you can tailor interactive experiences to individual viewers like tracking stats, preferences, or progress within a game or loyalty system. It works similarly to [Custom Variables](/v5\guides\custom-variables\page.mdx), but custom variables are not associated with a single viewer, and unless you have changed the settings do not persist when you close Firebot, meaning that when you close Firebot all data is deleted. Metadata on the other hand is stored for each user persistently and can be used across Firebot sessions. + +## **Configuring Metadata Effects** + +### **Username** + +Specify the username for whom you want to configure or modify the metadata. This should generally be the `$user` variable to affect the user triggering the event. + +### **Metadata Key** + +This is where you define the name of the specific piece of information you want to store. Choose a descriptive key without spaces (e.g., `favoriteColor`, `level`, `totalPoints`). A common practice is using camelCase. + +### **Data** + +This is the actual value you want to store under the specified Metadata Key. This can be static text, numbers, or any other data, or you can reference Firebot's built-in variables using the `$vars` button to create dynamic values. + +### **Advanced (Optional)** + +You can click on the blue "Advanced" text to open up this section, which enables you to directly access or modify specific parts of complex data structures, such as arrays or objects, associated with the Metadata key. This is designed for advanced users already familiar with property paths. +Most users can skip this section. + +This is used for accessing or modifying specific parts of complex data structures like arrays or objects. Most users can skip this section, but here’s a quick overview: + +- **Array Example:** `["apple", "banana", "cherry"]` + Access "banana" with `$$myArray[1]`. + +- **Object Example:** `{"fruit":"apple", "color":"red"}` + Access "apple" with `$$myObject[fruit]`. + +- **Array of Objects Example:** + `[{"fruit":"apple"}, {"fruit":"banana"}]` + Access "apple" with `$$myArray[0, fruit]`. + +You can use the Property Path field to update a specific part of the variable without overwriting the entire structure. + + + **Example**: To change the color of a fruit from red to yellow in `{"fruit":"apple", "color":"red"}`, set `Variable Name` to your object’s name, `Variable Data` to `yellow`, and `Property Path` to `color`. + + +## **Accessing and Using Metadata** + +Metadata is accessed using the `$userMetadata` replace variable. + +* `$userMetadata[key]` +* `$userMetadata[key, propertyPath]` + + + **Example:** Once you have used a `Set User Metadata` effect to set the user data for one of your viewers you can use `$userMetadata[key]` to display a viewer's favorite color, if for example you saved the metadata as "favouriteColor" you would set `Key` to `favoriteColor`, and use `$userMetadata[favoriteColor]` in a chat message or overlay effect. + + +## Example: Tracking Viewer Stats + +**Premise:** Suppose you want to keep track of how many times a viewer has checked into your stream. + +1. **Add Set User Metadata Effect to Check In:** Set up your check in, either with a new command or a channel reward, and add a "Set User metadata" effect. +2. **Set Up The Metadata Effect:** + + * `Username`: `$user` (This ensures the metadata is stored for the user who triggered the command/reward) + * `Metadata Key`: `checkInCount` + * `Data`: `$numberMath[$userMetadata[checkInCount] + 1]` + + Every time this event is triggered, the user's `checkInCount` will increase by one. +3. **Display the Stat:** In a chat message or overlay effect, use the following: + + * `$userMetadata[$username, checkInCount]` + + This will display the number of times the user has triggered the command or reward. + + ## Viewing and Managing Metadata + + You can view and manage metadata stored for a user by going to the "VIEWERS" tab in Firebot, selecting a viewer and looking at the "METADATA" table available there. You can see what metadata has been stored on the viewer, what the keys are to that data, and the data itself. You can also edit or delete metadata directly from this table. \ No newline at end of file diff --git a/src/navigation.ts b/src/navigation.ts index 9736ba0..ef7cf2f 100644 --- a/src/navigation.ts +++ b/src/navigation.ts @@ -33,6 +33,7 @@ export const nav: Array = [ { title: 'Custom Variables', href: '/v5/guides/custom-variables' }, { title: 'Evaluate JavaScript', href: '/v5/guides/evaluate-javascript' }, { title: 'Manual Restore', href: '/v5/guides/manual-restore' }, + { title: 'Metadata', href: '/v5/guides/metadata' }, ], }, {