Rate Limiters - Membercat-Studios/Streamlabs-Integration GitHub Wiki

Rate limiters can be used to prevent users from spamming certain donations, or make an action only excecute once for each user. A rate limiter has a value which is used to specify what exactly should be used to limit access. For example, using {user} will limit access for each user individually, while putting "" (nothing) will limit access for everyone.

There are different types of rate limiters, all have with functionality. Currently, the following types of rate limiters exist:

• once: Only allows the value to be used once, and rejects any attempts of triggering the action with that value more that one time.
• interval: Limits the value to be used once in the given interval. The interval can be defined using the interval parameter (in seconds), and reset_while_pending specifies whether the timer will be reset to 0 if the value is reused while the timer is still running.

Rate limiters will only retain their state as long as the plugin is active. Restarting the server will clear all of those states, so for example users who have been blocked before will get access to actions again. States can also be manually reset using the /streamlabs ratelimiters reset command.

actions:
  spammed_action:
    ...
     rate_limiter:
       type: once
       value: '{user}'  

This example rate limiter will only execute this action once for every user, meaning they won't ever be able to execute it again.

actions:
  interval_action:
    ...
     rate_limiter:
       type: interval
       value: ''
       interval: 300

This rate limiter will only allow the action to get triggered every 5 minutes (= 300 seconds), regardless of the user triggering it.

Rate limiters can optionally have events associated with them, which allow for the execution of any steps when a rate limit occurs:

rate_limiter:
  type: interval
  value: '{user}'
  interval: 300
  event:
    steps:
      - message: "<gold>{value} <red>just got rate limited!"

Those events work just like an action, meaning you can use conditions, steps, and yes, even other rate_limiters in the event. As you can see above, the event also provides some additional placeholders to work with. In the example, we're using the {value} placeholder, which will return the value of the rate limiter from when the limit occurred. The {already_limited} placeholder will return true if that value was already rate-limited when this limit occurred, and the {limited_before} placeholder will return true if the value has been rate-limited at any point in time before (will be reset by /streamlabs ratelimiters reset and reloads).

In addition to the placeholders, events have an additional event_mode property that can be used to specify when the event will trigger. The following modes are supported:

• ALWAYS: The event will trigger on every rate-limit
• ONCE: The event will trigger only once for every value
• ON_FIRST_LIMIT: The event triggers every time a value is rate limited for the first time. If the value is no longer rate-limited, this state gets reset.