Discourse Gamification

	Summary	Discourse Gamification adds customizable scoring (karma, kudos, points) and leaderboards to your instance.
	Install Guide	This plugin is bundled with Discourse core. There is no need to install the plugin separately.
	Demo	Leaderboard

image1169×1108 119 KB

Features

While Discourse ships, out of the box, with gamification features (badges, trust levels) some communities want to take it to another level. That’s where GitHub - discourse/discourse-gamification comes in.

This plugin allows admins to easily create and tweak community scoring contests, where points are awarded by participating in the community.

Points are automatically updated every hour for events of the day, and we re-calculate scores from the last 10 days once a day.

Cheers

Users are awarded “cheers” by performing certain actions on the community. Each user cheer score appear on their user card, user profile and can be enabled on the user directory.

user card example with cheers577×257 43 KB

user profile example with cheers799×578 69.4 KB

user directory example with cheers1166×595 77.7 KB

Like the plugin but the name cheers isn’t the best for your community? You can rename it to anything using Customize all text in Discourse.

Leaderboards

image1189×953 130 KB

Admins can create multiple leaderboards, and each one can have a custom:

• start date
• end date
• Competing users
• Leaderboard privacy

By default, we ship with a default leaderboard at /leaderboard that will list all users from the first day where scores started to be awarded.

You can see a demo of it at Discourse Meta

Scorables

Currently, the following events award cheers:

• Daily visits
• Flags accepted
• Likes given
• Likes received
• Posts created
• Posts read
• Solutions accepted (requires Discourse Solved (Accepted answer plugin))
• Time read
• Topics created
• User invites accepted

See roadmap for upcoming scorables.

Score backfill

You can run a backfill to calculate the historical scores through the UI using the ‘Recalculate Scores’ button on your /admin/plugins/gamification page:

recalculate scores - button1390×482 14.2 KB

This can also be used to recalculate the leaderboard if you make any changes to your scorables or eligible scoring categories. You can generate a rescore up to 5 times a day, and can select a range of time frames (or set a custom one):

select timeframe481×317 6.32 KB

timefarne options526×462 8.68 KB

Configuration

Global customizations are:

• each action score multiplier
• Restrict categories where points can be earned
• enable and disable the plugin

Those plugin-level settings live at /admin/site_settings/category/plugins?filter=plugin%3Adiscourse-gamification.

To create, delete and update leaderboards, admins can visit /admin/plugins/gamification.

Use as widget

This can also be displayed as a widget in a smaller format, inside the Right Sidebar Blocks theme component. More info to be found there.

Badges based on score

You can have automatic badges based on the gamification score using Enable Badge SQL

Here is an example badge when a user has over 9000 cheers:

SELECT user_id, current_timestamp AS granted_at 
FROM gamification_scores
WHERE (:backfill OR user_id IN (:user_ids))
GROUP BY 1
HAVING SUM(score) > 9000

Changelog

• 2022-05-02T03:00:00Z - Public Release
• 2022-05-10T05:00:00Z - Update roadmap with recent changes

Roadmap

(roughly ordered)

• Make leaderboard respect prioritize usernames in ux being disabled

• Use higher resolutions avatars in leaderboard podium

• Add custom per-badge scoring

• Add per-reaction score awarding (requires Discourse Reactions)

• Add chat-events scoring (requires Discourse Chat)

• Add poll events scoring (created poll, voted in poll)

• Add media events scoring (posted image, posted video, posted onebox)

Implemented:

• Fix i18n table title in custom score column on user directory
• Ignore staged users
• Ignore anonymized users (email match @anonymized.invalid)
• Style leaderboard edit form
• Leaderboard “you” link needs a larger offset to accommodate floating header..
• Fix highlight of own user on the leaderboard not working if own user position is > 100
• Add i18n thousands separator to user card / profile cheer score
• Add time period filters to leaderboards
• Add default time period filter to leaderboard settings
• Add excluded_groups_ids to leaderboard settings
• Allow admins to award/remove arbitrary points to users to allow integration with out-of-Discourse scorable events
• Make scores click link to leaderboard (both in user profile and user card)

Hosted by us? This plugin is available on our Business and Enterprise plans Gamification | Discourse - Civilized Discussion

Last edited by @tobiaseigen 2025-07-16T21:11:22Z

Check document

Perform check on document:

A post was split to a new topic: Choose leaderboard linked in profile

A post was split to a new topic: Subtract points based on certain reactions

2 posts were split to a new topic: Creating a Top 20 leaderboard for a specific date range

Just a note to say the gamification scoring for posts_created has been adjusted to account for a few extra things:

This is great. A feature suggestion is to allow different scorable settings for each board so every board could be used for a separate community-driven competition.

For example, a board for most posts this month would have the post created score value set to 1 while all others are 0. Where a best like of the month board would have like given score value set to 1 and all others set to 0.

Like this /u?order=likes_given&period=monthly?

Yes, that is a similar idea but as part of the Gamification board, not the default user listing layout.

The discourse user list (/u) can be displayed in different ways, such as the user card directory theme component which is good for the global site user list but does not look as good for a user ranking page. So the suggestion to have each gamification board use a separate setting is valid and makes more sense than using the discourse user list in this situation.

A post was split to a new topic: Gamefication scoring for portugese forum?

How do I remove this leaderboard link from my sidebar? It seems to be automatically added, since it isn’t in the custom section links settings where I’d like it to be in order to move it to the More menu.

2024-11-02 at 15.35.26530×402 11.2 KB

I see Meta has figured this out, but I don’t see a configurable setting anywhere on my end.

As an admin on a site, you should be able to customise this section.

image453×804 14.9 KB

Exactly, I would think it should be listed there.

2024-11-02 at 16.23.122020×1258 263 KB

You should be able to use the = to drag it into the ‘More’ section.

Sorry I misread your post

2 posts were split to a new topic: Is There a Minimum User Requirement for Leaderboard Display?

A post was split to a new topic: How Do You Get Cheers?

2 posts were split to a new topic: Differences in Score Ranking Options

A post was split to a new topic: Users Complaining About Losing Points

I just noticed this has apparently been added at some point…how does one do this?

@Kartoon I think this is what you are looking for:

Hi @Discourse,

I’m just wondering if the events that award cheers can be “undone”. For example, when I mark a reply of one of my forum members as a solution, they’d receive 5 cheers. However, later I decide that said reply wasn’t a solution and unmark it, then would they lose the 5 cheers that were awarded to them?

Yes, but with a caveat that we only look 10 days behind when doing recalculations.

Optionally, you can use the “Recalculate Scores” button on the admin UI to trigger a wider recalculation.

Hey folks,

Is there a mechanism to inform users about where they are on the leaderboard or provide them with a mini summary of their weekly totals via email/dm?

I have read the posts around the possibility to use a badge and the custom SQL to award this when they reach a certain total but I was also wondering if people had any other experiences of using method to inform users?

There is no automated notification system at the moment.

What I’ve seen in the wild is communities establishing periods and doing a topic showcasing the top users at the end of each period, like quarterly, monthly, or annually.

Ah, that’s a good suggestion. Thank you.

Are there any plans from the team to include external (Email) or internal (PMs) notifications from the plugin?

Not currently, but if you have an idea of how that would work I’d love to see it posted as a feature request with details on Feature.

Regarding the new user invitation event, I encountered a minor issue during the actual operation. During the event, I set the invitation points value to 250 cheers. Some users invited 10 new members to join the community through the event and received 2500 cheers. However, after the event ended, I adjusted the invitation points back to the regular value of 50 cheers. As a result, the points of users who had already participated in the event and earned invitation points were also reduced from 2500 cheers to 500. Is there any way to avoid making such an adjustment?

I guess if you would have waited for 10 days and THEN changing the points, the score would stay unchanged.

I’m a bit confused by something, can you please clarify this?

I had “like receive score” at 0, and didn’t realise that an update 5 months ago added Discourse Reaction support and automatically added “reaction receive score” as 1.

I just changed that to 0, and recalculated everything, but nothing has changed.

Is that because in order for reaction to score, likes need a score? Have I not actually changed anything here?

Thanks!

Edit: never mind, just took a little while to change!

Indeed, recalculating everything from the beginning, plus the time to recreate all our cached tables may take a while depending on the site activity and server specs.

Is there any way, maybe with Data Explorer, to figure out where someone gets all their points from?

For example, see a user’s score and how many are from new topics, new posts, likes, reading, etc.?

There is this one Gamification Calibration, but… it needs updating to include the reaction and chat scores

Why did I wait a long time and my scores didn’t update automatically?

Hi cnlanny and welcome to our community! Scores are recalculated once a day via a background task.

I think they’re updated more frequently than that for ‘current’ events, and the daily job does a double check of anything that may have changed over the last 10 days:

Having said that… I think the frequency of the ‘scores for today’ was updated to be hourly instead:

Could someone check that and update the doc if needed?

Updated the wiki at the OP.

It’s an unfortunate trade-off. Previously we had quick updates, but the leaderboard view would be slow in very large sites.

We made the leaderboard performance stay good at any size, but updates are now much more involved so we had to cut back the speed

4 posts were split to a new topic: Troubleshooting Cheers score discrepancies

This plugin is now bundled with Discourse core as part of Bundling more popular plugins with Discourse core. If you are self-hosting and use the plugin, you need to remove it from your app.yml before your next upgrade.

Just wondering, now that the plugin is part of the Discourse core ones, is there a way to create multiple leaderboards but for different sections on the forums?

Also, happy birthday, @tobiaseigen!

AFAIK there is no change to the plugin itself.

Is it possible to somehow manually reset or rewrite the Leaderboard URL? In our case we tested some leaderbaords, deleted them later.

E.g. /leaderboards/5 to /leaderboards/1.

Is it possible to award points to a user as an extra reward?

You may want to see:

which has this curl request inside:

curl --location 'https://my.discourse.com/admin/plugins/gamification/score_events' \
--header 'Api-Key: <your key>' \
--header 'Api-Username: <your username>' \
--header 'Content-Type: application/json' \
--data '{
    "user_id": "101",
    "date": "2024-05-15",
    "points": "-141",
    "description": "Gamification point adjustment"
}'

I enabled this plugin in admin, but the leaderboard tab did not automatically appear. I also added new leaderboards, but they did not show up. Why is this happening? Where should I look for these leaderboards?

I think you have to add them to the sidebar yourself . The leaderboards are at /leaderboard, /leaderboard/2, /leaderboard/3 etc.

Is it possible to create a leaderboard for a specific category or tag?

Leaderboards are tied to groups. But you can specify which categories affect all the leaderboards in the gamification settings. Seems like an interesting idea to move that to the leaderboard, to for example have a Support leaderboard here in this community.

Screenshot 2025-09-18 at 6.21.53 AM674×110 6.64 KB

2 posts were split to a new topic: Reducing points for flagged users

Is there a way for me to exclude myself from the rankings?

yes add yourself to a new group (call it ‘leaderboard-exclusion’ or something) and then exclude the group in the plugin settings.

edit: this will also easily allow you to exclude anyone else if you so wish at some point, by adding them to the same group.

Thank you so much. That makes sense.

After I upgraded to version 2026.1.0, I created a monthly leaderboard, and then accessing the following route caused an error:

http://localhost:4200/admin/plugins/discourse-gamification/leaderboards

image1877×921 52.6 KB

The error is as follows:

assert.js:40 
 Uncaught (in promise) Error: Assertion Failed: You attempted to update `_value` on `TrackedStorageImpl`, but it had already been used previously in the same computation.  Attempting to update a value after using it in a computation can cause logical errors, infinite revalidation bugs, and performance issues, and is not supported.

`_value` was first used:

- While rendering:
  {{outlet}} for -top-level
    -top-level
      {{outlet}} for application
        application
          DiscourseRoot
            {{outlet}} for admin
              admin
                {{outlet}} for adminPlugins
                  admin-plugins
                    {{outlet}} for adminPlugins.show
                      show
                        AdminPluginConfigPage
                          AdminPluginConfigArea
                            {{outlet}} for adminPlugins.show.discourse-gamification-leaderboards
                              adminPlugins.show.discourse-gamification-leaderboards
                                {{outlet}} for adminPlugins.show.discourse-gamification-leaderboards.index
                                  discourse-gamification-leaderboards
                                    DPageSubheader
                                      (result of a `unknown` helper)

Stack trace for the update:
    at TrackedArray._dirtyCollection2 (array.ts:163:13)
    at Object.set (array.ts:126:15)
    at Proxy.sort (<anonymous>)
    at AdminPluginsShowDiscourseGamificationLeaderboardsIndexController.sortedLeaderboards (index.js:23:1)
    at AdminPluginsShowDiscourseGamificationLeaderboardsIndexController.<anonymous> (handle-descriptor.js:67:17)

I located the problematic file as follows:

plugins/discourse-gamification/admin/assets/javascripts/discourse/controllers/admin-plugins/show/discourse-gamification-leaderboards/index.js

Specific code:

  @discourseComputed("model.leaderboards.@each.updatedAt")
  sortedLeaderboards(leaderboards) {
    return (
      leaderboards?.sort((a, b) => compare(b?.updatedAt, a?.updatedAt)) || [] // line 22
    );
  }

The reason for the error is:

Ember.js (or more accurately, the Glimmer tracking system) assertion error in reactive state management. The core reason is: within the same computation cycle, you first read a tracked (tracked state) value, and then attempt to modify that value. This “use then update” operation can lead to logical confusion, infinite loops, or performance issues, so Ember directly prohibits this behavior.

Key issue:

• Array.sort() modifies the original array in place, which updates the @tracked leaderboards state.

• The responsibility of a computed property (sortedLeaderboards) is to derive a new value, not to modify the original state; it should itself be a “pure function” (no side effects, does not modify the input source).

Here is the fix:

  @discourseComputed("model.leaderboards.@each.updatedAt")
  sortedLeaderboards(leaderboards) {
    return (
      //leaderboards?.sort((a, b) => compare(b?.updatedAt, a?.updatedAt)) || []
      leaderboards?.slice().sort((a, b) => compare(b?.updatedAt, a?.updatedAt)) || []
    );
  }

Screenshot after fixing:

image1878×913 54.6 KB

And this kind of similar issue doesn’t seem to be an isolated case. I suspect it’s an incompatibility issue caused by the emberjs upgrade. However, many places in plugins haven’t been modified to keep up with the upgrade, as this work is not as simple as it sounds.

Question: Is there a delay as to when points are awarded. For example, new users are doing point paying things, like posting a new topic or giving a like, but their scores don’t show up. I have trust level 0 included in the settings, so I am assuming it’s just a delay in assigning points? If so, how often does it calculate and update? Thank you!

I would like to revisit this idea. For now I’ve locked the leaderboards to 1 category but this being moved to an individual leaderboard would be better.

That is something we really wanna do, just a matter of finding time to do it or getting a customer to sponsor the effort.

Hi there,

I created a new leaderboard, but it wiped the settings from my original leaderboard.

Is there a way to see select which leaderboard my users see front end?

You can customize a section to go directly to the chosen ranking link.

image676×783 56.4 KB