@kvyverse/world-runtime 0.1.0 → 0.4.2

package/dist/lib-registry-D1VyVPBg.js

@@ -0,0 +1,142 @@
+//#region packages/world-runtime/src/addons/lib-registry.ts
+/**
+* Registry of the libraries scripts can `require`. One entry describes one
+* library; the flags say how it gets into the world:
+*
+* - **built-in** (`builtin: true`) — the runtime already bundles it, so it is
+*   available in every world with no config and no importer. Some of them are
+*   additionally exposed as a bare global (`globalName`) — that is the only
+*   difference between `THREE` and, say, `nanostores`.
+* - **optional** — enabled in `settings.addons.json → libs`, or pulled in by
+*   something that declares it in `requiredLibs` (physics → rapier). The
+*   importer comes from the runtime owner (`WorldImports`), never from the
+*   package itself — see `./optional-imports.ts`.
+*
+* `id` is the config key under `libs`, `requireKey` is what the user writes in
+* `require(...)` (and the import specifier importers are built from). Single
+* source for: the app's importer map, the `imports.libs` block of an exported
+* world, the JSON schema and the editor's require typings.
+*/
+var LibId = /* @__PURE__ */ function(LibId) {
+	LibId["Three"] = "three";
+	LibId["Tsl"] = "tsl";
+	LibId["ThreeStart"] = "threeStart";
+	LibId["Van"] = "van";
+	LibId["Nanostores"] = "nanostores";
+	LibId["EventEmitter"] = "eventemitter3";
+	LibId["Howler"] = "howler";
+	LibId["Tween"] = "tween";
+	LibId["Anime"] = "anime";
+	LibId["Nipplejs"] = "nipplejs";
+	LibId["Stats"] = "stats";
+	LibId["Rapier"] = "rapier";
+	LibId["Css2d"] = "css2d";
+	LibId["Css3d"] = "css3d";
+	return LibId;
+}({});
+var LIBS = {
+	["three"]: {
+		id: "three",
+		requireKey: "three",
+		label: "three.js (WebGPU build)",
+		builtin: true,
+		globalName: "THREE"
+	},
+	["tsl"]: {
+		id: "tsl",
+		requireKey: "three/tsl",
+		packageName: "three",
+		label: "Three Shading Language",
+		builtin: true,
+		globalName: "TSL"
+	},
+	["threeStart"]: {
+		id: "threeStart",
+		requireKey: "three-start",
+		label: "three-start (engine core)",
+		builtin: true
+	},
+	["van"]: {
+		id: "van",
+		requireKey: "vanjs-core",
+		label: "VanJS (HTML UI)",
+		builtin: true,
+		globalName: "van",
+		defaultExport: true
+	},
+	["nanostores"]: {
+		id: "nanostores",
+		requireKey: "nanostores",
+		label: "nanostores (atoms behind world.stores)",
+		builtin: true
+	},
+	["eventemitter3"]: {
+		id: "eventemitter3",
+		requireKey: "eventemitter3",
+		label: "EventEmitter3",
+		builtin: true,
+		defaultExport: true
+	},
+	["howler"]: {
+		id: "howler",
+		requireKey: "howler",
+		label: "howler.js (audio)",
+		builtin: true
+	},
+	["tween"]: {
+		id: "tween",
+		requireKey: "@tweenjs/tween.js",
+		label: "Tween.js"
+	},
+	["anime"]: {
+		id: "anime",
+		requireKey: "animejs/animation",
+		packageName: "animejs",
+		label: "Anime.js (animate)"
+	},
+	["nipplejs"]: {
+		id: "nipplejs",
+		requireKey: "nipplejs",
+		label: "nipplejs (on-screen joystick)",
+		defaultExport: true
+	},
+	["stats"]: {
+		id: "stats",
+		requireKey: "stats.js",
+		label: "Stats.js (fps overlay)",
+		defaultExport: true
+	},
+	["rapier"]: {
+		id: "rapier",
+		requireKey: "@dimforge/rapier3d-compat",
+		label: "Rapier (physics engine)",
+		init: async (module) => {
+			await module.init();
+			return module;
+		}
+	},
+	["css2d"]: {
+		id: "css2d",
+		requireKey: "three/addons/renderers/CSS2DRenderer.js",
+		packageName: "three",
+		label: "CSS2DRenderer (DOM labels at 3d positions)"
+	},
+	["css3d"]: {
+		id: "css3d",
+		requireKey: "three/addons/renderers/CSS3DRenderer.js",
+		packageName: "three",
+		label: "CSS3DRenderer (DOM elements in 3d)"
+	}
+};
+var LIB_IDS = Object.values(LibId);
+var LIB_DESCRIPTORS = LIB_IDS.map((id) => LIBS[id]);
+/** Bundled with the runtime — available in every world. */
+var BUILTIN_LIB_DESCRIPTORS = LIB_DESCRIPTORS.filter((lib) => lib.builtin);
+/** Enabled in `settings.addons.json → libs` or required by a module/behaviour. */
+var OPTIONAL_LIB_DESCRIPTORS = LIB_DESCRIPTORS.filter((lib) => !lib.builtin);
+var OPTIONAL_LIB_IDS = OPTIONAL_LIB_DESCRIPTORS.map((lib) => lib.id);
+function libByRequireKey(requireKey) {
+	return LIB_DESCRIPTORS.find((l) => l.requireKey === requireKey);
+}
+//#endregion
+export { LibId as a, libByRequireKey as c, LIB_IDS as i, LIBS as n, OPTIONAL_LIB_DESCRIPTORS as o, LIB_DESCRIPTORS as r, OPTIONAL_LIB_IDS as s, BUILTIN_LIB_DESCRIPTORS as t };

package/dist/modules/HtmlHudModule.d.ts

@@ -1,11 +1,15 @@
 import { ContextModule } from "three-start";
 import type { HtmlModuleApi } from "./contracts/html.module-api";
 export declare class HtmlHudModule extends ContextModule implements HtmlModuleApi {
-    readonly root: HTMLDivElement;
+    readonly overlay: HTMLDivElement;
+    readonly underlay: HTMLDivElement;
     readonly crosshair: HTMLDivElement;
     constructor();
     onAwake(): void;
+    /** Appends nodes over the canvas (the HUD). */
     append(...nodes: Array<Node | string>): void;
+    /** Appends nodes under the canvas — visible only through a transparent canvas. */
+    appendUnderlay(...nodes: Array<Node | string>): void;
     setCrosshair(innerHtml: string): void;
     /** three-start ContextModule has no onDestroy; teardown is explicit. */
     dispose(): void;

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 { LibId } from "../../addons/lib-registry";
+/**
+ * Public API of the `addons` module — the world's libraries and external
+ * scripts: built-in ones, those enabled in `settings.addons.json` and those
+ * required by an enabled module or a behaviour on the scene.
+ *
+ * Scripts normally reach a lib by `require("<key>")`; this module is the same
+ * bag behind that call.
+ */
+export interface AddonsModuleApi {
+    /** Value by require key (a lib) or by accessor (an external); undefined if absent. */
+    resolve: (key: string) => unknown;
+    /** The lib by its registry id — for runtime code that knows what it needs. */
+    lib: <T>(id: LibId) => T | undefined;
+}

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,27 @@
-/** Public API of the `html` module — fullscreen HTML HUD on top of the canvas. */
+/**
+ * Public API of the `html` module — two fullscreen DOM layers around the canvas:
+ * the HUD above it (`overlay`) and the underlay below it (`underlay`).
+ *
+ * Both are `pointer-events: none` on purpose: they cover the whole screen and
+ * must not swallow clicks meant for the world. Anything interactive appended to
+ * the HUD has to set `pointer-events: auto` on itself; the underlay can never
+ * be clicked at all — the canvas is on top of it.
+ *
+ * The underlay is only visible through a transparent canvas, which needs all
+ * three: `renderer.alpha` in `settings.renderer.json`, an empty scene
+ * background (a background colour paints over everything), and bloom off —
+ * the bloom pass currently loses the scene alpha, see
+ * `/docs/potential-issues.md`.
+ */
 export interface HtmlModuleApi {
-    readonly root: HTMLDivElement;
+    /** HUD container over the canvas; click-through (`pointer-events: none`). */
+    readonly overlay: HTMLDivElement;
+    /** Container under the canvas — for DOM that the world should render on top of. */
+    readonly underlay: HTMLDivElement;
     readonly crosshair: HTMLDivElement;
+    /** Appends nodes over the canvas — see the note above. */
     append: (...nodes: Array<Node | string>) => void;
+    /** Appends nodes under the canvas — see the note above. */
+    appendUnderlay: (...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;
 }