GRASS Event Schemas

Version: 1.2.0 Category: streaming

Complete catalog of GRASS event payload schemas for AI agents.

Base Event

All GRASS events share a common base structure.

Grid and planet events carry the owner player_id (added 2026-07-07). Their subjects append it — structs.grid.{object_type}.{object_id}.{player_id} and structs.planet.{planet_id}.{player_id} — and their payloads include a top-level player_id string field (the literal noPlayer when the owner can’t be resolved). This holds for full and stubbed planet payloads. Subscribe with a trailing */> (see subscription-patterns.md).

detail has two representations depending on transport. Over NATS/GRASS the frame is parsed once (message.json()), so detail arrives as an already-parsed object — access detail.* directly. Over the Guild API planet-activity REST feed the same detail comes from a PostgreSQL column as a JSON-encoded string — you must JSON.parse(row.detail) first. Code that consumes both transports must branch on the source. See api/integration-notes.md — Event detail has two representations.

Event Definitions

PlayerConsensusEvent

Extends BaseEvent. Category: player_consensus

Data Fields:

Fires when sync-state commits an insert or update to structs.player, including UGC changes from MsgPlayerUpdateName / MsgPlayerUpdatePfp or signup proxy.

GuildConsensusEvent

Extends BaseEvent. Category: guild_consensus

Data Fields: Guild consensus data object.

GuildMetaEvent

Extends BaseEvent. Category: guild_meta

Data Fields:

Chain UGC name and pfp live on structs.guild and surface via guild_consensus / chain events — not through guild_meta.

UGCModeratedEvent (Cosmos chain event)

Not delivered through GRASS. This is a typed Cosmos sdk.Event of type ugc_moderated emitted by the chain keeper. Subscribe via Tendermint event subscriptions (tx.events/block_events).

Fires only when the actor of a UGC update is not the target object’s owner (i.e. moderation overrides only — self-service updates are silent).

Attributes:

See knowledge/mechanics/ugc-moderation.md for the full philosophy and validation rules.

GuildMembershipEvent

Extends BaseEvent. Category: guild_membership

Data Fields: Guild membership change data object.

EventGuildRankPermission

Extends BaseEvent. Category: guild_rank_permission

Fires when guild rank permissions are set or revoked on an object.

Data Fields:

{
  "guildRankPermissionRecord": {
    "objectId": "6-1",
    "guildId": "0-1",
    "permissions": 4,
    "rank": 3
  }
}

PlanetRaidStatusEvent

Extends BaseEvent. Category: raid_status

Data Fields:

PlanetActivityEvent

Extends BaseEvent. Category: planet_activity

Data Fields:

FleetArriveEvent

Extends BaseEvent. Category: fleet_arrive

Data Fields: Fleet arrival data object.

StructAttackEvent

Extends BaseEvent. Category: struct_attack

The detail payload has the attacker context flat at the top and the per-projectile outcomes nested in eventAttackShotDetail[] (one entry per shot). Field keys are camelCase (unlike most other struct events).

Top-level (attacker) fields:

eventAttackShotDetail[] (per-projectile) fields:

attackerHealthBefore, targetHealthBefore, and targetHealthAfter are runtime-enriched fields present on the live activity feed (used for animation) and are not part of the canonical protobuf type; they may arrive as strings. See api/integration-notes.md — struct_attack event detail schema and combat.md.

Stubbing on the live stream. The NATS NOTIFY payload is capped at ~8000 bytes. When a struct_attack row’s full detail exceeds 7995 bytes (typical of multi-shot, multi-defender fights), the realtime stream sends a stub — { "category": "struct_attack", "stub": true, "planet_id": ..., "seq": ..., "time": ... } with no detail. The full eventAttackShotDetail[] is then only available by pulling the Guild API planet-activity row (keyed by seq/planet_id). Detect combat from the effect events that always stream in full (struct_health, struct_status, shield_change, raid_status); use the pull for per-shot detail. Small attacks ship detail inline.

StructStatusEvent

Extends BaseEvent. Category: struct_status

Data Fields: Struct status change data object.

BlockEvent

Extends BaseEvent. Category: block

Data Fields:

Event Categories

All planet/struct categories below are planet_activity rows delivered on structs.planet.{planet_id}.{player_id} (subscribe structs.planet.{planet_id}.*).

Not emitted by the current indexer (present in the enum/older docs only): fleet_advance and player_meta. Do not subscribe expecting them.

Related Documentation

• Event Types
• Streaming Protocol