@kite3d/engine 0.15.0

package/src/plugins/GeneratorComponent.ts

@@ -0,0 +1,275 @@
+import * as ThreePipe from 'threepipe'
+import {
+    type ComponentDefn,
+    type IObject3D,
+    Object3DComponent,
+    type ThreeViewer,
+} from 'threepipe'
+import {getAuthoringMetadata, setAuthoringMetadata, type AuthoringMetadata} from '../authoring.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>
+}
+
+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 = {}
+    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,
+        }).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
+}
+
+export async function runGenerator({
+    node,
+    params,
+    viewer,
+    module,
+    base,
+    revision = 0,
+    isCurrent,
+}: RunGeneratorOptions): Promise<IObject3D[]> {
+    removeGeneratedChildren(node)
+    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 (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)
+}

package/src/plugins/HtmlUiComponent.example.ts

@@ -0,0 +1,202 @@
+// /**
+//  * Example usage of HtmlUiComponent
+//  *
+//  * This file demonstrates how to use the HtmlUiComponent with threepipe
+//  */
+//
+// import { HtmlUiComponent } from './HtmlUiComponent'
+// import { IViewer, EntityComponentPlugin, IObject3D } from 'threepipe'
+//
+// /**
+//  * Initialize the HtmlUiComponent for a viewer
+//  */
+// export function initHtmlUiComponent(viewer: IViewer) {
+//     // The EntityComponentPlugin should already be added to the viewer
+//     // If not, add it:
+//     // viewer.addPluginSync(EntityComponentPlugin)
+// }
+//
+// /**
+//  * Add a simple label to an object that follows it in 3D space
+//  */
+// export function addObjectLabel(object: IObject3D, labelText: string) {
+//     return EntityComponentPlugin.AddComponent(object, HtmlUiComponent, {
+//         htmlData: `
+//             <div style="
+//                 background: rgba(0, 0, 0, 0.8);
+//                 color: white;
+//                 padding: 8px 12px;
+//                 border-radius: 5px;
+//                 font-family: Arial, sans-serif;
+//                 font-size: 14px;
+//                 white-space: nowrap;
+//                 box-shadow: 0 2px 8px rgba(0,0,0,0.3);
+//             ">
+//                 ${labelText}
+//             </div>
+//         `,
+//         width: 150,
+//         height: 40,
+//         positionMode: 'world',
+//         offsetY: -50, // Position above the object
+//         scrollable: false,
+//         interactable: false,
+//         visible: true,
+//         zIndex: 1000
+//     })
+// }
+//
+// /**
+//  * Add an info panel to an object
+//  */
+// export function addInfoPanel(object: IObject3D, title: string, content: string) {
+//     return EntityComponentPlugin.AddComponent(object, HtmlUiComponent, {
+//         htmlData: `
+//             <div style="
+//                 background: white;
+//                 padding: 15px;
+//                 border-radius: 8px;
+//                 font-family: Arial, sans-serif;
+//                 box-shadow: 0 4px 16px rgba(0,0,0,0.2);
+//                 border: 1px solid #ccc;
+//             ">
+//                 <h3 style="margin: 0 0 10px 0; font-size: 16px; color: #333;">${title}</h3>
+//                 <p style="margin: 0; font-size: 13px; color: #666; line-height: 1.5;">${content}</p>
+//             </div>
+//         `,
+//         width: 250,
+//         height: 150,
+//         positionMode: 'world',
+//         offsetX: 100,
+//         offsetY: -100,
+//         scrollable: true,
+//         interactable: true,
+//         visible: false, // Start hidden
+//         zIndex: 1000
+//     })
+// }
+//
+// /**
+//  * Add a fixed HUD element
+//  */
+// export function addHudElement(object: IObject3D, htmlContent: string, x: number, y: number) {
+//     return EntityComponentPlugin.AddComponent(object, HtmlUiComponent, {
+//         htmlData: htmlContent,
+//         width: 200,
+//         height: 100,
+//         positionMode: 'screen',
+//         offsetX: x,
+//         offsetY: y,
+//         scrollable: false,
+//         interactable: true,
+//         visible: true,
+//         zIndex: 1001
+//     })
+// }
+//
+// /**
+//  * Add an interactive button panel
+//  */
+// export function addButtonPanel(object: IObject3D, onButtonClick: () => void) {
+//     const component = EntityComponentPlugin.AddComponent(object, HtmlUiComponent, {
+//         htmlData: `
+//             <div style="
+//                 background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+//                 padding: 15px;
+//                 border-radius: 10px;
+//                 box-shadow: 0 4px 16px rgba(0,0,0,0.3);
+//             ">
+//                 <button id="action-button" style="
+//                     background: white;
+//                     border: none;
+//                     padding: 10px 20px;
+//                     border-radius: 5px;
+//                     cursor: pointer;
+//                     font-weight: bold;
+//                     color: #667eea;
+//                     font-size: 14px;
+//                     transition: transform 0.2s;
+//                 ">
+//                     Click Me
+//                 </button>
+//             </div>
+//         `,
+//         width: 140,
+//         height: 70,
+//         positionMode: 'world',
+//         offsetY: 50,
+//         scrollable: false,
+//         interactable: true,
+//         visible: true,
+//         zIndex: 1000
+//     })
+//
+//     // Add event listener after component is initialized
+//     setTimeout(() => {
+//         const button = component.element?.querySelector('#action-button')
+//         if (button) {
+//             button.addEventListener('click', onButtonClick)
+//         }
+//     }, 0)
+//
+//     return component
+// }
+//
+// /**
+//  * Example: Complete usage scenario
+//  */
+// export function exampleUsage(viewer: IViewer, targetObject: IObject3D) {
+//     // Initialize
+//     initHtmlUiComponent(viewer)
+//
+//     // Add a label that follows the object
+//     const label = addObjectLabel(targetObject, 'Important Object')
+//
+//     // Add an info panel that can be toggled
+//     const infoPanel = addInfoPanel(
+//         targetObject,
+//         'Object Details',
+//         'This object has special properties. Click to learn more about its configuration.'
+//     )
+//
+//     // Add an interactive button
+//     const buttonPanel = addButtonPanel(targetObject, () => {
+//         // Toggle info panel visibility
+//         infoPanel.visible = !infoPanel.visible
+//         console.log('Button clicked! Info panel toggled.')
+//     })
+//
+//     // Add a fixed HUD
+//     const hud = addHudElement(
+//         targetObject,
+//         `<div style="background: rgba(0,0,0,0.8); color: white; padding: 10px; border-radius: 5px;">
+//             <strong>Status:</strong> Active
+//         </div>`,
+//         10,
+//         10
+//     )
+//
+//     // Return components for further manipulation
+//     return { label, infoPanel, buttonPanel, hud }
+// }
+//
+// /**
+//  * Dynamic content update example
+//  */
+// export function updateLabelContent(component: HtmlUiComponent, newText: string) {
+//     component.setHtml(`
+//         <div style="
+//             background: rgba(0, 0, 0, 0.8);
+//             color: white;
+//             padding: 8px 12px;
+//             border-radius: 5px;
+//             font-family: Arial, sans-serif;
+//             font-size: 14px;
+//             white-space: nowrap;
+//             box-shadow: 0 2px 8px rgba(0,0,0,0.3);
+//         ">
+//             ${newText}
+//         </div>
+//     `)
+// }
+//

package/src/plugins/HtmlUiComponent.md

@@ -0,0 +1,219 @@
+# HtmlUiComponent
+
+A component for attaching HTML UI elements to 3D objects in threepipe.
+
+## Features
+
+- **HTML Content**: Render any HTML content in a div element
+- **Position Modes**: 
+  - `world`: Follow a 3D object in world space (automatically projects to screen)
+  - `screen`: Fixed screen position (top-left corner)
+  - `viewport`: Viewport-relative positioning (using percentages)
+- **Customizable Properties**:
+  - Size (width, height in pixels)
+  - Scrollable content
+  - Interactable (pointer events)
+  - Visibility toggle
+  - Z-index control
+  - Offset positioning
+
+## Usage Example
+
+```typescript
+import { HtmlUiComponent } from './plugins/HtmlUiComponent'
+import { EntityComponentPlugin } from 'threepipe'
+
+// Register the component
+viewer.addPluginSync(EntityComponentPlugin)
+
+// Add component to an object
+const component = EntityComponentPlugin.AddComponent(myObject, HtmlUiComponent, {
+  htmlData: '<div style="background: white; padding: 10px; border-radius: 5px;">Object Label</div>',
+  width: 150,
+  height: 50,
+  positionMode: 'world',
+  offsetY: -50, // Position above the object
+  scrollable: false,
+  interactable: true,
+  visible: true,
+  zIndex: 1000
+})
+
+// Update HTML content
+component.setHtml('<div>Updated content</div>')
+
+// Change position
+component.setPosition(10, 20) // offsetX, offsetY
+
+// Change size
+component.setSize(200, 100)
+
+// Show/hide
+component.show()
+component.hide()
+```
+
+## Position Modes
+
+### World Mode
+Follows the 3D object's position in world space and projects it to screen coordinates.
+Perfect for labels, tooltips, or info panels attached to 3D objects.
+
+```typescript
+component.positionMode = 'world'
+component.offsetX = 0  // Pixel offset from projected position
+component.offsetY = -50 // Position 50px above the object
+```
+
+### Screen Mode
+Fixed position relative to the top-left corner of the screen.
+
+```typescript
+component.positionMode = 'screen'
+component.offsetX = 100  // 100px from left edge
+component.offsetY = 50   // 50px from top edge
+```
+
+### Viewport Mode
+Position relative to the viewport size (0-100 representing percentages).
+
+```typescript
+component.positionMode = 'viewport'
+component.offsetX = 50  // 50% from left (center)
+component.offsetY = 50  // 50% from top (center)
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `htmlData` | `string` | `'<div>Hello World</div>'` | HTML content to render |
+| `width` | `number` | `200` | Width in pixels (set to `-1` for auto) |
+| `height` | `number` | `150` | Height in pixels (set to `-1` for auto) |
+| `scrollable` | `boolean` | `false` | Enable scrolling for overflow content |
+| `interactable` | `boolean` | `true` | Enable pointer events (clickable) |
+| `visible` | `boolean` | `true` | Show/hide the element |
+| `appendToBody` | `boolean` | `false` | Append to `document.body` (true) or `viewer.container` (false, default). Can be changed dynamically - element will be moved. |
+| `positionMode` | `'world' \| 'screen' \| 'viewport'` | `'world'` | Position mode |
+| `offsetX` | `number` | `0` | X-axis offset in pixels (or % for viewport mode) |
+| `offsetY` | `number` | `0` | Y-axis offset in pixels (or % for viewport mode) |
+| `zIndex` | `number` | `1000` | CSS z-index value |
+
+## Methods
+
+### `setHtml(html: string)`
+Update the HTML content.
+
+### `setPosition(x: number, y: number)`
+Set the offset position.
+
+### `setSize(width: number, height: number)`
+Set the size of the element.
+
+### `show()`
+Show the element (sets `visible` to `true`).
+
+### `hide()`
+Hide the element (sets `visible` to `false`).
+
+## Advanced Examples
+
+### Interactive Button Panel
+```typescript
+const buttonPanel = EntityComponentPlugin.AddComponent(object, HtmlUiComponent, {
+  htmlData: `
+    <div style="background: rgba(0,0,0,0.8); color: white; padding: 10px; border-radius: 8px;">
+      <button onclick="alert('Button clicked!')">Click Me</button>
+    </div>
+  `,
+  width: 120,
+  height: 60,
+  positionMode: 'world',
+  interactable: true
+})
+```
+
+### Information Panel with Scroll
+```typescript
+const infoPanel = EntityComponentPlugin.AddComponent(object, HtmlUiComponent, {
+  htmlData: `
+    <div style="background: white; padding: 15px; font-family: Arial;">
+      <h3>Object Information</h3>
+      <p>Lorem ipsum dolor sit amet...</p>
+      <ul>
+        <li>Property 1</li>
+        <li>Property 2</li>
+        <li>Property 3</li>
+      </ul>
+    </div>
+  `,
+  width: 250,
+  height: 200,
+  scrollable: true,
+  positionMode: 'world'
+})
+```
+
+### Fixed HUD Element
+```typescript
+const hud = EntityComponentPlugin.AddComponent(object, HtmlUiComponent, {
+  htmlData: `
+    <div style="background: rgba(255,255,255,0.9); padding: 10px;">
+      <strong>Score:</strong> <span id="score">0</span>
+    </div>
+  `,
+  width: 150,
+  height: 40,
+  positionMode: 'screen',
+  offsetX: 10,
+  offsetY: 10,
+  interactable: false
+})
+```
+
+### Auto-Sized Element
+```typescript
+const autoSized = EntityComponentPlugin.AddComponent(object, HtmlUiComponent, {
+  htmlData: `
+    <div style="background: white; padding: 15px; border-radius: 5px;">
+      <h3>This content determines the size</h3>
+      <p>Width and height are automatic!</p>
+    </div>
+  `,
+  width: -1,  // Auto width
+  height: -1, // Auto height
+  positionMode: 'world'
+})
+```
+
+### Dynamically Switch Container
+```typescript
+const component = EntityComponentPlugin.AddComponent(object, HtmlUiComponent, {
+  htmlData: '<div style="background: white; padding: 10px;">My UI</div>',
+  width: 200,
+  height: 100,
+  appendToBody: false // Start in viewer.container
+})
+
+// Later, move to document.body (useful for full-screen overlays)
+component.appendToBody = true
+
+// Move back to viewer.container
+component.appendToBody = false
+```
+
+## Styling Tips
+
+- Use inline styles in the HTML for better control
+- Set `pointer-events: none` on non-interactive elements within the HTML if needed
+- Use `rgba()` colors for transparency
+- The element has CSS class `threepipe-html-ui` for global styling
+
+## Notes
+
+- Elements are automatically cleaned up when the component is destroyed
+- World-positioned elements use `requestAnimationFrame` for smooth tracking
+- By default, elements are appended to `viewer.container` (set `appendToBody: true` to append to `document.body` instead)
+- The element is positioned absolutely within its container
+- Transform origin is centered for world-positioned elements (`translate(-50%, -50%)`)
+