Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mattjegan/django-gamification

The missing Django Gamification Package
https://github.com/mattjegan/django-gamification

django gamification gamification-framework python python3

Last synced: 3 months ago
JSON representation

The missing Django Gamification Package

Awesome Lists containing this project

README 

        
Django Gamification

===================



|PyPI version| |Build Status| |Downloads|



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 `__.



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 `__.



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.



1. Fork the `django-gamification` repo on GitHub.

2. Clone your fork locally::



    $ git clone [email protected]:your_name_here/django-gamification.git



3. 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



4. Create a branch for local development::



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



   Now you can make your changes locally.



5. 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.



6. 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



7. 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