@kvyverse/world-runtime 0.7.0 → 0.10.0

package/README.md

@@ -73,14 +73,23 @@ pointer, call `start()` from a user gesture — browsers require it.
 
 ### The `world` object
 
-`World` extends `ThreeStart` from `three-start`, so the usual lifecycle and
-context are yours:
+`World` extends `ThreeStart` from `three-start` (0.3 or newer), so the usual
+lifecycle and context are yours. An exception in a behaviour or module hook, or
+in a `world.ctx` listener, doesn't stop the world: three-start logs it to the
+console, or hands it to your `world.ctx.on(ThreeContextEvents.Error, (error,
+source, hook) => …)` listener if you add one.
 
 ```js
 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,7 +27,7 @@ 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";

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.7.0";
+var RUNTIME_VERSION = "0.10.0";
 //#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();
@@ -2208,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, 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, isMobileDevice, isUniformType, lazyProxy, libByRequireKey, loadGeometry, loadHdr, loadModel, loadTexture, normalizeChat, normalizePhysics, parseGeometryJson, parseHdr, parseModel, rapierPhysicsPatch, readMaterialShaderOutputs, setColor, setUniformNodeValue, 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/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/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.7.0";
+export declare const RUNTIME_VERSION = "0.10.0";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kvyverse/world-runtime",
-	"version": "0.7.0",
+	"version": "0.10.0",
 	"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.3.1",
 		"vanjs-core": "^1.6.0"
 	},
 	"peerDependenciesMeta": {