orbix-engine 1.0.0

package/dist/orbix.d.ts

@@ -0,0 +1,1460 @@
+// Orbix Engine — TypeScript Definitions
+// Built on Active Theory Hydra Framework
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shared utility types
+// ─────────────────────────────────────────────────────────────────────────────
+
+type RenderCallback = (time: number, dt: number) => void;
+type EaseName = string;  // e.g. 'easeOutCubic', 'linear', 'easeInOutQuad'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Top-level Orbix namespace
+// ─────────────────────────────────────────────────────────────────────────────
+
+declare namespace Orbix {
+
+    // ── VERSION ──────────────────────────────────────────────────────────────
+    const VERSION: string;
+    const ORIGINAL: string;
+
+    // ── BOOT HELPERS ─────────────────────────────────────────────────────────
+    function ready(): Promise<typeof Orbix>;
+    function check(): { supported: boolean; webgl: boolean; mobile: boolean; gpu: string; tier: string; reason?: string };
+    const supported: boolean;
+
+    // ── SCENE HELPERS ─────────────────────────────────────────────────────────
+    function createScene(options?: Record<string, any>): { scene: Scene; camera: PerspectiveCamera; nuke: Nuke; renderer: Renderer; element: HTMLCanvasElement };
+    function createShader(vertexName: string, fragmentName?: string, uniforms?: Record<string, any>): Shader;
+    function createPhysicalShader(uniforms?: Record<string, any>): Shader;
+    function loadGeometry(path: string): Promise<Geometry>;
+    function getTexture(path: string): Texture;
+    function getRepeatTexture(path: string): Texture;
+    function createFluid(options?: { simSize?: number; dyeSize?: number; rect?: any }): Fluid;
+    function createMouseFluid(): MouseFluid;
+    function createAntimatter(options?: Record<string, any>): Antimatter;
+    function createMeshBatch(): MeshBatch;
+    function createNukePass(shaderName: string, uniforms?: Record<string, any>): NukePass;
+
+    // ── RENDER HELPERS ────────────────────────────────────────────────────────
+    function onRender(callback: RenderCallback): { stop(): void };
+
+    // ── CLASS SYSTEM HELPERS ──────────────────────────────────────────────────
+    function define(name: string, constructor: Function): any;
+    function tween(obj: any, props: Record<string, any>, duration: number, ease?: EaseName, delay?: number): any;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // CORE FRAMEWORK
+    // ─────────────────────────────────────────────────────────────────────────
+
+    function Class(constructor: Function): void;
+    function Inherit(target: any, ...mixins: any[]): void;
+
+    class Component {
+        flag(name: string, value?: boolean): boolean;
+        on(event: string, callback: Function): this;
+        off(event: string, callback: Function): this;
+        dispatch(event: string, ...args: any[]): void;
+    }
+
+    class Element extends Component {
+        div: HTMLElement;
+        create(tag?: string, className?: string): void;
+    }
+
+    class Model extends Component {
+        get(key: string): any;
+        set(key: string, value: any): void;
+    }
+
+    const Events: {
+        on(event: string, callback: Function, scope?: any): void;
+        off(event: string, callback: Function, scope?: any): void;
+        dispatch(event: string, ...args: any[]): void;
+    };
+
+    const Timer: {
+        create(callback: Function, time: number, ...args: any[]): number;
+        destroy(id: number): void;
+    };
+
+    const Hydra: {
+        LOCAL: boolean;
+        VERSION: string;
+        init(params: Record<string, any>): void;
+    };
+
+    const Global: { [key: string]: any };
+    const Utils: { [key: string]: any };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // STATE MANAGEMENT
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const AppState: {
+        get(key: string): any;
+        set(key: string, value: any, scope?: any): void;
+        on(key: string, callback: Function, scope?: any): void;
+        createLocal(obj: object, nonReactive?: boolean): object;
+    };
+
+    class DerivedState { constructor(state: any, deriveFunc: Function); }
+    class StateArray { constructor(initial?: any[]); push(item: any): void; remove(item: any): void; }
+    class StateComponent extends Component {}
+    class StateInitializer { constructor(config: object); }
+    class ViewState extends Component { constructor(config?: object); }
+    const Storage: { get(key: string): any; set(key: string, value: any): void; remove(key: string): void; };
+    const Data: { [key: string]: any };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // DATA STRUCTURES
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Gate { constructor(count: number, callback: Function); tick(): void; }
+    class LinkedList { add(item: any): void; remove(item: any): void; forEach(cb: Function): void; }
+    class ObjectPool { constructor(factory: Function, initialSize?: number); get(): any; release(item: any): void; }
+    class XComponent extends Component {}
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // MATH
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Vector2 {
+        constructor(x?: number, y?: number);
+        x: number; y: number;
+        set(x: number, y: number): this;
+        copy(v: Vector2): this;
+        add(v: Vector2): this;
+        sub(v: Vector2): this;
+        multiply(v: Vector2): this;
+        multiplyScalar(s: number): this;
+        divideScalar(s: number): this;
+        length(): number;
+        lengthSq(): number;
+        normalize(): this;
+        lerp(v: Vector2, t: number): this;
+        dot(v: Vector2): number;
+        clone(): Vector2;
+        toArray(): [number, number];
+    }
+
+    class Vector3 {
+        constructor(x?: number, y?: number, z?: number);
+        x: number; y: number; z: number;
+        set(x: number, y: number, z: number): this;
+        setScalar(s: number): this;
+        copy(v: Vector3): this;
+        add(v: Vector3): this;
+        addScaledVector(v: Vector3, s: number): this;
+        sub(v: Vector3): this;
+        multiply(v: Vector3): this;
+        multiplyScalar(s: number): this;
+        divideScalar(s: number): this;
+        cross(v: Vector3): this;
+        crossVectors(a: Vector3, b: Vector3): this;
+        dot(v: Vector3): number;
+        length(): number;
+        lengthSq(): number;
+        normalize(): this;
+        lerp(v: Vector3, t: number): this;
+        negate(): this;
+        applyMatrix4(m: Matrix4): this;
+        applyQuaternion(q: Quaternion): this;
+        distanceTo(v: Vector3): number;
+        clone(): Vector3;
+        toArray(): [number, number, number];
+    }
+
+    class Vector4 {
+        constructor(x?: number, y?: number, z?: number, w?: number);
+        x: number; y: number; z: number; w: number;
+        set(x: number, y: number, z: number, w: number): this;
+        copy(v: Vector4): this;
+        clone(): Vector4;
+        toArray(): [number, number, number, number];
+    }
+
+    class Matrix3 {
+        elements: Float32Array;
+        identity(): this;
+        copy(m: Matrix3): this;
+        multiply(m: Matrix3): this;
+        transpose(): this;
+        invert(): this;
+        clone(): Matrix3;
+    }
+
+    class Matrix4 {
+        elements: Float32Array;
+        identity(): this;
+        copy(m: Matrix4): this;
+        multiply(m: Matrix4): this;
+        premultiply(m: Matrix4): this;
+        setPosition(v: Vector3): this;
+        makeTranslation(x: number, y: number, z: number): this;
+        makeRotationFromEuler(e: Euler): this;
+        makeRotationFromQuaternion(q: Quaternion): this;
+        makeScale(x: number, y: number, z: number): this;
+        compose(position: Vector3, quaternion: Quaternion, scale: Vector3): this;
+        decompose(position: Vector3, quaternion: Quaternion, scale: Vector3): this;
+        invert(): this;
+        transpose(): this;
+        lookAt(eye: Vector3, target: Vector3, up: Vector3): this;
+        clone(): Matrix4;
+    }
+
+    class Quaternion {
+        constructor(x?: number, y?: number, z?: number, w?: number);
+        x: number; y: number; z: number; w: number;
+        set(x: number, y: number, z: number, w: number): this;
+        copy(q: Quaternion): this;
+        setFromEuler(e: Euler): this;
+        setFromAxisAngle(axis: Vector3, angle: number): this;
+        multiply(q: Quaternion): this;
+        slerp(q: Quaternion, t: number): this;
+        normalize(): this;
+        length(): number;
+        clone(): Quaternion;
+    }
+
+    class Euler {
+        constructor(x?: number, y?: number, z?: number, order?: string);
+        x: number; y: number; z: number; order: string;
+        set(x: number, y: number, z: number, order?: string): this;
+        copy(e: Euler): this;
+        setFromQuaternion(q: Quaternion): this;
+        clone(): Euler;
+    }
+
+    class Color {
+        constructor(r?: number, g?: number, b?: number);
+        r: number; g: number; b: number;
+        set(r: number, g: number, b: number): this;
+        setHex(hex: number): this;
+        setHSL(h: number, s: number, l: number): this;
+        lerp(c: Color, t: number): this;
+        clone(): Color;
+        toArray(): [number, number, number];
+    }
+
+    class Box3 {
+        min: Vector3; max: Vector3;
+        constructor(min?: Vector3, max?: Vector3);
+        set(min: Vector3, max: Vector3): this;
+        setFromObject(obj: Object3D): this;
+        getCenter(target: Vector3): Vector3;
+        getSize(target: Vector3): Vector3;
+        intersectsBox(b: Box3): boolean;
+        containsPoint(p: Vector3): boolean;
+        expandByPoint(p: Vector3): this;
+        clone(): Box3;
+    }
+
+    class Sphere {
+        center: Vector3; radius: number;
+        constructor(center?: Vector3, radius?: number);
+        intersectsSphere(s: Sphere): boolean;
+        containsPoint(p: Vector3): boolean;
+        clone(): Sphere;
+    }
+
+    class Plane {
+        normal: Vector3; constant: number;
+        constructor(normal?: Vector3, constant?: number);
+        distanceToPoint(p: Vector3): number;
+        clone(): Plane;
+    }
+
+    class Ray {
+        origin: Vector3; direction: Vector3;
+        constructor(origin?: Vector3, direction?: Vector3);
+        intersectBox(box: Box3, target: Vector3): Vector3 | null;
+        intersectPlane(plane: Plane, target: Vector3): Vector3 | null;
+    }
+
+    class Frustum {
+        planes: Plane[];
+        setFromProjectionMatrix(m: Matrix4): this;
+        containsPoint(p: Vector3): boolean;
+        intersectsObject(obj: Object3D): boolean;
+    }
+
+    class MathTween { constructor(from: number, to: number, duration: number, ease?: EaseName, callback?: Function); }
+    class MatrixWasm { static multiply(a: Matrix4, b: Matrix4): Matrix4; }
+
+    const MathUtils: {
+        radians(degrees: number): number;
+        degrees(radians: number): number;
+        lerp(a: number, b: number, t: number): number;
+        clamp(val: number, min: number, max: number): number;
+        range(val: number, inMin: number, inMax: number, outMin: number, outMax: number): number;
+        smoothStep(min: number, max: number, val: number): number;
+        randFloat(low: number, high: number): number;
+        randInt(low: number, high: number): number;
+    };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // 3D OBJECTS
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Object3D {
+        position: Vector3;
+        rotation: Euler;
+        quaternion: Quaternion;
+        scale: Vector3;
+        matrix: Matrix4;
+        matrixWorld: Matrix4;
+        visible: boolean;
+        castShadow: boolean;
+        receiveShadow: boolean;
+        frustumCulled: boolean;
+        renderOrder: number;
+        name: string;
+        parent: Object3D | null;
+        children: Object3D[];
+        userData: Record<string, any>;
+        add(...children: Object3D[]): this;
+        remove(...children: Object3D[]): this;
+        traverse(callback: (obj: Object3D) => void): void;
+        updateMatrix(): void;
+        updateMatrixWorld(force?: boolean): void;
+        lookAt(v: Vector3): void;
+        clone(recursive?: boolean): this;
+        dispose(): void;
+    }
+
+    class Base3D extends Object3D {}
+    class Group extends Object3D {}
+    class Scene extends Object3D {
+        background: Color | Texture | null;
+        fog: any;
+    }
+
+    class Mesh extends Object3D {
+        constructor(geometry: Geometry, shader: Shader | any);
+        geometry: Geometry;
+        shader: Shader;
+        drawMode: number;
+    }
+
+    class Points extends Object3D {
+        constructor(geometry: Geometry, shader: Shader | any);
+        geometry: Geometry;
+        shader: Shader;
+        pointSize: number;
+    }
+
+    class Line3D extends Object3D {
+        constructor(geometry: Geometry, shader: Shader | any);
+        geometry: Geometry;
+        shader: Shader;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // GEOMETRY
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class GeometryAttribute {
+        constructor(data: Float32Array | number[], itemSize: number);
+        array: Float32Array;
+        itemSize: number;
+        count: number;
+    }
+
+    class Geometry {
+        attributes: Record<string, GeometryAttribute>;
+        index: GeometryAttribute | null;
+        addAttribute(name: string, attribute: GeometryAttribute): void;
+        setIndex(data: number[] | Uint16Array): void;
+        computeVertexNormals(): void;
+        computeBoundingBox(): void;
+        computeBoundingSphere(): void;
+        boundingBox: Box3;
+        boundingSphere: Sphere;
+        dispose(): void;
+    }
+
+    class PlaneGeometry extends Geometry {
+        constructor(width?: number, height?: number, widthSegs?: number, heightSegs?: number);
+    }
+    class BoxGeometry extends Geometry {
+        constructor(width?: number, height?: number, depth?: number, wSegs?: number, hSegs?: number, dSegs?: number);
+    }
+    class SphereGeometry extends Geometry {
+        constructor(radius?: number, widthSegs?: number, heightSegs?: number, phiStart?: number, phiLength?: number, thetaStart?: number, thetaLength?: number);
+    }
+    class CylinderGeometry extends Geometry {
+        constructor(radiusTop?: number, radiusBottom?: number, height?: number, radialSegs?: number, heightSegs?: number, openEnded?: boolean);
+    }
+    class IcosahedronGeometry extends Geometry {
+        constructor(radius?: number, detail?: number);
+    }
+
+    const GeomThread: {
+        loadGeometry(path: string): Promise<Geometry>;
+    };
+
+    const DracoThread: {
+        decode(buffer: ArrayBuffer): Promise<Geometry>;
+    };
+
+    class GLTFLoader {
+        constructor();
+        load(path: string, onLoad: (gltf: any) => void, onProgress?: Function, onError?: Function): void;
+        parse(data: ArrayBuffer, path: string, onLoad: Function, onError?: Function): void;
+    }
+
+    class SplineGen {
+        constructor(points: Vector3[], closed?: boolean);
+        getPoint(t: number): Vector3;
+        getPoints(divisions: number): Vector3[];
+        getTangent(t: number): Vector3;
+    }
+
+    class SplineLoader {
+        static load(path: string): Promise<SplineGen>;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // SHADERS & MATERIALS
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Shader {
+        constructor(name: string, options?: Record<string, any>);
+        uniforms: Record<string, { value: any }>;
+        name: string;
+        clone(): Shader;
+    }
+
+    const Shaders: {
+        [name: string]: string;
+        ready(): Promise<void>;
+        parse(code: string, file: string): void;
+    };
+
+    const ShaderChunk: { [name: string]: string };
+
+    class ShaderVariants {
+        constructor(shaderName: string, variants: Record<string, any>);
+        use(variantKey: string): Shader;
+    }
+
+    class PBRShader extends Shader {
+        constructor(options?: Record<string, any>);
+        roughness: number;
+        metalness: number;
+        envMapIntensity: number;
+    }
+
+    class LitMaterial extends Shader {
+        constructor(options?: Record<string, any>);
+        color: Color;
+        roughness: number;
+        metalness: number;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // TEXTURES & RENDER TARGETS
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Texture {
+        constructor(gl?: WebGLRenderingContext);
+        image: HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | null;
+        width: number;
+        height: number;
+        wrapS: number;
+        wrapT: number;
+        minFilter: number;
+        magFilter: number;
+        needsUpdate: boolean;
+        dispose(): void;
+    }
+
+    class RenderTarget {
+        constructor(width: number, height: number, options?: {
+            type?: string; format?: string; filter?: string;
+            depthBuffer?: boolean; stencilBuffer?: boolean; samples?: number;
+        });
+        width: number; height: number;
+        texture: Texture;
+        depthTexture: Texture | null;
+        resize(width: number, height: number): void;
+        dispose(): void;
+    }
+
+    class MultiRenderTarget {
+        constructor(width: number, height: number, count: number, options?: Record<string, any>);
+        textures: Texture[];
+        resize(width: number, height: number): void;
+        dispose(): void;
+    }
+
+    const Utils3D: {
+        getTexture(path: string): Texture;
+        getRepeatTexture(path: string): Texture;
+        loadCubemap(paths: string[]): Texture;
+        createDataTexture(data: Float32Array, width: number, height: number): Texture;
+    };
+
+    const RTPool: {
+        get(width: number, height: number, options?: Record<string, any>): RenderTarget;
+        release(rt: RenderTarget): void;
+    };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // CAMERAS
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Camera extends Object3D {
+        projectionMatrix: Matrix4;
+        projectionMatrixInverse: Matrix4;
+        matrixWorldInverse: Matrix4;
+        updateProjectionMatrix(): void;
+    }
+
+    class BaseCamera extends Camera {}
+    class CameraBase3D extends Camera {}
+
+    class PerspectiveCamera extends Camera {
+        constructor(fov?: number, aspect?: number, near?: number, far?: number);
+        fov: number; aspect: number; near: number; far: number;
+        updateProjectionMatrix(): void;
+    }
+
+    class OrthographicCamera extends Camera {
+        constructor(left?: number, right?: number, top?: number, bottom?: number, near?: number, far?: number);
+        left: number; right: number; top: number; bottom: number;
+        near: number; far: number;
+        updateProjectionMatrix(): void;
+    }
+
+    class GazeCamera extends PerspectiveCamera {
+        constructor(options?: { fov?: number; near?: number; far?: number });
+    }
+
+    const ScreenProjection: {
+        toScreen(pos: Vector3, camera: Camera): Vector2;
+        toWorld(screenPos: Vector2, z: number, camera: Camera): Vector3;
+    };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // WORLD & RENDERING
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const World: {
+        SCENE: Scene;
+        CAMERA: PerspectiveCamera;
+        RENDERER: Renderer;
+        NUKE: Nuke;
+        ELEMENT: HTMLCanvasElement;
+        instance(): typeof World;
+        init(): void;
+    };
+
+    const Render: {
+        start(callback: RenderCallback): void;
+        stop(callback: RenderCallback): void;
+        fps: number;
+    };
+
+    class Renderer {
+        constructor(canvas: HTMLCanvasElement, options?: Record<string, any>);
+        gl: WebGL2RenderingContext | WebGLRenderingContext;
+        setSize(width: number, height: number): void;
+        setPixelRatio(ratio: number): void;
+        render(scene: Scene, camera: Camera): void;
+        setClearColor(color: Color, alpha?: number): void;
+        dispose(): void;
+    }
+
+    const RenderManager: {
+        add(pass: any): void;
+        remove(pass: any): void;
+        setSize(w: number, h: number): void;
+    };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // LIGHTING
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Light extends Object3D {
+        constructor(color?: Color, intensity?: number);
+        color: Color;
+        intensity: number;
+    }
+
+    const Lighting: {
+        add(light: Light): void;
+        remove(light: Light): void;
+        setAmbient(color: Color, intensity?: number): void;
+    };
+
+    class ShadowLight extends Light {
+        constructor(options?: { color?: Color; intensity?: number; shadow?: Record<string, any> });
+        shadow: { mapSize: Vector2; camera: OrthographicCamera; bias: number };
+        castShadow: boolean;
+    }
+
+    class LightVolume {
+        constructor(options?: Record<string, any>);
+        position: Vector3;
+        color: Color;
+        radius: number;
+        intensity: number;
+    }
+
+    const AreaLightUtil: {
+        create(options: Record<string, any>): Light;
+    };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // POST-PROCESSING (NUKE)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Nuke {
+        constructor(renderer: Renderer, options?: Record<string, any>);
+        add(pass: NukePass): this;
+        remove(pass: NukePass): this;
+        setSize(width: number, height: number): void;
+        render(): void;
+    }
+
+    class NukePass {
+        constructor(shaderName: string, uniforms?: Record<string, { value: any }>);
+        enabled: boolean;
+        uniforms: Record<string, { value: any }>;
+        renderToScreen: boolean;
+    }
+
+    class BlitPass extends NukePass {
+        constructor(texture: Texture, uniforms?: Record<string, any>);
+    }
+
+    class FXAA extends NukePass {}
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // EFFECTS & FX
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const FX: { [name: string]: any };
+    class FXScene { constructor(options?: Record<string, any>); }
+    class FXLayer extends Object3D { constructor(options?: Record<string, any>); }
+    class FXStencil { constructor(options?: Record<string, any>); }
+    class FXScroll { constructor(options?: Record<string, any>); speed: number; }
+
+    class HydraBloom extends NukePass {
+        constructor(options?: { strength?: number; radius?: number; threshold?: number });
+        strength: number; radius: number; threshold: number;
+    }
+    class UnrealBloom extends NukePass {
+        constructor(options?: { strength?: number; radius?: number; threshold?: number });
+        strength: number; radius: number; threshold: number;
+    }
+    class VolumetricLight extends NukePass {
+        constructor(options?: { density?: number; decay?: number; weight?: number; samples?: number });
+    }
+    class HydraLensStreak extends NukePass {
+        constructor(options?: Record<string, any>);
+    }
+    class Mirror extends Object3D {
+        constructor(options?: Record<string, any>);
+        reflectionTexture: Texture;
+    }
+    class SnapshotFrame {
+        constructor(width?: number, height?: number);
+        capture(): Texture;
+        texture: Texture;
+    }
+    class SnapshotFramePingPong {
+        constructor(width?: number, height?: number);
+        ping: RenderTarget; pong: RenderTarget;
+        swap(): void;
+        current: RenderTarget;
+    }
+    class CubemapToEquirectangular {
+        constructor(renderer: Renderer, size?: number);
+        update(cubemap: Texture): Texture;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // FLUID SIMULATION
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Fluid {
+        constructor(simSize?: number, dyeSize?: number, rect?: { width: number; height: number });
+        splat(x: number, y: number, dx: number, dy: number, color?: Color): void;
+        update(dt?: number): void;
+        texture: Texture;
+        velocity: Texture;
+        dye: Texture;
+    }
+
+    class FluidFBO {
+        constructor(size: number, options?: Record<string, any>);
+        texture: Texture;
+        read: RenderTarget;
+        write: RenderTarget;
+        swap(): void;
+    }
+
+    class FluidScene {
+        constructor(options?: Record<string, any>);
+        fluid: Fluid;
+        mesh: Mesh;
+        update(dt?: number): void;
+    }
+
+    class FluidLayer extends Object3D {
+        constructor(options?: Record<string, any>);
+    }
+
+    class MouseFluid {
+        static instance(): MouseFluid;
+        applyTo(mesh: Mesh): void;
+        update(): void;
+        texture: Texture;
+        color: Color;
+        radius: number;
+        strength: number;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // PARTICLES — ANTIMATTER / PROTON
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Antimatter {
+        constructor(options?: {
+            count?: number; spawner?: AntimatterSpawn; attributes?: AntimatterAttribute[];
+            behavior?: string; blending?: string; size?: number;
+        });
+        mesh: Points;
+        count: number;
+        spawn(position?: Vector3, velocity?: Vector3): void;
+        reset(): void;
+    }
+
+    class AntimatterAttribute {
+        constructor(name: string, size: number, initialValue?: number[]);
+        name: string;
+        size: number;
+    }
+
+    class AntimatterFBO {
+        constructor(width: number, height: number, options?: Record<string, any>);
+        texture: Texture;
+        read: RenderTarget;
+        write: RenderTarget;
+        swap(): void;
+    }
+
+    class AntimatterPass {
+        constructor(shader: Shader, inputs: Texture[], output?: RenderTarget);
+        render(): void;
+    }
+
+    class AntimatterSpawn {
+        constructor(options?: { rate?: number; count?: number; burst?: boolean });
+    }
+
+    const AntimatterUtil: { [key: string]: any };
+
+    class Proton {
+        constructor(options?: Record<string, any>);
+        addEmitter(emitter: any): void;
+        removeEmitter(emitter: any): void;
+        update(dt?: number): void;
+    }
+
+    const ProtonPresets: { [name: string]: (options?: any) => Proton };
+    class ProtonTubes {
+        constructor(options?: Record<string, any>);
+        mesh: Mesh;
+        update(dt?: number): void;
+    }
+
+    class SplineParticles {
+        constructor(spline: SplineGen, options?: Record<string, any>);
+        mesh: Points;
+        update(dt?: number): void;
+        count: number;
+    }
+
+    class SplineParticlesStatic {
+        constructor(spline: SplineGen, count: number, options?: Record<string, any>);
+        mesh: Points;
+    }
+
+    class ParticleDistributor {
+        constructor(options?: Record<string, any>);
+        distribute(count: number, area: Box3): Vector3[];
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // INSTANCING & BATCHING
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class MeshBatch {
+        constructor(geometry?: Geometry, shader?: Shader, maxCount?: number);
+        mesh: Mesh;
+        count: number;
+        add(matrix: Matrix4, color?: Color): number;
+        remove(id: number): void;
+        setMatrixAt(id: number, matrix: Matrix4): void;
+        update(): void;
+    }
+
+    class MeshMerge {
+        constructor(meshes: Mesh[], options?: Record<string, any>);
+        mesh: Mesh;
+    }
+
+    class InstanceMesh {
+        constructor(geometry: Geometry, shader: Shader, count: number);
+        mesh: Mesh;
+        setMatrixAt(index: number, matrix: Matrix4): void;
+        setColorAt(index: number, color: Color): void;
+        instanceCount: number;
+        update(): void;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // TEXT (WebGL)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Text3D extends Mesh {
+        constructor(text: string, options?: { font?: string; size?: number; color?: Color; align?: string });
+        text: string;
+        font: string;
+        size: number;
+        lineHeight: number;
+        setText(text: string): void;
+        measure(): { width: number; height: number };
+    }
+
+    class GLText extends Object3D {
+        constructor(options?: { font?: string; size?: number; align?: string });
+        setText(text: string): void;
+        width: number;
+        height: number;
+    }
+
+    class GLTextGeometry extends Geometry {
+        constructor(text: string, font: any, options?: Record<string, any>);
+        setText(text: string): void;
+    }
+
+    const GLScreenProjection: {
+        project(pos: Vector3, camera: Camera, size: { width: number; height: number }): Vector2;
+    };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // INTERACTION
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const Mouse: {
+        x: number; y: number;
+        nX: number; nY: number;
+        vX: number; vY: number;
+        down: boolean;
+        element: HTMLElement;
+        on(event: string, callback: Function, scope?: any): void;
+    };
+
+    const Interaction: {
+        on(event: string, callback: Function, scope?: any): void;
+        off(event: string, callback: Function, scope?: any): void;
+    };
+
+    class Interaction3D {
+        constructor(camera?: Camera, scene?: Scene);
+        on(event: 'over' | 'out' | 'click' | 'down' | 'up', callback: (obj: Object3D) => void): void;
+        add(obj: Object3D): void;
+        remove(obj: Object3D): void;
+        update(): void;
+    }
+
+    class Raycaster {
+        constructor(origin?: Vector3, direction?: Vector3);
+        ray: Ray;
+        near: number;
+        far: number;
+        set(origin: Vector3, direction: Vector3): void;
+        setFromCamera(coords: Vector2, camera: Camera): void;
+        intersectObject(obj: Object3D, recursive?: boolean): Array<{ point: Vector3; distance: number; object: Object3D }>;
+        intersectObjects(objs: Object3D[], recursive?: boolean): Array<{ point: Vector3; distance: number; object: Object3D }>;
+    }
+
+    const Scroll: {
+        y: number; x: number;
+        delta: number;
+        on(event: string, callback: Function): void;
+    };
+
+    class ScrollController {
+        constructor(element: HTMLElement, options?: Record<string, any>);
+        scrollTo(y: number, duration?: number): void;
+        on(event: string, callback: Function): void;
+    }
+
+    const Keyboard: {
+        on(event: string, callback: (key: string, code: number) => void): void;
+        off(event: string, callback: Function): void;
+        isDown(key: string | number): boolean;
+    };
+
+    class VelocityTracker {
+        constructor(options?: { decay?: number });
+        update(value: number): void;
+        velocity: number;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // ANIMATION & TWEENING
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const TweenManager: {
+        to(obj: any, props: Record<string, any>, duration: number, ease?: EaseName, delay?: number): any;
+        from(obj: any, props: Record<string, any>, duration: number, ease?: EaseName, delay?: number): any;
+        kill(obj: any): void;
+        killAll(): void;
+    };
+
+    class TweenTimeline {
+        constructor(options?: { loop?: boolean; autoStart?: boolean });
+        add(tween: any, time: number): this;
+        play(): this;
+        pause(): this;
+        stop(): this;
+        seek(time: number): this;
+        duration: number;
+        time: number;
+    }
+
+    class FrameTween {
+        constructor(obj: any, props: Record<string, any>, frames: number, ease?: EaseName);
+        play(): this;
+        stop(): this;
+        frame: number;
+    }
+
+    class CSSTransition {
+        constructor(element: HTMLElement, options?: { duration?: number; ease?: string; delay?: number });
+        to(props: Record<string, any>): Promise<void>;
+        cancel(): void;
+    }
+
+    class HierarchyAnimation {
+        constructor(root: Object3D, options?: Record<string, any>);
+        play(name: string): this;
+        stop(): this;
+        mixer: any;
+    }
+
+    class LayerAnimation {
+        constructor(options?: Record<string, any>);
+        addLayer(name: string, tween: any): this;
+        play(name: string): this;
+        crossFadeTo(name: string, duration?: number): this;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // AUDIO
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Audio3D {
+        constructor(source: string | AudioBuffer, options?: { volume?: number; loop?: boolean; spatial?: boolean });
+        play(): void;
+        pause(): void;
+        stop(): void;
+        volume: number;
+        loop: boolean;
+        position: Vector3;
+    }
+
+    class Audio3DLayer {
+        constructor(options?: Record<string, any>);
+        add(audio: Audio3D): void;
+        volume: number;
+    }
+
+    class Audio3DResonance {
+        constructor(source: string, options?: Record<string, any>);
+        play(): void;
+        stop(): void;
+        position: Vector3;
+    }
+
+    class Audio3DWA {
+        constructor(options?: Record<string, any>);
+        context: AudioContext;
+    }
+
+    class Audio3DWABuffer {
+        constructor(context: AudioContext, path: string);
+        play(options?: { volume?: number; loop?: boolean }): AudioBufferSourceNode;
+    }
+
+    class Audio3DWAStream {
+        constructor(context: AudioContext, path: string);
+        play(): void;
+        pause(): void;
+        volume: number;
+    }
+
+    const GlobalAudio3D: {
+        context: AudioContext;
+        masterVolume: number;
+        setVolume(v: number): void;
+        mute(): void;
+        unmute(): void;
+    };
+
+    class SFXController {
+        constructor(sounds: Record<string, string>, options?: Record<string, any>);
+        play(name: string, options?: { volume?: number; pitch?: number }): void;
+        stop(name: string): void;
+    }
+
+    const WebAudio: {
+        context: AudioContext;
+        createGain(): GainNode;
+        createAnalyser(): AnalyserNode;
+        getFrequencyData(analyser: AnalyserNode): Uint8Array;
+    };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // VIDEO
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class Video {
+        constructor(src: string, options?: { autoplay?: boolean; loop?: boolean; muted?: boolean; playsInline?: boolean });
+        element: HTMLVideoElement;
+        play(): Promise<void>;
+        pause(): void;
+        stop(): void;
+        currentTime: number;
+        duration: number;
+        volume: number;
+        loop: boolean;
+    }
+
+    class VideoTexture extends Texture {
+        constructor(video: Video | HTMLVideoElement);
+        video: HTMLVideoElement;
+        update(): void;
+    }
+
+    class VideoTextureColorParser {
+        constructor(video: VideoTexture, options?: Record<string, any>);
+        dominantColor: Color;
+        update(): void;
+    }
+
+    class Webcam {
+        constructor(options?: { facingMode?: string; width?: number; height?: number });
+        element: HTMLVideoElement;
+        texture: VideoTexture;
+        start(): Promise<void>;
+        stop(): void;
+        width: number;
+        height: number;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // UI — GLUI (WebGL-rendered UI elements)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const GLUI: {
+        init(): void;
+        Stage: any; Scene: any;
+    };
+
+    class GLUIElement extends Object3D {
+        constructor(options?: Record<string, any>);
+        width: number; height: number;
+        alpha: number;
+        setSize(w: number, h: number): void;
+        show(): void;
+        hide(): void;
+    }
+
+    class GLUIBatch extends Object3D {
+        constructor(options?: Record<string, any>);
+        add(element: GLUIElement): void;
+        remove(element: GLUIElement): void;
+    }
+
+    class GLUIBatchText extends GLUIElement {
+        constructor(options?: { text?: string; font?: string; size?: number; color?: Color });
+        setText(text: string): void;
+        text: string;
+    }
+
+    class GLUIStage extends Object3D {
+        constructor(options?: Record<string, any>);
+        width: number; height: number;
+    }
+
+    class GLUIStage3D extends GLUIStage {
+        constructor(options?: Record<string, any>);
+        camera: PerspectiveCamera;
+    }
+
+    class GLUITexture extends GLUIElement {
+        constructor(texture: Texture, options?: Record<string, any>);
+        texture: Texture;
+        setTexture(t: Texture): void;
+    }
+
+    class GLUICornerPin extends GLUIElement {
+        constructor(options?: Record<string, any>);
+        setCorners(tl: Vector2, tr: Vector2, br: Vector2, bl: Vector2): void;
+    }
+
+    class GLUIStageInteraction2D {
+        constructor(stage: GLUIStage, options?: Record<string, any>);
+        on(event: string, callback: Function): void;
+    }
+
+    class GLUIStageInteraction3D {
+        constructor(stage: GLUIStage3D, options?: Record<string, any>);
+        on(event: string, callback: Function): void;
+    }
+
+    class GLA11y {
+        constructor(element: HTMLElement, options?: Record<string, any>);
+        setRole(role: string): void;
+        setLabel(label: string): void;
+    }
+
+    class UI3D extends Object3D {
+        constructor(options?: Record<string, any>);
+        show(): void;
+        hide(): void;
+    }
+
+    class UI3DLayer extends Object3D {
+        constructor(options?: Record<string, any>);
+        add(element: UI3D): void;
+        remove(element: UI3D): void;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // DOM
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const Stage: {
+        width: number; height: number;
+        pixelRatio: number;
+        add(element: HTMLElement): void;
+        remove(element: HTMLElement): void;
+        on(event: string, callback: Function): void;
+    };
+
+    const HydraCSS: {
+        style(element: HTMLElement, styles: Record<string, any>): void;
+        set(element: HTMLElement, styles: Record<string, any>): void;
+    };
+
+    const $: (selector: string, parent?: HTMLElement) => HTMLElement | null;
+
+    class PushState {
+        constructor();
+        static push(path: string, data?: any): void;
+        static replace(path: string, data?: any): void;
+        static on(event: 'change', callback: (path: string, data: any) => void): void;
+    }
+
+    class Router {
+        constructor(routes: Record<string, Function>);
+        start(): void;
+        navigate(path: string): void;
+    }
+
+    class DOMTemplate {
+        constructor(templateId: string);
+        render(data: Record<string, any>): HTMLElement;
+        clone(): HTMLElement;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // SCENE LAYOUT / FRAGMENTS
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const SceneLayout: {
+        add(fragment: Frag3D): void;
+        remove(fragment: Frag3D): void;
+        update(dt?: number): void;
+    };
+
+    class Frag3D extends Object3D {
+        constructor(options?: Record<string, any>);
+        init(): void;
+        resize(width: number, height: number): void;
+        update(dt?: number): void;
+        show(duration?: number): Promise<void>;
+        hide(duration?: number): Promise<void>;
+    }
+
+    class FragFXScene extends Frag3D {
+        constructor(options?: Record<string, any>);
+        nuke: Nuke;
+    }
+
+    class FXSceneCompositor {
+        constructor(options?: Record<string, any>);
+        add(scene: Frag3D, pass: NukePass): void;
+        render(): void;
+    }
+
+    class FragCompositor {
+        constructor(options?: Record<string, any>);
+        compose(fragments: Frag3D[]): void;
+    }
+
+    const Initializer3D: {
+        createWorld(options?: Record<string, any>): void;
+    };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // LOADING & ASSETS
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const Assets: {
+        list(): any;
+        getPath(path: string): string;
+        loadImage(path: string): HTMLImageElement;
+        loadJSON(path: string): Promise<any>;
+        loadText(path: string): Promise<string>;
+        loadArrayBuffer(path: string): Promise<ArrayBuffer>;
+    };
+
+    const AssetLoader: {
+        loadAssets(list: any): Promise<void>;
+        on(event: 'progress' | 'complete', callback: Function): void;
+    };
+
+    class ImageDecoder {
+        constructor(options?: Record<string, any>);
+        decode(blob: Blob): Promise<ImageBitmap>;
+    }
+
+    class Ktx2Transcoder {
+        constructor();
+        transcode(buffer: ArrayBuffer): Promise<Texture>;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // MULTIPLAYER / NETWORKING
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const Multiplayer: {
+        connect(url: string, options?: Record<string, any>): SocketConnection;
+        on(event: string, callback: Function): void;
+        send(event: string, data?: any): void;
+    };
+
+    const GameCenter: {
+        connect(url: string): void;
+        on(event: string, callback: Function): void;
+    };
+
+    class PlayerModel extends Model {
+        constructor(data?: Record<string, any>);
+        id: string;
+        position: Vector3;
+    }
+
+    class Player extends Object3D {
+        constructor(model: PlayerModel, options?: Record<string, any>);
+        model: PlayerModel;
+        view: PlayerView;
+    }
+
+    class PlayerView extends Object3D {
+        constructor(model: PlayerModel, options?: Record<string, any>);
+        model: PlayerModel;
+    }
+
+    class PhysicalSync {
+        constructor(object: Object3D, options?: Record<string, any>);
+        update(): void;
+    }
+
+    class PhysicalLink {
+        constructor(a: Object3D, b: Object3D, options?: Record<string, any>);
+        update(): void;
+        length: number;
+    }
+
+    class SynchronizedObjects {
+        constructor(options?: Record<string, any>);
+        add(object: Object3D, id: string): void;
+        update(dt?: number): void;
+    }
+
+    class SocketConnection {
+        constructor(url: string, options?: { reconnect?: boolean; protocols?: string[] });
+        on(event: string, callback: Function): void;
+        send(event: string, data?: any): void;
+        close(): void;
+        connected: boolean;
+    }
+
+    class QRCode {
+        constructor(text: string, options?: { size?: number; errorLevel?: string });
+        render(canvas: HTMLCanvasElement): void;
+        toDataURL(): string;
+    }
+
+    class QRGen {
+        constructor(options?: Record<string, any>);
+        generate(text: string): string;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // VR / AR / XR
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const XRConfig: {
+        requiredFeatures: string[];
+        optionalFeatures: string[];
+        frameOfReference: string;
+    };
+
+    const XRDeviceManager: {
+        isSupported(mode: 'immersive-vr' | 'immersive-ar' | 'inline'): Promise<boolean>;
+        requestSession(mode: string, options?: any): Promise<XRSession>;
+        on(event: string, callback: Function): void;
+    };
+
+    class VRInput extends Object3D {
+        constructor(session: XRSession, options?: Record<string, any>);
+        left: VRInputController;
+        right: VRInputController;
+        update(frame: XRFrame): void;
+    }
+
+    class VRInputController extends Object3D {
+        trigger: boolean;
+        grip: boolean;
+        thumbstick: Vector2;
+        on(event: 'select' | 'selectstart' | 'selectend' | 'squeeze', callback: Function): void;
+        hapticPulse(duration?: number, intensity?: number): void;
+    }
+
+    class VRInputHand extends Object3D {
+        constructor(options?: Record<string, any>);
+        joints: Object3D[];
+        update(frame: XRFrame): void;
+    }
+
+    class VRCamera extends PerspectiveCamera {
+        constructor(options?: Record<string, any>);
+        setFromXRFrame(frame: XRFrame, refSpace: XRReferenceSpace): void;
+    }
+
+    class VRRenderer {
+        constructor(renderer: Renderer, session: XRSession);
+        render(scene: Scene, camera: VRCamera, frame: XRFrame): void;
+        setSession(session: XRSession): void;
+    }
+
+    class ARCamera extends PerspectiveCamera {
+        constructor(options?: Record<string, any>);
+        setFromXRFrame(frame: XRFrame, refSpace: XRReferenceSpace): void;
+    }
+
+    class ARRenderer extends VRRenderer {
+        constructor(renderer: Renderer, session: XRSession);
+    }
+
+    const ARUtils: {
+        isSupported(): Promise<boolean>;
+        createSession(options?: Record<string, any>): Promise<XRSession>;
+        placeAnchor(frame: XRFrame, position: Vector3): XRAnchor | null;
+    };
+
+    class UserInput {
+        constructor(options?: Record<string, any>);
+        on(event: string, callback: Function): void;
+        pointer: Vector2;
+        down: boolean;
+    }
+
+    class UserInputMouseTouch extends UserInput {
+        constructor(element?: HTMLElement, options?: Record<string, any>);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // AI
+    // ─────────────────────────────────────────────────────────────────────────
+
+    class InteractAI {
+        constructor(options?: Record<string, any>);
+        send(message: string): Promise<string>;
+        on(event: 'message' | 'error', callback: Function): void;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // THREADING
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const Thread: {
+        create(workerFunction: Function): Worker;
+        post(worker: Worker, message: any, transfer?: Transferable[]): void;
+        terminate(worker: Worker): void;
+    };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // GPU / PERFORMANCE
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const GPU: {
+        vendor: string;
+        renderer: string;
+        tier: number;
+        isMobile: boolean;
+        webgl2: boolean;
+        extensions: string[];
+    };
+
+    const Performance: {
+        fps: number;
+        ms: number;
+        memory: { used: number; total: number } | null;
+        begin(): void;
+        end(): void;
+        on(event: 'low-fps', callback: (fps: number) => void): void;
+    };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // DEBUG / DEV
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const Dev: {
+        enabled: boolean;
+        log(...args: any[]): void;
+        warn(...args: any[]): void;
+        error(...args: any[]): void;
+        grid(scene: Scene, size?: number, divisions?: number): Object3D;
+        axes(size?: number): Object3D;
+        stats(): HTMLElement;
+    };
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // DEVICE DETECTION
+    // ─────────────────────────────────────────────────────────────────────────
+
+    const Device: {
+        mobile: false | { phone: boolean; tablet: boolean; pwa: boolean; native: boolean };
+        system: { os: string; browser: string; browserVersion: number; version: number; webworker: boolean; retina: boolean };
+        graphics: { webgl: any; gpu: string };
+        pixelRatio: number;
+        agent: string;
+        touchCapable: boolean;
+    };
+}
+
+export = Orbix;
+export as namespace Orbix;