Character roster

Usage guide of character.roster: game-defined characters and roles, team selection and locking, ability slots and bounded resources on top of combat.abilities; settings, the roster_characters collection, services, events and roster.* hooks.

Source: module-kits:kits/character_roster/usage/en.mdView Markdown source

Also read offline — CLI: grip-forge docs character-rosterMCP tool: gripforge_docs { "topic": "character-roster" }

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.

Turn it on #

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:

{ "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 #

Register the members of a team, select, lock, close, then use a slot (calls of the character.roster service):

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.