The camera of a layer (JSON-safe), or null if the layer does not
exist. angle is the 2D rotation (the yaw of the view, same
convention as object angles). rotationX/rotationY are the 3D
camera rotations: rotationX is 0 looking straight down (the 2D
default) and 90 at the horizon, so the pitch of a first-person
view is rotationX - 90 (positive = looking up).
LAST RESORT: the raw gdjs.RuntimeScene currently being played
(throws if no scene is running). Prefer the harness APIs.
The notable events recorded so far (scene changes and resets with their cause, stuck detections...), as a JSON-safe copy: lets a test assert, for example, that the game restarted its scene.
Get the instances of objectName within radius of the first
instance of referenceObjectName, sorted by distance.
Get a variable of an object (same entry shape as getSceneVariable),
or undefined if the object or the variable does not exist.
An instance id (from getObjects) or an object
name (first instance).
Get a state snapshot of all the instances of an object. Instances are returned in an unspecified order.
Get the position of a target (an object or a position) relative to
the first instance of referenceObjectName (2D and 3D). Deciding
how to move toward the target with the game's actual controls is
the job of the test script (use resetSceneAndProbeControls to
discover the controls, makeProgressTracker to detect a lack of
progress).
Optional options: { Optional fromMeasure from the camera of this layer (position, yaw and pitch) instead of the object: what a first-person view aims with.
Optional fromZ?: numberMeasure from this Z instead of the object's center Z (an eye or muzzle height).
Optional heading?: numberCompute yawDiff against this heading (in degrees) instead of
the object's angle - for turrets and weapons with their own
rotation.
Optional reachLAST RESORT: the raw gdjs.RuntimeGame being tested. Prefer the
harness APIs (snapshots, inputs, stepping...) - direct mutations
can invalidate what the test asserts.
The raw gdjs.RuntimeLayer of the current scene, or null if the
layer does not exist. Useful to check the layer visibility
(isVisible()) or read the camera (getCameraX(), getCameraZoom()...).
The raw gdjs.RuntimeObject of an instance, or null if not found.
Behaviors can be reached with getBehavior(behaviorName) (also null
if not found). Prefer the harness APIs (snapshots, inputs...) -
direct mutations can invalidate what the test asserts.
An instance id (from getObjects) or an object
name (first instance).
Check if the straight segment between the first instance of
referenceObjectName and the first instance of targetObjectName
is clear of the given blocker objects. 2D ONLY: the test uses the
2D hitboxes in the X/Y plane and ignores Z.
Optional blockedOptional blockedTurn the first instance of referenceObjectName toward the target,
by applying mouse movement deltas (FPS/pointer-lock style, yaw and
pitch in 3D) until it is aiming at it. The aim is measured on the
camera of the object's layer when it is a 3D one (the ground truth
of a first-person view: right eye height, right rotations whatever
the game drives to move it - see measuredFrom in the result),
with a fallback to the object's own rotations. The mouse
sensitivity and direction of the game are measured and adapted to
live, per axis. When the vertical aim shows no measurable response,
the vertical input is undone and the aim falls back to yaw-only,
reported as sawPitchResponse: false. Returns null if the object
or the target is missing.
Optional options: { Optional fromOptional toleranceConsider the aim done when both angles are within this tolerance (default 3 degrees - lower it to hit a small or far target).
Optional yawMake a tracker measuring the progress of the first instance of
referenceObjectName toward a target (the distance is 3D when the
object has a Z coordinate). Call update() regularly (e.g. once
per loop iteration): it reports the current distance, whether
the target is reached, and whether progress stalled (distance
shrank by less than minProgress over the last windowFrames
frames - time to try an escape strategy). The first update of a
stall also records a stuck event in the event log. Call
reset() after switching to another target.
Optional options: { Optional minOptional reachOptional windowMeasure what each key actually does to the first instance of
objectName (2D and 3D: dz is measured when the object has a Z
coordinate): for the baseline (no key) and then each key, the
scene is restarted, the key held for frames frames, and the
displacement (net + extremes: a jump shows as a negative minDy
even if the object lands back) and yaw change are measured.
Compare each key's result to baseline (gravity or idle drift
affects both). The scene is restarted again at the end, so call
this BEFORE the scenario of the test. An entry is null if the
instance disappeared during that probe.
Optional options: { Optional frames?: numberMove the instance with the given id to a position.
Use for test setup only. The move takes effect immediately (physics
bodies included), but the game's logic keeps acting on the object
each stepped frame (forces, AI...): to hold an object somewhere,
re-apply the position every frame via onFrame.
Optional z: numberSet a variable of an object (number, string or boolean). Use for test setup only. Throws if the object does not exist.
An instance id (from getObjects) or an object
name (first instance).
Create a new instance of an object at the given position. Use for test setup only - do not use it to fake a game behavior you are supposed to test.
Optional z: numberOptional layerName: stringStep the given number of game frames.
Optional options: { Optional dtOptional onStep frames until the condition returns true, or maxFrames frames
were stepped. Returns true if the condition was met.
Optional onOptional stuckOptional minOptional onOptional windowStep until the first instance of the object stops moving: its
position changed less than tolerance (default 0.5) per frame for
stableFrames (default 20) consecutive frames. Returns whether it
settled within maxFrames (default 300). Use this for physics
objects instead of a hand-written "read, compare, update"
condition in stepUntil (which can silently pass without
stepping a frame).
Optional options: { Optional maxOptional stableOptional tolerance?: numberStop profiling and return a flat, JSON-safe summary: average and
worst-frame time per profiled section (events, physics,
rendering... - nested sections are flattened as "parent > child",
sorted by average time descending), the frame-by-frame timeline (to
correlate a spike with the eventLog frames), the live object
counts, and renderer/memory counters when available.
The object passed as
harnessto a gameplay test script.