Extension:AchievementBadges

**MediaWiki extensions manual**
AchievementBadges; Release status: experimental
Implementation	Special page
Description	Provides an achievement system
Author(s)	Femiwiki Team
Latest version	0.3.0
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki	1.35+
License	GNU Affero General Public License 3.0 or later
Download	Download extension ; Git [?]: Download Git master; browse repository (GitHub); commit history; repository contributors (GitHub); code review; ; CHANGELOG
Help	Help:Extension:AchievementBadges
	Parameters $wgAchievementBadgesAchievementFallbackOpenGraphImage; $wgAchievementBadgesFacebookAppId; $wgAchievementBadgesDisabledAchievements; $wgAchievementBadgesReplaceEchoWelcome; $wgAchievementBadgesReplaceEchoThankYouEdit; $wgAchievementBadgesAchievements; $wgAchievementBadgesEnableBetaFeature; $wgAchievementBadgesAchievementFallbackIcon;
	Hooks used BeforeCreateAchievement; BeforeCreateEchoEvent; BeforeEchoEventInsert; GetBetaFeaturePreferences; SpecialAchievementsBeforeGetEarned; LocalUserCreated; UserSaveSettings; PageSaveComplete;
	Hooks provided BeforeCreateAchievement; SpecialAchievementsBeforeGetEarned;
Quarterly downloads	13 (Ranked 127th)
	Translate the AchievementBadges extension if it is available at translatewiki.net

AchievementBadges is an extension that provides an achievement system for MediaWiki wikis.

No Dependencies: There are only optional dependencies, unlike other similar achievement system extensions.
Customizability: There are built-in achievements, but you can disable each of them as needed.
Extensibility: If you are a developer, you can create your own achievements via hooks.

Features

Special:Achievements shows the list of the achieved achievements to logged-in users.
The user who earned an achievement will get notification. (Echo required)
You can install AchievementBadges as a beta feature. (BetaFeatures required)

Installation

Download and move the extracted AchievementBadges folder to your extensions/ directory.
Developers and code contributors should install the extension from Git instead, using:cd extensions/ git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/AchievementBadges
Add the following code at the bottom of your LocalSettings.php file:
```
wfLoadExtension( 'AchievementBadges' );
```
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

Parameters

TBD. See the extension.json for live update.

Variable	Default value	Description
`$wgAchievementBadgesEnableBetaFeature`	`false`	Whether to have AchievementBadges available only as a beta feature and only shown to the users who have enabled the beta feature.
`$wgAchievementBadgesReplaceEchoThankYouEdit`	`true`	Whether to suppress edit milestone notifications sent from Echo.
`$wgAchievementBadgesAchievementFallbackIcon`	`'extensions/AchievementBadges/images/achievement-icon-fallback.svg'`	Path to the fallback icon of achievements which is relative to the $wgScriptPath. The icon can be different for ltr and rtl languages. icons for specific languages can also specified using the language code.
`$wgAchievementBadgesAchievementFallbackOpenGraphImage`	`'extensions/AchievementBadges/images/achievement-og-image-fallback.png'`	Path to the fallback imago of achievements which is showed as an Open Graph image. Could be an array value, like $wgAchievementBadgesAchievementFallbackIcon
`$wgAchievementBadgesAchievements`	`[]`	Contains a key-value pair list of achievements. The thresholds should not be changed.
`$wgAchievementBadgesDisabledAchievements`	`[]`	Keys of achievements should be excluded.
`$wgAchievementBadgesFacebookAppId`	`false`	Facebook App id for SNS sharing.
`$wgAchievementBadgesAddThisId`	`false`	AddThis id for SNS sharing. it could include tool id in a form of array has keys 'pub' and 'tool'.

Others

SNS sharing links display in Special:ShareAchievement are just plain text. The interface administrator of the wiki can styling it via Common.css. See below example.

.mw-special-ShareAchievement .share-media a {
  display: inline-block;
  width: 2em;
  height: 2em;
  background-size: 2em;
}
.mw-special-ShareAchievement .share-media span {
  display: none;
}
.mw-special-ShareAchievement #share-achievement-facebook {
  background-image: url(https://PATH/TO/SOME_LOGO.png);
}
.mw-special-ShareAchievement #share-achievement-twitter {
  background-image: url(https://PATH/TO/SOME_LOGO2.png);
}

Creating a new achievement

Do not create a new achievement during the beta period.

Definitions

Achievement definitions happen in the method that responds to the BeforeCreateAchievement hook.

If you are adding a achievement type, its name should be 32 bytes or less including the index number(edit-page-3). The numbers is appended to the key of stats achievements automatically based on the thresholds of the achievements.

public static function onBeforeCreateAchievement( array &$achievements ) {
    global $wgScriptPath;
	$achievements['my-new-achievement'] = [
		'type' => 'instant',
		'priority' => 500,
		'icon' => "$ScriptPath/path/to/icon.svg",
		'og-image' => "$ScriptPath/path/to/og-image.png",
	];
}


	description	default	allowed value
type	TBD.		`'instant'` or `'stats'`
priority	TBD.	`1000`	int
icon	TBD.	`$wgAchievementBadgesAchievementFallbackIcon`	string
og-image	TBD.	`$wgAchievementBadgesAchievementFallbackOpenGraphImage`	string

Your i18n messages:

achievementbadges-achievement-name-my-new-achievement - for the name of the achievement. This is appears as a title of notification, displayed as a description in Special:Log, and displayed in Special:Achievements and Special:ShareAchievement.
achievementbadges-achievement-hint-my-new-achievement - for the Special:Achievements description that appears when the achievement is not achieved.
achievementbadges-achievement-description-my-new-achievement - for the Special:Achievements description that appears when the achievement is achieved and displayed in Special:ShareAchievement.

TBD.

Trigger the achievement

public static function onSomeHook( User $user ) {
    if ( !$user->isAnon() ) {
        Achievement::achieve( [ 'key' => 'my-new-achievement', 'user' => $user ] );
    }
}