@kite3d/engine 0.15.0

package/dist/projectFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectFormat.js","sources":["../src/runtime/projectFormat.ts"],"sourcesContent":["import {parse, ParseError} from 'jsonc-parser'\n\nexport const settingsKey = 'kite3d'\nexport const assetUrlPrefix = `/${settingsKey}/`\n\nexport type JSONValue = string | number | boolean | null | JSONValue[] | {[key: string]: JSONValue}\nexport type ProjectPackageJSON = Record<string, JSONValue> & {mainScene: string}\n\nexport interface ProjectGeneratorState {\n    componentId: string\n    module: string\n    nodeIndex: number\n    nodeName: string\n    params: Record<string, unknown>\n}\n\nexport interface AssetsJSONManifest {\n    files: Record<string, {\n        path: string\n    }>\n    version: number\n}\n\nexport interface ProjectDependency {\n    key: string\n    version: string\n    url?: string\n}\n\nexport interface ExternalPlugin {\n    import: string\n    /** @default `default` */\n    className?: string\n    /** @default true */\n    active?: boolean\n    /** Constructor parameters. */\n    params?: JSONValue[]\n}\n\nexport interface ExternalScript {\n    import: string\n    /** @default true */\n    active?: boolean\n}\n\nexport interface ProjectViewerSettings {\n    msaa?: boolean\n    rgbm?: boolean\n    zPrepass?: boolean\n    renderScale?: number | 'auto'\n    maxRenderScale?: number\n    backgroundColor?: string | number | null\n    modelRootScale?: number\n    stencil?: boolean\n    debug?: boolean\n    tonemap?: boolean\n    camera?: {\n        type?: 'perspective' | 'orthographic'\n        controlsMode?: string\n        position?: [number, number, number]\n        target?: [number, number, number]\n    }\n    maxHDRIntensity?: number\n    powerPreference?: 'default' | 'high-performance' | 'low-power'\n}\n\nexport interface ProjectConfigSettings {\n    plugins: ExternalPlugin[]\n    scripts: ExternalScript[]\n    dependencies: ProjectDependency[]\n    viewer: ProjectViewerSettings\n}\n\nexport interface ProjectConfigSettingsJSON {\n    plugins?: (ExternalPlugin | string)[]\n    imports?: Record<string, string>\n    scripts?: (ExternalScript | string)[]\n    viewer?: ProjectViewerSettings\n}\n\n/** A configured script or plugin is package-backed only when it names a declared dependency exactly. */\nexport function isDependencyModuleSpecifier(\n    specifier: string,\n    packageJson: ProjectPackageJSON,\n): boolean {\n    const dependencies = packageJson.dependencies\n    return isRecord(dependencies) && Object.prototype.hasOwnProperty.call(dependencies, specifier)\n}\n\nexport function parsePackageJSON(text: string): ProjectPackageJSON {\n    const json = parse(text) as unknown\n    if (!json || typeof json !== 'object' || Array.isArray(json)) {\n        throw new Error('Invalid package.json file: expected an object')\n    }\n    const packageJson = json as ProjectPackageJSON\n    if (typeof packageJson.mainScene !== 'string' || !packageJson.mainScene.toLowerCase().endsWith('.gltf')) {\n        throw new Error('package.json mainScene must name a text .gltf file')\n    }\n    return packageJson\n}\n\nexport function parseAssetsJSONManifest(text: string): AssetsJSONManifest {\n    const json = parse(text) as AssetsJSONManifest\n\n    if (json.files && typeof json.files !== 'object') {\n        throw new Error('Invalid assets.json file: files should be an object')\n    }\n    if (json.version !== undefined && typeof json.version !== 'number') {\n        throw new Error('Invalid assets.json file: version should be a number')\n    }\n\n    if (!json.files) json.files = {}\n    if (!json.version) json.version = 1\n\n    return json\n}\n\nexport function validateSceneSource(path: string, text: string): void {\n    const document = JSON.parse(text) as {asset?: unknown}\n    if (!document || typeof document !== 'object' || !document.asset) {\n        throw new Error(`${path} is not a JSON glTF document`)\n    }\n}\n\nexport function readProjectGeneratorStates(text: string): ProjectGeneratorState[] {\n    try {\n        const document = JSON.parse(text) as {\n            nodes?: Array<{\n                name?: unknown\n                extras?: {EntityComponentPlugin?: Record<string, {type?: unknown, state?: unknown}>}\n            }>\n        }\n        const generators: ProjectGeneratorState[] = []\n        for (const [nodeIndex, node] of (document.nodes || []).entries()) {\n            for (const [componentId, component] of Object.entries(node.extras?.EntityComponentPlugin || {})) {\n                if (component.type !== 'Generator' || !isRecord(component.state)) continue\n                generators.push({\n                    componentId,\n                    module: typeof component.state.module === 'string' ? component.state.module : '',\n                    nodeIndex,\n                    nodeName: typeof node.name === 'string' ? node.name : `Node ${nodeIndex}`,\n                    params: isRecord(component.state.params) ? component.state.params : {},\n                })\n            }\n        }\n        return generators\n    } catch {\n        return []\n    }\n}\n\nexport function updateProjectGeneratorState(\n    text: string,\n    generator: Pick<ProjectGeneratorState, 'componentId' | 'nodeIndex' | 'nodeName'>,\n    update: Partial<Pick<ProjectGeneratorState, 'module' | 'params'>>,\n): {text: string, state: Record<string, unknown>} {\n    const document = JSON.parse(text) as {\n        nodes?: Array<{extras?: {EntityComponentPlugin?: Record<string, {state?: unknown}>}}>\n    }\n    const state = document.nodes?.[generator.nodeIndex]?.extras?.EntityComponentPlugin?.[generator.componentId]?.state\n    if (!isRecord(state)) throw new Error(`Generator component is missing on ${generator.nodeName}`)\n    Object.assign(state, update)\n    return {text: JSON.stringify(document, null, 2), state}\n}\n\nexport async function parsePackageJsonSettingsConfig(json: ProjectPackageJSON, _project?: unknown): Promise<ProjectConfigSettings> {\n    const config = (json[settingsKey] ?? {}) as ProjectConfigSettingsJSON\n    const dependencies: ProjectDependency[] = []\n    const packageDependencies = json.dependencies && typeof json.dependencies === 'object' && !Array.isArray(json.dependencies)\n        ? json.dependencies as Record<string, string>\n        : {}\n    const deps: Record<string, string> = {\n        ...packageDependencies,\n    }\n\n    dependencies.push(...Object.entries(deps).map(([key, version]) => ({key, version})))\n\n    if (config.imports) {\n        dependencies.push(...Object.entries(config.imports).map(([key, url]) => ({\n            key,\n            url: !url.startsWith('@') ? url : undefined,\n            version: url.startsWith('@') ? url.slice(1) : '',\n        })))\n    }\n\n    const plugins = config.plugins?.map((entry) => {\n        if (typeof entry !== 'string') return entry\n\n        const match = entry.match(/\\((.*)\\)$/)\n        let params: JSONValue[] | undefined\n        let spec = entry\n\n        if (match) {\n            const paramString = match[1].trim()\n            spec = entry.slice(0, match.index).trim()\n            if (paramString) {\n                try {\n                    const errors: ParseError[] = []\n                    params = parse(`[${paramString}]`, errors)\n                    if (!Array.isArray(params) || errors.length) {\n                        console.error(errors)\n                        throw new Error('Plugin params is not a valid array')\n                    }\n                } catch (error) {\n                    console.error('Unable to parse plugin params, skipping plugin', entry, paramString, error)\n                    return null\n                }\n            }\n        }\n\n        const separator = spec.lastIndexOf(':')\n        return {\n            import: separator !== -1 ? spec.slice(0, separator) : spec,\n            className: separator !== -1 ? spec.slice(separator + 1) : undefined,\n            params,\n        } satisfies ExternalPlugin\n    }) || []\n\n    const scripts = config.scripts?.map((entry) =>\n        typeof entry === 'string' ? {import: entry} : entry\n    ) || []\n\n    return {\n        plugins: plugins.filter(Boolean) as ExternalPlugin[],\n        scripts,\n        dependencies,\n        viewer: config.viewer || {},\n    }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n    return Boolean(value) && typeof value === 'object' && !Array.isArray(value)\n}\n"],"names":["settingsKey","assetUrlPrefix","isDependencyModuleSpecifier","specifier","packageJson","dependencies","isRecord","parsePackageJSON","text","json","parse","parseAssetsJSONManifest","validateSceneSource","path","document","readProjectGeneratorStates","generators","nodeIndex","node","componentId","component","_a","updateProjectGeneratorState","generator","update","state","_e","_d","_c","_b","parsePackageJsonSettingsConfig","_project","config","deps","key","version","url","plugins","entry","match","params","spec","paramString","errors","error","separator","scripts","value"],"mappings":"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"}

package/dist/runtime/createGame.d.ts

@@ -0,0 +1,29 @@
+import { ThreeViewer } from 'threepipe';
+import { GameValidationFunction, GameValidationReport, RuntimeCleanupReport } from '../authoringValidation.ts';
+import { AssetsJSONManifest, ProjectPackageJSON, ProjectConfigSettings } from './projectFormat.ts';
+export interface CreateGameOptions {
+    base: string;
+    canvas: HTMLCanvasElement;
+    onError?: (error: unknown) => void;
+    /** Content hashes for cache-safe project module imports in development. */
+    fileRevisions?: Readonly<Record<string, string>>;
+    /** Identifies one module-graph load so transitive imports bypass the browser module map together. */
+    moduleRevision?: string;
+}
+export interface RuntimeProject {
+    packageJson: ProjectPackageJSON;
+    config: ProjectConfigSettings;
+    assetsManifest: AssetsJSONManifest;
+    mainScene: string;
+}
+export interface CreatedGame {
+    viewer: ThreeViewer;
+    project: RuntimeProject;
+    registerGameValidation(fn: GameValidationFunction): () => void;
+    publishGameTelemetry(value: object): () => void;
+    runGameValidation(): Promise<GameValidationReport>;
+    dispose(): RuntimeCleanupReport;
+}
+export declare function createGame(options: CreateGameOptions): Promise<CreatedGame>;
+/** Load the saved project and generator previews without starting components, physics, the timeline, or main.js. */
+export declare function createStoppedGame(options: CreateGameOptions): Promise<CreatedGame>;

package/dist/runtime/index.d.ts

@@ -0,0 +1,18 @@
+export { createGame, createStoppedGame } from './createGame.ts';
+export type { CreatedGame, CreateGameOptions, RuntimeProject } from './createGame.ts';
+export { RUNTIME_VERSION } from './version.ts';
+export * from './projectFormat.ts';
+export * from './migrations.ts';
+export { RuntimeNestedAssetLoader } from './nestedAssets.ts';
+export { registerScripts, walkScriptExports } from '../scripts.ts';
+export { HtmlUiComponent } from '../plugins/HtmlUiComponent.ts';
+export { GeneratorComponent, markGenerated, removeGeneratedChildren, resolveGeneratorModule, runGenerator } from '../plugins/GeneratorComponent.ts';
+export type { GeneratorContext, GeneratorModule, GeneratorParams, GeneratorViewerOptions, RunGeneratorOptions } from '../plugins/GeneratorComponent.ts';
+export { CannonPhysicsPlugin } from '../plugins/cannon/CannonPhysicsPlugin.ts';
+export { serializeSceneGltf, serializeSceneGltfDocument } from '../sceneSerialization.ts';
+export type { SerializeSceneGltfOptions, SerializedSceneFile, SerializedSceneGltf } from '../sceneSerialization.ts';
+export * from '../authoring.ts';
+export * from '../authoringValidation.ts';
+export * from 'threepipe';
+export * from 'uiconfig.js';
+export * from 'ts-browser-helpers';

package/dist/runtime/migrations.d.ts

@@ -0,0 +1,5 @@
+export interface ProjectMigration {
+    version: string;
+    migrate(projectRoot: string): void | Promise<void>;
+}
+export declare const PROJECT_MIGRATIONS: readonly ProjectMigration[];

package/dist/runtime/nestedAssets.d.ts

@@ -0,0 +1,26 @@
+import { IObject3D, ThreeViewer } from 'threepipe';
+type RuntimeErrorHandler = (error: unknown) => void;
+/**
+ * Loads the embedded rootPath references written by the editor's AssetTracker.
+ * This is deliberately runtime-only: it keeps root overrides, but has no file
+ * watching, picking, export hooks, refresh subscriptions, or editor registry.
+ */
+export declare class RuntimeNestedAssetLoader {
+    private readonly viewer;
+    private readonly onError;
+    private readonly importer;
+    private readonly cache;
+    private readonly pending;
+    constructor(viewer: ThreeViewer, onError: RuntimeErrorHandler);
+    dispose(): void;
+    loadObjectDependencies(object: IObject3D): Promise<void>;
+    waitForPending(): Promise<void>;
+    private readonly onProcessRaw;
+    private isEmbeddedReference;
+    private loadAsset;
+    private loadReference;
+    private updateObject;
+    private updateMaterial;
+    private track;
+}
+export {};

package/dist/runtime/projectFormat.d.ts

@@ -0,0 +1,83 @@
+export declare const settingsKey = "kite3d";
+export declare const assetUrlPrefix = "/kite3d/";
+export type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+export type ProjectPackageJSON = Record<string, JSONValue> & {
+    mainScene: string;
+};
+export interface ProjectGeneratorState {
+    componentId: string;
+    module: string;
+    nodeIndex: number;
+    nodeName: string;
+    params: Record<string, unknown>;
+}
+export interface AssetsJSONManifest {
+    files: Record<string, {
+        path: string;
+    }>;
+    version: number;
+}
+export interface ProjectDependency {
+    key: string;
+    version: string;
+    url?: string;
+}
+export interface ExternalPlugin {
+    import: string;
+    /** @default `default` */
+    className?: string;
+    /** @default true */
+    active?: boolean;
+    /** Constructor parameters. */
+    params?: JSONValue[];
+}
+export interface ExternalScript {
+    import: string;
+    /** @default true */
+    active?: boolean;
+}
+export interface ProjectViewerSettings {
+    msaa?: boolean;
+    rgbm?: boolean;
+    zPrepass?: boolean;
+    renderScale?: number | 'auto';
+    maxRenderScale?: number;
+    backgroundColor?: string | number | null;
+    modelRootScale?: number;
+    stencil?: boolean;
+    debug?: boolean;
+    tonemap?: boolean;
+    camera?: {
+        type?: 'perspective' | 'orthographic';
+        controlsMode?: string;
+        position?: [number, number, number];
+        target?: [number, number, number];
+    };
+    maxHDRIntensity?: number;
+    powerPreference?: 'default' | 'high-performance' | 'low-power';
+}
+export interface ProjectConfigSettings {
+    plugins: ExternalPlugin[];
+    scripts: ExternalScript[];
+    dependencies: ProjectDependency[];
+    viewer: ProjectViewerSettings;
+}
+export interface ProjectConfigSettingsJSON {
+    plugins?: (ExternalPlugin | string)[];
+    imports?: Record<string, string>;
+    scripts?: (ExternalScript | string)[];
+    viewer?: ProjectViewerSettings;
+}
+/** A configured script or plugin is package-backed only when it names a declared dependency exactly. */
+export declare function isDependencyModuleSpecifier(specifier: string, packageJson: ProjectPackageJSON): boolean;
+export declare function parsePackageJSON(text: string): ProjectPackageJSON;
+export declare function parseAssetsJSONManifest(text: string): AssetsJSONManifest;
+export declare function validateSceneSource(path: string, text: string): void;
+export declare function readProjectGeneratorStates(text: string): ProjectGeneratorState[];
+export declare function updateProjectGeneratorState(text: string, generator: Pick<ProjectGeneratorState, 'componentId' | 'nodeIndex' | 'nodeName'>, update: Partial<Pick<ProjectGeneratorState, 'module' | 'params'>>): {
+    text: string;
+    state: Record<string, unknown>;
+};
+export declare function parsePackageJsonSettingsConfig(json: ProjectPackageJSON, _project?: unknown): Promise<ProjectConfigSettings>;

package/dist/runtime/version.d.ts

@@ -0,0 +1 @@
+export declare const RUNTIME_VERSION: string;