@kvyverse/world-runtime 0.1.0 → 0.3.2

package/dist/index.js

@@ -1,5 +1,5 @@
-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 { 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 +7,10 @@ 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 { 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";
 //#region packages/world-runtime/src/world-events.ts
 /**
 * World lifecycle events, emitted on `game.emitter` (`world.events` in scripts)
@@ -40,8 +40,8 @@ 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;
@@ -268,6 +268,241 @@ 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-zLwVZpwF.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 });
+}
+/**
+* Registers physics on demand: a built-in physics behaviour declares it via
+* `meta.requiredPatch`, so a world with a collider on the scene gets
+* `ctx.modules.rapier` even without a line in `settings.addons.json`.
+* 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),
+	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;
@@ -336,46 +571,6 @@ var HtmlHudModule = class extends ContextModule {
 };
 //#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 +616,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 +649,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 +667,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 +688,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 +806,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 +843,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 +905,7 @@ var entries = [
 	{
 		uuid: "fpscameracontroller",
 		name: "FpsCameraController",
-		load: () => loadDefault(import("./FpsCameraController-BE2EirRj.js"))
+		load: () => loadDefault(import("./FpsCameraController-2GNWJM5D.js"))
 	},
 	{
 		uuid: "sightinteractablearea",
@@ -679,43 +920,43 @@ var entries = [
 	{
 		uuid: "rrb",
 		name: "Rigidbody",
-		load: () => loadDefault(import("./Rigidbody-b7QNF4ev.js").then((n) => n.n)),
+		load: () => loadDefault(import("./Rigidbody-DLhN8ddv.js").then((n) => n.n)),
 		requiredPatch: applyRapierPhysicsPatch
 	},
 	{
 		uuid: "rapierballcol",
 		name: "BallCollider",
-		load: () => loadDefault(import("./BallCollider-8ZrxReEd.js")),
+		load: () => loadDefault(import("./BallCollider-3L5vOrcL.js")),
 		requiredPatch: applyRapierPhysicsPatch
 	},
 	{
 		uuid: "rapiercapscol",
 		name: "CapsuleCollider",
-		load: () => loadDefault(import("./CapsuleCollider-bynyf6Mc.js")),
+		load: () => loadDefault(import("./CapsuleCollider-CBTsR-Ys.js")),
 		requiredPatch: applyRapierPhysicsPatch
 	},
 	{
 		uuid: "rapierconecol",
 		name: "ConeCollider",
-		load: () => loadDefault(import("./ConeCollider-DtRZmgK8.js")),
+		load: () => loadDefault(import("./ConeCollider-C3XU3Y9X.js")),
 		requiredPatch: applyRapierPhysicsPatch
 	},
 	{
 		uuid: "rapierconvxcol",
 		name: "ConvexMeshCollider",
-		load: () => loadDefault(import("./ConvexMeshCollider-BSmDM4o3.js")),
+		load: () => loadDefault(import("./ConvexMeshCollider-DzNV4HTO.js")),
 		requiredPatch: applyRapierPhysicsPatch
 	},
 	{
 		uuid: "rapiercubcol",
 		name: "CuboidCollider",
-		load: () => loadDefault(import("./CuboidCollider-CJvq7--s.js")),
+		load: () => loadDefault(import("./CuboidCollider-Dp1DZoFM.js")),
 		requiredPatch: applyRapierPhysicsPatch
 	},
 	{
 		uuid: "rapiercylcol",
 		name: "CylinderCollider",
-		load: () => loadDefault(import("./CylinderCollider-CQPSh4tu.js")),
+		load: () => loadDefault(import("./CylinderCollider-C0h_nhB5.js")),
 		requiredPatch: applyRapierPhysicsPatch
 	},
 	{
@@ -727,7 +968,7 @@ var entries = [
 	{
 		uuid: "rapierfpsplayercontroller",
 		name: "RapierFpsPlayerController",
-		load: () => loadDefault(import("./RapierFpsPlayerController-VsNfQl6v.js")),
+		load: () => loadDefault(import("./RapierFpsPlayerController-DthD8dw9.js")),
 		requiredPatch: applyRapierPhysicsPatch
 	}
 ];
@@ -803,20 +1044,25 @@ function createFont(url, family, mime, name) {
 	return source;
 }
 //#endregion
-//#region packages/world-runtime/src/settings/lib-registry.ts
+//#region packages/world-runtime/src/addons/lib-registry.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`),
+* (what the user writes in `require(...)` in scripts — and the import specifier
+* importers are built from). Single source for:
+*  - game: the app's importer map (`core/game/settings/optional-imports`),
+*  - export: the `imports.libs` block the build emits into the world module,
 *  - editor: JSON schema (`libs` props) + require typings (`AddonsRequireTypings`).
 *
-* Adding a lib = add an entry here (+ loader in game, + d.ts loader in editor).
+* Adding a lib = add an entry here (+ importer in the app, + d.ts loader in editor).
+* The package itself never imports these — see `./optional-imports.ts`.
 */
 var LibId = /* @__PURE__ */ function(LibId) {
 	LibId["Tween"] = "tween";
 	LibId["Anime"] = "anime";
+	LibId["Nipplejs"] = "nipplejs";
+	LibId["Stats"] = "stats";
 	return LibId;
 }({});
 var LIBS = {
@@ -828,7 +1074,20 @@ var LIBS = {
 	["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
 	}
 };
 var LIB_IDS = Object.values(LibId);
@@ -837,47 +1096,71 @@ function libByRequireKey(requireKey) {
 	return LIB_DESCRIPTORS.find((l) => l.requireKey === requireKey);
 }
 //#endregion
-//#region packages/world-runtime/src/settings/lib-loaders.ts
+//#region packages/world-runtime/src/addons/AddonsRuntime.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`.
-*/
-var LIB_LOADERS = {
-	[LibId.Tween]: () => import("@tweenjs/tween.js"),
-	[LibId.Anime]: () => import("animejs/animation")
-};
-//#endregion
-//#region packages/world-runtime/src/settings/AddonsRuntime.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`.
+* External dependencies of the world: built-in libs, externals and the physics
+* engine. Loaded before the world starts; scripts reach them through
+* `resolve(key)` (`require`), the physics module through `rapier`.
+*
+* 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 packages is up to the runtime owner
+* (see `WorldImports`).
 */
-var AddonsRuntime = class {
+var AddonsRuntime = class extends ContextModule {
+	_imports;
 	/** libs — by requireKey (`@tweenjs/tween.js`), externals — by accessor (`Tone`). */
 	_byKey = /* @__PURE__ */ new Map();
 	_scriptTags = [];
-	async load(addons) {
+	_rapier = null;
+	constructor(_imports = {}) {
+		super();
+		this._imports = _imports;
+	}
+	/** `physics` — whether the world needs rapier (config or a physics behaviour). */
+	async load(addons, options = {}) {
 		await this._loadLibs(addons.libs);
 		await this._loadExternals(addons.externals);
+		if (options.physics) await this._loadRapier();
 	}
 	/** Resolves a require key: enabled lib or external accessor; undefined otherwise. */
 	resolve(key) {
 		return this._byKey.get(key);
 	}
+	/** The physics engine, loaded and initialized; `null` in worlds without physics. */
+	get rapier() {
+		return this._rapier;
+	}
 	async _loadLibs(libs) {
 		if (!libs) return;
 		for (const id of LIB_IDS) {
 			if (!libs[id]) continue;
+			const load = this._imports.libs?.[id];
+			if (!load) {
+				console.error(`[addons] lib "${id}" is enabled but has no importer`);
+				continue;
+			}
 			try {
-				this._byKey.set(LIBS[id].requireKey, await LIB_LOADERS[id]());
+				this._byKey.set(LIBS[id].requireKey, unwrapLib(id, await load()));
 			} catch (e) {
 				console.error(`[addons] failed to load lib "${id}"`, e);
 			}
 		}
 	}
+	async _loadRapier() {
+		const load = this._imports.rapier;
+		if (!load) {
+			console.error("[addons] the world needs physics but has no importer for \"@dimforge/rapier3d-compat\"");
+			return;
+		}
+		try {
+			const rapier = await load();
+			await rapier.init();
+			this._rapier = rapier;
+		} catch (e) {
+			console.error("[addons] failed to load rapier", e);
+		}
+	}
 	async _loadExternals(externals) {
 		if (!externals) return;
 		for (const ext of externals) try {
@@ -907,36 +1190,14 @@ var AddonsRuntime = class {
 		for (const tag of this._scriptTags) tag.remove();
 		this._scriptTags.length = 0;
 		this._byKey.clear();
+		this._rapier = null;
 	}
 };
-//#endregion
-//#region packages/world-runtime/src/settings/module-registry.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`).
-*/
-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
-	};
+/** 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/WorldRuntime.ts
@@ -949,17 +1210,24 @@ var WorldRuntime = class {
 	options;
 	/** World lifecycle event bus (`world.events` in scripts). */
 	emitter = new EventEmitter();
-	_addons = new AddonsRuntime();
+	_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 +1242,23 @@ var WorldRuntime = class {
 	setBloom(bloom) {
 		this._bloom = bloom;
 	}
-	/** @internal Built-in libs and external scripts from `settings.addons.json`. */
+	/** @internal Built-in libs, externals and the physics engine, if the world needs one. */
 	async loadAddons() {
-		const addons = this.definition.addons;
-		if (addons) await this._addons.load(addons);
+		await this._addons.load(this.definition.addons ?? {}, { physics: this._usesPhysics() });
+	}
+	/** Physics is on in the config, or a built-in behaviour on the scene needs it. */
+	_usesPhysics() {
+		if (normalizePhysics(this.definition.addons?.modules?.physics)) return true;
+		return (this.definition.usedBuiltins ?? []).some((uuid) => getBuiltinBehaviour(uuid)?.requiredPatch);
 	}
 	/** @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 +1267,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}`;
 	};
@@ -1032,11 +1311,6 @@ var WorldRuntime = class {
 				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 +1324,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);
@@ -1144,6 +1419,10 @@ 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,
 				rendering: { get bloom() {
@@ -1155,7 +1434,11 @@ var WorldRuntime = class {
 			getUrl: this.getUrl,
 			THREE,
 			TSL,
-			van
+			van,
+			/** Physics engine global; null in worlds without physics. */
+			get RAPIER() {
+				return runtime.addons.rapier;
+			}
 		};
 		return this._scriptContext;
 	}
@@ -1177,7 +1460,7 @@ function isAbsoluteUrl(url) {
 }
 //#endregion
 //#region packages/world-runtime/src/version.gen.ts
-var RUNTIME_VERSION = "0.1.0";
+var RUNTIME_VERSION = "0.3.2";
 //#endregion
 //#region packages/world-runtime/src/version.ts
 /**
@@ -1243,7 +1526,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 +1964,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 +1990,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, CHAT_INPUT_MODES, DEFAULT_RESOURCE_IDS, DefaultResourceId, EXTERNAL_TYPES, EnvModule, FontSource, HtmlHudModule, InputSystemModule, LIBS, LIB_DESCRIPTORS, LIB_IDS, LOADING_MANAGER, LibId, 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, applyRapierPhysicsPatch, applyRendererConfig, applyTextureDefaults, collectModelSubResources, configureAssetLoaders, createAudio, createFont, createTslNode, createUniformNode, createVideo, createWorldModules, defineWorld, enableSceneEmissiveMrt, fontFormatFromMime, getBuiltinBehaviour, getDefaultResource, getHalfheightRadiusScale, getOptionalModuleDescriptor, getRadiusScale, isDefaultResourceId, isMobileDevice, isUniformType, libByRequireKey, loadGeometry, loadHdr, loadModel, loadTexture, normalizeChat, normalizePhysics, parseGeometryJson, parseHdr, parseModel, setColor, uniformType };