Django Gamification

Django Gamification aims to fill the gamification sized hole 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.

Example App

An example app can be found here <https://github.com/mattjegan/django-gamification-example-app>__.

Installation

Download from PyPI:

pip install django-gamification

And add to your INSTALLED_APPS:

.. code:: python

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    .
    .
    .
    '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 ^^^^^^^^^^^^^^^^^^^^^

.. code:: python

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

class YourUserModel(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.

.. code:: 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()``.

.. code:: 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``.

.. code:: python

    from django_gamification.models import UnlockableDefinition

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

Contributing
------------

Submitting an issue or feature request

If you find an issue or have a feature request please open an issue at Github Django Gamification Repo <https://github.com/mattjegan/django-gamification>__.

Working on issues


If you think that you can fix an issue or implement a feature, please
make sure that it isn't assigned to someone or if it is you may ask for
an update.

Once an issue is complete, open a pull request so that your contribution
can be reviewed. A TravisCI build will run and be attached to your pull
request. Your code must pass these checks.

Get Started!

Ready to contribute? Here's how to set up django-gamification for local development.

Fork the django-gamification repo on GitHub.
Clone your fork locally::

$ git clone git@github.com:your_name_here/django-gamification.git
Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::

$ mkvirtualenv django-gamification $ cd django-gamification/ $ python setup.py develop
Create a branch for local development::

$ git checkout -b name-of-your-bugfix-or-feature

Now you can make your changes locally.
When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox::
```
$ py.test
$ tox
```
To get flake8 and tox, just pip install them into your virtualenv.
Commit your changes and push your branch to GitHub::

$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature
Submit a pull request through the GitHub website.

Helping others



At all times, please be polite with others who are working on issues. It
may be their first ever patch and we want to foster a friendly and
familiar open source environment.

.. |PyPI version| image:: https://badge.fury.io/py/django-gamification.svg
   :target: https://badge.fury.io/py/django-gamification
.. |Build Status| image:: https://travis-ci.org/mattjegan/django-gamification.svg?branch=master
   :target: https://travis-ci.org/mattjegan/django-gamification
.. |Downloads| image:: http://pepy.tech/badge/django-gamification
   :target: http://pepy.tech/count/django-gamification

mattjegan / django-gamification

readme

Django Gamification

Example App

Installation

Features and Examples