# Character roster and selection (character.roster)

## What it is for

Characters defined by your game (hero shooters, MOBAs, squads): each has a role, ability slots bound to the abilities of
`combat.abilities`, and bounded resources. Members pick a character, lock it, and once every member is locked the selection
closes and the slots become usable. It does not match players or run a server. For the other character kits, see the
[character guide](guide:character).

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "character.roster" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "character.roster",
                              config: { "unique": "team", "maxMembers": 10, "title": "Pick your hero" } }
```

It requires `game.engine` and `combat.abilities`. A character is a document of the `roster_characters` collection:

```json
{ "id": "scout", "name": "Scout", "role": "duelist",
  "slots": [ { "id": "q", "ability": "slash", "label": "Slash", "action": "roster_q" } ],
  "resources": [ { "id": "mana", "initial": 60, "max": 100 } ] }
```

Up to 12 slots and 16 resources per character; `ability` names an ability of the installed pack.

## First example

<!-- test: kits/game_engine/host/tests/parity.rs::rust_host_matches_the_typescript_traces (fixture character.roster.selection) -->
Register the members of a team, select, lock, close, then use a slot (calls of the `character.roster` service):

```text
register("e2", "blue")      select("e1", "scout")     lock("e1")
select("e2", "medic")       lock("e2")                close()
use("e1", "q")              -> casts the ability bound to slot q
```

Every call answers `{ ok: true }` or `{ ok: false, reason }`: an unknown or unfinished character, a character already taken, a
member that is not registered or not locked, a selection that is not open.

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `unique` | `team` | a character can be taken once per `team`, once per `match`, or any number of times (`none`) |
| `autoPlayer` | `true` | the player entity joins the roster by itself |
| `maxMembers` | 32 | members the roster accepts (1 to 256) |
| `title` | `Choose a character` | title of the selection screen |

## Services, events, variables

- `character.roster` (service): `view()`, `register(entity, team)`, `remove`, `select(entity, character)`, `lock(entity)`, `open`,
  `close()`, `use(entity, slot)`, `abilities(entity)`, `grant(entity, resource, amount)`.
- Events: `roster.changed` (read `view()` again), `roster.locked` (`entity`, `character`), `roster.closed`; it listens to `entity.despawned`.

## Hooks and modding

| Hook | Mutable | Asked |
|---|---|---|
| `roster.select` | `character` | a member picks a character (the replacement is checked again) |
| `roster.lock` | - | a member is about to lock |
| `roster.close` | - | every member is locked and selection is about to close |
| `roster.use` | `ability` | a locked member uses a slot; then `combat.abilities` runs its own hooks |
| `roster.grant` | `amount` | a resource amount is granted (still clamped to the maximum) |

All are cancellable: the call then answers `ok: false` with the reason of the tap. Moddable: the settings above and the
`roster_characters` collection.

## Limits

The host owns the selection phases: no matchmaking, no server authority. Slots are only usable after selection closes. The
selection screen and the ability bar are shared web views; other engines show them through `ui.webui`.

## Versions

Kit 1.1.0 and service `character.roster` 1.1.0 (hooks and moddable collection); first release 1.0.0.