Trophy Essentials [M2N Addons]

[m2n]

A new product by m2n is available: Trophy Essentials 1.0.0 - Hugely improve trophies by awarding them for ongoing user activity


Trophy Essentials 1.0.0

Description

Xenforo’s trophies are based on the idea of milestones. For example, when you hit the milestone of posting your first 30 messages, you get awarded 5 trophy points.
Though admin can create more milestones, there are always a limited number and if trophy points motivate members, then once you have reached the top milestone, you will no longer be motivated by trophy points. Cumulative trophies remove the limit to trophies. Trophies unlimited!

If you wish to purchase or renew a license for this product, please register and then send a message to Stuart Wright to request access to purchase. Please include the URL of the forum you wish to use the product on.

The importance of trophy points
As a side discussion, obviously the importance of trophy points to members varies from one person to the next. While some people value their trophy score highly as a badge of achievement, others couldn’t care less. However, trophy points can be used to advance members up the membership ladder, so they can (and should) have a positive effect of adding member perks.

Cumulative trophies
Trophy Essentials awards points for each positive action a member takes. These are named Cumulative trophies and they can be awarded alongside the Milestone trophy points, though most Milestone trophy awards (e.g. for posting messages and earning positive reactions) become redundant.

Set up
Trophy admin is launched via Users > Trophies where the available trophies are separated into two tabs : Milestone trophies and Cumulative trophies. On first install, there are no cumulative trophies, and they will need to be added from the predefined list.

Note the option, set by default, to position the Cumulative trophies tab first, because it is likely to have more trophies.

Admin add cumulative trophies from a predefined list of cumulative trophy actions. This list contains the actions we feel need rewarding. Note that there are options to add negative trophy points for receiving negative reactions, receiving warnings and having reports rejected. Personally, I would only deduct trophy points when people get warnings.

Adding a cumulative trophy for posting a new thread

The most obvious positive action to award trophy points for, and by which all other trophy awards are measured, is the creation of a thread. This is the core action for growing a forum and so, by default, it will earn the poster 1 trophy point. Admin can set the title and description and number of points awarded for creating each thread. In addition, admin can set the frequency of alerts sent to users for receiving trophy points.

The next important action to grow a forum is replying to threads. So all posts will earn members .1 of a trophy point because we calculated that a new thread is worth 10 replies. Admin can, of course, set their own value for this.

Posting the first reply to a thread is also important to a forum, so there is also a cumulative trophy award for that.
As some trophy point awards can be a fraction of a whole point, when we display trophy points to a member, those actions worth less than a whole point, will have a bar showing the progress towards the next trophy point.

In the above screenshot, the member has posted 24 replies, each worth .1 trophy points and therefore has a total of 2.4 trophy points accumulated.
Note: when we display the cumulative trophy point totals, we only count whole trophy points.

Note: that users do not get trophy points for replying with the best answer to their own thread.

Usergroup promotions
Obviously veteran members who have posted thousands of threads will receive thousands of trophy points, (as opposed to a maximum of a couple of hundred, currently). That's the main reason why this change to the trophy point system is so significant.

Usergroup promotions
Admins will need to think carefully how they use trophy points to promote members up the usergroup ladder because you probably want to avoid having lots of people demoted.
Studying the Members page /members/ may help because it shows the number of messages, reactions and current points.
For AVForums, I used database queries to produce a list of the users in each usergroup showing the fewest number of threads, replies and reactions and worked out the best number of trophy points to use to promote people up the groups. A total of roughly 280 people in our top two usergroups (out of a total of over 400,000 members) were demoted.
For reference, this was the old promotion system:

Promotion requirements	Posts	Reactions	Days registered	Trophy points
Novice to Standard	1	3	1
to Established Member	50	3	1
to Prominent Member	50	3	1	75
to Distinguished Member	50	3	1	150

And this is the new promotion system with cumulative trophies

Promotion requirements	Posts	Reactions	Trophy points
Novice to Standard		3
to Established Member	50	3
to Prominent Member	50	3	250
to Distinguished Member	50	3	1000

Redundant milestone trophies
Most existing milestone trophy point awards - those for creating threads and posts, and for receiving positive reactions - will be redundant if points are awarded on a cumulative basis for these actions. So forum admin will likely want to delete those. Doing so instantly recalculates the trophy totals for members.
There may still be some milestone awards for actions like adding an avatar or subscribing to a newsletter.

Rebuilding Cumulative trophies
Once the cumulative trophies have been set up, the totals will need to be recalculated for all members.
This can be done using the new Rebuild user cumulative trophies function in /admin.php?tools/rebuild Tools > Rebuild caches. But because it takes quite some time to run, if you have a large forum, it may be wiser to use the command line
php cmd.php xf-rebuild:m2n-trophy-essentials-cumulative-trophies

Be aware that this will trigger the award of trophies to all members and (unless you temporarily turn all notification frequencies to 0) they will all get alerts.

Performance
There are no significant performance issues with Trophy Essentials. It is running fine on AVForums, MGEVs and ORAEVs.

Phrases
The addon is fully phrased. We advise that you change the phrase
x_has_not_been_awarded_any_trophies_yet
From
{name} has not been awarded any trophies yet.
To
{name} has not been awarded any milestone trophy points, yet.

Displaying trophies to users
The two trophy type tabs are shown consistently throughout the forums

The member statistics page will need a tweak to disable the Most points list since the new Most trophy points list will be enabled by default…

…to display the new trophy totals.

Extending trophy actions to support other actions
For information on how to extend Trophy Essentials to support other actions, please see the attached PDF document.


Extended Product Information

Add new trophy type - Cumulative Trophies which are awarded on an ongoing basis
Users are more motivated to contribute to the community because all positive actions have trophy point rewards
Admin set up Cumulative Trophies and their trophy point values


Read more about this product...

 

[Stuart Wright]

The following outlines the steps required to add a new cumulative trophy definition.

Adding a new cumulative trophy definition​

This can be done under Admin > Development > Cumulative trophy definitions. When you click the Add button, the following fields need to be specified:

• Definition ID
  • A unique key to identify this definition
• Title
  • A title to identify this definition and serves as the default display text for a cumulative trophy
• Description
  • A description to describe what the trophy definition does and serves as the default description text for a cumulative trophy
• Default points
  • The default number of points that will be awarded each time this cumulative trophy definition action is completed.
• Default notification frequency
  • How many trophy points should be awarded before a user is notified of gaining trophy points.
• Add-on
  • The add-on you are developing.

Shipping a new cumulative trophy definition​

Currently this is done by inserting a new cumulative trophy definition via the Setup class of your add-on.

You can use the \\M2N\\TrophyEssentials\\Setup::insertCumulativeTrophyDefinition() function to insert the cumulative trophy definition(s).

The arguments this accept match the fields required for adding a cumulative trophy definition in the UI:

string $definition_id, string $addon_id, float $default_points = 0.10, int $default_notification_frequency = 1

Creating a new cumulative trophy using the new definition​

Go to Admin > Users > Trophies > Cumulative trophies > Add cumulative trophy.

After selecting the definition, set up the options as desired.

Adding trophy points when an action is completed​

Whenever you wish to award points for a cumulative trophy, you simply need to call the following function as follows:

\\M2N\\TrophyEssentials\\Repository\\CumulativeTrophy::logCumulativeTrophyAction('definition_id', $user);

This will award trophy points for the definition_id definition to the $user passed in.

Other arguments for logCumulativeTrophyAction​

string $definitionId, \\XF\\Entity\\User $user, bool $isDelete = false, int $multiplier = 1, int $overrideCount = 0

• $definitionId - The cumulative trophy definition ID points are being awarded for
• $user - The user entity points are being awarded to
• $isDelete - false (default) if you are adding points and true if you are removing points
• $multiplier - If you want to give extra weight to the points being awarded, you can increase the multiplier. For example, positive reactions are multiplied by the reaction score of the reaction
• $overrideCount - This is used when rebuilding cumulative trophies. For example if a user has performed 10 valid actions, you can specify $overrideCount as 10 to apply the cumulative trophy points that many times

Creating a rebuild action​

Rebuild actions actually have two functions. They are utilised when analysing a user’s cumulative trophies and they are utilised when rebuilding a user’s cumulative trophies.

To add a new rebuild action for your cumulative trophy you must extend M2N\\TrophyEssentials\\Repository\\CumulativeTrophy and add a new method. The method name is a camelCased version of your definition ID.

For example if your cumulative trophy definition ID is your_addon_some_action you will add a new function named rebuildYourAddonSomeAction.

The arguments for the function must be as follows:

\\M2N\\TrophyEssentials\\Entity\\CumulativeTrophy $trophy, User $user, bool $pointsOnly = false

The function must return a float representing the number of points awarded for that action.

• $trophy - The cumulative trophy entity
• $user - The user being rebuilt or analysed
• $pointsOnly - false if this is a rebuild true if this is analysing

For a good example check out M2N\\TrophyEssentials\\Repository\\CumulativeTrophy::rebuildM2nPostReply.

• Valid posts are counted
• If there are posts and $pointsOnly is true then we call logCumulativeTrophyAction with the counted posts passed in as the $overrideCount
• We return the count multiplied by the trophies points

 

[m2n]

A new update is available for Trophy Essentials by m2n.


Trophy Essentials 1.0.2

Update highlights

We decided not to count trophy points for posts which do not count towards the post count.
If certain forums are set to not have the posts count towards users' post counts, then it makes sense not to award trophy points for them either. This then maintains consistency between the post count and trophy points count.


Complete Change Log

Tweak to functionality


Read more about this product...

 

[m2n]

A new update is available for Trophy Essentials by m2n.


Trophy Essentials 1.0.4

Update highlights

The Xenforo 2.2.13 release broke the trophy count display in the member's page. It showed as 24 instead of 24,000.
This release fixes that.


Complete Change Log

Bug fix.


Read more about this product...