@kvyverse/world-runtime 0.1.0 → 0.3.2

package/dist/modules/InputSystemModule.d.ts

@@ -1,38 +1,10 @@
 import { ContextModule } from "three-start";
-import EventEmitter from "eventemitter3";
 import * as THREE from "three/webgpu";
 import type { InputModuleApi } from "./contracts/input.module-api";
-declare class PlayerInput extends EventEmitter<{
-    dirchanged: [forward: number, lateral: number];
-    forcechanged: [force: number];
-    jump: [];
-}> {
-    private _forward;
-    private _lateral;
-    private _force;
-    /**
-     * @default 0
-     */
-    get forward(): number;
-    /**
-     * @default 0
-     */
-    get lateral(): number;
-    /**
-     * @default 1
-     */
-    get force(): number;
-    setDir(forward: number, lateral: number): void;
-    setForce(force: number): void;
-    jump(): void;
-    /**
-     * 0 is keyboard, 1 is joystick
-     * @default 0
-     */
-    mode: 0 | 1;
-}
 export declare class InputSystemModule extends ContextModule<{
     keyschanged: [];
+    keydown: [event: KeyboardEvent];
+    keyup: [event: KeyboardEvent];
 }> implements InputModuleApi {
     private _dom;
     private readonly _keys;
@@ -57,7 +29,15 @@ export declare class InputSystemModule extends ContextModule<{
     get ctrlKey(): boolean;
     get metaKey(): boolean;
     isKeyDown: (key: string) => boolean;
-    readonly player: PlayerInput;
+    private _captureKeyboard;
+    /**
+     * The game listens to the keyboard on the whole document, not just the canvas
+     * (otherwise any HTML over the world would swallow input). `false` hands the
+     * keyboard entirely to the UI: the game sees no keys and held ones are reset.
+     * @default true
+     */
+    get captureKeyboard(): boolean;
+    set captureKeyboard(value: boolean);
     onAwake(): void;
     /** three-start `ContextModule` has no `onDestroy`; teardown is explicit. */
     dispose(): void;
@@ -66,6 +46,9 @@ export declare class InputSystemModule extends ContextModule<{
     private onDomResize;
     private onFocus;
     private onBlur;
+    private onDocumentFocusIn;
+    /** The key belongs to the game, not to the UI. */
+    private acceptsKey;
     private onKeyDown;
     private onKeyUp;
     private onPointerEnter;
@@ -84,4 +67,3 @@ export declare class InputSystemModule extends ContextModule<{
     private recalculatePointerNdc;
     private updateDomBoundingClientRect;
 }
-export {};

package/dist/modules/chat/ChatDom.d.ts

@@ -0,0 +1,100 @@
+import type { ChatMessage } from "../contracts/chat.module-api";
+export interface ChatDomOptions {
+    /** The sent text (already non-empty and trimmed). */
+    onSubmit?: (text: string) => void;
+    onFocusChange?: (focused: boolean) => void;
+    placeholder?: string;
+    maxLength?: number;
+    /**
+     * Keep focus in the input after sending. On mobile — yes (otherwise the
+     * keyboard closes after every message), on desktop usually not: control goes
+     * back to the game.
+     */
+    keepFocusAfterSubmit?: boolean;
+    /** Where focus goes after sending or Escape (usually the canvas). */
+    returnFocusTo?: HTMLElement | null;
+    /**
+     * Hide the input while it is not focused (`toggle` mode): the chat stays out of
+     * the way and opens on Enter. `false` keeps the input always visible.
+     */
+    hideWhenIdle?: boolean;
+    /** How many recent lines stay visible while the chat is closed. */
+    visibleLines?: number;
+    /** How many lines are visible while the input is focused. */
+    openedLines?: number;
+    /** Ms before a line fades out; `0` keeps lines lit. */
+    fadeAfter?: number;
+}
+/**
+ * Chat DOM: the message feed plus the input field.
+ *
+ * Built to survive real devices: submit through a `<form>` (Enter/Go/Send on any
+ * mobile keyboard), an IME composition guard, and lifting above the on-screen
+ * keyboard via `visualViewport`. Details —
+ * `./README.md`.
+ */
+export declare class ChatDom {
+    readonly root: HTMLDivElement;
+    readonly feed: HTMLDivElement;
+    readonly form: HTMLFormElement;
+    readonly input: HTMLInputElement;
+    private readonly _options;
+    private _lines;
+    private _isComposing;
+    private _viewportRaf;
+    private _mounted;
+    constructor(options?: ChatDomOptions);
+    /** The focus policy is only known at runtime (mobile/desktop, canvas). */
+    setFocusPolicy(policy: Pick<ChatDomOptions, "keepFocusAfterSubmit" | "returnFocusTo">): void;
+    get isMounted(): boolean;
+    /** Whether to hide the input while unfocused (`toggle` mode). */
+    setHideWhenIdle(hide: boolean): void;
+    get isFocused(): boolean;
+    get value(): string;
+    set value(next: string);
+    /**
+     * Syncs the feed with the history: new lines are appended at the bottom, lines
+     * gone from the history are removed, extra ones are cut from the top. There is
+     * no scrolling — what does not fit is not shown.
+     */
+    renderMessages(messages: readonly ChatMessage[]): void;
+    mount(container: HTMLElement): void;
+    unmount(): void;
+    focus(): void;
+    blur(): void;
+    clear(): void;
+    dispose(): void;
+    /** Keep in the DOM as much as an opened chat could need. */
+    private get _maxLines();
+    private _createLine;
+    private _removeLine;
+    /**
+     * While the input is focused more lines are shown, including expired ones (an
+     * opened chat is meant to be read). Once closed, every line lives by its own
+     * deadline again: expired ones fade at once, the rest sit out their remainder.
+     */
+    private _syncLines;
+    private _setFaded;
+    private _bind;
+    private _unbind;
+    private readonly _onSubmit;
+    private readonly _onCompositionStart;
+    private readonly _onCompositionEnd;
+    /** Some Android keyboards send no Enter keydown, only `insertLineBreak`. */
+    private readonly _onBeforeInput;
+    private readonly _onKeyDown;
+    private readonly _stopPropagation;
+    private readonly _onFocus;
+    private readonly _onBlur;
+    /** In `toggle` mode a hidden input must catch neither clicks nor tab focus. */
+    private _syncVisibility;
+    private readonly _onViewportChange;
+    /**
+     * The keyboard changes the layout viewport neither on iOS nor (by default) on
+     * Android — anything fixed to the bottom ends up underneath it. We measure the
+     * overlap through `visualViewport` and lift the chat by that much.
+     */
+    private _syncKeyboardInset;
+    /** Styles are inlined once per document: the package ships no separate css file. */
+    private static _ensureStyles;
+}

package/dist/modules/chat/ChatModule.d.ts

@@ -0,0 +1,36 @@
+import { ContextModule } from "three-start";
+import { ChatDom } from "./ChatDom";
+import type { NormalizedChat } from "./chat.module-descriptor";
+import type { ChatEvents, ChatMessage, ChatModuleApi } from "../contracts/chat.module-api";
+/**
+ * The world chat as a pluggable ctx module: message history plus its own DOM
+ * input (`dom`), no React. Enabled from `settings.addons.json → modules`; it
+ * mounts its DOM itself. Details and mobile quirks — `./README.md`.
+ */
+export declare class ChatModule extends ContextModule<ChatEvents> implements ChatModuleApi {
+    readonly dom: ChatDom;
+    private readonly _maxMessages;
+    private readonly _openKeys;
+    private _messages;
+    private _seq;
+    constructor(config: NormalizedChat);
+    get messages(): readonly ChatMessage[];
+    onAwake(): void;
+    /** Print a line into the feed as is. */
+    print(text: string): void;
+    /**
+     * Send a line the way a player does: commands are handled here, everything else
+     * goes out as `sent`. It prints nothing by itself — what to show is up to the world.
+     */
+    send(text: string): void;
+    /** Redraw the whole feed — animation frames, tables, ASCII art. */
+    setMessages(texts: readonly string[]): void;
+    clear(): void;
+    private _emitChanged;
+    private _createMessage;
+    /** three-start ContextModule has no onDestroy; teardown is explicit. */
+    dispose(): void;
+    private readonly _onKeyDown;
+    private readonly _onMount;
+    private readonly _onUnmount;
+}

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

@@ -0,0 +1,43 @@
+import type { OptionalModuleDescriptor } from "../optional-module-descriptor";
+/**
+ * How the input behaves:
+ * - `always` — always visible (the classic game chat at the bottom);
+ * - `toggle` — hidden, opens on Enter and hides again on Escape or after sending.
+ */
+export type ChatInputMode = "always" | "toggle";
+/** `modules.chat`: off | input mode | an object with options. */
+export type ChatConfig = boolean | ChatInputMode | {
+    input?: ChatInputMode;
+    /** Max message length. */
+    maxLength?: number;
+    placeholder?: string;
+    /** How many messages the history keeps. */
+    maxMessages?: number;
+    /**
+     * Keys that open the chat — `KeyboardEvent.code`, i.e. physical keys:
+     * the player's layout does not matter.
+     */
+    openKeys?: string[];
+    /** How many recent lines stay visible while the chat is closed. */
+    visibleLines?: number;
+    /** How many lines are visible while the input is focused. */
+    openedLines?: number;
+    /** Ms before a line fades out; `0` keeps lines lit. */
+    fadeAfter?: number;
+};
+export interface NormalizedChat {
+    input: ChatInputMode;
+    maxLength: number;
+    placeholder: string;
+    maxMessages: number;
+    openKeys: readonly string[];
+    visibleLines: number;
+    openedLines: number;
+    fadeAfter: number;
+}
+/** `Slash` opens the chat with a "/" already typed — the Minecraft command gesture. */
+export declare const CHAT_COMMAND_KEY = "Slash";
+export declare const CHAT_INPUT_MODES: readonly ChatInputMode[];
+/** Chat defaults live here: `true` = an always visible input with a limit of 80. */
+export declare function normalizeChat(value: ChatConfig | undefined): NormalizedChat | null;
+export declare const chatModuleDescriptor: OptionalModuleDescriptor<NormalizedChat>;

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

@@ -0,0 +1,15 @@
+import type RAPIER from "@dimforge/rapier3d-compat";
+/**
+ * Public API of the `addons` module — external dependencies of the world:
+ * built-in libs and external scripts enabled in `settings.addons.json`, loaded
+ * before the world starts.
+ *
+ * Scripts normally reach a lib by `require("<key>")`; this module is the same
+ * bag behind that call, plus the physics engine.
+ */
+export interface AddonsModuleApi {
+    /** Value by require key (a lib) or by accessor (an external); null if absent. */
+    resolve: (key: string) => unknown;
+    /** The physics engine — loaded and initialized; null in worlds without physics. */
+    readonly rapier: typeof RAPIER | null;
+}

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

@@ -0,0 +1,52 @@
+import type { ModuleEvents } from "./module-events";
+/** A message in the chat history. */
+export interface ChatMessage {
+    id: string;
+    text: string;
+    /** `Date.now()` when the message was added. */
+    timestamp: number;
+}
+export type ChatEvents = {
+    /** The feed changed — printed, replaced or cleared. Render your own view here. */
+    changed: [messages: ChatMessage[]];
+    /** A line was sent (by the player or `send()`); commands never reach here. */
+    sent: [text: string];
+    /** The input gained or lost focus. */
+    inputfocuschanged: [focused: boolean];
+};
+/** Chat DOM — for advanced cases: place, focus or read the input yourself. */
+export interface ChatDomApi {
+    readonly root: HTMLDivElement;
+    /** Feed element — style it or place your own nodes next to the lines. */
+    readonly feed: HTMLDivElement;
+    readonly input: HTMLInputElement;
+    readonly isMounted: boolean;
+    readonly isFocused: boolean;
+    value: string;
+    mount: (container: HTMLElement) => void;
+    unmount: () => void;
+    focus: () => void;
+    blur: () => void;
+    clear: () => void;
+}
+/**
+ * Public API of the `chat` module — world chat: the feed + its own input.
+ *
+ * Sending and printing are separate on purpose: a sent line only fires `sent`,
+ * and nothing shows up until the world prints it.
+ *
+ * ```ts
+ * chat.on("sent", (text) => chat.print(`Player: ${text}`));
+ * ```
+ */
+export interface ChatModuleApi extends ModuleEvents<ChatEvents> {
+    readonly messages: readonly ChatMessage[];
+    /** Print a line into the feed as is. */
+    print: (text: string) => void;
+    /** Send a line as the player would: runs commands, otherwise fires `sent`. */
+    send: (text: string) => void;
+    /** Replace the whole feed at once — for redraws (frames, tables, ASCII art). */
+    setMessages: (texts: readonly string[]) => void;
+    clear: () => void;
+    readonly dom: ChatDomApi;
+}

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

@@ -0,0 +1,58 @@
+import type { ModuleEvents } from "./module-events";
+import type * as THREE from "three/webgpu";
+/** Device kind a driver reports; any string works, these are the built-in ones. */
+export type ControlsSource = "keyboard" | "touch" | "gamepad" | (string & {});
+/** Frame state a driver fills in. Reused across frames — never store it. */
+export interface ControlsState {
+    /** x — strafe, y — forward, -1..1. Write in place: `move.set(x, y)`. */
+    readonly move: THREE.Vector2;
+    /** Deflection: 1 is a normal walk, higher means a stronger stick tilt. */
+    force: number;
+    /** Run modifier — shift, a stick pushed past its ring, a UI button. */
+    run: boolean;
+    /** Held this frame; `controls` fires `jump` on the rising edge. */
+    jump: boolean;
+}
+/**
+ * An input source for `controls`: keyboard, an on-screen stick, a gamepad, the
+ * network, a cutscene. Register with `controls.addDriver(...)` — `read` is then
+ * called once per frame, before behaviours update.
+ *
+ * ```ts
+ * controls.addDriver({ kind: "touch", read: (s) => { s.move.set(x, y); s.force = f; } });
+ * ```
+ */
+export interface ControlsDriver {
+    /** Reported as `controls.source` while this driver is the one driving. */
+    readonly kind: ControlsSource;
+    read: (state: ControlsState) => void;
+}
+export type ControlsEvents = {
+    /** Movement vector changed (the same reused `move` instance). */
+    movechanged: [move: THREE.Vector2];
+    forcechanged: [force: number];
+    /** The driving device changed — the player switched keys ↔ stick. */
+    sourcechanged: [source: ControlsSource];
+    jump: [];
+};
+/**
+ * Public API of the `controls` module — the player's movement intent, whatever
+ * the device is. Input sources register as drivers, character controllers read
+ * `move`/`force`/`run`; raw device state lives in the `input` module.
+ */
+export interface ControlsModuleApi extends ModuleEvents<ControlsEvents> {
+    /** x — strafe, y — forward. Reused vector: copy it before storing. */
+    readonly move: THREE.Vector2;
+    readonly force: number;
+    readonly run: boolean;
+    /** Kind of the driver currently driving. */
+    readonly source: ControlsSource;
+    readonly drivers: readonly ControlsDriver[];
+    /** Built-in WASD/arrows driver, registered on start; remove it to take over. */
+    readonly keyboard: ControlsDriver;
+    /** Registers a driver and returns the unsubscribe. */
+    addDriver: (driver: ControlsDriver) => () => void;
+    removeDriver: (driver: ControlsDriver) => void;
+    /** Fire a jump by hand — a UI button, a script. */
+    jump: () => void;
+}

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

@@ -1,7 +1,15 @@
-/** Public API of the `html` module — fullscreen HTML HUD on top of the canvas. */
+/**
+ * Public API of the `html` module — fullscreen HTML HUD on top of the canvas.
+ *
+ * The root is `pointer-events: none` on purpose: the HUD covers the whole screen
+ * and must not swallow clicks meant for the world. Anything interactive you
+ * append has to set `pointer-events: auto` on itself.
+ */
 export interface HtmlModuleApi {
+    /** HUD container over the canvas; click-through (`pointer-events: none`). */
     readonly root: HTMLDivElement;
     readonly crosshair: HTMLDivElement;
+    /** Appends nodes into the click-through root — see the note above. */
     append: (...nodes: Array<Node | string>) => void;
     setCrosshair: (innerHtml: string) => void;
 }

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

@@ -1,3 +1,4 @@
+import type { ModuleEvents } from "./module-events";
 import type * as THREE from "three/webgpu";
 /**
  * Public API of the input module, available in user scripts
@@ -7,7 +8,13 @@ import type * as THREE from "three/webgpu";
  * if the class stops matching the contract, the project won't compile.
  * This same file is fed into Monaco (see `monaco/monaco-lib-types.ts`).
  */
-export interface InputModuleApi {
+export type InputEvents = {
+    /** Set of pressed keys changed. */
+    keyschanged: [];
+    keydown: [event: KeyboardEvent];
+    keyup: [event: KeyboardEvent];
+};
+export interface InputModuleApi extends ModuleEvents<InputEvents> {
     readonly pointerDeltaX: number;
     readonly pointerDeltaY: number;
     readonly isDragging: boolean;
@@ -18,14 +25,7 @@ export interface InputModuleApi {
     readonly ctrlKey: boolean;
     readonly metaKey: boolean;
     isKeyDown: (key: string) => boolean;
-    readonly player: PlayerInputApi;
-}
-/** Player's virtual gamepad stick (`input.player`). */
-export interface PlayerInputApi {
-    readonly forward: number;
-    readonly lateral: number;
-    readonly force: number;
-    setDir: (forward: number, lateral: number) => void;
-    setForce: (force: number) => void;
-    jump: () => void;
+    /** Game reads the keyboard; `false` hands it over to the world's own UI.
+     * @default true */
+    captureKeyboard: boolean;
 }

package/dist/modules/contracts/module-events.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Typed events every module inherits from the engine.
+ *
+ * ```ts
+ * world.ctx.modules.chat.on("sent", (text) => { ... });
+ * ```
+ *
+ * Not a module contract — a shared piece the `*.module-api.ts` files extend.
+ */
+export interface ModuleEvents<TEvents extends Record<string, unknown[]>> {
+    /** Subscribe. */
+    on: <TKey extends keyof TEvents & string>(event: TKey, fn: (...args: TEvents[TKey]) => void) => this;
+    /** Subscribe until the first call. */
+    once: <TKey extends keyof TEvents & string>(event: TKey, fn: (...args: TEvents[TKey]) => void) => this;
+    /** Unsubscribe; without `fn` removes every listener of the event. */
+    off: <TKey extends keyof TEvents & string>(event: TKey, fn?: (...args: TEvents[TKey]) => void) => this;
+}

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

@@ -1,11 +1,23 @@
+import type { ModuleEvents } from "./module-events";
 import type RAPIER from "@dimforge/rapier3d-compat";
 export type RapierJsModule = typeof RAPIER;
 /** Public API of the `rapier` module — Rapier physics world, event queue, simulation step. */
-export interface RapierModuleApi {
+export type RapierEvents = {
+    /** Right before the physics world steps. */
+    stepbefore: [];
+    /** Right after the step — transforms are already updated. */
+    stepafter: [];
+};
+export interface RapierModuleApi extends ModuleEvents<RapierEvents> {
     readonly isRapierPhysics: true;
     readonly api: RapierJsModule;
     readonly world: RAPIER.World;
     readonly eventQueue: RAPIER.EventQueue;
     /** @default "vary" */
     timeStep: number | "vary";
+    /** Collider debug rendering is on right now. */
+    readonly isDebugEnabled: boolean;
+    /** Turn collider debug rendering on; the renderer is fetched on demand. */
+    enableDebug: () => Promise<void>;
+    disableDebug: () => void;
 }

package/dist/modules/controls/ControlsModule.d.ts

@@ -0,0 +1,45 @@
+import { ContextModule } from "three-start";
+import * as THREE from "three/webgpu";
+import type { ControlsDriver, ControlsEvents, ControlsModuleApi, ControlsSource } from "../contracts/controls.module-api";
+/**
+ * The player's movement intent — what they want to do, whatever the hardware is.
+ * Input sources register as drivers (`addDriver`); the module polls them once a
+ * frame and decides which one is driving. Details — `./README.md`.
+ */
+export declare class ControlsModule extends ContextModule<ControlsEvents> implements ControlsModuleApi {
+    /** x — strafe, y — forward. Reused vector: copy it before storing. */
+    readonly move: THREE.Vector2;
+    private readonly _drivers;
+    private readonly _state;
+    private _keyboard;
+    private _active;
+    private _source;
+    private _force;
+    private _run;
+    private _jump;
+    onAwake(): void;
+    /** Speed multiplier: 1 is a normal walk, higher means a stronger stick tilt. */
+    get force(): number;
+    /** Run modifier: shift, a stick pushed past its ring, a UI button. */
+    get run(): boolean;
+    /** Kind of the device driving right now. */
+    get source(): ControlsSource;
+    get drivers(): readonly ControlsDriver[];
+    /** The built-in keyboard driver — detach it with `removeDriver`. */
+    get keyboard(): ControlsDriver;
+    addDriver(driver: ControlsDriver): () => void;
+    removeDriver(driver: ControlsDriver): void;
+    jump(): void;
+    onUpdate(): void;
+    /**
+     * The active driver keeps the channel while it produces input — otherwise the
+     * keyboard and a stick would steal control from each other every frame. Once it
+     * goes quiet, the first driver with input takes over. The state is left filled
+     * by the winner, so nobody is read twice.
+     */
+    private _readActiveDriver;
+    private _readDriver;
+    private _resetState;
+    private _apply;
+}
+export default ControlsModule;

package/dist/modules/controls/KeyboardControlsDriver.d.ts

@@ -0,0 +1,12 @@
+import type { InputSystemModule } from "../InputSystemModule";
+import type { ControlsDriver, ControlsState } from "../contracts/controls.module-api";
+/**
+ * Keyboard driver for `controls`: WASD/arrows, shift to run, Space to jump.
+ * Reads key state from the `input` module and binds no listeners of its own.
+ */
+export declare class KeyboardControlsDriver implements ControlsDriver {
+    private readonly _input;
+    readonly kind = "keyboard";
+    constructor(_input: InputSystemModule);
+    read(state: ControlsState): void;
+}

package/dist/modules/index.d.ts

@@ -1,9 +1,16 @@
+import { ControlsModule } from "./controls/ControlsModule";
 import { EnvModule } from "./EnvModule";
 import { HtmlHudModule } from "./HtmlHudModule";
 import { InputSystemModule } from "./InputSystemModule";
 import { SoundsModule } from "./SoundsModule";
 import { UtilsModule } from "./UtilsModule";
+import type { AddonsRuntime } from "../addons/AddonsRuntime";
+import type { AddonsConfig } from "../addons/types";
 import type { EnvMode } from "./EnvModule";
+import type { KvyverseModules } from "./registry";
+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";
@@ -11,12 +18,32 @@ export { SoundsModule } from "./SoundsModule";
 export { UtilsModule } from "./UtilsModule";
 export { isMobileDevice } from "./is-mobile-device";
 export type { EnvMode } from "./EnvModule";
-export type WorldModules = {
+/** Modules every world has — no toggle for them. */
+export type CoreWorldModules = {
+    addons: AddonsRuntime;
+    controls: ControlsModule;
     env: EnvModule;
     html: HtmlHudModule;
     input: InputSystemModule;
     sounds: SoundsModule;
     utils: UtilsModule;
 };
-/** World ctx modules. Registered before `start()` — three-start forbids it later. */
-export declare function createWorldModules(mode?: EnvMode): WorldModules;
+/** @deprecated kept for compatibility; see `CoreWorldModules`. */
+export type WorldModules = CoreWorldModules;
+export interface CreateWorldModulesOptions {
+    /** The world's external dependencies, already loaded (libs, externals, rapier). */
+    addons: AddonsRuntime;
+    /** `settings.addons.json → modules`: which pluggable modules are on, and how. */
+    modules?: AddonsConfig["modules"];
+}
+/**
+ * Assembles the world's ctx modules: core ones always, pluggable ones per config.
+ * Pluggable classes are pulled dynamically, so a disabled module never reaches
+ * the bundle. Call strictly before `start()` and with addons already loaded: the
+ * physics module takes rapier from `ctx.modules.addons`.
+ *
+ * A module the scene needs without a line in the config (physics when a physics
+ * behaviour is present) is added separately — through the behaviour's
+ * `meta.requiredPatch`, with the same descriptor and idempotently.
+ */
+export declare function createWorldModules(mode: EnvMode | undefined, options: CreateWorldModulesOptions): Promise<CoreWorldModules & Partial<KvyverseModules>>;

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

@@ -0,0 +1,36 @@
+import type { ContextModule } from "three-start";
+/**
+ * Keys of the pluggable modules — the same keys as in
+ * `settings.addons.json → modules`. Core modules (`addons`/`env`/`html`/`input`/
+ * `controls`/`sounds`/`utils`) are not here: every world has them, with no toggle.
+ */
+export declare enum OptionalModuleId {
+    Physics = "physics",
+    Chat = "chat"
+}
+export declare const OPTIONAL_MODULE_IDS: OptionalModuleId[];
+/** A JSON Schema (draft-07) fragment; structurally the platform's `JSONSchema`. */
+export type ModuleJsonSchema = Record<string, unknown>;
+/**
+ * Describes a pluggable module: how to read its value from the world config, how
+ * to create it and how to validate the config in the code editor. Defaults (is
+ * it on, in which mode) live in `normalize` — the registry knows nothing of them.
+ *
+ * Rule: `create` pulls the module class through a **dynamic** import, otherwise a
+ * disabled module still ends up in the bundle.
+ */
+export interface OptionalModuleDescriptor<TConfig = unknown> {
+    id: OptionalModuleId;
+    /** 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). */
+    defaultConfig: () => TConfig;
+    /** The module class is pulled here — a disabled module never reaches the bundle. */
+    create: (config: TConfig) => Promise<ContextModule>;
+    /**
+     * JSON Schema fragment for `modules.<id>`: the platform assembles the
+     * `settings.addons.json` schema from these, so module keys never drift from the
+     * registry. The type is deliberately wide — the package knows nothing of Monaco.
+     */
+    schema: ModuleJsonSchema;
+}

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

@@ -0,0 +1,11 @@
+import type { OptionalModuleDescriptor, OptionalModuleId } from "./optional-module-descriptor";
+/**
+ * Table of contents for the world's pluggable modules: what can be enabled from
+ * `settings.addons.json → modules`. The descriptors themselves live next to
+ * their module code; this is only the list.
+ *
+ * Add a descriptor here and the module shows up both in the runtime and in the
+ * config's JSON schema (the platform builds it from `descriptor.schema`).
+ */
+export declare const OPTIONAL_MODULES: ReadonlyArray<OptionalModuleDescriptor<any>>;
+export declare function getOptionalModuleDescriptor(id: OptionalModuleId): OptionalModuleDescriptor<any>;

package/dist/modules/physics/RapierDebugRenderer.d.ts

@@ -0,0 +1,19 @@
+import type { RapierPhysics } from "./RapierPhysics";
+import type { ThreeContext } from "three-start";
+/**
+ * Draws rapier colliders as lines. Not a ctx module: it lives inside
+ * `RapierPhysics` (`enableDebug`/`disableDebug`) and is pulled dynamically —
+ * worlds without debug never load this code.
+ *
+ * @see {@link https://github.com/vladkrutenyuk/three-kvy-core/blob/main/src/addons/RapierDebugRenderer.ts | Source}
+ */
+export declare class RapierDebugRenderer {
+    private readonly _ctx;
+    private readonly _rapier;
+    private _clear;
+    constructor(ctx: ThreeContext, rapier: RapierPhysics);
+    get enabled(): boolean;
+    start(): void;
+    stop(): void;
+}
+export default RapierDebugRenderer;