@kvyverse/world-runtime 0.1.0 → 0.4.2

package/dist/index.js

@@ -1,5 +1,6 @@
-import { t as RapierPhysics } from "./RapierPhysics-C_3b7QOn.js";
-import { n as getRadiusScale, t as getHalfheightRadiusScale } from "./get-scale-from-obj-QKv3Fig5.js";
+import { a as OPTIONAL_MODULE_IDS, i as normalizeChat, n as CHAT_INPUT_MODES, o as OptionalModuleId, r as chatModuleDescriptor } from "./chat.module-descriptor-BTsep-Kq.js";
+import { a as LibId, c as libByRequireKey, i as LIB_IDS, n as LIBS, o as OPTIONAL_LIB_DESCRIPTORS, r as LIB_DESCRIPTORS, s as OPTIONAL_LIB_IDS, t as BUILTIN_LIB_DESCRIPTORS } from "./lib-registry-D1VyVPBg.js";
+import { n as getRadiusScale, t as getHalfheightRadiusScale } from "./get-scale-from-obj-B7JlVPni.js";
 import * as THREE from "three/webgpu";
 import { BufferGeometryLoader, LoadingManager, TextureLoader } from "three/webgpu";
 import * as ThreeStartNS from "three-start";
@@ -7,10 +8,13 @@ import { ContextModule, ThreeContextEvents, ThreeStart } from "three-start";
 import * as TSL from "three/tsl";
 import { emissive, mrt, output } from "three/tsl";
 import van from "vanjs-core";
-import EventEmitter from "eventemitter3";
+import * as howler from "howler";
 import { Howl, Howler } from "howler";
 import { mergeGeometries } from "three/examples/jsm/utils/BufferGeometryUtils.js";
 import { clone } from "three/examples/jsm/utils/SkeletonUtils.js";
+import EventEmitter from "eventemitter3";
+import * as nanostores from "nanostores";
+import { atom } from "nanostores";
 //#region packages/world-runtime/src/world-events.ts
 /**
 * World lifecycle events, emitted on `game.emitter` (`world.events` in scripts)
@@ -40,12 +44,16 @@ var World = class extends ThreeStart {
 		super(options);
 		this._runtime = _runtime;
 	}
-	/** Asset URL by project path — same resolving as `getUrl` in scripts. */
-	getUrl = (path) => this._runtime.getUrl(path);
+	/** Asset URL by project path or resource — same resolving as `getUrl` in scripts. */
+	getUrl = (source) => this._runtime.getUrl(source);
 	/** World lifecycle event bus — the same one as `world.events` in scripts. */
 	get events() {
 		return this._runtime.emitter;
 	}
+	/** Shared reactive state — the same one as `world.stores` in scripts. */
+	get stores() {
+		return this._runtime.stores;
+	}
 	start() {
 		const wasStarted = this.isStarted;
 		super.start();
@@ -59,6 +67,26 @@ var World = class extends ThreeStart {
 };
 //#endregion
 //#region packages/world-runtime/src/utils/lazy.ts
+/**
+* Object that forwards every access to `resolve()`. For script globals that are
+* shortcuts into something created later (`modules` → `ctx.modules`): the script
+* bag is destructured eagerly, so a plain reference or a getter would be read
+* before the target exists.
+*/
+function lazyProxy(resolve) {
+	return new Proxy({}, {
+		get: (_target, key) => Reflect.get(resolve(), key),
+		has: (_target, key) => Reflect.has(resolve(), key),
+		ownKeys: () => Reflect.ownKeys(resolve()),
+		getOwnPropertyDescriptor: (_target, key) => {
+			const descriptor = Reflect.getOwnPropertyDescriptor(resolve(), key);
+			return descriptor && {
+				...descriptor,
+				configurable: true
+			};
+		}
+	});
+}
 /** Lazy cached value: the factory is called once on the first `get()`. */
 function lazy(factory) {
 	let has = false;
@@ -268,6 +296,248 @@ function finiteOr(value, fallback) {
 	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
 //#endregion
+//#region packages/world-runtime/src/modules/controls/KeyboardControlsDriver.ts
+/** A diagonal must not be faster than a straight line. */
+var DIAGONAL = Math.SQRT1_2;
+/**
+* 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.
+*/
+var KeyboardControlsDriver = class {
+	_input;
+	kind = "keyboard";
+	constructor(_input) {
+		this._input = _input;
+	}
+	read(state) {
+		const key = this._input.isKeyDown;
+		let x = 0;
+		let y = 0;
+		if (key("KeyW") || key("ArrowUp")) y += 1;
+		if (key("KeyS") || key("ArrowDown")) y -= 1;
+		if (key("KeyD") || key("ArrowRight")) x += 1;
+		if (key("KeyA") || key("ArrowLeft")) x -= 1;
+		if (x !== 0 && y !== 0) {
+			x *= DIAGONAL;
+			y *= DIAGONAL;
+		}
+		state.move.set(x, y);
+		state.force = x !== 0 || y !== 0 ? 1 : 0;
+		state.run = this._input.shiftKey;
+		state.jump = key("Space");
+	}
+};
+//#endregion
+//#region packages/world-runtime/src/modules/controls/ControlsModule.ts
+/**
+* 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`.
+*/
+var ControlsModule = class extends ContextModule {
+	/** x — strafe, y — forward. Reused vector: copy it before storing. */
+	move = new THREE.Vector2();
+	_drivers = [];
+	_state = {
+		move: new THREE.Vector2(),
+		force: 0,
+		run: false,
+		jump: false
+	};
+	_keyboard = null;
+	_active = null;
+	_source = "keyboard";
+	_force = 0;
+	_run = false;
+	_jump = false;
+	onAwake() {
+		this._keyboard = new KeyboardControlsDriver(this.modules.input);
+		this.addDriver(this._keyboard);
+	}
+	/** Speed multiplier: 1 is a normal walk, higher means a stronger stick tilt. */
+	get force() {
+		return this._force;
+	}
+	/** Run modifier: shift, a stick pushed past its ring, a UI button. */
+	get run() {
+		return this._run;
+	}
+	/** Kind of the device driving right now. */
+	get source() {
+		return this._source;
+	}
+	get drivers() {
+		return this._drivers;
+	}
+	/** The built-in keyboard driver — detach it with `removeDriver`. */
+	get keyboard() {
+		if (!this._keyboard) throw new Error("controls: keyboard driver is not ready yet");
+		return this._keyboard;
+	}
+	addDriver(driver) {
+		if (!this._drivers.includes(driver)) this._drivers.push(driver);
+		return () => this.removeDriver(driver);
+	}
+	removeDriver(driver) {
+		const index = this._drivers.indexOf(driver);
+		if (index < 0) return;
+		this._drivers.splice(index, 1);
+		if (this._active === driver) this._active = null;
+	}
+	jump() {
+		this.emit("jump");
+	}
+	onUpdate() {
+		const driver = this._readActiveDriver();
+		this._apply(driver);
+	}
+	/**
+	* 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.
+	*/
+	_readActiveDriver() {
+		if (this._active && this._readDriver(this._active)) return this._active;
+		for (const driver of this._drivers) {
+			if (driver === this._active) continue;
+			if (this._readDriver(driver)) return driver;
+		}
+		this._resetState();
+		return null;
+	}
+	_readDriver(driver) {
+		this._resetState();
+		driver.read(this._state);
+		const { move, force, jump } = this._state;
+		return move.x !== 0 || move.y !== 0 || force > 0 || jump;
+	}
+	_resetState() {
+		const state = this._state;
+		state.move.set(0, 0);
+		state.force = 0;
+		state.run = false;
+		state.jump = false;
+	}
+	_apply(driver) {
+		const state = this._state;
+		this._active = driver ?? this._active;
+		const source = this._active?.kind ?? this._source;
+		if (source !== this._source) {
+			this._source = source;
+			this.emit("sourcechanged", source);
+		}
+		if (!this.move.equals(state.move)) {
+			this.move.copy(state.move);
+			this.emit("movechanged", this.move);
+		}
+		if (this._force !== state.force) {
+			this._force = state.force;
+			this.emit("forcechanged", state.force);
+		}
+		this._run = state.run;
+		if (state.jump && !this._jump) this.jump();
+		this._jump = state.jump;
+	}
+};
+//#endregion
+//#region packages/world-runtime/src/behaviours/physics/_required-patch.ts
+var lazyRapierPhysicsModule = lazy(async () => (await import("./RapierPhysics-CU6X--c7.js")).default);
+/** The only place the physics module is created — called by the registry
+*  descriptor. The module itself takes rapier from `ctx.modules.addons` on awake. */
+async function createRapierPhysicsModule(config) {
+	return new (await (lazyRapierPhysicsModule.get()))({ debug: config.debug });
+}
+/**
+* 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`.
+*/
+var rapierPhysicsPatch = {
+	requiredLibs: [LibId.Rapier],
+	apply: (starter) => applyRapierPhysicsPatch(starter)
+};
+/**
+* Registers the physics module. Idempotent, and strictly before `start()` —
+* three-start forbids `addModules` afterwards.
+*/
+async function applyRapierPhysicsPatch(starter) {
+	if (starter.ctx.modules.rapier) return;
+	const descriptor = physicsModuleDescriptor;
+	const module = await descriptor.create(descriptor.defaultConfig());
+	starter.addModules({ rapier: module });
+}
+//#endregion
+//#region packages/world-runtime/src/modules/physics/physics.module-descriptor.ts
+var PHYSICS_ENGINES = ["rapier"];
+/** Physics defaults: the rapier engine, debug off. */
+function normalizePhysics(value) {
+	if (!value) return null;
+	if (typeof value === "string") return {
+		engine: value,
+		debug: false
+	};
+	return {
+		engine: value.engine,
+		debug: value.debug ?? false
+	};
+}
+var physicsModuleDescriptor = {
+	id: OptionalModuleId.Physics,
+	normalize: (raw) => normalizePhysics(raw),
+	defaultConfig: () => ({
+		engine: "rapier",
+		debug: false
+	}),
+	create: (config) => createRapierPhysicsModule(config),
+	requiredLibs: [LibId.Rapier],
+	schema: {
+		description: "Physics engine module. false | \"rapier\" | { engine, debug }.",
+		oneOf: [
+			{
+				type: "boolean",
+				enum: [false]
+			},
+			{
+				type: "string",
+				enum: [...PHYSICS_ENGINES]
+			},
+			{
+				type: "object",
+				additionalProperties: false,
+				required: ["engine"],
+				properties: {
+					engine: {
+						type: "string",
+						enum: [...PHYSICS_ENGINES]
+					},
+					debug: {
+						type: "boolean",
+						description: "Draw collider debug lines from the start (the renderer is loaded on demand)."
+					}
+				}
+			}
+		]
+	}
+};
+//#endregion
+//#region packages/world-runtime/src/modules/optional-modules.ts
+/**
+* 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`).
+*/
+var OPTIONAL_MODULES = [physicsModuleDescriptor, chatModuleDescriptor];
+var DESCRIPTOR_BY_ID = new Map(OPTIONAL_MODULES.map((m) => [m.id, m]));
+function getOptionalModuleDescriptor(id) {
+	const descriptor = DESCRIPTOR_BY_ID.get(id);
+	if (!descriptor) throw new Error(`Unknown world module "${id}"`);
+	return descriptor;
+}
+//#endregion
 //#region packages/world-runtime/src/modules/is-mobile-device.ts
 function isMobileDevice() {
 	if (typeof navigator === "undefined" || typeof window === "undefined") return false;
@@ -296,19 +566,25 @@ var EnvModule = class extends ContextModule {
 //#endregion
 //#region packages/world-runtime/src/modules/HtmlHudModule.ts
 var { div } = van.tags;
+var LAYER_STYLE = "position:fixed;inset:0;pointer-events:none;";
 var HtmlHudModule = class extends ContextModule {
-	root;
+	overlay;
+	underlay;
 	crosshair;
 	constructor() {
 		super();
 		this.crosshair = div({
-			id: "kvyverse-game-gui-crosshair",
+			id: "kvy-crosshair",
 			style: "position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);"
 		});
-		this.root = div({
-			id: "kvyverse-game-gui-root",
-			style: "position:fixed;inset:0;pointer-events:none;"
+		this.overlay = div({
+			id: "kvy-overlay",
+			style: LAYER_STYLE
 		}, this.crosshair);
+		this.underlay = div({
+			id: "kvy-underlay",
+			style: LAYER_STYLE
+		});
 	}
 	onAwake() {
 		const ctx = this.ctx;
@@ -316,8 +592,13 @@ var HtmlHudModule = class extends ContextModule {
 		ctx.on(ThreeContextEvents.Mount, this.onMount);
 		ctx.on(ThreeContextEvents.Unmount, this.onUnmount);
 	}
+	/** Appends nodes over the canvas (the HUD). */
 	append(...nodes) {
-		this.root.append(...nodes);
+		this.overlay.append(...nodes);
+	}
+	/** Appends nodes under the canvas — visible only through a transparent canvas. */
+	appendUnderlay(...nodes) {
+		this.underlay.append(...nodes);
 	}
 	setCrosshair(innerHtml) {
 		this.crosshair.innerHTML = innerHtml;
@@ -328,54 +609,18 @@ var HtmlHudModule = class extends ContextModule {
 		this.ctx.off(ThreeContextEvents.Unmount, this.onUnmount);
 	}
 	onMount = (container) => {
-		container.append(this.root);
+		container.prepend(this.underlay);
+		container.append(this.overlay);
+		const canvas = this.ctx.renderer.domElement;
+		if (!canvas.style.position) canvas.style.position = "relative";
 	};
 	onUnmount = () => {
-		this.root.remove();
+		this.overlay.remove();
+		this.underlay.remove();
 	};
 };
 //#endregion
 //#region packages/world-runtime/src/modules/InputSystemModule.ts
-var PlayerInput = class extends EventEmitter {
-	_forward = 0;
-	_lateral = 0;
-	_force = 1;
-	/**
-	* @default 0
-	*/
-	get forward() {
-		return this._forward;
-	}
-	/**
-	* @default 0
-	*/
-	get lateral() {
-		return this._lateral;
-	}
-	/**
-	* @default 1
-	*/
-	get force() {
-		return this._force;
-	}
-	setDir(forward, lateral) {
-		this._forward = forward;
-		this._lateral = lateral;
-		this.emit("dirchanged", forward, lateral);
-	}
-	setForce(force) {
-		this._force = force;
-		this.emit("forcechanged", force);
-	}
-	jump() {
-		this.emit("jump");
-	}
-	/**
-	* 0 is keyboard, 1 is joystick
-	* @default 0
-	*/
-	mode = 0;
-};
 var InputSystemModule = class extends ContextModule {
 	_dom;
 	_keys = /* @__PURE__ */ new Set();
@@ -421,12 +666,30 @@ var InputSystemModule = class extends ContextModule {
 	isKeyDown = (key) => {
 		return this._keys.has(key);
 	};
-	player = new PlayerInput();
+	_captureKeyboard = true;
+	/**
+	* 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() {
+		return this._captureKeyboard;
+	}
+	set captureKeyboard(value) {
+		if (this._captureKeyboard === value) return;
+		this._captureKeyboard = value;
+		if (!value) {
+			this.resetKeys();
+			this.emit("keyschanged");
+		}
+	}
 	onAwake() {
 		const ctx = this.ctx;
 		this._dom = ctx.renderer.domElement;
 		window.addEventListener("resize", this.onWindowResize);
 		window.addEventListener("scroll", this.onWindowScroll);
+		window.addEventListener("blur", this.onBlur);
 		ctx.on(ThreeContextEvents.Resized, this.onDomResize);
 		const on = this._dom.addEventListener.bind(this._dom);
 		on("focus", this.onFocus);
@@ -436,13 +699,15 @@ var InputSystemModule = class extends ContextModule {
 		on("pointermove", this.onPointerMove);
 		on("pointerup", this.onPointerUp);
 		on("pointerleave", this.onPointerLeave);
-		on("keydown", this.onKeyDown);
-		on("keyup", this.onKeyUp);
+		document.addEventListener("keydown", this.onKeyDown);
+		document.addEventListener("keyup", this.onKeyUp);
+		document.addEventListener("focusin", this.onDocumentFocusIn);
 	}
 	/** three-start `ContextModule` has no `onDestroy`; teardown is explicit. */
 	dispose() {
 		window.removeEventListener("resize", this.onWindowResize);
 		window.removeEventListener("scroll", this.onWindowScroll);
+		window.removeEventListener("blur", this.onBlur);
 		this.ctx.off(ThreeContextEvents.Resized, this.onDomResize);
 		const off = this._dom.removeEventListener.bind(this._dom);
 		off("focus", this.onFocus);
@@ -452,8 +717,9 @@ var InputSystemModule = class extends ContextModule {
 		off("pointermove", this.onPointerMove);
 		off("pointerup", this.onPointerUp);
 		off("pointerleave", this.onPointerLeave);
-		off("keydown", this.onKeyDown);
-		off("keyup", this.onKeyUp);
+		document.removeEventListener("keydown", this.onKeyDown);
+		document.removeEventListener("keyup", this.onKeyUp);
+		document.removeEventListener("focusin", this.onDocumentFocusIn);
 	}
 	onWindowResize = () => {
 		this.updateDomBoundingClientRect();
@@ -472,15 +738,28 @@ var InputSystemModule = class extends ContextModule {
 		this.resetKeys();
 		this.resetPointers();
 	};
+	onDocumentFocusIn = (event) => {
+		if (!isUiKeyboardTarget(event.target)) return;
+		this.resetKeys();
+		this.emit("keyschanged");
+	};
+	/** The key belongs to the game, not to the UI. */
+	acceptsKey(event) {
+		return this._captureKeyboard && !isUiKeyboardTarget(event.target);
+	}
 	onKeyDown = (event) => {
+		if (!this.acceptsKey(event)) return;
 		this.updFnKeys(event);
 		this._keys.add(event.code);
 		this.emit("keyschanged");
+		this.emit("keydown", event);
 	};
 	onKeyUp = (event) => {
+		if (!this.acceptsKey(event)) return;
 		this.updFnKeys(event);
 		this._keys.delete(event.code);
 		this.emit("keyschanged");
+		this.emit("keyup", event);
 	};
 	onPointerEnter = (_) => {};
 	onPointerDown = (event) => {
@@ -577,6 +856,21 @@ var InputSystemModule = class extends ContextModule {
 		return this._domBoundingClientRect;
 	}
 };
+/**
+* Focus is in a text field (or contenteditable) — the keyboard belongs to the UI
+* and the game does not see it. Engine plumbing: nobody has to think about it,
+* `isKeyDown` simply stays quiet while the player types.
+*/
+function isUiKeyboardTarget(target) {
+	if (!(target instanceof HTMLElement)) return false;
+	if (target.isContentEditable) return true;
+	switch (target.tagName) {
+		case "INPUT":
+		case "TEXTAREA":
+		case "SELECT": return true;
+		default: return false;
+	}
+}
 //#endregion
 //#region packages/world-runtime/src/modules/SoundsModule.ts
 var SoundsModule = class extends ContextModule {
@@ -599,39 +893,36 @@ var UtilsModule = class extends ContextModule {
 };
 //#endregion
 //#region packages/world-runtime/src/modules/index.ts
-/** World ctx modules. Registered before `start()` — three-start forbids it later. */
-function createWorldModules(mode = "prod") {
-	return {
+/**
+* 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.
+*/
+async function createWorldModules(mode = "prod", options) {
+	const modules = {
+		addons: options.addons,
+		controls: new ControlsModule(),
 		env: new EnvModule(mode),
 		html: new HtmlHudModule(),
 		input: new InputSystemModule(),
 		sounds: new SoundsModule(),
 		utils: new UtilsModule()
 	};
-}
-//#endregion
-//#region packages/world-runtime/src/behaviours/physics/_required-patch.ts
-/** rapier loads lazily: the wasm is pulled only in worlds with physics. */
-var lazyRapier = lazy(async () => {
-	const rapier = await import("@dimforge/rapier3d-compat");
-	await rapier.init();
-	return rapier;
-});
-var lazyRapierPhysicsModule = lazy(async () => (await import("./RapierPhysics-C_3b7QOn.js").then((n) => n.n)).default);
-var lazyRapierDebugModule = lazy(async () => (await import("./RapierDebugRenderer-sURZDLP4.js")).default);
-/**
-* Registers rapier modules before bootstrap: three-start forbids `addModules`
-* after `start()`. Idempotent — a repeated call sees the module in ctx and exits.
-*/
-async function applyRapierPhysicsPatch(starter) {
-	const RAPIER = await lazyRapier.get();
-	const RapierPhysicsModule = await lazyRapierPhysicsModule.get();
-	const RapierDebugRenderer = await lazyRapierDebugModule.get();
-	if (RapierPhysics.findInCtx(starter.ctx)) return;
-	starter.addModules({
-		rapier: new RapierPhysicsModule(RAPIER),
-		rapierDebug: new RapierDebugRenderer()
-	});
+	for (const descriptor of OPTIONAL_MODULES) {
+		const config = descriptor.normalize(options.modules?.[descriptor.id]);
+		if (!config) continue;
+		try {
+			modules[descriptor.id] = await descriptor.create(config);
+		} catch (error) {
+			console.error(`[modules] failed to create "${descriptor.id}"`, error);
+		}
+	}
+	return modules;
 }
 //#endregion
 //#region packages/world-runtime/src/behaviours/registry.ts
@@ -664,7 +955,7 @@ var entries = [
 	{
 		uuid: "fpscameracontroller",
 		name: "FpsCameraController",
-		load: () => loadDefault(import("./FpsCameraController-BE2EirRj.js"))
+		load: () => loadDefault(import("./FpsCameraController-2GNWJM5D.js"))
 	},
 	{
 		uuid: "sightinteractablearea",
@@ -679,56 +970,56 @@ var entries = [
 	{
 		uuid: "rrb",
 		name: "Rigidbody",
-		load: () => loadDefault(import("./Rigidbody-b7QNF4ev.js").then((n) => n.n)),
-		requiredPatch: applyRapierPhysicsPatch
+		load: () => loadDefault(import("./Rigidbody-DLhN8ddv.js").then((n) => n.n)),
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapierballcol",
 		name: "BallCollider",
-		load: () => loadDefault(import("./BallCollider-8ZrxReEd.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		load: () => loadDefault(import("./BallCollider-3L5vOrcL.js")),
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapiercapscol",
 		name: "CapsuleCollider",
-		load: () => loadDefault(import("./CapsuleCollider-bynyf6Mc.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		load: () => loadDefault(import("./CapsuleCollider-CBTsR-Ys.js")),
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapierconecol",
 		name: "ConeCollider",
-		load: () => loadDefault(import("./ConeCollider-DtRZmgK8.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		load: () => loadDefault(import("./ConeCollider-C3XU3Y9X.js")),
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapierconvxcol",
 		name: "ConvexMeshCollider",
-		load: () => loadDefault(import("./ConvexMeshCollider-BSmDM4o3.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		load: () => loadDefault(import("./ConvexMeshCollider-DzNV4HTO.js")),
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapiercubcol",
 		name: "CuboidCollider",
-		load: () => loadDefault(import("./CuboidCollider-CJvq7--s.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		load: () => loadDefault(import("./CuboidCollider-Dp1DZoFM.js")),
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapiercylcol",
 		name: "CylinderCollider",
-		load: () => loadDefault(import("./CylinderCollider-CQPSh4tu.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		load: () => loadDefault(import("./CylinderCollider-C0h_nhB5.js")),
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapiertricol",
 		name: "TrimeshCollider",
 		load: () => loadDefault(import("./TrimeshCollider-7dIs_xtZ.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapierfpsplayercontroller",
 		name: "RapierFpsPlayerController",
-		load: () => loadDefault(import("./RapierFpsPlayerController-VsNfQl6v.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		load: () => loadDefault(import("./RapierFpsPlayerController-DthD8dw9.js")),
+		requiredPatch: rapierPhysicsPatch
 	}
 ];
 /** Registry of built-in behaviours by uuid — source of truth for both game and export. */
@@ -803,81 +1094,124 @@ function createFont(url, family, mime, name) {
 	return source;
 }
 //#endregion
-//#region packages/world-runtime/src/settings/lib-registry.ts
+//#region packages/world-runtime/src/addons/builtin-libs.ts
 /**
-* Registry of built-in libraries enabled via `settings.addons.json → libs`.
-*
-* Separates two keys: `id` (short config key under `libs`) and `requireKey`
-* (what the user writes in `require(...)` in scripts). Single source for:
-*  - game: dynamic loading (`lib-loaders`),
-*  - editor: JSON schema (`libs` props) + require typings (`AddonsRequireTypings`).
-*
-* Adding a lib = add an entry here (+ loader in game, + d.ts loader in editor).
+* 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.
 */
-var LibId = /* @__PURE__ */ function(LibId) {
-	LibId["Tween"] = "tween";
-	LibId["Anime"] = "anime";
-	return LibId;
-}({});
-var LIBS = {
-	["tween"]: {
-		id: "tween",
-		requireKey: "@tweenjs/tween.js",
-		label: "Tween.js"
-	},
-	["anime"]: {
-		id: "anime",
-		requireKey: "animejs/animation",
-		label: "Anime.js (animate)"
-	}
+var BUILTIN_LIB_MODULES = {
+	[LibId.Three]: THREE,
+	[LibId.Tsl]: TSL,
+	[LibId.ThreeStart]: ThreeStartNS,
+	[LibId.Van]: van,
+	[LibId.Nanostores]: nanostores,
+	[LibId.EventEmitter]: EventEmitter,
+	[LibId.Howler]: howler
 };
-var LIB_IDS = Object.values(LibId);
-var LIB_DESCRIPTORS = LIB_IDS.map((id) => LIBS[id]);
-function libByRequireKey(requireKey) {
-	return LIB_DESCRIPTORS.find((l) => l.requireKey === requireKey);
-}
-//#endregion
-//#region packages/world-runtime/src/settings/lib-loaders.ts
 /**
-* Dynamic loaders of built-in libs (game-only). Key — `LibId` from the registry;
-* the value resolves for the user via `require("<requireKey>")`. Imports are lazy —
-* bundled only when the lib is enabled in `settings.addons.json`.
+* 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.
 */
-var LIB_LOADERS = {
-	[LibId.Tween]: () => import("@tweenjs/tween.js"),
-	[LibId.Anime]: () => import("animejs/animation")
+var BUILTIN_GLOBALS = {
+	THREE,
+	TSL,
+	van
 };
 //#endregion
-//#region packages/world-runtime/src/settings/AddonsRuntime.ts
+//#region packages/world-runtime/src/addons/required-libs.ts
 /**
-* Runtime loading of addons (game-only): enabled built-in libs + external
-* scripts (externals). Exposes them to user scripts via `resolve(key)`
-* (used in `ScriptsRuntime.require`). Replaces the old
-* `GameLoader.loadExternalsAsync` / `getExternalLib`.
+* 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.
 */
-var AddonsRuntime = class {
+function collectRequiredLibs(addons, usedBuiltinUuids = []) {
+	const required = /* @__PURE__ */ new Set();
+	const configured = addons?.libs ?? {};
+	for (const id of Object.keys(configured)) if (configured[id] && LIB_IDS.includes(id) && !LIBS[id].builtin) required.add(id);
+	for (const descriptor of OPTIONAL_MODULES) {
+		if (!descriptor.requiredLibs?.length) continue;
+		if (descriptor.normalize(addons?.modules?.[descriptor.id]) === null) continue;
+		for (const id of descriptor.requiredLibs) required.add(id);
+	}
+	for (const uuid of usedBuiltinUuids) {
+		const libs = getBuiltinBehaviour(uuid)?.requiredPatch?.requiredLibs;
+		if (libs) for (const id of libs) required.add(id);
+	}
+	return [...required];
+}
+//#endregion
+//#region packages/world-runtime/src/addons/AddonsRuntime.ts
+/**
+* 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`).
+*/
+var AddonsRuntime = class extends ContextModule {
+	_imports;
 	/** libs — by requireKey (`@tweenjs/tween.js`), externals — by accessor (`Tone`). */
 	_byKey = /* @__PURE__ */ new Map();
+	_byLibId = /* @__PURE__ */ new Map();
 	_scriptTags = [];
-	async load(addons) {
-		await this._loadLibs(addons.libs);
+	constructor(_imports = {}) {
+		super();
+		this._imports = _imports;
+		this._registerBuiltins();
+	}
+	/** `usedBuiltinUuids` — built-in behaviours on the scene; they may require libs. */
+	async load(addons, usedBuiltinUuids = []) {
+		await this._loadLibs(collectRequiredLibs(addons, usedBuiltinUuids));
 		await this._loadExternals(addons.externals);
 	}
-	/** Resolves a require key: enabled lib or external accessor; undefined otherwise. */
+	/** Resolves a require key: a lib or an external accessor; undefined otherwise. */
 	resolve(key) {
 		return this._byKey.get(key);
 	}
-	async _loadLibs(libs) {
-		if (!libs) return;
-		for (const id of LIB_IDS) {
-			if (!libs[id]) continue;
+	/** The lib itself, for runtime code that knows what it needs (physics → rapier). */
+	lib(id) {
+		return this._byLibId.get(id);
+	}
+	/** Libs bundled with the runtime: no importer, no config, always available. */
+	_registerBuiltins() {
+		for (const descriptor of BUILTIN_LIB_DESCRIPTORS) {
+			const module = BUILTIN_LIB_MODULES[descriptor.id];
+			if (module === void 0) {
+				console.error(`[addons] built-in lib "${descriptor.id}" has no module`);
+				continue;
+			}
+			this._register(descriptor.id, module);
+		}
+	}
+	async _loadLibs(ids) {
+		for (const id of ids) {
+			const descriptor = LIBS[id];
+			const load = this._imports.libs?.[id];
+			if (!load) {
+				console.error(`[addons] lib "${id}" is needed but has no importer`);
+				continue;
+			}
 			try {
-				this._byKey.set(LIBS[id].requireKey, await LIB_LOADERS[id]());
+				const module = await load();
+				this._register(id, unwrapLib(id, await (descriptor.init?.(module) ?? module)));
 			} catch (e) {
 				console.error(`[addons] failed to load lib "${id}"`, e);
 			}
 		}
 	}
+	_register(id, value) {
+		this._byLibId.set(id, value);
+		this._byKey.set(LIBS[id].requireKey, value);
+	}
 	async _loadExternals(externals) {
 		if (!externals) return;
 		for (const ext of externals) try {
@@ -907,37 +1241,76 @@ var AddonsRuntime = class {
 		for (const tag of this._scriptTags) tag.remove();
 		this._scriptTags.length = 0;
 		this._byKey.clear();
+		this._byLibId.clear();
 	}
 };
+/** A package like nipplejs exposes its API as the default export — that is what
+*  `require` should hand back. */
+function unwrapLib(id, module) {
+	if (!LIBS[id].defaultExport) return module;
+	return module.default ?? module;
+}
 //#endregion
-//#region packages/world-runtime/src/settings/module-registry.ts
+//#region packages/world-runtime/src/world-stores.ts
 /**
-* Registry of pluggable engine modules (`settings.addons.json → modules`).
-* These are three-start modules that must be registered before `start()`.
-* Feature toggles (chat/joystick/debugPerf) are NOT here — they live in
-* `settings.json` (see `../features/feature-registry`).
-*
-* The only module so far is physics.
-* Installation lives in game (`game/settings/module-installers`).
+* Shared reactive key-value state of a world (`world.stores` in scripts) — the
+* state counterpart of the `world.events` bus. Stores are created lazily on
+* first touch; `undefined` means "no value", so `delete`/`clear` only reset
+* values and never invalidate a reference taken from `of()`.
 */
-var ModuleId = /* @__PURE__ */ function(ModuleId) {
-	ModuleId["Physics"] = "physics";
-	return ModuleId;
-}({});
-var PHYSICS_ENGINES = ["rapier"];
-var MODULE_IDS = Object.values(ModuleId);
-/** Normalizes the physics config to an object (or null if disabled). */
-function normalizePhysics(value) {
-	if (!value) return null;
-	if (typeof value === "string") return {
-		engine: value,
-		debug: false
-	};
-	return {
-		engine: value.engine,
-		debug: value.debug ?? false
-	};
-}
+var WorldStores = class {
+	_stores = /* @__PURE__ */ new Map();
+	/** The store behind a key, created on first touch. */
+	of(key) {
+		let store = this._stores.get(key);
+		if (!store) {
+			store = atom(void 0);
+			this._stores.set(key, store);
+		}
+		return store;
+	}
+	get(key) {
+		return this.of(key).get();
+	}
+	set(key, value) {
+		this.of(key).set(value);
+	}
+	/** Subscribe to a key; returns unsubscribe. Not called with the current value. */
+	listen(key, listener) {
+		return this.of(key).listen(listener);
+	}
+	/** Same as `listen`, but also fires immediately with the current value. */
+	subscribe(key, listener) {
+		return this.of(key).subscribe(listener);
+	}
+	/** A value has been written to the key and not deleted since. */
+	has(key) {
+		return this._stores.get(key)?.get() !== void 0;
+	}
+	/** Keys that currently hold a value. */
+	keys() {
+		const keys = [];
+		for (const [key, store] of this._stores) if (store.get() !== void 0) keys.push(key);
+		return keys;
+	}
+	/** Plain object with all current values — for debugging and saves. */
+	snapshot() {
+		const result = {};
+		for (const [key, store] of this._stores) {
+			const value = store.get();
+			if (value !== void 0) result[key] = value;
+		}
+		return result;
+	}
+	/** Resets the key to `undefined`; listeners are notified. */
+	delete(key) {
+		this._stores.get(key)?.set(void 0);
+	}
+	/** Resets every key; listeners are notified. */
+	clear() {
+		for (const store of this._stores.values()) store.set(void 0);
+	}
+};
 //#endregion
 //#region packages/world-runtime/src/WorldRuntime.ts
 /**
@@ -949,17 +1322,26 @@ var WorldRuntime = class {
 	options;
 	/** World lifecycle event bus (`world.events` in scripts). */
 	emitter = new EventEmitter();
-	_addons = new AddonsRuntime();
+	/** Shared reactive state of the world (`world.stores` in scripts). */
+	stores = new WorldStores();
+	_addons;
 	_executedScripts = /* @__PURE__ */ new Map();
 	_builtins = /* @__PURE__ */ new Map();
 	_styleElements = [];
 	_resources = {};
+	/** Reverse index for `getUrl(resource)` — play mode resolves objects too. */
+	_pathByResource = /* @__PURE__ */ new Map();
 	_ctx = null;
 	_bloom = null;
 	_scriptContext = null;
 	constructor(definition, options) {
 		this.definition = definition;
 		this.options = options;
+		this._addons = new AddonsRuntime(definition.imports);
+	}
+	/** The world's external dependencies; also the `addons` ctx module. */
+	get addons() {
+		return this._addons;
 	}
 	/** ctx appears at the 3d-context creation step; unavailable to scripts before that. */
 	get ctx() {
@@ -974,14 +1356,18 @@ var WorldRuntime = class {
 	setBloom(bloom) {
 		this._bloom = bloom;
 	}
-	/** @internal Built-in libs and external scripts from `settings.addons.json`. */
+	/** @internal Libs (config + required by modules/behaviours) and externals. */
 	async loadAddons() {
-		const addons = this.definition.addons;
-		if (addons) await this._addons.load(addons);
+		await this._addons.load(this.definition.addons ?? {}, this.definition.usedBuiltins ?? []);
 	}
 	/** @internal World resources by asset path — result of `loadAssets`. */
 	setResources(resources) {
 		this._resources = resources;
+		this._pathByResource.clear();
+		for (const path in resources) {
+			const resource = resources[path];
+			if (resource !== null && typeof resource === "object") this._pathByResource.set(resource, path);
+		}
 	}
 	reportProgress(stage, details) {
 		const progress = {
@@ -990,9 +1376,11 @@ var WorldRuntime = class {
 		};
 		this.options.onProgress?.(progress);
 	}
-	getUrl = (path) => {
-		const url = this.definition.assets[path];
-		if (url === void 0) throw new Error(`World runtime: unknown asset "${path}"`);
+	/** Accepts an asset path or a resource returned by `require` — like play mode. */
+	getUrl = (source) => {
+		const path = typeof source === "string" ? source : this._pathByResource.get(source);
+		const url = path === void 0 ? void 0 : this.definition.assets[path];
+		if (url === void 0) throw new Error(`World runtime: unknown asset "${typeof source === "string" ? source : path ?? "<unknown resource>"}"`);
 		if (isAbsoluteUrl(url)) return url;
 		return `${this.options.assetsBaseUrl ?? ""}${url}`;
 	};
@@ -1027,16 +1415,11 @@ var WorldRuntime = class {
 			const patch = getBuiltinBehaviour(uuid)?.requiredPatch;
 			if (!patch) continue;
 			try {
-				await patch(starter);
+				await patch.apply(starter);
 			} catch (error) {
 				console.error(`Required patch of "${uuid}" failed`, error);
 			}
 		}
-		if (normalizePhysics(this.definition.addons?.modules?.physics)) try {
-			await applyRapierPhysicsPatch(starter);
-		} catch (error) {
-			console.error("Physics module patch failed", error);
-		}
 	}
 	/** Addon (built-in lib / external) → script by path → asset resource. Same
 	* resolve order as in play mode. */
@@ -1050,7 +1433,8 @@ var WorldRuntime = class {
 	};
 	/**
 	* 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, options) => {
 		const object = typeof source === "function" ? source() : clone(source);
@@ -1105,6 +1489,7 @@ var WorldRuntime = class {
 		this._styleElements.length = 0;
 		this._executedScripts.clear();
 		this.emitter.removeAllListeners();
+		this.stores.clear();
 	}
 	/** Narrow bloom facade for scripts: mode is read-only, params are live
 	* (uniforms, can be animated per frame). `null` — bloom is disabled. */
@@ -1144,18 +1529,22 @@ var WorldRuntime = class {
 				get ctx() {
 					return runtime.ctx;
 				},
+				/** Short path to the chat module, same as in play mode. */
+				get chat() {
+					return runtime.ctx.modules.chat;
+				},
 				events: this.emitter,
 				emitter: this.emitter,
+				stores: this.stores,
 				rendering: { get bloom() {
 					return runtime.bloomApi;
 				} }
 			},
+			modules: lazyProxy(() => runtime.ctx.modules),
 			require: this.require,
 			instantiate: this.instantiate,
 			getUrl: this.getUrl,
-			THREE,
-			TSL,
-			van
+			...BUILTIN_GLOBALS
 		};
 		return this._scriptContext;
 	}
@@ -1177,7 +1566,7 @@ function isAbsoluteUrl(url) {
 }
 //#endregion
 //#region packages/world-runtime/src/version.gen.ts
-var RUNTIME_VERSION = "0.1.0";
+var RUNTIME_VERSION = "0.4.2";
 //#endregion
 //#region packages/world-runtime/src/version.ts
 /**
@@ -1243,7 +1632,10 @@ async function createWorld(definition, runtime) {
 		scene: new THREE.Scene(),
 		autoInitRenderer: false
 	}, runtime);
-	world.addModules(createWorldModules("prod"));
+	world.addModules(await createWorldModules("prod", {
+		addons: runtime.addons,
+		modules: runtime.definition.addons?.modules
+	}));
 	applyRendererConfig(renderer, config);
 	if (config.bloom?.enabled) {
 		if (config.bloom.mode === "emissive") enableSceneEmissiveMrt(world.ctx.scenePass);
@@ -1678,7 +2070,7 @@ var UNIFORM_DEFAULTS = {
 	texture: () => getDefaultResource(DefaultResourceId.Texture)
 };
 //#endregion
-//#region packages/world-runtime/src/settings/externals.ts
+//#region packages/world-runtime/src/addons/externals.ts
 var EXTERNAL_TYPES = ["umd", "module"];
 //#endregion
 //#region packages/world-runtime/src/rendering/renderer-options.ts
@@ -1704,4 +2096,4 @@ var TONE_MAPPING_NAMES = [
 	"Neutral"
 ];
 //#endregion
-export { AddonsRuntime, AssetLoaders, AudioSource, BLOOM_MODES, BUILTIN_BEHAVIOURS, BUILTIN_BEHAVIOUR_LIST, DEFAULT_RESOURCE_IDS, DefaultResourceId, EXTERNAL_TYPES, EnvModule, FontSource, HtmlHudModule, InputSystemModule, LIBS, LIB_DESCRIPTORS, LIB_IDS, LOADING_MANAGER, LibId, MODULE_IDS, ModuleId, PHYSICS_ENGINES, RUNTIME_VERSION, SHADOW_MAP_TYPES, SceneBloom, SoundsModule, TONE_MAPPING_NAMES, TslNode, UNIFORM_DEFAULTS, UNIFORM_TYPES, UtilsModule, VideoSource, WORLD_FORMAT_VERSION, World, WorldEvent, applyRapierPhysicsPatch, applyRendererConfig, applyTextureDefaults, collectModelSubResources, configureAssetLoaders, createAudio, createFont, createTslNode, createUniformNode, createVideo, createWorldModules, defineWorld, enableSceneEmissiveMrt, fontFormatFromMime, getBuiltinBehaviour, getDefaultResource, getHalfheightRadiusScale, getRadiusScale, isDefaultResourceId, isMobileDevice, isUniformType, lazyRapier, libByRequireKey, loadGeometry, loadHdr, loadModel, loadTexture, normalizePhysics, parseGeometryJson, parseHdr, parseModel, setColor, uniformType };
+export { AddonsRuntime, AssetLoaders, AudioSource, BLOOM_MODES, BUILTIN_BEHAVIOURS, BUILTIN_BEHAVIOUR_LIST, BUILTIN_LIB_DESCRIPTORS, CHAT_INPUT_MODES, DEFAULT_RESOURCE_IDS, DefaultResourceId, EXTERNAL_TYPES, EnvModule, FontSource, HtmlHudModule, InputSystemModule, LIBS, LIB_DESCRIPTORS, LIB_IDS, LOADING_MANAGER, LibId, OPTIONAL_LIB_DESCRIPTORS, OPTIONAL_LIB_IDS, OPTIONAL_MODULES, OPTIONAL_MODULE_IDS, OptionalModuleId, PHYSICS_ENGINES, RUNTIME_VERSION, SHADOW_MAP_TYPES, SceneBloom, SoundsModule, TONE_MAPPING_NAMES, TslNode, UNIFORM_DEFAULTS, UNIFORM_TYPES, UtilsModule, VideoSource, WORLD_FORMAT_VERSION, World, WorldEvent, WorldStores, applyRendererConfig, applyTextureDefaults, collectModelSubResources, collectRequiredLibs, configureAssetLoaders, createAudio, createFont, createTslNode, createUniformNode, createVideo, createWorldModules, defineWorld, enableSceneEmissiveMrt, fontFormatFromMime, getBuiltinBehaviour, getDefaultResource, getHalfheightRadiusScale, getOptionalModuleDescriptor, getRadiusScale, isDefaultResourceId, isMobileDevice, isUniformType, lazyProxy, libByRequireKey, loadGeometry, loadHdr, loadModel, loadTexture, normalizeChat, normalizePhysics, parseGeometryJson, parseHdr, parseModel, rapierPhysicsPatch, setColor, uniformType };