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

package/dist/index.d.ts

@@ -0,0 +1,283 @@
+import * as THREE from 'three';
+import { WidgetSpec, SceneNode, WidgetAdapter, Scene } 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` — three.js edition.
+ *
+ * A primitive is a three.js 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 three.js adapter.
+ *
+ * Every primitive returns a three.js `Mesh` (or a `Group` for composites),
+ * ready to position in your scene. Pass `scene` to also add it for you.
+ *
+ * Mirrors `@particle-academy/fancy-3d-babylon`'s primitive API: same function
+ * names, same option shapes. Differences from the Babylon adapter are minor and
+ * idiomatic to three (e.g. `doubleSided?: boolean` instead of a `sideOrientation`
+ * enum; `scene` is optional since three meshes exist independent of a 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?: THREE.Object3D;
+    name?: string;
+    width: number;
+    height: number;
+    surface: SurfaceContent;
+    /** Render both faces (e.g. for self-luminous screens). */
+    doubleSided?: boolean;
+}
+declare function createPanel(opts: PanelOpts): THREE.Mesh;
+interface BillboardOpts extends PanelOpts {
+    /** When true, the mesh is flagged to always face the camera. `<Stage>` honors
+     *  the flag each frame; outside a Stage, call `mesh.lookAt(camera.position)`. */
+    faceCamera?: boolean;
+}
+declare function createBillboard(opts: BillboardOpts): THREE.Mesh;
+interface BuildingOpts {
+    scene?: THREE.Object3D;
+    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>>;
+}
+type BoxFace = "front" | "back" | "right" | "left" | "top" | "bottom";
+declare function createBuilding(opts: BuildingOpts): THREE.Mesh;
+interface PillarOpts {
+    scene?: THREE.Object3D;
+    name?: string;
+    thickness: number;
+    height: number;
+    surface?: SurfaceContent;
+}
+declare function createPillar(opts: PillarOpts): THREE.Mesh;
+interface CylinderOpts {
+    scene?: THREE.Object3D;
+    name?: string;
+    radius: number;
+    height: number;
+    surface: SurfaceContent;
+    tessellation?: number;
+}
+declare function createCylinder(opts: CylinderOpts): THREE.Mesh;
+interface CurvedPanelOpts {
+    scene?: THREE.Object3D;
+    name?: string;
+    width: number;
+    height: number;
+    arc: number;
+    surface: SurfaceContent;
+    tessellation?: number;
+}
+declare function createCurvedPanel(opts: CurvedPanelOpts): THREE.Mesh;
+interface SphereOpts {
+    scene?: THREE.Object3D;
+    name?: string;
+    diameter: number;
+    surface: SurfaceContent;
+    segments?: number;
+}
+declare function createSphere(opts: SphereOpts): THREE.Mesh;
+interface DiscOpts {
+    scene?: THREE.Object3D;
+    name?: string;
+    radius: number;
+    surface: SurfaceContent;
+    tessellation?: number;
+}
+declare function createDisc(opts: DiscOpts): THREE.Mesh;
+interface Card3DOpts {
+    scene?: THREE.Object3D;
+    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): THREE.Mesh;
+interface SignOpts {
+    scene?: THREE.Object3D;
+    name?: string;
+    width: number;
+    height: number;
+    postHeight?: number;
+    postThickness?: number;
+    surface: SurfaceContent;
+    postColor?: string;
+}
+interface SignResult {
+    root: THREE.Group;
+    panel: THREE.Mesh;
+    post: THREE.Mesh;
+}
+declare function createSign(opts: SignOpts): SignResult;
+interface MonitorOpts {
+    scene?: THREE.Object3D;
+    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: THREE.Group;
+    body: THREE.Mesh;
+    screen: THREE.Mesh;
+    stand?: THREE.Mesh;
+}
+declare function createMonitor(opts: MonitorOpts): MonitorResult;
+interface DecalOpts {
+    scene?: THREE.Object3D;
+    name?: string;
+    /** The mesh to project the decal onto. */
+    target: THREE.Mesh;
+    /** World-space position the projector sits at. */
+    position: THREE.Vector3;
+    /** Direction the projector points. Defaults to -Z. */
+    normal?: THREE.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;
+}
+declare function createDecal(opts: DecalOpts): THREE.Mesh;
+declare function createWidgetTexture(name: string, widget: WidgetSpec, pixelWidth: number, pixelHeight: number, selected?: boolean): THREE.CanvasTexture;
+
+/**
+ * Layout helpers — map 2D scene-node positions onto 3D arrangements (three.js).
+ *
+ * All layout functions take the same shape: a SceneNode, the Object3D that was
+ * built for it, the scene's bounds, and layout-specific options. They mutate
+ * `obj.position` (and sometimes `obj.rotation.y`) in place.
+ *
+ * Pair with `sceneBounds(scene)` from the package root to compute the bounds.
+ * Mirrors `@particle-academy/fancy-3d-babylon`'s layout API.
+ */
+
+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?: THREE.Vector3;
+}
+declare function placeOnGrid(node: SceneNode, obj: THREE.Object3D, bounds: Bounds, opts?: GridLayoutOpts): void;
+interface WallLayoutOpts {
+    z?: number;
+    spreadX?: number;
+    spreadY?: number;
+    centerY?: number;
+}
+declare function placeOnWall(node: SceneNode, obj: THREE.Object3D, bounds: Bounds, opts?: WallLayoutOpts): void;
+interface ArcLayoutOpts {
+    radius?: number;
+    arc?: number;
+    height?: number;
+    baseY?: number;
+}
+declare function placeOnArc(node: SceneNode, obj: THREE.Object3D, bounds: Bounds, opts?: ArcLayoutOpts): void;
+interface PathLayoutOpts {
+    waypoints: THREE.Vector3[];
+    faceForward?: boolean;
+    byIndex?: boolean;
+    nodeCount?: number;
+}
+declare function placeOnPath(node: SceneNode, obj: THREE.Object3D, bounds: Bounds, opts: PathLayoutOpts): void;
+interface SphereLayoutOpts {
+    radius?: number;
+    center?: THREE.Vector3;
+    latSpan?: number;
+    lonSpan?: number;
+}
+declare function placeOnSphere(node: SceneNode, obj: THREE.Object3D, bounds: Bounds, opts?: SphereLayoutOpts): void;
+
+/**
+ * three.js adapter for `@particle-academy/fancy-3d`.
+ *
+ * Each widget kind paints onto a 2D HTMLCanvasElement that becomes a three
+ * `CanvasTexture`, applied to a plane mesh sized to the widget's pixel rect.
+ * The same `Scene` data renders recognizably across the DOM, Babylon, and
+ * three.js adapters.
+ *
+ * `three` is a peer dependency — only consumers building 3D scenes install it.
+ *
+ *   import { renderScene } from "@particle-academy/fancy-3d";
+ *   import { createThreeAdapter, placeOnArc, sceneBounds } from "@particle-academy/fancy-3d-three";
+ */
+
+interface ThreeAdapterDeps {
+    /** The three Scene meshes are added to. */
+    scene3D: THREE.Scene;
+    /** Pixel size for the widget (the scene node's `size` field). */
+    sizeFor(spec: WidgetSpec): {
+        w: number;
+        h: number;
+    };
+}
+declare function createThreeAdapter(deps: ThreeAdapterDeps): WidgetAdapter<THREE.Object3D>;
+/**
+ * "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, obj: THREE.Object3D, bounds: {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}, opts?: {
+    radius?: number;
+    arc?: number;
+}): void;
+declare function sceneBounds(scene: Scene): {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+};
+
+export { type ArcLayoutOpts, 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 ThreeAdapterDeps, type WallLayoutOpts, createBillboard, createBuilding, createCard3D, createCurvedPanel, createCylinder, createDecal, createDisc, createMonitor, createPanel, createPillar, createSign, createSphere, createThreeAdapter, createWidgetTexture, paintWidget, placeOnArc, placeOnCylinder, placeOnGrid, placeOnPath, placeOnSphere, placeOnWall, sceneBounds };