@needle-tools/engine/plugins/vite/local-files-types.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.

/**
 * Shared type declarations for the local-files plugin family.
 * Referenced from local-files-utils.js, local-files-analysis.js, local-files-core.js, etc.
 */

export interface UrlHandler {
    name: string;
    /** RegExp with the /g flag — match group 1 must capture the URL. */
    pattern: RegExp;
    type: "binary" | "css" | "decoder-dir" | "webxr-profiles";
    feature: string;
    decoderFiles?: string[];
    localDirName?: string;
}

export interface LocalizationStats {
    fileCount: number;
    totalBytes: number;
    mimeCounts: Map<string, number>;
}

/**
 * Configuration for the `makeFilesLocal` build plugin.
 * Controls which external CDN assets are downloaded at build time and bundled locally,
 * producing fully self-contained deployments that work without internet access.
 * Useful for playable ads, app stores requiring single-origin bundles, offline PWAs,
 * and restricted hosting environments.
 */
export interface LocalizationOptions {
    /**
     * Which feature categories to include when downloading assets.
     * - `"auto"` — scan project scene files and source code to detect which features are actually used, then only download those.
     * - `string[]` — explicit list of feature names. When set, **only** these features are processed.
     * - When omitted, **all** features are included.
     *
     * Available features:
     * `"draco"`, `"ktx2"`, `"materialx"`, `"xr"`, `"skybox"`, `"fonts"`,
     * `"needle-fonts"`, `"needle-models"`, `"needle-avatars"`, `"needle-branding"`,
     * `"polyhaven"`, `"cdn-scripts"`, `"github-content"`, `"threejs-models"`, `"needle-uploads"`
     *
     * @example
     * features: "auto"
     * @example
     * features: ["draco", "ktx2", "fonts"]
     */
    features?: string | string[];
    /**
     * Feature categories to exclude. Applied **after** `features` (including after auto-detection).
     * Use this to opt out of specific categories you don't need without having to list every other one.
     *
     * @example
     * // Auto-detect everything except XR controller profiles
     * { features: "auto", excludeFeatures: ["xr"] }
     */
    excludeFeatures?: string[];
    /** URL substrings or RegExps to skip. */
    exclude?: (string | RegExp)[];
    /** @deprecated use `exclude` */
    excludeUrls?: string[];
    /** e.g. "facebook-instant", "discord" */
    platform?: string;
    /** Only process files inside these npm packages. */
    packages?: string[];
    /** Skybox selection: URL, magic keyword, array of those, or "all". */
    skybox?: string | string[];
    /** WebXR controller profile mode: "minimal" | "quest" | "pico" | "all" */
    webxr?: string;
    /**
     * Template-based URL expansion rules. Used for CDN URLs that contain template-literal
     * variables (e.g. `${version}`, `${platform}`). The plugin expands every combination
     * of the provided variable values, downloads each concrete URL, and rewrites the
     * template literal to point at the local copy.
     *
     * @example
     * templateExpansions: [{
     *   cdnPrefix: "https://cdn.example.com/decoders/",
     *   variables: { version: ["v1", "v2"], arch: ["wasm", "js"] },
     *   localPrefix: "decoders"   // optional — derived from cdnPrefix when omitted
     * }]
     */
    templateExpansions?: Array<{
        /** The CDN base URL that the template literals start with. */
        cdnPrefix: string;
        /** Map of variable names to all possible values. Every combination is expanded and downloaded. */
        variables: Record<string, string[]>;
        /** Local output subdirectory. Derived from `cdnPrefix` hostname when omitted. */
        localPrefix?: string;
    }>;
    /** Used when makeFilesLocal is an object — set to false to disable. */
    enabled?: boolean;
}

export interface AutoPolicy {
    features: Set<string>;
    hasWebXR: boolean;
    hasVideoPlayer: boolean;
    allowedSkyboxUrls: Set<string> | null;
    selectedWebXRProfiles: string[];
}

export interface LocalizationContext {
    /** The Rollup plugin context, available during build hooks (null in dev/serve). */
    pluginContext: import('rollup').PluginContext | null;
    cache: {
        addToCache(key: string, value: Buffer | string): void;
        getFromCache(key: string): Buffer | string | null;
        readonly map: Map<string, Buffer | string>;
    };
    command: "build" | "serve";
    viteConfig: { build?: { assetsDir?: string } } | null;
    options: LocalizationOptions;
    autoPolicy: AutoPolicy | null;
    failedDownloads: Map<string, string>;
    localizationStats: LocalizationStats;
}

export interface SceneAnalysisReport {
    hasWebXRComponent: boolean;
    hasVideoPlayerComponent: boolean;
    extensions: Set<string>;
    componentTypes: Set<string>;
    componentCounts: Map<string, number>;
    glbFileCount: number;
    gltfFileCount: number;
    totalSceneFileCount: number;
    totalNodeCount: number;
    totalVertexCount: number;
    totalTextureCount: number;
    totalMeshCount: number;
    totalPrimitiveCount: number;
    dracoPrimitiveCount: number;
    meshoptBufferViewCount: number;
}

export interface SceneFile {
    path: string;
    type: "glb" | "gltf";
}

export interface NeedleComponentEntry {
    name?: string;
    type?: string;
    guid?: string;
}

export interface NeedleComponentExtension {
    components?: NeedleComponentEntry[];
    builtin_components?: NeedleComponentEntry[];
}