README.md

GAMaaS

Add locally stored achievements to your web application and encourage users to continue using and learning.

Installation

npm install gamaas --save

Usage

Most functions in this project are chain-able and allow you to append a . and the next function you wish to call.

Quickstart

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.

Getting started

.init(configOnject: Object): Gamaas

This method is used when setting up your achievements. It accepts an object with specific properties to setup GAMaaS.

Parameters

Param	Required	Type	Description
configOnject	Yes	Object	An object with specific properties to setup GAMaaS

Returns

Return	Type
gamaas	Object

Example

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
    }
});

.on(event: string, callback: Function): Gamaas

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.

Parameters

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.

Returns

Return	Type
gamaas	Object

Example

import gamaas from 'gamaas';

gamaas.init({
    // Config Object
}).on('progress', ({id, event}) => {
    console.log("A progress event!", id, event);
});

.progress(id: string, awarded?: Boolean = true): Gamaas

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.

Parameters

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.

Returns

Return	Type
gamaas	Object

Example

import gamaas from 'gamaas';

gamaas.init({
    // Config Object
}).progress('achievementId');

.regress(id: string, awarded?: Boolean = true): Gamaas

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.

Parameters

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.

Returns

Return	Type
gamaas	Object

Example

import gamaas from 'gamaas';

gamaas.init({
    // Config Object
}).regress('achievementId');

.award(id: string, awarded?: Boolean = true, reason: string = "Unknown"): Gamaas

The .award() method allows you to set the awarded status of an achievement which causes the progress event to be fired.

Parameters

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.

Returns

Return	Type
gamaas	Object

Example

import gamaas from 'gamaas';

gamaas.init({
    // Config Object
}).award('achievementId');

.reset(id: string, awarded?: Boolean = true): Gamaas

Parameters

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.

Returns

Return	Type
gamaas	Object

.store(): Gamaas

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.

Returns

Return	Type
gamaas	Object