@needle-tools/engine 5.1.0-canary.fbdfce3 → 5.1.0-experimental.03e8105

package/plugins/dts-generator/index.js

@@ -1,36 +0,0 @@
-// @ts-check
-/**
- * Needle Engine — HTML binding DTS generator
- *
- * Scans all GLB/glTF files in the project's assets directory, extracts
- * NEEDLE_components data, and emits a `needle-bindings.d.ts` virtual-module
- * declaration so that TypeScript can type-check HTML ↔ 3D component bindings.
- *
- * Typical generated output:
- *
- *   declare module "needle-bindings" {
- *     interface SceneData {
- *       Sphere: {
- *         MyBall: { speed: number; label: string; };
- *       };
- *     }
- *   }
- *
- * How component field types are resolved:
- *   - For built-in Needle Engine components, types are read from
- *     `components.needle.json` which lists only @serializable fields with
- *     their proper TypeScript types.
- *   - For user-defined components (not in the manifest), types are inferred
- *     from the JSON value in the GLB (number/string/boolean → typed, else → unknown).
- *   - Known Three.js types (Color, Vector3, Object3D, …) are emitted as
- *     `import("three").TypeName` and known Needle types (RGBAColor, AssetReference, …)
- *     as `import("@needle-tools/engine").TypeName`.
- *   - Truly unknown types fall back to `unknown`.
- */
-
-export { resolveEntrypointGlbs, collectSceneFiles } from './glb.discovery.js';
-export { readGlbJsonChunk, readGltfJsonFile, readRemoteGlbJsonChunk } from './glb.reader.js';
-export { extractComponentBindings, sanitizeNodeName, inferNodeThreeType, inferTsType } from './glb.extractor.js';
-export { scanBindings } from './dts.scan.js';
-export { generateDts, generateHtmlCustomData } from './dts.codegen.js';
-export { generateBindingsDts } from './dts.writer.js';

package/plugins/dts-generator/manifest.types.js

@@ -1,174 +0,0 @@
-// @ts-check
-/**
- * Type tables and components.needle.json manifest loader.
- *
- * Knows about primitive TS types, known Three.js types, known Needle Engine
- * types, and how to resolve field types from the manifest.
- */
-
-import { existsSync, readFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-/** Primitive TS type strings that can safely appear in an ambient declaration. */
-export const PRIMITIVE_TYPES = new Set(["number", "string", "boolean"]);
-
-/**
- * Known Three.js types → import("three").TypeName
- * @type {Record<string, string>}
- */
-export const THREE_TYPES = {
-    Color: `import("three").Color`,
-    ColorRepresentation: `import("three").ColorRepresentation`,
-    Euler: `import("three").Euler`,
-    Texture: `import("three").Texture`,
-    // Materials
-    Material: `import("three").Material`,
-    MeshStandardMaterial: `import("three").MeshStandardMaterial`,
-    // Objects
-    Object3D: `import("three").Object3D`,
-    Mesh: `import("three").Mesh`,
-    SkinnedMesh: `import("three").SkinnedMesh`,
-    // Other
-    Vector2: `import("three").Vector2`,
-    Vector3: `import("three").Vector3`,
-    Vector4: `import("three").Vector4`,
-    Matrix3: `import("three").Matrix3`,
-    Matrix4: `import("three").Matrix4`,
-    Quaternion: `import("three").Quaternion`,
-    // Animation
-    AnimationClip: `import("three").AnimationClip`,
-    AnimationMixer: `import("three").AnimationMixer`,
-};
-
-/**
- * Known Needle Engine types → import("@needle-tools/engine").TypeName
- * @type {Record<string, string>}
- */
-export const NEEDLE_TYPES = {
-    AssetReference: `import("@needle-tools/engine").AssetReference`,
-    EventList: `import("@needle-tools/engine").EventList`,
-    GameObject: `import("@needle-tools/engine").GameObject`,
-    LookAtConstraint: `import("@needle-tools/engine").LookAtConstraint`,
-    RGBAColor: `import("@needle-tools/engine").RGBAColor`,
-    RenderTexture: `import("@needle-tools/engine").RenderTexture`,
-    Renderer: `import("@needle-tools/engine").Renderer`,
-    Rigidbody: `import("@needle-tools/engine").Rigidbody`,
-    Sprite: `import("@needle-tools/engine").Sprite`,
-    Vec2: `import("@needle-tools/engine").Vec2`,
-};
-
-/**
- * Map a single non-array, non-primitive type token to its TS representation.
- * Returns null if unknown.
- * @param {string} token
- * @returns {string | null}
- */
-function mapKnownType(token) {
-    if (token in THREE_TYPES) return THREE_TYPES[token];
-    if (token in NEEDLE_TYPES) return NEEDLE_TYPES[token];
-    return null;
-}
-
-/**
- * Convert a manifest type string to a safe ambient TS type.
- * Primitives and known Three.js/Needle types are resolved precisely.
- * For unknown types on a manifest component, falls back to
- * `import("@needle-tools/engine").ComponentName["fieldName"]`.
- * Truly unresolvable types → "unknown".
- *
- * @param {string} typeStr
- * @param {string} [componentName]  The manifest component class name (enables indexed-access fallback)
- * @param {string} [fieldName]      The field name on that component
- * @returns {string}
- */
-export function manifestTypeToTs(typeStr, componentName, fieldName) {
-    const parts = typeStr.split(" | ").map(p => p.trim());
-    const safeParts = parts.map(p => {
-        if (p === "undefined" || p === "null") return p;
-        const arrayMatch = p.match(/^(number|string|boolean)\[\]$/);
-        if (arrayMatch) return p;
-        if (PRIMITIVE_TYPES.has(p)) return p;
-        const arrayTypeMatch = p.match(/^(\w+)\[\]$/);
-        if (arrayTypeMatch) {
-            const base = arrayTypeMatch[1];
-            const mapped = mapKnownType(base);
-            if (mapped) return `${mapped}[]`;
-        }
-        const known = mapKnownType(p);
-        if (known) return known;
-        return null;
-    });
-    if (safeParts.every(p => p !== null)) {
-        return /** @type {string[]} */ (safeParts).join(" | ");
-    }
-    if (componentName && fieldName) {
-        return `import("@needle-tools/engine").${componentName}["${fieldName}"]`;
-    }
-    return "unknown";
-}
-
-/**
- * Load components.needle.json and build a lookup:
- *   componentName → Map<fieldName, tsType>
- * Inherited fields are flattened (inheritedFrom chain is resolved).
- *
- * @returns {Map<string, Map<string, string>>}
- */
-export function loadComponentsManifest() {
-    /** @type {Map<string, Map<string, string>>} */
-    const manifest = new Map();
-    const manifestPath = join(__dirname, "../../components.needle.json");
-    if (!existsSync(manifestPath)) return manifest;
-    try {
-        /** @type {Array<{name: string, inheritedFrom?: string, children?: Array<{name: string, kind: string, type: string}>}>} */
-        const entries = JSON.parse(readFileSync(manifestPath, "utf8"));
-
-        /** @type {Map<string, Map<string, string>>} */
-        const ownFields = new Map();
-        /** @type {Map<string, string>} */
-        const inheritedFrom = new Map();
-        for (const entry of entries) {
-            if (!entry.name) continue;
-            inheritedFrom.set(entry.name, entry.inheritedFrom || "");
-            /** @type {Map<string, string>} */
-            const fields = new Map();
-            if (Array.isArray(entry.children)) {
-                for (const child of entry.children) {
-                    if (child.kind === "property" && child.name && child.type) {
-                        fields.set(child.name, manifestTypeToTs(child.type, entry.name, child.name));
-                    }
-                }
-            }
-            ownFields.set(entry.name, fields);
-        }
-
-        /** @param {string} name @returns {Map<string, string>} */
-        function resolveFields(name) {
-            if (manifest.has(name)) return /** @type {Map<string, string>} */ (manifest.get(name));
-            const own = ownFields.get(name) ?? new Map();
-            const parent = inheritedFrom.get(name);
-            if (parent && ownFields.has(parent)) {
-                const parentFields = resolveFields(parent);
-                const merged = new Map([...parentFields, ...own]);
-                manifest.set(name, merged);
-                return merged;
-            }
-            manifest.set(name, own);
-            return own;
-        }
-
-        for (const name of ownFields.keys()) {
-            resolveFields(name);
-        }
-    } catch (e) {
-        console.warn("[needle:dts-generator] Failed to load components.needle.json:", (/** @type {any} */ (e))?.message ?? e);
-    }
-    return manifest;
-}
-
-/** @type {Map<string, Map<string, string>>} */
-export const componentsManifest = loadComponentsManifest();

package/plugins/gltf-packer.mjs

@@ -1 +0,0 @@
-console.error('ERR: this is an old version of the gltf packer, please update gltf-pack in your package.json. The pack-gltf script should now look something like this: "npm run pack-gltf --prefix node_modules/@needle-tools/engine" \nSee the ExportInfo component for more info.');

package/src/engine-components/AvatarLoader.ts

@@ -1,264 +0,0 @@
-import { Box3, Object3D, Vector3 } from "three";
-import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
-
-import { InstantiateOptions } from "../engine/engine_gameobject.js";
-import { getLoader } from "../engine/engine_gltf.js";
-import * as loaders from "../engine/engine_loaders.gltf.js"
-import { Context } from "../engine/engine_setup.js";
-import * as utils from "../engine/engine_utils.js"
-import { GameObject } from "./Component.js";
-
-const debug = utils.getParam("debugavatar");
-
-/**
- * Represents an avatar model with head and hands references.
- * Used for representing characters in 3D space.
- */
-export class AvatarModel {
-    /** The root object of the avatar model */
-    root: Object3D;
-    /** The head object of the avatar model */
-    head: Object3D;
-    /** The left hand object of the avatar model, if available */
-    leftHand: Object3D | null;
-    /** The right hand object of the avatar model, if available */
-    rigthHand: Object3D | null;
-
-
-    /**
-     * Checks if the avatar model has a valid configuration.
-     * An avatar is considered valid if it has a head.
-     * @returns Whether the avatar has a valid setup
-     */
-    get isValid(): boolean {
-        return this.head !== null && this.head !== undefined;
-    }
-
-    /**
-     * Creates a new avatar model.
-     * @param root The root object of the avatar
-     * @param head The head object of the avatar
-     * @param leftHand The left hand object of the avatar
-     * @param rigthHand The right hand object of the avatar
-     */
-    constructor(root: Object3D, head: Object3D, leftHand: Object3D | null, rigthHand: Object3D | null) {
-        this.root = root;
-        this.head = head;
-        this.leftHand = leftHand;
-        this.rigthHand = rigthHand;
-        this.root?.traverse(h => h.layers.set(2));
-        // this.head?.traverse(h => h.layers.set(2));
-        // this.leftHand?.traverse(h => h.layers.set(2));
-        // this.rigthHand?.traverse(h => h.layers.set(2));
-    }
-}
-
-/**
- * Handles loading and instantiating avatar models from various sources.
- * Provides functionality to find and extract important parts of an avatar (head, hands).
- * 
- * Debug mode can be enabled with the URL parameter `?debugavatar`,
- * which will log detailed information about avatar loading and configuration.
- */
-export class AvatarLoader {
-
-    private readonly avatarRegistryUrl: string | null = null;
-    // private loader: GLTFLoader | null;
-    // private avatarModelCache: Map<string, AvatarModel | null> = new Map<string, AvatarModel | null>();
-
-    /**
-     * Retrieves or creates a new avatar instance from an ID or existing Object3D.
-     * @param context The application context
-     * @param avatarId Either a string ID to load an avatar or an existing Object3D to use as avatar
-     * @returns Promise resolving to an AvatarModel if successful, or null if failed
-     */
-    public async getOrCreateNewAvatarInstance(context: Context, avatarId: string | Object3D): Promise<AvatarModel | null> {
-
-        if (!avatarId) {
-            console.error("Can not create avatar: failed to provide id or root object");
-            return null;
-        }
-
-        let root: Object3D | null = null;
-        if (typeof avatarId === "string") {
-            root = await this.loadAvatar(context, avatarId);
-            if (!root) {
-                const opts = new InstantiateOptions();
-                // opts.parent = context.scene.uuid;
-                root = GameObject.instantiate(utils.tryFindObject(avatarId, context.scene) as Object3D, opts);
-            }
-        }
-        else root = avatarId;
-
-        if (!root) {
-            return null;
-        }
-        const model = this.findAvatar(root);
-        // model.assignRandomColors();
-        // this.cacheModel(avatarId, model);
-
-        if (model.isValid) {
-            if (debug)
-                console.log("[Custom Avatar] valid config", avatarId, debug ? model : "");
-            return model;
-        }
-        else {
-            console.warn("[Custom Avatar] config isn't valid", avatarId, debug ? model : "");
-            return null;
-        }
-    }
-
-
-    /**
-     * Loads an avatar model from a file or registry using the provided ID.
-     * @param context The engine context
-     * @param avatarId The ID of the avatar to load
-     * @returns Promise resolving to the loaded avatar's Object3D, or null if failed
-     */
-    private async loadAvatar(context: Context, avatarId: string): Promise<Object3D | null> {
-
-        console.assert(avatarId !== undefined && avatarId !== null && typeof avatarId === "string", "Avatar id must not be null");
-        if (avatarId.length <= 0) return null;
-        if (!avatarId) return null;
-
-        if (debug)
-            console.log("[Custom Avatar] " + avatarId + ", loading...");
-        // should probably be done by the server?!
-        if (!avatarId.endsWith(".glb"))
-            avatarId += ".glb";
-
-
-        // for the demo we use the storage backend we uploaded the avatar to (by file drop)
-        if (this.avatarRegistryUrl === null) {
-            // try loading avatar from local file
-            const download_res = await fetch("./" + avatarId);
-            let bin: ArrayBuffer | null = null;
-            if (download_res.ok) {
-                const blob = await download_res.blob();
-                if (blob) bin = await blob.arrayBuffer();
-            }
-            if (!bin) {
-                // bin = await BlobStorage.download(avatarId, avatarId, 0, "no url here go away", true);
-                return null;
-            }
-
-            const gltf = await getLoader().parseSync(context, bin, null!, 0);
-            return gltf?.scene ?? null;
-        }
-
-
-        // if (this.avatarModelCache.has(avatarId)) {
-        //     console.log("[Custom Avatar] " + avatarId + ", found in cache");
-        //     return new Promise((res, _) => {
-        //         var model = this.avatarModelCache.get(avatarId)?.createNewInstance();
-        //         res(model);
-        //     });
-        // }
-        // return null;
-
-        const loader = new GLTFLoader();
-        loaders.addDracoAndKTX2Loaders(loader, context);
-
-        // TODO: cache binary (fetch finary from model gallery and use binary method)
-        return new Promise((resolve, _reject) => {
-            const url = this.avatarRegistryUrl + "/" + avatarId;
-            loader.load(url,
-                async gltf => {
-                    await getLoader().createBuiltinComponents(context, url, gltf, null, undefined);
-                    resolve(gltf.scene);
-                },
-                progress => {
-                    if (debug)
-                        console.log("[Custom Avatar] " + (progress.loaded / progress.total * 100) + '% loaded of ' + (progress.total / 1024) + "kB");
-                },
-                error => {
-                    console.error("[Custom Avatar] " + "Error when loading: " + error);
-                    resolve(null);
-                }
-            );
-        });
-    }
-
-    /**
-     * Caches an avatar model for reuse.
-     * @param _id The ID to associate with the model
-     * @param _model The avatar model to cache
-     */
-    private cacheModel(_id: string, _model: AvatarModel) {
-        // this.avatarModelCache.set(id, model);
-    }
-
-    /**
-     * Analyzes an Object3D to find avatar parts (head, hands) based on naming conventions.
-     * @param obj The Object3D to search for avatar parts
-     * @returns A structured AvatarModel with references to found parts
-     */
-    private findAvatar(obj: Object3D): AvatarModel {
-
-        const root: Object3D = obj;
-        let searchIn = root;
-        // some GLTFs have a "scene" root it seems, others don't, we skip the root here if there's only one child
-        if (searchIn.children.length == 1)
-            searchIn = obj.children[0];
-        let head = this.findAvatarPart(searchIn, ["head"]);
-
-        const leftHand = this.findAvatarPart(searchIn, ["left", "hand"]);
-        const rightHand = this.findAvatarPart(searchIn, ["right", "hand"]);
-
-        if (!head) {
-            // very last fallback, entire root is used as head
-            head = root;
-
-            // normalize size, if the object isn't properly setup the scale might be totally off
-            const boundsSize = new Vector3();
-            new Box3().setFromObject(head).getSize(boundsSize);
-            const maxAxis = Math.max(boundsSize.x, boundsSize.y, boundsSize.z);
-            console.warn("[Custom Avatar] " + "Normalizing head scale, it's too big: " + maxAxis + " meters! Should be < 0.3m");
-            if (maxAxis > 0.3) {
-                head.scale.multiplyScalar(1.0 / maxAxis * 0.3);
-            }
-        }
-
-        const model = new AvatarModel(root, head, leftHand, rightHand);
-        return model;
-    }
-
-    /**
-     * Recursively searches for an avatar part by name within an Object3D hierarchy.
-     * @param obj The Object3D to search within
-     * @param searchString Array of strings that should all be present in the object name
-     * @returns The found Object3D part or null if not found
-     */
-    private findAvatarPart(obj: Object3D, searchString: string[]): Object3D | null {
-
-        const name = obj.name.toLowerCase();
-        let matchesAll = true;
-        for (const str of searchString) {
-            if (!matchesAll) break;
-            if (name.indexOf(str) === -1)
-                matchesAll = false;
-        }
-        if (matchesAll) return obj;
-
-        if (obj.children) {
-            for (const child of obj.children) {
-                const found = this.findAvatarPart(child, searchString);
-                if (found) return found;
-            }
-        }
-        return null;
-    }
-
-    /**
-     * Handles HTTP response errors from avatar loading operations.
-     * @param response The fetch API response to check
-     * @returns The response if it was ok
-     * @throws Error with status text if response was not ok
-     */
-    private handleCustomAvatarErrors(response) {
-        if (!response.ok) {
-            throw Error(response.statusText);
-        }
-        return response;
-    }
-}

package/src/engine-components/avatar/AvatarBlink_Simple.ts

@@ -1,70 +0,0 @@
-import { Object3D } from "three";
-
-import { serializable } from "../../engine/engine_serialization_decorator.js";
-import { Behaviour, GameObject } from "../Component.js";
-import { XRFlag } from "../webxr/XRFlag.js";
-
-
-/** @internal */
-export class AvatarBlink_Simple extends Behaviour {
-
-    @serializable(Object3D)
-    private eyes: Object3D[] = [];
-    @serializable()
-    private lastBlinkTime: number = 0;
-    @serializable()
-    private blinkLength: number = 0;
-    @serializable()
-    private eyesOpen: boolean = true;
-
-    private state : XRFlag | null = null;
-
-    awake(){
-        this.state = GameObject.getComponentInParent(this.gameObject, XRFlag);
-        // console.log(this.state, this.activeAndEnabled, this.gameObject);
-    }
-
-    public update() {
-        if (!this.gameObject || !this.gameObject.visible) return;
-        if(!this.eyes || !Array.isArray(this.eyes) || this.eyes.length === 0) return;
-
-        const needsUpdate = this.context.time.time - this.lastBlinkTime > this.blinkLength;
-
-        if (needsUpdate) {
-            this.lastBlinkTime = this.context.time.time;
-
-            // workaround until we propagate active state to all child components
-            if(this.state && !this.state.isOn) return;
-            if(!this.activeAndEnabled) return;
-
-            // console.log(this.state?.isOn, this.activeAndEnabled);
-
-            this.eyesOpen = !this.eyesOpen;
-            this.blinkLength = Math.random();
-            if (!this.eyesOpen) {
-                this.blinkLength *= Math.random() * .2;
-                this.blinkLength += .1;
-            }
-            else {
-                // eyes are open
-                this.blinkLength *= 3;
-                this.blinkLength += .5;
-                if (Math.random() < .1) this.blinkLength = .1 + Math.random() * .2;
-            }
-            if (Math.random() < .1) this.blinkLength *= 3;
-
-            // if(time.time - this.lastMouthChangeTime < .5 && Math.random() > .5){
-            //     this.blinkLength *= 1-(100/this.lastMouthChangeFrequency);
-            // }
-
-            this.blinkLength = Math.max(.2, this.blinkLength);
-            this.blinkLength = Math.min(3, this.blinkLength);
-            if (this.eyes) {
-                for (const eye of this.eyes) {
-                    if (eye)
-                        eye.visible = this.eyesOpen;
-                }
-            }
-        }
-    }
-}

package/src/engine-components/avatar/AvatarEyeLook_Rotation.ts

@@ -1,64 +0,0 @@
-import { Object3D, Vector3 } from "three";
-
-import { serializable } from "../../engine/engine_serialization_decorator.js";
-import * as utils from "../../engine/engine_three_utils.js"
-import { Behaviour, GameObject } from "../Component.js";
-import { Avatar_Brain_LookAt } from "./Avatar_Brain_LookAt.js";
-
-/** @internal */
-export class AvatarEyeLook_Rotation extends Behaviour {
-
-    @serializable(Object3D)
-    public head: GameObject | null = null;
-    @serializable(Object3D)
-    public eyes: GameObject[] | null = null;
-    @serializable(Object3D)
-    public target: Object3D | null = null;
-
-    private brain: Avatar_Brain_LookAt | null = null;
-
-    awake(): void {
-        if (!this.brain) {
-            this.brain = GameObject.getComponentInParent(this.gameObject, Avatar_Brain_LookAt);
-        }
-        if (!this.brain) {
-            this.brain = GameObject.addComponent(this.gameObject, Avatar_Brain_LookAt);
-        }
-        if (this.brain && this.target) {
-            this.brain.controlledTarget = this.target;
-        }
-    }
-
-
-    private vec: Vector3 = new Vector3();
-    private static forward: Vector3 = new Vector3(0, 0, 1);
-    private currentTargetPoint: Vector3 = new Vector3();
-
-    update(): void {
-        // if(!this.activeAndEnabled) return;
-        const target = this.target;
-        // console.log(target);
-        if (target && this.head) {
-            const eyes = this.eyes;
-            if (eyes) {
-                const worldTarget = utils.getWorldPosition(target);
-                this.currentTargetPoint.lerp(worldTarget, this.context.time.deltaTime / .1);
-
-                const headPosition = utils.getWorldPosition(this.head);
-                const direction = this.vec.copy(this.currentTargetPoint).sub(headPosition).normalize();
-                if (direction.length() < .1) return;
-                const forward = AvatarEyeLook_Rotation.forward;
-                forward.set(0, 0, 1);
-                forward.applyQuaternion(utils.getWorldQuaternion(this.head));
-                const dot = forward.dot(direction);
-                if (dot > .45) {
-                    // console.log(dot);
-                    for (let i = 0; i < eyes.length; i++) {
-                        const eye = eyes[i];
-                        eye.lookAt(this.currentTargetPoint);
-                    }
-                }
-            }
-        }
-    }
-}