Skip to main content

Teams

The SDK exposes player teams via client.teams. A team is an app-scoped group with members, roles, and per-role permissions you use to delegate management (and, via grids, to give a team ownership of a region of the world). Unlike channels, teams have no realtime messaging path — it's pure GraphQL CRUD. See the Game API Teams guide for the full permission model.

Manage teams​

Teams are a Game API surface, so they need an app-scoped token: log in on an identity client, mint a token for the app, and drive teams from a per-game client (see Portals & app-scoped tokens).

import {
  BrowserLocalStorageTokenStore,
  createCrowdyClient,
} from '@crowdedkingdoms/crowdyjs';

const identity = createCrowdyClient({
  managementUrl: 'https://dev-management-api.crowdedkingdoms.com',
  tokenStore: new BrowserLocalStorageTokenStore('crowdyjs:session'),
});
await identity.auth.devLogin('player@example.com'); // passwordless sign-in (dev/test); see /crowdyjs/readme#sign-in-with-clientauth-passwordless

const appToken = await identity.portal.mintAppToken('1');
const game = createCrowdyClient({
  managementUrl: 'https://dev-management-api.crowdedkingdoms.com',
  httpUrl: appToken.gameApiUrl ?? 'https://dev-game-api.crowdedkingdoms.com',
  wsUrl: appToken.gameApiWsUrl ?? 'wss://dev-game-api.crowdedkingdoms.com',
  tokenStore: new BrowserLocalStorageTokenStore('crowdyjs:app:1'),
});
game.setToken(appToken.token);

// Create a team (the creator becomes owner with the system `leader` role).
const team = await game.teams.create({
  appId: '1',
  name: 'Red Dragons',
  membershipPolicy: 'request',
});

await game.teams.join(team.groupId);
const mine = await game.teams.mine('1');        // teams I belong to
const members = await game.teams.members(team.groupId);

Delegate with roles​

// An "officer" role that can manage members but not delete the team.
const role = await game.teams.createRole({
  groupId: team.groupId,
  roleName: 'officer',
  permissions: ['manage_members', 'invite_members'],
});

await game.teams.setMemberRoles({
  groupId: team.groupId,
  userId: '42',
  roleIds: [role.groupRoleId],
});

The full method set mirrors the GraphQL surface:

  • Read: mine(appId), list(appId), get(groupId), members(groupId), roles(groupId), policy(appId).
  • Team lifecycle: create, update, remove, setPolicy.
  • Membership: join, requestToJoin, leave, addMember, removeMember, setMemberRoles.
  • Roles: createRole, updateRole, deleteRole.

Setting the per-app team policy (setPolicy) requires the manage_apps permission; membership and role management are gated by the team's own role permissions. To give a team build rights in the world, assign it to a grid — see Grids and permissions.