Actions
Actions are an easy way of capturing events on the playlyfe platform.
Actions are basic triggers that allow you to translate player events/actions into a measurable entities on playlyfe.
An action has 3 parts:
- Rewards - Rewards are a set of scores and conditions where the scores are given to a player if he satisfies the given conditions.
- Variables - Variables that can be passed in during runtime and can be used in conditions for rewards or in rewards themselves.
- Visibility Requirements - By default, all actions are visible to all players. By using visibility requirements, you can restrict access to actions to only those players who satisfy a given criteria.
Use Cases
Any task done by a person can be easily recorded in playlyfe by using Actions. For example, an action could be going to the gym, reading a book, liking a facebook post or answering a quiz.
An action can be used pretty much anywhere. In case of an online education platform, action could be watching a tutorial video, which would fetch a player some experience points that can be used to show the person their progress within the course. Similarly, answering questions or posting on forums can also be actions that contribute to their progress or rating.
Rewards
Rewards are a set of metrics (points, badges, etc.) that a player gets when an action is performed. These rewards are metrics and can be either added, removed or set on a player.
Note: Adding negative values will reduce the player's score, similarly removing negative value increases the player's score.
Each reward can have its own conditions which are to be satisfied for the reward to be executed. More advanced scoring conditions such as probability and rate limits can also be set.
The various kinds of conditions available to you are:
Scoring Probability
A scoring probability (a.k.a chance) can be used to bring in an element of randomness or chance into the system. Scoring probability in actions can be set at 2 levels:
- Overall action level
- Per-reward level
A scoring probability at the action level would affect all the rewards of the action. It would be useful when you want to give all rewards together. The reward level probability would affect only a particular reward, hence you can control probabilities of each reward individually. Both probabilities can also be used simultaneously.
Rate Limiting
The default rate limit of an action is Infinity (i.e no rate limits), but if you want to rate limit an action you can specify the frequency limit. For example, an action can be set to execute at a maximum of 10 times per day.
There are 3 different types of rate limits that can be applied, they are:
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.
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.
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.
Formula and Variables
Variables in actions can be defined to tweak the behavior of actions at runtime. Variables can be of 2 types - Strings and Integers. They can be used in both conditions and in rewards by creating a formula.
Here are some details on how variables and scores can be used in a formula:
Action Count
Actions can also be triggered with a count. This count basically acts as a multiplier for the action's rewards.
For example, in a gym app, running 1km is an action with reward of calories burnt 300, if you perform the same action with a count of 3, rewards would now be 900. This way you dont have to make 3 calls for an action or make a new action for a 3km run. The action count can only be an integer.
You can view our API documentation on actions to see how to actually use the action count.
Caution: In case when an action has an action count condition and depends on its own action count, the rewards are taken as per the initial action count before execution.
Visibility Requirements
Visibility requirements allow your action to be visible only to a certain type of players. The conditions can be specified in a similar fashion as the conditions in rewards, however some conditions are not available.
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 Playlyfe 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 the keys id and entity_id. The id is the actual scope
ID and the entity_id is the ID of the player on whom the score will be
applied.
Related API
Design Structure
Base Structure
| Field | Description |
|---|---|
| id | A unique ID for the action. |
| name | A name for the action. |
| description | Brief description of the action. |
| image | An image which represents the action. You need to send a multipart form POST request to upload the image data. |
| probability | The probability that the player gets the rewards on completing the action. |
| rate |
Rate Limiting an action so that users do not abuse the system. This is an array of three items, which are:
|
Rules
The rules that would be evaluated to give rewards to the player. This is an array consisting of objects with the fields rewards and requires.
| Field | Description |
|---|---|
| rewards | The set of metrics that a player gets when he finishes this action. This is a an array consisting of one or more Rewards. |
| requires | These are the conditions which are checked to see if the player is suitable to get this reward. For more information on requires, see the Requires Structure below. |
Reward Structure
| Field | Description |
|---|---|
| metric |
The metric which will be used for the reward. This is an object with two fields:
|
| verb | Defines which operation is performed for this reward. Can be one of add, remove, set. |
| value | The value by which the player's score changes. |
| probabilty | The chance that this reward in an action or process task can be given must be within [0, 1] range. |
Requires 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 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:
|
| value | The value of the metric that the player should have on his scores. |
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. |
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. |
Timed Condition
You can also define conditions which become true only when triggered on a particular time.
| Field | Description |
|---|---|
| func |
The time unit to be counted, against a fixed duration. The available choices are:
|
| operator | Can be one of the relational operators: eq, ne, gt, ge, lt, le. |
| value | The count of the unit to be counted chosen in the func field. For example, for day of week, the value will represent day, and sensible values will be an integer between 1 to 7, both included. |
Formula Based Condition
You can also setup equations with two sides, a left-hand expression (LHS), a right-hand expression (RHS) and an operator. Whenever the equation is satisfied, the condition becomes truthy.
| Field | Description |
|---|---|
| lhs |
An arithmetic expression, which can use other metrics or variables defined within the custom rules
as components.
An example:
$scores.health + $vars.run_length
|
| operator | Can be one of the relational operators: eq, ne, gt, ge, lt, le. |
| rhs | Another arithmetic expression, same as the lhs. |
Variables
Variables allow users to input dynamic contents for evaluating rules when an action is performed. Each variable has the following properties:
| Field | Description |
|---|---|
| name | The name of the variable. |
| type | This is the type of the variable it can be a number or a string. |
| required | Whether the variable is required when the player performs this action. |
| default | The default value of the variable, which is applied only if the required property is not set. |
Requires
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 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:
|
| value | The value of the metric that the player should have on his scores. |
Example:
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:
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:
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:
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: