@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.
@@ -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,49 +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
- /**
155
- * Vector maths for the plain `{ x, y, z }` objects Specter returns (TypeScript has no operator overloading,
156
- * so `a + b` on two vectors won't work). Every function returns a new vector and leaves its inputs alone.
157
- *
158
- * @example
159
- * const { add, distance2D } = VectorUtils;
160
- * await boss.setLocation(add(home, { x: 2100, y: 0, z: 0 }));
161
- * expect(distance2D(await hero.getLocation(), start)).toBeLessThan(40);
162
- */
163
- export declare const VectorUtils: {
164
- /** `a + b` */
165
- add: (a: Vector3, b: Vector3) => Vector3;
166
- /** `a - b`: the vector from `b` to `a` */
167
- sub: (a: Vector3, b: Vector3) => Vector3;
168
- /** `v * scalar` */
169
- scale: (v: Vector3, scalar: number) => Vector3;
170
- /** Length of `v` */
171
- length: (v: Vector3) => number;
172
- /** `v` scaled to length 1; a zero vector stays zero */
173
- normalize: (v: Vector3) => Vector3;
174
- /** Dot product of `a` and `b` */
175
- dot: (a: Vector3, b: Vector3) => number;
176
- /** Distance between `a` and `b` */
177
- distance: (a: Vector3, b: Vector3) => number;
178
- /** Distance between `a` and `b` on the ground (x and y only), so height doesn't count */
179
- distance2D: (a: Vector3, b: Vector3) => number;
180
- /** `location + direction * offset`: a point `offset` units along `direction` from `location` */
181
- addOffset: (location: Vector3, direction: Vector3, offset: number) => Vector3;
182
- };
183
- export interface Rotator {
184
- pitch: number;
185
- yaw: number;
186
- roll: number;
187
- }
188
- export interface Transform {
189
- location: Vector3;
190
- rotation?: Rotator;
191
- scale?: Vector3;
192
- }
193
149
  export interface HitResult {
194
150
  bblockinghit?: boolean;
195
151
  bstartpenetrating?: boolean;
@@ -317,6 +273,26 @@ export declare class SpecterWorld {
317
273
  toString(): string;
318
274
  toSelectorString(): string;
319
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>;
320
296
  /**
321
297
  * Queries comprehensive runtime diagnostics from the engine, including
322
298
  * actor identity mapping, attribute/tag snapshots, spatial relations, and recent Flight Recorder events.
@@ -564,7 +540,8 @@ export declare class SpecterWorld {
564
540
  */
565
541
  loadLevelStream(levelName: string, makeVisible?: boolean): Promise<void>;
566
542
  /**
567
- * 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"
568
545
  */
569
546
  loadLevel(levelName: string, options?: string): Promise<void>;
570
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,44 +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
- /**
27
- * Vector maths for the plain `{ x, y, z }` objects Specter returns (TypeScript has no operator overloading,
28
- * so `a + b` on two vectors won't work). Every function returns a new vector and leaves its inputs alone.
29
- *
30
- * @example
31
- * const { add, distance2D } = VectorUtils;
32
- * await boss.setLocation(add(home, { x: 2100, y: 0, z: 0 }));
33
- * expect(distance2D(await hero.getLocation(), start)).toBeLessThan(40);
34
- */
35
- exports.VectorUtils = {
36
- /** `a + b` */
37
- add: (a, b) => ({ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z }),
38
- /** `a - b`: the vector from `b` to `a` */
39
- sub: (a, b) => ({ x: a.x - b.x, y: a.y - b.y, z: a.z - b.z }),
40
- /** `v * scalar` */
41
- scale: (v, scalar) => ({ x: v.x * scalar, y: v.y * scalar, z: v.z * scalar }),
42
- /** Length of `v` */
43
- length: (v) => Math.hypot(v.x, v.y, v.z),
44
- /** `v` scaled to length 1; a zero vector stays zero */
45
- normalize: (v) => {
46
- const len = Math.hypot(v.x, v.y, v.z);
47
- return len === 0 ? { x: 0, y: 0, z: 0 } : { x: v.x / len, y: v.y / len, z: v.z / len };
48
- },
49
- /** Dot product of `a` and `b` */
50
- dot: (a, b) => a.x * b.x + a.y * b.y + a.z * b.z,
51
- /** Distance between `a` and `b` */
52
- distance: (a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z),
53
- /** Distance between `a` and `b` on the ground (x and y only), so height doesn't count */
54
- distance2D: (a, b) => Math.hypot(a.x - b.x, a.y - b.y),
55
- /** `location + direction * offset`: a point `offset` units along `direction` from `location` */
56
- addOffset: (location, direction, offset) => {
57
- return {
58
- x: location.x + (direction.x * offset),
59
- y: location.y + (direction.y * offset),
60
- z: location.z + (direction.z * offset)
61
- };
62
- }
63
- };
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; } });
64
38
  // ==========================================
65
39
  // THE TRANSPORT LAYER (Hidden from End-User)
66
40
  // ==========================================
@@ -458,6 +432,30 @@ class SpecterWorld {
458
432
  // Inject the connected transport into the new world
459
433
  return new SpecterWorld(transport);
460
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
+ }
461
459
  /**
462
460
  * Queries comprehensive runtime diagnostics from the engine, including
463
461
  * actor identity mapping, attribute/tag snapshots, spatial relations, and recent Flight Recorder events.
@@ -580,7 +578,15 @@ class SpecterWorld {
580
578
  this.transport.sendCommand({
581
579
  command: 'ListenForGlobalEvent',
582
580
  payload: { eventName: String(eventName) }
583
- }).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
+ });
584
590
  });
585
591
  }
586
592
  async joinHost(ipAddress, expectedMap) {
@@ -717,8 +723,16 @@ class SpecterWorld {
717
723
  // Generate a unique tag if the user didn't provide one
718
724
  const uniqueId = crypto_1.default.randomBytes(4).toString('hex');
719
725
  const tag = options?.tag || `Spawned_${uniqueId}`;
720
- const location = options?.location || { x: 0, y: 0, z: 0 };
721
- 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
+ };
722
736
  const assetPath = String(classNameOrAssetPath);
723
737
  const assetName = assetPath.split('/').pop()?.split('.')[0];
724
738
  const properties = options?.properties;
@@ -1024,11 +1038,12 @@ class SpecterWorld {
1024
1038
  });
1025
1039
  }
1026
1040
  /**
1027
- * 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"
1028
1043
  */
1029
1044
  async loadLevel(levelName, options = "") {
1030
1045
  await test_1.default.step(`Specter: Load Level [${levelName}]`, async () => {
1031
- await this.evaluate("OpenLevel", { levelName, options });
1046
+ await this.evaluate("LoadLevel", { levelName, options });
1032
1047
  });
1033
1048
  }
1034
1049
  /**