@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,1006 @@
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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ var __importDefault = (this && this.__importDefault) || function (mod) {
36
+ return (mod && mod.__esModule) ? mod : { "default": mod };
37
+ };
38
+ Object.defineProperty(exports, "__esModule", { value: true });
39
+ exports.ActorLocator = void 0;
40
+ const component_registry_1 = require("../component-registry");
41
+ const specter_locator_1 = require("../locators/specter-locator");
42
+ const widget_locator_1 = require("./widget-locator");
43
+ const input_conditions_1 = require("../conditions/input-conditions");
44
+ const test_1 = __importDefault(require("@playwright/test"));
45
+ class ActorLocator extends specter_locator_1.SpecterLocator {
46
+ async waitForEvent(eventName, optionsOrPredicate) {
47
+ return super.waitForEvent(eventName, optionsOrPredicate);
48
+ }
49
+ async getLocation() {
50
+ // We know this is safe because the user explicitly cast it to an actor
51
+ const data = await this.callFunction("K2_GetActorLocation");
52
+ return data;
53
+ }
54
+ /**
55
+ * Calculates the Euclidean distance from this actor to another actor or 3D point.
56
+ */
57
+ async getDistanceTo(target) {
58
+ const myLoc = await this.getLocation();
59
+ let targetLoc;
60
+ if (target instanceof ActorLocator) {
61
+ targetLoc = await target.getLocation();
62
+ }
63
+ else {
64
+ targetLoc = target;
65
+ }
66
+ const dx = (myLoc.x ?? 0) - (targetLoc.x ?? 0);
67
+ const dy = (myLoc.y ?? 0) - (targetLoc.y ?? 0);
68
+ const dz = (myLoc.z ?? 0) - (targetLoc.z ?? 0);
69
+ return Math.sqrt(dx * dx + dy * dy + dz * dz);
70
+ }
71
+ async getForwardVector() {
72
+ return await this.callFunction("GetActorForwardVector");
73
+ }
74
+ async setLocation(location) {
75
+ await this.callFunction("K2_SetActorLocation", {
76
+ NewLocation: { X: location.x, Y: location.y, Z: location.z },
77
+ bSweep: false,
78
+ SweepHitResult: {},
79
+ bTeleport: true
80
+ });
81
+ }
82
+ async setRotation(rotation) {
83
+ await this.callFunction("K2_SetActorRotation", {
84
+ NewRotation: { Pitch: rotation.pitch, Yaw: rotation.yaw, Roll: rotation.roll },
85
+ bTeleportPhysics: true
86
+ });
87
+ }
88
+ async setTransform(transform) {
89
+ await this.evaluate("SetTransform", {
90
+ location: transform.location,
91
+ rotation: transform.rotation,
92
+ scale: transform.scale
93
+ });
94
+ }
95
+ async highlight(stateInfo = "Status: Nominal") {
96
+ await this.evaluate("VisualizeActorState", { info: stateInfo });
97
+ await new Promise(resolve => setTimeout(resolve, 500));
98
+ }
99
+ /**
100
+ * Draws a persistent 3D line trail tracking this actor's movement path.
101
+ */
102
+ async drawTrail(options) {
103
+ await this.evaluate("DrawTrail", {
104
+ duration: options?.duration ?? 5,
105
+ color: options?.color ?? "cyan",
106
+ thickness: options?.thickness ?? 3,
107
+ segmentDuration: options?.segmentDuration ?? 10
108
+ });
109
+ }
110
+ /**
111
+ * Draws a 3D directional arrow originating from this actor (facing or velocity vector).
112
+ */
113
+ async drawDirectionArrow(options) {
114
+ await this.evaluate("DrawDirectionArrow", {
115
+ length: options?.length ?? 200,
116
+ color: options?.color ?? "red",
117
+ duration: options?.duration ?? 3,
118
+ arrowSize: options?.arrowSize ?? 50,
119
+ thickness: options?.thickness ?? 3,
120
+ useVelocity: options?.useVelocity ?? false
121
+ });
122
+ }
123
+ /**
124
+ * Spawns a camera-facing 3D text panel floating above this actor displaying live GAS attributes and/or UProperties.
125
+ * Automatically updates in real time as stats change and tracks the actor's world position.
126
+ */
127
+ async showStatsBillboard(options) {
128
+ await this.evaluate("ShowStatsBillboard", {
129
+ attributes: options?.attributes,
130
+ properties: options?.properties,
131
+ duration: options?.duration ?? 5,
132
+ color: options?.color ?? "green"
133
+ });
134
+ }
135
+ /**
136
+ * Updates or reconfigures the live-tracking 3D stats billboard for this actor.
137
+ */
138
+ async updateStatsBillboard(options) {
139
+ return this.showStatsBillboard(options);
140
+ }
141
+ /**
142
+ * Explicitly destroys this actor in the Unreal Engine world.
143
+ */
144
+ async destroy() {
145
+ await this.evaluate("DestroyActor", {});
146
+ }
147
+ /**
148
+ * Checks if this actor has been destroyed or no longer exists in the world.
149
+ */
150
+ async isDestroyed() {
151
+ try {
152
+ const count = await this.count();
153
+ return count === 0;
154
+ }
155
+ catch {
156
+ return true;
157
+ }
158
+ }
159
+ /**
160
+ * Pins this actor in the Unreal Engine world with a unique tag and registers it
161
+ * into the engine's O(1) fast-path hash map. Returns a new ActorLocator pinned directly to that tag.
162
+ * Ideal for pre-existing map actors before running high-frequency polling assertions (like location/transform).
163
+ */
164
+ async pin(customTag) {
165
+ const response = await this.evaluate("PinActor", { tag: customTag });
166
+ const pinnedTag = response.data?.tag || customTag;
167
+ return new ActorLocator(this.transport, [{ action: 'getByTag', value: pinnedTag }]);
168
+ }
169
+ /**
170
+ * Clears all debug lines, boxes, spheres, trails, and billboard text widgets.
171
+ */
172
+ async clearDebugVisuals() {
173
+ await this.evaluate("ClearDebugVisuals", {});
174
+ }
175
+ async checkVisibility(checkOnScreen = false) {
176
+ try {
177
+ const response = await this.evaluate("CheckVisibility", { requireOnScreen: checkOnScreen }, undefined, true);
178
+ return response?.data?.isVisible === true;
179
+ }
180
+ catch (e) {
181
+ const msg = e instanceof Error ? e.message : String(e);
182
+ if (msg.toLowerCase().includes('strict mode')) {
183
+ throw e;
184
+ }
185
+ return false;
186
+ }
187
+ }
188
+ /**
189
+ * Filters the current set of Actors down to only those possessed by the local human player.
190
+ * Perfect for filtering out AI Bots in Lyra!
191
+ */
192
+ isLocallyControlled(locallyControlled = true) {
193
+ const newPipeline = [
194
+ ...this.pipeline,
195
+ { action: 'filterLocallyControlled', value: locallyControlled ? '' : 'false' }
196
+ ];
197
+ return new ActorLocator(this.transport, newPipeline);
198
+ }
199
+ /**
200
+ * Filters the current set of Actors down to only those that are possessed by a controller.
201
+ * Pass false to get unpossessed pawns.
202
+ */
203
+ isPossessed(possessed = true) {
204
+ const newPipeline = [
205
+ ...this.pipeline,
206
+ { action: 'filterPossessed', value: possessed ? '' : 'false' }
207
+ ];
208
+ return new ActorLocator(this.transport, newPipeline);
209
+ }
210
+ /**
211
+ * Filters the current set of Actors down to only those that are possessed by a human player.
212
+ * Excludes AI controllers, bots, and dummy level actors.
213
+ */
214
+ isPlayerControlled(playerControlled = true) {
215
+ const newPipeline = [
216
+ ...this.pipeline,
217
+ { action: 'filterPossessed', value: playerControlled ? '' : 'false' }
218
+ ];
219
+ return new ActorLocator(this.transport, newPipeline);
220
+ }
221
+ async getPlayerId() {
222
+ const response = await this.evaluate("GetPlayerId");
223
+ return response.data.playerId;
224
+ }
225
+ /**
226
+ * Queries detailed controller possession state for this Pawn.
227
+ */
228
+ async getControllerInfo() {
229
+ const response = await this.evaluate("GetControllerInfo");
230
+ return response.data;
231
+ }
232
+ /**
233
+ * Commands the PlayerController to possess this Pawn.
234
+ * If the Pawn is currently possessed by an AI Controller, it will cleanly unpossess it first.
235
+ *
236
+ * @param clientOrOptions Optional client SpecterWorld (or object with world / playerId / playerIndex)
237
+ * to command a specific client's PlayerController on the server. When provided, returns an ActorLocator
238
+ * bound to that client's world targeting the possessed actor.
239
+ */
240
+ async possessAsPlayer(clientOrOptions) {
241
+ let targetWorld;
242
+ let targetPlayerId;
243
+ let targetPlayerIndex;
244
+ let timeoutMs = 3000;
245
+ if (clientOrOptions) {
246
+ if ('evaluate' in clientOrOptions || 'keyboard' in clientOrOptions) {
247
+ targetWorld = clientOrOptions;
248
+ }
249
+ else if ('world' in clientOrOptions && clientOrOptions.world && ('evaluate' in clientOrOptions.world || 'keyboard' in clientOrOptions.world)) {
250
+ targetWorld = clientOrOptions.world;
251
+ targetPlayerId = clientOrOptions.playerId;
252
+ targetPlayerIndex = clientOrOptions.playerIndex;
253
+ if (clientOrOptions.timeout)
254
+ timeoutMs = clientOrOptions.timeout;
255
+ }
256
+ else {
257
+ const opts = clientOrOptions;
258
+ if (opts.world) {
259
+ targetWorld = ('world' in opts.world) ? opts.world.world : opts.world;
260
+ }
261
+ targetPlayerId = opts.playerId;
262
+ targetPlayerIndex = opts.playerIndex;
263
+ if (opts.timeout)
264
+ timeoutMs = opts.timeout;
265
+ }
266
+ }
267
+ // If a client world is provided but neither playerId nor playerIndex is specified,
268
+ // query the client world for its local PlayerId.
269
+ if (targetWorld && targetPlayerId === undefined && targetPlayerIndex === undefined) {
270
+ try {
271
+ const idResponse = await targetWorld.evaluate("GetPlayerId", {}, undefined);
272
+ if (idResponse?.data?.playerId !== undefined) {
273
+ targetPlayerId = idResponse.data.playerId;
274
+ }
275
+ }
276
+ catch {
277
+ // If GetPlayerId fails or isn't available yet, proceed without targetPlayerId
278
+ }
279
+ }
280
+ const payload = {};
281
+ if (targetPlayerId !== undefined) {
282
+ payload.playerId = targetPlayerId;
283
+ }
284
+ if (targetPlayerIndex !== undefined) {
285
+ payload.playerIndex = targetPlayerIndex;
286
+ }
287
+ const stepContext = targetPlayerId !== undefined
288
+ ? `PlayerId: ${targetPlayerId}`
289
+ : (targetPlayerIndex !== undefined ? `PlayerIndex: ${targetPlayerIndex}` : undefined);
290
+ const response = await this.evaluate("PossessAsPlayer", payload, stepContext);
291
+ if (targetWorld) {
292
+ const actorClass = response?.data?.actorClass;
293
+ const resolvedPlayerId = response?.data?.playerId ?? targetPlayerId;
294
+ const clientTransport = targetWorld.transport;
295
+ let clientLocator;
296
+ if (actorClass) {
297
+ clientLocator = new ActorLocator(clientTransport, [
298
+ { action: 'getByClass', value: actorClass },
299
+ { action: 'filterLocallyControlled', value: 'true' }
300
+ ]);
301
+ }
302
+ else if (resolvedPlayerId !== undefined) {
303
+ clientLocator = new ActorLocator(clientTransport, [
304
+ { action: 'getByPlayerId', value: String(resolvedPlayerId) }
305
+ ]);
306
+ }
307
+ else {
308
+ clientLocator = new ActorLocator(clientTransport, [
309
+ { action: 'filterLocallyControlled', value: 'true' }
310
+ ]);
311
+ }
312
+ // Wait briefly for possession and actor state to replicate to the client
313
+ const startTime = Date.now();
314
+ while (Date.now() - startTime < timeoutMs) {
315
+ try {
316
+ const count = await clientLocator.count(true);
317
+ if (count > 0) {
318
+ break;
319
+ }
320
+ }
321
+ catch {
322
+ // Not replicated yet
323
+ }
324
+ await new Promise(r => setTimeout(r, 50));
325
+ }
326
+ return clientLocator;
327
+ }
328
+ return this;
329
+ }
330
+ /**
331
+ * Restores the PlayerController to its pre-possession state (original pawn, view target, and camera rotation).
332
+ */
333
+ async unpossess() {
334
+ const { test } = await Promise.resolve().then(() => __importStar(require('@playwright/test')));
335
+ await test.step(`Specter: Restore Player Pre-Possession State`, async () => {
336
+ await this.evaluate("RestorePlayerState", {});
337
+ });
338
+ }
339
+ // --- Gameplay Ability System (GAS) ---
340
+ async getAttributeValue(attributeSet, attributeName) {
341
+ const response = await this.evaluate("GetAttributeValue", { attributeSet, attributeName }, attributeName);
342
+ return parseFloat(response.data.value);
343
+ }
344
+ async hasGameplayTag(tag) {
345
+ const response = await this.evaluate("HasGameplayTag", { tag });
346
+ return response.data.hasTag;
347
+ }
348
+ /**
349
+ * Waits for a Gameplay Tag to be added or removed.
350
+ */
351
+ async waitForGameplayTag(tag, expectedState, timeout = 5000) {
352
+ const { test } = await Promise.resolve().then(() => __importStar(require('@playwright/test')));
353
+ const { SpecterEventType } = await Promise.resolve().then(() => __importStar(require('../specter-client')));
354
+ return await test.step(`Specter: Wait For Tag [${tag} == ${expectedState}]`, async () => {
355
+ const locatorId = this.resolvedPath;
356
+ const response = await this.evaluate("TrackGameplayTag", { tag, locatorId });
357
+ let hasTag = response.data.hasTag;
358
+ if (hasTag === expectedState) {
359
+ return hasTag;
360
+ }
361
+ return await new Promise((resolve, reject) => {
362
+ let timeoutId;
363
+ const listener = (event) => {
364
+ if (event.eventType === SpecterEventType.GameplayTag &&
365
+ event.eventName === tag &&
366
+ event.description === locatorId) {
367
+ const isTagPresent = event.newValue === 'true';
368
+ if (isTagPresent === expectedState) {
369
+ clearTimeout(timeoutId);
370
+ this.transport.removeEventListener('GLOBAL_timeline-event', listener);
371
+ resolve(isTagPresent);
372
+ }
373
+ }
374
+ };
375
+ timeoutId = setTimeout(() => {
376
+ this.transport.removeEventListener('GLOBAL_timeline-event', listener);
377
+ reject(new Error(`Timed out after ${timeout}ms waiting for GAS Tag '${tag}' to be '${expectedState}'.`));
378
+ }, timeout);
379
+ this.transport.registerEventListener('GLOBAL_timeline-event', listener);
380
+ });
381
+ });
382
+ }
383
+ /**
384
+ * Waits for a Gameplay Attribute to reach a specific value, tracking its history.
385
+ */
386
+ async waitForAttributeValue(attributeSet, attributeName, expectedValue, timeout = 5000) {
387
+ const { test } = await Promise.resolve().then(() => __importStar(require('@playwright/test')));
388
+ const { SpecterEventType } = await Promise.resolve().then(() => __importStar(require('../specter-client')));
389
+ return await test.step(`Specter: Wait For Attribute [${attributeSet}.${attributeName} == ${expectedValue}]`, async () => {
390
+ let lastValue;
391
+ let history = [];
392
+ try {
393
+ lastValue = await this.getAttributeValue(attributeSet, attributeName);
394
+ if (lastValue !== undefined)
395
+ history.push(lastValue);
396
+ if (lastValue === expectedValue) {
397
+ return { finalValue: lastValue, history };
398
+ }
399
+ return await new Promise((resolve, reject) => {
400
+ let timeoutId;
401
+ const listener = (event) => {
402
+ if (event.eventType === SpecterEventType.GameplayAttribute &&
403
+ (event.eventName === attributeName || event.eventName.includes(attributeName))) {
404
+ const val = parseFloat(event.newValue);
405
+ history.push(val);
406
+ if (val === expectedValue) {
407
+ clearTimeout(timeoutId);
408
+ this.transport.removeEventListener('GLOBAL_timeline-event', listener);
409
+ resolve({ finalValue: val, history });
410
+ }
411
+ }
412
+ };
413
+ timeoutId = setTimeout(() => {
414
+ this.transport.removeEventListener('GLOBAL_timeline-event', listener);
415
+ reject(new Error(`Timed out after ${timeout}ms waiting for GAS Attribute '${attributeName}' to reach value '${expectedValue}'.\nHistory: [${history.join(', ')}]`));
416
+ }, timeout);
417
+ this.transport.registerEventListener('GLOBAL_timeline-event', listener);
418
+ });
419
+ }
420
+ catch (e) {
421
+ throw e;
422
+ }
423
+ });
424
+ }
425
+ /**
426
+ * Presses or releases a hardware key on this Actor's PlayerController, optionally holding until/while a condition is met.
427
+ */
428
+ async pressKey(key, eventType = 'Pressed', options) {
429
+ if (typeof options === 'object' && (options.until || options.while || options.when)) {
430
+ const bHideStep = options.bHideStep ?? false;
431
+ const execute = async () => {
432
+ await (0, input_conditions_1.runConditionalInputLoop)({
433
+ driveFn: async () => {
434
+ await this.evaluate("PressKey", { key, eventType: 'Pressed' }, undefined, true);
435
+ },
436
+ releaseFn: async () => {
437
+ await this.evaluate("PressKey", { key, eventType: 'Released' }, undefined, true);
438
+ },
439
+ options,
440
+ actor: this
441
+ });
442
+ };
443
+ if (bHideStep) {
444
+ await execute();
445
+ }
446
+ else {
447
+ const portStr = this.port ? `[Client ${this.port}] ` : '';
448
+ await test_1.default.step(`${portStr}Specter: Press Key [${key}] (Conditional)`, execute);
449
+ }
450
+ return;
451
+ }
452
+ const bHideStep = typeof options === 'boolean' ? options : false;
453
+ await this.evaluate("PressKey", { key, eventType }, undefined, bHideStep);
454
+ }
455
+ /**
456
+ * Holds a key down until/while a condition is satisfied on this Actor.
457
+ */
458
+ async holdKey(key, options) {
459
+ await this.pressKey(key, 'Pressed', options);
460
+ }
461
+ /**
462
+ * Injects an analog axis value for a specific key/input (e.g., thumbsticks, triggers).
463
+ * Supports continuous driving with condition options (until, while, when).
464
+ * @param key Unreal Engine Key Name (e.g., "Gamepad_LeftY")
465
+ * @param value Analog float value (typically -1.0 to 1.0)
466
+ * @param options Optional boolean for bHideStep or InputConditionalOptions
467
+ */
468
+ async injectAxis(key, value, options) {
469
+ if (typeof options === 'object' && (options.until || options.while || options.when)) {
470
+ const bHideStep = options.bHideStep ?? false;
471
+ const execute = async () => {
472
+ await (0, input_conditions_1.runConditionalInputLoop)({
473
+ driveFn: async () => {
474
+ await this.evaluate("InjectAxis", { key, value }, undefined, true);
475
+ },
476
+ releaseFn: async () => {
477
+ await this.evaluate("InjectAxis", { key, value: 0 }, undefined, true);
478
+ },
479
+ options,
480
+ actor: this
481
+ });
482
+ };
483
+ if (bHideStep) {
484
+ await execute();
485
+ }
486
+ else {
487
+ const portStr = this.port ? `[Client ${this.port}] ` : '';
488
+ await test_1.default.step(`${portStr}Specter: Inject Axis [${key} = ${value}] (Conditional)`, execute);
489
+ }
490
+ return;
491
+ }
492
+ const bHideStep = typeof options === 'boolean' ? options : false;
493
+ await this.evaluate("InjectAxis", { key, value }, undefined, bHideStep);
494
+ }
495
+ /**
496
+ * Triggers a UE5 Enhanced Input Action (UInputAction) on this Actor / PlayerController.
497
+ * Supports continuous driving with condition options (until, while, when).
498
+ * @param action Short action name (e.g. "IA_Jump"), or full asset path (e.g. "/Game/Input/Actions/IA_Jump").
499
+ * @param value Optional input magnitude (boolean, float number, or Vector {x, y, z}). Defaults to true (pressed).
500
+ * @param options Optional boolean for bHideStep or InputConditionalOptions
501
+ */
502
+ async triggerInputAction(action, value, options) {
503
+ let parsedValue = value ?? true;
504
+ if (typeof value === 'object' && value !== null) {
505
+ parsedValue = { x: value.x ?? 0, y: value.y ?? 0, z: value.z ?? 0 };
506
+ }
507
+ if (typeof options === 'object' && (options.until || options.while || options.when)) {
508
+ const bHideStep = options.bHideStep ?? false;
509
+ const execute = async () => {
510
+ await (0, input_conditions_1.runConditionalInputLoop)({
511
+ driveFn: async () => {
512
+ await this.evaluate("TriggerInputAction", { action, value: parsedValue }, undefined, true);
513
+ },
514
+ releaseFn: async () => {
515
+ let releaseVal = false;
516
+ if (typeof value === 'number')
517
+ releaseVal = 0;
518
+ else if (typeof value === 'object' && value !== null)
519
+ releaseVal = { x: 0, y: 0, z: 0 };
520
+ await this.evaluate("TriggerInputAction", { action, value: releaseVal }, undefined, true);
521
+ },
522
+ options,
523
+ actor: this
524
+ });
525
+ };
526
+ if (bHideStep) {
527
+ await execute();
528
+ }
529
+ else {
530
+ const portStr = this.port ? `[Client ${this.port}] ` : '';
531
+ await test_1.default.step(`${portStr}Specter: Trigger Input Action [${action}] (Conditional)`, execute);
532
+ }
533
+ return;
534
+ }
535
+ const bHideStep = typeof options === 'boolean' ? options : false;
536
+ if (bHideStep) {
537
+ await this.evaluate("TriggerInputAction", { action, value: parsedValue }, undefined, true);
538
+ return;
539
+ }
540
+ const portStr = this.port ? `[Client ${this.port}] ` : '';
541
+ await test_1.default.step(`${portStr}Specter: Trigger Input Action [${action}]`, async () => {
542
+ await this.evaluate("TriggerInputAction", { action, value: parsedValue }, undefined, true);
543
+ });
544
+ }
545
+ /**
546
+ * Checks if a UE5 Input Mapping Context (UInputMappingContext) is actively applied to the player's Enhanced Input Subsystem.
547
+ * @param context Short context name (e.g. "IMC_Vehicle"), or full asset path.
548
+ */
549
+ async hasInputMappingContext(context) {
550
+ const response = await this.evaluate("HasInputMappingContext", { context });
551
+ return response.data?.hasContext ?? false;
552
+ }
553
+ /**
554
+ * Gets the current evaluation value of a UE5 Enhanced Input Action.
555
+ * @param action Short action name or asset path.
556
+ */
557
+ async getInputActionValue(action) {
558
+ const response = await this.evaluate("GetInputActionValue", { action });
559
+ return response.data;
560
+ }
561
+ /**
562
+ * Retrieves the connected PlayerState info for this Actor / PlayerController.
563
+ * Returns { score, playerId, playerName, ping }.
564
+ */
565
+ async getPlayerStateInfo() {
566
+ const response = await this.evaluate("GetPlayerStateInfo", {});
567
+ return response.data;
568
+ }
569
+ /**
570
+ * Checks if this Actor's UNiagaraComponent is currently active and spawning particles.
571
+ */
572
+ async isNiagaraActive() {
573
+ const response = await this.evaluate("IsNiagaraActive", {});
574
+ return response.data?.isActive ?? false;
575
+ }
576
+ /**
577
+ * Retrieves the asset name of the UNiagaraSystem attached to this Actor.
578
+ */
579
+ async getNiagaraAsset() {
580
+ const response = await this.evaluate("GetNiagaraAsset", {});
581
+ return response.data?.assetName ?? "";
582
+ }
583
+ /**
584
+ * Sets a user variable parameter on this Actor's UNiagaraComponent.
585
+ * @param variableName Parameter name (e.g. "User.SpawnRate", "User.Color")
586
+ * @param value Float, Int, Bool, or Vector value
587
+ */
588
+ async setNiagaraVariable(variableName, value) {
589
+ await test_1.default.step(`Specter: Set Niagara Variable [${variableName}]`, async () => {
590
+ let parsedValue = value;
591
+ if (typeof value === 'object' && value !== null) {
592
+ parsedValue = { x: value.x ?? 0, y: value.y ?? 0, z: value.z ?? 0 };
593
+ }
594
+ await this.evaluate("SetNiagaraVariable", { variableName, value: parsedValue });
595
+ });
596
+ }
597
+ /**
598
+ * Checks if this Actor's UAudioComponent is currently playing audio.
599
+ */
600
+ async isAudioPlaying() {
601
+ const response = await this.evaluate("IsAudioPlaying", {});
602
+ return response.data?.isPlaying ?? false;
603
+ }
604
+ /**
605
+ * Retrieves the attached USoundBase asset name (e.g. MetaSound or SoundCue).
606
+ */
607
+ async getSoundAsset() {
608
+ const response = await this.evaluate("GetSoundAsset", {});
609
+ return response.data?.soundName ?? "";
610
+ }
611
+ /**
612
+ * Gets the volume multiplier of this Actor's UAudioComponent.
613
+ */
614
+ async getAudioVolume() {
615
+ const response = await this.evaluate("GetAudioVolume", {});
616
+ return response.data?.volume ?? 0;
617
+ }
618
+ /**
619
+ * Plays the audio on this Actor's UAudioComponent.
620
+ */
621
+ async playAudio() {
622
+ await test_1.default.step(`Specter: Play Audio`, async () => {
623
+ await this.evaluate("PlayAudio", {});
624
+ });
625
+ }
626
+ /**
627
+ * Stops the audio on this Actor's UAudioComponent.
628
+ */
629
+ async stopAudio() {
630
+ await test_1.default.step(`Specter: Stop Audio`, async () => {
631
+ await this.evaluate("StopAudio", {});
632
+ });
633
+ }
634
+ /**
635
+ * Applies a physical impulse to this Actor's root/primitive component.
636
+ * @param impulse 3D impulse vector {x, y, z}
637
+ * @param options Target bone name or velocity change flag
638
+ */
639
+ async addImpulse(impulse, options) {
640
+ await test_1.default.step(`Specter: Add Physics Impulse [${impulse.x}, ${impulse.y}, ${impulse.z}]`, async () => {
641
+ await this.evaluate("AddImpulse", { impulse, boneName: options?.boneName ?? "", velChange: options?.velChange ?? false });
642
+ });
643
+ }
644
+ /**
645
+ * Checks if physics simulation is currently active on this Actor.
646
+ */
647
+ async isPhysicsSimulating(boneName) {
648
+ const response = await this.evaluate("IsPhysicsSimulating", { boneName: boneName ?? "" });
649
+ return response.data?.isSimulating ?? false;
650
+ }
651
+ /**
652
+ * Checks if this Actor's rigid body is currently asleep (sleeping physics body).
653
+ */
654
+ async isPhysicsAsleep(boneName) {
655
+ const response = await this.evaluate("IsPhysicsAsleep", { boneName: boneName ?? "" });
656
+ return response.data?.isAsleep ?? false;
657
+ }
658
+ /**
659
+ * Retrieves linear/angular velocity and speed of this Actor's rigid body.
660
+ */
661
+ async getPhysicsVelocity(boneName) {
662
+ const response = await this.evaluate("GetPhysicsVelocity", { boneName: boneName ?? "" });
663
+ return response.data ?? { linearVelocity: { x: 0, y: 0, z: 0 }, angularVelocity: { x: 0, y: 0, z: 0 }, speed: 0 };
664
+ }
665
+ /**
666
+ * Gets the Field Of View (FOV) angle of this Actor's camera component / camera manager.
667
+ */
668
+ async getCameraFOV() {
669
+ const response = await this.evaluate("GetCameraFOV", {});
670
+ return response.data?.fov ?? 90.0;
671
+ }
672
+ /**
673
+ * Sets the Field Of View (FOV) angle for this Actor's camera.
674
+ */
675
+ async setCameraFOV(fov) {
676
+ await test_1.default.step(`Specter: Set Camera FOV [${fov}]`, async () => {
677
+ await this.evaluate("SetCameraFOV", { fov });
678
+ });
679
+ }
680
+ /**
681
+ * Checks if a camera shake is currently playing on the player's camera manager.
682
+ */
683
+ async isCameraShaking() {
684
+ const response = await this.evaluate("IsCameraShaking", {});
685
+ return response.data?.isShaking ?? false;
686
+ }
687
+ /**
688
+ * Retrieves the current View Target Actor name of the active camera manager.
689
+ */
690
+ async getCameraViewTarget() {
691
+ const response = await this.evaluate("GetCameraViewTarget", {});
692
+ return response.data?.viewTargetName ?? "";
693
+ }
694
+ /**
695
+ * Checks if this AI Pawn / Controller is actively moving along a NavMesh path.
696
+ */
697
+ async isAINavigating() {
698
+ const response = await this.evaluate("IsAINavigating", {});
699
+ return response.data?.isNavigating ?? false;
700
+ }
701
+ /**
702
+ * Retrieves current NavMesh destination location of this AI Pawn / Controller.
703
+ */
704
+ async getAINavGoal() {
705
+ const response = await this.evaluate("GetAINavGoal", {});
706
+ return response.data?.goalLocation ?? { x: 0, y: 0, z: 0 };
707
+ }
708
+ /**
709
+ * Retrieves all Gameplay Tags owned by this Actor (requires IGameplayTagAssetInterface).
710
+ */
711
+ async getGameplayTags() {
712
+ const response = await this.evaluate("GetGameplayTags", {});
713
+ return response.data?.tags ?? [];
714
+ }
715
+ /**
716
+ * Retrieves the Generic Team ID for this AI or Pawn (requires IGenericTeamAgentInterface).
717
+ */
718
+ async getTeamId() {
719
+ const response = await this.evaluate("GetTeamId", {});
720
+ return response.data?.teamId ?? 255;
721
+ }
722
+ /**
723
+ * Retrieves the Team Attitude of this Actor towards another Actor (requires IGenericTeamAgentInterface).
724
+ */
725
+ async getTeamAttitudeTowards(other) {
726
+ const response = await this.evaluate("GetTeamAttitudeTowards", { otherActorPath: other.resolvedPath });
727
+ return response.data?.attitude ?? 'Neutral';
728
+ }
729
+ /**
730
+ * Plays a high-resolution input sequence generated by SpecterInputSequence on this specific Actor.
731
+ * @param sequence The input pattern to play.
732
+ * @param options Additional playback options (e.g., looping).
733
+ */
734
+ async playSequence(sequence, options) {
735
+ const loops = options?.loops || 1;
736
+ const keyframes = sequence.getKeyframes();
737
+ if (keyframes.length === 0)
738
+ return;
739
+ const portStr = this.port ? `[Client ${this.port}] ` : '';
740
+ await test_1.default.step(`${portStr}Specter: Play Input Sequence [${keyframes.length * loops} frames]`, async () => {
741
+ const totalSequenceTime = keyframes[keyframes.length - 1].timeMs;
742
+ for (let l = 0; l < loops; l++) {
743
+ const startTime = performance.now();
744
+ while (true) {
745
+ const elapsed = performance.now() - startTime;
746
+ if (elapsed >= totalSequenceTime) {
747
+ break;
748
+ }
749
+ // Find the active keyframe for the current elapsed time
750
+ let activeKf = keyframes[0];
751
+ for (let i = 0; i < keyframes.length; i++) {
752
+ if (keyframes[i].timeMs > elapsed)
753
+ break;
754
+ activeKf = keyframes[i];
755
+ }
756
+ // Fire inputs asynchronously WITHOUT awaiting the WebSocket reply!
757
+ // This completely bypasses Playwright's WebSocket interception latency (which can be 50ms+)
758
+ // and restores the original asynchronous pacing that smoothly drives the engine.
759
+ if (activeKf.axes) {
760
+ for (const [axis, val] of Object.entries(activeKf.axes)) {
761
+ this.injectAxis(axis, val, true).catch(() => { });
762
+ }
763
+ }
764
+ if (activeKf.buttons) {
765
+ for (const [btn, state] of Object.entries(activeKf.buttons)) {
766
+ this.pressKey(btn, state, true).catch(() => { });
767
+ }
768
+ }
769
+ if (activeKf.actions) {
770
+ for (const [actionName, val] of Object.entries(activeKf.actions)) {
771
+ this.triggerInputAction(actionName, val, true).catch(() => { });
772
+ }
773
+ }
774
+ // Yield the event loop for ~15ms (standard Node.js timer resolution on Windows).
775
+ // This perfectly paces the asynchronous injection without spinlocking the CPU.
776
+ await new Promise(r => setTimeout(r, 1));
777
+ }
778
+ }
779
+ });
780
+ }
781
+ /**
782
+ * Simulates typing a string of text sequentially by sending Pressed and Released events for each character.
783
+ * @param text The text to type.
784
+ * @param delayMs Optional delay between keystrokes in milliseconds.
785
+ */
786
+ async type(text, delayMs = 0) {
787
+ for (const char of text) {
788
+ // Unreal's FKey names for letters are uppercase (e.g. 'A', 'B')
789
+ // This is a naive mapping and might need expanding for special characters
790
+ const keyName = char === ' ' ? 'SpaceBar' : char.toUpperCase();
791
+ await this.pressKey(keyName, 'Pressed');
792
+ await this.pressKey(keyName, 'Released');
793
+ if (delayMs > 0) {
794
+ await new Promise(r => setTimeout(r, delayMs));
795
+ }
796
+ }
797
+ }
798
+ async triggerAbilityByTag(inputTag) {
799
+ await this.evaluate("TriggerAbilityByTag", { inputTag });
800
+ }
801
+ async triggerAbilityWithTarget(abilityTag, target) {
802
+ let payload = { abilityTag };
803
+ if (target instanceof specter_locator_1.SpecterLocator) {
804
+ payload.targetLocatorPipeline = target.pipeline;
805
+ }
806
+ else {
807
+ payload.targetLocation = target;
808
+ }
809
+ await this.evaluate("TriggerAbilityWithTarget", payload);
810
+ }
811
+ async applyGameplayEffect(effectClassPath, level = 1.0) {
812
+ await this.evaluate("ApplyGameplayEffect", { effectClassPath, level });
813
+ }
814
+ async hasActiveGameplayEffect(effectClassPath) {
815
+ const response = await this.evaluate("HasActiveGameplayEffect", { effectClassPath });
816
+ return response.data.hasEffect;
817
+ }
818
+ async hasGameplayEffect(effectClassPath) {
819
+ return this.hasActiveGameplayEffect(effectClassPath);
820
+ }
821
+ async hasGameplayAbility(abilityClassPath) {
822
+ const response = await this.evaluate("HasGameplayAbility", { abilityClassPath });
823
+ return response.data.hasAbility;
824
+ }
825
+ async getAbilityCooldown(abilityClassPath) {
826
+ const response = await this.evaluate("GetAbilityCooldown", { abilityClassPath });
827
+ return response.data.cooldown;
828
+ }
829
+ async getGameplayEffectStackCount(effectClassPath) {
830
+ const response = await this.evaluate("GetGameplayEffectStackCount", { effectClassPath });
831
+ return response.data.stackCount;
832
+ }
833
+ async getGameplayEffectLevel(effectClassPath) {
834
+ const response = await this.evaluate("GetGameplayEffectLevel", { effectClassPath });
835
+ return response.data.level;
836
+ }
837
+ async getAttributeBaseValue(attributeSet, attributeName) {
838
+ const response = await this.evaluate("GetAttributeBaseValue", { attributeSet, attributeName });
839
+ return response.data.baseValue;
840
+ }
841
+ async isAbilityExecuting(abilityClassPath) {
842
+ const response = await this.evaluate("IsAbilityExecuting", { abilityClassPath });
843
+ return response.data.executing;
844
+ }
845
+ async cancelAbility(abilityClassPath) {
846
+ await this.evaluate("CancelAbility", { abilityClassPath });
847
+ }
848
+ async getGameplayTagCount(tag) {
849
+ const response = await this.evaluate("GetGameplayTagCount", { tag });
850
+ return response.data.count;
851
+ }
852
+ async hasAnyGameplayTags(tags) {
853
+ const response = await this.evaluate("HasAnyGameplayTags", { tags });
854
+ return response.data.hasAny;
855
+ }
856
+ async hasAllGameplayTags(tags) {
857
+ const response = await this.evaluate("HasAllGameplayTags", { tags });
858
+ return response.data.hasAll;
859
+ }
860
+ async getVelocitySize() {
861
+ const response = await this.evaluate("GetVelocitySize", {});
862
+ return response.data.speed;
863
+ }
864
+ async isFalling() {
865
+ const response = await this.evaluate("IsFalling", {});
866
+ return response.data.isFalling;
867
+ }
868
+ async isCrouching() {
869
+ const response = await this.evaluate("IsCrouching", {});
870
+ return response.data.isCrouching;
871
+ }
872
+ async isFlying() {
873
+ const response = await this.evaluate("IsFlying", {});
874
+ return response.data.isFlying;
875
+ }
876
+ async isSwimming() {
877
+ const response = await this.evaluate("IsSwimming", {});
878
+ return response.data?.isSwimming ?? false;
879
+ }
880
+ async isMovingOnGround() {
881
+ const response = await this.evaluate("IsMovingOnGround", {});
882
+ return response.data?.isMovingOnGround ?? false;
883
+ }
884
+ async getMovementMode() {
885
+ const response = await this.evaluate("GetMovementMode", {});
886
+ return response.data;
887
+ }
888
+ /**
889
+ * Hybrid event waiter: Checks current state first (0ms if already falling),
890
+ * then attaches to native OnMovementModeChanged delegate.
891
+ */
892
+ async waitForFalling(options) {
893
+ if (await this.isFalling())
894
+ return;
895
+ await this.waitForEvent('OnMovementModeChanged', {
896
+ timeout: options?.timeout ?? 5000,
897
+ predicate: (data) => data?.movementMode === 'Falling' || data?.isFalling === true
898
+ });
899
+ }
900
+ /**
901
+ * Hybrid event waiter: Checks current state first (0ms if already on ground),
902
+ * then attaches to native OnLanded / OnMovementModeChanged delegate.
903
+ */
904
+ async waitForLanded(options) {
905
+ if (!await this.isFalling()) {
906
+ return {};
907
+ }
908
+ return await this.waitForEvent('OnLanded', {
909
+ timeout: options?.timeout ?? 5000
910
+ });
911
+ }
912
+ /**
913
+ * Hybrid event waiter: Checks current state first (0ms if already swimming),
914
+ * then attaches to native OnMovementModeChanged delegate.
915
+ */
916
+ async waitForSwimming(options) {
917
+ if (await this.isSwimming())
918
+ return;
919
+ await this.waitForEvent('OnMovementModeChanged', {
920
+ timeout: options?.timeout ?? 5000,
921
+ predicate: (data) => data?.movementMode === 'Swimming' || data?.isSwimming === true
922
+ });
923
+ }
924
+ /**
925
+ * Hybrid event waiter: Checks current state first (0ms if already flying),
926
+ * then attaches to native OnMovementModeChanged delegate.
927
+ */
928
+ async waitForFlying(options) {
929
+ if (await this.isFlying())
930
+ return;
931
+ await this.waitForEvent('OnMovementModeChanged', {
932
+ timeout: options?.timeout ?? 5000,
933
+ predicate: (data) => data?.movementMode === 'Flying' || data?.isFlying === true
934
+ });
935
+ }
936
+ /**
937
+ * Hybrid event waiter for any arbitrary movement mode.
938
+ */
939
+ async waitForMovementMode(mode, options) {
940
+ const info = await this.getMovementMode();
941
+ if (info && info.movementMode && info.movementMode.toLowerCase() === mode.toLowerCase())
942
+ return;
943
+ await this.waitForEvent('OnMovementModeChanged', {
944
+ timeout: options?.timeout ?? 5000,
945
+ predicate: (data) => data?.movementMode?.toLowerCase() === mode.toLowerCase()
946
+ });
947
+ }
948
+ /**
949
+ * Traverses down the hierarchy to find a specific component,
950
+ * returning a strongly-typed specialized locator.
951
+ */
952
+ getByComponent(componentType, options) {
953
+ // 1. Look up the configuration in our registry object (if it's a specialized locator)
954
+ const config = component_registry_1.ComponentRegistry[componentType];
955
+ // 2. Instantiate the specialized locator or fallback to base SpecterLocator
956
+ const locatorClass = config ? config.locatorClass : specter_locator_1.SpecterLocator;
957
+ const targetUE5Class = config ? (options?.className || config.defaultUE5Class) : (options?.className || componentType);
958
+ const newLocator = new locatorClass(this.transport);
959
+ newLocator.pipeline = [...this.pipeline];
960
+ // 3. Build the pipeline payload
961
+ const stepPayload = {
962
+ action: 'GetComponent',
963
+ componentClass: targetUE5Class
964
+ };
965
+ if (options?.name) {
966
+ stepPayload.componentName = options.name;
967
+ }
968
+ newLocator.pipeline.push(stepPayload);
969
+ return newLocator;
970
+ }
971
+ /**
972
+ * Scopes locator to a UMG Widget hosted on this actor (via a UWidgetComponent or widget property).
973
+ * If no class name is provided, matches any widget hosted on this actor (e.g. floating health bar).
974
+ */
975
+ widget(widgetClassOrName) {
976
+ return new widget_locator_1.WidgetLocator(this.transport, [
977
+ ...this.pipeline,
978
+ { action: 'getWidgetByClass', value: widgetClassOrName || '' }
979
+ ]);
980
+ }
981
+ /**
982
+ * Scopes locator to a UMG widget hosted on this actor via a specific UWidgetComponent by name.
983
+ */
984
+ widgetComponent(componentName) {
985
+ return new widget_locator_1.WidgetLocator(this.transport, [
986
+ ...this.pipeline,
987
+ { action: 'getWidgetByClass', value: componentName || '' }
988
+ ]);
989
+ }
990
+ /**
991
+ * Finds a child widget on this actor by semantic role (button, image, text, slider, etc.)
992
+ * and optional accessible name.
993
+ */
994
+ getByRole(role, options) {
995
+ const rolePayload = JSON.stringify({
996
+ role,
997
+ name: options?.name instanceof RegExp ? options.name.source : options?.name || '',
998
+ exact: options?.exact ?? (typeof options?.name === 'string' ? true : false)
999
+ });
1000
+ return new widget_locator_1.WidgetLocator(this.transport, [
1001
+ ...this.pipeline,
1002
+ { action: 'getWidgetByRole', value: rolePayload, exact: options?.exact }
1003
+ ]);
1004
+ }
1005
+ }
1006
+ exports.ActorLocator = ActorLocator;