Quest Engine

This document describes the Quest Engine, including how to create quests and what the available predicates are.

Creating Quests

Quests can be created in the admin page of the system. Quests require a name, slug, description, level, unlock conditions, and completion conditions. The slug is a unique identifier that is automatically generated from the name of the quest. The level of a quest determines its priority in the user's quest window. Higher level quests typically involve more work than lower level quests. The level of a quest can be zero or even negative numbers. The important sections are the unlock conditions and completion conditions.

Unlock conditions are the conditions a user needs to meet in order to have this quest possibly appear in their quest window. Note that since the user can only have up to 3 quests, the quests with the lowest levels will appear first. Completion conditions are the conditions a user needs to meet in order to complete the quest. Quests can only be completed after the user accepts the quest.

For both unlock and completion conditions, the contents of the conditions are implemented using a subset of Python. In addition to a few basic boolean operations (and, or, not, True, False), there are a few functions that can be used in the expression. Each of the additional functions return True or False. For a condition to be valid, the conditions expressions needs to return True or False for a random user.

Available Functions

These functions can be used as predicates in the unlock and completion conditions.

has_task(slug=None, task_type=None, name=None)

has_task's behavior changes depending on the parameter. If the slug parameter is provided, then the method returns True if the user is participating in the task with that slug. If the task_type parameter is provided, then the method returns True if the user is participating in a task of that type (event, commitment, activity, survey, excursion). The method will throw an exception if neither of these parameters are specified. If both are specified, name takes priority. Note that to specify only a task_type, you can either use a named parameter or use has_task(None, 'commitment').

Examples

• has_task(slug="foo") returns True if the user is participating in a task with slug "foo".
• has_task(task_type="commitment") returns True if the user is participating in a commitment.

Note

This predicate previously used "name" instead of "slug". "name" will still work for now, but may be removed in the future.

completed_task(name=None, slug=None, task_type=None)

completed_task is similar to has_task. If the slug parameter is provided, then the method returns True if the user has completed the task with that slug. If the task_type parameter is provided, then the method returns True if the user has completed a task of that type (event, commitment, activity, survey, excursion). The method will throw an exception if neither of these parameters are specified. If both are specified, slug may take priority. Note that to specify only a task_type, you can either use a named parameter or use completed_task(None, 'commitment').

Examples

• completed_task(slug="foo") returns True if the user has completed the task with slug "foo".
• completed_task(task_type="commitment") returns True if the user has completed a commitment.

Note

This predicate previously used "name" instead of "slug". "name" will still work for now, but may be removed in the future.

has_points(points, round_name=None)

has_points returns True if the user has at least the number of points. An optional round_name parameter can be used to specify a round (i.e. "Round 1" or "Round 2").

Examples

• has_points(10) returns True if the user has at least 10 points overall.
• has_points(10, "Round 1") returns True if the user has at least 10 points in round 1.

allocated_ticket()

allocated_ticket() returns True if the user has ever allocated a ticket in the raffle game.

num_tasks_completed(num_tasks, category_name=None, task_type=None)

num_tasks_completed takes an integer (num_tasks) and returns True if the user has completed at least that many tasks in the system. The optional category_name parameter only counts the tasks completed within that category. The optional task_name parameter only counts tasks of the given type ('event', 'commitment', 'activity', 'excursion', 'survey'). Note that you can also use named parameters. For example, if you want to provide a task_type but not a category_name, you can do something like num_tasks_completed(1, task_type='activity')

Examples

• num_tasks_completed(1) returns True if the user completed at least one task in any category of any type.
• num_tasks_completed(1, category_name="Foo") returns True if the user has completed one task of any type in category Foo.
• num_tasks_completed(1, task_type='commitment') returns True if the user has completed a commitment.

badge_awarded(badge_slug)

badge_awarded takes a single parameter badge_slug which is used to identify the badge. It returns True if the user has the badge.

posted_to_wall()

posted_to_wall takes no parameters and returns True if the user has created any posts on their lounge wall.

set_profile_pic()

set_profile_pic takes no parameters and returns True if the user has a profile picture set.

Example Quests

To be completed.