@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.
- package/dist/core/failure-capture.d.ts +7 -0
- package/dist/core/failure-capture.js +128 -0
- package/dist/core/locators/actor-locator.d.ts +67 -4
- package/dist/core/locators/actor-locator.js +128 -9
- package/dist/core/locators/ai-controller-locator.d.ts +7 -1
- package/dist/core/locators/ai-controller-locator.js +10 -1
- package/dist/core/locators/specter-locator.js +18 -1
- package/dist/core/specter-client.d.ts +26 -49
- package/dist/core/specter-client.js +59 -44
- package/dist/core/specter-debug.d.ts +145 -0
- package/dist/core/specter-debug.js +35 -0
- package/dist/core/specter-matcher-report.d.ts +1 -1
- package/dist/core/specter-matcher-report.js +1 -1
- package/dist/core/specter-math.d.ts +417 -0
- package/dist/core/specter-math.js +522 -0
- package/dist/core/specter-preview.js +2 -1
- package/dist/core/specter-reporter.js +4 -2
- package/dist/core/test-wrapper.d.ts +2 -1
- package/dist/core/test-wrapper.js +27 -42
- package/dist/index.d.ts +2 -1
- package/dist/index.js +13 -1
- package/dist/matchers/actor-matchers.d.ts +51 -30
- package/dist/matchers/actor-matchers.js +93 -10
- package/dist/matchers/gas-matchers.d.ts +2 -0
- package/dist/matchers/gas-matchers.js +3 -0
- package/dist/matchers/instrument.js +21 -1
- package/package.json +1 -1
|
@@ -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 (
|
|
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
|
-
|
|
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
|
|
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:
|
|
91
|
-
|
|
92
|
-
|
|
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 (
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
133
|
-
|
|
134
|
-
|
|
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 (
|
|
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
|
/**
|