@specter-automation/test 1.0.148 → 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.
@@ -8,6 +8,7 @@ import { ActorEventMap, EventPredicate, WaitForEventOptions } from "../events";
8
8
  import { SpecterInputSequence } from "../specter-input-sequence";
9
9
  import { InputConditionalOptions, SpecterCondition, ConditionFunction } from '../conditions/input-conditions';
10
10
  import type { BehaviorTrail } from "../specter-ai-trail";
11
+ import type { CollisionDescription, NavPathResult, OverlapResult, PerceptionResult, TraceResult } from "../specter-debug";
11
12
  export interface BlackboardValueResult {
12
13
  value: string;
13
14
  objectName?: string;
@@ -29,7 +30,11 @@ export interface PossessAsPlayerOptions {
29
30
  }
30
31
  export declare class ActorLocator<T = any> extends SpecterLocator<T> {
31
32
  waitForEvent<K extends keyof ActorEventMap>(eventName: K | (string & {}), optionsOrPredicate?: number | EventPredicate<K extends keyof ActorEventMap ? ActorEventMap[K] : any> | WaitForEventOptions<K extends keyof ActorEventMap ? ActorEventMap[K] : any>): Promise<K extends keyof ActorEventMap ? ActorEventMap[K] : any>;
32
- getLocation(): Promise<Vector3>;
33
+ getLocation(): Promise<Vector3 & {
34
+ x: number;
35
+ y: number;
36
+ z: number;
37
+ }>;
33
38
  /**
34
39
  * Calculates the Euclidean distance from this actor to another actor or 3D point.
35
40
  */
@@ -37,6 +42,32 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
37
42
  getForwardVector(): Promise<Vector3>;
38
43
  setLocation(location: Vector3): Promise<void>;
39
44
  setRotation(rotation: Rotator): Promise<void>;
45
+ /**
46
+ * Queries the engine for the actor's current 3D rotation (Pitch, Yaw, Roll in degrees).
47
+ */
48
+ getRotation(): Promise<Rotator & {
49
+ pitch: number;
50
+ yaw: number;
51
+ roll: number;
52
+ }>;
53
+ /**
54
+ * Calculates the rotation required for this actor to face towards another actor or 3D point.
55
+ * Identical to Unreal Engine's FindLookAtRotation(this.Location, target.Location).
56
+ */
57
+ getRotationTo(target: ActorLocator | Vector3): Promise<Rotator>;
58
+ /**
59
+ * Rotates this actor to face directly towards another actor or 3D target point.
60
+ * Returns the target Rotator that was set.
61
+ */
62
+ rotateTowards(target: ActorLocator | Vector3): Promise<Rotator>;
63
+ /**
64
+ * Checks if this actor is facing towards a target actor or 3D point within an angular tolerance in degrees.
65
+ *
66
+ * @param target Target actor or 3D coordinate.
67
+ * @param toleranceDegrees Angular tolerance in degrees (default: 10°).
68
+ * @param planarOnly If true (default), compares yaw only on the ground plane. If false, compares full 3D orientation.
69
+ */
70
+ isFacing(target: ActorLocator | Vector3, toleranceDegrees?: number, planarOnly?: boolean): Promise<boolean>;
40
71
  setTransform(transform: Transform): Promise<void>;
41
72
  highlight(stateInfo?: string): Promise<void>;
42
73
  /**
@@ -371,7 +402,8 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
371
402
  z: number;
372
403
  }>;
373
404
  /**
374
- * Retrieves all Gameplay Tags owned by this Actor (requires IGameplayTagAssetInterface).
405
+ * Retrieves all Gameplay Tags owned by this Actor: the ones it reports (IGameplayTagAssetInterface) and its
406
+ * ability system's (loose tags, tags granted by effects).
375
407
  */
376
408
  getGameplayTags(): Promise<string[]>;
377
409
  /**
@@ -397,8 +429,39 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
397
429
  getBlackboardActor<A extends RegisteredActorClasses | (string & {}) = any>(keyName: string): Promise<ActorLocator<A> | null>;
398
430
  /**
399
431
  * Checks if this AI Actor / Controller has Line of Sight to a target Actor.
400
- */
401
- hasLineOfSightTo(target: ActorLocator | string): Promise<boolean>;
432
+ * By default this is the controller's own check, traced on Visibility. `channel` traces on another collision
433
+ * channel instead: `'AISight'` is the one AI sight uses (the AI System's Default Sight Collision Channel), or a
434
+ * project channel by name. `traceTo` says what's in the way.
435
+ */
436
+ hasLineOfSightTo(target: ActorLocator | string, options?: {
437
+ channel?: string;
438
+ }): Promise<boolean>;
439
+ /**
440
+ * Traces a line from this actor (its eyes, unless `fromEyes: false`) to another actor or a point on a collision
441
+ * channel: whether it's clear and, if not, the first thing in the way with its collision settings (profile,
442
+ * object type, response to the channel).
443
+ * `channel`: 'Visibility' (default), 'Camera', 'AISight' (what AI sight traces on), or a project channel's name.
444
+ */
445
+ traceTo(target: SpecterLocator | Vector3, options?: {
446
+ channel?: string;
447
+ fromEyes?: boolean;
448
+ }): Promise<TraceResult>;
449
+ /**
450
+ * Whether this AI perceives another actor by sight right now and, if not, why: out of range, outside its view,
451
+ * not an affiliation its sight detects, or something in the way (traced on the AI sight channel).
452
+ */
453
+ aiPerceives(target: SpecterLocator): Promise<PerceptionResult>;
454
+ /** The navmesh path from this actor to a point or another actor (found, partial, length, points), and what its AI's path following is doing. */
455
+ getNavPath(goal: SpecterLocator | Vector3): Promise<NavPathResult>;
456
+ /** What this actor's collision components overlap right now. */
457
+ getOverlappingActors(): Promise<OverlapResult>;
458
+ /**
459
+ * This actor's collision components and their settings: collision profile, object type, overlap events,
460
+ * whether they affect navigation, and the response to each named channel (or only `channel`).
461
+ */
462
+ getCollisionResponses(options?: {
463
+ channel?: string;
464
+ }): Promise<CollisionDescription[]>;
402
465
  /**
403
466
  * Checks if this AI Actor / Controller is running a specific Behavior Tree asset.
404
467
  */
@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
39
39
  exports.ActorLocator = void 0;
40
40
  const component_registry_1 = require("../component-registry");
41
41
  const specter_locator_1 = require("../locators/specter-locator");
42
+ const specter_client_1 = require("../specter-client");
42
43
  const widget_locator_1 = require("./widget-locator");
43
44
  const ai_controller_locator_1 = require("./ai-controller-locator");
44
45
  const input_conditions_1 = require("../conditions/input-conditions");
@@ -50,7 +51,11 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
50
51
  async getLocation() {
51
52
  // We know this is safe because the user explicitly cast it to an actor
52
53
  const data = await this.callFunction("K2_GetActorLocation");
53
- return data;
54
+ return {
55
+ x: data?.x ?? 0,
56
+ y: data?.y ?? 0,
57
+ z: data?.z ?? 0
58
+ };
54
59
  }
55
60
  /**
56
61
  * Calculates the Euclidean distance from this actor to another actor or 3D point.
@@ -74,22 +79,84 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
74
79
  }
75
80
  async setLocation(location) {
76
81
  await this.callFunction("K2_SetActorLocation", {
77
- NewLocation: { X: location.x, Y: location.y, Z: location.z },
82
+ NewLocation: { X: location.x ?? 0, Y: location.y ?? 0, Z: location.z ?? 0 },
78
83
  bSweep: false,
79
84
  bTeleport: true
80
85
  });
81
86
  }
82
87
  async setRotation(rotation) {
83
88
  await this.callFunction("K2_SetActorRotation", {
84
- NewRotation: { Pitch: rotation.pitch, Yaw: rotation.yaw, Roll: rotation.roll },
89
+ NewRotation: { Pitch: rotation.pitch ?? 0, Yaw: rotation.yaw ?? 0, Roll: rotation.roll ?? 0 },
85
90
  bTeleportPhysics: true
86
91
  });
87
92
  }
93
+ /**
94
+ * Queries the engine for the actor's current 3D rotation (Pitch, Yaw, Roll in degrees).
95
+ */
96
+ async getRotation() {
97
+ const data = await this.callFunction("K2_GetActorRotation");
98
+ return {
99
+ pitch: data?.pitch ?? 0,
100
+ yaw: data?.yaw ?? 0,
101
+ roll: data?.roll ?? 0
102
+ };
103
+ }
104
+ /**
105
+ * Calculates the rotation required for this actor to face towards another actor or 3D point.
106
+ * Identical to Unreal Engine's FindLookAtRotation(this.Location, target.Location).
107
+ */
108
+ async getRotationTo(target) {
109
+ const myLoc = await this.getLocation();
110
+ let targetLoc;
111
+ if (target instanceof ActorLocator) {
112
+ targetLoc = await target.getLocation();
113
+ }
114
+ else {
115
+ targetLoc = target;
116
+ }
117
+ return specter_client_1.RotatorUtils.fromVectors(myLoc, targetLoc);
118
+ }
119
+ /**
120
+ * Rotates this actor to face directly towards another actor or 3D target point.
121
+ * Returns the target Rotator that was set.
122
+ */
123
+ async rotateTowards(target) {
124
+ const targetRot = await this.getRotationTo(target);
125
+ await this.setRotation(targetRot);
126
+ return targetRot;
127
+ }
128
+ /**
129
+ * Checks if this actor is facing towards a target actor or 3D point within an angular tolerance in degrees.
130
+ *
131
+ * @param target Target actor or 3D coordinate.
132
+ * @param toleranceDegrees Angular tolerance in degrees (default: 10°).
133
+ * @param planarOnly If true (default), compares yaw only on the ground plane. If false, compares full 3D orientation.
134
+ */
135
+ async isFacing(target, toleranceDegrees = 10, planarOnly = true) {
136
+ const currentRot = await this.getRotation();
137
+ const targetRot = await this.getRotationTo(target);
138
+ if (planarOnly) {
139
+ return specter_client_1.RotatorUtils.yawDifference(currentRot, targetRot) <= toleranceDegrees;
140
+ }
141
+ return specter_client_1.RotatorUtils.angularDistance(currentRot, targetRot) <= toleranceDegrees;
142
+ }
88
143
  async setTransform(transform) {
89
144
  await this.evaluate("SetTransform", {
90
- location: transform.location,
91
- rotation: transform.rotation,
92
- scale: transform.scale
145
+ location: {
146
+ x: transform.location?.x ?? 0,
147
+ y: transform.location?.y ?? 0,
148
+ z: transform.location?.z ?? 0
149
+ },
150
+ rotation: transform.rotation ? {
151
+ pitch: transform.rotation.pitch ?? 0,
152
+ yaw: transform.rotation.yaw ?? 0,
153
+ roll: transform.rotation.roll ?? 0
154
+ } : undefined,
155
+ scale: transform.scale ? {
156
+ x: transform.scale.x ?? 1,
157
+ y: transform.scale.y ?? 1,
158
+ z: transform.scale.z ?? 1
159
+ } : undefined
93
160
  });
94
161
  }
95
162
  async highlight(stateInfo = "Status: Nominal") {
@@ -896,7 +963,8 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
896
963
  return response.data?.goalLocation ?? { x: 0, y: 0, z: 0 };
897
964
  }
898
965
  /**
899
- * Retrieves all Gameplay Tags owned by this Actor (requires IGameplayTagAssetInterface).
966
+ * Retrieves all Gameplay Tags owned by this Actor: the ones it reports (IGameplayTagAssetInterface) and its
967
+ * ability system's (loose tags, tags granted by effects).
900
968
  */
901
969
  async getGameplayTags() {
902
970
  const response = await this.evaluate("GetGameplayTags", {});
@@ -920,7 +988,8 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
920
988
  * Returns an AiControllerLocator for this Actor's AIController.
921
989
  */
922
990
  aiController() {
923
- return new ai_controller_locator_1.AiControllerLocator(this.transport, [...this.pipeline]);
991
+ // The pawn's controller, so callFunction reaches the controller's functions
992
+ return new ai_controller_locator_1.AiControllerLocator(this.transport, [...this.pipeline, { action: 'getController', value: '' }]);
924
993
  }
925
994
  /**
926
995
  * Reads a Blackboard variable from this Actor's AIController.
@@ -959,8 +1028,11 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
959
1028
  }
960
1029
  /**
961
1030
  * Checks if this AI Actor / Controller has Line of Sight to a target Actor.
1031
+ * By default this is the controller's own check, traced on Visibility. `channel` traces on another collision
1032
+ * channel instead: `'AISight'` is the one AI sight uses (the AI System's Default Sight Collision Channel), or a
1033
+ * project channel by name. `traceTo` says what's in the way.
962
1034
  */
963
- async hasLineOfSightTo(target) {
1035
+ async hasLineOfSightTo(target, options) {
964
1036
  let payload = {};
965
1037
  if (typeof target === 'string') {
966
1038
  payload = { targetTag: target, targetName: target };
@@ -968,9 +1040,56 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
968
1040
  else if (target && target.pipeline) {
969
1041
  payload = { targetLocatorPipeline: target.pipeline };
970
1042
  }
1043
+ if (options?.channel) {
1044
+ payload.channel = options.channel;
1045
+ }
971
1046
  const response = await this.evaluate("HasLineOfSightTo", payload);
972
1047
  return response.data?.hasLOS ?? false;
973
1048
  }
1049
+ /**
1050
+ * Traces a line from this actor (its eyes, unless `fromEyes: false`) to another actor or a point on a collision
1051
+ * channel: whether it's clear and, if not, the first thing in the way with its collision settings (profile,
1052
+ * object type, response to the channel).
1053
+ * `channel`: 'Visibility' (default), 'Camera', 'AISight' (what AI sight traces on), or a project channel's name.
1054
+ */
1055
+ async traceTo(target, options) {
1056
+ const payload = { channel: options?.channel ?? 'Visibility', fromEyes: options?.fromEyes ?? true };
1057
+ if (target instanceof specter_locator_1.SpecterLocator) {
1058
+ payload.targetLocatorPipeline = target.pipeline;
1059
+ }
1060
+ else {
1061
+ payload.point = target;
1062
+ }
1063
+ const response = await this.evaluate("TraceTo", payload);
1064
+ return response.data;
1065
+ }
1066
+ /**
1067
+ * Whether this AI perceives another actor by sight right now and, if not, why: out of range, outside its view,
1068
+ * not an affiliation its sight detects, or something in the way (traced on the AI sight channel).
1069
+ */
1070
+ async aiPerceives(target) {
1071
+ const response = await this.evaluate("AIPerceives", { targetLocatorPipeline: target.pipeline });
1072
+ return response.data;
1073
+ }
1074
+ /** The navmesh path from this actor to a point or another actor (found, partial, length, points), and what its AI's path following is doing. */
1075
+ async getNavPath(goal) {
1076
+ const payload = goal instanceof specter_locator_1.SpecterLocator ? { targetLocatorPipeline: goal.pipeline } : { goal };
1077
+ const response = await this.evaluate("GetNavPath", payload);
1078
+ return response.data;
1079
+ }
1080
+ /** What this actor's collision components overlap right now. */
1081
+ async getOverlappingActors() {
1082
+ const response = await this.evaluate("GetOverlappingActors", {});
1083
+ return response.data;
1084
+ }
1085
+ /**
1086
+ * This actor's collision components and their settings: collision profile, object type, overlap events,
1087
+ * whether they affect navigation, and the response to each named channel (or only `channel`).
1088
+ */
1089
+ async getCollisionResponses(options) {
1090
+ const response = await this.evaluate("GetCollisionResponses", options?.channel ? { channel: options.channel } : {});
1091
+ return (response.data?.components ?? []);
1092
+ }
974
1093
  /**
975
1094
  * Checks if this AI Actor / Controller is running a specific Behavior Tree asset.
976
1095
  */
@@ -1,5 +1,6 @@
1
1
  import { SpecterLocator } from "../locators/specter-locator";
2
2
  import type { BehaviorTrail } from "../specter-ai-trail";
3
+ import type { PerceptionResult } from "../specter-debug";
3
4
  import { ActorLocator, type BlackboardValueResult } from "./actor-locator";
4
5
  import type { RegisteredActorClasses } from "../specter-client";
5
6
  export declare class AiControllerLocator extends SpecterLocator {
@@ -14,7 +15,12 @@ export declare class AiControllerLocator extends SpecterLocator {
14
15
  }): Promise<BehaviorTrail>;
15
16
  getBlackboardValue(keyName: string): Promise<BlackboardValueResult>;
16
17
  getBlackboardActor<A extends RegisteredActorClasses | (string & {}) = any>(keyName: string): Promise<ActorLocator<A> | null>;
17
- hasLineOfSightTo(target: any): Promise<boolean>;
18
+ /** See ActorLocator.hasLineOfSightTo: `channel: 'AISight'` traces on the channel AI sight uses */
19
+ hasLineOfSightTo(target: any, options?: {
20
+ channel?: string;
21
+ }): Promise<boolean>;
22
+ /** Whether this AI perceives another actor by sight right now and, if not, why (see ActorLocator.aiPerceives) */
23
+ aiPerceives(target: SpecterLocator): Promise<PerceptionResult>;
18
24
  isAINavigating(): Promise<boolean>;
19
25
  getAINavGoal(): Promise<{
20
26
  x: number;
@@ -48,7 +48,8 @@ class AiControllerLocator extends specter_locator_1.SpecterLocator {
48
48
  const result = await this.getBlackboardValue(keyName);
49
49
  return result.toActor();
50
50
  }
51
- async hasLineOfSightTo(target) {
51
+ /** See ActorLocator.hasLineOfSightTo: `channel: 'AISight'` traces on the channel AI sight uses */
52
+ async hasLineOfSightTo(target, options) {
52
53
  let payload = {};
53
54
  if (typeof target === 'string') {
54
55
  payload = { targetTag: target, targetName: target };
@@ -56,9 +57,17 @@ class AiControllerLocator extends specter_locator_1.SpecterLocator {
56
57
  else if (target && target.pipeline) {
57
58
  payload = { targetLocatorPipeline: target.pipeline };
58
59
  }
60
+ if (options?.channel) {
61
+ payload.channel = options.channel;
62
+ }
59
63
  const response = await this.evaluate("HasLineOfSightTo", payload);
60
64
  return response.data?.hasLOS ?? false;
61
65
  }
66
+ /** Whether this AI perceives another actor by sight right now and, if not, why (see ActorLocator.aiPerceives) */
67
+ async aiPerceives(target) {
68
+ const response = await this.evaluate("AIPerceives", { targetLocatorPipeline: target.pipeline });
69
+ return response.data;
70
+ }
62
71
  async isAINavigating() {
63
72
  const response = await this.evaluate("IsAINavigating", {});
64
73
  return response.data?.isNavigating ?? false;
@@ -219,7 +219,24 @@ class SpecterLocator {
219
219
  * Argument types, required vs optional parameters, and return types are strictly validated.
220
220
  */
221
221
  callFunction = (async (functionName, ...args) => {
222
- const payloadArgs = args.length > 0 ? args[0] : {};
222
+ // A locator passed as a parameter goes as its pipeline: the engine resolves it to the object
223
+ const serializeArg = (value) => {
224
+ if (value instanceof SpecterLocator) {
225
+ return { pipeline: value.pipeline };
226
+ }
227
+ if (Array.isArray(value)) {
228
+ return value.map(serializeArg);
229
+ }
230
+ if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
231
+ const out = {};
232
+ for (const [key, inner] of Object.entries(value)) {
233
+ out[key] = serializeArg(inner);
234
+ }
235
+ return out;
236
+ }
237
+ return value;
238
+ };
239
+ const payloadArgs = serializeArg(args.length > 0 ? args[0] : {});
223
240
  // Explicitly map args to the 'parameters' key!
224
241
  const response = await this.evaluate("CallFunction", {
225
242
  functionName: functionName,
@@ -7,6 +7,7 @@ import { SpecterInputSequence } from './specter-input-sequence';
7
7
  import { SpecterNetwork } from './specter-network';
8
8
  import { SpecterPreview } from './specter-preview';
9
9
  import { type MeasurePerformanceOptions, type PerformanceCapture } from './specter-perf';
10
+ import type { EngineLog, StateHistory } from './specter-debug';
10
11
  export interface SpecterRegistry {
11
12
  }
12
13
  export interface SpecterFunctionRegistry {
@@ -129,11 +130,9 @@ export interface SpecterDiagnosticsReport {
129
130
  deltaSeconds: number;
130
131
  };
131
132
  }
132
- export interface Vector3 {
133
- x: number;
134
- y: number;
135
- z: number;
136
- }
133
+ export type { Vector3, Vector2D, Rotator, Transform } from './specter-math';
134
+ export { VectorUtils, RotatorUtils, resolveVector3, resolveRotator, normalizeAxis, findLookAtRotation, getRotationBetween, calculateDistance, calculateDistance2D, normalizeRotator, deltaRotator } from './specter-math';
135
+ import type { Vector3, Rotator } from './specter-math';
137
136
  export interface LinearColor {
138
137
  R?: number;
139
138
  G?: number;
@@ -147,23 +146,6 @@ export interface Color {
147
146
  A?: number;
148
147
  Hex?: string;
149
148
  }
150
- export interface Vector2D {
151
- X?: number;
152
- Y?: number;
153
- }
154
- export declare const VectorUtils: {
155
- addOffset: (location: Vector3, direction: Vector3, offset: number) => Vector3;
156
- };
157
- export interface Rotator {
158
- pitch: number;
159
- yaw: number;
160
- roll: number;
161
- }
162
- export interface Transform {
163
- location: Vector3;
164
- rotation?: Rotator;
165
- scale?: Vector3;
166
- }
167
149
  export interface HitResult {
168
150
  bblockinghit?: boolean;
169
151
  bstartpenetrating?: boolean;
@@ -291,6 +273,26 @@ export declare class SpecterWorld {
291
273
  toString(): string;
292
274
  toSelectorString(): string;
293
275
  static connect(url?: string): Promise<SpecterWorld>;
276
+ /**
277
+ * The engine's warnings and errors (the output log's yellow and red lines) since the last test's cleanup:
278
+ * spawn failures, navigation, Blueprint and ability system complaints. Specter's own are left out; a line logged
279
+ * again is counted (`count`). A failing test's diagnostics report shows them too.
280
+ */
281
+ getEngineLog(options?: {
282
+ max?: number;
283
+ }): Promise<EngineLog>;
284
+ /**
285
+ * Where the test's actors (what it spawned, and the pawns spawned while it ran) were and how they were doing, four
286
+ * times a second: location, yaw, speed, health, their AI's path following. Times are seconds since the test
287
+ * started, the timeline's clock. `at`: just the sample nearest that time. `actor`: only actors whose name has it.
288
+ * The history is also written next to the test's timeline preview frames when it ends (state.json).
289
+ */
290
+ getStateHistory(options?: {
291
+ from?: number;
292
+ to?: number;
293
+ at?: number;
294
+ actor?: string;
295
+ }): Promise<StateHistory>;
294
296
  /**
295
297
  * Queries comprehensive runtime diagnostics from the engine, including
296
298
  * actor identity mapping, attribute/tag snapshots, spatial relations, and recent Flight Recorder events.
@@ -538,7 +540,8 @@ export declare class SpecterWorld {
538
540
  */
539
541
  loadLevelStream(levelName: string, makeVisible?: boolean): Promise<void>;
540
542
  /**
541
- * Opens a level (absolute travel) via UGameplayStatics::OpenLevel
543
+ * Opens a level via UGameplayStatics::OpenLevel (relative travel in Play-In-Editor, so the editor world is safe).
544
+ * @param options URL options, e.g. "?game=/Game/Modes/BP_Arena.BP_Arena_C"
542
545
  */
543
546
  loadLevel(levelName: string, options?: string): Promise<void>;
544
547
  /**
@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.SpecterWorld = exports.SpecterTransport = exports.VectorUtils = exports.SpecterEventType = void 0;
6
+ exports.SpecterWorld = exports.SpecterTransport = exports.deltaRotator = exports.normalizeRotator = exports.calculateDistance2D = exports.calculateDistance = exports.getRotationBetween = exports.findLookAtRotation = exports.normalizeAxis = exports.resolveRotator = exports.resolveVector3 = exports.RotatorUtils = exports.VectorUtils = exports.SpecterEventType = void 0;
7
7
  const ws_1 = __importDefault(require("ws"));
8
8
  const crypto_1 = __importDefault(require("crypto"));
9
9
  const locators_1 = require("./locators");
@@ -23,15 +23,18 @@ var SpecterEventType;
23
23
  /** An AI's logic moved, a blackboard key changed, or its tree started or finished (the AI trail) */
24
24
  SpecterEventType["AIState"] = "AIState";
25
25
  })(SpecterEventType || (exports.SpecterEventType = SpecterEventType = {}));
26
- exports.VectorUtils = {
27
- addOffset: (location, direction, offset) => {
28
- return {
29
- x: location.x + (direction.x * offset),
30
- y: location.y + (direction.y * offset),
31
- z: location.z + (direction.z * offset)
32
- };
33
- }
34
- };
26
+ var specter_math_1 = require("./specter-math");
27
+ Object.defineProperty(exports, "VectorUtils", { enumerable: true, get: function () { return specter_math_1.VectorUtils; } });
28
+ Object.defineProperty(exports, "RotatorUtils", { enumerable: true, get: function () { return specter_math_1.RotatorUtils; } });
29
+ Object.defineProperty(exports, "resolveVector3", { enumerable: true, get: function () { return specter_math_1.resolveVector3; } });
30
+ Object.defineProperty(exports, "resolveRotator", { enumerable: true, get: function () { return specter_math_1.resolveRotator; } });
31
+ Object.defineProperty(exports, "normalizeAxis", { enumerable: true, get: function () { return specter_math_1.normalizeAxis; } });
32
+ Object.defineProperty(exports, "findLookAtRotation", { enumerable: true, get: function () { return specter_math_1.findLookAtRotation; } });
33
+ Object.defineProperty(exports, "getRotationBetween", { enumerable: true, get: function () { return specter_math_1.getRotationBetween; } });
34
+ Object.defineProperty(exports, "calculateDistance", { enumerable: true, get: function () { return specter_math_1.calculateDistance; } });
35
+ Object.defineProperty(exports, "calculateDistance2D", { enumerable: true, get: function () { return specter_math_1.calculateDistance2D; } });
36
+ Object.defineProperty(exports, "normalizeRotator", { enumerable: true, get: function () { return specter_math_1.normalizeRotator; } });
37
+ Object.defineProperty(exports, "deltaRotator", { enumerable: true, get: function () { return specter_math_1.deltaRotator; } });
35
38
  // ==========================================
36
39
  // THE TRANSPORT LAYER (Hidden from End-User)
37
40
  // ==========================================
@@ -429,6 +432,30 @@ class SpecterWorld {
429
432
  // Inject the connected transport into the new world
430
433
  return new SpecterWorld(transport);
431
434
  }
435
+ /**
436
+ * The engine's warnings and errors (the output log's yellow and red lines) since the last test's cleanup:
437
+ * spawn failures, navigation, Blueprint and ability system complaints. Specter's own are left out; a line logged
438
+ * again is counted (`count`). A failing test's diagnostics report shows them too.
439
+ */
440
+ async getEngineLog(options) {
441
+ const res = await this.evaluate("GetEngineLog", { max: options?.max ?? 100 });
442
+ return (res?.data ?? { entries: [], dropped: 0 });
443
+ }
444
+ /**
445
+ * Where the test's actors (what it spawned, and the pawns spawned while it ran) were and how they were doing, four
446
+ * times a second: location, yaw, speed, health, their AI's path following. Times are seconds since the test
447
+ * started, the timeline's clock. `at`: just the sample nearest that time. `actor`: only actors whose name has it.
448
+ * The history is also written next to the test's timeline preview frames when it ends (state.json).
449
+ */
450
+ async getStateHistory(options) {
451
+ const res = await this.evaluate("GetStateHistory", {
452
+ from: options?.from ?? -1,
453
+ to: options?.to ?? -1,
454
+ at: options?.at ?? -1,
455
+ actor: options?.actor ?? '',
456
+ });
457
+ return (res?.data ?? { interval: 0.25, classes: {} });
458
+ }
432
459
  /**
433
460
  * Queries comprehensive runtime diagnostics from the engine, including
434
461
  * actor identity mapping, attribute/tag snapshots, spatial relations, and recent Flight Recorder events.
@@ -551,7 +578,15 @@ class SpecterWorld {
551
578
  this.transport.sendCommand({
552
579
  command: 'ListenForGlobalEvent',
553
580
  payload: { eventName: String(eventName) }
554
- }).catch(() => { });
581
+ }).catch((error) => {
582
+ // A plugin from before ListenForGlobalEvent still broadcasts MapLoaded and timeline events: keep waiting
583
+ const message = error instanceof Error ? error.message : String(error);
584
+ if (/Unknown command/i.test(message))
585
+ return;
586
+ clearTimeout(timer);
587
+ this.transport.removeEventListener(eventKey, listener);
588
+ reject(new Error(`Specter: can't wait for world event [${String(eventName)}]: ${message}`));
589
+ });
555
590
  });
556
591
  }
557
592
  async joinHost(ipAddress, expectedMap) {
@@ -688,8 +723,16 @@ class SpecterWorld {
688
723
  // Generate a unique tag if the user didn't provide one
689
724
  const uniqueId = crypto_1.default.randomBytes(4).toString('hex');
690
725
  const tag = options?.tag || `Spawned_${uniqueId}`;
691
- const location = options?.location || { x: 0, y: 0, z: 0 };
692
- const rotation = options?.rotation || { pitch: 0, yaw: 0, roll: 0 };
726
+ const location = {
727
+ x: options?.location?.x ?? 0,
728
+ y: options?.location?.y ?? 0,
729
+ z: options?.location?.z ?? 0
730
+ };
731
+ const rotation = {
732
+ pitch: options?.rotation?.pitch ?? 0,
733
+ yaw: options?.rotation?.yaw ?? 0,
734
+ roll: options?.rotation?.roll ?? 0
735
+ };
693
736
  const assetPath = String(classNameOrAssetPath);
694
737
  const assetName = assetPath.split('/').pop()?.split('.')[0];
695
738
  const properties = options?.properties;
@@ -995,11 +1038,12 @@ class SpecterWorld {
995
1038
  });
996
1039
  }
997
1040
  /**
998
- * Opens a level (absolute travel) via UGameplayStatics::OpenLevel
1041
+ * Opens a level via UGameplayStatics::OpenLevel (relative travel in Play-In-Editor, so the editor world is safe).
1042
+ * @param options URL options, e.g. "?game=/Game/Modes/BP_Arena.BP_Arena_C"
999
1043
  */
1000
1044
  async loadLevel(levelName, options = "") {
1001
1045
  await test_1.default.step(`Specter: Load Level [${levelName}]`, async () => {
1002
- await this.evaluate("OpenLevel", { levelName, options });
1046
+ await this.evaluate("LoadLevel", { levelName, options });
1003
1047
  });
1004
1048
  }
1005
1049
  /**