@specter-automation/test 1.0.149 → 1.0.151

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,7 @@
1
+ export declare function setActiveWorld(world: any): void;
2
+ export declare function getActiveWorld(): any;
3
+ export declare function setAiDiagnosticsFormatter(fn: (diag: any) => string): void;
4
+ export declare function captureSpecterFailure(world: any, testInfo: any, source?: string): Promise<void>;
5
+ export declare function extractFunctionParams(fn: any): string;
6
+ export declare function wrapTestFunction(fn: any): any;
7
+ export declare function wrapTestInstance<T extends (...args: any[]) => any>(targetTest: T): T;
@@ -0,0 +1,128 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.setActiveWorld = setActiveWorld;
4
+ exports.getActiveWorld = getActiveWorld;
5
+ exports.setAiDiagnosticsFormatter = setAiDiagnosticsFormatter;
6
+ exports.captureSpecterFailure = captureSpecterFailure;
7
+ exports.extractFunctionParams = extractFunctionParams;
8
+ exports.wrapTestFunction = wrapTestFunction;
9
+ exports.wrapTestInstance = wrapTestInstance;
10
+ let activeWorld = null;
11
+ let diagnosticsFormatter = null;
12
+ function setActiveWorld(world) {
13
+ activeWorld = world;
14
+ }
15
+ function getActiveWorld() {
16
+ return activeWorld;
17
+ }
18
+ function setAiDiagnosticsFormatter(fn) {
19
+ diagnosticsFormatter = fn;
20
+ }
21
+ async function captureSpecterFailure(world, testInfo, source = 'test') {
22
+ if (!world || !testInfo)
23
+ return;
24
+ if (testInfo._specterFailureCaptured)
25
+ return;
26
+ testInfo._specterFailureCaptured = true;
27
+ const title = testInfo.title || 'Unknown_Test';
28
+ const safeName = `Specter_Fail_${title.replace(/[^a-zA-Z0-9]/g, '_')}`;
29
+ try {
30
+ if (typeof world.takeScreenshot === 'function') {
31
+ await world.takeScreenshot(safeName, false, { attachmentName: 'Unreal Engine Viewport' });
32
+ }
33
+ }
34
+ catch (e) {
35
+ console.error(`[Specter] Failed to capture error screenshot (${source}):`, e);
36
+ }
37
+ try {
38
+ if (typeof world.getDiagnostics === 'function') {
39
+ const diagnostics = await world.getDiagnostics({ limit: 35 });
40
+ if (diagnostics) {
41
+ const formattedSummary = diagnosticsFormatter ? diagnosticsFormatter(diagnostics) : JSON.stringify(diagnostics, null, 2);
42
+ console.log('\n' + formattedSummary + '\n');
43
+ const alreadyAttached = testInfo.attachments?.some((a) => a.name.includes('Specter AI Diagnostics'));
44
+ if (!alreadyAttached && testInfo.attachments) {
45
+ testInfo.attachments.push({
46
+ name: 'Specter AI Diagnostics (JSON)',
47
+ contentType: 'application/json',
48
+ body: Buffer.from(JSON.stringify(diagnostics, null, 2))
49
+ });
50
+ testInfo.attachments.push({
51
+ name: 'Specter AI Diagnostics (Markdown)',
52
+ contentType: 'text/markdown',
53
+ body: Buffer.from(formattedSummary)
54
+ });
55
+ }
56
+ }
57
+ }
58
+ }
59
+ catch (e) {
60
+ console.error(`[Specter] Failed to capture AI diagnostics on test failure (${source}):`, e);
61
+ }
62
+ }
63
+ function extractFunctionParams(fn) {
64
+ const str = fn.toString();
65
+ const match = str.match(/^(?:async\s*)?(?:function\s*)?\s*\(([^)]*)\)/);
66
+ if (match)
67
+ return match[1];
68
+ const arrowMatch = str.match(/^(?:async\s*)?([a-zA-Z0-9_{}\s,]+)=>/);
69
+ if (arrowMatch)
70
+ return arrowMatch[1];
71
+ return "fixtures, testInfo";
72
+ }
73
+ function wrapTestFunction(fn) {
74
+ if (typeof fn !== "function")
75
+ return fn;
76
+ const params = extractFunctionParams(fn);
77
+ try {
78
+ const wrapperFactory = new Function("fn", "captureSpecterFailure", "getActiveWorld", `
79
+ return async function(${params}) {
80
+ try {
81
+ return await fn.apply(this, arguments);
82
+ } catch (err) {
83
+ const testInfo = (arguments.length > 1 && arguments[1]) ? arguments[1] : undefined;
84
+ const world = (testInfo && testInfo._specterWorld) || (arguments[0] && arguments[0].world) || (arguments[0] && arguments[0].server && arguments[0].server.world) || getActiveWorld();
85
+ if (world && testInfo) {
86
+ try {
87
+ await captureSpecterFailure(world, testInfo, 'test-body');
88
+ } catch (e) {}
89
+ }
90
+ throw err;
91
+ }
92
+ };
93
+ `);
94
+ return wrapperFactory(fn, captureSpecterFailure, getActiveWorld);
95
+ }
96
+ catch (e) {
97
+ return fn;
98
+ }
99
+ }
100
+ function wrapTestInstance(targetTest) {
101
+ const wrapCall = (originalFn) => {
102
+ return function (title, ...rest) {
103
+ if (rest.length > 0 && typeof rest[rest.length - 1] === "function") {
104
+ rest[rest.length - 1] = wrapTestFunction(rest[rest.length - 1]);
105
+ }
106
+ return originalFn.apply(this, [title, ...rest]);
107
+ };
108
+ };
109
+ const wrapped = wrapCall(targetTest);
110
+ Object.setPrototypeOf(wrapped, targetTest);
111
+ for (const key of Object.getOwnPropertyNames(targetTest)) {
112
+ const desc = Object.getOwnPropertyDescriptor(targetTest, key);
113
+ if (desc)
114
+ Object.defineProperty(wrapped, key, desc);
115
+ }
116
+ for (const modifier of ["only", "skip", "fixme", "fail"]) {
117
+ if (typeof targetTest[modifier] === "function") {
118
+ wrapped[modifier] = wrapCall(targetTest[modifier]);
119
+ Object.setPrototypeOf(wrapped[modifier], targetTest[modifier]);
120
+ }
121
+ }
122
+ const origExtend = targetTest.extend.bind(targetTest);
123
+ wrapped.extend = function (...args) {
124
+ const extended = origExtend(...args);
125
+ return wrapTestInstance(extended);
126
+ };
127
+ return wrapped;
128
+ }
@@ -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
  /**