Add GMCPClientSpatial package for spatial audio scene management

Introduces Client.Spatial GMCP package with full scene, entity, emitter,
and listener position/orientation handling. Adds corresponding spatial
state fields to WorldData and clears them on connection cleanup.

Co-Authored-By: Christopher Toth <q.alpha@gmail.com>

Author: ctoth

src/client.ts

@@ -27,18 +27,29 @@ import {
   parseMcpMultiline,
 } from "./mcp";
 
-import { Cacophony } from "cacophony";
-import { AutoreadMode, preferencesStore } from "./PreferencesStore";
-import { WebRTCService } from "./WebRTCService";
+import { Cacophony } from "cacophony";
+import { AutoreadMode, preferencesStore } from "./PreferencesStore";
+import { WebRTCService } from "./WebRTCService";
 import FileTransferManager from "./FileTransferManager.js";
 import { GMCPMessageRoomInfo, RoomPlayer } from "./gmcp/Room"; // Import RoomPlayer
+import type {
+  SpatialEmitter,
+  SpatialEntity,
+  SpatialListenerOrientation,
+  SpatialVector,
+} from "./gmcp/Client/Spatial";
 
 export interface WorldData {
-  liveKitTokens: string[];
-  playerId: string;
-  playerName: string;
-  roomId: string;
-  roomPlayers: RoomPlayer[]; // Changed from string[]
+  liveKitTokens: string[];
+  playerId: string;
+  playerName: string;
+  roomId: string;
+  roomPlayers: RoomPlayer[]; // Changed from string[]
+  spatialEntities: Record<string, SpatialEntity>;
+  spatialEmitters: Record<string, SpatialEmitter>;
+  listenerEntityId: string;
+  listenerPosition: SpatialVector | null;
+  listenerOrientation: SpatialListenerOrientation;
 }
 
 function resetMidiIntentionalDisconnectFlags(): void {
@@ -78,13 +89,18 @@ class MudClient extends EventEmitter {
   public mcp_getset: McpAwnsGetSet;
   public gmcp_char: GMCPChar;
   public gmcp_fileTransfer: GMCPClientFileTransfer;
-  public worldData: WorldData = {
-    playerId: "",
-    playerName: "",
-    roomId: "",
-    liveKitTokens: [],
-    roomPlayers: [], // Initialized as RoomPlayer[]
-  };
+  public worldData: WorldData = {
+    playerId: "",
+    playerName: "",
+    roomId: "",
+    liveKitTokens: [],
+    roomPlayers: [], // Initialized as RoomPlayer[]
+    spatialEntities: {},
+    spatialEmitters: {},
+    listenerEntityId: "",
+    listenerPosition: null,
+    listenerOrientation: { forward: null, up: null },
+  };
   public cacophony: Cacophony;
   public editors: EditorManager;
   public webRTCService: WebRTCService;
@@ -419,13 +435,18 @@ class MudClient extends EventEmitter {
     }
   }
 
-  private cleanupConnection(): void {
-    this._connected = false;
-    this.mcpAuthKey = null;
-    this.telnetBuffer = "";
-    this.telnetNegotiation = false;
-    this.currentRoomInfo = null; // Reset room info on cleanup
-    this.webRTCService.cleanup();
+  private cleanupConnection(): void {
+    this._connected = false;
+    this.mcpAuthKey = null;
+    this.telnetBuffer = "";
+    this.telnetNegotiation = false;
+    this.currentRoomInfo = null; // Reset room info on cleanup
+    this.worldData.spatialEntities = {};
+    this.worldData.spatialEmitters = {};
+    this.worldData.listenerEntityId = "";
+    this.worldData.listenerPosition = null;
+    this.worldData.listenerOrientation = { forward: null, up: null };
+    this.webRTCService.cleanup();
     this.fileTransferManager.cleanup();
 
     // Reset intentional disconnect flag after handling disconnect

src/components/RoomInfoDisplay.test.tsx

@@ -0,0 +1,76 @@
+import React from "react";
+import { act, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { EventEmitter } from "eventemitter3";
+
+import RoomInfoDisplay from "./RoomInfoDisplay";
+
+function createMockClient() {
+  const emitter = new EventEmitter();
+
+  return Object.assign(emitter, {
+    currentRoomInfo: {
+      num: 101,
+      name: "Codex's Lab",
+      area: "Daystrom Annex",
+      exits: { west: 100, northeast: 102 },
+    },
+    gmcpHandlers: {
+      "Char.Items": {
+        sendRoomRequest: vi.fn(),
+      },
+    },
+    sendCommand: vi.fn(),
+    worldData: {
+      liveKitTokens: [],
+      playerId: "codex",
+      playerName: "codex",
+      roomId: "101",
+      roomPlayers: [
+        {
+          name: "q",
+          fullname: "Q",
+        },
+      ],
+      spatialEntities: {
+        codex: {
+          id: "codex",
+          position: [1, 1, 0],
+        },
+      },
+      spatialEmitters: {
+        "radio-1": {
+          id: "radio-1",
+          binding: "entity",
+          sourceEntity: "codex",
+        },
+      },
+      listenerEntityId: "codex",
+      listenerPosition: [1, 1, 0],
+      listenerOrientation: {
+        forward: [0, 1, 0],
+        up: [0, 0, 1],
+      },
+    },
+  });
+}
+
+describe("RoomInfoDisplay", () => {
+  it("still renders room, players, and items with spatial scene state present", () => {
+    const client = createMockClient();
+
+    render(<RoomInfoDisplay client={client as any} />);
+
+    act(() => {
+      client.emit("itemsList", {
+        location: "room",
+        items: [{ id: "lantern", name: "Lantern", location: "room" }],
+      });
+    });
+
+    expect(screen.getByText("Codex's Lab")).toBeTruthy();
+    expect(screen.getByText("Area: Daystrom Annex")).toBeTruthy();
+    expect(screen.getByText("Q")).toBeTruthy();
+    expect(screen.getByText("Lantern")).toBeTruthy();
+  });
+});

src/createConfiguredClient.ts

@@ -17,9 +17,10 @@ import {
   GMCPClientHaptics,
   GMCPClientHtml,
   GMCPClientKeystrokes,
-  GMCPClientMedia,
-  GMCPClientMidi,
-  GMCPClientSpeech,
+  GMCPClientMedia,
+  GMCPClientMidi,
+  GMCPClientSpatial,
+  GMCPClientSpeech,
   GMCPCommChannel,
   GMCPCommLiveKit,
   GMCPCore,
@@ -44,8 +45,9 @@ export function createConfiguredClient(): MudClient {
   const client = new MudClient("mongoose.moo.mud.org", 8765);
   // GMCP packages
   client.registerGMCPPackage(GMCPCore);
-  client.registerGMCPPackage(GMCPClientMedia);
-  client.registerGMCPPackage(GMCPClientMidi);
+  client.registerGMCPPackage(GMCPClientMedia);
+  client.registerGMCPPackage(GMCPClientSpatial);
+  client.registerGMCPPackage(GMCPClientMidi);
   client.registerGMCPPackage(GMCPClientSpeech);
   client.registerGMCPPackage(GMCPClientKeystrokes);
   client.registerGMCPPackage(GMCPCoreSupports);