< Back to Manuals

Teams

Teams let you organize your players into meaningful groups. These groups are what are called roles within the team. which can then be assigned separate roles to perform different tasks in a game.

In games there are several types of players. Some players have certain access and privileges which others do not.

In business scenarios, this is often a reflection of how we structure the organization itself.

In the case of a web community it could be reflection of how we organize the community into moderators and admins.

Whatever the case maybe, Playoff allows you to model the power relations between your players using teams. Within each team you can create a hierarchy of roles, assign permissions and control who can create an start a team, who can join and who can leave.

Use Cases

With teams we can very easily recreate an organizational or community like hierarchy. This makes modeling of the game a much more simpler process.

Take an example of a classroom, here we have just 2 roles - teacher and students. If we have actions for taking a class, attending a class, writing a test and so on, we can model and restrict these actions based on the role of players in the team.

This is a fairly trivial use case, but can be very easily extended to more complex and relevant real life use cases.

Design Structure

Base Structure

Name Description
id A unique ID for the team.
name A name for the team.
description Brief description of the team.
image An Image which represents the team. You need to do a multi-part form post to send the image data.
settings

Settings for the whole team.

See the Settings section for details.

permissions

An structure which defines the roles present in each team, and the permissions associated with each role.

This is an array of permission rows. Each permission row is an array, with two elements:

  1. role: The name of the role.
  2. permissions: A map of all permissions, each having a boolean value.

The list of permissions are as follows:

  • lock: player can lock the team, so no member can join or leave the team
  • peer: player can invite others to the same role
  • assign: player can invite others to lower roles
  • leave: player can leave the team.

*Note: the player here means anyone having a role with that permission.

creator_roles

An array of roles which will be assigned to the player who creates an instance of this.

Note: Only the roles defined in the permissions key can be used.

Settings Structure

Name Description
access The access settings with which the team 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 team, they get the chance to choosing only one of the access settings you set in the array.
max_global_instances The maximum number of instances of this type that can be created.
max_player_instances The maximum number of instances of this type that a player can create.
max_players The maximum number of players that any instances of this type can contain.
public

If false, the team definition will only be available to the game admins. Only the game admin can create an instance of the definition.

If true, the availability of the definition will be controlled by the requires key. If the requires key is not set, then it will be available to everyone within the game.

requires

The requirements for creation of an instance from this definition. Only the players who satisfy the requirements can create this type of team.

Click here to see the creation requirement 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 ] } }

Examples

Team

{ "name": "Managers", "id": "managers", "description": "This is the team for all managers", "permissions": [ ["Starter", {"lock": true, "assign": true}], ["Admin", {"lock": true, "assign": true, "peer": true, "leave": true }] ], "creator_roles": ["Admin"], "settings": { "access": ["PUBLIC"], "max_global_instances": "Infinity", "max_player_instances": "Infinity", "max_players": "Infinity", "public": true, "requires": {} } }

Team with Creation Requirements

{ "name": "Moderators", "id": "moderators", "description": "This is the team for all managers", "permissions": [ ["Forum Moderator", {"lock": true, assign: true}], ["Chat Moderator", {"lock": true, "assign": true}], ["Admin", {"lock": true, "assign": true, "peer": true, "leave": true }] ], "creator_roles": ["Admin"], "settings": { "access": ["PUBLIC"], "max_global_instances": "Infinity", "max_player_instances": "Infinity", "max_players": "Infinity", "public": true, "requires": { "type": "metric", "not": false, "context": { "id": "levels", "type": "state", "operator": "eq", "value": "Level 3" } } } }