@particle-academy/fancy-3d-babylon 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+import { Scene, Mesh, Vector3, DynamicTexture } from '@babylonjs/core';
+import { WidgetSpec, SceneNode, WidgetAdapter, Scene as Scene$1 } from '@particle-academy/fancy-3d';
+
+declare const TEX_SCALE = 2;
+declare function paintWidget(ctx: CanvasRenderingContext2D, spec: WidgetSpec, w: number, h: number, selected: boolean): void;
+
+/**
+ * 3D shape primitives for `@particle-academy/fancy-3d`.
+ *
+ * A primitive is a Babylon mesh that can host UI content on its surface —
+ * either a flat color, a freeform 2D paint callback, or a `WidgetSpec`
+ * rendered through the same painters as the Babylon adapter.
+ *
+ * Every primitive returns a `Mesh`, ready to position in your scene.
+ */
+
+type PaintFn = (ctx: CanvasRenderingContext2D, width: number, height: number) => void;
+type SurfaceContent = {
+    type: "color";
+    color: string;
+} | {
+    type: "paint";
+    paint: PaintFn;
+    pixelWidth?: number;
+    pixelHeight?: number;
+    transparent?: boolean;
+} | {
+    type: "widget";
+    widget: WidgetSpec;
+    pixelWidth?: number;
+    pixelHeight?: number;
+    selected?: boolean;
+};
+interface PanelOpts {
+    scene: Scene;
+    name?: string;
+    width: number;
+    height: number;
+    surface: SurfaceContent;
+    /** Babylon sideOrientation. Use `Mesh.DOUBLESIDE` for panels you want visible
+     *  from both directions (e.g. self-luminous screens). Default is FRONTSIDE. */
+    sideOrientation?: number;
+}
+declare function createPanel(opts: PanelOpts): Mesh;
+interface BillboardOpts extends PanelOpts {
+    /** When true, mesh.billboardMode = ALL — always faces the camera. */
+    faceCamera?: boolean;
+}
+declare function createBillboard(opts: BillboardOpts): Mesh;
+interface BuildingOpts {
+    scene: Scene;
+    name?: string;
+    width: number;
+    height: number;
+    depth: number;
+    /** Surface applied to all 6 faces (cheap path). */
+    surface?: SurfaceContent;
+    /** Per-face surfaces; missing faces use `surface` or a default grey. */
+    faces?: Partial<Record<BoxFace, SurfaceContent>>;
+}
+/** Babylon box face indices (CreateBox): 0=front (-Z), 1=back (+Z), 2=right (+X), 3=left (-X), 4=top (+Y), 5=bottom (-Y). */
+type BoxFace = "front" | "back" | "right" | "left" | "top" | "bottom";
+declare function createBuilding(opts: BuildingOpts): Mesh;
+interface PillarOpts {
+    scene: Scene;
+    name?: string;
+    thickness: number;
+    height: number;
+    surface?: SurfaceContent;
+}
+declare function createPillar(opts: PillarOpts): Mesh;
+interface CylinderOpts {
+    scene: Scene;
+    name?: string;
+    radius: number;
+    height: number;
+    surface: SurfaceContent;
+    tessellation?: number;
+}
+declare function createCylinder(opts: CylinderOpts): Mesh;
+interface CurvedPanelOpts {
+    scene: Scene;
+    name?: string;
+    width: number;
+    height: number;
+    arc: number;
+    surface: SurfaceContent;
+    tessellation?: number;
+}
+declare function createCurvedPanel(opts: CurvedPanelOpts): Mesh;
+interface SphereOpts {
+    scene: Scene;
+    name?: string;
+    diameter: number;
+    surface: SurfaceContent;
+    segments?: number;
+}
+declare function createSphere(opts: SphereOpts): Mesh;
+interface DiscOpts {
+    scene: Scene;
+    name?: string;
+    radius: number;
+    surface: SurfaceContent;
+    tessellation?: number;
+}
+declare function createDisc(opts: DiscOpts): Mesh;
+interface Card3DOpts {
+    scene: Scene;
+    name?: string;
+    width: number;
+    height: number;
+    /** Extrusion depth. Defaults to a thin 0.06 — like real foam-board signage. */
+    depth?: number;
+    /** Surface for the front face (the visible UI). */
+    front: SurfaceContent;
+    /** Surface for the side and back faces. Defaults to a dark color. */
+    edge?: SurfaceContent;
+}
+declare function createCard3D(opts: Card3DOpts): Mesh;
+interface SignOpts {
+    scene: Scene;
+    name?: string;
+    /** Panel dimensions. */
+    width: number;
+    height: number;
+    /** How tall the post is (from ground to bottom of panel). */
+    postHeight?: number;
+    /** Post thickness (square cross-section). */
+    postThickness?: number;
+    /** Panel surface (color, paint, or widget). */
+    surface: SurfaceContent;
+    /** Post color. */
+    postColor?: string;
+}
+interface SignResult {
+    /** Group containing the panel + post, parented at ground level. */
+    root: Mesh;
+    panel: Mesh;
+    post: Mesh;
+}
+declare function createSign(opts: SignOpts): SignResult;
+interface MonitorOpts {
+    scene: Scene;
+    name?: string;
+    width: number;
+    height: number;
+    /** Front-to-back depth of the display chassis. Defaults to 0.18. */
+    depth?: number;
+    /** Bezel color. Defaults to near-black. */
+    bezel?: string;
+    /** Screen surface — color, paint, or widget. */
+    screen: SurfaceContent;
+    /** Optional kickstand height — when set, the monitor sits on a base. */
+    standHeight?: number;
+}
+interface MonitorResult {
+    root: Mesh;
+    body: Mesh;
+    screen: Mesh;
+    stand?: Mesh;
+}
+declare function createMonitor(opts: MonitorOpts): MonitorResult;
+interface DecalOpts {
+    scene: Scene;
+    name?: string;
+    /** The mesh to project the decal onto. */
+    target: Mesh;
+    /** World-space position the projector sits at. */
+    position: Vector3;
+    /** Direction the projector points. Defaults to -Z. */
+    normal?: Vector3;
+    /** Size of the decal box. */
+    size: {
+        width: number;
+        height: number;
+        depth?: number;
+    };
+    /** Rotation around the projection axis (radians). */
+    angle?: number;
+    /** Surface to project. */
+    surface: SurfaceContent;
+}
+/**
+ * Projects a SurfaceContent onto `target`'s geometry. The decal conforms to
+ * the underlying surface — useful for signage on curved walls, logos on
+ * irregular terrain, graffiti on cylindrical surfaces, etc.
+ */
+declare function createDecal(opts: DecalOpts): Mesh;
+declare function createWidgetTexture(scene: Scene, name: string, widget: WidgetSpec, pixelWidth: number, pixelHeight: number, selected?: boolean): DynamicTexture;
+
+/**
+ * Layout helpers — map 2D scene-node positions onto 3D arrangements.
+ *
+ * All layout functions take the same shape: a SceneNode, the Mesh that was
+ * built for it, the scene's bounds, and layout-specific options. They mutate
+ * `mesh.position` (and sometimes `mesh.rotation`) in place.
+ *
+ * Pair with `sceneBounds(scene)` from `./babylon` to compute the bounds.
+ */
+
+interface Bounds {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+interface GridLayoutOpts {
+    /** Pixel-to-world unit ratio. Defaults to 1/120. */
+    scale?: number;
+    /** World-space center of the grid. Defaults to (0, 0, 0). */
+    origin?: Vector3;
+}
+/**
+ * Direct 2D-to-3D mapping. DOM (x, y) becomes world (x, -y, 0) — the most
+ * literal layout. Useful when you want the scene to look identical to its
+ * DOM rendering, just rendered as floating panels.
+ */
+declare function placeOnGrid(node: SceneNode, mesh: Mesh, bounds: Bounds, opts?: GridLayoutOpts): void;
+interface WallLayoutOpts {
+    /** Distance from origin along the wall's normal. Defaults to 0. */
+    z?: number;
+    /** Spread along world X. Defaults to 10 world units. */
+    spreadX?: number;
+    /** Spread along world Y. Defaults to 4 world units. */
+    spreadY?: number;
+    /** Wall vertical center. Defaults to 1.5 world units. */
+    centerY?: number;
+}
+/**
+ * Hangs panels on a flat virtual wall, centered on the world origin and
+ * facing +Z.
+ */
+declare function placeOnWall(node: SceneNode, mesh: Mesh, bounds: Bounds, opts?: WallLayoutOpts): void;
+interface ArcLayoutOpts {
+    /** Cylinder radius. Defaults to 6. */
+    radius?: number;
+    /** Total arc spanned in radians. Defaults to π * 0.9 (~160°). */
+    arc?: number;
+    /** Vertical extent. Defaults to 6. */
+    height?: number;
+    /** Base Y of the arc. Defaults to 0. */
+    baseY?: number;
+}
+/**
+ * Wraps DOM x onto an angle around a vertical axis; DOM y becomes height.
+ * Same math as `placeOnCylinder` from `./babylon`, exposed here with a
+ * clearer name and consistent options shape.
+ */
+declare function placeOnArc(node: SceneNode, mesh: Mesh, bounds: Bounds, opts?: ArcLayoutOpts): void;
+interface PathLayoutOpts {
+    /** Waypoints along the path. */
+    waypoints: Vector3[];
+    /** Should each mesh face the next waypoint? Defaults to true. */
+    faceForward?: boolean;
+    /** Distribute by node index (0..n-1) instead of normalized x. Defaults to false. */
+    byIndex?: boolean;
+    /** Total node count when using `byIndex`. Defaults to inferred from bounds. */
+    nodeCount?: number;
+}
+/**
+ * Distributes nodes along a polyline. Each mesh sits on the path; if
+ * `faceForward` is true, each mesh's +Y rotation aligns with the path
+ * tangent.
+ */
+declare function placeOnPath(node: SceneNode, mesh: Mesh, bounds: Bounds, opts: PathLayoutOpts): void;
+interface SphereLayoutOpts {
+    /** Sphere radius. Defaults to 5. */
+    radius?: number;
+    /** World-space center. Defaults to (0, 0, 0). */
+    center?: Vector3;
+    /** Latitude span in radians (0..π). Defaults to π * 0.7 (avoids poles). */
+    latSpan?: number;
+    /** Longitude span in radians (0..2π). Defaults to 2π. */
+    lonSpan?: number;
+}
+/**
+ * DOM x → longitude, DOM y → latitude. Useful for "globe of widgets" or
+ * any kind of spherical immersive layout.
+ */
+declare function placeOnSphere(node: SceneNode, mesh: Mesh, bounds: Bounds, opts?: SphereLayoutOpts): void;
+
+/**
+ * BabylonJS adapter for `@particle-academy/fancy-3d`.
+ *
+ * Each widget kind paints onto a 2D HTMLCanvasElement that is uploaded to a
+ * Babylon `DynamicTexture`, which is then applied to a plane mesh sized to
+ * the widget's pixel rect. Edges become line meshes between node centers.
+ *
+ * `@babylonjs/core` is an OPTIONAL peer dependency — only consumers building
+ * 3D scenes need to install it.
+ */
+
+interface BabylonAdapterDeps {
+    scene3D: Scene;
+    /** Pixel size for the widget (the scene node's `size` field). */
+    sizeFor(spec: WidgetSpec): {
+        w: number;
+        h: number;
+    };
+}
+declare function createBabylonAdapter(deps: BabylonAdapterDeps): WidgetAdapter<Mesh>;
+/**
+ * "3D Desktop" layout — wraps the scene's 2D positions onto a partial
+ * cylinder facing the camera. DOM `x` becomes angle around the cylinder,
+ * DOM `y` becomes height.
+ */
+declare function placeOnCylinder(node: SceneNode, mesh: Mesh, bounds: {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}, opts?: {
+    radius?: number;
+    arc?: number;
+}): void;
+declare function sceneBounds(scene: Scene$1): {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+};
+
+export { type ArcLayoutOpts, type BabylonAdapterDeps, type BillboardOpts, type BoxFace, type BuildingOpts, type Card3DOpts, type CurvedPanelOpts, type CylinderOpts, type DecalOpts, type DiscOpts, type GridLayoutOpts, type MonitorOpts, type MonitorResult, type PaintFn, type PanelOpts, type PathLayoutOpts, type PillarOpts, type SignOpts, type SignResult, type SphereLayoutOpts, type SphereOpts, type SurfaceContent, TEX_SCALE, type WallLayoutOpts, createBabylonAdapter, createBillboard, createBuilding, createCard3D, createCurvedPanel, createCylinder, createDecal, createDisc, createMonitor, createPanel, createPillar, createSign, createSphere, createWidgetTexture, paintWidget, placeOnArc, placeOnCylinder, placeOnGrid, placeOnPath, placeOnSphere, placeOnWall, sceneBounds };