three-low-poly 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -19,7 +19,6 @@ import { ParametricGeometry } from 'three/addons/geometries/ParametricGeometry.j
 import { PerspectiveCamera } from 'three';
 import { PlaneGeometry } from 'three';
 import { PointLight } from 'three';
-import { Points } from 'three';
 import { Quaternion } from 'three';
 import { Shape } from 'three';
 import { ShapeGeometry } from 'three';
@@ -3764,11 +3763,11 @@ export declare class Star extends Mesh<StarGeometry, MeshStandardMaterial> {
 }
 
 export declare interface StarBurstShapeOptions {
-    /** Burst ray count. Defaults to `4`. */
+    /** Burst ray count. Defaults to `4` point diffraction spike. */
     sides?: number;
     innerRadius?: number;
     outerRadius?: number;
-    /** Extrusion depth; keep small for flat starbursts. Defaults to `0.05`. */
+    /** Extrusion depth (`orientation: "radial"` only — billboards are flat). Defaults to `0.05`. */
     depth?: number;
 }
 
@@ -3780,27 +3779,27 @@ export declare interface StarBurstShapeOptions {
  * every frame. Parenting to the camera is not supported: Three.js does not render
  * objects attached to the active camera.
  *
- * **Styles**
+ * **Orientation** — the only axis that distinguishes how stars are drawn:
  *
- * - `points` — lightweight `Points` sprites using a canvas starburst texture.
- * - `burst` — instanced 3D starbursts ({@link BurstGeometry}) that face the shell center.
- *   Uses `DoubleSide` so stars remain visible when the camera sits inside the shell.
+ * - `billboard` — screen-aligned via `SpriteNodeMaterial`, with per-star position, scale,
+ *   and rotation supplied as instanced attributes. The field stays visually fixed as the
+ *   camera orbits. Flat by construction: only the geometry's XY profile is used.
+ * - `radial` — instanced 3D meshes rotated to face the shell center, drawn `DoubleSide` so
+ *   stars stay visible from inside the shell.
+ *
+ * Both orientations render as a single instanced draw call, so the geometry you pass is a
+ * matter of looks rather than cost.
  *
  * **Sizing** — `sizeMin` / `sizeMax` are angular extents (radians at unit distance),
  * multiplied by each star's distance from the origin so stars look similar regardless
  * of shell depth (`minRadius`–`maxRadius`).
  *
- * **Rendering** — `frustumCulled` is disabled and materials use `depthWrite: false` so
- * the field draws reliably as a background layer. For per-star color variation in burst
- * mode, colors are written via `InstancedMesh.setColorAt`, not `vertexColors` on the
- * base material.
- *
  * @example
  * ```typescript
  * const stars = new StarFieldEffect({
- *   style: "burst",
  *   count: 2500,
  *   radius: 480,
+ *   rotationJitter: 0, // every burst locked vertical on screen
  *   twinkle: true,
  * });
  *
@@ -3813,52 +3812,61 @@ export declare interface StarBurstShapeOptions {
  * }
  * ```
  *
- * Call {@link dispose} when removing the effect to free geometry, materials, and the
- * points sprite texture.
+ * Call {@link dispose} when removing the effect to free geometry and materials.
  */
 export declare class StarFieldEffect extends Object3D {
-    readonly style: "points" | "burst";
+    readonly orientation: StarFieldOrientation;
     private readonly field;
     private readonly twinkle;
-    private readonly baseSize;
     private readonly baseScales?;
     private readonly twinklePhases?;
-    /** Untwinkled per-point RGB (points style), multiplied by each star's pulse each frame. */
-    private baseColors?;
-    private spriteTexture?;
+    /** Billboard scale attribute, rewritten each frame while twinkling. */
+    private scaleAttribute?;
     private readonly dummy;
     constructor(options?: StarFieldEffectOptions);
-    get drawable(): Points | InstancedMesh;
+    get mesh(): InstancedMesh;
     get geometry(): BufferGeometry;
     get material(): Material | Material[];
-    /** Release GPU resources held by the field (and sprite texture, if any). */
+    /** Release GPU resources held by the field. */
     dispose(): void;
     /**
      * Animate twinkling. No-op when `twinkle` is `false`.
      *
-     * Both styles pulse with a per-star phase offset so stars twinkle out of sync:
-     * points modulate per-point brightness (via the color attribute), burst pulses
-     * each instance scale. Pass elapsed time in seconds (defaults to `performance.now()`).
+     * Each star pulses on its own phase offset so the field twinkles out of sync. Billboards
+     * rewrite the instanced scale attribute; radial stars rebuild each instance matrix.
+     * Pass elapsed time in seconds (defaults to `performance.now()`).
      */
     update(elapsed?: number): void;
-    private createPointsField;
-    private createBurstField;
+    /**
+     * Screen-aligned stars. `SpriteNodeMaterial` builds its quad from the geometry's XY and
+     * reads the sprite center from `positionNode` — it never consults `instanceMatrix` — so
+     * every per-star value has to arrive as an instanced attribute.
+     */
+    private createBillboardField;
+    /** Full 3D stars rotated to face the shell center. */
+    private createRadialField;
 }
 
 export declare interface StarFieldEffectOptions {
     /**
-     * Rendering style.
+     * How each star faces the viewer.
      *
-     * - `points` (default) — billboard sprites with a procedural starburst texture
-     *   (not the default square `Points` marker).
-     * - `burst` — instanced {@link BurstGeometry} meshes oriented toward the shell center.
+     * - `billboard` (default) — every star is screen-aligned, so the field holds its
+     *   orientation as the camera orbits. Only the geometry's **XY profile** is drawn;
+     *   any Z extent is ignored.
+     * - `radial` — full 3D geometry rotated to face the shell center. Depth is real here,
+     *   and stars shear as the camera moves, the way any world-space mesh does.
      */
-    style?: "points" | "burst";
-    /** Shape parameters for both styles; `burst` uses them for geometry, `points` for the sprite. */
+    orientation?: StarFieldOrientation;
+    /** Star shape used to build the default {@link BurstGeometry}. */
     burst?: StarBurstShapeOptions;
-    /** Override the burst mesh geometry (`style: "burst"` only). */
+    /** Replace the star geometry entirely. Billboards use its XY profile; radial uses all of it. */
     geometry?: BufferGeometry;
-    /** Override the default field material. */
+    /**
+     * Override the default field material. In `billboard` mode this must be a
+     * `SpriteNodeMaterial` — per-star position, scale, and rotation are assigned onto it
+     * as node inputs.
+     */
     material?: Material;
     /** Number of stars. Defaults to `1500`. */
     count?: number;
@@ -3879,8 +3887,26 @@ export declare interface StarFieldEffectOptions {
     color?: ColorRepresentation | ColorRepresentation[];
     /** Enable pulsing brightness; call {@link StarFieldEffect.update} each frame when `true`. */
     twinkle?: boolean;
+    /**
+     * Base star rotation, in radians. Defaults to `0`.
+     *
+     * Measured in screen space for `billboard` and world space for `radial` — the same knob
+     * means different things, because a billboard re-aligns every frame and a radial star
+     * does not.
+     */
+    rotation?: number;
+    /**
+     * Random rotation spread added per star, in radians. Defaults to `Math.PI * 2`.
+     *
+     * `0` aligns every star — with `billboard` that yields a coherent diffraction-spike field
+     * that stays locked as the camera orbits. `2π` is fully random.
+     */
+    rotationJitter?: number;
 }
 
+/** How each star is turned to face the viewer. */
+export declare type StarFieldOrientation = "billboard" | "radial";
+
 /**
  * Extruded star prism.
  */