Gameplay Action Authority And Command Audit

Gameplay actions are client-requested commands that must be accepted, rejected, or replayed by server authority. The game server resolves each action through the owning authority family, applies authoritative effects, records idempotency state, and writes a command audit row for incident review.

Action Contract

crates/common-proto/src/gameplay_actions.rs defines the shared action kinds, request payloads, resolver metadata, audit labels, mutation fields, and mutation prefixes. Metadata is compatibility-significant: clients, authority resolution, replay, and audit all depend on the same action-to-resolver contract.

The action families are:

Combat;
NpcService;
Quest;
Dialogue;
Farming;
Player.

Each request carries a request ID and an action payload. The request ID is part of the idempotency key and should be stable across client retries of the same logical command.

Acceptance, Rejection, And Replay

The realtime service first prepares the request for resolution:

If the session is in pending transfer, the action is rejected before mutation.
If the request ID and mutation identity match a retained result, the service returns the retained result as a replay.
If the request ID conflicts with a different mutation identity, the service rejects the command as a conflicting duplicate.
If no retained result exists, the request proceeds to authority resolution.

The outer realtime dispatcher handles player-owned session commands, such as equipment loadout and appearance customization, through session-specific authority. Non-combat gameplay actions are resolved through the gameplay authority service. Combat actions leave the generic resolver and are handled by combat authority so encounter state, reward hooks, correction packets, and defeat persistence stay under the combat owner.

Every outcome is classified as accepted, rejected, or replayed before response packets and audit records are emitted.

Idempotency And Mutation IDs

The idempotency envelope is built from:

source, currently realtime gameplay;
persistence scope, currently character-scoped for these commands;
request ID;
parsed mutation IDs;
replay metadata;
optional session token context.

Mutation IDs are derived from action metadata and action payload fields. Some resolvers add extra authoritative IDs, such as combat reward hooks, dialogue inventory or faction mutations, farming tile mutations, and economy mutation IDs.

The replay ledger keeps a bounded set of processed gameplay action results. Retained accepted or rejected results let retries return the same wire response instead of applying the command twice.

Resolver Families

Gameplay authority routes actions through resolver families:

NPC service actions resolve vendor, crafting, or direct service entries and their costs/effects.
Quest actions resolve accept and turn-in behavior.
Dialogue actions resolve writes and authoritative choice intents.
Farming actions resolve tile-scoped farming changes and deltas.
Combat actions are rejected by the generic gameplay resolver when they belong to realtime combat authority.
Player actions are rejected by the generic gameplay resolver when they belong to realtime session authority.

This split keeps command ownership explicit. Adding a new action should update protocol metadata and route it to exactly one authority owner.

Authoritative Effects

GameplayActionOutcome carries the accepted flag, user-facing message, and any authoritative state changes. Effects can include:

quest state;
inventory snapshots;
currency snapshots;
player stat snapshots;
gameplay-state revisions and persistence status;
NPC service overlays;
farming tile deltas;
economy mutation IDs.

Non-combat effects update session gameplay state, retain the idempotent result, and send response packets plus any updated snapshots. Combat effects are applied by combat authority and can include scene combat state, reward events, movement correction, encounter memory, and reward persistence.

If an action creates gameplay-state persistence work, the resolution records a pending persistence effect such as authoritative_gameplay_state. When persistence is queued for disconnect-safe recovery, the service records that outcome in audit rather than treating the response as unaudited success.

Command Audit Rows

Accepted, rejected, and replayed gameplay commands are recorded through the command audit store. The gameplay audit record includes:

command type, currently gameplay_action;
request ID and action kind;
accepted and replayed flags;
session, account, character, and realm identity;
source zone and tile;
target zone and tile when applicable;
normalized mutation IDs;
authoritative audit event JSON;
replay payload JSON when replayed;
persistence outcome;
message;
creation timestamp.

The database table is command_audit_log. It is indexed for character history, action-kind review, and command type plus request ID lookup.

GameplayCommandAuditPersistenceOutcome records the normalized persistence label:

not_required: the accepted command did not need a gameplay-state persistence write.
state_saved: authoritative gameplay state was saved immediately.
state_queued: gameplay-state persistence failed synchronously and was queued into durable retry; the session is disconnected for repair-safe recovery.
outbox_queued: combat authority accepted the command and queued follow-up persistence work, such as combat reward or defeat persistence.
replayed: the command returned a retained idempotent result.
rejected: authority rejected the command before durable mutation.

These labels let incident review separate a rejected command from an accepted command whose state save or combat reward write was deferred.

Incident Review

For a disputed gameplay command:

Look up the row by command_type = 'gameplay_action' and request ID.
Check accepted and replayed before inspecting effects.
Compare normalized mutation_ids with the command payload and resolver metadata.
Inspect audit_event for authoritative resolver details.
Inspect replay_payload when replayed is true.
Check persistence_outcome to see whether state was saved immediately, queued, replayed, or rejected.
Use command-audit replay tooling when the incident requires drift analysis against stored wire, state, quest, or audit snapshots.

Replay diagnostics report drift categories for audit events, wire snapshots, gameplay state, and quest snapshots. Mob encounter replay also reports event, wire snapshot, state, and quest drift for combat flows. Use those drift reports to identify whether the authority result changed, serialization changed, or the stored state projection changed.

Tuning And Ownership

Gameplay action authority does not expose production tuning through game-server environment variables. Important constants and contracts live in source:

processed gameplay action result retention;
authoritative event journal retention;
replay schema versions;
canonical economy IDs;
action metadata and resolver family descriptors.

Treat changes to action metadata, mutation IDs, and audit schema as compatibility-sensitive. They affect replay, duplicate detection, incident review, and the ability to prove which authoritative mutations came from one client command.