@idosgames/module-sdk 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { IDosGamesClient } from '@idosgames/core';
+import { RealtimeSession, IDosGamesClient } from '@idosgames/core';
 export { IDosGamesClient, SdkEvents } from '@idosgames/core';
 import { ComponentType } from 'react';
 
@@ -276,6 +276,87 @@ interface FeatureRegistry {
     setPresenter(presenter: FeaturePresenter): () => void;
 }
 
+/** A room setting the host picks when creating a room for the game (guest mode, cheats…). */
+interface MultiplayerSetting {
+    /** Key in `MultiplayerRoom.settings`. */
+    id: string;
+    /** Label, already in the player's language. */
+    label: string;
+    /** A choice of options, or an on/off switch. */
+    kind: "choice" | "toggle";
+    /** For `choice`: value + label of every option. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Value when the host does not change it. */
+    default: string | boolean;
+}
+/** What a game declares about playing online (`ctx.multiplayer.registerGame`). */
+interface MultiplayerGame {
+    /** The game's mode (its route id) — the room's game and where "Play" takes the room. */
+    mode: string;
+    /** Label of the game in the rooms screen; defaults to the route's label. */
+    label?: string;
+    /**
+     * Who connects to whom: `"Host"` (star — the host links to everyone, the others only to the host)
+     * or `"Mesh"` (everyone to everyone). Default `"Mesh"`.
+     */
+    topology?: "Host" | "Mesh";
+    /**
+     * `"P2P"` — the game has its own chat over the DataChannels, the lobby draws none;
+     * `"ServerRelay"` (default) — the lobby's room chat goes through the server.
+     */
+    chatMode?: "P2P" | "ServerRelay";
+    /** Most players in one room (the title's limit caps it). Default 8. */
+    maxPlayers?: number;
+    /**
+     * A player may join a room whose game is already running — the rooms screen lets them in and
+     * `start` gets called for them right away (the game's own "late joiner" path). Default `false`.
+     */
+    joinInProgress?: boolean;
+    /** Room settings the host picks on creation; the game reads them in `room.settings`. */
+    settings?: MultiplayerSetting[];
+    /**
+     * The room goes into this game: switch the game to network play over `room.session`. Called on
+     * EVERY member's device (the host's first) — after the app switched to the game's mode.
+     */
+    start(room: MultiplayerRoom): void | Promise<void>;
+}
+/** The room handed to a game. */
+interface MultiplayerRoom {
+    /** The live session — links, messages, members, host changes. Opened by the rooms system. */
+    readonly session: RealtimeSession;
+    /** The game's mode. */
+    readonly mode: string;
+    /** Whether this player created the game (the host at start). Live host: `session.hostId`. */
+    readonly isHost: boolean;
+    /** The room's settings as the host picked them (defaults filled in). */
+    readonly settings: Readonly<Record<string, string | boolean>>;
+    /**
+     * The game joins a running room (`joinInProgress`) rather than starting together with it.
+     */
+    readonly lateJoin: boolean;
+    /** Leave the room for good: closes the session and the rooms screen forgets it. */
+    leave(): Promise<void>;
+}
+/** What `ctx.features.open("multiplayer", args)` understands. */
+interface MultiplayerScreenArgs {
+    /** Show only this game's rooms and preselect it in "Create a room". */
+    mode?: string;
+    /** Open straight on "Create a room" (a game's "Open for friends"). */
+    create?: boolean;
+}
+/** `ctx.multiplayer` — the host's registry of games that play online, shared by every module. */
+interface MultiplayerRegistry {
+    /** A game declares that it plays online. Returns an unregister function. */
+    registerGame(game: MultiplayerGame): () => void;
+    getGame(mode: string): MultiplayerGame | undefined;
+    listGames(): MultiplayerGame[];
+    /** Called when a game is registered or removed. */
+    subscribe(listener: () => void): () => void;
+}
+
 /** What a module is, for catalog/UI purposes. Not every module is a game. */
 type ModuleType = "game" | "app" | "ai-app";
 /**
@@ -328,10 +409,19 @@ interface ModuleManifest {
      */
     type?: "template" | "feature";
     /**
-     * Part of the standard set: the platform installs this module into EVERY new project together with
-     * the base (login + lobby) — the shop, heroes, leaderboards… A creator removes it like any module.
+     * Part of the base: the platform installs this system into EVERY new project together with the base
+     * (sign-in + the lobby) — only profile, inventory, invite, friends, quests and mailbox (owner's rule
+     * 29.09.2026). Every other module is installed only when it is needed: a game brings the ones it
+     * `uses`, the AI Coder installs any other one as soon as the task needs what it `provides`. A creator removes it like any module.
      */
     inBase?: boolean;
+    /**
+     * A game's modules: catalog ids of the systems this game plugs into (`ctx.multiplayer` →
+     * `"multiplayer"`, `ctx.content` → `"workshop"`, …). The platform installs them together with the game
+     * — a new title on this game gets them, and so does a project the AI Coder adds the game to.
+     * `npm run check` makes a module that registers in `ctx.multiplayer` / `ctx.content` list them.
+     */
+    uses?: string[];
     /** Overrides the catalog display name; defaults to `ModuleMeta.name` from `module.ts`. */
     name?: string;
     /** One-line pitch shown on the catalog card. */
@@ -431,6 +521,12 @@ interface ModuleContext {
      * rather than a mode of its own; `open(id)` opens another module's screen. See `FeatureDefinition`.
      */
     features: FeatureRegistry;
+    /**
+     * Games that play online and the rooms system that runs them (see `MultiplayerGame`). A game
+     * registers here (`registerGame`) and takes the room in `start`; it never creates or joins rooms
+     * itself. Without the multiplayer system installed nothing ever calls `start`.
+     */
+    multiplayer: MultiplayerRegistry;
     /**
      * The app's modes — every route any module registered, and which one is on screen. The lobby
      * builds its "Play" buttons from it; a game can tell whether a lobby exists to return to.
@@ -600,4 +696,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 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 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 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 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 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 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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { IDosGamesClient } from '@idosgames/core';
+import { RealtimeSession, IDosGamesClient } from '@idosgames/core';
 export { IDosGamesClient, SdkEvents } from '@idosgames/core';
 import { ComponentType } from 'react';
 
@@ -276,6 +276,87 @@ interface FeatureRegistry {
     setPresenter(presenter: FeaturePresenter): () => void;
 }
 
+/** A room setting the host picks when creating a room for the game (guest mode, cheats…). */
+interface MultiplayerSetting {
+    /** Key in `MultiplayerRoom.settings`. */
+    id: string;
+    /** Label, already in the player's language. */
+    label: string;
+    /** A choice of options, or an on/off switch. */
+    kind: "choice" | "toggle";
+    /** For `choice`: value + label of every option. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Value when the host does not change it. */
+    default: string | boolean;
+}
+/** What a game declares about playing online (`ctx.multiplayer.registerGame`). */
+interface MultiplayerGame {
+    /** The game's mode (its route id) — the room's game and where "Play" takes the room. */
+    mode: string;
+    /** Label of the game in the rooms screen; defaults to the route's label. */
+    label?: string;
+    /**
+     * Who connects to whom: `"Host"` (star — the host links to everyone, the others only to the host)
+     * or `"Mesh"` (everyone to everyone). Default `"Mesh"`.
+     */
+    topology?: "Host" | "Mesh";
+    /**
+     * `"P2P"` — the game has its own chat over the DataChannels, the lobby draws none;
+     * `"ServerRelay"` (default) — the lobby's room chat goes through the server.
+     */
+    chatMode?: "P2P" | "ServerRelay";
+    /** Most players in one room (the title's limit caps it). Default 8. */
+    maxPlayers?: number;
+    /**
+     * A player may join a room whose game is already running — the rooms screen lets them in and
+     * `start` gets called for them right away (the game's own "late joiner" path). Default `false`.
+     */
+    joinInProgress?: boolean;
+    /** Room settings the host picks on creation; the game reads them in `room.settings`. */
+    settings?: MultiplayerSetting[];
+    /**
+     * The room goes into this game: switch the game to network play over `room.session`. Called on
+     * EVERY member's device (the host's first) — after the app switched to the game's mode.
+     */
+    start(room: MultiplayerRoom): void | Promise<void>;
+}
+/** The room handed to a game. */
+interface MultiplayerRoom {
+    /** The live session — links, messages, members, host changes. Opened by the rooms system. */
+    readonly session: RealtimeSession;
+    /** The game's mode. */
+    readonly mode: string;
+    /** Whether this player created the game (the host at start). Live host: `session.hostId`. */
+    readonly isHost: boolean;
+    /** The room's settings as the host picked them (defaults filled in). */
+    readonly settings: Readonly<Record<string, string | boolean>>;
+    /**
+     * The game joins a running room (`joinInProgress`) rather than starting together with it.
+     */
+    readonly lateJoin: boolean;
+    /** Leave the room for good: closes the session and the rooms screen forgets it. */
+    leave(): Promise<void>;
+}
+/** What `ctx.features.open("multiplayer", args)` understands. */
+interface MultiplayerScreenArgs {
+    /** Show only this game's rooms and preselect it in "Create a room". */
+    mode?: string;
+    /** Open straight on "Create a room" (a game's "Open for friends"). */
+    create?: boolean;
+}
+/** `ctx.multiplayer` — the host's registry of games that play online, shared by every module. */
+interface MultiplayerRegistry {
+    /** A game declares that it plays online. Returns an unregister function. */
+    registerGame(game: MultiplayerGame): () => void;
+    getGame(mode: string): MultiplayerGame | undefined;
+    listGames(): MultiplayerGame[];
+    /** Called when a game is registered or removed. */
+    subscribe(listener: () => void): () => void;
+}
+
 /** What a module is, for catalog/UI purposes. Not every module is a game. */
 type ModuleType = "game" | "app" | "ai-app";
 /**
@@ -328,10 +409,19 @@ interface ModuleManifest {
      */
     type?: "template" | "feature";
     /**
-     * Part of the standard set: the platform installs this module into EVERY new project together with
-     * the base (login + lobby) — the shop, heroes, leaderboards… A creator removes it like any module.
+     * Part of the base: the platform installs this system into EVERY new project together with the base
+     * (sign-in + the lobby) — only profile, inventory, invite, friends, quests and mailbox (owner's rule
+     * 29.09.2026). Every other module is installed only when it is needed: a game brings the ones it
+     * `uses`, the AI Coder installs any other one as soon as the task needs what it `provides`. A creator removes it like any module.
      */
     inBase?: boolean;
+    /**
+     * A game's modules: catalog ids of the systems this game plugs into (`ctx.multiplayer` →
+     * `"multiplayer"`, `ctx.content` → `"workshop"`, …). The platform installs them together with the game
+     * — a new title on this game gets them, and so does a project the AI Coder adds the game to.
+     * `npm run check` makes a module that registers in `ctx.multiplayer` / `ctx.content` list them.
+     */
+    uses?: string[];
     /** Overrides the catalog display name; defaults to `ModuleMeta.name` from `module.ts`. */
     name?: string;
     /** One-line pitch shown on the catalog card. */
@@ -431,6 +521,12 @@ interface ModuleContext {
      * rather than a mode of its own; `open(id)` opens another module's screen. See `FeatureDefinition`.
      */
     features: FeatureRegistry;
+    /**
+     * Games that play online and the rooms system that runs them (see `MultiplayerGame`). A game
+     * registers here (`registerGame`) and takes the room in `start`; it never creates or joins rooms
+     * itself. Without the multiplayer system installed nothing ever calls `start`.
+     */
+    multiplayer: MultiplayerRegistry;
     /**
      * The app's modes — every route any module registered, and which one is on screen. The lobby
      * builds its "Play" buttons from it; a game can tell whether a lobby exists to return to.
@@ -600,4 +696,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 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 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 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 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 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 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idosgames/module-sdk",
-  "version": "0.6.0",
+  "version": "0.7.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",