@threenative/core 0.3.4 → 0.3.5

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 (176) hide show
  1. package/capabilities.json +1505 -79
  2. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  3. package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  4. package/dist/{game-CljaDv4D.d.ts → game-Bj8G1wmD.d.ts} +102 -11
  5. package/dist/hot.d.ts +4 -4
  6. package/dist/index.d.ts +712 -118
  7. package/dist/index.js +12423 -4955
  8. package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
  9. package/dist/playtest.d.ts +6 -10
  10. package/dist/playtest.js +47 -24
  11. package/dist/react-css.d.ts +62 -0
  12. package/dist/react-css.js +591 -0
  13. package/dist/react.d.ts +2 -2
  14. package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
  15. package/dist/terrain-jobs-worker.d.ts +2 -0
  16. package/dist/terrain-jobs-worker.js +130 -0
  17. package/dist/ui-layer.js +59 -8
  18. package/dist/world.d.ts +766 -73
  19. package/dist/world.js +9307 -3543
  20. package/gpl/recipes/export_world.py +18 -1
  21. package/mcp/blender-server.mjs +7 -4
  22. package/mcp/blender.mjs +3 -4
  23. package/mcp/engine-server.mjs +2 -2
  24. package/mcp/servers.mjs +4 -4
  25. package/package.json +15 -9
  26. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  27. package/patches/three@0.185.1.patch +6594 -700
  28. package/scripts/apply-three-patch.mjs +62 -4
  29. package/src/animation-blend.ts +264 -0
  30. package/src/animation-composition.ts +362 -0
  31. package/src/animation-layers.ts +260 -0
  32. package/src/animation-root-motion.ts +283 -0
  33. package/src/animation.ts +896 -0
  34. package/src/assets.ts +1303 -0
  35. package/src/atmosphere/index.ts +335 -0
  36. package/src/atmosphere/luts.ts +298 -0
  37. package/src/atmosphere/params.ts +323 -0
  38. package/src/audio.ts +912 -0
  39. package/src/billboard.ts +124 -0
  40. package/src/bone-lengths.ts +157 -0
  41. package/src/camera-shake.ts +116 -0
  42. package/src/canvas-layer.ts +47 -0
  43. package/src/clip-audit.ts +401 -0
  44. package/src/clustered-batch.ts +492 -0
  45. package/src/clustered-mesh.ts +638 -0
  46. package/src/compute-driven.ts +176 -0
  47. package/src/compute-timing.ts +318 -0
  48. package/src/config.ts +593 -0
  49. package/src/debug.ts +82 -0
  50. package/src/engine-render-hook.ts +25 -0
  51. package/src/entities.ts +79 -0
  52. package/src/entity-snapshot.ts +53 -0
  53. package/src/flight.ts +683 -0
  54. package/src/fluid-field.ts +748 -0
  55. package/src/fluid-particles.ts +1253 -0
  56. package/src/frame-budget.ts +1368 -0
  57. package/src/game.ts +2390 -0
  58. package/src/geometry-capture.ts +1098 -0
  59. package/src/gpu-class.ts +160 -0
  60. package/src/gpu-frame-observation.ts +424 -0
  61. package/src/gpu-readback.ts +143 -0
  62. package/src/gpu-scene-bvh.ts +464 -0
  63. package/src/grounding.ts +100 -0
  64. package/src/hot.ts +161 -0
  65. package/src/import-meta.d.ts +13 -0
  66. package/src/index.ts +1536 -0
  67. package/src/input.ts +690 -0
  68. package/src/instanced-batch-lod.ts +283 -0
  69. package/src/instanced-batch.ts +274 -0
  70. package/src/interpolation.ts +129 -0
  71. package/src/launch-diagnostics.ts +161 -0
  72. package/src/loop.ts +564 -0
  73. package/src/matrix-world.ts +245 -0
  74. package/src/merge-parts.ts +812 -0
  75. package/src/model-lod.ts +1315 -0
  76. package/src/net-protocol.ts +333 -0
  77. package/src/net-session.ts +477 -0
  78. package/src/net.ts +80 -0
  79. package/src/ocean/fft.ts +72 -0
  80. package/src/ocean/spectral.ts +728 -0
  81. package/src/particle-significance.ts +102 -0
  82. package/src/particles.ts +648 -0
  83. package/src/path-follow.ts +175 -0
  84. package/src/picking.ts +250 -0
  85. package/src/pipeline-census.ts +1566 -0
  86. package/src/platform.ts +210 -0
  87. package/src/playtest.ts +839 -0
  88. package/src/pointer-events.ts +411 -0
  89. package/src/pose-measure.ts +435 -0
  90. package/src/profiling/FrameCounters.ts +231 -0
  91. package/src/profiling/Spans.ts +548 -0
  92. package/src/profiling/opacity-convention.ts +21 -0
  93. package/src/profiling/render-list-validate.ts +175 -0
  94. package/src/profiling/render-trap-audit.ts +84 -0
  95. package/src/profiling/scene-warning.ts +190 -0
  96. package/src/profiling/span-probes.ts +191 -0
  97. package/src/profiling/unlit-foliage-warning.ts +149 -0
  98. package/src/projection-apply.ts +1529 -0
  99. package/src/projection-marker.ts +142 -0
  100. package/src/projection-plan.ts +1258 -0
  101. package/src/projection-skinned.ts +419 -0
  102. package/src/projection-stability.ts +409 -0
  103. package/src/projection-uniform.ts +328 -0
  104. package/src/random.ts +41 -0
  105. package/src/react-css.ts +604 -0
  106. package/src/react-glyphs.ts +114 -0
  107. package/src/react-host.ts +576 -0
  108. package/src/react-layout.ts +265 -0
  109. package/src/react.ts +60 -0
  110. package/src/render/alpha-antialiasing.ts +159 -0
  111. package/src/render/batched-velocity.ts +126 -0
  112. package/src/render/chain.ts +1021 -0
  113. package/src/render/daylight.ts +189 -0
  114. package/src/render/depth-pyramid.ts +596 -0
  115. package/src/render/foliage-alpha.ts +166 -0
  116. package/src/render/material-key.ts +60 -0
  117. package/src/render/mesh-pool.ts +144 -0
  118. package/src/render/probe-volume.ts +1668 -0
  119. package/src/render/resolution-subrect.ts +253 -0
  120. package/src/render/velocity.ts +442 -0
  121. package/src/render/virtual-shadow-pages.ts +827 -0
  122. package/src/render/virtual-shadow-partial.ts +174 -0
  123. package/src/render/virtual-shadow.ts +3330 -0
  124. package/src/render/world-impostor-surface.ts +722 -0
  125. package/src/render/world-impostor.ts +558 -0
  126. package/src/render-camera-cull.ts +441 -0
  127. package/src/render-pass-budget.ts +501 -0
  128. package/src/renderProjection.ts +758 -0
  129. package/src/renderer-config.ts +127 -0
  130. package/src/renderer.ts +1847 -0
  131. package/src/replay-protocol.ts +85 -0
  132. package/src/replay.ts +205 -0
  133. package/src/resolution-scaler.ts +819 -0
  134. package/src/rig-preparation.ts +271 -0
  135. package/src/ripple-field.ts +432 -0
  136. package/src/scale.ts +109 -0
  137. package/src/scene.ts +239 -0
  138. package/src/schedule.ts +155 -0
  139. package/src/skeletal-mesh.ts +61 -0
  140. package/src/skeleton.ts +100 -0
  141. package/src/snow-field.ts +744 -0
  142. package/src/softbody-topology.ts +269 -0
  143. package/src/softbody.ts +516 -0
  144. package/src/sprite-animator.ts +222 -0
  145. package/src/startup-readiness.ts +386 -0
  146. package/src/state.ts +66 -0
  147. package/src/static-transform.ts +274 -0
  148. package/src/storage-buffer.ts +253 -0
  149. package/src/streaming.ts +308 -0
  150. package/src/target-fps.ts +92 -0
  151. package/src/terrain-jobs-worker.ts +17 -0
  152. package/src/terrain-jobs.ts +353 -0
  153. package/src/textures.ts +39 -0
  154. package/src/tracers.ts +237 -0
  155. package/src/ui-bridge.ts +368 -0
  156. package/src/ui-hit-regions.ts +380 -0
  157. package/src/ui-layer.ts +83 -0
  158. package/src/ui-state.ts +220 -0
  159. package/src/version.ts +2 -0
  160. package/src/viewport.ts +253 -0
  161. package/src/warmup.ts +1357 -0
  162. package/src/water-surface.ts +384 -0
  163. package/src/wave-field.ts +524 -0
  164. package/src/world-capabilities.ts +131 -0
  165. package/src/world-cell-proxy.ts +392 -0
  166. package/src/world-cells.ts +10564 -0
  167. package/src/world-gpu-scene.ts +3354 -0
  168. package/src/world-heightmap.ts +82 -0
  169. package/src/world-package.ts +469 -0
  170. package/src/world-passes.ts +582 -0
  171. package/src/world-region.ts +17 -0
  172. package/src/world-terrain-splat.ts +564 -0
  173. package/src/world-tiles.ts +3826 -0
  174. package/src/world-topology.ts +370 -0
  175. package/src/world-validate.ts +48 -0
  176. package/src/world.ts +805 -0
package/src/flight.ts ADDED
@@ -0,0 +1,683 @@
1
+ /**
2
+ * Force-integrated fixed-wing flight dynamics for a game-owned aircraft.
3
+ *
4
+ * The model integrates lift, drag, thrust and aerodynamic moments in SI units, `+Y` up, with the
5
+ * nose down local `-Z`. Attitude is a quaternion, so there are no Euler clamps and no commanded
6
+ * velocity vectors: the game writes controls, the model writes forces, and the aircraft keeps its
7
+ * own momentum. Every number that decides how the aircraft looks or performs — mass, wing area,
8
+ * engine power, inertia, control authority, wind, damage multipliers and payload — arrives from
9
+ * the game. This module owns only the mechanism that turns those inputs into motion.
10
+ */
11
+
12
+ export interface IFlightVector3 {
13
+ x: number;
14
+ y: number;
15
+ z: number;
16
+ }
17
+
18
+ export interface IFlightQuaternion {
19
+ x: number;
20
+ y: number;
21
+ z: number;
22
+ w: number;
23
+ }
24
+
25
+ export interface IFlightAxes {
26
+ readonly r: IFlightVector3;
27
+ readonly u: IFlightVector3;
28
+ readonly f: IFlightVector3;
29
+ }
30
+
31
+ /** Per-aircraft constants. The game supplies these; the model ships no airframe of its own. */
32
+ export interface IAircraftAirframe {
33
+ /** Empty mass, kg. */
34
+ readonly dryMass: number;
35
+ /** Mass of a full fuel load, kg. */
36
+ readonly fuelMass: number;
37
+ /** Reference wing area, m². */
38
+ readonly wingArea: number;
39
+ /** Wingspan, m. */
40
+ readonly span: number;
41
+ /** Mean aerodynamic chord, m. */
42
+ readonly chord: number;
43
+ /** Shaft power at full throttle, W. */
44
+ readonly power: number;
45
+ /** Propeller efficiency, 0–1. */
46
+ readonly propEfficiency: number;
47
+ /** Maximum static thrust, N. */
48
+ readonly staticThrust: number;
49
+ /** Pitch moment of inertia, kg·m². */
50
+ readonly pitchInertia: number;
51
+ /** Roll moment of inertia, kg·m². */
52
+ readonly rollInertia: number;
53
+ /** Yaw moment of inertia, kg·m². */
54
+ readonly yawInertia: number;
55
+ }
56
+
57
+ /** Multipliers a game applies for damage, load or upgrades. 1 / 0 is the undamaged case. */
58
+ export interface IFlightModifiers {
59
+ readonly power: number;
60
+ readonly lift: number;
61
+ readonly drag: number;
62
+ readonly roll: number;
63
+ readonly controls: number;
64
+ }
65
+
66
+ export const NEUTRAL_FLIGHT_MODIFIERS: IFlightModifiers = Object.freeze({
67
+ controls: 1,
68
+ drag: 0,
69
+ lift: 1,
70
+ power: 1,
71
+ roll: 0,
72
+ });
73
+
74
+ /** One fixed step of pilot input. Every field is a dimensionless command in `[-1, 1]`. */
75
+ export interface IFlightControls {
76
+ readonly turn?: number;
77
+ readonly pitch?: number;
78
+ readonly rudder?: number;
79
+ readonly wheelBrake?: boolean;
80
+ /** When true, stability assist is bypassed and the game commands the attitude directly. */
81
+ readonly autopilot?: boolean;
82
+ }
83
+
84
+ /** The moving deck an aircraft launches from. */
85
+ export interface IFlightDeck {
86
+ readonly x: number;
87
+ readonly y?: number;
88
+ readonly z: number;
89
+ readonly heading: number;
90
+ readonly speed: number;
91
+ readonly length: number;
92
+ readonly width: number;
93
+ }
94
+
95
+ export interface IFlightState {
96
+ x: number;
97
+ y: number;
98
+ z: number;
99
+ vx: number;
100
+ vy: number;
101
+ vz: number;
102
+ attitude?: IFlightQuaternion;
103
+ heading: number;
104
+ pitch: number;
105
+ roll: number;
106
+ rollRate: number;
107
+ pitchRate: number;
108
+ yawRate: number;
109
+ speed: number;
110
+ ias: number;
111
+ groundSpeed: number;
112
+ throttle: number;
113
+ rpm: number;
114
+ fuel: number;
115
+ hp: number;
116
+ engineCut: boolean;
117
+ gear: boolean;
118
+ brakes: boolean;
119
+ gearPos: number;
120
+ brakePos: number;
121
+ flapPos: number;
122
+ flaps: number;
123
+ aileron: number;
124
+ elevator: number;
125
+ rudder: number;
126
+ controlAileron: number;
127
+ assist: boolean;
128
+ trim: number;
129
+ gforce: number;
130
+ aoa: number;
131
+ beta: number;
132
+ stall: number;
133
+ /** Mass of everything under the wings, kg. The game writes it as stores are released. */
134
+ payloadMass: number;
135
+ /** Extra flat-plate drag coefficient from external stores. */
136
+ payloadDrag: number;
137
+ flightTime: number;
138
+ lift: number;
139
+ drag: number;
140
+ thrust: number;
141
+ mass: number;
142
+ deckSpeed?: number;
143
+ deckLateral?: number;
144
+ deckOffset?: number;
145
+ chocks?: boolean;
146
+ }
147
+
148
+ export interface IFlightEnvironment {
149
+ readonly airframe: IAircraftAirframe;
150
+ readonly wind?: IFlightVector3;
151
+ readonly modifiers?: IFlightModifiers;
152
+ readonly gravity?: number;
153
+ /** Height of the carrier deck surface above the water, m. */
154
+ readonly deckHeight?: number;
155
+ }
156
+
157
+ export interface IFlightForces {
158
+ readonly x: number;
159
+ readonly y: number;
160
+ readonly z: number;
161
+ readonly normalLoad: number;
162
+ readonly lift: number;
163
+ readonly drag: number;
164
+ readonly thrust: number;
165
+ readonly alpha: number;
166
+ readonly beta: number;
167
+ readonly airspeed: number;
168
+ readonly density: number;
169
+ readonly mass: number;
170
+ readonly qs: number;
171
+ readonly axes: IFlightAxes;
172
+ readonly cl: number;
173
+ readonly cd: number;
174
+ readonly stall: number;
175
+ readonly critical: number;
176
+ }
177
+
178
+ const TAU = Math.PI * 2;
179
+ const SEA_WIND: IFlightVector3 = Object.freeze({ x: 0, y: 0, z: 0 });
180
+ const clamp = (value: number, low: number, high: number): number =>
181
+ Math.max(low, Math.min(high, value));
182
+ const lerp = (a: number, b: number, t: number): number => a + (b - a) * t;
183
+ const wrap = (angle: number): number => ((angle % TAU) + TAU) % TAU;
184
+ const dot = (a: IFlightVector3, b: IFlightVector3): number => a.x * b.x + a.y * b.y + a.z * b.z;
185
+ const unit = (a: IFlightVector3): IFlightVector3 => {
186
+ const length = Math.hypot(a.x, a.y, a.z) || 1;
187
+ return { x: a.x / length, y: a.y / length, z: a.z / length };
188
+ };
189
+ const smooth = (a: number, b: number, x: number): number => {
190
+ const t = clamp((x - a) / (b - a), 0, 1);
191
+ return t * t * (3 - 2 * t);
192
+ };
193
+ const move = (a: number, b: number, maxStep: number): number => a + clamp(b - a, -maxStep, maxStep);
194
+
195
+ /** ISA air density at altitude `y` metres, kg/m³. */
196
+ export function airDensity(y: number): number {
197
+ return 1.225 * Math.max(0.19, 1 - 2.25577e-5 * Math.max(0, y)) ** 4.25588;
198
+ }
199
+
200
+ /** Current mass of the aircraft from its empty mass, fuel load and game-written payload. */
201
+ export function aircraftMass(state: IFlightState, airframe: IAircraftAirframe): number {
202
+ return (
203
+ airframe.dryMass +
204
+ airframe.fuelMass * clamp((state.fuel ?? 100) / 100, 0, 1) +
205
+ (state.payloadMass ?? 0)
206
+ );
207
+ }
208
+
209
+ /** Lift and drag coefficients for an angle of attack and the deployed high-lift devices. */
210
+ export function aerodynamicCoefficients(
211
+ alpha: number,
212
+ flaps = 0,
213
+ gear = 0,
214
+ brakes = 0,
215
+ ): { cl: number; cd: number; stall: number; critical: number } {
216
+ const critical = 0.265 + flaps * 0.035;
217
+ const stall = smooth(critical - 0.015, critical + 0.15, Math.abs(alpha));
218
+ const attached = clamp(0.22 + flaps * 0.48 + 4.8 * alpha, -1.48, 1.58 + flaps * 0.35);
219
+ const separated = 1.1 * Math.sin(2 * alpha);
220
+ const cl = lerp(attached, separated, stall);
221
+ const cd =
222
+ 0.027 +
223
+ 0.075 * cl * cl +
224
+ 0.9 * Math.sin(alpha) ** 2 * stall +
225
+ gear * 0.029 +
226
+ brakes * 0.135 +
227
+ flaps * flaps * 0.047;
228
+ return { cd, cl, critical, stall };
229
+ }
230
+
231
+ /** Write a heading/pitch/roll pose into the body quaternion. Nose down local `-Z`. */
232
+ export function setAttitude(
233
+ state: IFlightState,
234
+ heading = 0,
235
+ pitch = 0,
236
+ roll = 0,
237
+ ): IFlightQuaternion {
238
+ const a = pitch / 2;
239
+ const b = -heading / 2;
240
+ const c = roll / 2;
241
+ const ca = Math.cos(a);
242
+ const sa = Math.sin(a);
243
+ const cb = Math.cos(b);
244
+ const sb = Math.sin(b);
245
+ const cc = Math.cos(c);
246
+ const sc = Math.sin(c);
247
+ const attitude = {
248
+ w: ca * cb * cc + sa * sb * sc,
249
+ x: sa * cb * cc + ca * sb * sc,
250
+ y: ca * sb * cc - sa * cb * sc,
251
+ z: ca * cb * sc - sa * sb * cc,
252
+ };
253
+ state.attitude = attitude;
254
+ state.heading = wrap(heading);
255
+ state.pitch = pitch;
256
+ state.roll = roll;
257
+ return attitude;
258
+ }
259
+
260
+ /** Right, up and forward unit vectors of the body frame. */
261
+ export function attitudeAxes(state: IFlightState): IFlightAxes {
262
+ const q = state.attitude ?? { x: 0, y: 0, z: 0, w: 1 };
263
+ const { x, y, z, w } = q;
264
+ return {
265
+ f: { x: -2 * (x * z + y * w), y: -2 * (y * z - x * w), z: -(1 - 2 * (x * x + y * y)) },
266
+ r: { x: 1 - 2 * (y * y + z * z), y: 2 * (x * y + z * w), z: 2 * (x * z - y * w) },
267
+ u: { x: 2 * (x * y - z * w), y: 1 - 2 * (x * x + z * z), z: 2 * (y * z + x * w) },
268
+ };
269
+ }
270
+
271
+ /** Height of the gear contact point below the body origin at the current pitch. */
272
+ export function gearClearance(state: IFlightState): number {
273
+ return 1.82 * Math.cos(state.pitch) - 0.65 * Math.sin(state.pitch);
274
+ }
275
+
276
+ /** Initialise velocities from a pose and clear the integrated rates. */
277
+ export function initFlight(state: IFlightState, environment: IFlightEnvironment): void {
278
+ const wind = environment.wind ?? SEA_WIND;
279
+ setAttitude(state, state.heading ?? 0, state.pitch ?? 0, state.roll ?? 0);
280
+ const f = attitudeAxes(state).f;
281
+ const speed = state.speed ?? 0;
282
+ state.vx = f.x * speed + wind.x;
283
+ state.vy = f.y * speed + wind.y;
284
+ state.vz = f.z * speed + wind.z;
285
+ state.rollRate = 0;
286
+ state.pitchRate = 0;
287
+ state.yawRate = 0;
288
+ state.gearPos = state.gear ? 1 : 0;
289
+ state.brakePos = state.brakes ? 1 : 0;
290
+ state.flaps = state.flaps ?? 0;
291
+ state.flapPos = state.flaps;
292
+ state.rpm = state.throttle || 0;
293
+ state.assist = state.assist ?? true;
294
+ state.trim = state.trim ?? 0.04;
295
+ state.aileron = 0;
296
+ state.elevator = 0;
297
+ state.rudder = 0;
298
+ state.controlAileron = 0;
299
+ state.gforce = 1;
300
+ state.aoa = 0;
301
+ state.beta = 0;
302
+ state.stall = 0;
303
+ state.ias = speed;
304
+ state.groundSpeed = speed;
305
+ state.flightTime = 0;
306
+ }
307
+
308
+ /** Aerodynamic and propulsive force on the body for the current state, no integration. */
309
+ export function flightForces(state: IFlightState, environment: IFlightEnvironment): IFlightForces {
310
+ const { airframe } = environment;
311
+ const wind = environment.wind ?? SEA_WIND;
312
+ const gravity = environment.gravity ?? 9.80665;
313
+ const modifiers = environment.modifiers ?? NEUTRAL_FLIGHT_MODIFIERS;
314
+ const axes = attitudeAxes(state);
315
+ const va = { x: state.vx - wind.x, y: state.vy - wind.y, z: state.vz - wind.z };
316
+ const airspeed = Math.hypot(va.x, va.y, va.z);
317
+ const direction = unit(va);
318
+ const vf = dot(va, axes.f);
319
+ const vu = dot(va, axes.u);
320
+ const vr = dot(va, axes.r);
321
+ const alpha = Math.atan2(-vu, Math.max(0.001, vf));
322
+ const beta = Math.atan2(vr, Math.hypot(vf, vu) || 0.001);
323
+ const density = airDensity(state.y);
324
+ const q = 0.5 * density * airspeed * airspeed;
325
+ const qs = q * airframe.wingArea;
326
+ const coeff = aerodynamicCoefficients(
327
+ alpha,
328
+ state.flapPos || 0,
329
+ state.gearPos || 0,
330
+ state.brakePos || 0,
331
+ );
332
+ const health = 0.72 + 0.28 * clamp((state.hp ?? 100) / 100, 0, 1);
333
+ const mass = aircraftMass(state, airframe);
334
+ const lift = qs * coeff.cl * health * modifiers.lift;
335
+ const drag = qs * (coeff.cd + modifiers.drag + (state.payloadDrag ?? 0));
336
+ const liftDir = unit({
337
+ x: axes.u.x - direction.x * dot(axes.u, direction),
338
+ y: axes.u.y - direction.y * dot(axes.u, direction),
339
+ z: axes.u.z - direction.z * dot(axes.u, direction),
340
+ });
341
+ const sideDir = unit({
342
+ x: axes.r.x - direction.x * dot(axes.r, direction),
343
+ y: axes.r.y - direction.y * dot(axes.r, direction),
344
+ z: axes.r.z - direction.z * dot(axes.r, direction),
345
+ });
346
+ const side = -qs * 0.48 * Math.sin(beta);
347
+ const rpm = state.rpm ?? state.throttle ?? 0;
348
+ const thrust =
349
+ (state.fuel > 0 ? 1 : 0) *
350
+ Math.min(
351
+ airframe.staticThrust,
352
+ (airframe.power * airframe.propEfficiency) / Math.max(20, airspeed),
353
+ ) *
354
+ rpm *
355
+ health *
356
+ modifiers.power;
357
+ const fx = liftDir.x * lift - direction.x * drag + sideDir.x * side + axes.f.x * thrust;
358
+ const fy = liftDir.y * lift - direction.y * drag + sideDir.y * side + axes.f.y * thrust;
359
+ const fz = liftDir.z * lift - direction.z * drag + sideDir.z * side + axes.f.z * thrust;
360
+ // Written out field by field, never `{ ...coeff, ... }`: a spread sends V8 through
361
+ // `CopyDataProperties` instead of the boilerplate a fixed literal gets, and this runs twice per
362
+ // aircraft per fixed step. Measured on `scripts/check-flight-cost.ts` (32 aircraft): mean step
363
+ // 0.82 ms spread versus 0.09 ms written out, with a bit-identical `finalStateSha256`.
364
+ return {
365
+ x: fx,
366
+ y: fy - mass * gravity,
367
+ z: fz,
368
+ normalLoad: (fx * axes.u.x + fy * axes.u.y + fz * axes.u.z) / (mass * gravity),
369
+ lift,
370
+ drag,
371
+ thrust,
372
+ alpha,
373
+ beta,
374
+ airspeed,
375
+ density,
376
+ mass,
377
+ qs,
378
+ axes,
379
+ cl: coeff.cl,
380
+ cd: coeff.cd,
381
+ stall: coeff.stall,
382
+ critical: coeff.critical,
383
+ };
384
+ }
385
+
386
+ /** Smoothly drive the control surfaces and engine toward the commanded values. */
387
+ export function updateActuators(
388
+ state: IFlightState,
389
+ dt: number,
390
+ controls: IFlightControls = {},
391
+ ): void {
392
+ state.flightTime = (state.flightTime || 0) + dt;
393
+ state.rpm = lerp(
394
+ state.rpm ?? state.throttle,
395
+ state.fuel <= 0 || state.engineCut ? 0 : state.throttle,
396
+ 1 - Math.exp(-dt / 1.3),
397
+ );
398
+ state.gearPos = move(state.gearPos ?? (state.gear ? 1 : 0), state.gear ? 1 : 0, dt * 0.36);
399
+ state.brakePos = move(state.brakePos ?? (state.brakes ? 1 : 0), state.brakes ? 1 : 0, dt * 0.85);
400
+ state.flapPos = move(state.flapPos ?? 0, state.flaps ?? 0, dt * 0.23);
401
+ state.aileron = lerp(state.aileron || 0, clamp(controls.turn || 0, -1, 1), 1 - Math.exp(-dt * 7));
402
+ state.elevator = lerp(
403
+ state.elevator || 0,
404
+ clamp(controls.pitch || 0, -1, 1),
405
+ 1 - Math.exp(-dt * 6),
406
+ );
407
+ state.rudder = lerp(state.rudder || 0, clamp(controls.rudder || 0, -1, 1), 1 - Math.exp(-dt * 7));
408
+ }
409
+
410
+ function advanceQuaternion(state: IFlightState, dt: number): void {
411
+ const q = state.attitude;
412
+ if (q === undefined) return;
413
+ const ox = state.pitchRate;
414
+ const oy = -state.yawRate;
415
+ const oz = -state.rollRate;
416
+ const len = Math.hypot(ox, oy, oz);
417
+ const half = (len * dt) / 2;
418
+ const s = len > 1e-9 ? Math.sin(half) / len : dt / 2;
419
+ const dx = ox * s;
420
+ const dy = oy * s;
421
+ const dz = oz * s;
422
+ const dw = Math.cos(half);
423
+ const x = q.x * dw + q.w * dx + q.y * dz - q.z * dy;
424
+ const y = q.y * dw + q.w * dy + q.z * dx - q.x * dz;
425
+ const z = q.z * dw + q.w * dz + q.x * dy - q.y * dx;
426
+ const w = q.w * dw - q.x * dx - q.y * dy - q.z * dz;
427
+ const n = Math.hypot(x, y, z, w) || 1;
428
+ q.x = x / n;
429
+ q.y = y / n;
430
+ q.z = z / n;
431
+ q.w = w / n;
432
+ const axes = attitudeAxes(state);
433
+ state.heading = wrap(Math.atan2(axes.f.x, -axes.f.z));
434
+ state.pitch = Math.asin(clamp(axes.f.y, -1, 1));
435
+ state.roll = Math.atan2(axes.r.y, axes.u.y);
436
+ }
437
+
438
+ /** Integrate one fixed step of free flight. Sub-steps internally at 120 Hz. */
439
+ export function stepFlight(
440
+ state: IFlightState,
441
+ dt: number,
442
+ controls: IFlightControls,
443
+ environment: IFlightEnvironment,
444
+ ): void {
445
+ if (!Number.isFinite(dt) || dt <= 0) return;
446
+ if (dt > 1 / 120 + 1e-8) {
447
+ const n = Math.ceil(dt / (1 / 120));
448
+ for (let i = 0; i < n; i += 1) stepFlight(state, dt / n, controls, environment);
449
+ return;
450
+ }
451
+ const { airframe } = environment;
452
+ const gravity = environment.gravity ?? 9.80665;
453
+ const wind = environment.wind ?? SEA_WIND;
454
+ const modifiers = environment.modifiers ?? NEUTRAL_FLIGHT_MODIFIERS;
455
+ if (!state.attitude) initFlight(state, environment);
456
+ updateActuators(state, dt, controls);
457
+ const f = flightForces(state, environment);
458
+ const speed = Math.max(12, f.airspeed);
459
+ const neutralWeight = Math.exp(-Math.abs(state.elevator) * 12);
460
+ const upright = f.axes.u.y > 0.35;
461
+ const assistLoad =
462
+ state.assist && !controls.autopilot && upright
463
+ ? neutralWeight *
464
+ (clamp(1 / Math.max(0.55, Math.cos(state.roll)), 1, 1.8) -
465
+ 1 +
466
+ clamp(-state.vy * 0.05, -0.45, 0.45))
467
+ : 0;
468
+ const desiredLoad = 1 + assistLoad + (state.elevator >= 0 ? 4.5 : 2.5) * state.elevator;
469
+ const trimAlpha =
470
+ state.assist || controls.autopilot
471
+ ? clamp(
472
+ ((desiredLoad * f.mass * gravity) / Math.max(f.qs, 4000) - 0.22 - state.flapPos * 0.48) /
473
+ 4.8,
474
+ -0.34,
475
+ 0.43,
476
+ )
477
+ : state.trim + state.elevator * 0.34;
478
+ const dampingSpeed = Math.max(25, speed);
479
+ const controlPower = clamp(f.qs, 0, 400000);
480
+ const pitchMoment =
481
+ controlPower *
482
+ airframe.chord *
483
+ (0.64 * modifiers.controls * (trimAlpha - f.alpha) -
484
+ (10 * state.pitchRate * airframe.chord) / (2 * dampingSpeed) -
485
+ 0.045 * f.stall);
486
+ const bankDemand = clamp((state.roll + state.aileron * 1.1) * 1.7 - state.rollRate * 0.65, -1, 1);
487
+ const rollInput = state.assist && !controls.autopilot ? bankDemand : state.aileron;
488
+ state.controlAileron = rollInput;
489
+ const rollMoment =
490
+ controlPower *
491
+ airframe.span *
492
+ (0.023 * rollInput * (0.35 + 0.65 * modifiers.lift) +
493
+ modifiers.roll -
494
+ (0.48 * state.rollRate * airframe.span) / (2 * dampingSpeed) -
495
+ 0.012 * f.beta);
496
+ const yawAssist = state.assist || controls.autopilot ? clamp(f.beta * 1.3, -0.6, 0.6) : 0;
497
+ const yawMoment =
498
+ controlPower *
499
+ airframe.span *
500
+ (0.1 * f.beta +
501
+ 0.024 * modifiers.controls * (state.rudder + yawAssist) -
502
+ (0.29 * state.yawRate * airframe.span) / (2 * dampingSpeed) -
503
+ 0.0017 * state.aileron);
504
+ state.pitchRate += (pitchMoment / airframe.pitchInertia) * dt;
505
+ state.rollRate += (rollMoment / airframe.rollInertia) * dt;
506
+ state.yawRate += (yawMoment / airframe.yawInertia) * dt;
507
+ advanceQuaternion(state, dt);
508
+ state.vx += (f.x / f.mass) * dt;
509
+ state.vy += (f.y / f.mass) * dt;
510
+ state.vz += (f.z / f.mass) * dt;
511
+ state.x += state.vx * dt;
512
+ state.y += state.vy * dt;
513
+ state.z += state.vz * dt;
514
+ state.speed = Math.hypot(state.vx - wind.x, state.vy - wind.y, state.vz - wind.z);
515
+ state.ias = state.speed * Math.sqrt(f.density / 1.225);
516
+ state.groundSpeed = Math.hypot(state.vx, state.vz);
517
+ state.gforce = lerp(state.gforce ?? 1, f.normalLoad, 1 - Math.exp(-dt * 8));
518
+ state.aoa = f.alpha;
519
+ state.beta = f.beta;
520
+ state.stall = f.stall;
521
+ state.lift = f.lift;
522
+ state.drag = f.drag;
523
+ state.thrust = f.thrust;
524
+ state.mass = f.mass;
525
+ }
526
+
527
+ /** Run one step of a deck launch. Returns `liftoff`, `overrun` or `null` while still rolling. */
528
+ export function stepDeck(
529
+ state: IFlightState,
530
+ deck: IFlightDeck,
531
+ dt: number,
532
+ controls: IFlightControls,
533
+ environment: IFlightEnvironment,
534
+ ): "liftoff" | "overrun" | null {
535
+ const gravity = environment.gravity ?? 9.80665;
536
+ const deckHeight = environment.deckHeight ?? 20;
537
+ const wind = environment.wind ?? SEA_WIND;
538
+ if (!state.attitude) initFlight(state, environment);
539
+ updateActuators(state, dt, controls);
540
+ state.deckSpeed = state.deckSpeed ?? 0;
541
+ state.deckLateral = state.deckLateral ?? -2.5;
542
+ state.deckOffset = state.deckOffset ?? -105;
543
+ const sin = Math.sin(deck.heading);
544
+ const cos = Math.cos(deck.heading);
545
+ const overDeck = deck.speed + wind.z * cos - wind.x * sin;
546
+ const speed = state.deckSpeed + overDeck;
547
+ const tailRise = smooth(22, 38, speed);
548
+ const rotation = smooth(42, 51, speed);
549
+ const neutralPitch = lerp(0.22, 0.025, tailRise) + (state.assist ? 0.145 * rotation : 0);
550
+ const desiredPitch = clamp(neutralPitch + (controls.pitch || 0) * 0.13, -0.025, 0.26);
551
+ state.pitch = lerp(state.pitch, desiredPitch, 1 - Math.exp(-dt * 2.8));
552
+ state.heading = wrap(
553
+ state.heading +
554
+ (controls.rudder || controls.turn || 0) * dt * 0.22 * clamp(state.deckSpeed / 12, 0, 1),
555
+ );
556
+ setAttitude(state, state.heading, state.pitch, 0);
557
+ const yaw = Math.atan2(
558
+ Math.sin(state.heading - deck.heading),
559
+ Math.cos(state.heading - deck.heading),
560
+ );
561
+ state.vx = Math.sin(state.heading) * state.deckSpeed + sin * deck.speed;
562
+ state.vy = 0;
563
+ state.vz = -Math.cos(state.heading) * state.deckSpeed - cos * deck.speed;
564
+ const f = flightForces(state, environment);
565
+ const normal = Math.max(0, f.mass * gravity - f.lift * Math.cos(state.pitch));
566
+ if (state.chocks !== false && state.throttle < 0.55) {
567
+ state.deckSpeed = 0;
568
+ } else {
569
+ state.chocks = false;
570
+ const acceleration =
571
+ (f.thrust - f.drag - normal * (controls.wheelBrake ? 0.55 : 0.019)) / f.mass;
572
+ state.deckSpeed = Math.max(0, state.deckSpeed + acceleration * dt);
573
+ }
574
+ state.deckOffset += Math.cos(yaw) * state.deckSpeed * dt;
575
+ state.deckLateral += Math.sin(yaw) * state.deckSpeed * dt;
576
+ state.x = deck.x + sin * state.deckOffset + cos * state.deckLateral;
577
+ state.z = deck.z - cos * state.deckOffset + sin * state.deckLateral;
578
+ state.y = deckHeight + gearClearance(state);
579
+ state.vx = Math.sin(state.heading) * state.deckSpeed + sin * deck.speed;
580
+ state.vz = -Math.cos(state.heading) * state.deckSpeed - cos * deck.speed;
581
+ state.speed = Math.hypot(state.vx - wind.x, state.vz - wind.z);
582
+ state.ias = state.speed * Math.sqrt(airDensity(state.y) / 1.225);
583
+ state.groundSpeed = state.deckSpeed + deck.speed;
584
+ state.lift = f.lift;
585
+ state.drag = f.drag;
586
+ state.thrust = f.thrust;
587
+ state.aoa = f.alpha;
588
+ state.stall = f.stall;
589
+ state.gforce = 1;
590
+ const lifted = f.lift * Math.cos(state.pitch) > f.mass * gravity * 1.015 && state.deckSpeed > 18;
591
+ const leftDeck =
592
+ state.deckOffset > deck.length / 2 - 1 || Math.abs(state.deckLateral) > deck.width / 2 - 1;
593
+ if (lifted || leftDeck) {
594
+ state.rollRate = 0;
595
+ state.pitchRate = 0;
596
+ state.yawRate = 0;
597
+ return lifted ? "liftoff" : "overrun";
598
+ }
599
+ return null;
600
+ }
601
+
602
+ export interface IFlightModelOptions<TState extends IFlightState = IFlightState>
603
+ extends IFlightEnvironment {
604
+ /** The game's own aircraft object, extended with whatever else the game needs on it. */
605
+ readonly state: TState;
606
+ }
607
+
608
+ /** `IFlightEnvironment` with a writable `modifiers`, for the one record each model steps with. */
609
+ interface IFlightStepEnvironment extends Omit<IFlightEnvironment, "modifiers"> {
610
+ modifiers?: IFlightModifiers;
611
+ }
612
+
613
+ /**
614
+ * One aircraft's dynamics: a thin owner of a game-authored state object plus its environment.
615
+ *
616
+ * The step record copies the options' own fields once, at construction — so `airframe`, `wind`,
617
+ * `gravity` and `deckHeight` are read from the objects those fields reference, which stay live,
618
+ * but replacing a field on the options object afterwards is not observed. Change a model's airframe
619
+ * or deck by building it again, as a game that binds aircraft to carriers already does.
620
+ *
621
+ * @example
622
+ * const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
623
+ * model.setAttitude(0, 0.2, 0);
624
+ * model.step(1 / 60, { turn: -1, pitch: 0.4 });
625
+ */
626
+ export class FlightModel<TState extends IFlightState = IFlightState> {
627
+ readonly state: TState;
628
+ readonly environment: IFlightEnvironment;
629
+ /**
630
+ * `environment` plus the modifiers of the step in flight: one record per model, written per call
631
+ * rather than spread per call. Spreading allocated a whole environment on every aircraft every
632
+ * fixed step, which was the single hottest line of Midway's step; the caller's own environment is
633
+ * never touched.
634
+ */
635
+ readonly #stepEnvironment: IFlightStepEnvironment;
636
+
637
+ constructor(options: IFlightModelOptions<TState>) {
638
+ this.state = options.state;
639
+ this.environment = options;
640
+ this.#stepEnvironment = { ...options };
641
+ initFlight(this.state, this.environment);
642
+ }
643
+
644
+ setAttitude(heading = 0, pitch = 0, roll = 0): void {
645
+ setAttitude(this.state, heading, pitch, roll);
646
+ }
647
+
648
+ reset(): void {
649
+ initFlight(this.state, this.environment);
650
+ }
651
+
652
+ axes(): IFlightAxes {
653
+ return attitudeAxes(this.state);
654
+ }
655
+
656
+ gearClearance(): number {
657
+ return gearClearance(this.state);
658
+ }
659
+
660
+ forces(modifiers: IFlightModifiers = NEUTRAL_FLIGHT_MODIFIERS): IFlightForces {
661
+ this.#stepEnvironment.modifiers = modifiers;
662
+ return flightForces(this.state, this.#stepEnvironment);
663
+ }
664
+
665
+ step(
666
+ dt: number,
667
+ controls: IFlightControls,
668
+ modifiers: IFlightModifiers = NEUTRAL_FLIGHT_MODIFIERS,
669
+ ): void {
670
+ this.#stepEnvironment.modifiers = modifiers;
671
+ stepFlight(this.state, dt, controls, this.#stepEnvironment);
672
+ }
673
+
674
+ stepDeck(
675
+ deck: IFlightDeck,
676
+ dt: number,
677
+ controls: IFlightControls,
678
+ modifiers: IFlightModifiers = NEUTRAL_FLIGHT_MODIFIERS,
679
+ ): "liftoff" | "overrun" | null {
680
+ this.#stepEnvironment.modifiers = modifiers;
681
+ return stepDeck(this.state, deck, dt, controls, this.#stepEnvironment);
682
+ }
683
+ }