structs-streaming_skill

Overview

This skill connects to the GRASS real-time event system via a NATS WebSocket so agents can react the moment game events occur. It helps you subscribe to subjects like planets, structs, fleets, inventory, and grid updates instead of relying on polling. Use it to build alerting, monitoring, and event-driven tools that track raids, fleet movements, player creation, and combat in real time.

How this skill works

The skill discovers the GRASS WebSocket endpoint from guild configuration (or uses a recommended fallback) and opens a NATS WebSocket connection. It supports wildcard discovery (subscribe to ">") to reveal active subjects, then narrows subscriptions to targeted subjects such as structs.planet.{id} or structs.inventory.{denom}.{guild}.{player}.{address}. Incoming messages are JSON payloads; the skill parses them and emits structured events like raid_status, struct_attack, fleet_arrive, grid attribute changes, and inventory movements.

When to use it

• You need immediate reaction to events (raid detection, fleet arrival) instead of polling.
• You want continuous monitoring or an event-driven game loop tied to block or consensus ticks.
• You need to watch player creation or address registration after guild signup.
• You are tracking combat, struct health, or defender interactions in real time.
• You manage multiple players or planets and prefer a single connection to monitor them all.

Best practices

• Discover subjects first with the ">" wildcard, then restrict to specific subjects to reduce noise.
• Filter out constant noise like consensus and healthcheck during discovery.
• Limit subscriptions (aim for 10–20 per connection) and implement reconnection with exponential backoff.
• Parse JSON defensively; event schemas can vary and not every message matches expectations.
• Close idle connections and log events to persistent storage for cross-session awareness.

Example use cases

• Raid alert service that listens to structs.planet.{planet_id} and triggers defensive automation on raid_status.
• Fleet tracker that watches structs.fleet.* and updates threat assessment on fleet_arrive or fleet_depart.
• Combat monitor that parses struct_attack and struct_health events to display shot-by-shot resolution and HP tracking.
• Player creation watcher that subscribes to structs.address.register.* to detect new address registration instead of polling.
• Economy tracker that subscribes to structs.inventory.{denom}.> to monitor mining, refining, minting, and seized transfers.