@specter-automation/test 1.0.149 → 1.0.150

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.
@@ -0,0 +1,145 @@
1
+ /**
2
+ * Results of Specter's debugging commands: what's in the way of a line, why an AI doesn't see something, the navmesh
3
+ * path to a place, what overlaps what, collision settings, the engine's warnings during a test, and the state history
4
+ * of the test's actors.
5
+ */
6
+ /** "Block", "Overlap" or "Ignore" */
7
+ export type CollisionResponse = 'Block' | 'Overlap' | 'Ignore';
8
+ /** A collision component's settings */
9
+ export interface CollisionDescription {
10
+ component: string;
11
+ componentClass: string;
12
+ actor?: string;
13
+ /** The collision profile ("Custom" when set by hand) */
14
+ profile: string;
15
+ collisionEnabled: 'NoCollision' | 'QueryOnly' | 'PhysicsOnly' | 'QueryAndPhysics' | 'Other';
16
+ /** The channel it is as an object ("Pawn", "WorldDynamic", a project channel) */
17
+ objectType: string;
18
+ generatesOverlapEvents: boolean;
19
+ canEverAffectNavigation: boolean;
20
+ /** Its response to each channel the project names (or only the channel asked about) */
21
+ responses: Record<string, CollisionResponse>;
22
+ }
23
+ /** A line traced on a collision channel */
24
+ export interface TraceResult {
25
+ channel: string;
26
+ /** Nothing in the way (or the first thing in the way is the target) */
27
+ clear: boolean;
28
+ from: [number, number, number];
29
+ to: [number, number, number];
30
+ distance: number;
31
+ /** One line: "Clear on Visibility." or what blocked it and its collision settings */
32
+ summary: string;
33
+ /** The first thing in the way, when not clear */
34
+ blockedBy?: CollisionDescription & {
35
+ actorClass?: string;
36
+ location: [number, number, number];
37
+ distance: number;
38
+ };
39
+ }
40
+ /** Whether an AI sees another actor, and why not */
41
+ export interface PerceptionResult {
42
+ ai: string;
43
+ target: string;
44
+ perceived: boolean;
45
+ /** "Perceived by sight.", "Out of range: ...", "Outside its view: ...", "Something's in the way: ...", ... */
46
+ reason: string;
47
+ distance: number;
48
+ /** Degrees between where it faces and the target */
49
+ angle: number;
50
+ attitude: 'Friendly' | 'Neutral' | 'Hostile' | '?';
51
+ sightRadius?: number;
52
+ loseSightRadius?: number;
53
+ peripheralVisionAngle?: number;
54
+ /** The last time sight sensed the target */
55
+ lastSight?: {
56
+ ageSeconds: number;
57
+ sensed: boolean;
58
+ };
59
+ /** The line AI sight traces (on the AI System's sight channel) */
60
+ trace: TraceResult;
61
+ }
62
+ /** The navmesh path to a goal */
63
+ export interface NavPathResult {
64
+ start: [number, number, number];
65
+ goal: [number, number, number];
66
+ startOnNavMesh: boolean;
67
+ goalOnNavMesh: boolean;
68
+ found: boolean;
69
+ /** The path stops short of the goal */
70
+ partial?: boolean;
71
+ length?: number;
72
+ end?: [number, number, number];
73
+ endToGoal?: number;
74
+ points?: [number, number, number][];
75
+ /** Its AI's path following now */
76
+ aiMove?: {
77
+ status: 'Idle' | 'Waiting' | 'Paused' | 'Moving';
78
+ destination?: [number, number, number];
79
+ speed: number;
80
+ };
81
+ summary: string;
82
+ }
83
+ export interface OverlapResult {
84
+ /** The actors overlapping */
85
+ actors: string[];
86
+ overlaps: {
87
+ component: string;
88
+ actor: string;
89
+ actorClass: string;
90
+ otherComponent: string;
91
+ }[];
92
+ }
93
+ /** One line of the engine's warnings and errors */
94
+ export interface EngineLogEntry {
95
+ /** Seconds after the last test's cleanup (real time) */
96
+ seconds: number;
97
+ verbosity: 'Warning' | 'Error';
98
+ category: string;
99
+ message: string;
100
+ /** Times it was logged */
101
+ count: number;
102
+ }
103
+ export interface EngineLog {
104
+ entries: EngineLogEntry[];
105
+ /** Different lines not kept, the buffer being full */
106
+ dropped: number;
107
+ }
108
+ /** One actor in a state sample */
109
+ export interface ActorStateSample {
110
+ at: [number, number, number];
111
+ yaw: number;
112
+ speed: number;
113
+ health?: number;
114
+ maxHealth?: number;
115
+ /** Its AI's path following: Idle, Waiting, Paused, Moving */
116
+ move?: string;
117
+ moveGoal?: [number, number];
118
+ gone?: boolean;
119
+ }
120
+ export interface StateSample {
121
+ /** Seconds since the test started (the timeline's clock) */
122
+ t: number;
123
+ actors: Record<string, ActorStateSample>;
124
+ }
125
+ /** Where the test's actors were and how they were doing, a few times a second */
126
+ export interface StateHistory {
127
+ /** Seconds between samples */
128
+ interval: number;
129
+ /** Each actor's class */
130
+ classes: Record<string, string>;
131
+ samples?: StateSample[];
132
+ /** With `at`: the sample nearest that time */
133
+ sample?: StateSample;
134
+ }
135
+ /** An AI that stood still while its path following said it was moving */
136
+ export interface StuckAI {
137
+ actor: string;
138
+ since: number;
139
+ seconds: number;
140
+ location: [number, number];
141
+ goal: [number, number];
142
+ stillStuck: boolean;
143
+ }
144
+ /** The diagnostics report's lines about the engine's warnings and stuck AIs */
145
+ export declare function formatDebugDiagnostics(diagnostics: any): string[];
@@ -0,0 +1,35 @@
1
+ "use strict";
2
+ /**
3
+ * Results of Specter's debugging commands: what's in the way of a line, why an AI doesn't see something, the navmesh
4
+ * path to a place, what overlaps what, collision settings, the engine's warnings during a test, and the state history
5
+ * of the test's actors.
6
+ */
7
+ Object.defineProperty(exports, "__esModule", { value: true });
8
+ exports.formatDebugDiagnostics = formatDebugDiagnostics;
9
+ /** The diagnostics report's lines about the engine's warnings and stuck AIs */
10
+ function formatDebugDiagnostics(diagnostics) {
11
+ const lines = [];
12
+ const stuck = diagnostics?.stuckAI ?? [];
13
+ if (stuck.length > 0) {
14
+ lines.push('🚧 AI that stood still while moving:');
15
+ for (const entry of stuck) {
16
+ lines.push(` • ${entry.actor}: moving to (${entry.goal[0]}, ${entry.goal[1]}) but at (${entry.location[0]}, ${entry.location[1]}) for ${Number(entry.seconds).toFixed(1)}s from ${Number(entry.since).toFixed(1)}s${entry.stillStuck ? ', still' : ''}`);
17
+ }
18
+ lines.push('');
19
+ }
20
+ const log = diagnostics?.engineLog ?? [];
21
+ if (log.length > 0) {
22
+ lines.push('⚠️ Engine warnings and errors since the last test (most recent last):');
23
+ for (const entry of log.slice(-15)) {
24
+ lines.push(` [${Number(entry.seconds).toFixed(1)}s] ${entry.verbosity} ${entry.category}: ${entry.message}${entry.count > 1 ? ` (×${entry.count})` : ''}`);
25
+ }
26
+ if (log.length > 15) {
27
+ lines.push(` … ${log.length - 15} earlier`);
28
+ }
29
+ if (diagnostics?.engineLogDropped) {
30
+ lines.push(` … ${diagnostics.engineLogDropped} more not kept`);
31
+ }
32
+ lines.push('');
33
+ }
34
+ return lines;
35
+ }
@@ -31,7 +31,7 @@ export type SpecterMatcherName = keyof GasMatchers | keyof ActorMatchers | keyof
31
31
  * Every Specter matcher. The compile-time check below fails the build if a
32
32
  * matcher is added to one of the matcher interfaces but not to this list.
33
33
  */
34
- export declare const SPECTER_MATCHER_NAMES: readonly ["toHaveAttributeValue", "toHaveAttributeChange", "toHaveGameplayTag", "toHaveGameplayEffect", "toHaveAppliedGameplayEffect", "toHaveGameplayAbility", "toHaveAbilityCooldown", "toHaveGameplayEffectStackCount", "toHaveGameplayEffectLevel", "toHaveAttributeBaseValue", "toBeExecutingAbility", "toHaveActivatedAbility", "toHaveGameplayTagCount", "toHaveAnyGameplayTags", "toHaveAllGameplayTags", "toHaveMovedFurtherThan", "toHaveLocation", "toHaveInputMappingContext", "toHaveInputActionValue", "toHavePlayerScore", "toBeNiagaraActive", "toHaveNiagaraAsset", "toBeAudioPlaying", "toHaveSoundAsset", "toBePhysicsSimulating", "toBePhysicsAsleep", "toHaveVelocity", "toHaveCameraFOV", "toBeCameraShaking", "toHaveCameraViewTarget", "toBeAINavigating", "toHaveTeamId", "toBeHostileTowards", "toBePossessed", "toBePlayerControlled", "toBeLocallyControlled", "toHaveController", "toBeFalling", "toBeSwimming", "toBeFlying", "toBeCrouching", "toBeMovingOnGround", "toHaveMovementMode", "toBeVisible", "toHavePropertyValue", "toBeInViewport", "toBeDestroyed", "toHaveCount", "toHaveText", "toHaveValue", "toContainText", "toBeEnabled", "toHaveMaterialScalarParameter", "toHaveMaterialVectorParameter", "toHaveMaterial", "toBeDynamicMaterial", "toHaveMaterialTextureParameter", "toHaveBlackboardValue", "toHaveAIState", "toBeMovingTowards", "toBeMovingAwayFrom", "toBeWithinDistance", "toBeFollowing", "toHaveLineOfSightTo", "toBeRunningBehaviorTree", "toBeInState", "toHaveBlackboardChange", "toHaveVisitedState", "toHaveFPS", "toHaveMinFPS", "toHaveFrameTimeBelow", "toHaveMemoryBelow", "toMaintainPerformanceBudget", "toHaveFrameTimeP95Below", "toHaveFrameTimeP99Below", "toHaveAverageFrameTimeBelow", "toHaveAverageFPSAbove", "toHaveOnePercentLowFPSAbove", "toHaveNoHitchesOver", "toHavePeakMemoryBelow", "toHaveMemoryGrowthBelow", "toHaveDrawCallsBelow"];
34
+ export declare const SPECTER_MATCHER_NAMES: readonly ["toHaveAttributeValue", "toHaveAttributeChange", "toHaveGameplayTag", "toHaveGameplayEffect", "toHaveAppliedGameplayEffect", "toHaveGameplayAbility", "toHaveAbilityCooldown", "toHaveGameplayEffectStackCount", "toHaveGameplayEffectLevel", "toHaveAttributeBaseValue", "toBeExecutingAbility", "toHaveActivatedAbility", "toHaveGameplayTagCount", "toHaveAnyGameplayTags", "toHaveAllGameplayTags", "toHaveMovedFurtherThan", "toHaveLocation", "toHaveRotation", "toBeFacing", "toHaveInputMappingContext", "toHaveInputActionValue", "toHavePlayerScore", "toBeNiagaraActive", "toHaveNiagaraAsset", "toBeAudioPlaying", "toHaveSoundAsset", "toBePhysicsSimulating", "toBePhysicsAsleep", "toHaveVelocity", "toHaveCameraFOV", "toBeCameraShaking", "toHaveCameraViewTarget", "toBeAINavigating", "toHaveTeamId", "toBeHostileTowards", "toBePossessed", "toBePlayerControlled", "toBeLocallyControlled", "toHaveController", "toBeFalling", "toBeSwimming", "toBeFlying", "toBeCrouching", "toBeMovingOnGround", "toHaveMovementMode", "toBeVisible", "toHavePropertyValue", "toBeInViewport", "toBeDestroyed", "toHaveCount", "toHaveText", "toHaveValue", "toContainText", "toBeEnabled", "toHaveMaterialScalarParameter", "toHaveMaterialVectorParameter", "toHaveMaterial", "toBeDynamicMaterial", "toHaveMaterialTextureParameter", "toHaveBlackboardValue", "toHaveAIState", "toBeMovingTowards", "toBeMovingAwayFrom", "toBeWithinDistance", "toBeFollowing", "toHaveLineOfSightTo", "toBeRunningBehaviorTree", "toBeInState", "toHaveBlackboardChange", "toHaveVisitedState", "toHaveFPS", "toHaveMinFPS", "toHaveFrameTimeBelow", "toHaveMemoryBelow", "toMaintainPerformanceBudget", "toHaveFrameTimeP95Below", "toHaveFrameTimeP99Below", "toHaveAverageFrameTimeBelow", "toHaveAverageFPSAbove", "toHaveOnePercentLowFPSAbove", "toHaveNoHitchesOver", "toHavePeakMemoryBelow", "toHaveMemoryGrowthBelow", "toHaveDrawCallsBelow"];
35
35
  export declare function isSpecterMatcher(name: string): boolean;
36
36
  /**
37
37
  * Parses Playwright's expect step title, e.g. `Expect "soft not toHaveGameplayTag"`.
@@ -17,7 +17,7 @@ exports.SPECTER_MATCHER_NAMES = [
17
17
  'toBeExecutingAbility', 'toHaveActivatedAbility', 'toHaveGameplayTagCount',
18
18
  'toHaveAnyGameplayTags', 'toHaveAllGameplayTags',
19
19
  // actor-matchers
20
- 'toHaveMovedFurtherThan', 'toHaveLocation', 'toHaveInputMappingContext', 'toHaveInputActionValue',
20
+ 'toHaveMovedFurtherThan', 'toHaveLocation', 'toHaveRotation', 'toBeFacing', 'toHaveInputMappingContext', 'toHaveInputActionValue',
21
21
  'toHavePlayerScore', 'toBeNiagaraActive', 'toHaveNiagaraAsset', 'toBeAudioPlaying', 'toHaveSoundAsset',
22
22
  'toBePhysicsSimulating', 'toBePhysicsAsleep', 'toHaveVelocity', 'toHaveCameraFOV', 'toBeCameraShaking',
23
23
  'toHaveCameraViewTarget', 'toBeAINavigating', 'toHaveTeamId', 'toBeHostileTowards', 'toBePossessed',
@@ -0,0 +1,417 @@
1
+ /**
2
+ * 3D vector representation matching Unreal Engine's FVector (in centimeters).
3
+ * Left-handed coordinate system (Z-Up, X-Forward, Y-Right).
4
+ * All components are optional and default to 0 when omitted.
5
+ */
6
+ export interface Vector3 {
7
+ x?: number;
8
+ y?: number;
9
+ z?: number;
10
+ }
11
+ /**
12
+ * 2D vector representation matching Unreal Engine's FVector2D.
13
+ */
14
+ export interface Vector2D {
15
+ X?: number;
16
+ Y?: number;
17
+ }
18
+ /**
19
+ * Euler angle rotation representation matching Unreal Engine's FRotator (in degrees).
20
+ * - Pitch: Rotation around Y-axis (nose up/down)
21
+ * - Yaw: Rotation around Z-axis (heading / compass, clockwise)
22
+ * - Roll: Rotation around X-axis (banking right/left)
23
+ * All components are optional and default to 0 when omitted.
24
+ */
25
+ export interface Rotator {
26
+ pitch?: number;
27
+ yaw?: number;
28
+ roll?: number;
29
+ }
30
+ /**
31
+ * Complete 3D transform matching Unreal Engine's FTransform.
32
+ */
33
+ export interface Transform {
34
+ location: Vector3;
35
+ rotation?: Rotator;
36
+ scale?: Vector3;
37
+ }
38
+ /**
39
+ * Resolves a partial or complete Vector3, defaulting undefined components (x, y, z) to 0.
40
+ */
41
+ export declare function resolveVector3(v?: Vector3 | null): {
42
+ x: number;
43
+ y: number;
44
+ z: number;
45
+ };
46
+ /**
47
+ * Resolves a partial or complete Rotator, defaulting undefined components (pitch, yaw, roll) to 0.
48
+ */
49
+ export declare function resolveRotator(r?: Rotator | null): {
50
+ pitch: number;
51
+ yaw: number;
52
+ roll: number;
53
+ };
54
+ /**
55
+ * Normalizes an angle in degrees to the [-180, 180) range, matching Unreal's FRotator::NormalizeAxis.
56
+ */
57
+ export declare function normalizeAxis(angleDeg: number): number;
58
+ /**
59
+ * Utilities for 3D vectors matching Unreal Engine coordinate math.
60
+ */
61
+ export declare const VectorUtils: {
62
+ /**
63
+ * Creates a Vector3 at (0, 0, 0).
64
+ */
65
+ zero: () => {
66
+ x: number;
67
+ y: number;
68
+ z: number;
69
+ };
70
+ /**
71
+ * Resolves a partial or complete Vector3, defaulting undefined components to 0.
72
+ */
73
+ resolve: typeof resolveVector3;
74
+ /**
75
+ * Adds an offset in a given direction vector: location + (direction * offset).
76
+ * Undefined x, y, z components default to 0.
77
+ */
78
+ addOffset: (location: Vector3, direction: Vector3, offset: number) => {
79
+ x: number;
80
+ y: number;
81
+ z: number;
82
+ };
83
+ /**
84
+ * Adds two vectors (A + B). Undefined components default to 0.
85
+ */
86
+ add: (a: Vector3, b: Vector3) => {
87
+ x: number;
88
+ y: number;
89
+ z: number;
90
+ };
91
+ /**
92
+ * Subtracts vector B from vector A (A - B). Undefined components default to 0.
93
+ */
94
+ subtract: (a: Vector3, b: Vector3) => {
95
+ x: number;
96
+ y: number;
97
+ z: number;
98
+ };
99
+ /** `a - b`: alias for subtract */
100
+ sub: (a: Vector3, b: Vector3) => {
101
+ x: number;
102
+ y: number;
103
+ z: number;
104
+ };
105
+ /**
106
+ * Multiplies a vector by a scalar. Undefined components default to 0.
107
+ */
108
+ multiply: (v: Vector3, scalar: number) => {
109
+ x: number;
110
+ y: number;
111
+ z: number;
112
+ };
113
+ /** `v * scalar`: alias for multiply */
114
+ scale: (v: Vector3, scalar: number) => {
115
+ x: number;
116
+ y: number;
117
+ z: number;
118
+ };
119
+ /**
120
+ * Divides a vector by a scalar. Returns (0, 0, 0) if scalar is 0.
121
+ */
122
+ divide: (v: Vector3, scalar: number) => {
123
+ x: number;
124
+ y: number;
125
+ z: number;
126
+ };
127
+ /**
128
+ * Calculates the Euclidean distance between two 3D vectors. Undefined components default to 0.
129
+ */
130
+ distance: (a: Vector3, b: Vector3) => number;
131
+ /**
132
+ * Calculates the 2D Euclidean distance on the ground plane (XY only). Undefined components default to 0.
133
+ */
134
+ distance2D: (a: Vector3, b: Vector3) => number;
135
+ /**
136
+ * Returns the magnitude / length of a 3D vector. Undefined components default to 0.
137
+ */
138
+ length: (v: Vector3) => number;
139
+ /**
140
+ * Returns the 2D magnitude on the XY plane. Undefined components default to 0.
141
+ */
142
+ length2D: (v: Vector3) => number;
143
+ /**
144
+ * Returns the squared length of a 3D vector. Undefined components default to 0.
145
+ */
146
+ lengthSquared: (v: Vector3) => number;
147
+ /**
148
+ * Returns a normalized unit vector (length = 1). Returns (0, 0, 0) if length is 0.
149
+ */
150
+ normalize: (v: Vector3) => {
151
+ x: number;
152
+ y: number;
153
+ z: number;
154
+ };
155
+ /**
156
+ * Returns the normalized direction vector from point `from` to point `to`.
157
+ * Undefined components default to 0.
158
+ */
159
+ direction: (from: Vector3, to: Vector3) => {
160
+ x: number;
161
+ y: number;
162
+ z: number;
163
+ };
164
+ /**
165
+ * Computes the dot product of two vectors (A · B). Undefined components default to 0.
166
+ */
167
+ dot: (a: Vector3, b: Vector3) => number;
168
+ /**
169
+ * Computes the cross product of two vectors (A × B) in Unreal's left-handed coordinate system.
170
+ * Undefined components default to 0.
171
+ */
172
+ cross: (a: Vector3, b: Vector3) => {
173
+ x: number;
174
+ y: number;
175
+ z: number;
176
+ };
177
+ /**
178
+ * Linearly interpolates between vector A and B by alpha. Undefined components default to 0.
179
+ */
180
+ lerp: (a: Vector3, b: Vector3, alpha: number) => {
181
+ x: number;
182
+ y: number;
183
+ z: number;
184
+ };
185
+ /**
186
+ * Checks if two vectors are approximately equal within a tolerance distance.
187
+ * Undefined components default to 0.
188
+ */
189
+ isNearlyEqual: (a: Vector3, b: Vector3, tolerance?: number) => boolean;
190
+ /**
191
+ * Converts a direction vector into an Unreal Engine FRotator (Roll = 0).
192
+ * Matches Unreal's `FVector::Rotation()` / `FRotationMatrix::MakeFromX()`.
193
+ */
194
+ toRotator: (direction: Vector3) => {
195
+ pitch: number;
196
+ yaw: number;
197
+ roll: number;
198
+ };
199
+ /**
200
+ * Calculates the FRotator required to face from point `from` towards point `to`.
201
+ * Identical to Unreal Engine's `UKismetMathLibrary::FindLookAtRotation`.
202
+ * Undefined components default to 0.
203
+ */
204
+ findLookAtRotation: (from: Vector3, to: Vector3) => {
205
+ pitch: number;
206
+ yaw: number;
207
+ roll: number;
208
+ };
209
+ /**
210
+ * Rotates a 3D vector by an Unreal FRotator.
211
+ * Matches Unreal Engine's `FRotator::RotateVector`.
212
+ * Undefined components default to 0.
213
+ */
214
+ rotate: (v: Vector3, rot: Rotator) => {
215
+ x: number;
216
+ y: number;
217
+ z: number;
218
+ };
219
+ };
220
+ /**
221
+ * Utilities for Euler rotations (Pitch, Yaw, Roll in degrees) matching Unreal Engine's FRotator.
222
+ */
223
+ export declare const RotatorUtils: {
224
+ /**
225
+ * Creates a Rotator at (pitch: 0, yaw: 0, roll: 0).
226
+ */
227
+ zero: () => {
228
+ pitch: number;
229
+ yaw: number;
230
+ roll: number;
231
+ };
232
+ /**
233
+ * Resolves a partial or complete Rotator, defaulting undefined components (pitch, yaw, roll) to 0.
234
+ */
235
+ resolve: typeof resolveRotator;
236
+ /**
237
+ * Constructs a Rotator from pitch, yaw, and optional roll. Defaults omitted parameters to 0.
238
+ */
239
+ make: (pitch?: number, yaw?: number, roll?: number) => {
240
+ pitch: number;
241
+ yaw: number;
242
+ roll: number;
243
+ };
244
+ /**
245
+ * Constructs a flat yaw-only Rotator (pitch: 0, roll: 0).
246
+ */
247
+ fromYaw: (yaw?: number) => {
248
+ pitch: number;
249
+ yaw: number;
250
+ roll: number;
251
+ };
252
+ /**
253
+ * Calculates the look-at rotation from a direction vector.
254
+ * Matches Unreal's `FVector::Rotation()`. Undefined components default to 0.
255
+ */
256
+ fromDirection: (dir: Vector3) => {
257
+ pitch: number;
258
+ yaw: number;
259
+ roll: number;
260
+ };
261
+ /**
262
+ * Calculates the rotation required to look from `from` towards `to`.
263
+ * Identical to Unreal Engine's `UKismetMathLibrary::FindLookAtRotation(Start, Target)`.
264
+ * Undefined components default to 0.
265
+ */
266
+ fromVectors: (from: Vector3, to: Vector3) => {
267
+ pitch: number;
268
+ yaw: number;
269
+ roll: number;
270
+ };
271
+ /**
272
+ * Alias for `fromVectors`: finds the look-at rotation from `start` to `target`.
273
+ */
274
+ findLookAtRotation: (start: Vector3, target: Vector3) => {
275
+ pitch: number;
276
+ yaw: number;
277
+ roll: number;
278
+ };
279
+ /**
280
+ * Computes the three unit axis vectors (Forward, Right, Up) for a given Rotator.
281
+ * Matches Unreal Engine's `FRotationMatrix(Rotator)`.
282
+ * Undefined components default to 0.
283
+ */
284
+ getAxes: (rot: Rotator) => {
285
+ fwd: {
286
+ x: number;
287
+ y: number;
288
+ z: number;
289
+ };
290
+ right: {
291
+ x: number;
292
+ y: number;
293
+ z: number;
294
+ };
295
+ up: {
296
+ x: number;
297
+ y: number;
298
+ z: number;
299
+ };
300
+ };
301
+ /**
302
+ * Returns the unit forward vector (+X) for this rotation.
303
+ * Matches Unreal Engine's `FRotator::Vector()`.
304
+ * Undefined components default to 0.
305
+ */
306
+ getForwardVector: (rot: Rotator) => {
307
+ x: number;
308
+ y: number;
309
+ z: number;
310
+ };
311
+ /**
312
+ * Returns the unit right vector (+Y) for this rotation.
313
+ */
314
+ getRightVector: (rot: Rotator) => {
315
+ x: number;
316
+ y: number;
317
+ z: number;
318
+ };
319
+ /**
320
+ * Returns the unit up vector (+Z) for this rotation.
321
+ */
322
+ getUpVector: (rot: Rotator) => {
323
+ x: number;
324
+ y: number;
325
+ z: number;
326
+ };
327
+ /**
328
+ * Normalizes all components (Pitch, Yaw, Roll) to [-180, 180) degrees.
329
+ * Matches Unreal's `FRotator::GetNormalized()`. Undefined components default to 0.
330
+ */
331
+ normalize: (rot: Rotator) => {
332
+ pitch: number;
333
+ yaw: number;
334
+ roll: number;
335
+ };
336
+ /**
337
+ * Calculates the angular difference (to - from) with all components normalized to [-180, 180).
338
+ * Undefined components default to 0.
339
+ */
340
+ delta: (from: Rotator, to: Rotator) => {
341
+ pitch: number;
342
+ yaw: number;
343
+ roll: number;
344
+ };
345
+ /**
346
+ * Calculates the absolute angular distance in degrees between two 3D orientations (0° to 180°).
347
+ * Undefined components default to 0.
348
+ */
349
+ angularDistance: (a: Rotator, b: Rotator) => number;
350
+ /**
351
+ * Calculates the absolute difference between two yaw angles in degrees (0° to 180°).
352
+ * Undefined components default to 0.
353
+ */
354
+ yawDifference: (a: Rotator | number, b: Rotator | number) => number;
355
+ /**
356
+ * Checks if two Rotators are approximately equal within a tolerance in degrees.
357
+ * Handles 360-degree wrapping (e.g. 179° and -179° are within 2° of each other).
358
+ * Undefined components default to 0.
359
+ */
360
+ isNearlyEqual: (a: Rotator, b: Rotator, toleranceDegrees?: number) => boolean;
361
+ /**
362
+ * Interpolates smoothly from Rotator A to B taking the shortest angular path.
363
+ * Undefined components default to 0.
364
+ */
365
+ lerp: (from: Rotator, to: Rotator, alpha: number) => {
366
+ pitch: number;
367
+ yaw: number;
368
+ roll: number;
369
+ };
370
+ };
371
+ /**
372
+ * Calculates the FRotator required to face from point `from` towards point `to`.
373
+ * Identical to Unreal Engine's `UKismetMathLibrary::FindLookAtRotation`.
374
+ * Undefined components default to 0.
375
+ */
376
+ export declare function findLookAtRotation(from: Vector3, to: Vector3): {
377
+ pitch: number;
378
+ yaw: number;
379
+ roll: number;
380
+ };
381
+ /**
382
+ * Alias for `findLookAtRotation`: calculates the rotation between two 3D positions.
383
+ * Undefined components default to 0.
384
+ */
385
+ export declare function getRotationBetween(from: Vector3, to: Vector3): {
386
+ pitch: number;
387
+ yaw: number;
388
+ roll: number;
389
+ };
390
+ /**
391
+ * Calculates the Euclidean distance between two 3D points.
392
+ * Undefined components default to 0.
393
+ */
394
+ export declare function calculateDistance(a: Vector3, b: Vector3): number;
395
+ /**
396
+ * Calculates the 2D Euclidean distance on the ground plane (XY only).
397
+ * Undefined components default to 0.
398
+ */
399
+ export declare function calculateDistance2D(a: Vector3, b: Vector3): number;
400
+ /**
401
+ * Normalizes all components of a Rotator to [-180, 180) degrees.
402
+ * Undefined components default to 0.
403
+ */
404
+ export declare function normalizeRotator(rot: Rotator): {
405
+ pitch: number;
406
+ yaw: number;
407
+ roll: number;
408
+ };
409
+ /**
410
+ * Calculates the angular delta between two Rotators (to - from), wrapping shortest-path to [-180, 180).
411
+ * Undefined components default to 0.
412
+ */
413
+ export declare function deltaRotator(from: Rotator, to: Rotator): {
414
+ pitch: number;
415
+ yaw: number;
416
+ roll: number;
417
+ };