@threenative/core 0.3.4 → 0.3.6
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.
- package/capabilities.json +1505 -79
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12437 -4955
- package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
- package/dist/playtest.d.ts +6 -10
- package/dist/playtest.js +57 -24
- package/dist/react-css.d.ts +62 -0
- package/dist/react-css.js +591 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +766 -73
- package/dist/world.js +9307 -3543
- package/gpl/recipes/export_world.py +18 -1
- package/mcp/blender-server.mjs +7 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +2 -2
- package/mcp/servers.mjs +4 -4
- package/package.json +15 -9
- package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
- package/patches/three@0.185.1.patch +6594 -700
- package/scripts/apply-three-patch.mjs +62 -4
- package/src/animation-blend.ts +264 -0
- package/src/animation-composition.ts +362 -0
- package/src/animation-layers.ts +260 -0
- package/src/animation-root-motion.ts +283 -0
- package/src/animation.ts +896 -0
- package/src/assets.ts +1303 -0
- package/src/atmosphere/index.ts +335 -0
- package/src/atmosphere/luts.ts +298 -0
- package/src/atmosphere/params.ts +323 -0
- package/src/audio.ts +912 -0
- package/src/billboard.ts +124 -0
- package/src/bone-lengths.ts +157 -0
- package/src/camera-shake.ts +116 -0
- package/src/canvas-layer.ts +47 -0
- package/src/clip-audit.ts +401 -0
- package/src/clustered-batch.ts +492 -0
- package/src/clustered-mesh.ts +638 -0
- package/src/compute-driven.ts +176 -0
- package/src/compute-timing.ts +318 -0
- package/src/config.ts +593 -0
- package/src/debug.ts +82 -0
- package/src/engine-render-hook.ts +25 -0
- package/src/entities.ts +79 -0
- package/src/entity-snapshot.ts +53 -0
- package/src/flight.ts +683 -0
- package/src/fluid-field.ts +748 -0
- package/src/fluid-particles.ts +1253 -0
- package/src/frame-budget.ts +1368 -0
- package/src/game.ts +2408 -0
- package/src/geometry-capture.ts +1098 -0
- package/src/gpu-class.ts +160 -0
- package/src/gpu-frame-observation.ts +424 -0
- package/src/gpu-readback.ts +143 -0
- package/src/gpu-scene-bvh.ts +464 -0
- package/src/grounding.ts +100 -0
- package/src/hot.ts +161 -0
- package/src/import-meta.d.ts +13 -0
- package/src/index.ts +1536 -0
- package/src/input.ts +690 -0
- package/src/instanced-batch-lod.ts +283 -0
- package/src/instanced-batch.ts +274 -0
- package/src/interpolation.ts +129 -0
- package/src/launch-diagnostics.ts +161 -0
- package/src/loop.ts +574 -0
- package/src/matrix-world.ts +245 -0
- package/src/merge-parts.ts +812 -0
- package/src/model-lod.ts +1315 -0
- package/src/net-protocol.ts +333 -0
- package/src/net-session.ts +477 -0
- package/src/net.ts +80 -0
- package/src/ocean/fft.ts +72 -0
- package/src/ocean/spectral.ts +728 -0
- package/src/particle-significance.ts +102 -0
- package/src/particles.ts +648 -0
- package/src/path-follow.ts +175 -0
- package/src/picking.ts +250 -0
- package/src/pipeline-census.ts +1566 -0
- package/src/platform.ts +210 -0
- package/src/playtest.ts +850 -0
- package/src/pointer-events.ts +411 -0
- package/src/pose-measure.ts +435 -0
- package/src/profiling/FrameCounters.ts +231 -0
- package/src/profiling/Spans.ts +548 -0
- package/src/profiling/opacity-convention.ts +21 -0
- package/src/profiling/render-list-validate.ts +175 -0
- package/src/profiling/render-trap-audit.ts +84 -0
- package/src/profiling/scene-warning.ts +190 -0
- package/src/profiling/span-probes.ts +191 -0
- package/src/profiling/unlit-foliage-warning.ts +149 -0
- package/src/projection-apply.ts +1529 -0
- package/src/projection-marker.ts +142 -0
- package/src/projection-plan.ts +1258 -0
- package/src/projection-skinned.ts +419 -0
- package/src/projection-stability.ts +409 -0
- package/src/projection-uniform.ts +328 -0
- package/src/random.ts +41 -0
- package/src/react-css.ts +604 -0
- package/src/react-glyphs.ts +114 -0
- package/src/react-host.ts +576 -0
- package/src/react-layout.ts +265 -0
- package/src/react.ts +60 -0
- package/src/render/alpha-antialiasing.ts +159 -0
- package/src/render/batched-velocity.ts +126 -0
- package/src/render/chain.ts +1021 -0
- package/src/render/daylight.ts +189 -0
- package/src/render/depth-pyramid.ts +596 -0
- package/src/render/foliage-alpha.ts +166 -0
- package/src/render/material-key.ts +60 -0
- package/src/render/mesh-pool.ts +144 -0
- package/src/render/probe-volume.ts +1668 -0
- package/src/render/resolution-subrect.ts +253 -0
- package/src/render/velocity.ts +442 -0
- package/src/render/virtual-shadow-pages.ts +827 -0
- package/src/render/virtual-shadow-partial.ts +174 -0
- package/src/render/virtual-shadow.ts +3330 -0
- package/src/render/world-impostor-surface.ts +722 -0
- package/src/render/world-impostor.ts +558 -0
- package/src/render-camera-cull.ts +441 -0
- package/src/render-pass-budget.ts +501 -0
- package/src/renderProjection.ts +758 -0
- package/src/renderer-config.ts +127 -0
- package/src/renderer.ts +1847 -0
- package/src/replay-protocol.ts +85 -0
- package/src/replay.ts +205 -0
- package/src/resolution-scaler.ts +819 -0
- package/src/rig-preparation.ts +271 -0
- package/src/ripple-field.ts +432 -0
- package/src/scale.ts +109 -0
- package/src/scene.ts +239 -0
- package/src/schedule.ts +155 -0
- package/src/skeletal-mesh.ts +61 -0
- package/src/skeleton.ts +100 -0
- package/src/snow-field.ts +744 -0
- package/src/softbody-topology.ts +269 -0
- package/src/softbody.ts +516 -0
- package/src/sprite-animator.ts +222 -0
- package/src/startup-readiness.ts +386 -0
- package/src/state.ts +66 -0
- package/src/static-transform.ts +274 -0
- package/src/storage-buffer.ts +253 -0
- package/src/streaming.ts +308 -0
- package/src/target-fps.ts +92 -0
- package/src/terrain-jobs-worker.ts +17 -0
- package/src/terrain-jobs.ts +353 -0
- package/src/textures.ts +39 -0
- package/src/tracers.ts +237 -0
- package/src/ui-bridge.ts +368 -0
- package/src/ui-hit-regions.ts +380 -0
- package/src/ui-layer.ts +83 -0
- package/src/ui-state.ts +220 -0
- package/src/version.ts +2 -0
- package/src/viewport.ts +253 -0
- package/src/warmup.ts +1357 -0
- package/src/water-surface.ts +384 -0
- package/src/wave-field.ts +524 -0
- package/src/world-capabilities.ts +131 -0
- package/src/world-cell-proxy.ts +392 -0
- package/src/world-cells.ts +10564 -0
- package/src/world-gpu-scene.ts +3354 -0
- package/src/world-heightmap.ts +82 -0
- package/src/world-package.ts +469 -0
- package/src/world-passes.ts +582 -0
- package/src/world-region.ts +17 -0
- package/src/world-terrain-splat.ts +564 -0
- package/src/world-tiles.ts +3826 -0
- package/src/world-topology.ts +370 -0
- package/src/world-validate.ts +48 -0
- package/src/world.ts +805 -0
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
import { Vector3 } from "three";
|
|
2
|
+
|
|
3
|
+
export type AtmosphereRgb = readonly [number, number, number];
|
|
4
|
+
export type AtmosphereVector =
|
|
5
|
+
| AtmosphereRgb
|
|
6
|
+
| Readonly<{ x: number; y: number; z: number }>
|
|
7
|
+
| Vector3;
|
|
8
|
+
|
|
9
|
+
/** Physical inputs for the atmosphere model. Coefficients use 1/km and radii use km. */
|
|
10
|
+
export interface IAtmosphereParameters {
|
|
11
|
+
readonly rayleigh: AtmosphereVector;
|
|
12
|
+
readonly mie: AtmosphereVector;
|
|
13
|
+
readonly ozone: AtmosphereVector;
|
|
14
|
+
readonly planetRadius: number;
|
|
15
|
+
readonly atmosphereRadius: number;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export interface IResolvedAtmosphereParameters {
|
|
19
|
+
readonly rayleigh: Vector3;
|
|
20
|
+
readonly mie: Vector3;
|
|
21
|
+
readonly ozone: Vector3;
|
|
22
|
+
readonly planetRadius: number;
|
|
23
|
+
readonly atmosphereRadius: number;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export type IAtmosphereParameterPatch = Partial<IAtmosphereParameters>;
|
|
27
|
+
|
|
28
|
+
export interface ISolarPositionInput {
|
|
29
|
+
readonly date?: Date | string;
|
|
30
|
+
readonly dayOfYear?: number;
|
|
31
|
+
readonly timeOfDay?: number;
|
|
32
|
+
readonly latitude: number;
|
|
33
|
+
readonly longitude: number;
|
|
34
|
+
/** UTC offset in hours. Use zero when `date` is already UTC. */
|
|
35
|
+
readonly utcOffset?: number;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export interface ISolarPosition {
|
|
39
|
+
elevation: number;
|
|
40
|
+
azimuth: number;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
const RAYLEIGH_SCALE_HEIGHT_KM = 8;
|
|
44
|
+
const MIE_SCALE_HEIGHT_KM = 1.2;
|
|
45
|
+
const OZONE_START_KM = 10;
|
|
46
|
+
const OZONE_PEAK_KM = 25;
|
|
47
|
+
const OZONE_END_KM = 40;
|
|
48
|
+
const TAU = Math.PI * 2;
|
|
49
|
+
|
|
50
|
+
function missingParameter(options: unknown, field: keyof IAtmosphereParameters): never {
|
|
51
|
+
if (options === null || typeof options !== "object")
|
|
52
|
+
throw new Error("Atmosphere parameters are required.");
|
|
53
|
+
if (!Object.hasOwn(options, field)) throw new Error(`Atmosphere.${field} is required.`);
|
|
54
|
+
throw new Error(`Atmosphere.${field} must be valid.`);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function vectorValue(value: unknown, field: keyof IAtmosphereParameters): Vector3 {
|
|
58
|
+
if (value instanceof Vector3) return value.clone();
|
|
59
|
+
if (Array.isArray(value) && value.length === 3) {
|
|
60
|
+
const [x, y, z] = value;
|
|
61
|
+
if ([x, y, z].every((component) => typeof component === "number")) return new Vector3(x, y, z);
|
|
62
|
+
}
|
|
63
|
+
if (value !== null && typeof value === "object") {
|
|
64
|
+
const vector = value as { x?: unknown; y?: unknown; z?: unknown };
|
|
65
|
+
if ([vector.x, vector.y, vector.z].every((component) => typeof component === "number"))
|
|
66
|
+
return new Vector3(vector.x as number, vector.y as number, vector.z as number);
|
|
67
|
+
}
|
|
68
|
+
throw new Error(`Atmosphere.${field} must be an RGB vector.`);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function finiteNonNegativeVector(value: Vector3, field: keyof IAtmosphereParameters): Vector3 {
|
|
72
|
+
if (![value.x, value.y, value.z].every((component) => Number.isFinite(component)))
|
|
73
|
+
throw new Error(`Atmosphere.${field} must contain finite numbers.`);
|
|
74
|
+
if ([value.x, value.y, value.z].some((component) => component < 0))
|
|
75
|
+
throw new Error(`Atmosphere.${field} must contain non-negative numbers.`);
|
|
76
|
+
return value;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
function finitePositive(value: unknown, field: keyof IAtmosphereParameters): number {
|
|
80
|
+
if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
|
|
81
|
+
throw new Error(`Atmosphere.${field} must be a finite positive number.`);
|
|
82
|
+
return value;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Validate and clone game-owned coefficients. There is intentionally no Earth fallback.
|
|
86
|
+
* @situation validate atmosphere coefficients before a game creates its sky
|
|
87
|
+
* @constraint provide all three coefficient vectors and both radii; omitted fields are errors
|
|
88
|
+
* @example const parameters = resolveAtmosphereParameters({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
|
|
89
|
+
*/
|
|
90
|
+
export function resolveAtmosphereParameters(
|
|
91
|
+
options: IAtmosphereParameters,
|
|
92
|
+
): IResolvedAtmosphereParameters {
|
|
93
|
+
const input: Record<string, unknown> = { ...options };
|
|
94
|
+
for (const field of ["rayleigh", "mie", "ozone", "planetRadius", "atmosphereRadius"] as const) {
|
|
95
|
+
if (!Object.hasOwn(input, field)) missingParameter(options, field);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
const rayleigh = finiteNonNegativeVector(vectorValue(input.rayleigh, "rayleigh"), "rayleigh");
|
|
99
|
+
const mie = finiteNonNegativeVector(vectorValue(input.mie, "mie"), "mie");
|
|
100
|
+
const ozone = finiteNonNegativeVector(vectorValue(input.ozone, "ozone"), "ozone");
|
|
101
|
+
const planetRadius = finitePositive(input.planetRadius, "planetRadius");
|
|
102
|
+
const atmosphereRadius = finitePositive(input.atmosphereRadius, "atmosphereRadius");
|
|
103
|
+
if (atmosphereRadius <= planetRadius)
|
|
104
|
+
throw new Error("Atmosphere.atmosphereRadius must be greater than planetRadius.");
|
|
105
|
+
|
|
106
|
+
return { atmosphereRadius, mie, ozone, planetRadius, rayleigh };
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** Apply a partial game-owned atmosphere change while preserving validation.
|
|
110
|
+
* @situation change scattering coefficients and rebake an atmosphere
|
|
111
|
+
* @constraint patches cannot introduce omitted, negative, or non-finite physical values
|
|
112
|
+
* @example atmosphere.setAtmosphere({ rayleigh: [0.008, 0.016, 0.04] });
|
|
113
|
+
*/
|
|
114
|
+
export function updateAtmosphereParameters(
|
|
115
|
+
current: IResolvedAtmosphereParameters,
|
|
116
|
+
patch: IAtmosphereParameterPatch,
|
|
117
|
+
): IResolvedAtmosphereParameters {
|
|
118
|
+
return resolveAtmosphereParameters({
|
|
119
|
+
atmosphereRadius:
|
|
120
|
+
patch.atmosphereRadius === undefined ? current.atmosphereRadius : patch.atmosphereRadius,
|
|
121
|
+
mie: patch.mie === undefined ? current.mie : patch.mie,
|
|
122
|
+
ozone: patch.ozone === undefined ? current.ozone : patch.ozone,
|
|
123
|
+
planetRadius: patch.planetRadius === undefined ? current.planetRadius : patch.planetRadius,
|
|
124
|
+
rayleigh: patch.rayleigh === undefined ? current.rayleigh : patch.rayleigh,
|
|
125
|
+
});
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
function exponentialColumn(scaleHeight: number, thickness: number): number {
|
|
129
|
+
return scaleHeight * (1 - Math.exp(-thickness / scaleHeight));
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
function ozoneColumn(thickness: number): number {
|
|
133
|
+
const lower = Math.max(0, Math.min(thickness, OZONE_END_KM) - OZONE_START_KM);
|
|
134
|
+
if (lower <= 0) return 0;
|
|
135
|
+
if (thickness <= OZONE_PEAK_KM) return (lower * lower) / (2 * (OZONE_PEAK_KM - OZONE_START_KM));
|
|
136
|
+
const rising = (OZONE_PEAK_KM - OZONE_START_KM) / 2;
|
|
137
|
+
const fallingWidth = Math.min(thickness, OZONE_END_KM) - OZONE_PEAK_KM;
|
|
138
|
+
return (
|
|
139
|
+
rising + fallingWidth - (fallingWidth * fallingWidth) / (2 * (OZONE_END_KM - OZONE_PEAK_KM))
|
|
140
|
+
);
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/**
|
|
144
|
+
* Return the direct vertical transmittance of the supplied atmosphere.
|
|
145
|
+
*
|
|
146
|
+
* The coefficient fixture follows the Hillaire/Bruneton Earth model: an exponential Rayleigh
|
|
147
|
+
* column, an exponential aerosol column, and the triangular ozone column. This CPU value is a
|
|
148
|
+
* small validation oracle for the same coefficients that the GPU LUT kernels consume.
|
|
149
|
+
* @situation check a supplied atmosphere's direct vertical transmittance
|
|
150
|
+
* @constraint use the returned value as a validation oracle; the rendered path samples the LUT
|
|
151
|
+
* @example const zenith = zenithTransmittance({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
|
|
152
|
+
*/
|
|
153
|
+
export function zenithTransmittance(
|
|
154
|
+
parameters: IAtmosphereParameters | IResolvedAtmosphereParameters,
|
|
155
|
+
): AtmosphereRgb {
|
|
156
|
+
const resolved = resolveAtmosphereParameters(parameters);
|
|
157
|
+
const thickness = resolved.atmosphereRadius - resolved.planetRadius;
|
|
158
|
+
const rayleighColumn = exponentialColumn(RAYLEIGH_SCALE_HEIGHT_KM, thickness);
|
|
159
|
+
const mieColumn = exponentialColumn(MIE_SCALE_HEIGHT_KM, thickness);
|
|
160
|
+
const ozoneColumnKm = ozoneColumn(thickness);
|
|
161
|
+
return [
|
|
162
|
+
Math.exp(
|
|
163
|
+
-resolved.rayleigh.x * rayleighColumn -
|
|
164
|
+
resolved.mie.x * mieColumn -
|
|
165
|
+
resolved.ozone.x * ozoneColumnKm,
|
|
166
|
+
),
|
|
167
|
+
Math.exp(
|
|
168
|
+
-resolved.rayleigh.y * rayleighColumn -
|
|
169
|
+
resolved.mie.y * mieColumn -
|
|
170
|
+
resolved.ozone.y * ozoneColumnKm,
|
|
171
|
+
),
|
|
172
|
+
Math.exp(
|
|
173
|
+
-resolved.rayleigh.z * rayleighColumn -
|
|
174
|
+
resolved.mie.z * mieColumn -
|
|
175
|
+
resolved.ozone.z * ozoneColumnKm,
|
|
176
|
+
),
|
|
177
|
+
];
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/** Approximate direct transmittance for a ray leaving the ground in a supplied direction.
|
|
181
|
+
* @situation colour a game-owned sun from atmosphere extinction
|
|
182
|
+
* @constraint pass a non-zero direction; coefficients and radii come from the game
|
|
183
|
+
* @example const transmittance = directionalTransmittance(parameters, sunDirection);
|
|
184
|
+
*/
|
|
185
|
+
export function directionalTransmittance(
|
|
186
|
+
parameters: IAtmosphereParameters | IResolvedAtmosphereParameters,
|
|
187
|
+
direction: Vector3,
|
|
188
|
+
): Vector3 {
|
|
189
|
+
const lengthSquared = direction.lengthSq();
|
|
190
|
+
if (!Number.isFinite(lengthSquared) || lengthSquared === 0)
|
|
191
|
+
throw new Error("Atmosphere direction must be finite and non-zero.");
|
|
192
|
+
const normal = direction.clone().normalize();
|
|
193
|
+
const cosine = Math.max(0.05, normal.y);
|
|
194
|
+
const airMass = 1 / cosine;
|
|
195
|
+
const zenith = zenithTransmittance(parameters);
|
|
196
|
+
return new Vector3(zenith[0] ** airMass, zenith[1] ** airMass, zenith[2] ** airMass);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
function checkedSolarInput(input: ISolarPositionInput): ISolarPositionInput {
|
|
200
|
+
if (!Number.isFinite(input.latitude) || input.latitude < -90 || input.latitude > 90)
|
|
201
|
+
throw new Error("solarPosition.latitude must be between -90 and 90 degrees.");
|
|
202
|
+
if (!Number.isFinite(input.longitude) || input.longitude < -180 || input.longitude > 180)
|
|
203
|
+
throw new Error("solarPosition.longitude must be between -180 and 180 degrees.");
|
|
204
|
+
if (
|
|
205
|
+
input.utcOffset !== undefined &&
|
|
206
|
+
(!Number.isFinite(input.utcOffset) || Math.abs(input.utcOffset) > 24)
|
|
207
|
+
)
|
|
208
|
+
throw new Error("solarPosition.utcOffset must be finite and within 24 hours.");
|
|
209
|
+
return input;
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
function calculateSolarPosition(
|
|
213
|
+
input: ISolarPositionInput,
|
|
214
|
+
target?: ISolarPosition,
|
|
215
|
+
): ISolarPosition {
|
|
216
|
+
const checked = checkedSolarInput(input);
|
|
217
|
+
let dayOfYear: number;
|
|
218
|
+
let timeOfDay: number;
|
|
219
|
+
let utcOffset: number;
|
|
220
|
+
if (checked.date !== undefined) {
|
|
221
|
+
const date =
|
|
222
|
+
checked.date instanceof Date ? new Date(checked.date.getTime()) : new Date(checked.date);
|
|
223
|
+
if (!Number.isFinite(date.getTime())) throw new Error("solarPosition.date must be valid.");
|
|
224
|
+
const yearStart = Date.UTC(date.getUTCFullYear(), 0, 0);
|
|
225
|
+
dayOfYear = Math.floor((date.getTime() - yearStart) / 86_400_000);
|
|
226
|
+
timeOfDay =
|
|
227
|
+
date.getUTCHours() +
|
|
228
|
+
date.getUTCMinutes() / 60 +
|
|
229
|
+
date.getUTCSeconds() / 3600 +
|
|
230
|
+
date.getUTCMilliseconds() / 3_600_000;
|
|
231
|
+
utcOffset = checked.utcOffset ?? 0;
|
|
232
|
+
} else {
|
|
233
|
+
if (checked.dayOfYear === undefined || checked.timeOfDay === undefined)
|
|
234
|
+
throw new Error("solarPosition requires date or dayOfYear and timeOfDay.");
|
|
235
|
+
if (!Number.isFinite(checked.dayOfYear) || !Number.isFinite(checked.timeOfDay))
|
|
236
|
+
throw new Error("solarPosition dayOfYear and timeOfDay must be finite.");
|
|
237
|
+
dayOfYear = checked.dayOfYear;
|
|
238
|
+
timeOfDay = checked.timeOfDay;
|
|
239
|
+
utcOffset = checked.utcOffset ?? 0;
|
|
240
|
+
}
|
|
241
|
+
const gamma = (TAU / 365) * (dayOfYear - 1 + (timeOfDay - 12) / 24);
|
|
242
|
+
const equationOfTime =
|
|
243
|
+
229.18 *
|
|
244
|
+
(0.000075 +
|
|
245
|
+
0.001868 * Math.cos(gamma) -
|
|
246
|
+
0.032077 * Math.sin(gamma) -
|
|
247
|
+
0.014615 * Math.cos(2 * gamma) -
|
|
248
|
+
0.040849 * Math.sin(2 * gamma));
|
|
249
|
+
const declination =
|
|
250
|
+
0.006918 -
|
|
251
|
+
0.399912 * Math.cos(gamma) +
|
|
252
|
+
0.070257 * Math.sin(gamma) -
|
|
253
|
+
0.006758 * Math.cos(2 * gamma) +
|
|
254
|
+
0.000907 * Math.sin(2 * gamma) -
|
|
255
|
+
0.002697 * Math.cos(3 * gamma) +
|
|
256
|
+
0.00148 * Math.sin(3 * gamma);
|
|
257
|
+
// The NOAA equation uses the conventional signed timezone directly (Vancouver is -8).
|
|
258
|
+
const trueSolarMinutes = timeOfDay * 60 + equationOfTime + 4 * checked.longitude - 60 * utcOffset;
|
|
259
|
+
const hourAngle = ((((trueSolarMinutes / 4 - 180) % 360) + 540) % 360) - 180;
|
|
260
|
+
const latitude = (checked.latitude * Math.PI) / 180;
|
|
261
|
+
const cosineZenith =
|
|
262
|
+
Math.sin(latitude) * Math.sin(declination) +
|
|
263
|
+
Math.cos(latitude) * Math.cos(declination) * Math.cos((hourAngle * Math.PI) / 180);
|
|
264
|
+
const elevation = 90 - (Math.acos(Math.max(-1, Math.min(1, cosineZenith))) * 180) / Math.PI;
|
|
265
|
+
const azimuth =
|
|
266
|
+
(Math.atan2(
|
|
267
|
+
Math.sin((hourAngle * Math.PI) / 180),
|
|
268
|
+
Math.cos((hourAngle * Math.PI) / 180) * Math.sin(latitude) -
|
|
269
|
+
Math.tan(declination) * Math.cos(latitude),
|
|
270
|
+
) *
|
|
271
|
+
180) /
|
|
272
|
+
Math.PI +
|
|
273
|
+
180;
|
|
274
|
+
const result = target ?? { azimuth: 0, elevation: 0 };
|
|
275
|
+
result.azimuth = (azimuth + 360) % 360;
|
|
276
|
+
result.elevation = elevation;
|
|
277
|
+
return result;
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/** Calculate solar elevation and azimuth from time, latitude, and longitude.
|
|
281
|
+
* @situation move a sun across a real day at a game's latitude and longitude
|
|
282
|
+
* @situation run a day and night cycle over the game's sky
|
|
283
|
+
* @constraint dates are interpreted as UTC unless utcOffset is supplied; no fixed sun direction is assumed
|
|
284
|
+
* @constraint pass a mutable { azimuth, elevation } target to reuse the result object in a steady frame loop
|
|
285
|
+
* @example const sun = solarPosition({ date, latitude: 49.28, longitude: -123.12, utcOffset: -8 });
|
|
286
|
+
*/
|
|
287
|
+
export function solarPosition(input: ISolarPositionInput, target?: ISolarPosition): ISolarPosition;
|
|
288
|
+
export function solarPosition(
|
|
289
|
+
date: Date | string,
|
|
290
|
+
latitude: number,
|
|
291
|
+
longitude: number,
|
|
292
|
+
target?: ISolarPosition,
|
|
293
|
+
): ISolarPosition;
|
|
294
|
+
export function solarPosition(
|
|
295
|
+
inputOrDate: ISolarPositionInput | Date | string,
|
|
296
|
+
latitude?: number | ISolarPosition,
|
|
297
|
+
longitude?: number,
|
|
298
|
+
target?: ISolarPosition,
|
|
299
|
+
): ISolarPosition {
|
|
300
|
+
if (inputOrDate instanceof Date || typeof inputOrDate === "string") {
|
|
301
|
+
if (typeof latitude !== "number" || longitude === undefined)
|
|
302
|
+
throw new Error("solarPosition positional form requires date, latitude, and longitude.");
|
|
303
|
+
return calculateSolarPosition({ date: inputOrDate, latitude, longitude }, target);
|
|
304
|
+
}
|
|
305
|
+
return calculateSolarPosition(inputOrDate, typeof latitude === "object" ? latitude : target);
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/** Convert solar elevation and azimuth degrees into a normalized Three.js direction.
|
|
309
|
+
* @situation aim a template's sun from solarPosition output
|
|
310
|
+
* @constraint elevation and azimuth must be finite degrees
|
|
311
|
+
* @example const direction = directionFromSolarPosition(sun.elevation, sun.azimuth);
|
|
312
|
+
*/
|
|
313
|
+
export function directionFromSolarPosition(elevation: number, azimuth: number): Vector3 {
|
|
314
|
+
if (![elevation, azimuth].every((value) => Number.isFinite(value)))
|
|
315
|
+
throw new Error("solarPosition elevation and azimuth must be finite.");
|
|
316
|
+
const elevationRadians = (elevation * Math.PI) / 180;
|
|
317
|
+
const azimuthRadians = (azimuth * Math.PI) / 180;
|
|
318
|
+
return new Vector3(
|
|
319
|
+
Math.cos(elevationRadians) * Math.sin(azimuthRadians),
|
|
320
|
+
Math.sin(elevationRadians),
|
|
321
|
+
Math.cos(elevationRadians) * Math.cos(azimuthRadians),
|
|
322
|
+
).normalize();
|
|
323
|
+
}
|