Groups and raids (social.party) #

What it is for #

social.party keeps the membership of player groups for a game: who leads, who is a tank, a healer or a damage dealer, who is online, which subgroup of a raid each member sits in, and which invitations are still open. One coordinator owns the membership of every group in its world, so an actor can never be in two parties at once. The kit holds rules and state only: it draws nothing, and it has no clock of its own (the game drives time with step).

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "social.party" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "social.party",
                              config: { "maxParties": 64, "inviteFrames": 3600 } }

It requires game.engine and provides the exclusive service social.party. A coordinator called default exists as soon as the kit starts, built from the configuration above.

First example #

<!-- test: kits/social_party/tests/social_party.rs::a_party_is_made_joined_and_projected_for_the_hud -->

social.party.request("default", { "op": "create", "party": "p", "actor": "ann", "role": "tank" })
social.party.request("default", { "op": "invite", "party": "p", "actor": "ann", "target": "bob" })
social.party.request("default", { "op": "accept", "party": "p", "actor": "bob", "role": "damage" })
social.party.groupFor("bob")   // { "party": "p", "members": { "ann": {...}, "bob": {...} } }
social.party.groupFor("zed")   // null: not grouped

Creating a second party for someone already grouped is refused.

Settings #

Unknown keys and out-of-range values are reported when the configuration is validated.

Services #

• social.party (service), methods:
  • create(id, config): makes another coordinator named id (at most 128). config may name a preset of the social_party_presets collection; the other keys of config override it.
  • request(id, command): runs a command on that coordinator and returns { state, events }. An unknown coordinator is an error.
  • step(id?): advances one fixed frame (default default) and returns null; invitations that reach their end vanish.
  • groupFor(actor): { party, members } of that actor in the default coordinator, or null.
  • ids(): the coordinator names. remove(id): deletes one and returns whether it existed.

Commands of request #

Every command is an object with an op; unknown fields are refused. Group commands carry party and the acting actor.

Read-only commands: status (the whole state), config, save, preview (runs a command on a copy and discards it), load.

Events #

Each decision that is not a read emits an event; the engine ticks alone expire nothing.

social.party.created   { instance, preset }
social.party.removed   { instance }
social.party.changed   { instance, op, result }
social.party.refused   { instance, op, by, reason }

Hooks and modding #

Two hooks let a game or a mod decide before the kit does:

• social.party.create: asked before a coordinator is made; the payload has instance, preset and config and the config can be changed. A cancelling tap makes create fail with "creation refused".
• social.party.request: asked before every command that changes something; the payload has instance, op and command, and the command can be rewritten. A cancelling tap returns { ok: false, cancelled: true, by, reason } and emits the refused event.

Content can send a command with the verb social_party_request and test that a coordinator exists with the condition social_party_exists:

{ "social_party_request": { "instance": "default", "command": { "op": "leave", "party": "p", "actor": "bob" } } }

Engines #

The rules are the same Rust module on the web, in the native player and in the engine wrappers; there is nothing to draw.

When it does not do what you expect #

• An invitation never expires: nothing ticks it by itself. Call step once per fixed frame from the host that owns the group.
• accept fails with "invitation absent or expired": more than inviteFrames steps passed, or the actor was never invited.
• invite fails with "leader required": only the leader invites, kicks, promotes or configures.
• create fails with "party limit": raise maxParties (at most 256).
• groupFor only looks at the default coordinator; use request with status for others.
• A load that does not match the kit configuration is refused and live state is kept.

Limits #

• Roles are tank, healer and damage; a party holds 5 members, a raid 40 in 8 subgroups of 5.
• No chat, matchmaking or loot rolling: loot only records the chosen mode for the game to apply.
• Reconcile actors with your server when you remove a coordinator.

Versions #

Kit version 1.0.0; it relies on game.engine 1.x. The party is part of the game save.