@kite3d/engine 0.18.0 → 0.19.0-alpha.1

package/src/sceneSerialization.ts

@@ -1,4 +1,4 @@
-import type {ThreeViewer} from 'threepipe'
+import type {IObject3D, ThreeViewer} from 'threepipe'
 
 export interface SerializeSceneGltfOptions {
     scenePath?: string
@@ -51,13 +51,21 @@ export async function serializeSceneGltf(
         preserveUUIDs: true,
         viewerConfig: true,
         embedUrlImages: false,
-        onlyVisible: true,
+        onlyVisible: false,
+        shouldExportObject: isAuthoredSceneObject,
         jsonSpaces: 2,
     }, false)
     if (!blob) throw new Error('The scene exporter returned no glTF data')
     return serializeSceneGltfDocument(JSON.parse(await blob.text()), options)
 }
 
+function isAuthoredSceneObject(object: IObject3D): boolean {
+    return object.userData?.excludeFromExport !== true
+        && object.userData?.isWidgetRoot !== true
+        && object.isWidget !== true
+        && object.assetType !== 'widget'
+}
+
 /** Canonicalize JSON glTF and extract every embedded resource. */
 export async function serializeSceneGltfDocument(
     input: unknown,

package/dist/generatorParams.d.ts

@@ -1,23 +0,0 @@
-export declare const generatorParamTypes: readonly ["boolean", "number", "integer", "string", "select", "vector", "color", "json"];
-export type GeneratorParamType = typeof generatorParamTypes[number];
-export type GeneratorParamOption = string | number | {
-    value: string | number;
-    label: string;
-};
-export interface GeneratorParamDefinition {
-    type?: GeneratorParamType;
-    label?: string;
-    help?: string;
-    default?: unknown;
-    options?: GeneratorParamOption[];
-    min?: number;
-    max?: number;
-    step?: number;
-}
-export interface GeneratorParamSchemaEntry extends Omit<GeneratorParamDefinition, 'type'> {
-    type: GeneratorParamType;
-}
-export type GeneratorParamSchema = Record<string, GeneratorParamSchemaEntry>;
-export declare function parseGeneratorParamsSchema(exported: unknown, module: string, warn?: (message: string) => void): GeneratorParamSchema;
-export declare function inferGeneratorParam(value: unknown): GeneratorParamSchemaEntry;
-export declare function validateGeneratorParam(value: unknown, entry: GeneratorParamSchemaEntry): string | undefined;

package/dist/plugins/GeneratorComponent.d.ts

@@ -1,44 +0,0 @@
-import { ComponentDefn, IObject3D, Object3DComponent, ThreeViewer } from 'threepipe';
-import { GeneratorParamDefinition, GeneratorParamSchema } from '../generatorParams.ts';
-export interface GeneratorParams {
-    [key: string]: unknown;
-}
-export interface GeneratorContext {
-    node: IObject3D;
-    params: GeneratorParams;
-    viewer: ThreeViewer;
-    engine: Record<string, unknown>;
-}
-export interface GeneratorModule {
-    default?: (context: GeneratorContext) => unknown | Promise<unknown>;
-    params?: Record<string, GeneratorParamDefinition>;
-}
-export interface GeneratorViewerOptions {
-    base: string | URL;
-    onError?: (error: unknown) => void;
-}
-export declare class GeneratorComponent extends Object3DComponent {
-    static ComponentType: string;
-    static StateProperties: ComponentDefn['StateProperties'];
-    module: string;
-    params: GeneratorParams;
-    schema: GeneratorParamSchema;
-    private runRevision;
-    static configureViewer(viewer: ThreeViewer, options: GeneratorViewerOptions): void;
-    static waitForViewer(viewer: ThreeViewer): Promise<void>;
-    init(object: IObject3D, state: Record<string, unknown>): void;
-    run(): Promise<void>;
-    bake(): Promise<number>;
-    destroy(): Record<string, unknown>;
-}
-export interface RunGeneratorOptions extends Omit<GeneratorContext, 'engine'> {
-    module: string;
-    base: URL;
-    revision?: number;
-    isCurrent?: () => boolean;
-    onSchema?: (schema: GeneratorParamSchema) => void;
-}
-export declare function runGenerator({ node, params, viewer, module, base, revision, isCurrent, onSchema, }: RunGeneratorOptions): Promise<IObject3D[]>;
-export declare function removeGeneratedChildren(node: IObject3D): void;
-export declare function markGenerated(object: IObject3D, sourceId?: string, outputIndex?: number): void;
-export declare function resolveGeneratorModule(module: string, base: URL): URL;

package/src/generatorParams.ts

@@ -1,182 +0,0 @@
-export const generatorParamTypes = [
-    'boolean',
-    'number',
-    'integer',
-    'string',
-    'select',
-    'vector',
-    'color',
-    'json',
-] as const
-
-export type GeneratorParamType = typeof generatorParamTypes[number]
-
-export type GeneratorParamOption = string | number | {
-    value: string | number
-    label: string
-}
-
-export interface GeneratorParamDefinition {
-    type?: GeneratorParamType
-    label?: string
-    help?: string
-    default?: unknown
-    options?: GeneratorParamOption[]
-    min?: number
-    max?: number
-    step?: number
-}
-
-export interface GeneratorParamSchemaEntry extends Omit<GeneratorParamDefinition, 'type'> {
-    type: GeneratorParamType
-}
-
-export type GeneratorParamSchema = Record<string, GeneratorParamSchemaEntry>
-
-export function parseGeneratorParamsSchema(
-    exported: unknown,
-    module: string,
-    warn: (message: string) => void = console.warn,
-): GeneratorParamSchema {
-    if (exported === undefined) return {}
-    if (!isRecord(exported)) {
-        warn(`[kite3d] Ignoring invalid generator params export from ${module}: expected an object`)
-        return {}
-    }
-
-    const schema: GeneratorParamSchema = {}
-    for (const [key, value] of Object.entries(exported)) {
-        const parsed = parseEntry(value)
-        if (typeof parsed === 'string') {
-            warn(`[kite3d] Ignoring invalid generator param "${key}" from ${module}: ${parsed}`)
-            continue
-        }
-        schema[key] = parsed
-    }
-    return schema
-}
-
-export function inferGeneratorParam(value: unknown): GeneratorParamSchemaEntry {
-    if (typeof value === 'boolean') return {type: 'boolean'}
-    if (typeof value === 'number') return {type: 'number'}
-    if (isNumberVector(value)) return {type: 'vector'}
-    if (typeof value === 'string') return {type: 'string'}
-    return {type: 'json'}
-}
-
-export function validateGeneratorParam(value: unknown, entry: GeneratorParamSchemaEntry): string | undefined {
-    const name = entry.label || 'Value'
-    switch (entry.type) {
-        case 'boolean':
-            return typeof value === 'boolean' ? undefined : `${name} must be true or false.`
-        case 'number':
-        case 'integer': {
-            if (typeof value !== 'number' || !Number.isFinite(value)) return `${name} must be a number.`
-            if (entry.type === 'integer' && !Number.isInteger(value)) return `${name} must be an integer.`
-            if (entry.min !== undefined && value < entry.min) return `${name} must be at least ${entry.min}.`
-            if (entry.max !== undefined && value > entry.max) return `${name} must be at most ${entry.max}.`
-            return undefined
-        }
-        case 'string':
-            return typeof value === 'string' ? undefined : `${name} must be text.`
-        case 'select': {
-            if (typeof value !== 'string' && typeof value !== 'number') {
-                return `${name} must be one of the available options.`
-            }
-            if (entry.options?.length && !entry.options.some((option) => Object.is(optionValue(option), value))) {
-                return `${name} must be one of the available options.`
-            }
-            return undefined
-        }
-        case 'vector':
-            return isNumberVector(value) ? undefined : `${name} must be an array of 2 to 4 numbers.`
-        case 'color':
-            return typeof value === 'string' && /^#[\da-f]{6}$/i.test(value)
-                ? undefined
-                : `${name} must be a six-digit hex color.`
-        case 'json':
-            return isJsonValue(value) ? undefined : `${name} must be a JSON value.`
-    }
-}
-
-function parseEntry(value: unknown): GeneratorParamSchemaEntry | string {
-    if (!isRecord(value)) return 'expected an object'
-    if (value.type !== undefined && !generatorParamTypes.includes(value.type as GeneratorParamType)) {
-        return `unknown type ${JSON.stringify(value.type)}`
-    }
-    if (value.label !== undefined && typeof value.label !== 'string') return 'label must be a string'
-    if (value.help !== undefined && typeof value.help !== 'string') return 'help must be a string'
-    if (value.options !== undefined && !isOptions(value.options)) return 'options must contain strings, numbers, or labeled values'
-    for (const bound of ['min', 'max', 'step'] as const) {
-        if (value[bound] !== undefined && !isFiniteNumber(value[bound])) return `${bound} must be a finite number`
-    }
-    if (isFiniteNumber(value.step) && value.step <= 0) return 'step must be greater than zero'
-    if (isFiniteNumber(value.min) && isFiniteNumber(value.max) && value.min > value.max) {
-        return 'min must not be greater than max'
-    }
-
-    const type = value.type as GeneratorParamType | undefined
-        ?? (value.options !== undefined ? 'select' : inferGeneratorParam(value.default).type)
-    if ((value.min !== undefined || value.max !== undefined || value.step !== undefined)
-        && type !== 'number' && type !== 'integer') {
-        return 'min, max, and step require a number or integer type'
-    }
-    if (value.options !== undefined && type !== 'select') return 'options require the select type'
-
-    const entry: GeneratorParamSchemaEntry = {
-        type,
-        ...(value.label !== undefined ? {label: value.label} : {}),
-        ...(value.help !== undefined ? {help: value.help} : {}),
-        ...(Object.prototype.hasOwnProperty.call(value, 'default') ? {default: value.default} : {}),
-        ...(value.options !== undefined ? {options: value.options} : {}),
-        ...(isFiniteNumber(value.min) ? {min: value.min} : {}),
-        ...(isFiniteNumber(value.max) ? {max: value.max} : {}),
-        ...(isFiniteNumber(value.step) ? {step: value.step} : {}),
-    }
-    if (Object.prototype.hasOwnProperty.call(entry, 'default')) {
-        const error = validateGeneratorParam(entry.default, entry)
-        if (error) return `invalid default: ${error}`
-    }
-    return entry
-}
-
-function isOptions(value: unknown): value is GeneratorParamOption[] {
-    return Array.isArray(value) && value.every((option) => {
-        if (typeof option === 'string' || typeof option === 'number') return true
-        return isRecord(option)
-            && (typeof option.value === 'string' || typeof option.value === 'number')
-            && typeof option.label === 'string'
-    })
-}
-
-function optionValue(option: GeneratorParamOption): string | number {
-    return typeof option === 'object' ? option.value : option
-}
-
-function isNumberVector(value: unknown): value is number[] {
-    return Array.isArray(value)
-        && value.length >= 2
-        && value.length <= 4
-        && value.every(isFiniteNumber)
-}
-
-function isFiniteNumber(value: unknown): value is number {
-    return typeof value === 'number' && Number.isFinite(value)
-}
-
-function isJsonValue(value: unknown, seen = new Set<object>()): boolean {
-    if (value === null || typeof value === 'string' || typeof value === 'boolean') return true
-    if (typeof value === 'number') return Number.isFinite(value)
-    if (!value || typeof value !== 'object' || seen.has(value)) return false
-    seen.add(value)
-    const valid = Array.isArray(value)
-        ? value.every((item) => isJsonValue(item, seen))
-        : Object.getPrototypeOf(value) === Object.prototype
-            && Object.values(value).every((item) => isJsonValue(item, seen))
-    seen.delete(value)
-    return valid
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
-}

package/src/plugins/GeneratorComponent.ts

@@ -1,287 +0,0 @@
-import * as ThreePipe from 'threepipe'
-import {
-    type ComponentDefn,
-    type IObject3D,
-    Object3DComponent,
-    type ThreeViewer,
-} from 'threepipe'
-import {getAuthoringMetadata, setAuthoringMetadata, type AuthoringMetadata} from '../authoring.ts'
-import {
-    parseGeneratorParamsSchema,
-    type GeneratorParamDefinition,
-    type GeneratorParamSchema,
-} from '../generatorParams.ts'
-
-export interface GeneratorParams {
-    [key: string]: unknown
-}
-
-export interface GeneratorContext {
-    node: IObject3D
-    params: GeneratorParams
-    viewer: ThreeViewer
-    engine: Record<string, unknown>
-}
-
-export interface GeneratorModule {
-    default?: (context: GeneratorContext) => unknown | Promise<unknown>
-    params?: Record<string, GeneratorParamDefinition>
-}
-
-export interface GeneratorViewerOptions {
-    base: string | URL
-    onError?: (error: unknown) => void
-}
-
-interface GeneratorViewerConfig {
-    base: URL
-    onError?: (error: unknown) => void
-    pending: Set<Promise<void>>
-}
-
-const viewerConfigs = new WeakMap<ThreeViewer, GeneratorViewerConfig>()
-let generatorImportRevision = 0
-
-export class GeneratorComponent extends Object3DComponent {
-    static ComponentType = 'Generator'
-    static StateProperties: ComponentDefn['StateProperties'] = ['module', 'params']
-
-    module = ''
-    params: GeneratorParams = {}
-    schema: GeneratorParamSchema = {}
-    private runRevision = 0
-
-    static configureViewer(viewer: ThreeViewer, options: GeneratorViewerOptions): void {
-        viewerConfigs.set(viewer, {
-            base: typeof options.base === 'string' ? new URL(options.base) : options.base,
-            onError: options.onError,
-            pending: new Set(),
-        })
-    }
-
-    static async waitForViewer(viewer: ThreeViewer): Promise<void> {
-        const config = viewerConfigs.get(viewer)
-        while (config?.pending.size) await Promise.all([...config.pending])
-    }
-
-    init(object: IObject3D, state: Record<string, unknown>): void {
-        super.init(object, state)
-        const run = () => { void this.run().catch((error) => reportGeneratorError(this.ctx.viewer, error)) }
-        this.onStateChange('module', run)
-        this.onStateChange('params', run)
-        run()
-    }
-
-    async run(): Promise<void> {
-        const viewer = this.ctx.viewer
-        const config = viewerConfigs.get(viewer)
-        if (!config) throw new Error('Generator viewer is not configured')
-        const revision = ++this.runRevision
-        const task = runGenerator({
-            node: this.object,
-            params: this.params,
-            viewer,
-            module: this.module,
-            base: config.base,
-            revision: ++generatorImportRevision,
-            isCurrent: () => revision === this.runRevision,
-            onSchema: (schema) => { this.schema = schema },
-        }).then(() => {
-            if (revision === this.runRevision) viewer.setDirty(this)
-        }).finally(() => config.pending.delete(task))
-        config.pending.add(task)
-        await task
-    }
-
-    async bake(): Promise<number> {
-        await this.run()
-        const node = this.object
-        const generated = node.children.filter((child) => child.userData.kite3dGenerated === true)
-        const bakedFrom = {
-            module: this.module,
-            params: JSON.parse(JSON.stringify(this.params)) as GeneratorParams,
-            ts: new Date().toISOString(),
-        }
-        for (const child of generated) unmarkGenerated(child as IObject3D)
-        this.ctx.ecp.removeComponent(node, this.uuid)
-        const metadata = getAuthoringMetadata(node)
-        if (metadata?.role === 'generator' && !metadata.sourceId) {
-            setAuthoringMetadata(node, {
-                role: 'direct',
-                id: metadata.id,
-                ...(metadata.allowCameraInside !== undefined ? {allowCameraInside: metadata.allowCameraInside} : {}),
-            })
-        }
-        node.userData.kite3dBakedFrom = bakedFrom
-        node._sChildren = [...node.children]
-        node.setDirty?.({change: 'userData.kite3dBakedFrom', source: 'kite3d bake'})
-        return generated.length
-    }
-
-    destroy(): Record<string, unknown> {
-        this.runRevision += 1
-        removeGeneratedChildren(this.object)
-        return super.destroy()
-    }
-}
-
-export interface RunGeneratorOptions extends Omit<GeneratorContext, 'engine'> {
-    module: string
-    base: URL
-    revision?: number
-    isCurrent?: () => boolean
-    onSchema?: (schema: GeneratorParamSchema) => void
-}
-
-export async function runGenerator({
-    node,
-    params,
-    viewer,
-    module,
-    base,
-    revision = 0,
-    isCurrent,
-    onSchema,
-}: RunGeneratorOptions): Promise<IObject3D[]> {
-    removeGeneratedChildren(node)
-    onSchema?.({})
-    if (!module) return []
-    const source = ensureGeneratorMetadata(node)
-    const moduleUrl = resolveGeneratorModule(module, base)
-    if (revision) moduleUrl.searchParams.set('kite3d-generator', String(revision))
-    const loaded = await importGeneratorModule(moduleUrl.href)
-    if (!isCurrent || isCurrent()) onSchema?.(parseGeneratorParamsSchema(loaded.params, module))
-    if (typeof loaded.default !== 'function') {
-        throw new Error(`Generator module must have a default generate function: ${module}`)
-    }
-
-    const existingChildren = new Set(node.children)
-    const returned = await loaded.default({
-        node,
-        params,
-        viewer,
-        engine: ThreePipe as unknown as Record<string, unknown>,
-    })
-    const returnedObjects = normalizeGeneratedResult(returned)
-    for (const [index, child] of returnedObjects.entries()) {
-        if (child.parent === node) continue
-        markGenerated(child, source.id, index)
-        node.add(child)
-    }
-
-    const generated = node.children.filter((child) => !existingChildren.has(child)) as IObject3D[]
-    if (isCurrent && !isCurrent()) {
-        for (const child of generated) removeGeneratedObject(child)
-        return []
-    }
-    generated.forEach((child, index) => markGenerated(child, source.id, index))
-    return generated
-}
-
-export function removeGeneratedChildren(node: IObject3D): void {
-    for (const child of [...node.children] as IObject3D[]) {
-        if (child.userData.kite3dGenerated !== true) continue
-        removeGeneratedObject(child)
-    }
-}
-
-export function markGenerated(object: IObject3D, sourceId?: string, outputIndex = 0): void {
-    let descendantIndex = 0
-    object.traverse((child: IObject3D) => {
-        child.userData.kite3dGenerated = true
-        child.userData.excludeFromExport = true
-        if (sourceId) {
-            child.userData.kite3dAuthoring = {
-                role: 'generator',
-                id: `${sourceId}:preview:${outputIndex}:${descendantIndex++}`,
-                sourceId,
-            } satisfies AuthoringMetadata
-        }
-    })
-}
-
-function unmarkGenerated(object: IObject3D): void {
-    object.traverse((child: IObject3D) => {
-        delete child.userData.kite3dGenerated
-        delete child.userData.excludeFromExport
-        const metadata = getAuthoringMetadata(child)
-        if (metadata?.role === 'generator' && metadata.sourceId) delete child.userData.kite3dAuthoring
-    })
-}
-
-function ensureGeneratorMetadata(node: IObject3D): AuthoringMetadata {
-    const current = getAuthoringMetadata(node)
-    if (current?.role === 'generator' && !current.sourceId) return current
-    const savedId = typeof node.userData.gltfUUID === 'string' && node.userData.gltfUUID.trim()
-        ? node.userData.gltfUUID.trim()
-        : current?.id || generatorPathId(node)
-    setAuthoringMetadata(node, {role: 'generator', id: savedId})
-    return getAuthoringMetadata(node)!
-}
-
-function generatorPathId(node: IObject3D): string {
-    const parts: string[] = []
-    for (let current: IObject3D | null = node; current?.parent; current = current.parent as IObject3D) {
-        const index = current.parent.children.indexOf(current)
-        parts.push(`${current.name || current.type}:${index}`)
-        if (current.parent.userData?.rootSceneModelRoot) break
-    }
-    return `generator:${parts.reverse().join('/')}`
-}
-
-function removeGeneratedObject(object: IObject3D): void {
-    object.removeFromParent()
-    const disposed = new Set<object>()
-    object.traverse((child) => {
-        const renderable = child as IObject3D & {geometry?: {dispose?(): void}, material?: unknown | unknown[]}
-        disposeResource(renderable.geometry, disposed)
-        const materials = Array.isArray(renderable.material) ? renderable.material : [renderable.material]
-        for (const material of materials) {
-            if (!material || typeof material !== 'object') continue
-            for (const value of Object.values(material)) {
-                if (value && typeof value === 'object' && 'isTexture' in value) disposeResource(value, disposed)
-            }
-            disposeResource(material, disposed)
-        }
-    })
-}
-
-function disposeResource(resource: unknown, disposed: Set<object>): void {
-    if (!resource || typeof resource !== 'object' || disposed.has(resource)) return
-    disposed.add(resource)
-    ;(resource as {dispose?(): void}).dispose?.()
-}
-
-export function resolveGeneratorModule(module: string, base: URL): URL {
-    if (!module || module.startsWith('/') || /^[a-z][a-z\d+.-]*:/i.test(module)) {
-        throw new Error(`Generator module must be a project-relative path: ${module}`)
-    }
-    const resolved = new URL(module, base)
-    if (resolved.origin !== base.origin) {
-        throw new Error(`Generator module must be same-origin: ${resolved.href}`)
-    }
-    return resolved
-}
-
-function normalizeGeneratedResult(value: unknown): IObject3D[] {
-    if (!value) return []
-    const values = Array.isArray(value) ? value : [value]
-    const objects: IObject3D[] = []
-    for (const candidate of values) {
-        if (!(candidate as IObject3D | undefined)?.isObject3D) {
-            throw new Error('Generator output must be an Object3D, an array of Object3D values, or undefined')
-        }
-        objects.push(candidate as IObject3D)
-    }
-    return objects
-}
-
-async function importGeneratorModule(url: string): Promise<GeneratorModule> {
-    return import(/* @vite-ignore */ url) as Promise<GeneratorModule>
-}
-
-function reportGeneratorError(viewer: ThreeViewer, error: unknown): void {
-    const onError = viewerConfigs.get(viewer)?.onError
-    if (onError) onError(error)
-    else console.error('[kite3d] Generator error', error)
-}