Metadata-Version: 2.0
Name: django-gamification
Version: 0.2.0
Summary: The missing gamification plugin for Django
Home-page: https://github.com/mattjegan/django-gamification
Author: Matthew Egan
Author-email: matthewj.egan@hotmail.com
License: BSD
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.8
Classifier: Framework :: Django :: 1.9
Classifier: Framework :: Django :: 1.10
Classifier: Framework :: Django :: 1.11
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Internet :: WWW/HTTP


# Django Gamification
[![PyPI version](https://badge.fury.io/py/django-gamification.svg)](https://badge.fury.io/py/django-gamification)

Django Gamification aims to fill the gamification sized whole in the Django package ecosystem. In the current state, Django Gamification provides a set of models that can be used to implement gamification features in your application. These include a centralised interface for keeping track of all gamification related objects including badges, points, and unlockables.

## Installation

```
pip install django_gamification
```

## Features and Examples
### Concepts
Django Gamification requires the understanding of a few core concepts.
- **BadgeDefinitions:** A template used to create new Badges and update existing Badges.
- **Badge:** An object that represents some achievable objective in the system that can award points and track its own progression.
- **UnlockableDefinition:** A template used to create new Unlockables and update existing Unlockables.
- **Unlockable:** An object that is achieved by some accumulation of points.
- **Category:** An object used to label other objects like Badges via their BadgeDefinition.

### Interfaces
#### Creating an interface
```python

from django.contrib.auth.models import User
from django.db import models
from django_gamification.models import GamificationInterface

class YourUserModel(models.User):
    # Your user fields here

    # The gamification interface
    interface = models.ForeignKey(GamificationInterface)
```

### BadgeDefinitions and Badges
### Creating a new badge
By creating a new `BadgeDefinition`, Django Gamification will automatically create `Badge` instances for all your current `GamificationInterfaces` with `Badge.name`, `Badge.description`, `Badge.points`, `Badge.progression` and `Badge.category` mimicking the fields on the `BadgeDefinition`.

```python
from django_gamification.models import BadgeDefinition, Category

BadgeDefinition.objects.create(
    name='Badge of Awesome',
    description='You proved your awesomeness',
    points=50,
    progression_target=100,
    category=Category.objects.create(name='Gold Badges', description='These are the top badges'),
)
```

### Awarding a badge
You can manually award a `Badge` instance using `Badge.award()`.

```python
from django_gamification.models import Badge

badge = Badge.objects.first()
# badge.acquired = False

badge.award()
# badge.acquired = True
```

### UnlockableDefinitions and Unlockables
### Creating a new unlockable
By creating a new `UnlockableDefinition`, Django Gamification will automatically create `Unlockable` instances for all your current `GamificationInterfaces` with `Unlockable.name`, `Unlockable.description`, `Unlockable.points_required` mimicking the fields on the `UnlockableDefinition`.

```python
from django_gamification.models import UnlockableDefinition

UnlockableDefinition.objects.create(
    name='Some super sort after feature',
    description='You unlocked a super sort after feature',
    points_required=100
)
```


