@idosgames/module-sdk 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { RealtimeSession, IDosGamesClient } from '@idosgames/core';
+import { RealtimeSession, VoiceController, IDosGamesClient } from '@idosgames/core';
 export { IDosGamesClient, SdkEvents } from '@idosgames/core';
 import { ComponentType } from 'react';
 
@@ -345,6 +345,13 @@ interface MultiplayerRoom {
     readonly lateJoin: boolean;
     /** Leave the room for good: closes the session and the rooms screen forgets it. */
     leave(): Promise<void>;
+    /**
+     * The room's voice chat, or `null` when the room has none. The rooms system owns it and draws its
+     * controls (the mic button over the game included); a game reads it for its own touches — who is
+     * speaking (`isSpeaking`, `on("change")`), a talking player's marker, proximity volume
+     * (`setPeerVolume` by distance).
+     */
+    readonly voice: VoiceController | null;
 }
 /** What `ctx.features.open("multiplayer", args)` understands. */
 interface MultiplayerScreenArgs {
@@ -525,6 +532,32 @@ interface AppNotifications {
     dismiss(id: string): void;
 }
 
+/** The room's voices, as the recording takes them (the multiplayer system provides this). */
+interface RecordingVoiceSource {
+    /** This player's microphone track (silent while not transmitting); null — mic off. */
+    mic(): MediaStreamTrack | null;
+    /** Other players' voice tracks. */
+    others(): MediaStreamTrack[];
+    /** The publisher allows other players' voices in videos (`Multiplayer.RecordVoices`). */
+    recordOthers(): boolean;
+    /** Called when tracks come or go (a player joined, the mic went on). */
+    subscribe(listener: () => void): () => void;
+}
+/** `ctx.clips`. */
+interface ClipsRegistry {
+    /**
+     * A bright moment right now. `weight` 1–10 (default 5): how much it is worth showing — a boss
+     * kill 8, a level-up 4. Close marks merge into one clip (their weights add up).
+     */
+    mark(name: string, weight?: number): void;
+    /** The multiplayer system registers the room's voices here; `null` when the room is gone. */
+    setVoiceSource(source: RecordingVoiceSource | null): void;
+    /** This player is making a long recording right now. */
+    isRecording(): boolean;
+    /** Called when `isRecording` changes. */
+    subscribe(listener: () => void): () => void;
+}
+
 /** What a module is, for catalog/UI purposes. Not every module is a game. */
 type ModuleType = "game" | "app" | "ai-app";
 /**
@@ -750,6 +783,12 @@ interface ModuleContext {
      * one look, one queue, one sound for the whole app. The module's own id is the default `source`.
      */
     notifications: AppNotifications;
+    /**
+     * The platform's video recording (see `ClipsRegistry`): a game marks bright moments
+     * (`ctx.clips.mark("boss_down", 8)`) — they become the player's "Best moments" clips on
+     * idosgames.com. A no-op anywhere else.
+     */
+    clips: ClipsRegistry;
 }
 /**
  * A module's debug surface for the agent: read its state, drive it with named actions.
@@ -842,6 +881,21 @@ interface EngineScene {
      * host falls back to reading the canvas itself, which is correct for 2D canvases.
      */
     capture?(): Promise<Blob | null>;
+    /**
+     * Where the action is right now, 0–1 on both axes of the canvas (the player, the explosion) — for
+     * the platform's video recording: a vertical (TikTok) cut of a landscape game follows this point
+     * instead of cutting the middle. Called a few times a second; keep it cheap. Omit — the centre.
+     */
+    focus?(): {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * The game's own sound as a MediaStream, for the platform's video recording — e.g. a
+     * `MediaStreamAudioDestinationNode` your audio graph also feeds (Three.js: `listener.context`).
+     * Omit — videos carry the voices but not the game's sound.
+     */
+    audio?(): MediaStream | null;
     /** Permanent teardown — dispose GPU resources, remove listeners. */
     destroy(): void;
 }
@@ -930,4 +984,4 @@ interface SharedEventBus<Events extends Record<string, unknown> = Record<string,
 /** Identity helper that pins a module literal to the `Module` type for editor help and errors. */
 declare function defineModule(module: Module): Module;
 
-export { type AppNotifications, type CapturedContent, type ContentFileData, type ContentRegistry, type ContentTypeHandler, type DownloadedContent, type EngineScene, type FeatureDefinition, type FeatureEntry, type FeatureGroup, type FeaturePresenter, type FeatureRegistry, type FeatureScreenProps, type InferShape, type LoadingReporter, type LoadingTask, type LobbyHeroAction, type LobbyHeroDefinition, type LobbyHeroStage, type LobbyHeroView, type LobbyRegistry, type LocalContentItem, type ModeEntry, type ModeRegistry, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleEventEmit, type ModuleEventListen, type ModuleEvents, type ModuleEventsManifest, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleSharedUi, type ModuleType, type MultiplayerGame, type MultiplayerRegistry, type MultiplayerRoom, type MultiplayerScreenArgs, type MultiplayerSetting, type NotificationAction, type NotificationInput, type NotificationLevel, type PanelSlot, type RouteEntry, SHARED_UI_ROLES, type SceneMountContext, type Shape, type ShapeDescriptor, type ShapeLeaf, type ShapeLeafSpec, type SharedEventBus, type SharedUiContext, type SharedUiRole, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, TOPIC_NAME_RE, type Topic, type TopicName, type TopicPayload, type UiPanel, defineModule, defineTopic, hostTopics, isSharedUiRole, isTopicName, shape, topicNamespace };
+export { type AppNotifications, type CapturedContent, type ClipsRegistry, type ContentFileData, type ContentRegistry, type ContentTypeHandler, type DownloadedContent, type EngineScene, type FeatureDefinition, type FeatureEntry, type FeatureGroup, type FeaturePresenter, type FeatureRegistry, type FeatureScreenProps, type InferShape, type LoadingReporter, type LoadingTask, type LobbyHeroAction, type LobbyHeroDefinition, type LobbyHeroStage, type LobbyHeroView, type LobbyRegistry, type LocalContentItem, type ModeEntry, type ModeRegistry, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleEventEmit, type ModuleEventListen, type ModuleEvents, type ModuleEventsManifest, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleSharedUi, type ModuleType, type MultiplayerGame, type MultiplayerRegistry, type MultiplayerRoom, type MultiplayerScreenArgs, type MultiplayerSetting, type NotificationAction, type NotificationInput, type NotificationLevel, type PanelSlot, type RecordingVoiceSource, type RouteEntry, SHARED_UI_ROLES, type SceneMountContext, type Shape, type ShapeDescriptor, type ShapeLeaf, type ShapeLeafSpec, type SharedEventBus, type SharedUiContext, type SharedUiRole, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, TOPIC_NAME_RE, type Topic, type TopicName, type TopicPayload, type UiPanel, defineModule, defineTopic, hostTopics, isSharedUiRole, isTopicName, shape, topicNamespace };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { RealtimeSession, IDosGamesClient } from '@idosgames/core';
+import { RealtimeSession, VoiceController, IDosGamesClient } from '@idosgames/core';
 export { IDosGamesClient, SdkEvents } from '@idosgames/core';
 import { ComponentType } from 'react';
 
@@ -345,6 +345,13 @@ interface MultiplayerRoom {
     readonly lateJoin: boolean;
     /** Leave the room for good: closes the session and the rooms screen forgets it. */
     leave(): Promise<void>;
+    /**
+     * The room's voice chat, or `null` when the room has none. The rooms system owns it and draws its
+     * controls (the mic button over the game included); a game reads it for its own touches — who is
+     * speaking (`isSpeaking`, `on("change")`), a talking player's marker, proximity volume
+     * (`setPeerVolume` by distance).
+     */
+    readonly voice: VoiceController | null;
 }
 /** What `ctx.features.open("multiplayer", args)` understands. */
 interface MultiplayerScreenArgs {
@@ -525,6 +532,32 @@ interface AppNotifications {
     dismiss(id: string): void;
 }
 
+/** The room's voices, as the recording takes them (the multiplayer system provides this). */
+interface RecordingVoiceSource {
+    /** This player's microphone track (silent while not transmitting); null — mic off. */
+    mic(): MediaStreamTrack | null;
+    /** Other players' voice tracks. */
+    others(): MediaStreamTrack[];
+    /** The publisher allows other players' voices in videos (`Multiplayer.RecordVoices`). */
+    recordOthers(): boolean;
+    /** Called when tracks come or go (a player joined, the mic went on). */
+    subscribe(listener: () => void): () => void;
+}
+/** `ctx.clips`. */
+interface ClipsRegistry {
+    /**
+     * A bright moment right now. `weight` 1–10 (default 5): how much it is worth showing — a boss
+     * kill 8, a level-up 4. Close marks merge into one clip (their weights add up).
+     */
+    mark(name: string, weight?: number): void;
+    /** The multiplayer system registers the room's voices here; `null` when the room is gone. */
+    setVoiceSource(source: RecordingVoiceSource | null): void;
+    /** This player is making a long recording right now. */
+    isRecording(): boolean;
+    /** Called when `isRecording` changes. */
+    subscribe(listener: () => void): () => void;
+}
+
 /** What a module is, for catalog/UI purposes. Not every module is a game. */
 type ModuleType = "game" | "app" | "ai-app";
 /**
@@ -750,6 +783,12 @@ interface ModuleContext {
      * one look, one queue, one sound for the whole app. The module's own id is the default `source`.
      */
     notifications: AppNotifications;
+    /**
+     * The platform's video recording (see `ClipsRegistry`): a game marks bright moments
+     * (`ctx.clips.mark("boss_down", 8)`) — they become the player's "Best moments" clips on
+     * idosgames.com. A no-op anywhere else.
+     */
+    clips: ClipsRegistry;
 }
 /**
  * A module's debug surface for the agent: read its state, drive it with named actions.
@@ -842,6 +881,21 @@ interface EngineScene {
      * host falls back to reading the canvas itself, which is correct for 2D canvases.
      */
     capture?(): Promise<Blob | null>;
+    /**
+     * Where the action is right now, 0–1 on both axes of the canvas (the player, the explosion) — for
+     * the platform's video recording: a vertical (TikTok) cut of a landscape game follows this point
+     * instead of cutting the middle. Called a few times a second; keep it cheap. Omit — the centre.
+     */
+    focus?(): {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * The game's own sound as a MediaStream, for the platform's video recording — e.g. a
+     * `MediaStreamAudioDestinationNode` your audio graph also feeds (Three.js: `listener.context`).
+     * Omit — videos carry the voices but not the game's sound.
+     */
+    audio?(): MediaStream | null;
     /** Permanent teardown — dispose GPU resources, remove listeners. */
     destroy(): void;
 }
@@ -930,4 +984,4 @@ interface SharedEventBus<Events extends Record<string, unknown> = Record<string,
 /** Identity helper that pins a module literal to the `Module` type for editor help and errors. */
 declare function defineModule(module: Module): Module;
 
-export { type AppNotifications, type CapturedContent, type ContentFileData, type ContentRegistry, type ContentTypeHandler, type DownloadedContent, type EngineScene, type FeatureDefinition, type FeatureEntry, type FeatureGroup, type FeaturePresenter, type FeatureRegistry, type FeatureScreenProps, type InferShape, type LoadingReporter, type LoadingTask, type LobbyHeroAction, type LobbyHeroDefinition, type LobbyHeroStage, type LobbyHeroView, type LobbyRegistry, type LocalContentItem, type ModeEntry, type ModeRegistry, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleEventEmit, type ModuleEventListen, type ModuleEvents, type ModuleEventsManifest, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleSharedUi, type ModuleType, type MultiplayerGame, type MultiplayerRegistry, type MultiplayerRoom, type MultiplayerScreenArgs, type MultiplayerSetting, type NotificationAction, type NotificationInput, type NotificationLevel, type PanelSlot, type RouteEntry, SHARED_UI_ROLES, type SceneMountContext, type Shape, type ShapeDescriptor, type ShapeLeaf, type ShapeLeafSpec, type SharedEventBus, type SharedUiContext, type SharedUiRole, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, TOPIC_NAME_RE, type Topic, type TopicName, type TopicPayload, type UiPanel, defineModule, defineTopic, hostTopics, isSharedUiRole, isTopicName, shape, topicNamespace };
+export { type AppNotifications, type CapturedContent, type ClipsRegistry, type ContentFileData, type ContentRegistry, type ContentTypeHandler, type DownloadedContent, type EngineScene, type FeatureDefinition, type FeatureEntry, type FeatureGroup, type FeaturePresenter, type FeatureRegistry, type FeatureScreenProps, type InferShape, type LoadingReporter, type LoadingTask, type LobbyHeroAction, type LobbyHeroDefinition, type LobbyHeroStage, type LobbyHeroView, type LobbyRegistry, type LocalContentItem, type ModeEntry, type ModeRegistry, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleEventEmit, type ModuleEventListen, type ModuleEvents, type ModuleEventsManifest, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleSharedUi, type ModuleType, type MultiplayerGame, type MultiplayerRegistry, type MultiplayerRoom, type MultiplayerScreenArgs, type MultiplayerSetting, type NotificationAction, type NotificationInput, type NotificationLevel, type PanelSlot, type RecordingVoiceSource, type RouteEntry, SHARED_UI_ROLES, type SceneMountContext, type Shape, type ShapeDescriptor, type ShapeLeaf, type ShapeLeafSpec, type SharedEventBus, type SharedUiContext, type SharedUiRole, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, TOPIC_NAME_RE, type Topic, type TopicName, type TopicPayload, type UiPanel, defineModule, defineTopic, hostTopics, isSharedUiRole, isTopicName, shape, topicNamespace };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idosgames/module-sdk",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "The composable-module contract for the iDosGames host shell: Module / ModuleContext types plus tiny authoring helpers. Framework-neutral at runtime — a module can be a game (Three/Phaser), a plain app, or an AI app.",
   "type": "module",
   "license": "MIT",
@@ -46,7 +46,7 @@
   },
   "//": "@idosgames/core is a real range, not '*': a published contract must name the version of core whose IDosGamesClient/SdkEvents shapes it references. Bump in step with core (see RELEASING.md). react is an OPTIONAL peer — the contract references React's ComponentType type only (a UI panel is a React component), which is erased at build, so a runtime-only module needs no React.",
   "dependencies": {
-    "@idosgames/core": "^0.21.0"
+    "@idosgames/core": "^0.22.0"
   },
   "peerDependencies": {
     "react": "^18.3.1 || ^19.0.0"