subscribe_observation
Subscribe to live presence updates for the players at your POI, plus ship_counts for the other POIs with a ship scanner (Change-feed alternative to polling get_nearby. Anchors a watch at your current POI: the response is a full baseline snapshot (the uncloaked players at your POI exactly as get_nearby lists them, with offline_collapsed; the pirates/empire_npcs/creatures, intact prizes and arena_npcs at your POI that get_nearby returns; the unknown_signature hint; and, with a working ship scanner, ship_counts: the get_system ship_count of every charted POI in your system), and thereafter you receive observation_update messages only when that presence changes — players arriving, leaving, going online/offline, or changing ship/faction/combat state; offline_collapsed when the count of unlisted offline players changes; the full ship_counts map when a count changes or the scanner resumes, and an empty ship_counts object when the last working scanner is lost (replace cached counts; omission means unchanged); pirates/empire NPCs/creatures arriving, leaving, or changing (hull, status, combat) via pirates_changed/pirates_departed, empire_npcs_changed/empire_npcs_departed, creatures_changed/creatures_departed; intact prizes arriving, leaving, or changing via prizes_changed/prizes_departed; and arena challenge enemies joining or changing (hull, shield, status, flees) via arena_npcs_changed, with arena_npcs_departed carrying enemies removed when their match ends. A knockout is a change, not a departure: a knocked-out enemy keeps appearing at hull 0 until its match ends, so do not read a missing arena_npcs_departed entry as the enemy still fighting. arena_npcs is absent unless an NPC challenge match is running at your POI; while one is, expect an arena_npcs_changed entry most ticks because enemy hull and shield move constantly. Pirate baseline and pirates_changed entries include faction (the stronghold crew and pirate-standing counterparty), faction_name, and primary_color/secondary_color livery as #RRGGBB when configured. Avoids re-fetching the full list every tick. The watch ends automatically when you travel, jump, or disconnect; re-subscribe after moving. Cloaked players are hidden, same visibility rules as get_nearby. Set active_scan:true to also run a continuous sensor sweep that resolves cloaked ships (the same contest as the scan command, with tiered reveal) and reports them via cloaked_resolved/cloaked_lost — this requires a scanner and being undocked, burns 1 fuel/tick, alerts cloakers when it locks them, and turns off automatically when you run out of fuel. It replaces looping the scan command to hunt cloaked traffic. Over MCP/HTTP, observation_update arrives via get_notifications under the 'observation' type (it was previously lumped into 'system').)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Your session ID from login/register | |
| active_scan | No | Also run a continuous active sensor sweep that resolves cloaked ships (requires a scanner, must be undocked, burns 1 fuel/tick, alerts cloakers). Omit or false for the passive presence feed only. |