@kvyverse/world-runtime 0.6.8 → 0.9.1

package/README.md

@@ -81,6 +81,12 @@ world.ctx.scene, world.ctx.camera, world.ctx.renderer
 world.unmount(), world.runLoop(), world.stopLoop(), world.dispose()
 ```
 
+`world.ctx.camera` starts as the world's main camera: the one picked in the
+editor's Scene settings, otherwise the first perspective camera in the scene,
+prefab and model contents included, otherwise the first orthographic one
+(`resolveMainCamera`). An orthographic main camera is `world.ctx.ortho`, and
+`world.ctx.isOrtho` is `true`.
+
 On top of that: `world.getUrl(path)` resolves an asset URL the same way scripts
 inside the world do, `world.events` is the world lifecycle emitter (the same
 `world.events` your scripts use), and `world.stores` is the world's shared

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export type { InstantiateOptions, PrefabFactory } from "./WorldRuntime";
 export { setColor } from "./values";
 export { RUNTIME_VERSION, WORLD_FORMAT_VERSION } from "./version";
 export { WorldEvent } from "./world-events";
+export { isMainCameraKind, resolveMainCamera, setActiveCamera } from "./main-camera";
 export { lazyProxy } from "./utils/lazy";
 export { WorldStores } from "./world-stores";
 export type { WorldStore } from "./world-stores";
@@ -26,11 +27,13 @@ export { BUILTIN_BEHAVIOUR_LIST, BUILTIN_BEHAVIOURS, getBuiltinBehaviour, } from
 export type { BuiltinBehaviour, RequiredPatch } from "./behaviours/registry";
 export { rapierPhysicsPatch } from "./behaviours/physics/_required-patch";
 export { AddonsRuntime } from "./addons/AddonsRuntime";
-export { applyRendererConfig } from "./rendering/renderer-apply";
+export { applyRendererConfig, resolveToneMapping } from "./rendering/renderer-apply";
 export { enableSceneEmissiveMrt, SceneBloom } from "./rendering/SceneBloom";
 export { createTslNode, TslNode } from "./rendering/tsl-node";
 export type { TslNodeBuilder } from "./rendering/tsl-node";
-export { createUniformNode, isUniformType, UNIFORM_DEFAULTS, UNIFORM_TYPES, uniformType, } from "./rendering/tsl-uniforms";
+export { createMaterialShader, MaterialShader, readMaterialShaderOutputs, } from "./rendering/material-shader";
+export type { MaterialShaderBuilder, MaterialShaderOutputs, } from "./rendering/material-shader";
+export { createUniformNode, createUniformValuesView, getUniformNodeValue, isUniformType, setUniformNodeValue, UNIFORM_DEFAULTS, UNIFORM_TYPES, uniformType, } from "./rendering/tsl-uniforms";
 export type { UniformType } from "./rendering/tsl-uniforms";
 export { BUILTIN_LIB_DESCRIPTORS, LIB_DESCRIPTORS, LIB_IDS, LIBS, LibId, OPTIONAL_LIB_DESCRIPTORS, OPTIONAL_LIB_IDS, libByRequireKey, } from "./addons/lib-registry";
 export { collectRequiredLibs } from "./addons/required-libs";

package/dist/index.js

@@ -204,11 +204,15 @@ var TONE_MAPPINGS = {
 function applyRendererConfig(renderer, cfg) {
 	renderer.shadowMap.enabled = cfg.shadowMap?.enabled ?? true;
 	renderer.shadowMap.type = SHADOW_MAP_TYPES$1[cfg.shadowMap?.type ?? "PCFSoft"] ?? THREE.PCFSoftShadowMap;
-	renderer.toneMapping = TONE_MAPPINGS[cfg.toneMapping ?? "Neutral"] ?? THREE.NeutralToneMapping;
+	renderer.toneMapping = resolveToneMapping(cfg.toneMapping);
 	const pr = cfg.pixelResolution;
 	const pixelResolution = typeof pr === "number" && Number.isFinite(pr) && pr > 0 ? pr : 1;
 	renderer.setPixelRatio(window.devicePixelRatio * pixelResolution);
 }
+/** `RendererConfig.toneMapping` → three constant; a missing or bad name falls back to Neutral. */
+function resolveToneMapping(name) {
+	return TONE_MAPPINGS[name ?? "Neutral"] ?? THREE.NeutralToneMapping;
+}
 //#endregion
 //#region packages/world-runtime/src/rendering/SceneBloom.ts
 /** BloomNode loads as a chunk only when bloom is enabled. */
@@ -1608,7 +1612,7 @@ function isAbsoluteUrl(url) {
 }
 //#endregion
 //#region packages/world-runtime/src/version.gen.ts
-var RUNTIME_VERSION = "0.6.8";
+var RUNTIME_VERSION = "0.9.1";
 //#endregion
 //#region packages/world-runtime/src/version.ts
 /**
@@ -1624,6 +1628,46 @@ function assertFormatVersion(version) {
 	throw new Error(`@kvyverse/world-runtime: world format v${version} is not supported by runtime (expected v1). Re-export the world or pin a matching runtime version.`);
 }
 //#endregion
+//#region packages/world-runtime/src/main-camera.ts
+/**
+* The camera a world starts from: the one picked in scene settings, otherwise the
+* first `PerspectiveCamera` depth-first, otherwise the first `OrthographicCamera`.
+* One rule for Play, the editor and export.
+*/
+function resolveMainCamera(explicit, roots) {
+	if (isMainCameraKind(explicit)) return explicit;
+	const found = { ortho: null };
+	for (const root of roots) {
+		const perspective = findCameras(root, found);
+		if (perspective) return perspective;
+	}
+	return found.ortho;
+}
+/** Makes the camera active, through the accessor that matches its kind. */
+function setActiveCamera(ctx, camera) {
+	if (isOrthographicCamera(camera)) ctx.ortho = camera;
+	else ctx.camera = camera;
+}
+/** A camera that can be the main one (`ThreeStartCamera`). */
+function isMainCameraKind(value) {
+	return isPerspectiveCamera(value) || isOrthographicCamera(value);
+}
+function findCameras(obj, found) {
+	if (isPerspectiveCamera(obj)) return obj;
+	if (!found.ortho && isOrthographicCamera(obj)) found.ortho = obj;
+	for (const child of obj.children) {
+		const perspective = findCameras(child, found);
+		if (perspective) return perspective;
+	}
+	return null;
+}
+function isPerspectiveCamera(value) {
+	return !!value?.isPerspectiveCamera;
+}
+function isOrthographicCamera(value) {
+	return !!value?.isOrthographicCamera;
+}
+//#endregion
 //#region packages/world-runtime/src/bootstrap.ts
 /**
 * World assembly order. The only place where it is fixed: the artifact supplies
@@ -1650,7 +1694,8 @@ async function bootstrapWorld(definition, options) {
 	await runtime.applyRequiredPatches(world);
 	runtime.reportProgress("Applying scene settings");
 	definition.applySceneSettings?.(runtime, world.ctx.scene);
-	if (built.camera) world.ctx.camera = built.camera;
+	const camera = resolveMainCamera(built.camera, built.children);
+	if (camera) setActiveCamera(world.ctx, camera);
 	runtime.reportProgress("Running scripts");
 	runtime.mountFonts();
 	runtime.mountStyles();
@@ -2009,49 +2054,6 @@ async function createVideo(url, name) {
 	return source;
 }
 //#endregion
-//#region packages/world-runtime/src/rendering/tsl-node.ts
-/**
-* World TSL node: the built graph node + its uniform nodes. This is what
-* `require("/Shaders/....tsl")` returns, so the method set matches the editor's
-* `TslNodeSource` (`setUniformValue` / `getUniformValue` / `uniformValues`).
-*/
-var TslNode = class {
-	uniforms;
-	node;
-	_uniformValuesView;
-	constructor(uniforms, build, name = "TslNode") {
-		this.uniforms = uniforms;
-		let node;
-		try {
-			node = build(TSL, uniforms);
-		} catch (error) {
-			console.warn(`TSL node "${name}" build failed`, error);
-		}
-		this.node = node ?? TSL.float(1);
-	}
-	/** Flat view of uniform values: reads and writes go straight to `node.value`. */
-	get uniformValues() {
-		return this._uniformValuesView ??= new Proxy({}, {
-			get: (_target, key) => typeof key === "string" ? this.getUniformValue(key) : void 0,
-			set: (_target, key, value) => {
-				if (typeof key === "string") this.setUniformValue(key, value);
-				return true;
-			}
-		});
-	}
-	setUniformValue(key, value) {
-		const node = this.uniforms[key];
-		if (node) node.value = value;
-	}
-	getUniformValue(key) {
-		return this.uniforms[key]?.value;
-	}
-};
-/** Factory for the generated code: builds the node and wraps it. */
-function createTslNode(uniforms, build, name) {
-	return new TslNode(uniforms, build, name);
-}
-//#endregion
 //#region packages/world-runtime/src/rendering/tsl-uniforms.ts
 var UNIFORM_TYPES = [
 	"float",
@@ -2112,6 +2114,118 @@ var UNIFORM_DEFAULTS = {
 	bool: () => false,
 	texture: () => getDefaultResource(DefaultResourceId.Texture)
 };
+/** Writes a uniform value by key; an unknown key is a no-op. */
+function setUniformNodeValue(uniforms, key, value) {
+	const node = uniforms[key];
+	if (node) node.value = value;
+}
+/** Reads a uniform value by key; `undefined` for an unknown key. */
+function getUniformNodeValue(uniforms, key) {
+	return uniforms[key]?.value;
+}
+/** Flat view of uniform values: reads and writes go straight to `node.value`,
+* so values live only in the nodes (no copy, no sync step). */
+function createUniformValuesView(uniforms) {
+	return new Proxy({}, {
+		get: (_target, key) => typeof key === "string" ? getUniformNodeValue(uniforms, key) : void 0,
+		set: (_target, key, value) => {
+			if (typeof key === "string") setUniformNodeValue(uniforms, key, value);
+			return true;
+		}
+	});
+}
+//#endregion
+//#region packages/world-runtime/src/rendering/tsl-node.ts
+/**
+* World TSL node: the built graph node + its uniform nodes. This is what
+* `require("/Shaders/....tsl")` returns, so the method set matches the editor's
+* `TslNodeSource` (`setUniformValue` / `getUniformValue` / `uniformValues`).
+*/
+var TslNode = class {
+	uniforms;
+	node;
+	_uniformValuesView;
+	constructor(uniforms, build, name = "TslNode") {
+		this.uniforms = uniforms;
+		let node;
+		try {
+			node = build(TSL, uniforms);
+		} catch (error) {
+			console.warn(`TSL node "${name}" build failed`, error);
+		}
+		this.node = node ?? TSL.float(1);
+	}
+	/** Flat view of uniform values: reads and writes go straight to `node.value`. */
+	get uniformValues() {
+		return this._uniformValuesView ??= createUniformValuesView(this.uniforms);
+	}
+	setUniformValue(key, value) {
+		setUniformNodeValue(this.uniforms, key, value);
+	}
+	getUniformValue(key) {
+		return getUniformNodeValue(this.uniforms, key);
+	}
+};
+/** Factory for the generated code: builds the node and wraps it. */
+function createTslNode(uniforms, build, name) {
+	return new TslNode(uniforms, build, name);
+}
+//#endregion
+//#region packages/world-runtime/src/rendering/material-shader.ts
+var EMPTY_OUTPUTS = Object.freeze({});
+/**
+* Validates what a material shader assigned to `output`: a plain object whose
+* values are TSL nodes (`null`/`undefined` entries are skipped). Throws otherwise.
+*/
+function readMaterialShaderOutputs(raw) {
+	if (!isPlainObject(raw)) throw new Error("material shader must assign an object of node inputs to `output`, e.g. { colorNode, emissiveNode }");
+	const outputs = {};
+	for (const key of Object.keys(raw)) {
+		const value = raw[key];
+		if (value === null || value === void 0) continue;
+		if (!value.isNode) throw new Error(`material shader output "${key}" is not a TSL node`);
+		outputs[key] = value;
+	}
+	return outputs;
+}
+/**
+* World material shader: one script that builds several material node inputs
+* with shared uniforms. `require("/Shaders/....")` returns it, so the method set
+* matches the editor's `MaterialShaderSource`.
+*/
+var MaterialShader = class {
+	uniforms;
+	/** Built outputs; empty when the build failed (the material keeps its own inputs). */
+	outputs;
+	_uniformValuesView;
+	constructor(uniforms, build, name = "MaterialShader") {
+		this.uniforms = uniforms;
+		let outputs = EMPTY_OUTPUTS;
+		try {
+			outputs = readMaterialShaderOutputs(build(TSL, uniforms));
+		} catch (error) {
+			console.warn(`material shader "${name}" build failed`, error);
+		}
+		this.outputs = outputs;
+	}
+	/** Flat view of uniform values: reads and writes go straight to `node.value`. */
+	get uniformValues() {
+		return this._uniformValuesView ??= createUniformValuesView(this.uniforms);
+	}
+	setUniformValue(key, value) {
+		setUniformNodeValue(this.uniforms, key, value);
+	}
+	getUniformValue(key) {
+		return getUniformNodeValue(this.uniforms, key);
+	}
+};
+/** Factory for the generated code: builds the shader and wraps it. */
+function createMaterialShader(uniforms, build, name) {
+	return new MaterialShader(uniforms, build, name);
+}
+function isPlainObject(x) {
+	return typeof x === "object" && x !== null && Object.getPrototypeOf(x) === Object.prototype;
+}
 //#endregion
 //#region packages/world-runtime/src/addons/externals.ts
 var EXTERNAL_TYPES = ["umd", "module"];
@@ -2139,4 +2253,4 @@ var TONE_MAPPING_NAMES = [
 	"Neutral"
 ];
 //#endregion
-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, NullPlatformModule, 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 };
+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, MaterialShader, NullPlatformModule, 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, createMaterialShader, createTslNode, createUniformNode, createUniformValuesView, createVideo, createWorldModules, defineWorld, enableSceneEmissiveMrt, fontFormatFromMime, getBuiltinBehaviour, getDefaultResource, getHalfheightRadiusScale, getOptionalModuleDescriptor, getRadiusScale, getUniformNodeValue, isDefaultResourceId, isMainCameraKind, isMobileDevice, isUniformType, lazyProxy, libByRequireKey, loadGeometry, loadHdr, loadModel, loadTexture, normalizeChat, normalizePhysics, parseGeometryJson, parseHdr, parseModel, rapierPhysicsPatch, readMaterialShaderOutputs, resolveMainCamera, resolveToneMapping, setActiveCamera, setColor, setUniformNodeValue, uniformType };

package/dist/main-camera.d.ts

@@ -0,0 +1,12 @@
+import type * as THREE from "three/webgpu";
+import type { ThreeContext, ThreeStartCamera } from "three-start";
+/**
+ * The camera a world starts from: the one picked in scene settings, otherwise the
+ * first `PerspectiveCamera` depth-first, otherwise the first `OrthographicCamera`.
+ * One rule for Play, the editor and export.
+ */
+export declare function resolveMainCamera(explicit: unknown, roots: readonly THREE.Object3D[]): ThreeStartCamera | null;
+/** Makes the camera active, through the accessor that matches its kind. */
+export declare function setActiveCamera(ctx: ThreeContext, camera: ThreeStartCamera): void;
+/** A camera that can be the main one (`ThreeStartCamera`). */
+export declare function isMainCameraKind(value: unknown): value is ThreeStartCamera;

package/dist/rendering/material-shader.d.ts

@@ -0,0 +1,29 @@
+import * as TSL from "three/tsl";
+import type { Node } from "three/webgpu";
+/** Material shader outputs: material node input name (`colorNode`, …) → node. */
+export type MaterialShaderOutputs = Readonly<Record<string, Node>>;
+/** Material shader body: returns the `output` value, receiving `TSL` and the uniform nodes. */
+export type MaterialShaderBuilder = (tsl: typeof TSL, uniforms: Record<string, Node>) => unknown;
+/**
+ * Validates what a material shader assigned to `output`: a plain object whose
+ * values are TSL nodes (`null`/`undefined` entries are skipped). Throws otherwise.
+ */
+export declare function readMaterialShaderOutputs(raw: unknown): MaterialShaderOutputs;
+/**
+ * World material shader: one script that builds several material node inputs
+ * with shared uniforms. `require("/Shaders/....")` returns it, so the method set
+ * matches the editor's `MaterialShaderSource`.
+ */
+export declare class MaterialShader {
+    readonly uniforms: Record<string, Node>;
+    /** Built outputs; empty when the build failed (the material keeps its own inputs). */
+    readonly outputs: MaterialShaderOutputs;
+    private _uniformValuesView?;
+    constructor(uniforms: Record<string, Node>, build: MaterialShaderBuilder, name?: string);
+    /** Flat view of uniform values: reads and writes go straight to `node.value`. */
+    get uniformValues(): Record<string, unknown>;
+    setUniformValue(key: string, value: unknown): void;
+    getUniformValue(key: string): unknown;
+}
+/** Factory for the generated code: builds the shader and wraps it. */
+export declare function createMaterialShader(uniforms: Record<string, Node>, build: MaterialShaderBuilder, name?: string): MaterialShader;

package/dist/rendering/renderer-apply.d.ts

@@ -12,3 +12,5 @@ import type { RendererConfig } from "./types";
  * `undefined` constant / `NaN` (silently broken rendering).
  */
 export declare function applyRendererConfig(renderer: THREE.Renderer, cfg: RendererConfig): void;
+/** `RendererConfig.toneMapping` → three constant; a missing or bad name falls back to Neutral. */
+export declare function resolveToneMapping(name: string | undefined): THREE.ToneMapping;

package/dist/rendering/tsl-uniforms.d.ts

@@ -16,3 +16,10 @@ export declare function createUniformNode(type: UniformType): Node;
 /** Default value per type — for `Property.setDefault` (value==default is not
  * serialized, restored on load). Factories, since Color/Vec are mutable. */
 export declare const UNIFORM_DEFAULTS: Record<UniformType, () => unknown>;
+/** Writes a uniform value by key; an unknown key is a no-op. */
+export declare function setUniformNodeValue(uniforms: Record<string, Node>, key: string, value: unknown): void;
+/** Reads a uniform value by key; `undefined` for an unknown key. */
+export declare function getUniformNodeValue(uniforms: Record<string, Node>, key: string): unknown;
+/** Flat view of uniform values: reads and writes go straight to `node.value`,
+ * so values live only in the nodes (no copy, no sync step). */
+export declare function createUniformValuesView(uniforms: Record<string, Node>): Record<string, unknown>;

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { Object3DBehaviourConstructor } from "three-start";
+import type { Object3DBehaviourConstructor, ThreeStartCamera } from "three-start";
 import type { AddonsConfig, WorldImports } from "./addons/types";
 import type { RendererConfig } from "./rendering/types";
 import type * as THREE from "three/webgpu";
@@ -11,7 +11,8 @@ export type ScriptTable = Record<string, ScriptModule>;
 /** Result of constructing the scene hierarchy (before values are applied). */
 export interface SceneBuildResult {
     children: THREE.Object3D[];
-    camera?: THREE.PerspectiveCamera | null;
+    /** The main camera picked in scene settings; absent — the first one in `children`. */
+    camera?: ThreeStartCamera | null;
 }
 /** Load-step details for the user's UI. */
 export interface WorldLoadProgress {

package/dist/version.gen.d.ts

@@ -1 +1 @@
-export declare const RUNTIME_VERSION = "0.6.8";
+export declare const RUNTIME_VERSION = "0.9.1";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kvyverse/world-runtime",
-	"version": "0.6.8",
+	"version": "0.9.1",
 	"description": "Runtime for worlds exported from the Kvyverse platform for self-hosting",
 	"license": "SEE LICENSE IN LICENSE.md",
 	"author": "Kvyverse, Inc.",
@@ -39,7 +39,7 @@
 		"nipplejs": "^0.10.2",
 		"stats.js": "^0.17.0",
 		"three": "^0.184.0",
-		"three-start": "^0.1.3",
+		"three-start": "^0.2.1",
 		"vanjs-core": "^1.6.0"
 	},
 	"peerDependenciesMeta": {