@specter-automation/test 1.0.107

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.
Files changed (47) hide show
  1. package/dist/core/component-registry.d.ts +12 -0
  2. package/dist/core/component-registry.js +25 -0
  3. package/dist/core/conditions/input-conditions.d.ts +81 -0
  4. package/dist/core/conditions/input-conditions.js +197 -0
  5. package/dist/core/events.d.ts +133 -0
  6. package/dist/core/events.js +6 -0
  7. package/dist/core/locators/actor-locator.d.ts +425 -0
  8. package/dist/core/locators/actor-locator.js +1006 -0
  9. package/dist/core/locators/ai-controller-locator.d.ts +6 -0
  10. package/dist/core/locators/ai-controller-locator.js +19 -0
  11. package/dist/core/locators/index.d.ts +6 -0
  12. package/dist/core/locators/index.js +22 -0
  13. package/dist/core/locators/movement-locator.d.ts +27 -0
  14. package/dist/core/locators/movement-locator.js +78 -0
  15. package/dist/core/locators/skeleton-locator.d.ts +13 -0
  16. package/dist/core/locators/skeleton-locator.js +35 -0
  17. package/dist/core/locators/specter-locator.d.ts +110 -0
  18. package/dist/core/locators/specter-locator.js +323 -0
  19. package/dist/core/locators/widget-locator.d.ts +104 -0
  20. package/dist/core/locators/widget-locator.js +297 -0
  21. package/dist/core/specter-client.d.ts +352 -0
  22. package/dist/core/specter-client.js +883 -0
  23. package/dist/core/specter-input-sequence.d.ts +96 -0
  24. package/dist/core/specter-input-sequence.js +180 -0
  25. package/dist/core/specter-keyboard.d.ts +21 -0
  26. package/dist/core/specter-keyboard.js +63 -0
  27. package/dist/core/specter-keys.d.ts +1 -0
  28. package/dist/core/specter-keys.js +2 -0
  29. package/dist/core/specter-network.d.ts +34 -0
  30. package/dist/core/specter-network.js +59 -0
  31. package/dist/core/specter-reporter.d.ts +23 -0
  32. package/dist/core/specter-reporter.js +403 -0
  33. package/dist/core/test-wrapper.d.ts +25 -0
  34. package/dist/core/test-wrapper.js +200 -0
  35. package/dist/index.d.ts +13 -0
  36. package/dist/index.js +29 -0
  37. package/dist/matchers/actor-matchers.d.ts +492 -0
  38. package/dist/matchers/actor-matchers.js +841 -0
  39. package/dist/matchers/gas-matchers.d.ts +198 -0
  40. package/dist/matchers/gas-matchers.js +539 -0
  41. package/dist/matchers/locator-matchers.d.ts +80 -0
  42. package/dist/matchers/locator-matchers.js +214 -0
  43. package/dist/matchers/material-matchers.d.ts +74 -0
  44. package/dist/matchers/material-matchers.js +295 -0
  45. package/dist/matchers/widget-matchers.d.ts +81 -0
  46. package/dist/matchers/widget-matchers.js +110 -0
  47. package/package.json +33 -0
@@ -0,0 +1,6 @@
1
+ import { SpecterLocator } from "../locators/specter-locator";
2
+ export declare class AiControllerLocator extends SpecterLocator {
3
+ isRunningBehaviorTree(treePath: string): Promise<boolean>;
4
+ getBlackboardValue(keyName: string): Promise<string>;
5
+ hasLineOfSightTo(targetName: string): Promise<boolean>;
6
+ }
@@ -0,0 +1,19 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.AiControllerLocator = void 0;
4
+ const specter_locator_1 = require("../locators/specter-locator");
5
+ class AiControllerLocator extends specter_locator_1.SpecterLocator {
6
+ async isRunningBehaviorTree(treePath) {
7
+ const response = await this.evaluate("IsRunningBehaviorTree", { treePath });
8
+ return response.data.isRunning;
9
+ }
10
+ async getBlackboardValue(keyName) {
11
+ const response = await this.evaluate("GetBlackboardValue", { keyName });
12
+ return response.data.value;
13
+ }
14
+ async hasLineOfSightTo(targetName) {
15
+ const response = await this.evaluate("HasLineOfSightTo", { targetName });
16
+ return response.data.hasLOS;
17
+ }
18
+ }
19
+ exports.AiControllerLocator = AiControllerLocator;
@@ -0,0 +1,6 @@
1
+ export * from './actor-locator';
2
+ export * from './specter-locator';
3
+ export * from './widget-locator';
4
+ export * from './skeleton-locator';
5
+ export * from './movement-locator';
6
+ export * from './ai-controller-locator';
@@ -0,0 +1,22 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
+ for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
+ };
16
+ Object.defineProperty(exports, "__esModule", { value: true });
17
+ __exportStar(require("./actor-locator"), exports);
18
+ __exportStar(require("./specter-locator"), exports);
19
+ __exportStar(require("./widget-locator"), exports);
20
+ __exportStar(require("./skeleton-locator"), exports);
21
+ __exportStar(require("./movement-locator"), exports);
22
+ __exportStar(require("./ai-controller-locator"), exports);
@@ -0,0 +1,27 @@
1
+ import { SpecterLocator } from "../locators/specter-locator";
2
+ export declare class MovementLocator extends SpecterLocator {
3
+ getVelocity(): Promise<{
4
+ x: number;
5
+ y: number;
6
+ z: number;
7
+ }>;
8
+ getMovementMode(): Promise<string>;
9
+ isFalling(): Promise<boolean>;
10
+ isFlying(): Promise<boolean>;
11
+ isSwimming(): Promise<boolean>;
12
+ isMovingOnGround(): Promise<boolean>;
13
+ getMaxWalkSpeed(): Promise<number>;
14
+ isCrouching(): Promise<boolean>;
15
+ waitForFalling(options?: {
16
+ timeout?: number;
17
+ }): Promise<void>;
18
+ waitForLanded(options?: {
19
+ timeout?: number;
20
+ }): Promise<any>;
21
+ waitForSwimming(options?: {
22
+ timeout?: number;
23
+ }): Promise<void>;
24
+ waitForFlying(options?: {
25
+ timeout?: number;
26
+ }): Promise<void>;
27
+ }
@@ -0,0 +1,78 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.MovementLocator = void 0;
4
+ const specter_locator_1 = require("../locators/specter-locator");
5
+ class MovementLocator extends specter_locator_1.SpecterLocator {
6
+ // Returns the exact current velocity of the actor
7
+ async getVelocity() {
8
+ const response = await this.evaluate('GetVelocity', {});
9
+ return response.data.velocity;
10
+ }
11
+ // Validates the current movement mode (e.g., 'Walking', 'Falling', 'Swimming', 'Flying')
12
+ async getMovementMode() {
13
+ const response = await this.evaluate('GetMovementMode', {});
14
+ return response.data?.movementMode ?? response.data?.mode ?? 'None';
15
+ }
16
+ // Quick helper specifically for jump/gravity validation
17
+ async isFalling() {
18
+ const response = await this.evaluate('IsFalling', {});
19
+ return response.data?.isFalling ?? false;
20
+ }
21
+ // Checks if character is flying
22
+ async isFlying() {
23
+ const response = await this.evaluate('IsFlying', {});
24
+ return response.data?.isFlying ?? false;
25
+ }
26
+ // Checks if character is swimming in a water body / physics volume
27
+ async isSwimming() {
28
+ const response = await this.evaluate('IsSwimming', {});
29
+ return response.data?.isSwimming ?? false;
30
+ }
31
+ // Checks if character is currently moving on ground
32
+ async isMovingOnGround() {
33
+ const response = await this.evaluate('IsMovingOnGround', {});
34
+ return response.data?.isMovingOnGround ?? false;
35
+ }
36
+ // Validates if a speed buff/debuff was applied correctly by GAS
37
+ async getMaxWalkSpeed() {
38
+ const response = await this.evaluate('GetMaxWalkSpeed', {});
39
+ return parseFloat(response.data.value);
40
+ }
41
+ // Checks if the character is currently crouching
42
+ async isCrouching() {
43
+ const response = await this.evaluate('IsCrouching', {});
44
+ return response.data?.isCrouching === true;
45
+ }
46
+ async waitForFalling(options) {
47
+ if (await this.isFalling())
48
+ return;
49
+ await this.waitForEvent('OnMovementModeChanged', {
50
+ timeout: options?.timeout ?? 5000,
51
+ predicate: (data) => data?.movementMode === 'Falling' || data?.isFalling === true
52
+ });
53
+ }
54
+ async waitForLanded(options) {
55
+ if (!await this.isFalling())
56
+ return {};
57
+ return await this.waitForEvent('OnLanded', {
58
+ timeout: options?.timeout ?? 5000
59
+ });
60
+ }
61
+ async waitForSwimming(options) {
62
+ if (await this.isSwimming())
63
+ return;
64
+ await this.waitForEvent('OnMovementModeChanged', {
65
+ timeout: options?.timeout ?? 5000,
66
+ predicate: (data) => data?.movementMode === 'Swimming' || data?.isSwimming === true
67
+ });
68
+ }
69
+ async waitForFlying(options) {
70
+ if (await this.isFlying())
71
+ return;
72
+ await this.waitForEvent('OnMovementModeChanged', {
73
+ timeout: options?.timeout ?? 5000,
74
+ predicate: (data) => data?.movementMode === 'Flying' || data?.isFlying === true
75
+ });
76
+ }
77
+ }
78
+ exports.MovementLocator = MovementLocator;
@@ -0,0 +1,13 @@
1
+ import { SpecterLocator } from "../locators/specter-locator";
2
+ export declare class SkeletonLocator extends SpecterLocator {
3
+ hasBone(boneName: string): Promise<boolean>;
4
+ getSocketLocation(socketName: string): Promise<{
5
+ x: number;
6
+ y: number;
7
+ z: number;
8
+ }>;
9
+ isMontagePlaying(montageName: string): Promise<boolean>;
10
+ getAnimPosition(): Promise<number>;
11
+ isPlayingMontage(montageClassPath: string): Promise<boolean>;
12
+ getCurrentMontageSection(): Promise<string>;
13
+ }
@@ -0,0 +1,35 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.SkeletonLocator = void 0;
4
+ const specter_locator_1 = require("../locators/specter-locator");
5
+ class SkeletonLocator extends specter_locator_1.SpecterLocator {
6
+ // Validates if a specific bone exists
7
+ async hasBone(boneName) {
8
+ const response = await this.evaluate('HasBone', { boneName });
9
+ return response.data.hasBone === true;
10
+ }
11
+ // Fetches the exact 3D world coordinates of a socket
12
+ async getSocketLocation(socketName) {
13
+ const response = await this.evaluate('GetSocketLocation', { socketName });
14
+ return response.data.location; // Assumes C++ returns { location: { x, y, z } }
15
+ }
16
+ // Validates if a specific Animation Montage is currently playing
17
+ async isMontagePlaying(montageName) {
18
+ const response = await this.evaluate('IsMontagePlaying', { montageName });
19
+ return response.data.isPlaying === true;
20
+ }
21
+ // Retrieves the current frame/time of the playing animation to test blend states
22
+ async getAnimPosition() {
23
+ const response = await this.evaluate('GetAnimPosition', {});
24
+ return response.data.position;
25
+ }
26
+ async isPlayingMontage(montageClassPath) {
27
+ const response = await this.evaluate("IsPlayingMontage", { montageClassPath });
28
+ return response.data.isPlaying;
29
+ }
30
+ async getCurrentMontageSection() {
31
+ const response = await this.evaluate("GetCurrentMontageSection", {});
32
+ return response.data.section;
33
+ }
34
+ }
35
+ exports.SkeletonLocator = SkeletonLocator;
@@ -0,0 +1,110 @@
1
+ import { SpecterTransport, SpecterWorld, SpecterFunctionRegistry } from "../specter-client";
2
+ import { EventPredicate, WaitForEventOptions } from "../events";
3
+ export interface LocatorStep {
4
+ action: string;
5
+ value: string;
6
+ exact?: boolean;
7
+ }
8
+ export interface FilterOptions {
9
+ hasComponent?: string;
10
+ withinRadius?: number;
11
+ x?: number;
12
+ y?: number;
13
+ z?: number;
14
+ property?: {
15
+ name: string;
16
+ value: string;
17
+ operator?: '===' | '!=' | '>' | '<' | '>=' | '<=' | 'contains' | 'regex';
18
+ };
19
+ }
20
+ export declare class SpecterLocator<T = any> {
21
+ pipeline: LocatorStep[];
22
+ protected transport: SpecterTransport;
23
+ constructor(transport: SpecterTransport, initialPipeline?: LocatorStep[]);
24
+ protected clone(): this;
25
+ get port(): string;
26
+ get portTag(): string;
27
+ /**
28
+ * Resolves the pipeline to a unique ID string for event binding.
29
+ */
30
+ protected get resolvedPath(): string;
31
+ /**
32
+ * Natively waits for a C++ UObject delegate to broadcast, with optional predicate filtering.
33
+ */
34
+ waitForEvent<T = any>(eventName: string, optionsOrPredicate?: number | EventPredicate<T> | WaitForEventOptions<T>): Promise<T>;
35
+ or(alternateLocator: SpecterLocator): this;
36
+ and(alternateLocator: SpecterLocator): this;
37
+ filter(options: FilterOptions): this;
38
+ /**
39
+ * Returns a locator pointing to a specific index in the current collection.
40
+ */
41
+ nth(index: number): this;
42
+ first(): this;
43
+ last(): this;
44
+ /**
45
+ * Returns an array of locators for every element matching the current query.
46
+ */
47
+ all(): Promise<this[]>;
48
+ count(bHideStep?: boolean): Promise<number>;
49
+ toString(): string;
50
+ /**
51
+ * The "Generic Bridge": Calls any C++ command and returns the raw data.
52
+ */
53
+ callFunction<F extends (T extends keyof SpecterFunctionRegistry ? keyof SpecterFunctionRegistry[T] : string)>(functionName: F, ...args: T extends keyof SpecterFunctionRegistry ? (F extends keyof SpecterFunctionRegistry[T] ? (SpecterFunctionRegistry[T][F] extends {
54
+ args: infer A;
55
+ } ? (A extends Record<string, never> ? [] : [A]) : [Record<string, any>?]) : [Record<string, any>?]) : [Record<string, any>?]): Promise<T extends keyof SpecterFunctionRegistry ? (F extends keyof SpecterFunctionRegistry[T] ? (SpecterFunctionRegistry[T][F] extends {
56
+ returnType: infer R;
57
+ } ? R : any) : any) : any>;
58
+ hasGameplayTag(tagToCheck: string): Promise<boolean>;
59
+ getObjectName(): Promise<string>;
60
+ getPropertyValue(propertyName: string): Promise<any>;
61
+ getMaterialScalarParameter(parameterName: string, options?: {
62
+ slotIndex?: number;
63
+ componentName?: string;
64
+ }): Promise<number>;
65
+ getMaterialVectorParameter(parameterName: string, options?: {
66
+ slotIndex?: number;
67
+ componentName?: string;
68
+ }): Promise<{
69
+ r: number;
70
+ g: number;
71
+ b: number;
72
+ a: number;
73
+ hex?: string;
74
+ }>;
75
+ getMaterialTextureParameter(parameterName: string, options?: {
76
+ slotIndex?: number;
77
+ componentName?: string;
78
+ }): Promise<string>;
79
+ getMaterialName(options?: {
80
+ slotIndex?: number;
81
+ componentName?: string;
82
+ }): Promise<string>;
83
+ isDynamicMaterial(options?: {
84
+ slotIndex?: number;
85
+ componentName?: string;
86
+ }): Promise<boolean>;
87
+ /**
88
+ * Dynamically track a UPROPERTY value. The C++ plugin will poll it and emit events.
89
+ */
90
+ trackProperty(propertyName: string): Promise<string>;
91
+ /**
92
+ * Dynamically track a GAS attribute. The C++ plugin will listen via delegate events.
93
+ */
94
+ trackAttribute(attributeSet: string, attributeName: string): Promise<string>;
95
+ /**
96
+ * Polls the engine until the locator resolves to at least 1 object.
97
+ * Uses the ultra-fast GetCount command to bypass Strict Mode during the wait.
98
+ */
99
+ waitForExist(timeout?: number): Promise<void>;
100
+ /**
101
+ * Executes a command on the Unreal Engine against this specific locator pipeline.
102
+ * @param command The engine command to execute
103
+ * @param payload The data payload to send
104
+ * @param context Optional string to distinguish identical commands in the UI
105
+ /**
106
+ * Clones the locator and binds it to a different player/client's world connection.
107
+ */
108
+ client(world: SpecterWorld): this;
109
+ evaluate(command: string, payload?: any, context?: string, bHideStep?: boolean): Promise<any>;
110
+ }
@@ -0,0 +1,323 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.SpecterLocator = void 0;
7
+ const test_1 = __importDefault(require("@playwright/test"));
8
+ class SpecterLocator {
9
+ pipeline = [];
10
+ transport;
11
+ constructor(transport, initialPipeline = []) {
12
+ this.transport = transport;
13
+ this.pipeline = initialPipeline;
14
+ }
15
+ clone() {
16
+ const ctor = this.constructor;
17
+ return new ctor(this.transport, [...this.pipeline]);
18
+ }
19
+ get port() {
20
+ return this.transport.port;
21
+ }
22
+ get portTag() {
23
+ return this.transport.friendlyPortTag;
24
+ }
25
+ /**
26
+ * Resolves the pipeline to a unique ID string for event binding.
27
+ */
28
+ get resolvedPath() {
29
+ return btoa(JSON.stringify(this.pipeline));
30
+ }
31
+ /**
32
+ * Natively waits for a C++ UObject delegate to broadcast, with optional predicate filtering.
33
+ */
34
+ waitForEvent(eventName, optionsOrPredicate) {
35
+ let timeoutMs = 5000;
36
+ let predicate;
37
+ if (typeof optionsOrPredicate === 'number') {
38
+ timeoutMs = optionsOrPredicate;
39
+ }
40
+ else if (typeof optionsOrPredicate === 'function') {
41
+ predicate = optionsOrPredicate;
42
+ }
43
+ else if (optionsOrPredicate && typeof optionsOrPredicate === 'object') {
44
+ timeoutMs = optionsOrPredicate.timeout ?? 5000;
45
+ predicate = optionsOrPredicate.predicate;
46
+ }
47
+ const eventKey = `${this.resolvedPath}_${eventName}`;
48
+ const eventPromise = new Promise((resolve, reject) => {
49
+ let timer;
50
+ const listener = (data) => {
51
+ if (predicate && !predicate(data)) {
52
+ return; // Skip if predicate evaluates to false
53
+ }
54
+ clearTimeout(timer);
55
+ this.transport.removeEventListener(eventKey, listener);
56
+ resolve(data);
57
+ };
58
+ timer = setTimeout(() => {
59
+ this.transport.removeEventListener(eventKey, listener);
60
+ reject(new Error(`Specter Timeout: Event [${eventName}] did not fire matching criteria within ${timeoutMs}ms.`));
61
+ }, timeoutMs);
62
+ this.transport.registerEventListener(eventKey, listener);
63
+ });
64
+ this.transport.sendCommand({
65
+ command: 'ListenForEvent',
66
+ locatorPipeline: this.pipeline,
67
+ payload: { eventName, locatorId: this.resolvedPath }
68
+ });
69
+ return eventPromise;
70
+ }
71
+ or(alternateLocator) {
72
+ const combinedLocator = this.clone();
73
+ const pipelinesToMerge = [];
74
+ // 1. Check the Caller (Handles A.or(B).or(C))
75
+ if (this.pipeline.length === 1 && this.pipeline[0].action === 'LogicalOr') {
76
+ const existingPayload = JSON.parse(this.pipeline[0].value);
77
+ pipelinesToMerge.push(...existingPayload.pipelines);
78
+ }
79
+ else {
80
+ pipelinesToMerge.push([...this.pipeline]);
81
+ }
82
+ // 2. Check the Argument (Handles A.or(B.or(C)))
83
+ const altPipeline = alternateLocator.pipeline;
84
+ if (altPipeline.length === 1 && altPipeline[0].action === 'LogicalOr') {
85
+ const altPayload = JSON.parse(altPipeline[0].value);
86
+ pipelinesToMerge.push(...altPayload.pipelines);
87
+ }
88
+ else {
89
+ pipelinesToMerge.push([...altPipeline]);
90
+ }
91
+ // 3. Package it into a single, beautifully flat JSON array
92
+ combinedLocator.pipeline = [{
93
+ action: 'LogicalOr',
94
+ value: JSON.stringify({ pipelines: pipelinesToMerge })
95
+ }];
96
+ return combinedLocator;
97
+ }
98
+ and(alternateLocator) {
99
+ const combinedLocator = this.clone();
100
+ const pipelinesToMerge = [];
101
+ // 1. Flatten the Caller
102
+ if (this.pipeline.length === 1 && this.pipeline[0].action === 'LogicalAnd') {
103
+ const existingPayload = JSON.parse(this.pipeline[0].value);
104
+ pipelinesToMerge.push(...existingPayload.pipelines);
105
+ }
106
+ else {
107
+ pipelinesToMerge.push([...this.pipeline]);
108
+ }
109
+ // 2. Flatten the Argument
110
+ const altPipeline = alternateLocator.pipeline;
111
+ if (altPipeline.length === 1 && altPipeline[0].action === 'LogicalAnd') {
112
+ const altPayload = JSON.parse(altPipeline[0].value);
113
+ pipelinesToMerge.push(...altPayload.pipelines);
114
+ }
115
+ else {
116
+ pipelinesToMerge.push([...altPipeline]);
117
+ }
118
+ // 3. Clear the current pipeline and replace it with the composed Action
119
+ combinedLocator.pipeline = [{
120
+ action: 'LogicalAnd',
121
+ value: JSON.stringify({ pipelines: pipelinesToMerge })
122
+ }];
123
+ return combinedLocator;
124
+ }
125
+ filter(options) {
126
+ const newLocator = this.clone();
127
+ if (options.hasComponent) {
128
+ newLocator.pipeline.push({ action: 'filterByComponent', value: options.hasComponent });
129
+ }
130
+ if (options.property) {
131
+ newLocator.pipeline.push({ action: 'filterByProperty', value: JSON.stringify(options.property) });
132
+ }
133
+ if (options.withinRadius !== undefined) {
134
+ // Stringify the spatial data exactly how the C++ router expects to parse it
135
+ const spatialPayload = JSON.stringify({
136
+ x: options.x ?? 0,
137
+ y: options.y ?? 0,
138
+ z: options.z ?? 0,
139
+ radius: options.withinRadius
140
+ });
141
+ newLocator.pipeline.push({ action: 'withinRadius', value: spatialPayload });
142
+ }
143
+ return newLocator;
144
+ }
145
+ /**
146
+ * Returns a locator pointing to a specific index in the current collection.
147
+ */
148
+ nth(index) {
149
+ const newLocator = this.clone();
150
+ newLocator.pipeline.push({ action: 'getIndex', value: index.toString() });
151
+ return newLocator;
152
+ }
153
+ first() {
154
+ const newLocator = this.clone();
155
+ newLocator.pipeline.push({ action: 'first', value: '' });
156
+ return newLocator;
157
+ }
158
+ last() {
159
+ const newLocator = this.clone();
160
+ newLocator.pipeline.push({ action: 'last', value: '' });
161
+ return newLocator;
162
+ }
163
+ /**
164
+ * Returns an array of locators for every element matching the current query.
165
+ */
166
+ async all() {
167
+ // 1. Ask the engine how many objects currently match this pipeline
168
+ const response = await this.evaluate("GetCount", {});
169
+ const count = response.data.count;
170
+ // 2. Return an array of locators with hard-coded indices
171
+ return Array.from({ length: count }, (_, i) => this.nth(i));
172
+ }
173
+ async count(bHideStep = false) {
174
+ const response = await this.evaluate("GetCount", {}, undefined, bHideStep);
175
+ return response?.data?.count ?? 0;
176
+ }
177
+ toString() {
178
+ return this.pipeline.map(step => `${step.action}('${step.value}')`).join(' -> ');
179
+ }
180
+ // ==========================================
181
+ // THE "ENTITY" METHODS
182
+ // ==========================================
183
+ /**
184
+ * The "Generic Bridge": Calls any C++ command and returns the raw data.
185
+ */
186
+ async callFunction(functionName, ...args) {
187
+ const payloadArgs = args.length > 0 ? args[0] : {};
188
+ // Explicitly map args to the 'parameters' key!
189
+ const response = await this.evaluate("CallFunction", {
190
+ functionName: functionName,
191
+ parameters: payloadArgs
192
+ }, functionName);
193
+ return response.data?.ReturnValue || response.data?.returnValue || response.data;
194
+ }
195
+ async hasGameplayTag(tagToCheck) {
196
+ const response = await this.evaluate("HasGameplayTag", { tag: tagToCheck }, tagToCheck);
197
+ return response.data.hasTag === true;
198
+ }
199
+ async getObjectName() {
200
+ const response = await this.evaluate("GetObjectName", {}, undefined, true);
201
+ return response.data.objectName;
202
+ }
203
+ async getPropertyValue(propertyName) {
204
+ const response = await this.evaluate("GetPropertyValue", { propertyName }, propertyName);
205
+ return response.data.value;
206
+ }
207
+ async getMaterialScalarParameter(parameterName, options) {
208
+ const response = await this.evaluate("GetMaterialParameter", {
209
+ parameterName,
210
+ parameterType: 'Scalar',
211
+ slotIndex: options?.slotIndex ?? 0,
212
+ componentName: options?.componentName
213
+ }, parameterName);
214
+ return response.data?.value;
215
+ }
216
+ async getMaterialVectorParameter(parameterName, options) {
217
+ const response = await this.evaluate("GetMaterialParameter", {
218
+ parameterName,
219
+ parameterType: 'Vector',
220
+ slotIndex: options?.slotIndex ?? 0,
221
+ componentName: options?.componentName
222
+ }, parameterName);
223
+ return response.data?.value;
224
+ }
225
+ async getMaterialTextureParameter(parameterName, options) {
226
+ const response = await this.evaluate("GetMaterialParameter", {
227
+ parameterName,
228
+ parameterType: 'Texture',
229
+ slotIndex: options?.slotIndex ?? 0,
230
+ componentName: options?.componentName
231
+ }, parameterName);
232
+ return response.data?.value?.textureName || '';
233
+ }
234
+ async getMaterialName(options) {
235
+ const response = await this.evaluate("GetMaterialParameter", {
236
+ parameterType: 'Info',
237
+ slotIndex: options?.slotIndex ?? 0,
238
+ componentName: options?.componentName
239
+ });
240
+ return response.data?.materialName || '';
241
+ }
242
+ async isDynamicMaterial(options) {
243
+ const response = await this.evaluate("GetMaterialParameter", {
244
+ parameterType: 'Info',
245
+ slotIndex: options?.slotIndex ?? 0,
246
+ componentName: options?.componentName
247
+ });
248
+ return response.data?.isDynamic === true;
249
+ }
250
+ /**
251
+ * Dynamically track a UPROPERTY value. The C++ plugin will poll it and emit events.
252
+ */
253
+ async trackProperty(propertyName) {
254
+ const response = await this.evaluate("TrackProperty", { propertyName }, propertyName);
255
+ return response.data?.trackedName || propertyName;
256
+ }
257
+ /**
258
+ * Dynamically track a GAS attribute. The C++ plugin will listen via delegate events.
259
+ */
260
+ async trackAttribute(attributeSet, attributeName) {
261
+ const response = await this.evaluate("TrackAttribute", { attributeSet, attributeName }, attributeName);
262
+ return response.data?.trackedName || attributeName;
263
+ }
264
+ /**
265
+ * Polls the engine until the locator resolves to at least 1 object.
266
+ * Uses the ultra-fast GetCount command to bypass Strict Mode during the wait.
267
+ */
268
+ async waitForExist(timeout = 5000) {
269
+ const startTime = Date.now();
270
+ while (Date.now() - startTime < timeout) {
271
+ try {
272
+ // Pass 'true' as the 4th parameter to hide this from the UI!
273
+ const response = await this.evaluate('GetCount', {}, undefined, true);
274
+ if (response.data && response.data.count > 0) {
275
+ return; // The widget has successfully spawned!
276
+ }
277
+ }
278
+ catch (e) {
279
+ // Swallow WebSocket hiccups during polling
280
+ }
281
+ await new Promise(resolve => setTimeout(resolve, 100));
282
+ }
283
+ throw new Error(`[Specter Timeout] Element did not exist after ${timeout}ms.\nPipeline: ${JSON.stringify(this.pipeline)}`);
284
+ }
285
+ // ==========================================
286
+ // EXECUTION
287
+ // ==========================================
288
+ /**
289
+ * Executes a command on the Unreal Engine against this specific locator pipeline.
290
+ * @param command The engine command to execute
291
+ * @param payload The data payload to send
292
+ * @param context Optional string to distinguish identical commands in the UI
293
+ /**
294
+ * Clones the locator and binds it to a different player/client's world connection.
295
+ */
296
+ client(world) {
297
+ return new this.constructor(world.transport, [...this.pipeline]);
298
+ }
299
+ async evaluate(command, payload = {}, context, bHideStep = false) {
300
+ if (bHideStep) {
301
+ return this.transport.sendCommand({ command, locatorPipeline: this.pipeline, payload });
302
+ }
303
+ let displayCommand = command.charAt(0).toLowerCase() + command.slice(1);
304
+ let displayContext = context;
305
+ if (command === "CallFunction" || command === "CallFunctionWithReturn") {
306
+ if (context) {
307
+ displayCommand = context.replace(/^K2_/, "");
308
+ displayContext = undefined;
309
+ }
310
+ }
311
+ // Context will attach to the main command header, before the locator subtitle
312
+ const commandWithContext = displayContext ? `${displayCommand} [${displayContext}]` : displayCommand;
313
+ const stepName = `${commandWithContext} @ ${this.toString()}`;
314
+ return await test_1.default.step(stepName, async () => {
315
+ return this.transport.sendCommand({
316
+ command: command,
317
+ locatorPipeline: this.pipeline,
318
+ payload: payload
319
+ });
320
+ });
321
+ }
322
+ }
323
+ exports.SpecterLocator = SpecterLocator;