Created: 2012-03-21 13:16
Updated: 2016-09-29 04:47

Django Hero

Hero is a powerful, extensible, reusable application that provides support for awarding "Achievements" to users in Django.


Add hero to your INSTALLED_APPS:

  # ...

Add the autodiscover function to your for your convenience.

# Register achievements
import hero

Optional: Hook up hero to your URLconf for some default views.

urlpatterns = patterns("",
  # ...
  url(r"^achievements/", include("hero.urls"))


ACHIEVEMENT_LEVELS (=((1, "Bronze"), (2, "Silver"), (3, "Gold"),(4, "Diamond"),))

ACHIEVEMENT_IMAGE_LOCKED (='achievements/images/default-locked.jpg')

ACHIEVEMENT_IMAGE_UNLOCKED (='achievements/images/default-unlocked.jpg')

ACHIEVEMENT_IMAGE_SECRET (='achievements/images/default-secret.jpg')


Start by creating a file in your app/project. The autodiscover function will pick this up. Here you will define your custom achievements.

A achievement object might look like this:

from hero import AchievementMeta
from hero.models import AchievementUnlocked

class TestAchievement(AchievementBase):
  Achievement attribute's
  id             = "comments_50"
  title          = "50 comments"
  description    = "User has posted 50 comments"
  secret         = False
  invisible      = False
  image_locked   = 'achievements/images/default-locked.jpg'
  image_unlocked = 'achievements/images/default-unlocked.jpg'
  image_secret   = 'achievements/images/default-hidden.jpg'

  Event's on wich this achievement should be called
  events = [
  def unlock(self, **state):
    Validates unlock requirements
    user = state["user"]
    points = 5000
    if points == 5000:
      return AchievementUnlocked(level=1)

There are a few relevant attributes and methods here.

  • attribute:: id :: required

    The unique identifier for the 'Achievement', it should never change.

  • attribute:: title :: required

    Title for this achievement

  • attribute:: description :: optional

    Description for this achievement

  • attribute:: secret :: optional

    The achievement is visible for a user but does not reveal its title, description, etc untill the user unlocks it.

  • attribute:: invisible :: optional

    Invisible achievement. Invisible achievements should not be revealed untill a user unlocked it, neither does it shows as a secret achievement in listings.

  • attribute:: image_locked :: optional

    Override default locked achievement image

  • attribute:: image_unlocked :: optional

    Override default unlocked achievement image

  • attribute:: image_secret :: optional

    Override default hidden achievement image

  • attribute:: events :: optional

    A list of events that can possibly trigger this achievement to be unlocked.

  • method:: unlock :: required

    This method returns whether or not this achievement should be unlocked for a user. 'state' is guaranteed to have a "user" key, as well as any other custom data you provide. It should return either a AchievementUnlocked instance, or 'None'.

Now just call the acchievements.unlock method for an event. Any achievement registered with the given event will get it's "unlock" method called and unlock it for a user if validates.

import hero

hero.achievements.unlock("points_awarded", user=request.user) 

Achievement's are saved to the DB aswell. This way you can use Django's ORM to query achievements.

  • Sjoerd Arendsen
Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more