@spawnco/sdk-types 0.0.54 → 0.0.56

package/dist/index.d.mts

@@ -22,6 +22,51 @@ interface SoundSettings {
     ambience: number;
     voice: number;
 }
+type GameSpecMutation = {
+    kind: 'spawn';
+    id: string;
+    spec: Record<string, unknown>;
+} | {
+    kind: 'destroy';
+    id: string;
+} | {
+    kind: 'setProperty';
+    id: string;
+    key: string;
+    value: unknown;
+} | {
+    kind: 'replaceState';
+    id: string;
+    state: Record<string, unknown>;
+} | {
+    kind: 'patchState';
+    id: string;
+    patch: Record<string, unknown>;
+};
+interface GameSpecMutationResult {
+    appId: string;
+    version: number;
+    applied: number;
+    skipped: number;
+    mutationCount: number;
+    updated: boolean;
+}
+interface RoomRegistrationOptions {
+    maxPlayers?: number;
+    metadata?: Record<string, unknown>;
+}
+interface RoomHeartbeatOptions {
+    playerCount: number;
+    metadata?: Record<string, unknown>;
+}
+interface RoomPlayerJoinOptions {
+    userId: string;
+}
+interface RoomRegistrationResult {
+    success: boolean;
+    roomId: string;
+    appId: string;
+}
 interface ClipThumbnailDescriptor {
     assetUrl: string;
     contentType: string;
@@ -217,6 +262,16 @@ interface SpawnServerSDK__V1<TConfig = any> {
             success: boolean;
         }>;
     };
+    roomRegistry: {
+        /** Register this room with the central registry. Call once on room startup. */
+        register(options?: RoomRegistrationOptions): Promise<RoomRegistrationResult>;
+        /** Send heartbeat with current metrics. Call every 30s. */
+        heartbeat(options: RoomHeartbeatOptions): Promise<void>;
+        /** Track a player joining this room. Call when a player connects. */
+        playerJoin(options: RoomPlayerJoinOptions): Promise<void>;
+        /** Deregister this room. Call on graceful shutdown. */
+        deregister(): Promise<void>;
+    };
     sparks: {
         verifyPurchase({ purchaseId, price }: {
             purchaseId: string;
@@ -287,6 +342,13 @@ interface SpawnServerSDK__V1<TConfig = any> {
             version: number;
             gameSpec: Record<string, unknown>;
         } | null>;
+        /**
+         * Apply script-style mutations (spawn/destroy/setProperty/state) to the game spec.
+         */
+        applyMutations(options: {
+            mutations: GameSpecMutation[];
+            appId?: string;
+        }): Promise<GameSpecMutationResult>;
     };
     config: {
         get(): Promise<TConfig>;
@@ -509,4 +571,4 @@ interface JobFnEnv {
 type SpawnClientSDK__V0<TConfig = any> = Omit<SpawnClientSDK__V1<TConfig>, 'economy'>;
 type SpawnServerSDK__V0<TConfig = any> = Omit<SpawnServerSDK__V1<TConfig>, 'economy' | 'room' | 'llm'>;
 
-export type { ClipDescriptor, ClipFormat, ClipKind, ClipListOptions, ClipLookupOptions, ClipStatus, ClipThumbnailDescriptor, InventoryItem, Item, JobDewEnv, JobFnEnv, LeaderboardEntry, LlmApi, LlmChatOptions, LlmChatResponse, LlmModel, Room, RoomInfo, RoomVisibility, SoundSettings, SpawnClientSDK__V0, SpawnClientSDK__V1, SpawnServerSDK__V0, SpawnServerSDK__V1, TokenPayload, UploadClipOptions, User };
+export type { ClipDescriptor, ClipFormat, ClipKind, ClipListOptions, ClipLookupOptions, ClipStatus, ClipThumbnailDescriptor, GameSpecMutation, GameSpecMutationResult, InventoryItem, Item, JobDewEnv, JobFnEnv, LeaderboardEntry, LlmApi, LlmChatOptions, LlmChatResponse, LlmModel, Room, RoomHeartbeatOptions, RoomInfo, RoomPlayerJoinOptions, RoomRegistrationOptions, RoomRegistrationResult, RoomVisibility, SoundSettings, SpawnClientSDK__V0, SpawnClientSDK__V1, SpawnServerSDK__V0, SpawnServerSDK__V1, TokenPayload, UploadClipOptions, User };

package/dist/index.d.ts

@@ -22,6 +22,51 @@ interface SoundSettings {
     ambience: number;
     voice: number;
 }
+type GameSpecMutation = {
+    kind: 'spawn';
+    id: string;
+    spec: Record<string, unknown>;
+} | {
+    kind: 'destroy';
+    id: string;
+} | {
+    kind: 'setProperty';
+    id: string;
+    key: string;
+    value: unknown;
+} | {
+    kind: 'replaceState';
+    id: string;
+    state: Record<string, unknown>;
+} | {
+    kind: 'patchState';
+    id: string;
+    patch: Record<string, unknown>;
+};
+interface GameSpecMutationResult {
+    appId: string;
+    version: number;
+    applied: number;
+    skipped: number;
+    mutationCount: number;
+    updated: boolean;
+}
+interface RoomRegistrationOptions {
+    maxPlayers?: number;
+    metadata?: Record<string, unknown>;
+}
+interface RoomHeartbeatOptions {
+    playerCount: number;
+    metadata?: Record<string, unknown>;
+}
+interface RoomPlayerJoinOptions {
+    userId: string;
+}
+interface RoomRegistrationResult {
+    success: boolean;
+    roomId: string;
+    appId: string;
+}
 interface ClipThumbnailDescriptor {
     assetUrl: string;
     contentType: string;
@@ -217,6 +262,16 @@ interface SpawnServerSDK__V1<TConfig = any> {
             success: boolean;
         }>;
     };
+    roomRegistry: {
+        /** Register this room with the central registry. Call once on room startup. */
+        register(options?: RoomRegistrationOptions): Promise<RoomRegistrationResult>;
+        /** Send heartbeat with current metrics. Call every 30s. */
+        heartbeat(options: RoomHeartbeatOptions): Promise<void>;
+        /** Track a player joining this room. Call when a player connects. */
+        playerJoin(options: RoomPlayerJoinOptions): Promise<void>;
+        /** Deregister this room. Call on graceful shutdown. */
+        deregister(): Promise<void>;
+    };
     sparks: {
         verifyPurchase({ purchaseId, price }: {
             purchaseId: string;
@@ -287,6 +342,13 @@ interface SpawnServerSDK__V1<TConfig = any> {
             version: number;
             gameSpec: Record<string, unknown>;
         } | null>;
+        /**
+         * Apply script-style mutations (spawn/destroy/setProperty/state) to the game spec.
+         */
+        applyMutations(options: {
+            mutations: GameSpecMutation[];
+            appId?: string;
+        }): Promise<GameSpecMutationResult>;
     };
     config: {
         get(): Promise<TConfig>;
@@ -509,4 +571,4 @@ interface JobFnEnv {
 type SpawnClientSDK__V0<TConfig = any> = Omit<SpawnClientSDK__V1<TConfig>, 'economy'>;
 type SpawnServerSDK__V0<TConfig = any> = Omit<SpawnServerSDK__V1<TConfig>, 'economy' | 'room' | 'llm'>;
 
-export type { ClipDescriptor, ClipFormat, ClipKind, ClipListOptions, ClipLookupOptions, ClipStatus, ClipThumbnailDescriptor, InventoryItem, Item, JobDewEnv, JobFnEnv, LeaderboardEntry, LlmApi, LlmChatOptions, LlmChatResponse, LlmModel, Room, RoomInfo, RoomVisibility, SoundSettings, SpawnClientSDK__V0, SpawnClientSDK__V1, SpawnServerSDK__V0, SpawnServerSDK__V1, TokenPayload, UploadClipOptions, User };
+export type { ClipDescriptor, ClipFormat, ClipKind, ClipListOptions, ClipLookupOptions, ClipStatus, ClipThumbnailDescriptor, GameSpecMutation, GameSpecMutationResult, InventoryItem, Item, JobDewEnv, JobFnEnv, LeaderboardEntry, LlmApi, LlmChatOptions, LlmChatResponse, LlmModel, Room, RoomHeartbeatOptions, RoomInfo, RoomPlayerJoinOptions, RoomRegistrationOptions, RoomRegistrationResult, RoomVisibility, SoundSettings, SpawnClientSDK__V0, SpawnClientSDK__V1, SpawnServerSDK__V0, SpawnServerSDK__V1, TokenPayload, UploadClipOptions, User };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spawnco/sdk-types",
-  "version": "0.0.54",
+  "version": "0.0.56",
   "description": "TypeScript type definitions for Spawn SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/v1.ts

@@ -27,6 +27,42 @@ export interface SoundSettings {
   voice: number; // 0-1
 }
 
+export type GameSpecMutation =
+  | { kind: 'spawn'; id: string; spec: Record<string, unknown> }
+  | { kind: 'destroy'; id: string }
+  | { kind: 'setProperty'; id: string; key: string; value: unknown }
+  | { kind: 'replaceState'; id: string; state: Record<string, unknown> }
+  | { kind: 'patchState'; id: string; patch: Record<string, unknown> };
+
+export interface GameSpecMutationResult {
+  appId: string;
+  version: number;
+  applied: number;
+  skipped: number;
+  mutationCount: number;
+  updated: boolean;
+}
+
+export interface RoomRegistrationOptions {
+  maxPlayers?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RoomHeartbeatOptions {
+  playerCount: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RoomPlayerJoinOptions {
+  userId: string;
+}
+
+export interface RoomRegistrationResult {
+  success: boolean;
+  roomId: string;
+  appId: string;
+}
+
 export interface ClipThumbnailDescriptor {
   assetUrl: string;
   contentType: string;
@@ -235,6 +271,20 @@ export interface SpawnServerSDK__V1<TConfig = any> {
     notifyDm(options: { message: string; source?: string; entityId?: string }): Promise<{ success: boolean }>;
   };
 
+  roomRegistry: {
+    /** Register this room with the central registry. Call once on room startup. */
+    register(options?: RoomRegistrationOptions): Promise<RoomRegistrationResult>;
+
+    /** Send heartbeat with current metrics. Call every 30s. */
+    heartbeat(options: RoomHeartbeatOptions): Promise<void>;
+
+    /** Track a player joining this room. Call when a player connects. */
+    playerJoin(options: RoomPlayerJoinOptions): Promise<void>;
+
+    /** Deregister this room. Call on graceful shutdown. */
+    deregister(): Promise<void>;
+  };
+
   sparks: {
     verifyPurchase({ purchaseId, price }: { purchaseId: string; price: number }): Promise<boolean>;
   };
@@ -310,6 +360,11 @@ export interface SpawnServerSDK__V1<TConfig = any> {
       version: number;
       gameSpec: Record<string, unknown>;
     } | null>;
+
+    /**
+     * Apply script-style mutations (spawn/destroy/setProperty/state) to the game spec.
+     */
+    applyMutations(options: { mutations: GameSpecMutation[]; appId?: string }): Promise<GameSpecMutationResult>;
   };
 
   config: {