Skip to main content

Statrole - Conditions

Feeling Lost?

Conditions can be a little confusing at first, but we're here to help! If you're ever feeling overwhelmed or have any questions, please do not hesitate to reach out to our amazing support team!

What Are Conditions?​

Conditions are where all the work happens. They calculate a set of members who "Pass" the requirements (settings) you've set for each Condition. A Statrole then uses this set of members to know who to give the role to, and who to take it away from.

Below is a quick list of the available Conditions and the stats they use.

ConditionDescription
MessageText messages a user has sent.
VoiceTime a user has spent in voice channels.
ActivityTime a user has spent interacting with a game / application.
Joined AgeHow long the member has been in the server.
Account AgeHow old the member's account is.
CompareComparison of two lists of a user's stats.
StatroleThe results of another Statrole.
MatchLogical group of other Conditions.
premium

Get the Statroles+ Upgrade to unlock all of the Conditions and more!

Conditions​

Here are all of the Conditions and their options. Some options are available for many Conditions and can be found under Common Settings.

Message​

Looks at the user's message stats.

Settings

Voice​

Looks at the user's voice stats.

Settings

Voice States​

You can select which Voice States that the Voice Condition will use. These are the same as when setting the server's Voice States Filter.

Premium Conditions​

Activity​

Looks at the user's playing / streaming / listening of a game / application.

Settings

Activity​

The game / application that the Activity Condition will use.

premium

The "Any Activity" option relies on Activity Tracking which requires the Data+ Upgrade.

Activity Types​

How the user is interacting with the application.

caution

Streaming is determined by Discord integrations and primarily only works with Twitch streaming. It does not currently include streaming through Discord itself.

Listening seems to only be used by Spotify.

Joined Age​

Looks at how long ago the member most recently joined the server.

Settings
  • Comparison
  • Lookback
  • Filters (Members and Roles)

Comparison​

The first option is how the bot will compare the member's Joined Age to the following Lookback settings.

Days or Hours

  • More than ( older ) — The time the user has been in the server must be more than the Days / Hours specified.
  • Less than ( younger ) — The time the user has been in the server must be less than the Days / Hours specified.

Date

  • Before — The user must have joined before the date specified.
  • After — The user must have joined after the date specified.

Lookback​

This is the duration or date that the Comparison setting will use when checking the user.

Restrictions

This is a special condition that must be inside a Match — ALL condition with at least one Message, Voice, Activity, or Compare condition.

Account Age​

The Account Age Condition is the same as the Joined Age Condition except is uses the date of the user's account creation instead.

Compare​

warning

The Compare Condition is the most complex and is only recommended for advanced users. It is assumed that you are already somewhat familiar with Statroles. If you are not, we recommend you skip this section for now.

Performs math on two lists of stats and compares them. Because not all stats are created equal, this condition introduces Weights that let you fine-tune the Values.

Settings

Values​

This condition contains two lists of Values, along with the Comparison Operator. It calculates the stats in the lists by adding the counts together, and then compares the result of the top's to the bottom's based on the Comparison Operator.

Each Value in the list is something like a "mini-condition", though without any of the more complex settings. Because many of the settings are similar to the other Conditions, we will focus on just Subtract and Custom Weight.

Subtract​

When ON, the Value will instead be subtracted from the others in the list. This could be useful if you wanted participation in one way to be counted against participation in another.

Custom Weight​

Multiplies the Value by this amount. This allows you to change the importance of a Value against the others.

Statrole​

Uses the results of Statroles.

info

Because Statroles calculate their results independent from one another, and because Statroles often run at the same time, the Statrole Condition is preferred over Condition Role Filters to avoid delayed actions resulting from Statroles not knowing what the others are doing.

Settings

Statrole​

The Target Statrole whose results to include. When checking Conditions, Statbot will calculate the results of the Target Statrole—Invert Resultsing if necessary—then passes those results into the rest of the check.

It can be helpful to think of Statroles in terms of "Result Sets". The Result Set is the members who should have the role—the members who have passed all the Conditions in the Statrole. A Statrole usually compares this Result Set against the members in the server to know who to give roles to and remove roles from.

The Statrole Condition instead takes the Result Set of the Target Statrole and marks the "Passes" members in it as "Passing". In other words, members who Pass the Target Statrole also Pass the Statrole Condition (before Invert Results). This has important implications when setting up Statroles that depend on one another.

tip

A Statrole does not have to be turned ON to use in a Statrole Condition.

caution

A Statrole Condition with Ignore Members and Permanent may not behave as you'd expect. These settings apply only immediately before roles events are processed, well after the Result Set is calculated.

Match​

The Match Condition is the one Condition to rule them All! It allows for grouping the other Conditions together based on AND / OR logic. When under a Match Condition, we refer to Conditions as "Sub-Conditions".

Options
  • All ( AND ) — A member must match ALL of the Sub-Conditions in this group. (i.e. "This AND that.")
  • Any ( OR ) — A member must match ANY of the Sub-Conditions in this group. (i.e. "This OR that.")

Understanding Match​

When thinking about Match Conditions, it can be helpful to think each individual Conditions as Pass / Fail. Members either Pass a condition when they meet all of its requirements, or Fail it when they don't.

When a Statrole has a single non-Match Condition, there's only one Pass / Fail to look at and so that one Condition primarily decides who gets the role.

When using a Match Condition, the Sub-Conditions each have their own Pass / Fail. The Match Condition computes all of those Pass / Fail values, and then returns its own Pass or Fail based on the All / Any option.

tip

For those who are comfortable with boolean logic, Pass and Fail are interchangeable with True and False respectively.

All / Any Logic​

  • All checks that the user passes every Sub-Condition.
  • Any only checks that the user passes at least one Sub-Condition.

For each statement, the Match Condition returns Pass if the user matches it, Fail if they don't. See "Diagrams" below for a visual representation.

Diagrams

Here are some visuals to help illustrate the options.

Assuming a Match Condition has two Sub-Conditions "A" and "B".

All

A-PassA-Fail
B-Pass✅❌
B-Fail❌❌

Any

A-PassA-Fail
B-Pass✅✅
B-Fail✅❌
A-Pass, B-PassA-Pass, B-FailA-Fail, B-Fail
All✅❌❌
Any✅✅❌
Key
✅ = User passes Match Condition
❌ = User fails Match Condition

Common Settings​

info

"Stats" below will refer to text messages for the Message Condition, and minutes for the Voice and Activity Conditions.

Limit Types​

Limit Types define the upper and lower boundaries (limits) when checking stats. A user must fall inside of the boundaries to pass the Condition. Each Limit Type is explained here.

Filters​

Different than the Statrole Filters, these filters directly impact the Condition's results.

warning

Adding Members or Roles the Blacklist does NOT ignore them. Rather it makes them automatically Fail the Condition (before Invert Results). See Invert Results.

If you want to ignore members (not change their role), use the Statrole's Ignore Members setting.

Filters

Channel Filter​

What channels to use when computing Stats. Supports categories. Leave empty to include all channels.

Choose between Whitelist or Blacklist

  • Whitelist — Only include these channels' Stats when checking the Condition.
  • Blacklist — Do not include these channels' Stats when checking the Condition. (Will use all others.)

Member Filter​

What members to include when computing Stats. Leave empty to include all members.

Choose between Whitelist or Blacklist

  • Whitelist — Only include these members' Stats when checking the Condition.
  • Blacklist — Do not include these members' Stats when checking the Condition. (Will use all others.)

Role Filters​

What members to include when computing Stats based on their roles. Leave empty to include all members.

Supports both Whitelist and Blacklist

  • Whitelist — A member must have at least one of the roles in this list.
  • Blacklist — A member can not have any of the roles in this list.
warning

Blacklisting a role may have unintended consequences when Inverting the Condition. See Common Mistakes.

Invert Results​

Most Conditions have the Invert Results option available under their Advanced tab. Invert Results makes the Condition return the exact opposite results than it originally would. This basically Passes everyone who would have Failed, and Fails everyone who would have Passed.

tip

This is how you can implement "NOT" logic into your Statroles. This is also how Inactivity Statroles are accomplished (though there's a shortcut with using Minimum: 0).

Common Mistakes​

The flexibility and feature-rich nature of Statroles comes at the price of complexity. This complexity may at times force people to make assumptions about how the system works—assumptions that sometimes backfire and make it even harder to get the results they want.

Here are some common mistake and misconceptions we've seen around Statroles. Hopefully this will help you avoid the same pitfalls!

Feeling lost?

If you find these explanations lacking and want more information, or want any other assistance with Statroles, our fantastic support team is here to help!

Blacklisting a Statrole's Discord Role​

A common application of Statroles are tiered-Statroles using complex Match Conditions. When doing this, "tiers" become a lot more difficult because you can longer simply step a single Message or Voice Condition. This leads to users Role Blacklisting the lower or higher-tiered Statroles from the others. While the idea is close, there's a problem with this approach.

A server's Statroles run in parallel with one another—meaning they run at the exact same time. The Condition Role Filter uses the roles a member has when the Statrole started its run. This means that a Statrole that filters the role of another will often lag behind by a run, because they both started at the same time and the one in question didn't know that the other was going to make any role changes.

The solution here is to use the Statrole Condition. This calculates the Target Statrole's result set directly inside the Statrole that's using it.

Putting a Statrole Condition with Invert Results ON and the rest of the (Sub-)Conditions inside a Match Condition set to ALL will make it so that the Statrole only Passes members who don't Pass the Statrole Condition—in other words, only Pass members who shouldn't have the Target Statrole's role.

caution

As mentioned under the Statrole Condition section, the Ignore Members and Permanent settings of a Target Statrole's do not affect its output and should not be considered when thinking about the Statrole Condition.

Inverting a Role Filter​

People often think that a Condition's Role Filters apply after inversion. In other words, they think that if you Blacklist a role, members of that role will not Pass the condition, regardless of the Invert Results setting. This is incorrect.

Invert Results is the FINAL step of a Condition's calculations. It occurs after all stats have been processed, and after all of the Condition's filters have been applied. In this sense, the Role Filter is treated no differently than the Channel Filter.

If you want to think through what Inverting a Condition will do, take the results of the Condition as it is normally (without Invert Results), and then instead Fail those users and Pass everyone else in the server.