Add locally stored achievements to your web application and encourage users to continue using and learning.
npm install gamaas --save
Most functions in this project are chain-able and allow you to append a .
and the next function you wish to call.
To get started quickly, run the below command to run the application in a Webpack'd server.
npm run start
Now point your browser to http://localhost:8090/
, open your browser's console, and access the gamaas
object directly as it is attached to the window
.
This method is used when setting up your achievements. It accepts an object with specific properties to setup GAMaaS.
Param | Required | Type | Description |
---|---|---|---|
configOnject | Yes | Object | An object with specific properties to setup GAMaaS |
Return | Type |
---|---|
gamaas | Object |
import gamaas from 'gamaas';
gamaas.init({
achievements: {
// One to many achievements
uniqueAchievementId : {
title : "Achievement Title", // The title of your achievement
worth : 5, // Number of points the achievement is worth
required : 5, // Amount of progress required to achieve the achievement
exceedRequired : false // Whether or not the achievement progress can exceed what is required
},
...
},
store : {
when : "always", // Whether to store the progress upon every action or when you call .store()
dataKey : "achievements" // Namespace for where to save your achievement progress within localStorage
}
});
The .on()
method requires two parameters, event
and callback
. The event can be one of four different types which include progress
, regress
, reset
or award
. .on()
is not required for GAMaaS to function. When any of the events occur, their associated callback function is called. The parameter passed to the callback function is a single object containing the id
of the achievement affected along with the event
that fired.
Param | Required | Type | Description |
---|---|---|---|
event | Yes | String | progress or regress or reset or award |
callback | Yes | Function | The function to be called when event occurs. |
Return | Type |
---|---|
gamaas | Object |
import gamaas from 'gamaas';
gamaas.init({
// Config Object
}).on('progress', ({id, event}) => {
console.log("A progress event!", id, event);
});
The .progress()
method is used when incrementing the progress (by 1) of the achievement. In this way if an achievement's progress is currently 1
and you .progress()
the achievement, it will then be 2
. if exceedRequired
is specified and is truthy, then .progress()
will not allow the progress to exceed the value specified in the required
property of the achievement.
Param | Required | Type | Description |
---|---|---|---|
id | Yes | string | The id of the achievement you wish to progress. |
awarded | No | Boolean | Whether or not you want to award the achievement when the progress meets its requirements. Defaults to true . |
Return | Type |
---|---|
gamaas | Object |
import gamaas from 'gamaas';
gamaas.init({
// Config Object
}).progress('achievementId');
The .regress()
method is used when decrementing the progress (by 1) of the achievement. In this way if an achievement's progress is currently 3
and you .regress()
the achievement, it will then be 2
. Achievements can not be reduced below 0.
Param | Required | Type | Description |
---|---|---|---|
id | Yes | string | The id of the achievement you wish to regress. |
awarded | No | Boolean | Whether or not you want to un-award the achievement when the progress is below or equal to its requirements. Defaults to true . |
Return | Type |
---|---|
gamaas | Object |
import gamaas from 'gamaas';
gamaas.init({
// Config Object
}).regress('achievementId');
The .award()
method allows you to set the awarded status of an achievement which causes the progress event to be fired.
Param | Required | Type | Description |
---|---|---|---|
id | Yes | string | The id of the achievement you wish to award. |
awarded | No | Boolean | The awarded state of the achievement id specified. Defaults to true . |
reason | No | string | A short description of why the award was given (or taken away). Defaults to Unknown . |
Return | Type |
---|---|
gamaas | Object |
import gamaas from 'gamaas';
gamaas.init({
// Config Object
}).award('achievementId');
Param | Required | Type | Description |
---|---|---|---|
id | Yes | string | The id of the achievement you wish to reset. |
awarded | No | Boolean | Whether or not you want to un-award the achievement when the achievement is rest. Defaults to true . |
Return | Type |
---|---|
gamaas | Object |
Stores the progress of the achievements to localStorage
. This is called automatically when you progress
, regress
, award
or reset
achievements when the store.when
config value is set to always
when you .init()
GAMaaS.
Return | Type |
---|---|
gamaas | Object |