@kite3d/engine 0.15.0

package/src/runtime/nestedAssets.ts

@@ -0,0 +1,226 @@
+import {
+    copyObject3DUserData,
+    getPartialProps,
+    IMaterial,
+    ImportResult,
+    ImportResultExtras,
+    IObject3D,
+    Quaternion,
+    setPartialProps,
+    ThreeViewer,
+    Vector3,
+} from 'threepipe'
+
+type RuntimeErrorHandler = (error: unknown) => void
+
+const defaultObjectOverrides = ['visible', 'name', 'position', 'quaternion', 'scale']
+const defaultMaterialOverrides = ['name']
+const objectProperties: (keyof IObject3D)[] = [
+    'position',
+    'quaternion',
+    'scale',
+    'visible',
+    'castShadow',
+    'receiveShadow',
+    'frustumCulled',
+    'renderOrder',
+]
+
+/**
+ * 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 class RuntimeNestedAssetLoader {
+    private readonly importer: ThreeViewer['assetManager']['importer']
+    private readonly cache = new Map<string, Promise<ImportResult | undefined>>()
+    private readonly pending = new Set<Promise<void>>()
+
+    constructor(
+        private readonly viewer: ThreeViewer,
+        private readonly onError: RuntimeErrorHandler,
+    ) {
+        this.importer = viewer.assetManager.importer
+        this.importer.addEventListener('processRaw', this.onProcessRaw)
+    }
+
+    dispose() {
+        this.importer.removeEventListener('processRaw', this.onProcessRaw)
+        this.cache.clear()
+        this.pending.clear()
+    }
+
+    async loadObjectDependencies(object: IObject3D): Promise<void> {
+        if (!object.traverse) return
+
+        const objects: IObject3D[] = []
+        const materials = new Set<IMaterial>()
+        object.traverse((child: IObject3D) => {
+            objects.push(child)
+            const material = (child as IObject3D & {material?: IMaterial | IMaterial[]}).material
+            if (material) {
+                const entries = Array.isArray(material) ? material : [material]
+                entries.forEach((entry) => entry?.isMaterial && materials.add(entry))
+            }
+        })
+
+        const loads: Promise<void>[] = []
+        for (const child of objects) {
+            if (!this.isEmbeddedReference(child)) continue
+            if (child._loadingPromise) {
+                loads.push(child._loadingPromise.then(() => undefined))
+                continue
+            }
+
+            if (!(child.userData.sProperties as string[]).length) {
+                child.userData.sProperties = [...defaultObjectOverrides]
+            }
+            child._sChildren ||= []
+            const load = this.loadReference(child)
+            child._loadingPromise = load
+            loads.push(load)
+        }
+
+        for (const material of materials) {
+            if (!this.isEmbeddedReference(material)) continue
+            if (material._loadingPromise) {
+                loads.push(material._loadingPromise.then(() => undefined))
+                continue
+            }
+
+            if (!(material.userData.sProperties as string[]).length) {
+                material.userData.sProperties = [...defaultMaterialOverrides]
+            }
+            const load = this.loadReference(material)
+            material._loadingPromise = load
+            loads.push(load)
+        }
+
+        if (!loads.length) return
+        const loading = Promise.allSettled(loads).then((results) => {
+            for (const result of results) {
+                if (result.status === 'rejected') this.onError(result.reason)
+            }
+        })
+        object._loadingPromise = loading
+        this.track(loading)
+        await loading
+    }
+
+    async waitForPending(): Promise<void> {
+        while (this.pending.size) {
+            await Promise.all([...this.pending])
+        }
+    }
+
+    private readonly onProcessRaw = (event: {data?: ImportResult}) => {
+        const object = event.data
+        if (!object?.isObject3D) return
+        const loading = this.loadObjectDependencies(object as IObject3D)
+        this.track(loading)
+    }
+
+    private isEmbeddedReference(value: IObject3D | IMaterial): boolean {
+        const rootPath = value.userData?.rootPath
+        return typeof rootPath === 'string'
+            && !(value as ImportResultExtras).__rootPath
+            && !value.userData.rootPathRefresh
+            && Array.isArray(value.userData.sProperties)
+    }
+
+    private loadAsset(path: string, options: Record<string, unknown> | undefined) {
+        let loading = this.cache.get(path)
+        if (!loading) {
+            loading = this.importer.importSingle(path, options || {})
+            this.cache.set(path, loading)
+        }
+        return loading
+    }
+
+    private async loadReference(target: IObject3D | IMaterial): Promise<void> {
+        const path = target.userData.rootPath as string
+        const imported = await this.loadAsset(path, target.userData.rootPathOptions)
+        if (!imported) throw new Error(`Unable to load nested asset from ${path}`)
+        if (imported._loadingPromise) await imported._loadingPromise
+
+        const targetObject = target as IObject3D
+        const targetMaterial = target as IMaterial
+        if (targetObject.isObject3D && imported.isObject3D) {
+            this.updateObject(imported as IObject3D, targetObject)
+            return
+        }
+        if (targetMaterial.isMaterial && imported.isMaterial) {
+            this.updateMaterial(imported as IMaterial, targetMaterial)
+            return
+        }
+        throw new Error(`Nested asset at ${path} does not match its reference type`)
+    }
+
+    private updateObject(source: IObject3D, target: IObject3D) {
+        if (target._sChildren) {
+            for (const child of [...target.children]) {
+                if (!target._sChildren.includes(child)) child.removeFromParent()
+            }
+        }
+
+        for (const child of source.children) {
+            const clone = cloneObject(child)
+            clone.userData.excludeFromExport = true
+            target.add(clone)
+        }
+
+        const overrideProperties = target.userData.sProperties as string[]
+        const name = target.name
+        const visible = target.visible
+        for (const property of objectProperties) {
+            if (overrideProperties.includes(property)) continue
+            const value = source[property]
+            const current = target[property]
+            if (value && current && (value as Vector3).isVector3) {
+                (current as Vector3).copy(value as Vector3)
+            } else if (value && current && (value as Quaternion).isQuaternion) {
+                (current as Quaternion).copy(value as Quaternion)
+            } else if (value !== undefined) {
+                Object.assign(target, {[property]: value})
+            }
+        }
+
+        const targetUserData = target.userData
+        target.userData = {}
+        copyObject3DUserData(target.userData, source.userData, ['uuid', 'sProperties'])
+        Object.assign(target.userData, targetUserData)
+        target.name = name
+        target.visible = visible
+        target.userData.uuid = target.uuid
+        target.userData.sProperties = overrideProperties
+        target.setDirty?.({source: 'RuntimeNestedAssetLoader'})
+    }
+
+    private updateMaterial(source: IMaterial, target: IMaterial) {
+        const overrideProperties = target.userData.sProperties as string[]
+        const overrides = getPartialProps(target, overrideProperties)
+        const name = target.name
+        target.setValues(source)
+        target.name = name
+        setPartialProps(overrides, target)
+        target.userData.uuid = target.uuid
+        target.userData.sProperties = overrideProperties
+    }
+
+    private track(promise: Promise<void>) {
+        this.pending.add(promise)
+        const remove = () => this.pending.delete(promise)
+        promise.then(remove, remove)
+    }
+}
+
+function cloneObject(source: IObject3D): IObject3D {
+    const clone = source.clone(false) as IObject3D
+    const sourceRoot = source as IObject3D & {_tpRootPath?: string, _tpRootUid?: string}
+    const cloneRoot = clone as IObject3D & {_tpRootPath?: string, _tpRootUid?: string}
+    cloneRoot._tpRootPath = sourceRoot._tpRootPath
+    cloneRoot._tpRootUid = sourceRoot._tpRootUid || source.uuid
+    delete clone.userData.cloneParent
+    for (const child of source.children) clone.add(cloneObject(child))
+    return clone
+}

package/src/runtime/projectFormat.ts

@@ -0,0 +1,233 @@
+import {parse, ParseError} from 'jsonc-parser'
+
+export const settingsKey = 'kite3d'
+export const assetUrlPrefix = `/${settingsKey}/`
+
+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 function isDependencyModuleSpecifier(
+    specifier: string,
+    packageJson: ProjectPackageJSON,
+): boolean {
+    const dependencies = packageJson.dependencies
+    return isRecord(dependencies) && Object.prototype.hasOwnProperty.call(dependencies, specifier)
+}
+
+export function parsePackageJSON(text: string): ProjectPackageJSON {
+    const json = parse(text) as unknown
+    if (!json || typeof json !== 'object' || Array.isArray(json)) {
+        throw new Error('Invalid package.json file: expected an object')
+    }
+    const packageJson = json as ProjectPackageJSON
+    if (typeof packageJson.mainScene !== 'string' || !packageJson.mainScene.toLowerCase().endsWith('.gltf')) {
+        throw new Error('package.json mainScene must name a text .gltf file')
+    }
+    return packageJson
+}
+
+export function parseAssetsJSONManifest(text: string): AssetsJSONManifest {
+    const json = parse(text) as AssetsJSONManifest
+
+    if (json.files && typeof json.files !== 'object') {
+        throw new Error('Invalid assets.json file: files should be an object')
+    }
+    if (json.version !== undefined && typeof json.version !== 'number') {
+        throw new Error('Invalid assets.json file: version should be a number')
+    }
+
+    if (!json.files) json.files = {}
+    if (!json.version) json.version = 1
+
+    return json
+}
+
+export function validateSceneSource(path: string, text: string): void {
+    const document = JSON.parse(text) as {asset?: unknown}
+    if (!document || typeof document !== 'object' || !document.asset) {
+        throw new Error(`${path} is not a JSON glTF document`)
+    }
+}
+
+export function readProjectGeneratorStates(text: string): ProjectGeneratorState[] {
+    try {
+        const document = JSON.parse(text) as {
+            nodes?: Array<{
+                name?: unknown
+                extras?: {EntityComponentPlugin?: Record<string, {type?: unknown, state?: unknown}>}
+            }>
+        }
+        const generators: ProjectGeneratorState[] = []
+        for (const [nodeIndex, node] of (document.nodes || []).entries()) {
+            for (const [componentId, component] of Object.entries(node.extras?.EntityComponentPlugin || {})) {
+                if (component.type !== 'Generator' || !isRecord(component.state)) continue
+                generators.push({
+                    componentId,
+                    module: typeof component.state.module === 'string' ? component.state.module : '',
+                    nodeIndex,
+                    nodeName: typeof node.name === 'string' ? node.name : `Node ${nodeIndex}`,
+                    params: isRecord(component.state.params) ? component.state.params : {},
+                })
+            }
+        }
+        return generators
+    } catch {
+        return []
+    }
+}
+
+export function updateProjectGeneratorState(
+    text: string,
+    generator: Pick<ProjectGeneratorState, 'componentId' | 'nodeIndex' | 'nodeName'>,
+    update: Partial<Pick<ProjectGeneratorState, 'module' | 'params'>>,
+): {text: string, state: Record<string, unknown>} {
+    const document = JSON.parse(text) as {
+        nodes?: Array<{extras?: {EntityComponentPlugin?: Record<string, {state?: unknown}>}}>
+    }
+    const state = document.nodes?.[generator.nodeIndex]?.extras?.EntityComponentPlugin?.[generator.componentId]?.state
+    if (!isRecord(state)) throw new Error(`Generator component is missing on ${generator.nodeName}`)
+    Object.assign(state, update)
+    return {text: JSON.stringify(document, null, 2), state}
+}
+
+export async function parsePackageJsonSettingsConfig(json: ProjectPackageJSON, _project?: unknown): Promise<ProjectConfigSettings> {
+    const config = (json[settingsKey] ?? {}) as ProjectConfigSettingsJSON
+    const dependencies: ProjectDependency[] = []
+    const packageDependencies = json.dependencies && typeof json.dependencies === 'object' && !Array.isArray(json.dependencies)
+        ? json.dependencies as Record<string, string>
+        : {}
+    const deps: Record<string, string> = {
+        ...packageDependencies,
+    }
+
+    dependencies.push(...Object.entries(deps).map(([key, version]) => ({key, version})))
+
+    if (config.imports) {
+        dependencies.push(...Object.entries(config.imports).map(([key, url]) => ({
+            key,
+            url: !url.startsWith('@') ? url : undefined,
+            version: url.startsWith('@') ? url.slice(1) : '',
+        })))
+    }
+
+    const plugins = config.plugins?.map((entry) => {
+        if (typeof entry !== 'string') return entry
+
+        const match = entry.match(/\((.*)\)$/)
+        let params: JSONValue[] | undefined
+        let spec = entry
+
+        if (match) {
+            const paramString = match[1].trim()
+            spec = entry.slice(0, match.index).trim()
+            if (paramString) {
+                try {
+                    const errors: ParseError[] = []
+                    params = parse(`[${paramString}]`, errors)
+                    if (!Array.isArray(params) || errors.length) {
+                        console.error(errors)
+                        throw new Error('Plugin params is not a valid array')
+                    }
+                } catch (error) {
+                    console.error('Unable to parse plugin params, skipping plugin', entry, paramString, error)
+                    return null
+                }
+            }
+        }
+
+        const separator = spec.lastIndexOf(':')
+        return {
+            import: separator !== -1 ? spec.slice(0, separator) : spec,
+            className: separator !== -1 ? spec.slice(separator + 1) : undefined,
+            params,
+        } satisfies ExternalPlugin
+    }) || []
+
+    const scripts = config.scripts?.map((entry) =>
+        typeof entry === 'string' ? {import: entry} : entry
+    ) || []
+
+    return {
+        plugins: plugins.filter(Boolean) as ExternalPlugin[],
+        scripts,
+        dependencies,
+        viewer: config.viewer || {},
+    }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}

package/src/runtime/version.ts

@@ -0,0 +1,3 @@
+import enginePackage from '../../package.json'
+
+export const RUNTIME_VERSION = enginePackage.version