[Feature Request] "Raid" quick action

[TheStaticMage]

I have written this for my own use and for other streamers I support. I have received very positive feedback about this, so I am seeking dev approval to submit this as a PR.

Describe the solution you'd like

I would like to use a quick action to initiate the raid in a way that's more convenient for the streamer than /raid whomever. I have implemented a quick action that allows the streamer to select an online channel in their same category, an online channel that they follow, or an arbitrary user.

This is what I came up with:

The display indicates the user, category, viewer count, language, and uptime. There's also a ⚠ icon that displays for mature content (not seen in this particular example).

The configuration modal:

My goal is to present something that makes no changes to existing quick actions, "just works" for the raid quick action with no configuration, but is fully customizable if desired.

Additional context

One of the most awkward points in my streams is at the end, when I finish my game and want to raid out. Finding the next person to raid involves looking at Twitch to see who is online, remembering whether or not there's a @ when using the /raid command, remembering those random numbers or how many underscores are in someone's name, etc. 99% of the time I am raiding someone in my same category and/or someone I follow, and so I wanted something less awkward. That's what I've done here, and the two times I used it, it was far less awkward than before.

The best I could do in Firebot before this was to create a custom quick action targeting a preset effect list and prompting for the parameter. (Just targeting the "Raid/Unraid Channel" effect from a quick action provided no way to pass a parameter.) This requires typing in the username, so it's really not much better than /raid. This is arguably worse, since there's no auto-completion and no instant feedback for an invalid username.

To achieve this I added a "raid" built-in (system) quick action:

• Added "get-streams" and "get-followed-streams" to src/backend/twitch-api/api.ts (these call the same-named Twurple functions)
• Added a raid modal (pictured in screenshot) with three options:
  • Same category: Calls get-channel-info to get your category and then get-streams with filter to that category ID
  • Followed streams: Calls get-followed-streams
  • Username: Calls search-twitch-channels (this was existing, already created for the viewer search modal)
• Raid modal has a confirmation if Firebot believes you're offline to prevent spam raids (but still can be overridden, as per Discord discussion)

However I don't just want to call "Raid/Unraid Channel" -- I also post a message in chat and trigger an on-screen effect when I start a raid. However, there's no Firebot event for "raid initiated" so I need the ability to specify a custom event list for a system quick action. I did this as follows:

• Added properties as an optional field for QuickAction
• If properties.customizable is true, then add "Edit" to the context menu for the system quick action
  • This is only true for the new raid quick action
  • This is fully backward compatible / has no effect on existing quick actions
• To support a customizable system quick action:
  • Updated add-or-edit-custom-quick-action-modal.js to add a "Default" choice (again used only for raid at this time)

The default for raid is to call "Raid/Unraid Channel" (this makes it "just work" with no user configuration required). For advanced users, there are two replacement variables for the raid quick action (selected username and selected user display name) to use in custom effect lists.

The customized configuration for a system quick action gets stored in custom-quick-actions.json like this. There's never a conflict with user-defined custom quick actions because those are keyed with a UUIDv4 whereas the system quick action's ID is static.

{
    "abac12e9-ee5c-4182-967a-5042ad577aee": {
        "id": "abac12e9-ee5c-4182-967a-5042ad577aee",
        "name": "Trivia Question",
        "type": "custom",
        "icon": "fas fa-question",
        "presetListId": "5a5e8970-f282-11ef-bb3a-cba1291cfda0",
        "presetArgValues": {},
        "promptForArgs": false,
        "effectList": null
    },
    "firebot:raid": {
        "id": "firebot:raid",
        "name": "Raid",
        "type": "system",
        "icon": "fad fa-rocket-launch",
        "effectList": {
            "list": [
                {
                    "id": "af31e32d-154b-4e02-a399-0d5823760f47",
                    "type": "firebot:run-effect-list",
                    "active": true,
                    "listType": "preset",
                    "presetListArgs": {
                        "target": "$raidQuickActionTargetUsername"
                    },
                    "effectList": {
                        "list": [],
                        "id": "a67085f5-96c7-44dd-a9ac-b6d23a6a6474"
                    },
                    "presetListId": "610dc6f9-a431-46d5-99b2-2990e94e7f0c",
                    "dontWait": true,
                    "percentWeight": null
                }
            ],
            "id": "bb130a3c-6d33-484e-bc32-f16dbc8aec1e"
        },
        "presetListId": null,
        "overrideDefault": true
    }
}

I also made a couple minor backend changes to make this all work (all of which are backward compatible):

• onTriggerEvent() in the quick-action now takes a optional parameter
• Trigger type now has a quickAction? field (optional for backward compatibility)
• EffectTrigger.QUICK_ACTION can now be an array or a boolean (like events) to scope custom variables to just one quick action

[TheStaticMage]

FWIW I refactored this into a plugin (https://github.com/TheStaticMage/firebot-mage-raid-modal) and have not kept the quick action changes I made up-to-date after 5b8246e0235a31213a8f95f703a2d72ccc251a03 landed.

You can probably close this. Unless this is something you want to bring into Firebot properly rather than leaving it as an external script, in which case I'll note I released it as GPL3 😄 .