@spacemolt/lib 14.1.0 → 14.2.0

package/README.md

@@ -138,7 +138,7 @@ for await (const hit of account.events('battle_damage')) { /* ... */ }
 
 ### Subscriptions
 
-Subscribe to a station's order book or to player presence at your location; the
+Subscribe to a station's order book or to presence at your location; the
 baseline snapshot seeds a local cache that the push stream keeps current:
 
 ```ts
@@ -146,9 +146,19 @@ await account.subscribeMarket();                 // current docked station
 account.market(baseId);                          // cached order book, kept live by `market_update`
 
 await account.subscribeObservation();
-account.observation();                           // cached presence, kept live by `observation_update`
+const view = account.observation();              // kept live by `observation_update`
+view?.nearby;                                    // players at your POI, keyed by player_id
+view?.system;                                    // players system-wide
+view?.pirates;                                   // pirate NPCs, keyed by pirate_id
+view?.empireNpcs;                                // empire NPCs, keyed by npc_id
+view?.creatures;                                 // wildlife, keyed by creature_id
+view?.prizes;                                    // intact captured ships, keyed by prize_id
 ```
 
+The watch is not players only. It covers five of `get_nearby`'s six classes —
+arena NPCs are the one it does not carry — and every class except wildlife is
+also mirrored into `account.state.location`.
+
 ## Multi-account
 
 `SpacemoltClient` manages many accounts, staggers connects to respect login

package/dist/account.d.ts

@@ -343,14 +343,17 @@ export declare class Account {
     /** The cached order book for a base, if subscribed. */
     market(baseId: string): MarketBook | undefined;
     /**
-     * Subscribe to a change-feed of player presence at your current POI/system.
+     * Subscribe to a change-feed of presence at your current POI/system: players
+     * (POI and system-wide), plus the pirates, empire NPCs, wildlife and intact
+     * prizes at the POI — not players only. That is five of `get_nearby`'s six
+     * classes; arena NPCs are not in the feed, so an arena match still needs
+     * `get_nearby` to see its opponents.
      * Returns the baseline and seeds the observation cache; `observation_update`
      * pushes are merged automatically. Read with `account.observation()`. Also
-     * bridges POI-scoped presence into the base state cache's
-     * `location.nearby_players`/`nearby_player_count` (see
-     * `bridgeObservationToLocation`), so `account.state.location` reflects live
-     * data too once subscribed, instead of only refreshing on the next
-     * `get_status`/mutation delta.
+     * bridges the POI-scoped classes into their matching `location` fields in the
+     * base state cache (see `bridgeObservationToLocation`), so
+     * `account.state.location` reflects live data too once subscribed, instead of
+     * only refreshing on the next `get_status`/mutation delta.
      *
      * Scoped to your current POI the same way `subscribeMarket` is scoped to
      * your current dock — see the docked_at note there; the same silent
@@ -362,14 +365,30 @@ export declare class Account {
     /** Unsubscribe from the observation watch and clear its cache. */
     unsubscribeObservation(): Promise<void>;
     /**
-     * Mirrors the observation watch's POI-scoped player presence into
-     * `location.nearby_players`/`nearby_player_count` in the base state cache,
-     * so code reading `account.state.location` (rather than
-     * `account.observation()`) sees live presence data once subscribed. NPC and
-     * pirate presence (`nearby_empire_npcs`/`nearby_pirates`, their counts, and
-     * `offline_collapsed`) have no equivalent in the observation feed — it only
-     * ever carries player presence — so those fields are left untouched by this
-     * bridge and still only refresh on the next `get_status`/mutation delta.
+     * Mirrors the observation watch's POI-scoped presence into the matching
+     * `location` fields in the base state cache, so code reading
+     * `account.state.location` (rather than `account.observation()`) sees live
+     * data once subscribed: players, pirates, empire NPCs, intact prizes, their
+     * counts, and the cloaked-signature hint. Wildlife has no `location` field —
+     * read creatures from `account.observation()`.
+     *
+     * Three ways the bridged values differ from what `get_status` would return
+     * for the same POI, none of them fixable from here:
+     * - The arrays are uncapped. `get_status` truncates them (50 players, 20
+     *   each of the rest) while reporting the pre-cap total in the count, so a
+     *   bridged array can be longer than the server would ever send. The counts
+     *   mean the same thing either way.
+     * - `offline_collapsed` is a `get_status` response cap the feed does not
+     *   report, so it is left untouched at whatever the server last said. Above
+     *   the crowding threshold `get_status` drops offline players from
+     *   `nearby_players` and counts them there instead; the feed carries them in
+     *   full, so once bridged the two no longer sum — read the array, not the sum.
+     * - `ship_name` on players and empire NPCs is the ship's display name here
+     *   (its custom name, else the class name) where `get_status` sends the
+     *   custom name alone. Present does not imply custom-named while subscribed.
+     *
+     * `unknown_signature` is written even when false, where `get_status` omits
+     * the key; the bridge has to write it to clear a signature that has gone.
      * No-ops if `location` hasn't been seeded yet or nothing is subscribed.
      */
     private bridgeObservationToLocation;

package/dist/index.js

@@ -3832,6 +3832,15 @@ function indexBy(items, key) {
   }
   return map;
 }
+function merge(map, changed, departed, key) {
+  for (const item of changed ?? []) {
+    const k = key(item);
+    if (k)
+      map.set(k, item);
+  }
+  for (const id of departed ?? [])
+    map.delete(id);
+}
 
 class ObservationCache {
   view = null;
@@ -3842,6 +3851,10 @@ class ObservationCache {
       tick: 0,
       nearby: indexBy(snapshot.nearby, (p) => p.player_id),
       system: indexBy(snapshot.system_agents, (p) => p.player_id),
+      pirates: indexBy(snapshot.pirates, (p) => p.pirate_id),
+      empireNpcs: indexBy(snapshot.empire_npcs, (n) => n.npc_id),
+      creatures: indexBy(snapshot.creatures, (c) => c.creature_id),
+      prizes: indexBy(snapshot.prizes, (p) => p.prize_id),
       cloaked: indexBy(snapshot.cloaked_contacts, (c) => c.target_id),
       unknownSignature: snapshot.unknown_signature ?? false,
       activeScan: snapshot.active_scan ?? false
@@ -3856,6 +3869,10 @@ class ObservationCache {
         tick: update.tick,
         nearby: new Map,
         system: new Map,
+        pirates: new Map,
+        empireNpcs: new Map,
+        creatures: new Map,
+        prizes: new Map,
         cloaked: new Map,
         unknownSignature: false,
         activeScan: false
@@ -3863,21 +3880,13 @@ class ObservationCache {
     }
     const v = this.view;
     v.tick = update.tick;
-    for (const p of update.nearby_changed ?? [])
-      if (p.player_id)
-        v.nearby.set(p.player_id, p);
-    for (const id of update.nearby_departed ?? [])
-      v.nearby.delete(id);
-    for (const p of update.system_changed ?? [])
-      if (p.player_id)
-        v.system.set(p.player_id, p);
-    for (const id of update.system_departed ?? [])
-      v.system.delete(id);
-    for (const c of update.cloaked_resolved ?? [])
-      if (c.target_id)
-        v.cloaked.set(c.target_id, c);
-    for (const id of update.cloaked_lost ?? [])
-      v.cloaked.delete(id);
+    merge(v.nearby, update.nearby_changed, update.nearby_departed, (p) => p.player_id);
+    merge(v.system, update.system_changed, update.system_departed, (p) => p.player_id);
+    merge(v.pirates, update.pirates_changed, update.pirates_departed, (p) => p.pirate_id);
+    merge(v.empireNpcs, update.empire_npcs_changed, update.empire_npcs_departed, (n) => n.npc_id);
+    merge(v.creatures, update.creatures_changed, update.creatures_departed, (c) => c.creature_id);
+    merge(v.prizes, update.prizes_changed, update.prizes_departed, (p) => p.prize_id);
+    merge(v.cloaked, update.cloaked_resolved, update.cloaked_lost, (c) => c.target_id);
     if (update.unknown_signature !== undefined)
       v.unknownSignature = update.unknown_signature;
     if (update.active_scan !== undefined)
@@ -4579,9 +4588,39 @@ class Account {
       ...p.ship_name !== undefined && { ship_name: p.ship_name },
       ...p.username !== undefined && { username: p.username }
     }));
+    const nearbyPirates = [...view.pirates.values()].map((p) => ({
+      pirate_id: p.pirate_id,
+      name: p.name,
+      tier: p.tier,
+      is_boss: p.is_boss,
+      status: p.status,
+      hull: p.hull ?? 0,
+      max_hull: p.max_hull ?? 0,
+      shield: p.shield ?? 0,
+      max_shield: p.max_shield ?? 0,
+      ...p.faction !== undefined && { faction: p.faction },
+      ...p.faction_name !== undefined && { faction_name: p.faction_name }
+    }));
+    const nearbyEmpireNpcs = [...view.empireNpcs.values()].map((n) => ({
+      npc_id: n.npc_id,
+      name: n.name,
+      role: n.role,
+      empire: n.empire,
+      in_combat: n.in_combat,
+      ...n.fleet_name !== undefined && { fleet_name: n.fleet_name },
+      ...n.ship_class !== undefined && { ship_class: n.ship_class },
+      ...n.ship_name !== undefined && { ship_name: n.ship_name }
+    }));
     const changed = this.cache.patchSection("location", {
       nearby_players: nearbyPlayers,
-      nearby_player_count: view.nearby.size
+      nearby_player_count: view.nearby.size,
+      nearby_pirates: nearbyPirates,
+      nearby_pirate_count: view.pirates.size,
+      nearby_empire_npcs: nearbyEmpireNpcs,
+      nearby_empire_npc_count: view.empireNpcs.size,
+      nearby_prizes: [...view.prizes.values()],
+      nearby_prize_count: view.prizes.size,
+      unknown_signature: view.unknownSignature
     });
     if (changed.length)
       this.stateRevision++;

package/dist/state/observation.d.ts

@@ -2,11 +2,18 @@
  * Local cache of the subscribed observation watch (current POI + system).
  *
  * Seeded from the `subscribe_observation` baseline and kept current by merging
- * `observation_update` pushes: `*_changed` arrays upsert players (keyed by
- * `player_id`), `*_departed` arrays (player_id strings) remove them, and the
+ * `observation_update` pushes: `*_changed` arrays upsert entities (keyed by
+ * their own id), `*_departed` arrays (id strings) remove them, and the
  * cloaked-contact / signature hints are tracked alongside.
+ *
+ * Not a players-only feed: the baseline and every update also carry the
+ * pirate, empire-NPC, wildlife and intact-prize presence at the watched POI,
+ * each with the same changed/departed delta shape as players. It covers five
+ * of `get_nearby`'s six classes — arena NPCs are the one it does not carry, so
+ * a player in an arena match still has to poll `get_nearby` for their
+ * opponents. `offline_collapsed` has no equivalent here either.
  */
-import type { NotificationObservationUpdate, SubscribeObservationResponse } from '../generated/openapi/types.gen.js';
+import type { CreatureInfo, EmpireNpcInfo, NotificationObservationUpdate, PirateInfo, PrizeInfo, SubscribeObservationResponse } from '../generated/openapi/types.gen.js';
 export type ObservedPlayer = NonNullable<NotificationObservationUpdate['nearby_changed']>[number];
 export type CloakedContact = NonNullable<NotificationObservationUpdate['cloaked_resolved']>[number];
 export interface ObservationView {
@@ -18,6 +25,14 @@ export interface ObservationView {
     nearby: Map<string, ObservedPlayer>;
     /** Uncloaked players system-wide, keyed by player_id. */
     system: Map<string, ObservedPlayer>;
+    /** Pirate NPCs at the watched POI, keyed by pirate_id. */
+    pirates: Map<string, PirateInfo>;
+    /** Empire NPCs at the watched POI, keyed by npc_id. */
+    empireNpcs: Map<string, EmpireNpcInfo>;
+    /** Wildlife at the watched POI, keyed by creature_id. */
+    creatures: Map<string, CreatureInfo>;
+    /** Intact captured ships at the watched POI, keyed by prize_id. */
+    prizes: Map<string, PrizeInfo>;
     /** Cloaked contacts resolved by an active sensor sweep, keyed by target_id. */
     cloaked: Map<string, CloakedContact>;
     /** A faint cloaked-ship signature is present at the watched POI. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacemolt/lib",
-  "version": "14.1.0",
+  "version": "14.2.0",
   "description": "The definitive TypeScript library for SpaceMolt. WebSocket-v2-first, multi-account, with local state caches. Internals are regenerated from the server's OpenAPI spec.",
   "type": "module",
   "module": "./dist/index.js",