Teams

Overview #

Teams bring the full depth of Hiro’s player-level systems to the group-level, such as team inventories for resource pooling, achievements for collective goals, and leaderboards that pit teams against each other in large-scale tournaments.

By allowing players to band together and work towards a common goal (all while making friends along the way!), Teams solve the challenge of long-term player retention through social investment. When players contribute to team progression or help their guild advance through tiers, they build lasting value that extends beyond individual sessions. This transforms Teams from temporary social convenience into meaningful long-term relationships.

Synonyms: guilds, clans, groups

Features #

Team Lifecycle & Discovery #

• Team creation workflow with customizable metadata and icons
• Team search capabilities with filtering by name, language, and stats
• Team listing and recommendation system designed to help players find suitable teams based on status, available slots, and other criteria

Team Permissions #

• Role-based access control with super admin, admin, and member permissions governing access to team resources and activities
• Dynamic team sizing with ability to modify maximum team capacity
• Activity tracking to distinguish between active and idle players

Team Chat #

• Team chat system with support for announcements that admins can pin for all members
• Announcement read receipts ensuring important messages are displayed prominently until acknowledged
• Integration with Nakama’s real-time messaging for seamless team communication

Roles & Permissions #

Teams are built on top of Nakama’s Groups system, which provides the membership hierarchy of super admin, admin, and members. Within the Teams system, these roles determine access to team-specific resources and operations.

Resource Management #

• Admins have full control over team resources including the team wallet (granting currencies), inventory (managing items), achievements (claiming rewards), and store purchases
• Members have read-only access to team resources and can contribute to team progression through gameplay but cannot manage or distribute resources

Team Progression #

• Admins can claim achievement rewards, update team stats, sign up to event leaderboards, and manage mailbox rewards on behalf of the team
• Members can contribute to team achievements through their gameplay and participate in event leaderboards by submitting scores
• All active members can view team progression data including achievements, leaderboards, and statistics

Communication #

• Admins can send pinned chat announcements that appear prominently to all team members
• Members can send regular chat messages and participate in team discussions
• All active members receive and can view pinned announcements

Expanded Team Systems #

In addition to the core Teams functionality, several powerful sub-systems are available to elevate your team-based gameplay to the next level.

Team Achievements #

• Full achievement system with support for sub-achievements, preconditions, and auto-claiming
• Configurable reset schedules, duration limits, and complex progression tracking
• Integration with reward systems for achievement completion bonuses

Learn more about Team Achievements

Team Event Leaderboards #

• Sophisticated competitive system with cohort-based matchmaking and tier progression
• Support for scheduled events, promotion/demotion mechanics, and tier-based rewards
• Includes contribution tracking per team member and comprehensive reward distribution

Learn more about Team Achievements

Team Inventory #

• Comprehensive item management with support for stackable/non-stackable items, item categories, and usage limits
• Configurable access controls for item management and consumption based on team roles
• Integration with reward systems for item grants and consumption rewards

Learn more about Team Inventory

Team Mailbox #

• Reward distribution system allowing rewards to be sent to teams and claimed by authorized members
• Support for expiring entries, pagination, and automatic cleanup
• Serves as both team rewards inbox and member reward inbox functionality

Learn more about Team Mailbox

Team Stats #

• Supports both public and private team statistics with configurable operations (increment, decrement, set, best)
• Integrates with group metadata for public stats and separate storage for private stats
• Enables custom server-side actions triggered by stat changes

Learn more about Team Stats

Team Store #

• Purchase system allowing teams to buy items using team wallet currencies
• Support for reward modifiers and complex reward structures
• Integration with inventory and wallet systems for seamless transactions

Learn more about Team Store

Team Wallet #

• Multi-currency wallet system with configurable initial values and currency types
• Support for granting/deducting currencies with validation to prevent negative balances
• Integrated with other systems for reward distribution and purchase transactions

Learn more about Team Wallet

Configuring Teams #

Teams Config

Example: Teams JSON #

The JSON schema defines a Teams configuration object which contains the core team settings and subsystem configurations. You can configure as few or as many features as needed for your game.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

{
  "initial_max_team_size": 25,
  "max_team_size": 30,
  "wallet": {
    "currencies": {
      "team_coins": 1000,
      "premium_tokens": 0
    }
  },
  "stats": {
    "stats_public": {
      "team_level": {
        "value": 1,
        "additional_properties": {
          "display_name": "Team Level",
          "icon": "level_star"
        }
      }
    },
    "stats_private": {
      "internal_rating": {
        "value": 0,
        "additional_properties": {
          "calculation_method": "elo"
        }
      }
    }
  },
  "inventory": {
    "items": {
      "team_banner": {
        "name": "Team Banner",
        "description": "Customizable team banner",
        "category": "decoration",
        "item_sets": ["cosmetic", "team_items"],
        "max_count": 1,
        "stackable": false,
        "consumable": false,
        "string_properties": {
          "color": "blue"
        },
        "numeric_properties": {
          "prestige_value": 100
        }
      }
    },
    "limits": {
      "categories": {
        "decoration": 5
      },
      "item_sets": {
        "cosmetic": 10
      }
    }
  },
  "achievements": {
    "team_veteran": {
      "name": "Team Veteran",
      "description": "Complete 100 team activities",
      "count": 100,
      "auto_claim": false,
      "category": "progression",
      "reward": {
        "guaranteed": {
          "currencies": { "team_coins": { "min": 1000 } }
        }
      }
    }
  },
  "store_items": {
    "team_upgrade": {
      "name": "Team Capacity Upgrade",
      "description": "Increase team member limit",
      "category": "upgrades",
      "cost": {
        "currencies": {
          "team_coins": 5000,
          "premium_tokens": 10
        }
      },
      "reward": {
        "guaranteed": {
          "currencies": { "capacity_tokens": { "min": 1 } }
        }
      }
    }
  },
  "mailbox": {
    "max_size": 100,
    "expiry_sec": 604800
  }
}

What Ifs #

This section describes edge cases and scenarios that may be unintuitive to the developer.

A player has a pending join request and tries to join another team

The original join request is not automatically canceled when a player attempts to join a different team. Players can have multiple pending requests simultaneously. You can implement custom logic in server hooks to automatically cancel previous requests when new ones are submitted, or require players to explicitly cancel their existing requests using the Leave operation.

Tracking read status of chat messages

There is no built-in mechanism for tracking read status of regular chat messages. The recommended approach is to implement message tracking locally in the client by maintaining the last seen message timestamp or ID. For critical announcements, use the pinned message system which provides read receipt functionality.

Team size limits are changed after teams are created

When you modify max_team_size in your configuration, existing teams retain their current member count even if it exceeds the new limit. Teams that are over the new limit cannot accept new members until they fall below the threshold. You can use the Teams API to adjust individual team capacities as needed.

Teams are deleted with active members and resources

When a team is deleted, all associated data including the team wallet, inventory, achievements, and mailbox entries are permanently removed. Active members lose access to all team resources immediately.