Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/255bits/achieve
A framework agnostic library for defining achievements
https://github.com/255bits/achieve
Last synced: about 2 months ago
JSON representation
A framework agnostic library for defining achievements
- Host: GitHub
- URL: https://github.com/255bits/achieve
- Owner: 255BITS
- Created: 2012-06-28T04:53:08.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2012-06-28T05:28:48.000Z (over 12 years ago)
- Last Synced: 2024-04-09T16:40:30.651Z (9 months ago)
- Language: CoffeeScript
- Size: 105 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
#Achieve
A framework/persistence agnostic API for defining user achievements.
##High Level Overview:
* Achievements are defined as a list of required flags.
* Flags are set in the browser when a user reaches certain checkpoints.
* User-defined events are triggered when achievements get all the required flags.
##Typical usage
* `define` your list of achievements
* Add a listener for the `recieved` and `removed` events
* As the user does certain actions, add and remove `flags`
#Installing
For this beta, install by cloning this git repo and running [giles](/255BITS/giles). Please file bugs and provide feedback!
```bash
git clone git://github.com/255BITS/achieve.git
cd achieve
giles
cp achieve.js PROJECT_DIRECTORY/public
```
#API Documentation
##achievements
###define(required, achievement)
This creates a new achievement definition. This will not give a user an achievement.
`required` is a list of flags that the achievement requires to activate
`achievement` is the object that is passed to the listening callback
####Example
```coffeescript
achievements.define(['validPicture', 'validName'], {
name: 'profileSetup',
icon: '/badges/profileSetup.png',
message: 'Congratulations! Your profile is now setup.',
removalMessage: "Fix your profile buddy."
})
```
###flag(bit)
`bit` is a symbol designating the name of the flag.
This will toggle a flag as ON. If the correct flags are set to ON, a `received` event is triggered.
Calling `flag` on an existing ON `bit` will do nothing.
####Example
```coffeescript
achievements.flag('validPicture')
achievements.flag('validName')
```
###removeFlag(bit)
`bit` is a symbol designating the name of the flag.
This will toggle a flag as OFF. If an active achievements required flag is set to OFF, a `removed` event is triggered. Events
are only triggered once, when any of the required flags are set to OFF.
Calling `removeFlag` on an existing OFF `bit` will do nothing.
####Example
```coffeescript
achievements.removeFlag('validPicture')
```
###received(callback)
`callback` is a function that will execute when a new achievement is received.
####Example
```coffeescript
achievements.received (achievement) ->
console.log("User has a new achievement!")
console.log(achievement)
#This is where you would update your DOM
```
###removed(callback)
`callback` is a function that will execute when an achievement with all it's required flags set to ON has a flag removed.
####Example
```coffeescript
achievements.removed (achievement) ->
console.log("Your user lost an achievement. We have to tell them")
console.log(achievement)
#This is where you would give the user the bad news
```
#Changelog
v0.1.0 Initial documentation and unit-tested achievement system.
#License
Achieve is available under the MIT license. We hope you find it useful. Please let us at 255 BITS know if you use it for something cool.