< Back to Manuals

Processes

At its core a process is a way of structuring your players interactions with the game. You can create a simple linear sequence of activities for a player to do or complex choice driven quests.

Processes are the most powerful component available to you in a game. They make it possible to create complex and flexible player journeys. The way you use processes depends on the type of gamified system you wish to make.

There are several benefits you can reap from well defined processes within a game:

  1. Sketching out the player journey as a process forces us to think through the actual player experience. We can put ourselves in the player's shoes, and that helps us design better experiences.
  2. Processes enable you to change the player experience and see the impact immediately in the game.
  3. Breaking down an activity into many short steps enables the player to receive feedback on each step. This increases the probability of a player making it through the entire process especially if its long.
  4. Processes make it easy for us to find out which step of a activity causes people to get stuck or give up. We can then use that insight to improve the player experience.
  5. Finally processes enable you to create external games much faster. Playoff takes care of all the complex state transitions and player progress tracking.

Use Cases

Processes are great when you need to create things like skill trees. In the context of an online education platform, good skill trees encourage players to learn and allow them to build their own skill set as per their interests. The process of guidance can be very easily tweaked and tested with Playoff.

With features such as Lanes and Escalations, processes work well for role based activities too. In an organization, processes are generally well defined and often involve people with different roles, which makes processes in playoff a natrual fit.

Building a Process

A process consists of a set of nodes connected together with a set of flows. There are 4 types of nodes that you can create in a process:

  1. Task

    These are the bread and butter of a process. A task can be any activity that you wish your players to perform. All the other nodes are just helpers to control the order in which tasks can be performed. A task can have only 1 incoming flow (in-flow) and 1 outgoing flow (out-flow).

    Basic Task Properties
    Property Description
    ID A unique ID for the task within the process/sub-process
    Name A name for the task
    Loop Count The number of times a player can loop over the task. [default: 0]
    Lane The lane to which this task belongs
  2. Sub-Process

    A sub-process is almost the same as a process. You can use sub-processes to model complex processes which are big and difficult to visualize. You can also use it to break down the player journey into different modules.

    Basic Sub-Process Properties
    Property Description
    ID A unique ID for the sub-process within the process/sub-process
    Name A name for the sub-process
    Instance Key A unique key which identifies this sub-process from all other sub-processes within the process. You can use this to access a particular sub-process within a complex process from the API.
    Loop Count The number of times a player can loop over the sub-process. [default: 0]
    Lane The lane to which this sub-process belongs
  3. Parallel Gateway

    Diverging parallel gateways allow a player to perform many different task in any order they wish (i.e., in parallel).

    A diverging parallel gateway has more out-flows than in-flows.

    Converging parallel gateways allow a player to proceed along the out-going flow only after they complete all in-flows. It provides a way of synchronizing different paths of progress before moving forward.

    A converging parallel gateway has less out-flows than in-flows.

    Basic Parallel Gateway Properties
    Property Description
    ID A unique ID for the gateway within the process/sub-process
    Name A name for the gateway
    Lane The lane to which this sub-process belongs
  4. Exclusive Gateway

    Diverging exclusive gateways allow a player to perform exactly one task from among the many available alternatives.

    A diverging exclusive gateway has more out-flows than in-flows.

    Converging exclusive gateways allow you to merge progress along different paths together.

    A converging exclusive gateway has less out-flows than in-flows.

    Unlike converging Parallel gateways, converging Exclusive gateways allow players to proceed along it's out-going flows before they complete all in-flows.

    Basic Exclusive Gateway Properties
    Property Description
    ID A unique ID for the gateway within the process/sub-process
    Name A name for the gateway
    Lane The lane to which this sub-process belongs

Connection Restrictions

Building processes using nodes and flows is fairly straight forward, however, there are some restrictions:

  • Tasks/Sub-Processes can only have 1 out-flow and 1 in-flow
  • Gateways can be either converging or diverging.
    • Diverging gateways have atmost 1 in-flows and atleast 1 out-flows
    • Converging gateways have atmost 1 out-flows and atleast 1 in-flows

Start Nodes

All nodes without any in-flows in a process are called Start Nodes. When a player starts a process, the very first tasks available to him are the Start Nodes in a process.

Common Flow Patterns

There are a lot of things you can achieve with processes, from designing approval systems, to parallel quests and more! We illustrate some of the most common flow patterns below:

Linear Flow

You can use this flow to model a linear sequence of activities which the player must perform.

The Linear (Sequence) Flow layout

Approval Flow

You can use this flow to model a simple approval mechanism. In the diagram, only candidates of the admin lane can perform the approve task. When a player finishes the approve task it resolves the scoring actions on the work task.

An approval flow

Parallel Split Flow

You can use this flow to model many choices available to a player which the player can perform in any order.

The Parallel Flow layout

Exclusive Choice Flow

You can use this flow to model many choices available to a player out of which exactly they can perform exactly one choice.

The Exclusive Choice layout

Synchronization Flow

You can use this flow to synchronize several paths that a player could take at a common point before moving forward.

The Synchronization Flow layout

Merge Flow

You can use this flow to merge several paths a player could take at a common point. It allows the player to move forward without finishing all incoming paths.

The Merge Flow layout

Cancelling Merge Flow

You can use this flow to merge several paths a player could take at a common point. As soon as the player reaches the common point, all tasks on incoming paths are cancelled. Players cannot complete a cancelled task.

The Cancelling Merge Flow layout

Sub-Processes

Sub-Processes are an effective way to manage arbitrary complexity within your processes. Sub-Processes are like small processes within a larger one. There are a few things you need to know to work with sub-processes.

Task IDs in Sub-Processes

Sub-Processes add a new context for your tasks. This means that two different sub-processes can have tasks with the same IDs within them. This can be useful for repeated tasks across many sub-processes.

Navigating Sub-Processes

  • Hover your mouse over the sub-process.
  • Click the expand icon which pops up (1).

expand sub-process icon

You will now see the internal details of the sub-process. You can see a breadcrumb which appears at the bottom of the showing the root process at the leftmost end and the sub-process to its right. You can click on any part of the breadcrumb (2) to navigate to that sub-process.

Lanes

Lanes are a restricting mechanism used to divide the tasks within a process among different types of players. This allows you to co-ordinate complex activities between many different teams of players.

Candidates of a lane are eligible to perform tasks/sub-processes/gateways belonging to that lane. Players can be a part of multiple lanes and cannot perform tasks in lanes they are not a part of.

You can combine lanes with resolution to create an approval mechanism.

Rate Limiting

Playoff allows you to control the rate at which any task or sub-process within a process can performed. You can use this to create an effective an anti-gaming mechanic which prevents players from abusing your system. You can also use it to effect scheduled daily, weekly or monthly tasks.

There are 3 different types of rate limits that can be applied, they are:

  1. Rolling Window - A moving window type rate limit essentially means that at any given point in time, the activity can only be done a specified number of times in the last interval. Let us say your rate limit is 5 times per day, this would translate to a limit of 5 times in the last 24 hours (more precisely, in the last 24x60x60x1000 milliseconds) at any given point in time. Since we need to store timestamps for each event, there is a limit of 50 events in an interval. This is the default algorithm.

  2. Fixed Window - In a fixed window rate limit, the windows are fixed at particular time intervals - minutes, hours, days, weeks, months and years. What this means is that if your rate limit is 5 per day, the activity can be performed 5 times in a calendar day. In this alogirthm, the game's timezone is used to figure out calendar limits. The interval unit has been restricted only to 1 (i.e. 5 times in 1 day, in 1 minute, etc) as some other values can lead to unexpected results.

  3. Leaky Bucket - The leaky bucket algorithm, though generally used in the world of networking, might also find use in games. You can read more about it here.

Rate Limiting a Task/Sub-Process

  • Select the task/sub-process you wish to rate limit.
  • Click the Timed tab in the property window of the node.

    Rate Limiting

  • Click the Limit Rate button and specify the rate you want to cap the task/sub-process at.

    Rate Liming Setting

Notifications

Notifications enable players to interact with a process through their email.

Setting up notifications

  • Select a task/gateway and go to the Notify tab
  • Click the Set Notifications button

    Notify

  • Write the email template and notification message.

    Create Trigger Email

You can customize the email itself with simple tags to provide contextual information.

Tag Description
[[user]] Complete user name
[[user:first_name]] User's first Name
[[user:last_name]] User's last name
[[actions]] Available actions that the player can take. If the email is set on a task/sub-process the successive node is the only possible action. If it is set on a gateway all available out-flows are possible actions that the player can take.
[[global_logs]] Recent game logs (level + achievement logs) from the last notification
[[local_logs]] Recent activity logs in this process from the last notification
[[date]] The date when the mail is sent

Playoff sends an email whenever a node with an notification email is completed. The recipient of the email can be set by using the following options:

  1. Target The Target can be set to either one of these options.

    Option Description
    Myself Sends an email notification to the player who completes the task.
    Teammates Sends an email notification to the teammates of the player who completes this task.
    Members of this process Sends an email notification to all members of this process.
    Teammates of all members of this process. Sends an email notification to all the team members of all the performers of this process.
  2. Target Requirements In addition to the above, additional conditions can be specified in target requirements.

If the email had notifications and the recipient was not a performer in the process, he can be added into the process. The lanes and roles he joins with can be defined in target roles. He can then act on a notification email by replying with the number specifying the action they wish to take on the notification.

Scoring

A task/sub-process can have multiple rewards which take place when they are completed. Rewards change the scores of the player who performed the task/sub-process.

Advanced Scoring Mechanics

Besides the normal simple scoring mechanism, Playoff provides you a number of advanced scoring mechanics which can be used to make complex gamified experiences.

Chance

When a player completes a task the scoring actions associated with it are always applied to the player. Using the chance mechanic you can specify the probability of Playoff applying a reward.

There are 2 types of chance mechanics currently:

  1. Activity Reward Chance - This is the probability of Playoff trying to apply the rewards of an activity. If the activity has no rewards this does not have any effect. You can do this if you have many rewards on an activity and wish to have Playoff always apply them together.
    Activity Reward Chance
  2. Individual Reward Chance - This is the probability of Playoff applying an individual rewards to a player. You can do this if you want to set a different chance for applying each reward on the completion of an activity.
    Individual Reward Chance

You can combine both Activity Reward Chance and Individual Reward Chance together on a single activity.

Resolution

You can use scoring resolutions to delay the application of rewards on a player. Instead of applying the rewards on completion of a task you can specify a second task as the resolution task for the reward. Reward Resolution

Playoff resolves the reward and applies it to the performer of the first task once a player completes the resolution task .

Reward Resolution Post

The resolution mechanic can be combined with lanes to create an approval flow

Recurrence

Recurrence is a mechanic which only works with looped tasks. Usually, Playoff applies the reward on a looped task only once the task has been completed. A looped task is considered to be complete only after all it's loops are complete. Sometimes this is not the desired behavior. You may wish to apply the reward on every loop of the task. This can be done by marking the reward as a recurring reward.

Recurring Reward

Scopes

Scopes let you create leaderboards for an arbitrary group of players. These are particularly useful when you want to create groups based on the source of an event.

Scopes are available only from Playoff API v2.0

Consider a class in which students are being offered various optional courses. Each course has quizzes which on completion grant rewards to the students. To maintain a leaderboard for any given course, instead of creating teams for each course, you can simply pass the course's name or any other unique identifier as the scope and a leaderboard for that course will be created on the fly. This leaderboard will only track actions/rules/processes that have been performed with the given scope.

Scopes are currently available only via API and are not available in the simulator and would need a custom leaderboard in the design of the game. When executing an action, rule or task, you need to pass the scopes an array of objects with a keys id and entity_id. The id is the actual scope ID and the entity_id is the ID of the player who is being scored.

Joining Channel

Joining channel basically lets you manage how other players can join a process. There are 3 choices:

  1. Free To Join - The process is visible and anyone can join it with any role and lane.
  2. Request Based - The process is visible but players need to request access to join the process.
  3. Invite Only - The process is not visible to players who are not a part of the process. Players can only join via invitations.

Creation Requirements

Conditions that the player must satisfy in order to be able to create a process instance.

Restrictions

Restrictions can be set on the process creation itself. These restrictions can be either per player restrictions or global restrictions.

  1. Process Limit - Limit the maximum number of process instances created. Default: Infinity
  2. Active Process Limit - Limit the number of maximum active processes that can exist at any given point. Default: Infinity

Design Structure

There are two parts to a process:

  1. the design, which we call the definition of the process, and
  2. the instance, which is created by the players when they are in the game

Both the definition and the instance have very separate structures. The definition structure is as follows:

Process Definition Structure

The design structure is what is used when you are making the process.

Field Description
id A unique ID for the process.
name A name for the process.
description A brief description of the process.
image An image which represents the process. You need to send a multipart form POST request to upload the image data.
settings Settings for the whole process. See the Settings section for details.
lanes Lanes can be used to retrict players to a particular task/tasks. Each lane has a structure described in the Lane Structure section below
id A unique ID for the process.

Settings Structure

Field Description
access The access settings with which the process instance can be created. It is an array which can contain any or all of these PUBLIC, PROTECTED, PRIVATE. When players create an instance of this process, they get the chance to choosing only one of the access settings you set in the array.
max_global_instances The maximun number of process instances that can be created from this process.
max_active_global_instances The maximun number of active process instances that can be created from this process
max_player_instances The maximum number of process instances that a player can create from this process
max_active_player_instances The maximum number of active process instances that a player can create from this process.
requires

A set of conditions, which will determine if the player can see this definition in the game or not.

Click here to see the creation requirements structure.

Creation Requirements Structure

This allows certain checks to be performed to make sure a player can actually see/perform/join the task, action, team.

Field Description
type The type of condition. It can be one of metric, action, team, and, or.
not If true, inverts the condition. So any check which would usually evaluate to true will now evaluate to false.
expression An array of contexts joined with an AND or OR operator. This field is only applicable if the condition type is and or or, and replaces the context field.
context The actual comparison expression. The structure changes depending on the type of condition selected. The structure for each condition is defined below:
  • metric - Metric Based Condition
  • action - Action Based Condition
  • team - Team Based Condition
The and and or type of conditions do not have this field. Instead, they have the expressions field, which is an array of these contexts.

Metric Based Condition

Condition which depends on a player's score for a particular metric

Field Description
id ID of the metric.
type Type of the metric being used for comparison.
For set metrics, there is an additional item field which denotes the set item
item The set item whose value will be compared.
This field is only available if the metric type is set.
operator Can be one of the relational operators:
  • eq (equal to),
  • ne (not equal to),
  • gt (greater than),
  • ge (greater than or equal to),
  • lt (less than),
  • le (less than or equal to)
value The value of the metric that the player should have on his scores.

Example:

{ "requires": { "type": "metric", "not": false, "context": { "id": "exp", "type": "point", "operator": "eq", "value": "55" } } }

Action Based Condition

Condition which depends on how many times an action has been performed.

Field Description
id ID of the action.
operator Can be one of the relational operators: eq, ne, gt, ge, lt, le.
value The number of times the action should be executed by the player.

Example:

{ "requires": { "type": "action", "context": { "id": "login", "operator": "eq", "value": "15" } } }

Team Based Condition

Condition which depends on how many times an action has been performed.

Field Description
definition_id Definition ID of the team which the player should be a part of.
role The role the player should have within the team of this type. If you don't care about the role, then you can ignore this field.

Example:

{ "requires": { "type": "team", "not": false, "context": { "definition_id": "disciples", "role": "student" // optional if the player can have any role } } }

All Conditions: and

An and condition, which is shown as All of the following rules can be used to join two or more conditions such that the whole condition will be true only when all of the child conditions are true.

Example:

{ "requires": { "type": "and", "expression": [ // two or more conditions ] } }

Any Condition: or

An or condition, which is shown as Any of the following rules can be used to join two or more conditions such that the whole condition will be true even if only one of the child conditions become true.

Example:

{ "requires": { "type": "or", "expression": [ // two or more conditions ] } }

Lanes Structure

Field Description
name The name of the lane.
default If true, all players who join an instance of this process will automatically join this lane.

Activity Structure

Activities are the tasks or sub-processes within a process. They can have rewards attached to them.

Field Description
id A unique ID for the activity.
name Name of the activity.
type Whether the activity is a task or a sub-process.
lane The lane in which the activity belongs to.
loop

Number of times a player can perform this task.

If loop is not set, the player can perform the task once.
If loop is set to 10, the player can perform the task 11 times.
rewards The rewards which the player can earn upon completing this task.
requires The requirements for performing the task.
probability Chance that the player will get any of the rewards on completing the task.

Gateway Structure

Gateways are used to restrict access to certain tasks and sub-processes based on the process state. They cannot have rewards on them.

Field Description
id A unique ID for the gateway.
name Name of the gateway.
type The gateway can be either parallel or exclusive.
lane The lane in which the activity belongs to.

Sequence Flow Structure

Sequence flows are lightweight objects which connect other nodes (activities, gateways) to each other. Each sequence flow has a source node and a target node.

Field Description
src The node from which the sequence flow originates.
target The node to which the sequence flow ends.
retry If set to true, the player can retry a task if he fails. Default is false
lane The lane in which the activity belongs to.

Process Instance Structure

Containers

They represent processes or sub-processes. They must contain a field key which must be unique.

Field Description
key Represents a path to a process or a sub-process. If the key is the process instance ID then it represents the process instance container otherwise it represents sub-processes. The key is used to notification tasks in sub-processes without acutally specifying the full path to the task.
nodes These represent all available nodes within the process or sub-process. The node can be of 2 types:

Process Instance Task Structure

Field Description
id The ID of the task or sub-process. This represents the path to the process or sub-process.
state Can be one of three states:
  • READY means the player can perform the task
  • COMPLETED means the player has finished the task
  • ACTIVE means a task which has been performed but not completed (looped tasks), or a sub-process in which only some of the tasks have been completed.
loop The number of times the player has perfomed this task.
perfomers The players within this task who have performed this task at least once. Each performer has the following keys:
  • id: The ID of the performer.
  • scopes: The custom leaderboard scopes the performer had performed this task with.

Process Instance Gateway Structure

Field Description
id The ID of the gateway.
routes It represents all the tasks or sub-process connected to this gateway. It is an array in which each element contains:
  • id: The ID of the nodes to which the gateway is connected to. Its value is true if the player has performed the task connected to the gateway
  • enabled: If the gateway has been cleared and there are no more tasks left in its routes then this is false otherwise its true.
  • performers: An array of performers (players) within this task who have been thorough this gateway
The performers key is an array of performers, each performer being an object with only one key:
  • id: the ID of the performer.

Examples

Process

{ "name": "Learning", "id": "learning", "description": "The Process of learning", "lanes": [ { "name": "Main", "default": true } ], "activities": [ { "id": "study", "name": "study", "lane": "Main", "type": "task", "loop": "0", "rewards": [] }, { "id": "practice", "name": "practice", "lane": "Main", "type": "task", "loop": "0", "rewards": [] } ], "gateways": [], "sequence_flows": [ { "src": "study", "tgt": "practice", "retry": true } ], "settings": { "access": ["PUBLIC"], "max_global_instances": "Infinity", "max_active_global_instances": "Infinity", "max_player_instances": "Infinity", "max_active_player_instances": "Infinity", "requires": {} }, "conditions": [] }

Process with Subprocess

{ "name": "Learning", "id": "learning", "description": "The Process of learning", "lanes": [ { "name": "Main", "default": true } ], "activities": [ { "id": "study", "name": "study", "lane": "Main", "type": "sub_process", "loop": "0", "rewards": [], "activities": [ { "id": "get_books", "name": "get_books", "lane": "Main", "type": "task", "loop": "0", }, { "id": "read_books", "name": "read_books", "lane": "Main", "type": "task", "loop": "0", }, { "id": "make_notes", "name": "make_notes", "lane": "Main", "type": "task", "loop": "0", } ], "sequence_flows": [ { "src": "get_books", "tgt": "read_books", "retry": true }, { "src": "read_books", "tgt": "make_notes", "retry": true } ], "gateways": [] }, { "id": "practice", "name": "practice", "lane": "Main", "type": "task", "loop": "0", "rewards": [] } ], "gateways": [], "sequence_flows": [], "settings": { "access": ["PUBLIC"], "max_global_instances": "Infinity", "max_active_global_instances": "Infinity", "max_player_instances": "Infinity", "max_active_player_instances": "Infinity", "requires": {} }, "conditions": [] }