@kvyverse/world-runtime 0.6.2 → 0.6.8

package/dist/modules/contracts/platform.module-api.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Public API of the `platform` module — the world's link to the Kvyverse
+ * platform. Off the platform (self-hosted export) every call is a safe no-op:
+ * nothing throws, reads resolve to empty values.
+ */
+export interface PlatformModuleApi {
+    /** The world runs on the platform and the link is established. */
+    readonly available: boolean;
+    readonly player: PlatformPlayerApi;
+    /** Parameters this world was opened with; empty when opened from its own page. */
+    readonly openedWith: Readonly<WorldOpenParams>;
+    /**
+     * The world that switched to this one with `openWorld`; `null` when the
+     * player came straight to this page (a reload included).
+     */
+    readonly referrer: WorldName | null;
+    /**
+     * Asks the platform to put another world of the same author on this page,
+     * in place of this one. `state` reaches it as its `openedWith`. Resolves to
+     * `false` when the platform refuses (another author, no such world) or off
+     * the platform; on success this world is torn down.
+     */
+    openWorld: (world: WorldName, state?: WorldOpenParams) => Promise<boolean>;
+    /**
+     * Checks a name that came at runtime (a chat command, player input) against
+     * the author's worlds: resolves to its url-name, typed as `WorldName`, or
+     * `null` when there is no such world of this author, or off the platform.
+     * Takes a url-name or an id.
+     */
+    resolveWorld: (world: string) => Promise<WorldName | null>;
+    /**
+     * Asks the platform to open an external link. The platform shows the address
+     * and asks the player; resolves to `false` when they decline, when the
+     * address is not http(s), or off the platform.
+     */
+    openLink: (url: string) => Promise<boolean>;
+}
+/** Parameters a world is opened with. Values are strings. */
+export type WorldOpenParams = Record<string, string>;
+/**
+ * Filled in by the Kvyverse editor for the author's own world: `worlds` lists
+ * the author's worlds. Not filled (anywhere else) — any string.
+ */
+export interface WorldNamesRegister {
+}
+/** Url-name of one of the author's worlds: what `openWorld` takes and `referrer` holds. */
+export type WorldName = WorldNamesRegister extends {
+    worlds: infer TWorld extends string;
+} ? TWorld : string;
+export interface PlatformPlayerApi {
+    /** Display name of the current player; `null` for a guest or off-platform. */
+    readonly username: string | null;
+    /** Server-side storage for this world + player pair. */
+    readonly storage: PlatformPlayerStorageApi;
+}
+/** Storage of one world for one player. Never throws: no platform — no value. */
+export interface PlatformPlayerStorageApi {
+    get: () => Promise<string | null>;
+    save: (data: string) => Promise<void>;
+}

package/dist/modules/index.d.ts

@@ -7,13 +7,16 @@ import { UtilsModule } from "./UtilsModule";
 import type { AddonsRuntime } from "../addons/AddonsRuntime";
 import type { AddonsConfig } from "../addons/types";
 import type { EnvMode } from "./EnvModule";
+import type { PlatformModuleApi } from "./contracts/platform.module-api";
 import type { KvyverseModules } from "./registry";
+import type { ContextModule } from "three-start";
 export type { ChatModule } from "./chat/ChatModule";
 export type { ChatDom, ChatDomOptions } from "./chat/ChatDom";
 export { ControlsModule } from "./controls/ControlsModule";
 export { EnvModule } from "./EnvModule";
 export { HtmlHudModule } from "./HtmlHudModule";
 export { InputSystemModule } from "./InputSystemModule";
+export { NullPlatformModule } from "./platform/NullPlatformModule";
 export { SoundsModule } from "./SoundsModule";
 export { UtilsModule } from "./UtilsModule";
 export { isMobileDevice } from "./is-mobile-device";
@@ -25,6 +28,7 @@ export type CoreWorldModules = {
     env: EnvModule;
     html: HtmlHudModule;
     input: InputSystemModule;
+    platform: ContextModule & PlatformModuleApi;
     sounds: SoundsModule;
     utils: UtilsModule;
 };
@@ -35,6 +39,8 @@ export interface CreateWorldModulesOptions {
     addons: AddonsRuntime;
     /** `settings.addons.json → modules`: which pluggable modules are on, and how. */
     modules?: AddonsConfig["modules"];
+    /** `world.platform`: the host's implementation; omitted off the platform, and it turns no-op. */
+    platform?: ContextModule & PlatformModuleApi;
 }
 /**
  * Assembles the world's ctx modules: core ones always, pluggable ones per config.

package/dist/modules/optional-module-descriptor.d.ts

@@ -1,3 +1,4 @@
+import type { KvyverseModules } from "./registry";
 import type { ContextModule } from "three-start";
 import type { LibId } from "../addons/lib-registry";
 /**
@@ -22,6 +23,12 @@ export type ModuleJsonSchema = Record<string, unknown>;
  */
 export interface OptionalModuleDescriptor<TConfig = unknown> {
     id: OptionalModuleId;
+    /**
+     * Key in `ctx.modules`, when it differs from the config key `id` (physics is
+     * configured as `modules.physics` but lives on `ctx.modules.rapier`, named
+     * after the engine). Defaults to `id`.
+     */
+    ctxKey?: keyof KvyverseModules;
     /** Config value → normalized config; `null` means the module is off. */
     normalize: (raw: unknown) => TConfig | null;
     /** Config for an on-demand enable (a behaviour pulled the module in without config). */

package/dist/modules/platform/NullPlatformModule.d.ts

@@ -0,0 +1,16 @@
+import { ContextModule } from "three-start";
+import type { PlatformModuleApi, PlatformPlayerApi, WorldOpenParams } from "../contracts/platform.module-api";
+/**
+ * `world.platform` без платформы: self-hosted экспорт, мир без моста. Все вызовы
+ * безопасны — чтения пустые, записи ничего не делают. Мир на платформе получает
+ * вместо него реализацию хоста, переданную в `createWorldModules({ platform })`.
+ */
+export declare class NullPlatformModule extends ContextModule implements PlatformModuleApi {
+    readonly available = false;
+    readonly player: PlatformPlayerApi;
+    readonly openedWith: Readonly<WorldOpenParams>;
+    readonly referrer: null;
+    openWorld(): Promise<boolean>;
+    resolveWorld(): Promise<null>;
+    openLink(): Promise<boolean>;
+}

package/dist/modules/registry.d.ts

@@ -1,3 +1,4 @@
+import type { ContextModule } from "three-start";
 import type { RapierPhysics } from "./physics/RapierPhysics";
 import type { AddonsRuntime } from "../addons/AddonsRuntime";
 import type { ChatModule } from "./chat/ChatModule";
@@ -5,6 +6,7 @@ import type { ControlsModule } from "./controls/ControlsModule";
 import type { EnvModule } from "./EnvModule";
 import type { HtmlHudModule } from "./HtmlHudModule";
 import type { InputSystemModule } from "./InputSystemModule";
+import type { PlatformModuleApi } from "./contracts/platform.module-api";
 import type { SoundsModule } from "./SoundsModule";
 import type { UtilsModule } from "./UtilsModule";
 /**
@@ -23,6 +25,8 @@ export interface KvyverseModules {
     controls: ControlsModule;
     env: EnvModule;
     html: HtmlHudModule;
+    /** Реализацию даёт тот, кто собирает мир: хост на платформе или пустая. */
+    platform: ContextModule & PlatformModuleApi;
     sounds: SoundsModule;
     utils: UtilsModule;
     rapier: RapierPhysics;

package/dist/version.gen.d.ts

@@ -1 +1 @@
-export declare const RUNTIME_VERSION = "0.6.2";
+export declare const RUNTIME_VERSION = "0.6.8";

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "@kvyverse/world-runtime",
-	"version": "0.6.2",
+	"version": "0.6.8",
 	"description": "Runtime for worlds exported from the Kvyverse platform for self-hosting",
 	"license": "SEE LICENSE IN LICENSE.md",
-	"author": "Vladislav Kruteniuk",
+	"author": "Kvyverse, Inc.",
 	"homepage": "https://kvyverse.com",
 	"type": "module",
 	"main": "./dist/index.js",