@needle-tools/engine/lib/engine/engine_create_objects.d.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

import { ColorRepresentation, Group, Material, Mesh, Object3D, Sprite, Texture } from "three";
import { Font } from "three/examples/jsm/loaders/FontLoader.js";
import type { Vec3 } from "./engine_types.js";
export declare enum PrimitiveType {
    /**
     * A quad with a width and height of 1 facing the positive Z axis
     */
    Quad = 0,
    /**
     * A cube with a width, height, and depth of 1
     */
    Cube = 1,
    Sphere = 2,
    Cylinder = 3,
    RoundedCube = 10
}
export type PrimitiveTypeNames = keyof typeof PrimitiveType;
/**
 * Options to create an object. Used by {@link ObjectUtils.createPrimitive}
 */
export type ObjectOptions = {
    /**
     * The parent object to add the created object to
     */
    parent?: Object3D;
    /**
     * The name of the object
     */
    name?: string;
    /** The material to apply to the object */
    material?: Material;
    /** The color of the object. This color will only be used if no material is provided */
    color?: ColorRepresentation;
    /** The texture will applied to the material's main texture slot e.g. `material.map` if any is passed in */
    texture?: Texture;
    /**
     * The position of the object in local space
     */
    position?: Vec3 | [number, number, number];
    /** The rotation of the object in local space */
    rotation?: Vec3 | [number, number, number];
    /**
     * The scale of the object in local space
     */
    scale?: Vec3 | number | [number, number, number];
    /**
     * If the object should receive shadows
     * @default true
     */
    receiveShadow?: boolean;
    /**
     * If the object should cast shadows
     * @default true
     */
    castShadow?: boolean;
};
/**
 * Options to create a 3D text object. Used by {@link ObjectUtils.createText}
 */
export type TextOptions = Omit<ObjectOptions, "texture"> & {
    /**
     * Optional: The font to use for the text. If not provided, the default font will be used
     */
    font?: Font;
    /**
     * If the font is not provided, the familyFamily can be used to load a font from the default list
     */
    familyFamily?: "OpenSans" | "Helvetiker";
    /**
     * Optional: The depth of the text.
     * @default .1
     */
    depth?: number;
    /**
     * Optional: If the text should have a bevel effect
     * @default false
    */
    bevel?: boolean;
    /**
     * Invoked when the font geometry is loaded
     */
    onGeometry?: (obj: Mesh) => void;
};
/**
 * Utility class to create primitive objects
 * @example
 * ```typescript
 * const cube = ObjectUtils.createPrimitive("Cube", { name: "Cube", position: { x: 0, y: 0, z: 0 } });
 * ```
 */
export declare class ObjectUtils {
    #private;
    /**
     * Creates a 3D text object
     * @param text The text to display
     * @param opts Options to create the object
     */
    static createText(text: string, opts?: TextOptions): Mesh;
    /**
     * Creates an occluder object that only render depth but not color
     * @param type The type of primitive to create
     * @returns The created object
     */
    static createOccluder(type: PrimitiveTypeNames): Mesh;
    /** Creates a primitive object like a Cube or Sphere
     * @param type The type of primitive to create
     * @param opts Options to create the object
     * @returns The created object
    */
    static createPrimitive(type: "ShaderBall", opts?: ObjectOptions): Group;
    static createPrimitive(type: PrimitiveType | PrimitiveTypeNames, opts?: ObjectOptions): Mesh;
    /**
     * Creates a Sprite object
     * @param opts Options to create the object
     * @returns The created object
     */
    static createSprite(opts?: Omit<ObjectOptions, "material">): Sprite;
    private static applyDefaultObjectOptions;
}