@kvyverse/world-runtime 0.1.0

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

@@ -0,0 +1,24 @@
+/**
+ * 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).
+ */
+export declare enum LibId {
+    Tween = "tween",
+    Anime = "anime"
+}
+export interface LibDescriptor {
+    readonly id: LibId;
+    /** Key the user gets the lib by: `require("<requireKey>")`. */
+    readonly requireKey: string;
+    readonly label: string;
+}
+export declare const LIBS: Readonly<Record<LibId, LibDescriptor>>;
+export declare const LIB_IDS: LibId[];
+export declare const LIB_DESCRIPTORS: LibDescriptor[];
+export declare function libByRequireKey(requireKey: string): LibDescriptor | undefined;

package/dist/settings/module-registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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`).
+ */
+export declare enum ModuleId {
+    Physics = "physics"
+}
+export type PhysicsEngine = "rapier";
+/** `modules.physics` value: off | engine shorthand | object with options. */
+export type PhysicsConfig = false | PhysicsEngine | {
+    engine: PhysicsEngine;
+    debug?: boolean;
+};
+export declare const PHYSICS_ENGINES: readonly PhysicsEngine[];
+export declare const MODULE_IDS: ModuleId.Physics[];
+/** Normalizes the physics config to an object (or null if disabled). */
+export declare function normalizePhysics(value: PhysicsConfig | undefined): {
+    engine: PhysicsEngine;
+    debug: boolean;
+} | null;

package/dist/settings/types.d.ts

@@ -0,0 +1,46 @@
+import type { ExternalDescriptor } from "./externals";
+import type { LibId } from "./lib-registry";
+import type { PhysicsConfig } from "./module-registry";
+import type { BloomModeName, ShadowMapTypeName, ToneMappingName } from "../rendering/renderer-options";
+/** `settings.addons.json` — pluggable modules, built-in libs, external scripts. */
+export interface AddonsConfig {
+    modules?: {
+        physics?: PhysicsConfig;
+    };
+    libs?: Partial<Record<LibId, boolean>>;
+    externals?: ExternalDescriptor[];
+}
+/** Subset of `WebGPURendererParameters` configurable via the config. */
+export interface RendererParams {
+    antialias?: boolean;
+    alpha?: boolean;
+    depth?: boolean;
+    stencil?: boolean;
+    logarithmicDepthBuffer?: boolean;
+    reverseDepthBuffer?: boolean;
+    preserveDrawingBuffer?: boolean;
+    premultipliedAlpha?: boolean;
+    failIfMajorPerformanceCaveat?: boolean;
+}
+/**
+ * Bloom post-effect. `mode` (default `threshold`): threshold — full-frame by
+ * brightness; emissive — selective via MRT, only emissive materials glow.
+ */
+export interface BloomConfig {
+    enabled?: boolean;
+    mode?: BloomModeName;
+    strength?: number;
+    radius?: number;
+    threshold?: number;
+}
+/** `settings.renderer.json` — WebGPURenderer parameters. */
+export interface RendererConfig {
+    renderer?: RendererParams;
+    pixelResolution?: number;
+    bloom?: BloomConfig;
+    shadowMap?: {
+        enabled?: boolean;
+        type?: ShadowMapTypeName;
+    };
+    toneMapping?: ToneMappingName;
+}

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+import type { Object3DBehaviourConstructor } from "three-start";
+import type { AddonsConfig, RendererConfig } from "./settings/types";
+import type * as THREE from "three/webgpu";
+/** World assets: asset path in the project (`/Folder/name.ext`) → URL. */
+export type AssetUrlTable = Record<string, string>;
+/** User script: the body runs with a context object, returns `output`. */
+export type ScriptModule = (context: Record<string, unknown>) => unknown;
+/** World scripts keyed by the same paths as in `require`. */
+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;
+}
+/** Load-step details for the user's UI. */
+export interface WorldLoadProgress {
+    stage: string;
+    details?: string;
+}
+/**
+ * Runtime API for the generated code: asset resolving, resource factories,
+ * scripts and behaviours. The only object the world hooks receive.
+ */
+export interface RuntimeApi {
+    /** Asset URL by its project path. Same resolving as `getUrl` in scripts. */
+    getUrl: (path: string) => string;
+    /** `require` value by asset path or addon key. */
+    require: (key: string) => unknown;
+    /** Built-in behaviour class by uuid (preloaded by bootstrap). */
+    builtin: (uuid: string) => Object3DBehaviourConstructor;
+}
+/**
+ * A world unrolled by the codegen into imperative code. The artifact supplies
+ * the data and steps; the runtime owns their call order (see `bootstrap.ts`).
+ */
+export interface WorldDefinition<TAssets = unknown> {
+    formatVersion: number;
+    assets: AssetUrlTable;
+    /** Loads world resources; the result is passed to the remaining steps. */
+    loadAssets: (rt: RuntimeApi) => Promise<TAssets>;
+    /**
+     * Scene assembly: object construction, then applying values and attaching
+     * behaviours. Both passes live in one function — forward references
+     * (`$O` to an object created later) are closed by applying values after
+     * all objects are declared.
+     */
+    buildScene: (rt: RuntimeApi, assets: TAssets) => SceneBuildResult;
+    /** Scene settings: background, fog, environment. */
+    applySceneSettings?: (rt: RuntimeApi, scene: THREE.Scene) => void;
+    /** `settings.renderer.json`: renderer params, shadow map, tone mapping, bloom. */
+    renderer?: RendererConfig;
+    /** `settings.addons.json`: built-in libs and external scripts for `require`. */
+    addons?: AddonsConfig;
+    /** User scripts keyed by asset paths — same keys as `require`. */
+    scripts?: ScriptTable;
+    /** Path of the world entry script (`main.ts`). */
+    entryScript?: string;
+    /** Contents of the world's css scripts. */
+    styles?: string[];
+    /** Font asset paths — the runtime mounts their `@font-face` in a single tag. */
+    fontPaths?: string[];
+    /** Uuids of built-in behaviours used by the world: their classes are preloaded
+     * and their required patches are applied before `start()`. */
+    usedBuiltins?: string[];
+}
+/** World load options. */
+export interface LoadWorldOptions {
+    /**
+     * Prefix for relative paths in the asset table. Not needed when assets
+     * stay on the Kvyverse CDN (the table contains absolute URLs).
+     */
+    assetsBaseUrl?: string;
+    /**
+     * Folder with the draco decoder for compressed models. Defaults to the
+     * public Google decoder; set your own if you host the decoder yourself
+     * (offline, CSP).
+     */
+    dracoPath?: string;
+    onProgress?: (progress: WorldLoadProgress) => void;
+}

package/dist/utils/lazy.d.ts

@@ -0,0 +1,4 @@
+/** Lazy cached value: the factory is called once on the first `get()`. */
+export declare function lazy<T>(factory: () => T): {
+    get: () => T;
+};

package/dist/values.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Writes a color into an object field, creating a `Color` if the slot is empty.
+ * Mirrors the `$C` branch of `applyValues` — needed by generated code for fields
+ * like `scene.background` that may be `null`.
+ */
+export declare function setColor(target: object, key: string, hex: string | number): void;

package/dist/version.d.ts

@@ -0,0 +1,10 @@
+export { RUNTIME_VERSION } from "./version.gen";
+/**
+ * Format version of the generated world. The codegen stamps it into the artifact,
+ * the runtime checks it on load. A breaking format change = package major bump.
+ * Not to be confused with {@link RUNTIME_VERSION} — the package's own version
+ * (from package.json, generated into version.gen.ts by gen-runtime-version).
+ */
+export declare const WORLD_FORMAT_VERSION = 1;
+/** Throws if the artifact was built by an incompatible generator version. */
+export declare function assertFormatVersion(version: number): void;

package/dist/version.gen.d.ts

@@ -0,0 +1 @@
+export declare const RUNTIME_VERSION = "0.1.0";

package/dist/world-events.d.ts

@@ -0,0 +1,13 @@
+/**
+ * World lifecycle events, emitted on `game.emitter` (`world.events` in scripts)
+ * during classic-load. The entry script runs BEFORE them (step 9) — subscriptions
+ * from `main.ts` catch all three. See `docs/scripting/game-runtime.md`.
+ */
+export declare enum WorldEvent {
+    /** Scene parsed, values applied; objects are NOT yet added to `ctx.scene`. */
+    BeforeSceneReady = "before-scene-ready",
+    /** Hierarchy added to `ctx.scene` — scene is ready; lifecycle not started yet. */
+    SceneReady = "scene-ready",
+    /** `start()` called: behaviours woke up, the render loop is running. */
+    Started = "started"
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@kvyverse/world-runtime",
+	"version": "0.1.0",
+	"description": "Runtime for worlds exported from the Kvyverse platform for self-hosting",
+	"license": "SEE LICENSE IN LICENSE.md",
+	"author": "Vladislav Kruteniuk",
+	"homepage": "https://kvyverse.com",
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE.md"
+	],
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "vite build && tsc -p tsconfig.build.json",
+		"typecheck": "tsc -p tsconfig.build.json --noEmit",
+		"prepublishOnly": "node -e \"require('fs').accessSync('dist/index.js')\" || (echo 'run npm run build:world-runtime from repo root first' && exit 1)"
+	},
+	"peerDependencies": {
+		"@dimforge/rapier3d-compat": "0.19.3",
+		"@tweenjs/tween.js": "^25.0.0",
+		"animejs": "^4.5.0",
+		"eventemitter3": "^5.0.1",
+		"howler": "^2.2.4",
+		"three": "^0.184.0",
+		"three-start": "^0.1.2",
+		"vanjs-core": "^1.6.0"
+	},
+	"peerDependenciesMeta": {
+		"@dimforge/rapier3d-compat": {
+			"optional": true
+		},
+		"@tweenjs/tween.js": {
+			"optional": true
+		},
+		"animejs": {
+			"optional": true
+		}
+	}
+}