entangled-worlds-orbiters-shared 3.3.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/README.md +3 -2
  2. package/dist/config/env.d.ts +8 -0
  3. package/dist/config/env.js +36 -0
  4. package/dist/config/index.d.ts +3 -0
  5. package/dist/config/index.js +4 -0
  6. package/dist/config/textureConfig.d.ts +140 -0
  7. package/dist/config/textureConfig.js +318 -0
  8. package/dist/core/index.d.ts +2 -0
  9. package/dist/core/index.js +3 -0
  10. package/dist/core/lightFresnel.d.ts +6 -0
  11. package/dist/core/lightFresnel.js +63 -0
  12. package/dist/core/lights.d.ts +48 -0
  13. package/dist/core/lights.js +79 -0
  14. package/dist/index.d.ts +6 -0
  15. package/dist/index.js +7 -0
  16. package/dist/loaders/bodyTextureLoader.d.ts +10 -0
  17. package/dist/loaders/bodyTextureLoader.js +28 -0
  18. package/dist/loaders/cubeMapLoader.d.ts +58 -0
  19. package/dist/loaders/cubeMapLoader.js +291 -0
  20. package/dist/loaders/glbLoader.d.ts +24 -0
  21. package/dist/loaders/glbLoader.js +72 -0
  22. package/dist/loaders/index.d.ts +5 -0
  23. package/{src → dist}/loaders/index.js +0 -2
  24. package/dist/{types/loaders → loaders}/ktx2.d.ts +4 -6
  25. package/dist/loaders/ktx2.js +48 -0
  26. package/dist/moons/index.d.ts +3 -0
  27. package/dist/moons/index.js +3 -0
  28. package/dist/moons/moonsGeneration.d.ts +64 -0
  29. package/dist/moons/moonsGeneration.js +238 -0
  30. package/dist/moons/moonsManager.d.ts +43 -0
  31. package/dist/moons/moonsManager.js +93 -0
  32. package/dist/{types/render → render}/frameBudget.d.ts +18 -17
  33. package/dist/render/frameBudget.js +42 -0
  34. package/dist/render/index.d.ts +4 -0
  35. package/dist/render/viewportCompositor.d.ts +124 -0
  36. package/dist/render/viewportCompositor.js +643 -0
  37. package/dist/studio/headerBroadcast.d.ts +10 -1
  38. package/dist/studio/hostTransport.d.ts +2 -2
  39. package/dist/studio/index.d.ts +1 -1
  40. package/dist/utils/dispose.d.ts +5 -0
  41. package/dist/utils/dispose.js +50 -0
  42. package/dist/utils/index.d.ts +3 -0
  43. package/{src → dist}/utils/index.js +1 -1
  44. package/dist/utils/materials.d.ts +10 -0
  45. package/dist/utils/materials.js +36 -0
  46. package/dist/world/cloudShell.d.ts +16 -0
  47. package/dist/world/cloudShell.js +73 -0
  48. package/dist/world/index.d.ts +6 -0
  49. package/{src → dist}/world/index.js +0 -2
  50. package/dist/world/worldGLB.d.ts +17 -0
  51. package/dist/world/worldGLB.js +22 -0
  52. package/dist/world/worldManager.d.ts +57 -0
  53. package/dist/world/worldManager.js +125 -0
  54. package/dist/world/worldNormal.d.ts +30 -0
  55. package/dist/world/worldNormal.js +58 -0
  56. package/dist/world/worldTexture.d.ts +56 -0
  57. package/dist/world/worldTexture.js +299 -0
  58. package/package.json +29 -39
  59. package/src/config/env.ts +48 -0
  60. package/src/config/{index.js → index.ts} +7 -0
  61. package/src/config/{textureConfig.js → textureConfig.ts} +126 -60
  62. package/src/core/{lightFresnel.js → lightFresnel.ts} +1 -1
  63. package/src/core/{lights.js → lights.ts} +21 -21
  64. package/src/loaders/{bodyTextureLoader.js → bodyTextureLoader.ts} +10 -7
  65. package/src/loaders/{cubeMapLoader.js → cubeMapLoader.ts} +83 -49
  66. package/src/loaders/{glbLoader.js → glbLoader.ts} +41 -18
  67. package/src/loaders/index.ts +6 -0
  68. package/src/loaders/{ktx2.js → ktx2.ts} +5 -7
  69. package/src/moons/{index.js → index.ts} +1 -0
  70. package/src/moons/{moonsGeneration.js → moonsGeneration.ts} +45 -32
  71. package/src/moons/{moonsManager.js → moonsManager.ts} +37 -11
  72. package/src/render/{frameBudget.js → frameBudget.ts} +15 -8
  73. package/src/render/index.ts +14 -0
  74. package/src/render/{viewportCompositor.js → viewportCompositor.ts} +121 -59
  75. package/src/studio/headerBroadcast.ts +14 -1
  76. package/src/studio/hostTransport.ts +2 -1
  77. package/src/studio/index.ts +1 -1
  78. package/src/utils/dispose.ts +47 -0
  79. package/src/utils/index.ts +4 -0
  80. package/src/utils/materials.ts +44 -0
  81. package/src/world/{cloudShell.js → cloudShell.ts} +19 -12
  82. package/src/world/index.ts +7 -0
  83. package/src/world/worldGLB.ts +41 -0
  84. package/src/world/{worldManager.js → worldManager.ts} +67 -32
  85. package/src/world/{worldNormal.js → worldNormal.ts} +25 -20
  86. package/src/world/{worldTexture.js → worldTexture.ts} +70 -51
  87. package/dist/types/config/env.d.ts +0 -12
  88. package/dist/types/config/index.d.ts +0 -2
  89. package/dist/types/config/textureConfig.d.ts +0 -121
  90. package/dist/types/core/index.d.ts +0 -2
  91. package/dist/types/core/lightFresnel.d.ts +0 -5
  92. package/dist/types/core/lights.d.ts +0 -58
  93. package/dist/types/index.d.ts +0 -6
  94. package/dist/types/loaders/bodyTextureLoader.d.ts +0 -12
  95. package/dist/types/loaders/cubeMapLoader.d.ts +0 -70
  96. package/dist/types/loaders/glbLoader.d.ts +0 -24
  97. package/dist/types/loaders/index.d.ts +0 -5
  98. package/dist/types/moons/index.d.ts +0 -2
  99. package/dist/types/moons/moonsGeneration.d.ts +0 -72
  100. package/dist/types/moons/moonsManager.d.ts +0 -27
  101. package/dist/types/render/index.d.ts +0 -2
  102. package/dist/types/render/viewportCompositor.d.ts +0 -58
  103. package/dist/types/utils/dispose.d.ts +0 -2
  104. package/dist/types/utils/index.d.ts +0 -2
  105. package/dist/types/utils/materials.d.ts +0 -2
  106. package/dist/types/world/cloudShell.d.ts +0 -25
  107. package/dist/types/world/index.d.ts +0 -6
  108. package/dist/types/world/worldGLB.d.ts +0 -20
  109. package/dist/types/world/worldManager.d.ts +0 -63
  110. package/dist/types/world/worldNormal.d.ts +0 -43
  111. package/dist/types/world/worldTexture.d.ts +0 -80
  112. package/src/config/env.js +0 -38
  113. package/src/utils/dispose.js +0 -39
  114. package/src/utils/materials.js +0 -31
  115. package/src/world/worldGLB.js +0 -19
  116. /package/{src → dist}/render/index.js +0 -0
  117. /package/src/core/{index.js → index.ts} +0 -0
  118. /package/src/{index.js → index.ts} +0 -0
@@ -1,3 +1,4 @@
1
+ import type * as THREE from 'three';
1
2
  import { disposeObject3D } from '../utils/dispose.js';
2
3
  import { makeGLB } from './worldGLB.js';
3
4
  import { makeSphere } from './worldTexture.js';
@@ -7,19 +8,58 @@ import { makeNormalSphere } from './worldNormal.js';
7
8
  * Builds a world object for a mode registered with `registerWorldCreator`. It receives the manager's
8
9
  * flags, the `setMode` args and the renderer, and may return the object or a promise of it (the
9
10
  * manager awaits either).
10
- * @typedef {(args: { flags: object, renderer: import('three').WebGLRenderer | null, [key: string]: unknown }) => import('three').Object3D | Promise<import('three').Object3D>} WorldCreator
11
11
  */
12
+ export type WorldCreator = (args: {
13
+ flags: object;
14
+ renderer: THREE.WebGLRenderer | null;
15
+ [key: string]: unknown;
16
+ }) => THREE.Object3D | Promise<THREE.Object3D>;
17
+
18
+ /**
19
+ * What `setMode` takes: the options of the world it builds. Mode 2 reads `modelUrl` (required there:
20
+ * it throws without one), `withCredentials` and `emissiveIntensity`; mode 3 passes everything to
21
+ * `makeNormalSphere`, the textured sphere to `makeSphere`, a registered creator gets it all as given.
22
+ * The manager's own renderer is always used. `flags`, when given, replaces the manager's flags for
23
+ * that world in every mode but 2 (which always uses the manager's).
24
+ */
25
+ export type WorldModeArgs = Omit<NonNullable<Parameters<typeof makeSphere>[0]>, 'renderer'> &
26
+ Omit<NonNullable<Parameters<typeof makeNormalSphere>[0]>, 'renderer'> & {
27
+ modelUrl?: string;
28
+ withCredentials?: boolean;
29
+ emissiveIntensity?: number;
30
+ [key: string]: unknown;
31
+ };
12
32
 
13
33
  export class WorldManager {
14
- /**
15
- * @param {import('three').Scene} scene
16
- * @param {object} [opts]
17
- * @param {() => void} [opts.onLoadStart]
18
- * @param {() => void} [opts.onLoadEnd]
19
- * @param {import('three').WebGLRenderer | null} [opts.renderer]
20
- * @param {boolean} [opts.externalTick=false]
21
- */
22
- constructor(scene, { onLoadStart, onLoadEnd, renderer, externalTick = false } = {}) {
34
+ // The fields are `declare`d so the emitted class assigns them in the constructor only, as the JS
35
+ // did: subclasses in the apps redefine `renderer` on the instance after `super()`.
36
+ declare scene: THREE.Scene;
37
+ declare renderer: THREE.WebGLRenderer | null;
38
+ declare externalTick: boolean;
39
+ /** The world on show, or null. */
40
+ declare current: THREE.Object3D | null;
41
+ /** Merged by `setFlags`, handed to every world built (material flags such as `forceOpaque`). */
42
+ declare flags: Record<string, unknown>;
43
+ declare onLoadStart: (() => void) | undefined;
44
+ declare onLoadEnd: (() => void) | undefined;
45
+ declare token: number;
46
+ /** The creators `registerWorldCreator` added, by mode. */
47
+ declare customCreators: Map<number, WorldCreator>;
48
+
49
+ constructor(
50
+ scene: THREE.Scene,
51
+ {
52
+ onLoadStart,
53
+ onLoadEnd,
54
+ renderer,
55
+ externalTick = false,
56
+ }: {
57
+ onLoadStart?: (() => void) | undefined;
58
+ onLoadEnd?: (() => void) | undefined;
59
+ renderer?: THREE.WebGLRenderer | null | undefined;
60
+ externalTick?: boolean | undefined;
61
+ } = {},
62
+ ) {
23
63
  this.scene = scene;
24
64
  // The renderer this world belongs to — threaded to the texture loaders so each view's textures
25
65
  // bind to its OWN WebGL context (multi-view: N orbiters / N planets in one page). REQUIRED for
@@ -31,7 +71,6 @@ export class WorldManager {
31
71
  // defeating the one-loop compositor.
32
72
  this.externalTick = Boolean(externalTick);
33
73
  this.current = null;
34
- /** @type {Record<string, any>} */
35
74
  this.flags = {};
36
75
  this.onLoadStart = onLoadStart;
37
76
  this.onLoadEnd = onLoadEnd;
@@ -40,11 +79,8 @@ export class WorldManager {
40
79
  this.customCreators = new Map();
41
80
  }
42
81
 
43
- /**
44
- * Run the current world's per-frame updater once (externalTick hosts only; no-op otherwise).
45
- * @param {number} timeSec
46
- */
47
- tick(timeSec) {
82
+ /** Run the current world's per-frame updater once (externalTick hosts only; no-op otherwise). */
83
+ tick(timeSec: number): void {
48
84
  if (!this.externalTick || !this.current) return;
49
85
  const updater = this.current.userData?.update;
50
86
  if (typeof updater !== 'function') return;
@@ -57,12 +93,12 @@ export class WorldManager {
57
93
  }
58
94
  }
59
95
 
60
- /** @param {object} flags merged over the current flags */
61
- setFlags(flags) {
96
+ /** `flags` are merged over the current flags. */
97
+ setFlags(flags: object): void {
62
98
  this.flags = { ...this.flags, ...flags };
63
99
  }
64
100
 
65
- disposeCurrent() {
101
+ disposeCurrent(): void {
66
102
  if (this.current) {
67
103
  disposeObject3D(this.current);
68
104
  this.scene.remove(this.current);
@@ -71,22 +107,15 @@ export class WorldManager {
71
107
  }
72
108
 
73
109
  // Register custom world creators for app-specific world types
74
- /**
75
- * @param {number} mode
76
- * @param {WorldCreator} creatorFunction
77
- */
78
- registerWorldCreator(mode, creatorFunction) {
110
+ registerWorldCreator(mode: number, creatorFunction: WorldCreator): void {
79
111
  this.customCreators.set(mode, creatorFunction);
80
112
  }
81
113
 
82
114
  /**
83
115
  * Build and show the world for `mode` (a registered creator, 2 = GLB, 3 = normal sphere, else the
84
116
  * textured sphere), replacing the current one. A newer call supersedes one still loading.
85
- * @param {number} mode
86
- * @param {Record<string, any>} [args]
87
- * @returns {Promise<void>}
88
117
  */
89
- async setMode(mode, args = {}) {
118
+ async setMode(mode: number, args: WorldModeArgs = {}): Promise<void> {
90
119
  const myToken = ++this.token;
91
120
  this.onLoadStart?.();
92
121
  try {
@@ -95,10 +124,12 @@ export class WorldManager {
95
124
 
96
125
  // Check for custom creators first
97
126
  if (this.customCreators.has(mode)) {
98
- obj = await this.customCreators.get(mode)({ flags: this.flags, ...args, renderer });
127
+ // `has` just said it is there; a creator registered as nothing (untyped callers) throws, as always.
128
+ obj = await this.customCreators.get(mode)!({ flags: this.flags, ...args, renderer });
99
129
  } else if (mode === 2) {
100
130
  obj = await makeGLB({
101
- modelUrl: args.modelUrl,
131
+ // `makeGLB` throws without a model, so a mode-2 call without one fails there, as always.
132
+ modelUrl: args.modelUrl as string,
102
133
  flags: this.flags,
103
134
  withCredentials: Boolean(args.withCredentials),
104
135
  renderer,
@@ -114,8 +145,12 @@ export class WorldManager {
114
145
  return;
115
146
  }
116
147
  this.disposeCurrent();
117
- this.scene.add(obj);
118
- this.current = obj;
148
+ // An object by every type here: a creator returns one, and `makeGLB` resolves to nothing only
149
+ // with `retries` of 0 or less, while this call keeps its default of 3. Cast, not checked, as
150
+ // the JS always took it.
151
+ const world = obj as THREE.Object3D;
152
+ this.scene.add(world);
153
+ this.current = world;
119
154
 
120
155
  // If the object exposes a frame updater, run a render-time loop — unless an external host
121
156
  // drives it via tick() (shared-renderer compositor: one loop for all worlds).
@@ -10,24 +10,10 @@ import { resolvePublicUrl } from '../config/env.js';
10
10
  * Create a simple sphere using THREE.MeshNormalMaterial.
11
11
  * Accepts the same basic geometry params as textured sphere so the manager API is consistent.
12
12
  *
13
- * @param {object} [opts]
14
- * @param {number} [opts.sphereRadius]
15
- * @param {number} [opts.sphereWidthSegments]
16
- * @param {number} [opts.sphereHeightSegments]
17
- * @param {object} [opts.flags] material flags (`forceOpaque`, `wireframe`).
18
- * @param {boolean} [opts.glow] add the fresnel halo.
19
- * @param {number} [opts.glowScale=1.18]
20
- * @param {number} [opts.glowRimHex=0x66ccff]
21
- * @param {number} [opts.glowFacingHex=0x000000]
22
- * @param {number} [opts.glowBias=0.02]
23
- * @param {number} [opts.glowFresnelScale=1]
24
- * @param {number} [opts.glowPower=3.5]
25
- * @param {boolean} [opts.cloudsEnabled]
26
- * @param {string} [opts.cloudsTextureUrl]
27
- * @param {number} [opts.cloudsColor=0xffffff]
28
- * @param {number} [opts.cloudsOpacity=0.6]
29
- * @param {number} [opts.cloudsSpeed=0.015]
30
- * @param {import('three').WebGLRenderer | null} [opts.renderer]
13
+ * `flags`: material flags (`forceOpaque`, `wireframe`); `glow` adds the fresnel halo. Defaults:
14
+ * `glowScale` 1.18, `glowRimHex` 0x66ccff, `glowFacingHex` 0x000000, `glowBias` 0.02,
15
+ * `glowFresnelScale` 1, `glowPower` 3.5, `cloudsColor` 0xffffff, `cloudsOpacity` 0.6,
16
+ * `cloudsSpeed` 0.015.
31
17
  */
32
18
  export async function makeNormalSphere({
33
19
  sphereRadius,
@@ -47,10 +33,29 @@ export async function makeNormalSphere({
47
33
  cloudsOpacity = 0.6,
48
34
  cloudsSpeed = 0.015,
49
35
  renderer = null,
36
+ }: {
37
+ sphereRadius?: number | undefined;
38
+ sphereWidthSegments?: number | undefined;
39
+ sphereHeightSegments?: number | undefined;
40
+ flags?: object | undefined;
41
+ glow?: boolean | undefined;
42
+ glowScale?: number | undefined;
43
+ glowRimHex?: number | undefined;
44
+ glowFacingHex?: number | undefined;
45
+ glowBias?: number | undefined;
46
+ glowFresnelScale?: number | undefined;
47
+ glowPower?: number | undefined;
48
+ cloudsEnabled?: boolean | undefined;
49
+ cloudsTextureUrl?: string | undefined;
50
+ cloudsColor?: number | undefined;
51
+ cloudsOpacity?: number | undefined;
52
+ cloudsSpeed?: number | undefined;
53
+ renderer?: THREE.WebGLRenderer | null | undefined;
50
54
  } = {}) {
51
55
  const radius = typeof sphereRadius === 'number' ? Math.max(0.0001, sphereRadius) : EARTH_RADIUS_UNITS;
52
- const widthSegs = Number.isFinite(sphereWidthSegments) ? Math.max(3, Math.floor(sphereWidthSegments)) : 64;
53
- const heightSegs = Number.isFinite(sphereHeightSegments) ? Math.max(2, Math.floor(sphereHeightSegments)) : 64;
56
+ // `Number.isFinite` does not narrow: past it, each count is a number.
57
+ const widthSegs = Number.isFinite(sphereWidthSegments) ? Math.max(3, Math.floor(sphereWidthSegments as number)) : 64;
58
+ const heightSegs = Number.isFinite(sphereHeightSegments) ? Math.max(2, Math.floor(sphereHeightSegments as number)) : 64;
54
59
  const geometry = new THREE.SphereGeometry(radius, widthSegs, heightSegs);
55
60
  const material = new THREE.MeshNormalMaterial();
56
61
  if (flags) applyFlagsToMaterial(material, flags);
@@ -8,28 +8,34 @@ import { resolvePublicUrl } from '../config/env.js';
8
8
  // Debug tag so you can verify the loaded file version in console
9
9
  export const WORLD_TEXTURE_DEBUG_TAG = 'WT:vFlipGeom-r3@2025-10-28T17:22:00Z';
10
10
 
11
+ /** The debug globals this module reads and sets on `window`. Not exported: no global type is added. */
12
+ type DebugWindow = Window & { DEBUG_TEXTURE_FLIP?: boolean; EW_WT_DEBUG_TAG?: string };
13
+
11
14
  // Enable debug if query/localStorage says so; expose tag
12
15
  if (typeof window !== 'undefined') {
13
16
  const q = (window.location && window.location.search) || '';
14
17
  const qsDebug = /(?:[?&])debugTextures=1(?:&|$)/.test(q);
15
18
  const lsDebug = (window.localStorage && window.localStorage.DEBUG_TEXTURE_FLIP === '1') || false;
16
- if (!window.DEBUG_TEXTURE_FLIP && (qsDebug || lsDebug)) {
17
- window.DEBUG_TEXTURE_FLIP = true;
19
+ if (!(window as DebugWindow).DEBUG_TEXTURE_FLIP && (qsDebug || lsDebug)) {
20
+ (window as DebugWindow).DEBUG_TEXTURE_FLIP = true;
18
21
  }
19
- window.EW_WT_DEBUG_TAG = WORLD_TEXTURE_DEBUG_TAG;
20
- if (window.DEBUG_TEXTURE_FLIP) {
22
+ (window as DebugWindow).EW_WT_DEBUG_TAG = WORLD_TEXTURE_DEBUG_TAG;
23
+ if ((window as DebugWindow).DEBUG_TEXTURE_FLIP) {
21
24
  console.info('[worldTexture] loaded', WORLD_TEXTURE_DEBUG_TAG);
22
25
  }
23
26
  }
24
27
 
25
28
  const WT_LOGGED_FIRST_CALL = false;
26
29
 
30
+ /** A loaded texture, compressed (KTX2) or not. */
31
+ type FlipTexture = THREE.Texture & { isCompressedTexture?: boolean };
32
+
27
33
  export const EARTH_RADIUS_UNITS = 0.5; // scene units
28
34
 
29
35
  /**
30
36
  * Simplified detection: width = height -> rectangular, width = 2×height -> equirectangular
31
37
  */
32
- function isLikelyEquirectangular(img) {
38
+ function isLikelyEquirectangular(img: { width: number; height: number }): boolean {
33
39
  const aspectRatio = img.width / img.height;
34
40
 
35
41
  // Check for 2:1 aspect ratio (equirectangular)
@@ -55,41 +61,16 @@ function isLikelyEquirectangular(img) {
55
61
  * geometry options are read only when they have their type; the rest are used as given (`glow`,
56
62
  * `cloudsEnabled` and `mirrorX` by truthiness).
57
63
  *
58
- * @param {object} [opts]
59
- * @param {string} [opts.textureUrl]
60
- * @param {import('three').WebGLRenderer | null} [opts.renderer] REQUIRED for a KTX2 texture.
61
- * @param {object} [opts.flags] material flags (`forceOpaque`, `wireframe`).
62
- * @param {number} [opts.uOffset] horizontal texture offset, 0..1 (wins over `textureOffsetDeg`).
63
- * @param {number} [opts.textureOffsetDeg] horizontal texture offset in degrees.
64
- * @param {boolean} [opts.mirrorX]
65
- * @param {boolean} [opts.mirrorDuplicateX] explicit override of the equirectangular detection.
66
- * @param {boolean} [opts.autoDetectEquirectangular=true]
67
- * @param {boolean} [opts.forceEquirectangular=false]
68
- * @param {boolean} [opts.forceRectangular=false]
69
- * @param {string} [opts.wrapS='repeat'] `'clamp'`, `'repeat'` or `'mirror'`.
70
- * @param {string} [opts.wrapT='clamp'] `'clamp'`, `'repeat'` or `'mirror'`.
71
- * @param {number} [opts.repeatX]
72
- * @param {number} [opts.repeatY]
73
- * @param {number} [opts.rotationDeg]
74
- * @param {number[]} [opts.center=[0.5, 0.5]] texture rotation centre, `[u, v]`.
75
- * @param {boolean} [opts.flipY]
76
- * @param {number} [opts.sphereRadius]
77
- * @param {number} [opts.sphereWidthSegments]
78
- * @param {number} [opts.sphereHeightSegments]
79
- * @param {number} [opts.materialRoughness] accepted from saved worlds; no longer changes the look.
80
- * @param {number} [opts.materialMetalness] accepted from saved worlds; no longer changes the look.
81
- * @param {boolean} [opts.glow=true]
82
- * @param {number} [opts.glowRimHex=0x66ccff]
83
- * @param {number} [opts.glowFacingHex=0x000000]
84
- * @param {number} [opts.glowScale=1.18]
85
- * @param {number} [opts.glowBias=0.02]
86
- * @param {number} [opts.glowFresnelScale=1]
87
- * @param {number} [opts.glowPower=3.5]
88
- * @param {boolean} [opts.cloudsEnabled=false]
89
- * @param {string} [opts.cloudsTextureUrl]
90
- * @param {number} [opts.cloudsColor=0xffffff]
91
- * @param {number} [opts.cloudsOpacity=0.6]
92
- * @param {number} [opts.cloudsSpeed=0.015]
64
+ * - `renderer`: REQUIRED for a KTX2 texture. `flags`: material flags (`forceOpaque`, `wireframe`).
65
+ * - `uOffset`: horizontal texture offset, 0..1 (wins over `textureOffsetDeg`, in degrees).
66
+ * - `mirrorDuplicateX`: explicit override of the equirectangular detection
67
+ * (`autoDetectEquirectangular` true, `forceEquirectangular` / `forceRectangular` false).
68
+ * - `wrapS` ('repeat') / `wrapT` ('clamp'): `'clamp'`, `'repeat'` or `'mirror'`.
69
+ * - `center` ([0.5, 0.5]): texture rotation centre, `[u, v]`.
70
+ * - `materialRoughness` / `materialMetalness`: accepted from saved worlds; no longer change the look.
71
+ * - Defaults: `glow` true, `glowRimHex` 0x66ccff, `glowFacingHex` 0x000000, `glowScale` 1.18,
72
+ * `glowBias` 0.02, `glowFresnelScale` 1, `glowPower` 3.5, `cloudsEnabled` false, `cloudsColor`
73
+ * 0xffffff, `cloudsOpacity` 0.6, `cloudsSpeed` 0.015.
93
74
  */
94
75
  export async function makeSphere({
95
76
  textureUrl,
@@ -131,10 +112,46 @@ export async function makeSphere({
131
112
  cloudsColor = 0xffffff,
132
113
  cloudsOpacity = 0.6,
133
114
  cloudsSpeed = 0.015,
115
+ }: {
116
+ textureUrl?: string | undefined;
117
+ renderer?: THREE.WebGLRenderer | null | undefined;
118
+ flags?: object | undefined;
119
+ uOffset?: number | undefined;
120
+ textureOffsetDeg?: number | undefined;
121
+ mirrorX?: boolean | undefined;
122
+ mirrorDuplicateX?: boolean | undefined;
123
+ autoDetectEquirectangular?: boolean | undefined;
124
+ forceEquirectangular?: boolean | undefined;
125
+ forceRectangular?: boolean | undefined;
126
+ wrapS?: string | undefined;
127
+ wrapT?: string | undefined;
128
+ repeatX?: number | undefined;
129
+ repeatY?: number | undefined;
130
+ rotationDeg?: number | undefined;
131
+ center?: number[] | undefined;
132
+ flipY?: boolean | undefined;
133
+ sphereRadius?: number | undefined;
134
+ sphereWidthSegments?: number | undefined;
135
+ sphereHeightSegments?: number | undefined;
136
+ materialRoughness?: number | undefined;
137
+ materialMetalness?: number | undefined;
138
+ glow?: boolean | undefined;
139
+ glowRimHex?: number | undefined;
140
+ glowFacingHex?: number | undefined;
141
+ glowScale?: number | undefined;
142
+ glowBias?: number | undefined;
143
+ glowFresnelScale?: number | undefined;
144
+ glowPower?: number | undefined;
145
+ cloudsEnabled?: boolean | undefined;
146
+ cloudsTextureUrl?: string | undefined;
147
+ cloudsColor?: number | undefined;
148
+ cloudsOpacity?: number | undefined;
149
+ cloudsSpeed?: number | undefined;
134
150
  } = {}) {
135
151
  const radius = typeof sphereRadius === 'number' ? Math.max(0.0001, sphereRadius) : EARTH_RADIUS_UNITS;
136
- const widthSegs = Number.isFinite(sphereWidthSegments) ? Math.max(3, Math.floor(sphereWidthSegments)) : 64;
137
- const heightSegs = Number.isFinite(sphereHeightSegments) ? Math.max(2, Math.floor(sphereHeightSegments)) : 64;
152
+ // `Number.isFinite` does not narrow: past it, each count is a number.
153
+ const widthSegs = Number.isFinite(sphereWidthSegments) ? Math.max(3, Math.floor(sphereWidthSegments as number)) : 64;
154
+ const heightSegs = Number.isFinite(sphereHeightSegments) ? Math.max(2, Math.floor(sphereHeightSegments as number)) : 64;
138
155
  const geometry = new THREE.SphereGeometry(radius, widthSegs, heightSegs);
139
156
  let meshGeometry = geometry; // may clone/flip UVs for compressed textures
140
157
 
@@ -143,7 +160,7 @@ export async function makeSphere({
143
160
  // `materialMetalness` stay accepted from saved worlds but no longer change the look.
144
161
  const material = new THREE.MeshLambertMaterial({ color: 0xffffff });
145
162
 
146
- const WRAP = {
163
+ const WRAP: Record<string, THREE.Wrapping> = {
147
164
  clamp: THREE.ClampToEdgeWrapping,
148
165
  repeat: THREE.RepeatWrapping,
149
166
  mirror: THREE.MirroredRepeatWrapping,
@@ -152,7 +169,7 @@ export async function makeSphere({
152
169
  // For compressed textures (e.g., KTX2) WebGL cannot apply UNPACK_FLIP_Y at upload.
153
170
  // To normalize orientation across loaders, emulate vertical flip in UV sampling:
154
171
  // v' = 1 - v => repeat.y = -repeat.y, offset.y = 1 - offset.y
155
- const normalizeCompressedFlip = (t) => {
172
+ const normalizeCompressedFlip = (t: FlipTexture) => {
156
173
  if (!t || !t.isCompressedTexture) return;
157
174
  const wantFlip = (typeof flipY === 'boolean') ? flipY : true; // match uncompressed default
158
175
  if (!wantFlip) return;
@@ -164,7 +181,7 @@ export async function makeSphere({
164
181
  };
165
182
 
166
183
  // Emulate vertical flip for compressed textures (e.g., KTX2) using UV transform
167
- const normalizeCompressedFlipY = (t, desired) => {
184
+ const normalizeCompressedFlipY = (t: FlipTexture, desired?: boolean) => {
168
185
  if (!t || !t.isCompressedTexture) return;
169
186
  const wantFlip = (typeof desired === 'boolean') ? desired : true; // default to match uncompressed loader
170
187
  const rY = t.repeat?.y ?? 1;
@@ -180,7 +197,7 @@ export async function makeSphere({
180
197
  };
181
198
 
182
199
  // Flip UV.y on a cloned geometry (keeps other layers safe)
183
- const flipGeometryUVY = (geom) => {
200
+ const flipGeometryUVY = (geom: THREE.BufferGeometry) => {
184
201
  if (!geom || !geom.attributes || !geom.attributes.uv) return 0;
185
202
  const uv = geom.attributes.uv;
186
203
  const arr = uv.array;
@@ -192,7 +209,7 @@ export async function makeSphere({
192
209
  };
193
210
 
194
211
  // Attach a Fresnel glow mesh as a child of the sphere mesh
195
- function createGlow(rimHex, facingHex) {
212
+ function createGlow(rimHex: number, facingHex: number) {
196
213
  const fresnelMat = getLightFresnel({ rimHex, facingHex });
197
214
  // tweak uniforms for stronger rim
198
215
  fresnelMat.uniforms.fresnelBias.value = glowBias;
@@ -218,13 +235,14 @@ export async function makeSphere({
218
235
  if (typeof flipY === 'boolean') tex.flipY = flipY;
219
236
 
220
237
  // Only enable mipmaps for non-compressed, power-of-two textures
221
- const isCompressed = tex.isCompressedTexture;
238
+ // A KTX2 load is a CompressedTexture, which says so; a plain Texture has no such field.
239
+ const isCompressed = (tex as Partial<THREE.CompressedTexture>).isCompressedTexture;
222
240
  const img = tex.image;
223
241
  const isPowerOfTwo = img && ((img.width & (img.width - 1)) === 0) && ((img.height & (img.height - 1)) === 0);
224
242
  tex.generateMipmaps = !isCompressed && isPowerOfTwo;
225
243
 
226
244
  // Decide mapping approach
227
- let shouldMirrorDuplicate = mirrorDuplicateX;
245
+ let shouldMirrorDuplicate: boolean | undefined = mirrorDuplicateX;
228
246
  if (tex.image) {
229
247
  const img = tex.image;
230
248
  let isEquirectangular = false;
@@ -255,7 +273,7 @@ export async function makeSphere({
255
273
  offsetX = (((textureOffsetDeg / 360) % 1) + 1) % 1;
256
274
  }
257
275
 
258
- const applyWrapOptions = (t) => {
276
+ const applyWrapOptions = (t: THREE.Texture) => {
259
277
  t.wrapS = WRAP[wrapS] ?? THREE.RepeatWrapping;
260
278
  t.wrapT = WRAP[wrapT] ?? THREE.ClampToEdgeWrapping;
261
279
  // Compressed textures + NPOT prefer clamp to avoid artifacts
@@ -286,7 +304,8 @@ export async function makeSphere({
286
304
  const canvas = document.createElement('canvas');
287
305
  canvas.width = img.width * 2;
288
306
  canvas.height = img.height;
289
- const ctx = canvas.getContext('2d');
307
+ // A missing 2D context throws on first use and lands in the fallback below, as before.
308
+ const ctx = canvas.getContext('2d') as CanvasRenderingContext2D;
290
309
 
291
310
  // Left half: original
292
311
  ctx.drawImage(img, 0, 0, img.width, img.height);
@@ -1,12 +0,0 @@
1
- /** @param {string | null | undefined} url */
2
- export function setPublicBase(url: string | null | undefined): void;
3
- /** @returns {string} */
4
- export function getPublicBase(): string;
5
- /**
6
- * @param {string} path root-relative, relative, or an absolute http(s) URL (returned unchanged).
7
- * An empty string comes back as is.
8
- * @returns {string}
9
- */
10
- export function resolvePublicUrl(path: string): string;
11
- /** @type {string | null} */
12
- export let __PUBLIC_BASE: string | null;
@@ -1,2 +0,0 @@
1
- export { loadTextureConfig, getTextureOptions, getTextureChoices, getDefaultTexture, getSkyboxOptions, getDefaultSkybox, getTextureFallbackUrl } from "./textureConfig.js";
2
- export { setPublicBase, getPublicBase, resolvePublicUrl } from "./env.js";
@@ -1,121 +0,0 @@
1
- /**
2
- * Load texture configuration from remote endpoint or use passed config
3
- * @param {string} configUrl - Override config URL
4
- * @param {boolean} useCache - Whether to use cached config if available
5
- * @returns {Promise<Object>} Texture configuration object
6
- */
7
- export function loadTextureConfig(configUrl?: string, useCache?: boolean): Promise<Object>;
8
- /**
9
- * @typedef {Object} TextureChoice
10
- * @property {string} id Catalogue id.
11
- * @property {string} label Human-readable name.
12
- * @property {string} url Resolved texture URL (the .ktx2 the world renders).
13
- * @property {string|null} still Resolved URL of the item's picture — a small thumbnail suitable
14
- * for showing the texture in a picker. `null` when the catalogue names none.
15
- *
16
- * Every catalogue item IS a picture, so a chooser should show it rather than its name. `still` is
17
- * read straight from the catalogue and never derived from `filename`: the stills do not share one
18
- * extension, and a wrong guess fails silently (a broken `<img>` just shows nothing).
19
- */
20
- /**
21
- * Get the full choice records for a category (clouds, moons, etc.) — label, texture URL, and the
22
- * picture to show for it. The single resolution point for a category's items; `getTextureOptions`
23
- * is the flat `{ label: url }` projection of this.
24
- * @param {string} category - Texture category (clouds, moons)
25
- * @param {Object} config - Optional pre-loaded config object
26
- * @returns {Promise<TextureChoice[]>} Choice records in catalogue order
27
- */
28
- export function getTextureChoices(category: string, config?: Object): Promise<TextureChoice[]>;
29
- /**
30
- * Get texture options for a specific category (clouds, moons, etc.)
31
- * @param {string} category - Texture category (clouds, moons, skyboxes)
32
- * @param {Object} config - Optional pre-loaded config object
33
- * @returns {Promise<Object>} Options object suitable for dropdown option lists
34
- */
35
- export function getTextureOptions(category: string, config?: Object): Promise<Object>;
36
- /**
37
- * Get default texture for a category
38
- * @param {string} category - Texture category
39
- * @param {Object} config - Optional pre-loaded config object
40
- * @returns {Promise<string>} Default texture path
41
- */
42
- export function getDefaultTexture(category: string, config?: Object): Promise<string>;
43
- /**
44
- * Return the configured fallback URL for a given texture if defined.
45
- * @param {string} category - Texture category (clouds, moons, etc.)
46
- * @param {string} textureUrl - Resolved texture URL
47
- * @param {Object|null} config - Optional texture config override
48
- * @returns {string|null} Resolved fallback texture URL or null
49
- */
50
- export function getTextureFallbackUrl(category: string, textureUrl: string, config?: Object | null): string | null;
51
- /**
52
- * Get texture by ID within a category
53
- * @param {string} category - Texture category
54
- * @param {string} textureId - Texture ID
55
- * @param {Object} config - Optional pre-loaded config object
56
- * @returns {Promise<Object|null>} Texture definition object
57
- */
58
- export function getTextureById(category: string, textureId: string, config?: Object): Promise<Object | null>;
59
- /**
60
- * Get full URL for a texture
61
- * @param {string} category - Texture category
62
- * @param {string} textureId - Texture ID
63
- * @param {Object} config - Optional pre-loaded config object
64
- * @returns {Promise<string|null>} Full texture URL
65
- */
66
- export function getTextureUrl(category: string, textureId: string, config?: Object): Promise<string | null>;
67
- /**
68
- * Search textures by tags
69
- * @param {string} category - Texture category
70
- * @param {string[]} tags - Tags to search for
71
- * @param {Object} config - Optional pre-loaded config object
72
- * @returns {Promise<Object[]>} Array of matching texture definitions
73
- */
74
- export function searchTexturesByTags(category: string, tags: string[], config?: Object): Promise<Object[]>;
75
- /**
76
- * Get skybox options formatted for GUI dropdowns
77
- * @param {Object} config - Optional pre-loaded config object
78
- * @returns {Promise<Object>} Options object with labels and IDs
79
- */
80
- export function getSkyboxOptions(config?: Object): Promise<Object>;
81
- /**
82
- * Get default skybox ID
83
- * @param {Object} config - Optional pre-loaded config object
84
- * @returns {Promise<string>} Default skybox ID
85
- */
86
- export function getDefaultSkybox(config?: Object): Promise<string>;
87
- /**
88
- * Reload configuration (force refresh)
89
- * @param {string} configUrl - Override config URL
90
- * @returns {Promise<Object>} Fresh configuration object
91
- */
92
- export function reloadTextureConfig(configUrl?: string): Promise<Object>;
93
- /**
94
- * Get configuration metadata
95
- * @param {Object} config - Optional pre-loaded config object
96
- * @returns {Promise<Object>} Configuration metadata
97
- */
98
- export function getConfigMetadata(config?: Object): Promise<Object>;
99
- export type TextureChoice = {
100
- /**
101
- * Catalogue id.
102
- */
103
- id: string;
104
- /**
105
- * Human-readable name.
106
- */
107
- label: string;
108
- /**
109
- * Resolved texture URL (the .ktx2 the world renders).
110
- */
111
- url: string;
112
- /**
113
- * Resolved URL of the item's picture — a small thumbnail suitable
114
- * for showing the texture in a picker. `null` when the catalogue names none.
115
- *
116
- * Every catalogue item IS a picture, so a chooser should show it rather than its name. `still` is
117
- * read straight from the catalogue and never derived from `filename`: the stills do not share one
118
- * extension, and a wrong guess fails silently (a broken `<img>` just shows nothing).
119
- */
120
- still: string | null;
121
- };
@@ -1,2 +0,0 @@
1
- export { getLightFresnel } from "./lightFresnel.js";
2
- export { ensureDefaultLights, updateDefaultLights, setHemisphereEnabled } from "./lights.js";
@@ -1,5 +0,0 @@
1
- export function getLightFresnel({ rimHex, facingHex }?: {
2
- rimHex?: number | undefined;
3
- facingHex?: number | undefined;
4
- }): THREE.ShaderMaterial;
5
- import * as THREE from "three";
@@ -1,58 +0,0 @@
1
- /**
2
- * Ensure a scene has the default hemisphere + ambient lights. Idempotent PER SCENE.
3
- *
4
- * A multi-orbiter realm renders N independent scenes through one renderer. A module-level
5
- * singleton light is wrong twice over — it's only added to the FIRST scene, and a THREE light can
6
- * live in just one scene (adding it to a second removes it from the first), so scenes 2..N rendered
7
- * DARK ("only one entangled world"). So create + add the lights PER scene, keyed by name so a
8
- * re-call on the same scene is a no-op. Single-orbiter (one scene) is unchanged.
9
- *
10
- * @param {import('three').Scene} scene
11
- * @returns {{ hemi: import('three').HemisphereLight, ambient: import('three').AmbientLight }}
12
- */
13
- export function ensureDefaultLights(scene: import("three").Scene): {
14
- hemi: import("three").HemisphereLight;
15
- ambient: import("three").AmbientLight;
16
- };
17
- /**
18
- * Apply a lighting patch to ONE scene's default lights.
19
- *
20
- * The scene is required. This used to address module-global light refs pointing at whichever scene
21
- * was ensured last, so on a page rendering several scenes every lighting update landed on one of
22
- * them — a shared-renderer page (N feed worlds, N orbiters) lit the wrong world.
23
- *
24
- * Every field is optional; an omitted one leaves that part of the lighting as it is.
25
- *
26
- * @param {import('three').Scene} scene
27
- * @param {object} [patch]
28
- * @param {number} [patch.ambientIntensity] ambient light intensity (clamped at 0)
29
- * @param {number} [patch.diffuseIntensity] hemisphere light intensity (clamped at 0)
30
- * @param {import('three').Color | number | string} [patch.lightColor] hemisphere light colour
31
- * @param {{ x: number, y?: number, z?: number }} [patch.lightDirection] hemisphere light direction
32
- * @param {boolean} [patch.hemisphere] switch the hemisphere light on or off
33
- */
34
- export function updateDefaultLights(scene: import("three").Scene, { ambientIntensity, diffuseIntensity, lightColor, lightDirection, hemisphere }?: {
35
- ambientIntensity?: number | undefined;
36
- diffuseIntensity?: number | undefined;
37
- lightColor?: string | number | THREE.Color | undefined;
38
- lightDirection?: {
39
- x: number;
40
- y?: number;
41
- z?: number;
42
- } | undefined;
43
- hemisphere?: boolean | undefined;
44
- }): void;
45
- /**
46
- * Switch a scene's default hemisphere light on or off (the ambient light is untouched). Hosts turn it
47
- * off when a directional light — the star — lights the scene, so night sides can read.
48
- *
49
- * @param {import('three').Scene} scene
50
- * @param {boolean} on
51
- */
52
- export function setHemisphereEnabled(scene: import("three").Scene, on: boolean): void;
53
- /** @param {import('three').Scene} scene */
54
- export function addDefaultLights(scene: import("three").Scene): {
55
- hemi: import("three").HemisphereLight;
56
- ambient: import("three").AmbientLight;
57
- };
58
- import * as THREE from 'three';
@@ -1,6 +0,0 @@
1
- export * from "./world/index.js";
2
- export * from "./moons/index.js";
3
- export * from "./loaders/index.js";
4
- export * from "./core/index.js";
5
- export * from "./config/index.js";
6
- export * from "./utils/index.js";