@3driseai/3drise-core 1.0.21 → 1.0.23

package/dist/utils/skyPhase.js

@@ -0,0 +1,93 @@
+/**
+ * Time-of-day phases, keyed by SUN ELEVATION — never by the clock.
+ *
+ * Everything that changes with the time of day (the Preetham atmosphere, star
+ * visibility, labels) reads these, so they all turn at the moment the sun
+ * actually crosses the horizon, whatever sunrise/sunset hours or sun model is in
+ * use. There used to be six hour tables that disagreed by up to 1.5 h.
+ *
+ * Keys, in degrees of sun elevation:
+ *   night     ≤ −12  (astronomical-ish: sky fully dark)
+ *   twilight    −4   (blue hour, sun just below the horizon)
+ *   golden       3   (sun on the horizon: reddest, haziest)
+ *   day       ≥ 15
+ * Between two keys the weights cross-fade with a smoothstep; they always sum to 1.
+ */
+export const SKY_PHASE_ELEVATIONS = { night: -12, twilight: -4, golden: 3, day: 15 };
+/** Built-in atmospheres for the non-day phases. The day look is the user's own
+ *  sky settings (see atmosphereForSunElevation). */
+export const SKY_PHASE_ATMOSPHERES = {
+    night: { turbidity: 0.5, rayleigh: 0.1, mieCoefficient: 0.001, mieDirectionalG: 0.8 },
+    twilight: { turbidity: 2.5, rayleigh: 2.0, mieCoefficient: 0.008, mieDirectionalG: 0.86 },
+    golden: { turbidity: 4.5, rayleigh: 3.5, mieCoefficient: 0.012, mieDirectionalG: 0.92 },
+};
+const smooth = (t) => {
+    const c = Math.max(0, Math.min(1, t));
+    return c * c * (3 - 2 * c);
+};
+/** Phase weights for a sun elevation in degrees. Sum to 1. */
+export function skyPhaseWeights(sunElevation, out) {
+    const w = out ?? { night: 0, twilight: 0, golden: 0, day: 0 };
+    w.night = 0;
+    w.twilight = 0;
+    w.golden = 0;
+    w.day = 0;
+    const { night, twilight, golden, day } = SKY_PHASE_ELEVATIONS;
+    if (sunElevation <= night) {
+        w.night = 1;
+        return w;
+    }
+    if (sunElevation >= day) {
+        w.day = 1;
+        return w;
+    }
+    if (sunElevation < twilight) {
+        const t = smooth((sunElevation - night) / (twilight - night));
+        w.night = 1 - t;
+        w.twilight = t;
+    }
+    else if (sunElevation < golden) {
+        const t = smooth((sunElevation - twilight) / (golden - twilight));
+        w.twilight = 1 - t;
+        w.golden = t;
+    }
+    else {
+        const t = smooth((sunElevation - golden) / (day - golden));
+        w.golden = 1 - t;
+        w.day = t;
+    }
+    return w;
+}
+/**
+ * The Preetham atmosphere for a sun elevation: the user's `day` look by day,
+ * blended through golden hour and twilight into night as the sun goes down.
+ * The user's sliders, keyframes and pointer bindings keep working with the clock
+ * on — they shape the day, and time of day adds the evening around it.
+ */
+export function atmosphereForSunElevation(sunElevation, day, out) {
+    const w = skyPhaseWeights(sunElevation);
+    const { night: n, twilight: t, golden: g } = SKY_PHASE_ATMOSPHERES;
+    const o = out ?? { turbidity: 0, rayleigh: 0, mieCoefficient: 0, mieDirectionalG: 0 };
+    o.turbidity = w.night * n.turbidity + w.twilight * t.turbidity + w.golden * g.turbidity + w.day * day.turbidity;
+    o.rayleigh = w.night * n.rayleigh + w.twilight * t.rayleigh + w.golden * g.rayleigh + w.day * day.rayleigh;
+    o.mieCoefficient = w.night * n.mieCoefficient + w.twilight * t.mieCoefficient + w.golden * g.mieCoefficient + w.day * day.mieCoefficient;
+    o.mieDirectionalG = w.night * n.mieDirectionalG + w.twilight * t.mieDirectionalG + w.golden * g.mieDirectionalG + w.day * day.mieDirectionalG;
+    return o;
+}
+/** How visible the night sky is (stars, moon halo): 0 by day, 1 once the sun is
+ *  12° down. */
+export function nightAmount(sunElevation) {
+    const w = skyPhaseWeights(sunElevation);
+    return w.night + w.twilight * 0.5;
+}
+/**
+ * How bright the sky dome is drawn, 1 by day. Preetham alone never gets darker
+ * than a flat grey after sunset (its constant 0.1 base term), so the night reads
+ * as overcast dusk instead of night. SkyMesh multiplies its output by this.
+ */
+export const SKY_PHASE_BRIGHTNESS = { night: 0.08, twilight: 0.5, golden: 1, day: 1 };
+export function skyBrightnessForSunElevation(sunElevation) {
+    const w = skyPhaseWeights(sunElevation);
+    const b = SKY_PHASE_BRIGHTNESS;
+    return w.night * b.night + w.twilight * b.twilight + w.golden * b.golden + w.day * b.day;
+}

package/dist/utils/spaceMigration.d.ts

@@ -0,0 +1,3 @@
+import type { CreatedObjectSettings } from '../types/scene3d';
+export declare function migrateSpaceObject<T extends CreatedObjectSettings>(obj: T): T;
+//# sourceMappingURL=spaceMigration.d.ts.map

package/dist/utils/spaceMigration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spaceMigration.d.ts","sourceRoot":"","sources":["../../src/utils/spaceMigration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAsB9D,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,qBAAqB,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CA2B7E"}

package/dist/utils/spaceMigration.js

@@ -0,0 +1,46 @@
+// =============================================================================
+// Space objects — load-time migration of the legacy config
+// =============================================================================
+//
+// The old starfield spun itself through a `rotateSpeed` knob (rotation.y +=
+// rotateSpeed * 0.01 every frame). Spinning the whole object is the parent's
+// transform, so the knob is gone from the space family; a saved starfield that
+// had it gets the equivalent transform 'spin' effect instead (rad/s at 60 fps),
+// unless it already animates its transform (a rotation effect, or keyframes: an
+// enabled transform effect would switch those off). The dead `size` / `sep` keys (never
+// read by the renderer) are dropped too.
+//
+// Pure and idempotent: returns the same object when there is nothing to migrate,
+// so it can run on every load without marking anything dirty.
+//
+const ROTATION_EFFECTS = new Set(['rotate3d', 'spin', 'sway', 'flip']);
+/** The old per-frame step (0.01 rad per unit) at 60 frames per second. */
+const LEGACY_FRAMES_PER_SECOND = 60;
+export function migrateSpaceObject(obj) {
+    if (!obj || obj.type !== 'space')
+        return obj;
+    const config = obj.config;
+    if (!config || config.type !== 'stars')
+        return obj;
+    if (!('rotateSpeed' in config) && !('size' in config) && !('sep' in config))
+        return obj;
+    const { rotateSpeed, size: _size, sep: _sep, ...rest } = config;
+    const next = { ...obj, config: rest };
+    const speed = typeof rotateSpeed === 'number' ? rotateSpeed * 0.01 * LEGACY_FRAMES_PER_SECOND : 0;
+    if (speed > 0) {
+        const animations = obj.animations ?? {};
+        const transform = animations.transform ?? {};
+        const effects = transform.effects ?? [];
+        const keyframed = (transform.animations?.length ?? 0) > 0;
+        if (!keyframed && !effects.some(e => ROTATION_EFFECTS.has(e?.type))) {
+            const hasOther = Object.entries(animations).some(([k, v]) => k !== 'enabled' && v && ((v.animations?.length ?? 0) > 0 || (v.effects?.length ?? 0) > 0));
+            next.animations = {
+                ...animations,
+                // Switch the animations on only when nothing else is there that the user may have turned off.
+                enabled: hasOther ? (animations.enabled ?? true) : true,
+                transform: { ...transform, effects: [...effects, { type: 'spin', enabled: true, speed, options: { axis: 'y' } }] },
+            };
+        }
+    }
+    return next;
+}

package/dist/utils/sunUtils.d.ts

@@ -1,6 +1,31 @@
-export declare function createSunPosition(elevation: number, azimuth: number): {
+/**
+ * THE sun direction convention for 3drise. Every piece that turns an
+ * elevation/azimuth pair into a direction — the Preetham sky, the key light,
+ * the day-cycle clock, the clouds, the ocean, the terrain, the lighting rig —
+ * goes through `sunDirectionFromAngles`, so the sun that is drawn and the sun
+ * that lights the scene cannot disagree.
+ *
+ *   elevation  degrees above the horizon (90 = straight up, negative = below)
+ *   azimuth    degrees around +Y, measured from +X towards +Z
+ *              (0 → +X, 90 → +Z, 180 → −X, −90 → −Z)
+ *
+ * There used to be two conventions: this one (Preetham sky, LightsManager) and
+ * x = sin(az), z = cos(az) (the clock, the skybox shader, useCloudSun), which
+ * mirrored the lit sun across the x = z plane — up to 137° away from the disc.
+ */
+export interface Vec3Like {
     x: number;
     y: number;
     z: number;
+}
+/** Unit vector toward the sun. Writes into `out` when given (a THREE.Vector3
+ *  works), so per-frame callers allocate nothing. */
+export declare function sunDirectionFromAngles<T extends Vec3Like = Vec3Like>(elevation: number, azimuth: number, out?: T): T;
+/** Inverse of `sunDirectionFromAngles`. The vector need not be normalised. */
+export declare function sunAnglesFromDirection(dir: Vec3Like): {
+    elevation: number;
+    azimuth: number;
 };
+/** Kept for existing callers; same convention. */
+export declare function createSunPosition(elevation: number, azimuth: number): Vec3Like;
 //# sourceMappingURL=sunUtils.d.ts.map

package/dist/utils/sunUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sunUtils.d.ts","sourceRoot":"","sources":["../../src/utils/sunUtils.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG;IAC/D,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb,CAQJ"}
+{"version":3,"file":"sunUtils.d.ts","sourceRoot":"","sources":["../../src/utils/sunUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,QAAQ;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb;AAID;qDACqD;AACrD,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CASpH;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,QAAQ,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAM5F;AAED,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAE9E"}

package/dist/utils/sunUtils.js

@@ -1,9 +1,40 @@
-export function createSunPosition(elevation, azimuth) {
-    const phi = (90 - elevation) * (Math.PI / 180);
-    const theta = azimuth * (Math.PI / 180);
+/**
+ * THE sun direction convention for 3drise. Every piece that turns an
+ * elevation/azimuth pair into a direction — the Preetham sky, the key light,
+ * the day-cycle clock, the clouds, the ocean, the terrain, the lighting rig —
+ * goes through `sunDirectionFromAngles`, so the sun that is drawn and the sun
+ * that lights the scene cannot disagree.
+ *
+ *   elevation  degrees above the horizon (90 = straight up, negative = below)
+ *   azimuth    degrees around +Y, measured from +X towards +Z
+ *              (0 → +X, 90 → +Z, 180 → −X, −90 → −Z)
+ *
+ * There used to be two conventions: this one (Preetham sky, LightsManager) and
+ * x = sin(az), z = cos(az) (the clock, the skybox shader, useCloudSun), which
+ * mirrored the lit sun across the x = z plane — up to 137° away from the disc.
+ */
+const DEG = Math.PI / 180;
+/** Unit vector toward the sun. Writes into `out` when given (a THREE.Vector3
+ *  works), so per-frame callers allocate nothing. */
+export function sunDirectionFromAngles(elevation, azimuth, out) {
+    const el = elevation * DEG;
+    const az = azimuth * DEG;
+    const c = Math.cos(el);
+    const target = (out ?? { x: 0, y: 0, z: 0 });
+    target.x = c * Math.cos(az);
+    target.y = Math.sin(el);
+    target.z = c * Math.sin(az);
+    return target;
+}
+/** Inverse of `sunDirectionFromAngles`. The vector need not be normalised. */
+export function sunAnglesFromDirection(dir) {
+    const r = Math.sqrt(dir.x * dir.x + dir.y * dir.y + dir.z * dir.z) || 1;
     return {
-        x: Math.sin(phi) * Math.cos(theta),
-        y: Math.cos(phi),
-        z: Math.sin(phi) * Math.sin(theta),
+        elevation: Math.asin(Math.max(-1, Math.min(1, dir.y / r))) / DEG,
+        azimuth: Math.atan2(dir.z, dir.x) / DEG,
     };
 }
+/** Kept for existing callers; same convention. */
+export function createSunPosition(elevation, azimuth) {
+    return sunDirectionFromAngles(elevation, azimuth);
+}

package/dist/utils/textMigration.d.ts

@@ -0,0 +1,3 @@
+import type { CreatedObjectSettings } from '../types/scene3d';
+export declare function migrateTextObject<T extends CreatedObjectSettings>(obj: T): T;
+//# sourceMappingURL=textMigration.d.ts.map

package/dist/utils/textMigration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textMigration.d.ts","sourceRoot":"","sources":["../../src/utils/textMigration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAqB9D,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,qBAAqB,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAuC5E"}

package/dist/utils/textMigration.js

@@ -0,0 +1,56 @@
+import { DEFAULT_TEXT_OBJECTS, TEXT_FONTS } from '../data/textDefaults.js';
+// =============================================================================
+// Text — load-time migration of the legacy 2d (bitmap) / 3d text
+// =============================================================================
+//
+// Object type 'text' used to host two renderers told apart by `config.renderMode` and carrying no
+// `config.type`: a troika bitmap text ('bitmap') and a per-letter extruded text ('text3d'). Both are gone:
+//   bitmap  → the `plain` text look (same object type; the material colour / opacity become the look's own
+//             knobs, the em size matches so a 0.5 fontSize keeps its size and any other scales the transform)
+//   text3d  → the `text` shape of the mesh family (object type 'mesh'), which keeps its material and bevel
+// Fonts the packed font list does not know fall back to the default face.
+//
+// Pure and idempotent: a text with a config.type is already in the new shape and is returned as is.
+//
+const KNOWN_FONTS = new Set(TEXT_FONTS.map((f) => f.id));
+const fontOf = (font) => (typeof font === 'string' && KNOWN_FONTS.has(font) ? font : 'inter');
+const num = (v, d) => (typeof v === 'number' && Number.isFinite(v) ? v : d);
+export function migrateTextObject(obj) {
+    if (!obj || obj.type !== 'text')
+        return obj;
+    const config = (obj.config ?? {});
+    if (typeof config.type === 'string' && config.type in DEFAULT_TEXT_OBJECTS)
+        return obj;
+    const text = typeof config.text === 'string' ? config.text : 'Hello';
+    const font = fontOf(config.font);
+    const material = (obj.materialSettings ?? {});
+    if (config.renderMode === 'text3d') {
+        const bevel = config.bevelEnabled !== false;
+        return {
+            ...obj,
+            type: 'mesh',
+            config: {
+                type: 'text', text, font,
+                size: num(config.size, 1), height: num(config.height, 0.2), letterSpacing: num(config.letterSpacing, 0),
+                bevelEnabled: bevel, bevelThickness: num(config.bevelThickness, 0.02), bevelSize: num(config.bevelSize, 0.015), bevelSegments: num(config.bevelSegments, 3),
+            },
+        };
+    }
+    // bitmap (or no renderMode at all) → plain look
+    const next = {
+        ...obj,
+        config: {
+            ...DEFAULT_TEXT_OBJECTS.plain, text, font,
+            ...(typeof material.color === 'string' ? { color: material.color } : {}),
+            ...(typeof material.opacity === 'number' ? { opacity: material.opacity } : {}),
+        },
+    };
+    const fontSize = num(config.fontSize, 0.5);
+    if (Math.abs(fontSize - 0.5) > 1e-6) {
+        const k = fontSize / 0.5;
+        const ms = obj.meshSettings ?? {};
+        const sc = Array.isArray(ms.scale) && ms.scale.length === 3 ? ms.scale : [1, 1, 1];
+        next.meshSettings = { ...ms, scale: sc.map((v) => v * k) };
+    }
+    return next;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3driseai/3drise-core",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",