@kvyverse/world-runtime 0.1.0 → 0.4.2

package/dist/RapierDebugRenderer-BQy_m-3C.js

@@ -0,0 +1,73 @@
+import * as THREE from "three/webgpu";
+//#region packages/world-runtime/src/modules/physics/RapierDebugRenderer.ts
+/**
+* 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}
+*/
+var RapierDebugRenderer = class {
+	_ctx;
+	_rapier;
+	_clear = null;
+	constructor(ctx, rapier) {
+		this._ctx = ctx;
+		this._rapier = rapier;
+	}
+	get enabled() {
+		return !!this._clear;
+	}
+	start() {
+		if (this._clear) return;
+		const geometry = new THREE.BufferGeometry();
+		const lines = new THREE.LineSegments(geometry, new THREE.LineBasicMaterial({
+			vertexColors: true,
+			toneMapped: false
+		}));
+		lines.frustumCulled = false;
+		lines.renderOrder = Number.MAX_SAFE_INTEGER;
+		this._ctx.scene.add(lines);
+		let positionAttr = null;
+		let colorAttr = null;
+		const rapier = this._rapier;
+		const draw = () => {
+			const { vertices, colors } = rapier.world.debugRender();
+			const vertexCount = vertices.length / 3;
+			if (!positionAttr || positionAttr.array.length < vertices.length) {
+				positionAttr = new THREE.BufferAttribute(new Float32Array(vertices.length), 3);
+				positionAttr.setUsage(THREE.DynamicDrawUsage);
+				geometry.setAttribute("position", positionAttr);
+				colorAttr = new THREE.BufferAttribute(new Float32Array(vertexCount * 3), 3);
+				colorAttr.setUsage(THREE.DynamicDrawUsage);
+				geometry.setAttribute("color", colorAttr);
+			}
+			const positions = positionAttr.array;
+			const colorValues = colorAttr.array;
+			positions.set(vertices);
+			for (let i = 0; i < vertexCount; i++) {
+				colorValues[i * 3] = colors[i * 4] ?? 1;
+				colorValues[i * 3 + 1] = colors[i * 4 + 1] ?? 1;
+				colorValues[i * 3 + 2] = colors[i * 4 + 2] ?? 1;
+			}
+			positionAttr.needsUpdate = true;
+			colorAttr.needsUpdate = true;
+			geometry.setDrawRange(0, vertexCount);
+		};
+		rapier.on("stepafter", draw);
+		this._clear = () => {
+			rapier.off("stepafter", draw);
+			lines.removeFromParent();
+			geometry.dispose();
+			lines.material.dispose();
+			positionAttr = null;
+			colorAttr = null;
+			this._clear = null;
+		};
+	}
+	stop() {
+		this._clear?.();
+	}
+};
+//#endregion
+export { RapierDebugRenderer, RapierDebugRenderer as default };

package/dist/{RapierFpsPlayerController-VsNfQl6v.js → RapierFpsPlayerController-DthD8dw9.js}

@@ -61,29 +61,12 @@ var RapierFpsPlayerController = class extends Object3DBehaviour {
 		const kcc = this.kcc;
 		const col = this.col;
 		const dt = this.getDt();
-		const input = this.modules.input;
+		const controls = this.modules.controls;
 		const dir = this._inputDir;
-		dir.setScalar(0);
-		const playerInput = input.player;
-		let speed = this.walkSpeed;
-		switch (playerInput.mode) {
-			case 0: {
-				const keys = input.isKeyDown;
-				if (keys("KeyW") || keys("ArrowUp")) dir.z -= 1;
-				if (keys("KeyS") || keys("ArrowDown")) dir.z += 1;
-				if (keys("KeyA") || keys("ArrowLeft")) dir.x -= 1;
-				if (keys("KeyD") || keys("ArrowRight")) dir.x += 1;
-				if (this.useShiftRun && input.shiftKey) speed = this.runSpeed;
-				break;
-			}
-			case 1: {
-				const { forward, lateral, force } = input.player;
-				dir.z -= forward;
-				dir.x += lateral;
-				speed = force > 2 ? THREE.MathUtils.lerp(this.walkSpeed, this.runSpeed, THREE.MathUtils.clamp(force - 2, 0, 1.5)) : this.walkSpeed;
-				break;
-			}
-		}
+		dir.set(controls.move.x, 0, -controls.move.y);
+		const analog = THREE.MathUtils.clamp(controls.force - 2, 0, 1);
+		const running = this.useShiftRun && controls.run;
+		const speed = THREE.MathUtils.lerp(this.walkSpeed, this.runSpeed, running ? 1 : analog);
 		dir.normalize();
 		const camera = this.ctx.camera;
 		if (dir.lengthSq() > 0) {

package/dist/{RapierPhysics-C_3b7QOn.js → RapierPhysics-CU6X--c7.js}

@@ -1,10 +1,6 @@
-import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { a as LibId } from "./lib-registry-D1VyVPBg.js";
 import { ContextModule, ThreeContextEvents, defineProps, readOnly } from "three-start";
-//#region packages/world-runtime/src/behaviours/physics/rapier-addon-core/RapierPhysics.ts
-var RapierPhysics_exports = /* @__PURE__ */ __exportAll({
-	RapierPhysics: () => RapierPhysics,
-	default: () => RapierPhysics
-});
+//#region packages/world-runtime/src/modules/physics/RapierPhysics.ts
 var RapierPhysics = class RapierPhysics extends ContextModule {
 	isRapierPhysics;
 	api;
@@ -13,24 +9,33 @@ var RapierPhysics = class RapierPhysics extends ContextModule {
 	/** @default "vary" */
 	timeStep;
 	_steppingState = { accumulator: 0 };
-	constructor(Rapier, options = {}) {
+	_debug = null;
+	_debugOnStart;
+	_gravity;
+	constructor(options = {}) {
 		super();
 		const { timeStep = "vary", gravity = [
 			0,
 			-9.81,
 			0
-		] } = options;
-		const world = new Rapier.World({
-			x: gravity[0],
-			y: gravity[1],
-			z: gravity[2]
-		});
+		], debug = false } = options;
+		this._debugOnStart = debug;
+		this._gravity = gravity;
 		this.timeStep = timeStep;
+	}
+	onAwake() {
+		const Rapier = this.modules.addons.lib(LibId.Rapier);
+		if (!Rapier) throw new Error("RapierPhysics: the physics engine is not loaded — `addons` has no rapier");
+		const [x, y, z] = this._gravity;
 		console.log(`Rapier version: ${Rapier.version()}`);
 		defineProps(this, {
 			isRapierPhysics: readOnly(true),
 			api: readOnly(Rapier),
-			world: readOnly(world),
+			world: readOnly(new Rapier.World({
+				x,
+				y,
+				z
+			})),
 			eventQueue: readOnly(new Rapier.EventQueue(false))
 		});
 	}
@@ -40,10 +45,24 @@ var RapierPhysics = class RapierPhysics extends ContextModule {
 				this.ctx.on(ThreeContextEvents.RenderBefore, this.update);
 			});
 		});
+		if (this._debugOnStart) this.enableDebug();
+	}
+	/** Whether collider outlines are being drawn right now. */
+	get isDebugEnabled() {
+		return !!this._debug?.enabled;
+	}
+	/** Turn on collider debug drawing; the renderer is fetched on demand. */
+	async enableDebug() {
+		this._debug ??= new (await (import("./RapierDebugRenderer-BQy_m-3C.js"))).RapierDebugRenderer(this.ctx, this);
+		this._debug.start();
+	}
+	disableDebug() {
+		this._debug?.stop();
 	}
 	/** three-start ContextModule has no onDestroy; teardown is explicit. */
 	dispose() {
 		this.ctx.off(ThreeContextEvents.RenderBefore, this.update);
+		this.disableDebug();
 	}
 	update = () => {
 		const steppingState = this._steppingState;
@@ -71,4 +90,4 @@ var RapierPhysics = class RapierPhysics extends ContextModule {
 	}
 };
 //#endregion
-export { RapierPhysics_exports as n, RapierPhysics as t };
+export { RapierPhysics, RapierPhysics as default };

package/dist/{Rigidbody-b7QNF4ev.js → Rigidbody-DLhN8ddv.js}

@@ -1,6 +1,17 @@
-import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import * as THREE from "three/webgpu";
 import { Object3DBehaviour, assertDefined, defineProps, readOnly } from "three-start";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
 //#region packages/world-runtime/src/behaviours/physics/Rigidbody.ts
 var Rigidbody_exports = /* @__PURE__ */ __exportAll({ default: () => Rigidbody });
 /**

package/dist/World.d.ts

@@ -10,10 +10,12 @@ import type { WorldRuntime } from "./WorldRuntime";
 export declare class World extends ThreeStart {
     private readonly _runtime;
     constructor(options: ThreeStartOptions, _runtime: WorldRuntime);
-    /** Asset URL by project path — same resolving as `getUrl` in scripts. */
-    getUrl: (path: string) => string;
+    /** Asset URL by project path or resource — same resolving as `getUrl` in scripts. */
+    getUrl: (source: string | object) => string;
     /** World lifecycle event bus — the same one as `world.events` in scripts. */
     get events(): WorldRuntime["emitter"];
+    /** Shared reactive state — the same one as `world.stores` in scripts. */
+    get stores(): WorldRuntime["stores"];
     start(): this;
     dispose(): void;
 }

package/dist/WorldRuntime.d.ts

@@ -1,10 +1,12 @@
 import EventEmitter from "eventemitter3";
-import * as THREE from "three/webgpu";
+import { AddonsRuntime } from "./addons/AddonsRuntime";
+import { WorldStores } from "./world-stores";
+import type * as THREE from "three/webgpu";
 import type { Object3DBehaviourConstructor, ThreeContext, ThreeStart } from "three-start";
 import type { SceneBloom } from "./rendering/SceneBloom";
 import type { LoadWorldOptions, RuntimeApi, WorldDefinition } from "./types";
 /** Slice of the world definition the runtime needs: independent of the asset bag type. */
-export type RuntimeDefinitionSlice = Pick<WorldDefinition, "assets" | "scripts" | "entryScript" | "styles" | "fontPaths" | "usedBuiltins" | "addons">;
+export type RuntimeDefinitionSlice = Pick<WorldDefinition, "assets" | "scripts" | "entryScript" | "styles" | "fontPaths" | "usedBuiltins" | "addons" | "imports">;
 /**
  * Owner of the world's runtime state: assets, script execution, ctx access.
  * The only object the generated code receives.
@@ -14,27 +16,34 @@ export declare class WorldRuntime implements RuntimeApi {
     readonly options: LoadWorldOptions;
     /** World lifecycle event bus (`world.events` in scripts). */
     readonly emitter: EventEmitter<string | symbol, any>;
+    /** Shared reactive state of the world (`world.stores` in scripts). */
+    readonly stores: WorldStores;
     private readonly _addons;
     private readonly _executedScripts;
     private readonly _builtins;
     private readonly _styleElements;
     private _resources;
+    /** Reverse index for `getUrl(resource)` — play mode resolves objects too. */
+    private readonly _pathByResource;
     private _ctx;
     private _bloom;
     private _scriptContext;
     constructor(definition: RuntimeDefinitionSlice, options: LoadWorldOptions);
+    /** The world's external dependencies; also the `addons` ctx module. */
+    get addons(): AddonsRuntime;
     /** ctx appears at the 3d-context creation step; unavailable to scripts before that. */
     get ctx(): ThreeContext;
     /** @internal Set by bootstrap. */
     setContext(ctx: ThreeContext): void;
     /** @internal World bloom, if enabled in the renderer config. */
     setBloom(bloom: SceneBloom): void;
-    /** @internal Built-in libs and external scripts from `settings.addons.json`. */
+    /** @internal Libs (config + required by modules/behaviours) and externals. */
     loadAddons(): Promise<void>;
     /** @internal World resources by asset path — result of `loadAssets`. */
     setResources(resources: Record<string, unknown>): void;
     reportProgress(stage: string, details?: string): void;
-    getUrl: (path: string) => string;
+    /** Accepts an asset path or a resource returned by `require` — like play mode. */
+    getUrl: (source: string | object) => string;
     /**
      * Built-in behaviour class by uuid. Classes are preloaded by bootstrap,
      * so attaching in `buildScene` is synchronous.
@@ -52,7 +61,8 @@ export declare class WorldRuntime implements RuntimeApi {
     require: (key: string) => unknown;
     /**
      * Runtime spawn: a prefab (build-time factory) is assembled anew, a regular
-     * object is cloned. Returns a detached object — the caller adds it.
+     * object is cloned. The instance is only created and returned — adding it to
+     * the scene hierarchy is up to the caller (`ctx.scene.add(obj)`).
      */
     instantiate: (source: THREE.Object3D | PrefabFactory, options?: InstantiateOptions) => THREE.Object3D;
     /** Runs a script once and caches its `output`. The cache entry is set before

package/dist/addons/AddonsRuntime.d.ts

@@ -0,0 +1,37 @@
+import { ContextModule } from "three-start";
+import type { AddonsModuleApi } from "../modules/contracts/addons.module-api";
+import type { LibId } from "./lib-registry";
+import type { AddonsConfig, WorldImports } from "./types";
+/**
+ * External dependencies of the world: libs and external scripts. Built-in libs
+ * are registered right away (the runtime bundles them), optional ones are loaded
+ * before the world starts — enabled in `settings.addons.json → libs` or declared
+ * by a module/behaviour through `requiredLibs`. Scripts reach all of them by
+ * `require("<key>")`.
+ *
+ * This is the `addons` ctx module, but it also works without a ctx: launcher
+ * worlds have no 3d context while `require` still has to work, so there the
+ * instance is used directly. How to import optional packages is up to the
+ * runtime owner (see `WorldImports`).
+ */
+export declare class AddonsRuntime extends ContextModule implements AddonsModuleApi {
+    private readonly _imports;
+    /** libs — by requireKey (`@tweenjs/tween.js`), externals — by accessor (`Tone`). */
+    private readonly _byKey;
+    private readonly _byLibId;
+    private readonly _scriptTags;
+    constructor(_imports?: WorldImports);
+    /** `usedBuiltinUuids` — built-in behaviours on the scene; they may require libs. */
+    load(addons: AddonsConfig, usedBuiltinUuids?: readonly string[]): Promise<void>;
+    /** Resolves a require key: a lib or an external accessor; undefined otherwise. */
+    resolve(key: string): unknown;
+    /** The lib itself, for runtime code that knows what it needs (physics → rapier). */
+    lib<T>(id: LibId): T | undefined;
+    /** Libs bundled with the runtime: no importer, no config, always available. */
+    private _registerBuiltins;
+    private _loadLibs;
+    private _register;
+    private _loadExternals;
+    private _mountScript;
+    dispose(): void;
+}

package/dist/addons/builtin-libs.d.ts

@@ -0,0 +1,20 @@
+import * as THREE from "three/webgpu";
+import * as TSL from "three/tsl";
+import { LibId } from "./lib-registry";
+/**
+ * Libraries the runtime bundles itself: `require("<key>")` hands these back in
+ * every world, no config and no importer involved. Metadata (keys, labels) is
+ * in `lib-registry`; the modules live here so the registry stays importable
+ * from the editor without dragging three & co along.
+ */
+export declare const BUILTIN_LIB_MODULES: Partial<Record<LibId, unknown>>;
+/**
+ * The subset of built-ins that is also a bare global in script scope — same
+ * objects as above, so `THREE === require("three")`. Typed literally: the
+ * script context contract depends on these exact shapes.
+ */
+export declare const BUILTIN_GLOBALS: {
+    readonly THREE: typeof THREE;
+    readonly TSL: typeof TSL;
+    readonly van: import("vanjs-core").Van;
+};

package/dist/addons/lib-registry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+export declare enum LibId {
+    Three = "three",
+    Tsl = "tsl",
+    ThreeStart = "threeStart",
+    Van = "van",
+    Nanostores = "nanostores",
+    EventEmitter = "eventemitter3",
+    Howler = "howler",
+    Tween = "tween",
+    Anime = "anime",
+    Nipplejs = "nipplejs",
+    Stats = "stats",
+    Rapier = "rapier",
+    Css2d = "css2d",
+    Css3d = "css3d"
+}
+export interface LibDescriptor {
+    readonly id: LibId;
+    /** Key the user gets the lib by: `require("<requireKey>")`. It is also the
+     *  import specifier — importers are generated from it. */
+    readonly requireKey: string;
+    readonly label: string;
+    /** npm package to install; defaults to `requireKey` (differs for subpaths). */
+    readonly packageName?: string;
+    /** Bundled with the runtime: always available, no importer, nothing to install. */
+    readonly builtin?: boolean;
+    /** Built-in libs that are also bare globals in script scope. */
+    readonly globalName?: string;
+    /** The package exposes its API as the default export — unwrap it on load. */
+    readonly defaultExport?: boolean;
+    /** Post-import step, e.g. wasm init. Returns what `require` should hand back. */
+    readonly init?: (module: unknown) => Promise<unknown>;
+}
+export declare const LIBS: Readonly<Record<LibId, LibDescriptor>>;
+export declare const LIB_IDS: LibId[];
+export declare const LIB_DESCRIPTORS: LibDescriptor[];
+/** Bundled with the runtime — available in every world. */
+export declare const BUILTIN_LIB_DESCRIPTORS: LibDescriptor[];
+/** Enabled in `settings.addons.json → libs` or required by a module/behaviour. */
+export declare const OPTIONAL_LIB_DESCRIPTORS: LibDescriptor[];
+export declare const OPTIONAL_LIB_IDS: LibId[];
+export declare function libByRequireKey(requireKey: string): LibDescriptor | undefined;

package/dist/addons/required-libs.d.ts

@@ -0,0 +1,9 @@
+import type { LibId } from "./lib-registry";
+import type { AddonsConfig } from "./types";
+/**
+ * Libs the world needs beyond what `libs` lists: an enabled module or a built-in
+ * behaviour on the scene declares them itself (`requiredLibs`), so physics keeps
+ * working without a line in `settings.addons.json`. Same answer for the game and
+ * for the export — the build emits importers from it.
+ */
+export declare function collectRequiredLibs(addons: AddonsConfig | undefined, usedBuiltinUuids?: readonly string[]): LibId[];

package/dist/addons/types.d.ts

@@ -0,0 +1,28 @@
+import type { ExternalDescriptor } from "./externals";
+import type { LibId } from "./lib-registry";
+import type { ChatConfig } from "../modules/chat/chat.module-descriptor";
+import type { PhysicsConfig } from "../modules/physics/physics.module-descriptor";
+/** How to import an optional npm package. */
+export type PackageImport = () => Promise<unknown>;
+/**
+ * Importers of the world's optional packages. The runtime never spells them out
+ * itself: a literal `import("nipplejs")` in its dist would force the host
+ * project's bundler to resolve a package that may not be installed. The runtime
+ * owner supplies them — the platform on game start, an exported world through
+ * `imports` in `defineWorld`.
+ */
+export interface WorldImports {
+    /** Optional libs by `LibId` — enabled in `settings.addons.json → libs` or
+     *  required by a module/behaviour (physics → rapier). Built-in libs are
+     *  bundled with the runtime and need no importer. */
+    libs?: Partial<Record<LibId, PackageImport>>;
+}
+/** `settings.addons.json` — pluggable modules, built-in libs, external scripts. */
+export interface AddonsConfig {
+    modules?: {
+        physics?: PhysicsConfig;
+        chat?: ChatConfig;
+    };
+    libs?: Partial<Record<LibId, boolean>>;
+    externals?: ExternalDescriptor[];
+}

package/dist/behaviours/physics/BallCollider.d.ts

@@ -1,4 +1,4 @@
-import { Collider } from "./rapier-addon-core/Collider";
+import { Collider } from "./Collider";
 import type * as RAPIER from "@dimforge/rapier3d-compat";
 export default class BallCollider extends Collider {
     readonly type = "Ball";

package/dist/behaviours/physics/CapsuleCollider.d.ts

@@ -1,4 +1,4 @@
-import { Collider } from "./rapier-addon-core/Collider";
+import { Collider } from "./Collider";
 import type * as RAPIER from "@dimforge/rapier3d-compat";
 export default class CapsuleCollider extends Collider {
     readonly type = "Capsule";

package/dist/behaviours/physics/ConeCollider.d.ts

@@ -1,4 +1,4 @@
-import { Collider } from "./rapier-addon-core/Collider";
+import { Collider } from "./Collider";
 import type * as RAPIER from "@dimforge/rapier3d-compat";
 export default class ConeCollider extends Collider {
     readonly type = "Cone";

package/dist/behaviours/physics/ConvexMeshCollider.d.ts

@@ -1,4 +1,4 @@
-import { Collider } from "./rapier-addon-core/Collider";
+import { Collider } from "./Collider";
 import type * as RAPIER from "@dimforge/rapier3d-compat";
 export default class ConvexMeshCollider extends Collider {
     readonly type = "Convex";

package/dist/behaviours/physics/CuboidCollider.d.ts

@@ -1,4 +1,4 @@
-import { Collider } from "./rapier-addon-core/Collider";
+import { Collider } from "./Collider";
 import type * as RAPIER from "@dimforge/rapier3d-compat";
 export default class CuboidCollider extends Collider {
     readonly type = "Cuboid";

package/dist/behaviours/physics/CylinderCollider.d.ts

@@ -1,4 +1,4 @@
-import { Collider } from "./rapier-addon-core/Collider";
+import { Collider } from "./Collider";
 import type * as RAPIER from "@dimforge/rapier3d-compat";
 export default class CylinderCollider extends Collider {
     readonly type = "Cylinder";

package/dist/behaviours/physics/HalfspaceCollider.d.ts

@@ -1,4 +1,4 @@
-import { Collider } from "./rapier-addon-core/Collider";
+import { Collider } from "./Collider";
 import type * as RAPIER from "@dimforge/rapier3d-compat";
 export default class HalfspaceCollider extends Collider {
     readonly type = "Halfspace";

package/dist/behaviours/physics/_required-patch.d.ts

@@ -1,10 +1,12 @@
-import type { ThreeStart } from "three-start";
-/** rapier loads lazily: the wasm is pulled only in worlds with physics. */
-export declare const lazyRapier: {
-    get: () => Promise<typeof import("@dimforge/rapier3d-compat")>;
-};
+import type { RequiredPatch } from "../registry";
+import type { RapierPhysics } from "../../modules/physics/RapierPhysics";
+import type { NormalizedPhysics } from "../../modules/physics/physics.module-descriptor";
+/** The only place the physics module is created — called by the registry
+ *  descriptor. The module itself takes rapier from `ctx.modules.addons` on awake. */
+export declare function createRapierPhysicsModule(config: NormalizedPhysics): Promise<RapierPhysics>;
 /**
- * Registers rapier modules before bootstrap: three-start forbids `addModules`
- * after `start()`. Idempotent — a repeated call sees the module in ctx and exits.
+ * What a physics behaviour needs on top of its class: the rapier lib (loaded
+ * with the other addons, before the world starts) and the physics ctx module.
+ * A collider on the scene is enough — no line in `settings.addons.json`.
  */
-export declare function applyRapierPhysicsPatch(starter: ThreeStart): Promise<void>;
+export declare const rapierPhysicsPatch: RequiredPatch;

package/dist/behaviours/registry.d.ts

@@ -1,4 +1,5 @@
 import type { Object3DBehaviourConstructor, ThreeStart } from "three-start";
+import type { LibId } from "../addons/lib-registry";
 /**
  * Built-in behaviour: uuid is its identity in user worlds — it must never
  * change. The class loads lazily, so a world without physics doesn't pull rapier.
@@ -7,8 +8,14 @@ export interface BuiltinBehaviour {
     uuid: string;
     name: string;
     load: () => Promise<Object3DBehaviourConstructor>;
-    /** Registers ctx modules the behaviour needs. Strictly before `start()`. */
-    requiredPatch?: (starter: ThreeStart) => Promise<void>;
+    /** ctx modules (and their libs) the behaviour cannot work without. */
+    requiredPatch?: RequiredPatch;
+}
+/** What a behaviour needs beyond its own class: libs to load before the world
+ *  starts, and ctx modules to register strictly before `start()`. */
+export interface RequiredPatch {
+    requiredLibs?: LibId[];
+    apply: (starter: ThreeStart) => Promise<void>;
 }
 /** Registry of built-in behaviours by uuid — source of truth for both game and export. */
 export declare const BUILTIN_BEHAVIOURS: Record<string, BuiltinBehaviour | undefined>;

package/dist/chat.module-descriptor-BTsep-Kq.js

@@ -0,0 +1,107 @@
+//#region packages/world-runtime/src/modules/optional-module-descriptor.ts
+/**
+* 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.
+*/
+var OptionalModuleId = /* @__PURE__ */ function(OptionalModuleId) {
+	OptionalModuleId["Physics"] = "physics";
+	OptionalModuleId["Chat"] = "chat";
+	return OptionalModuleId;
+}({});
+var OPTIONAL_MODULE_IDS = Object.values(OptionalModuleId);
+//#endregion
+//#region packages/world-runtime/src/modules/chat/chat.module-descriptor.ts
+/** `Slash` opens the chat with a "/" already typed — the Minecraft command gesture. */
+var CHAT_COMMAND_KEY = "Slash";
+var CHAT_INPUT_MODES = ["always", "toggle"];
+var DEFAULTS = {
+	input: "always",
+	maxLength: 80,
+	placeholder: "Chat",
+	maxMessages: 150,
+	openKeys: ["Enter", "KeyT"],
+	visibleLines: 10,
+	openedLines: 20,
+	fadeAfter: 1e4
+};
+/** Chat defaults live here: `true` = an always visible input with a limit of 80. */
+function normalizeChat(value) {
+	if (!value) return null;
+	if (value === true) return { ...DEFAULTS };
+	if (typeof value === "string") return {
+		...DEFAULTS,
+		input: value
+	};
+	return {
+		input: value.input ?? DEFAULTS.input,
+		maxLength: value.maxLength ?? DEFAULTS.maxLength,
+		placeholder: value.placeholder ?? DEFAULTS.placeholder,
+		maxMessages: value.maxMessages ?? DEFAULTS.maxMessages,
+		openKeys: value.openKeys ?? DEFAULTS.openKeys,
+		visibleLines: value.visibleLines ?? DEFAULTS.visibleLines,
+		openedLines: value.openedLines ?? DEFAULTS.openedLines,
+		fadeAfter: value.fadeAfter ?? DEFAULTS.fadeAfter
+	};
+}
+var chatModuleDescriptor = {
+	id: OptionalModuleId.Chat,
+	normalize: (raw) => normalizeChat(raw),
+	defaultConfig: () => ({ ...DEFAULTS }),
+	create: async (config) => {
+		const { ChatModule } = await import("./ChatModule-2tiWS_Yr.js");
+		return new ChatModule(config);
+	},
+	schema: {
+		description: "World chat. false | \"always\" | \"toggle\" | { input, maxLength, placeholder, maxMessages }.",
+		oneOf: [
+			{ type: "boolean" },
+			{
+				type: "string",
+				enum: [...CHAT_INPUT_MODES]
+			},
+			{
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					input: {
+						type: "string",
+						enum: [...CHAT_INPUT_MODES],
+						description: "always — the input is always visible; toggle — hidden until Enter, hides again on Escape or after sending."
+					},
+					maxLength: {
+						type: "number",
+						description: "Max message length (default 80)."
+					},
+					placeholder: {
+						type: "string",
+						description: "Input placeholder."
+					},
+					maxMessages: {
+						type: "number",
+						description: "How many messages to keep in history (default 150)."
+					},
+					openKeys: {
+						type: "array",
+						items: { type: "string" },
+						description: "Keys that open the chat — KeyboardEvent.code, layout-independent (default [\"Enter\", \"KeyT\"]). \"Slash\" always opens it with a \"/\" typed in."
+					},
+					visibleLines: {
+						type: "number",
+						description: "Lines shown while the chat is closed (default 10)."
+					},
+					openedLines: {
+						type: "number",
+						description: "Lines shown while the input is focused (default 20)."
+					},
+					fadeAfter: {
+						type: "number",
+						description: "Ms before a line fades out; 0 keeps lines until they are pushed out (default 10000)."
+					}
+				}
+			}
+		]
+	}
+};
+//#endregion
+export { OPTIONAL_MODULE_IDS as a, normalizeChat as i, CHAT_INPUT_MODES as n, OptionalModuleId as o, chatModuleDescriptor as r, CHAT_COMMAND_KEY as t };