@kite3d/engine 0.15.0

package/src/plugins/cannon/utils.ts

@@ -0,0 +1,185 @@
+// https://github.com/donmccurdy/three-to-cannon/blob/main/src/utils.ts
+
+import { BufferAttribute, BufferGeometry, Mesh, Object3D, Quaternion, Vector3 } from 'threepipe';
+
+const _v1 = new Vector3();
+const _v2 = new Vector3();
+const _q1 = new Quaternion();
+
+/**
+ * Returns a single geometry for the given object. If the object is compound,
+ * its geometries are automatically merged. Bake world scale into each
+ * geometry, because we can't easily apply that to the cannonjs shapes later.
+ */
+export function getGeometry (object: Object3D): BufferGeometry | null {
+    const meshes = getMeshes(object);
+    if (meshes.length === 0) return null;
+
+    // Single mesh. Return, preserving original type.
+    if (meshes.length === 1) {
+        return normalizeGeometry(meshes[0]);
+    }
+
+    // Multiple meshes. Merge and return.
+    let mesh: Mesh | undefined;
+    const geometries: BufferGeometry[] = [];
+    while ((mesh = meshes.pop())) {
+        geometries.push(simplifyGeometry(normalizeGeometry(mesh)));
+    }
+
+    return mergeBufferGeometries(geometries);
+}
+
+function normalizeGeometry (mesh: Mesh): BufferGeometry {
+    // Preserve original type, e.g. CylinderBufferGeometry.
+    const geometry: BufferGeometry = mesh.geometry.clone();
+
+    mesh.updateMatrixWorld();
+    mesh.matrixWorld.decompose(_v1, _q1, _v2);
+    geometry.scale(_v2.x, _v2.y, _v2.z);
+    return geometry;
+}
+
+/**
+ * Greatly simplified version of BufferGeometryUtils.mergeBufferGeometries.
+ * Because we only care about the vertex positions, and not the indices or
+ * other attributes, we throw everything else away.
+ */
+function mergeBufferGeometries (geometries: BufferGeometry[]): BufferGeometry {
+    let vertexCount = 0;
+    for (let i = 0; i < geometries.length; i++) {
+        const position = geometries[i].attributes.position;
+        if (position && position.itemSize === 3) {
+            vertexCount += position.count;
+        }
+    }
+
+    const positionArray = new Float32Array(vertexCount * 3);
+
+    let positionOffset = 0;
+    for (let i = 0; i < geometries.length; i++) {
+        const position = geometries[i].attributes.position;
+        if (position && position.itemSize === 3) {
+            for (let j = 0; j < position.count; j++) {
+                positionArray[positionOffset++] = position.getX(j);
+                positionArray[positionOffset++] = position.getY(j);
+                positionArray[positionOffset++] = position.getZ(j);
+            }
+        }
+    }
+
+    return new BufferGeometry().setAttribute('position', new BufferAttribute(positionArray, 3));
+}
+
+export function getVertices (geometry: BufferGeometry): Float32Array {
+    const position = geometry.attributes.position;
+    const vertices = new Float32Array(position.count * 3);
+    for (let i = 0; i < position.count; i++) {
+        vertices[i * 3] = position.getX(i);
+        vertices[i * 3 + 1] = position.getY(i);
+        vertices[i * 3 + 2] = position.getZ(i);
+    }
+    return vertices;
+}
+
+/**
+ * Returns a flat array of THREE.Mesh instances from the given object. If
+ * nested transformations are found, they are applied to child meshes
+ * as mesh.userData.matrix, so that each mesh has its position/rotation/scale
+ * independently of all of its parents except the top-level object.
+ */
+function getMeshes (object: Object3D): Mesh[] {
+    const meshes: Mesh[] = [];
+    object.traverse(function (o) {
+        if ((o as Mesh).isMesh) {
+            meshes.push(o as Mesh);
+        }
+    });
+    return meshes;
+}
+
+export function getComponent(v: Vector3, component: string): number {
+    switch(component) {
+        case 'x': return v.x;
+        case 'y': return v.y;
+        case 'z': return v.z;
+    }
+    throw new Error(`Unexpected component ${component}`);
+}
+
+/**
+ * Modified version of BufferGeometryUtils.mergeVertices, ignoring vertex
+ * attributes other than position.
+ *
+ * @param {THREE.BufferGeometry} geometry
+ * @param {number} tolerance
+ * @return {THREE.BufferGeometry>}
+ */
+function simplifyGeometry (geometry: BufferGeometry, tolerance = 1e-4): BufferGeometry {
+
+    tolerance = Math.max( tolerance, Number.EPSILON );
+
+    // Generate an index buffer if the geometry doesn't have one, or optimize it
+    // if it's already available.
+    const hashToIndex: {[key: string]: number} = {};
+    const indices = geometry.getIndex();
+    const positions = geometry.getAttribute( 'position' );
+    const vertexCount = indices ? indices.count : positions.count;
+
+    // Next value for triangle indices.
+    let nextIndex = 0;
+
+    const newIndices = [];
+    const newPositions = [];
+
+    // Convert the error tolerance to an amount of decimal places to truncate to.
+    const decimalShift = Math.log10( 1 / tolerance );
+    const shiftMultiplier = Math.pow( 10, decimalShift );
+
+    for ( let i = 0; i < vertexCount; i ++ ) {
+
+        const index = indices ? indices.getX( i ) : i;
+
+        // Generate a hash for the vertex attributes at the current index 'i'.
+        let hash = '';
+
+        // Double tilde truncates the decimal value.
+        hash += `${ ~ ~ ( positions.getX( index ) * shiftMultiplier ) },`;
+        hash += `${ ~ ~ ( positions.getY( index ) * shiftMultiplier ) },`;
+        hash += `${ ~ ~ ( positions.getZ( index ) * shiftMultiplier ) },`;
+
+        // Add another reference to the vertex if it's already
+        // used by another index.
+        if ( hash in hashToIndex ) {
+
+            newIndices.push( hashToIndex[ hash ] );
+
+        } else {
+
+            newPositions.push( positions.getX( index ) );
+            newPositions.push( positions.getY( index ) );
+            newPositions.push( positions.getZ( index ) );
+
+            hashToIndex[ hash ] = nextIndex;
+            newIndices.push( nextIndex );
+            nextIndex ++;
+
+        }
+
+    }
+
+    // Construct merged BufferGeometry.
+
+    const positionAttribute = new BufferAttribute(
+        new Float32Array( newPositions ),
+        positions.itemSize,
+        positions.normalized
+    );
+
+    const result = new BufferGeometry();
+    result.setAttribute( 'position', positionAttribute );
+    result.setIndex( newIndices );
+
+    return result;
+
+}

package/src/runtime/createGame.ts

@@ -0,0 +1,337 @@
+import {
+    Class,
+    EntityComponentPlugin,
+    GBufferPlugin,
+    GLTFAnimationPlugin,
+    GLTFMeshOptDecodePlugin,
+    IObject3D,
+    IViewerPlugin,
+    KTX2LoadPlugin,
+    KTXLoadPlugin,
+    PLYLoadPlugin,
+    PopmotionPlugin,
+    Rhino3dmLoadPlugin,
+    STLLoadPlugin,
+    ThreeViewer,
+    USDZLoadPlugin,
+} from 'threepipe'
+import {MeshoptDecoder} from 'meshoptimizer'
+import {registerScripts} from '../scripts.ts'
+import {HtmlUiComponent} from '../plugins/HtmlUiComponent.ts'
+import {GeneratorComponent} from '../plugins/GeneratorComponent.ts'
+import {CannonPhysicsPlugin} from '../plugins/cannon/CannonPhysicsPlugin.ts'
+import {
+    installGameHooks,
+    runtimeCleanupReport,
+    type GameValidationFunction,
+    type GameValidationReport,
+    type RuntimeCleanupReport,
+} from '../authoringValidation.ts'
+import {RuntimeNestedAssetLoader} from './nestedAssets.ts'
+import {
+    assetUrlPrefix,
+    AssetsJSONManifest,
+    ExternalPlugin,
+    isDependencyModuleSpecifier,
+    parseAssetsJSONManifest,
+    parsePackageJSON,
+    parsePackageJsonSettingsConfig,
+    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
+}
+
+type ModuleExports = Record<string, unknown>
+type RuntimeErrorHandler = (error: unknown) => void
+
+export function createGame(options: CreateGameOptions): Promise<CreatedGame> {
+    return createProjectGame(options, true)
+}
+
+/** Load the saved project and generator previews without starting components, physics, the timeline, or main.js. */
+export function createStoppedGame(options: CreateGameOptions): Promise<CreatedGame> {
+    return createProjectGame(options, false)
+}
+
+async function createProjectGame({
+    base,
+    canvas,
+    onError,
+    fileRevisions = {},
+    moduleRevision,
+}: CreateGameOptions, start: boolean): Promise<CreatedGame> {
+    const reportError = createErrorReporter(onError)
+    let viewer: ThreeViewer | undefined
+    let nestedAssets: RuntimeNestedAssetLoader | undefined
+    let removeURLModifier: (() => void) | undefined
+    let gameHooks: ReturnType<typeof installGameHooks> | undefined
+
+    try {
+        const baseUrl = validateBase(base)
+        const [packageText, assetsText] = await Promise.all([
+            fetchText(new URL('package.json', baseUrl)),
+            fetchText(new URL('assets.json', baseUrl)),
+        ])
+        const packageJson = parsePackageJSON(packageText)
+        const config = await parsePackageJsonSettingsConfig(packageJson)
+        const assetsManifest = parseAssetsJSONManifest(assetsText)
+        const project: RuntimeProject = {
+            packageJson,
+            config,
+            assetsManifest,
+            mainScene: packageJson.mainScene,
+        }
+
+        const entityComponents = new EntityComponentPlugin(false)
+        const physics = new CannonPhysicsPlugin(true, false)
+        EntityComponentPlugin.AddObjectUiConfig = false
+        window.MeshoptDecoder = MeshoptDecoder
+
+        viewer = new ThreeViewer({
+            canvas,
+            ...config.viewer,
+            assetManager: {
+                simpleCache: false,
+                storage: false,
+            },
+            plugins: [
+                entityComponents,
+                new GBufferPlugin(),
+                physics,
+                new PopmotionPlugin(),
+                new GLTFAnimationPlugin(),
+                new GLTFMeshOptDecodePlugin(false),
+                new KTX2LoadPlugin(),
+                new KTXLoadPlugin(),
+                new PLYLoadPlugin(),
+                new Rhino3dmLoadPlugin(),
+                new STLLoadPlugin(),
+                new USDZLoadPlugin(),
+            ],
+        })
+        viewer.timeline.endTime = 0
+        gameHooks = installGameHooks()
+        entityComponents.addComponentType(HtmlUiComponent)
+        entityComponents.addComponentType(GeneratorComponent)
+        GeneratorComponent.configureViewer(viewer, {base: baseUrl, onError: reportError})
+
+        // Three's LoadingManager delegates through this importer hook. It covers
+        // glTF buffers/textures and nested imports without patching global fetch.
+        const urlModifier = createURLModifier(baseUrl, assetsManifest)
+        viewer.assetManager.importer.addURLModifier(urlModifier)
+        removeURLModifier = () => viewer?.assetManager.importer.removeURLModifier(urlModifier)
+
+        nestedAssets = new RuntimeNestedAssetLoader(viewer, reportError)
+
+        await registerProjectScripts(viewer, project, baseUrl, fileRevisions, moduleRevision)
+        await registerProjectPlugins(viewer, project, baseUrl, fileRevisions, moduleRevision)
+
+        const sceneUrl = new URL(project.mainScene, baseUrl).href
+        const loadedScene = await viewer.load(sceneUrl, {importAsModelRoot: true})
+        if (!loadedScene?.isObject3D) {
+            throw new Error(`The main scene did not load as an Object3D: ${sceneUrl}`)
+        }
+        await nestedAssets.loadObjectDependencies(loadedScene as IObject3D)
+        await nestedAssets.waitForPending()
+        await GeneratorComponent.waitForViewer(viewer)
+
+        if (start) {
+            viewer.timeline.reset()
+            viewer.timeline.start()
+            entityComponents.start()
+            physics.running = true
+
+            const mainUrl = versionedProjectUrl('main.js', baseUrl, fileRevisions, moduleRevision)
+            const mainModule = await importModule(mainUrl.href)
+            if (mainModule.main !== undefined) {
+                if (typeof mainModule.main !== 'function') {
+                    throw new Error('main.js export "main" must be a function')
+                }
+                await mainModule.main({viewer})
+            }
+        }
+
+        const readyViewer = viewer
+        let disposed = false
+        let cleanupReport: RuntimeCleanupReport | undefined
+        return {
+            viewer: readyViewer,
+            project,
+            registerGameValidation: gameHooks.registerGameValidation,
+            publishGameTelemetry: gameHooks.publishGameTelemetry,
+            runGameValidation: gameHooks.runGameValidation,
+            dispose() {
+                if (disposed) return cleanupReport!
+                disposed = true
+                entityComponents.stop()
+                physics.running = false
+                readyViewer.timeline.stop()
+                cleanupReport = runtimeCleanupReport(readyViewer)
+                nestedAssets?.dispose()
+                removeURLModifier?.()
+                gameHooks?.dispose()
+                readyViewer.dispose()
+                return cleanupReport
+            },
+        }
+    } catch (error) {
+        nestedAssets?.dispose()
+        removeURLModifier?.()
+        gameHooks?.dispose()
+        viewer?.dispose()
+        reportError(error)
+        throw error
+    }
+}
+
+async function registerProjectPlugins(
+    viewer: ThreeViewer,
+    project: RuntimeProject,
+    base: URL,
+    fileRevisions: Readonly<Record<string, string>>,
+    moduleRevision?: string,
+) {
+    const {config, packageJson} = project
+    for (const definition of config.plugins) {
+        if (definition.active === false) continue
+        const specifier = resolvePluginSpecifier(definition, packageJson, base, fileRevisions, moduleRevision)
+        const module = await importModule(specifier)
+        const plugin = findPluginExport(module, definition)
+        if (viewer.getPlugin(plugin)) continue
+        await viewer.addPlugin(plugin, ...(definition.params || []))
+    }
+}
+
+async function registerProjectScripts(
+    viewer: ThreeViewer,
+    project: RuntimeProject,
+    base: URL,
+    fileRevisions: Readonly<Record<string, string>>,
+    moduleRevision?: string,
+) {
+    const {config, packageJson} = project
+    const modules: ModuleExports[] = []
+    for (const definition of config.scripts) {
+        if (definition.active === false) continue
+        const specifier = isDependencyModuleSpecifier(definition.import, packageJson)
+            ? definition.import
+            : versionedProjectUrl(definition.import, base, fileRevisions, moduleRevision).href
+        modules.push(await importModule(specifier))
+    }
+    await registerScripts(viewer, modules)
+}
+
+function createURLModifier(base: URL, assets: AssetsJSONManifest) {
+    const assetIdPrefix = `${assetUrlPrefix}@`
+    return (url: string): string => {
+        if (url.startsWith(assetIdPrefix)) {
+            const id = url.slice(assetIdPrefix.length).split('/', 1)[0]
+            const asset = assets.files[id]
+            if (!asset?.path) throw new Error(`Unknown asset id in URL: ${id}`)
+            return new URL(asset.path, base).href
+        }
+        if (url.startsWith(assetUrlPrefix)) {
+            return new URL(url.slice(assetUrlPrefix.length), base).href
+        }
+        return url
+    }
+}
+
+function resolvePluginSpecifier(
+    definition: ExternalPlugin,
+    packageJson: ProjectPackageJSON,
+    base: URL,
+    fileRevisions: Readonly<Record<string, string>>,
+    moduleRevision?: string,
+) {
+    const isDependency = isDependencyModuleSpecifier(definition.import, packageJson)
+    if (isDependency) return definition.import
+    return versionedProjectUrl(definition.import, base, fileRevisions, moduleRevision).href
+}
+
+function versionedProjectUrl(
+    path: string,
+    base: URL,
+    fileRevisions: Readonly<Record<string, string>>,
+    moduleRevision?: string,
+): URL {
+    const url = assertSameOrigin(new URL(path, base), base)
+    const normalized = path.replace(/^\.\//, '')
+    const revision = fileRevisions[normalized]
+    if (revision) url.searchParams.set('v', revision)
+    if (moduleRevision) url.searchParams.set('r', moduleRevision)
+    return url
+}
+
+function findPluginExport(module: ModuleExports, definition: ExternalPlugin): Class<IViewerPlugin> {
+    const requested = definition.className || 'default'
+    const selected = module[requested]
+    if (isPluginType(selected)) return selected
+
+    if (!definition.className) {
+        const candidates = Object.values(module).filter(isPluginType)
+        if (candidates.length === 1) return candidates[0]
+    }
+    throw new Error(`Cannot find plugin export "${requested}" in ${definition.import}`)
+}
+
+function isPluginType(value: unknown): value is Class<IViewerPlugin> {
+    return typeof value === 'function'
+        && typeof (value as unknown as {PluginType?: unknown}).PluginType === 'string'
+}
+
+async function importModule(specifier: string): Promise<ModuleExports> {
+    return import(/* @vite-ignore */ specifier) as Promise<ModuleExports>
+}
+
+async function fetchText(url: URL): Promise<string> {
+    const response = await fetch(url)
+    if (!response.ok) throw new Error(`Failed to fetch ${url.href}: ${response.status} ${response.statusText}`)
+    return response.text()
+}
+
+function validateBase(base: string): URL {
+    if (!base.endsWith('/')) throw new Error('createGame base must end in "/"')
+    const url = new URL(base)
+    if (!url.protocol.startsWith('http')) throw new Error('createGame base must be an absolute HTTP(S) URL')
+    return url
+}
+
+function assertSameOrigin(url: URL, base: URL): URL {
+    if (url.origin !== base.origin) {
+        throw new Error(`Project modules must be same-origin: ${url.href}`)
+    }
+    return url
+}
+
+function createErrorReporter(onError?: RuntimeErrorHandler) {
+    return (error: unknown) => {
+        console.error('[kite3d] Runtime error', error)
+        onError?.(error)
+    }
+}

package/src/runtime/index.ts

@@ -0,0 +1,19 @@
+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/src/runtime/migrations.ts

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