Raycasts, masks and an explicit trigger policy

Separate visibility, eligibility and the gameplay decision

The first question is what the interaction is allowed to observe. A physics ray has an origin and direction, a maximum distance, a layer filter and a trigger rule. The nearest eligible collider is not automatically an interactable object: it might be a wall that correctly blocks the view. Decide whether a query is selecting surfaces, testing obstruction, or finding a particular gameplay role. Those purposes can require different masks and result handling. RayQueryProbe keeps this first exercise to a single observable query, so a miss, a filtered object and a nearer blocker can be investigated independently before another gameplay rule is added.

Read the real ray construction and overload

Probe first refuses an edit-mode invocation or an inactive controller, then rejects an absent camera and an invalid range. ViewportPointToRay uses normalized viewport coordinates, so the centre is one half on both axes. The resulting ray begins on the camera’s near plane; hit.distance is measured from that ray origin, not necessarily from the camera Transform. The selected Raycast overload supplies out hit, range, queryLayers and Ignore explicitly. Read that final argument as part of this component’s contract. Debug.Log uses the hit collider as context, letting the learner select the actual reported object instead of guessing from a printed name.

        Ray ray = viewCamera.ViewportPointToRay(new Vector3(0.5f, 0.5f, 0f));
        if (Physics.Raycast(ray, out RaycastHit hit, range, queryLayers, QueryTriggerInteraction.Ignore))
            Debug.Log("Hit " + hit.collider.name + " at " + hit.distance, hit.collider);
        else Debug.Log("No eligible hit in range", this);

Trace supplied observations without claiming a geometric query

The companion begins with three already supplied descriptions. The sensor is at distance one, the crate at two and the far object at nine. With a five-unit limit and trigger inclusion disabled, the sensor is rejected by policy and the far entry by range, leaving crate. Turning trigger inclusion on makes sensor the nearest allowed description. The lab never calculates an intersection or discovers whether anything lies behind a wall. Its additional layer bounds guard prevents an invalid supplied layer index from exploiting C# shift-count behavior. Treat these outputs as two selection-rule checks, then verify actual geometry through the separate Editor script.

Diagnose a miss before changing the code

Start with one static collider that is visibly centred in the camera and wait for a settled physics frame. Check that the component references the camera actually used for the experiment, that the collider is enabled and that its GameObject layer is included. A trigger is deliberately invisible to this query even when its layer matches. An origin inside a collider has a documented detection limitation; enlarging the range does not fix that configuration. If another script moves colliders through Transform, inspect when the physics world is synchronized. Do not add SyncTransforms to every query as an unexplained universal repair for an unclear update policy.

Practice: make a blocker an intentional part of selection

Create a short three-object scene: a trigger sensor near the camera, a solid wall farther away and a target cube behind the wall. Predict the result with the wall layer included, then exclude only that wall layer and repeat the context-menu query. Record which change altered eligibility and which changed geometry. For a real use action, extend the result handling so the nearest collider must carry the intended role; a wall should reject interaction rather than disappear from the query. This experiment is independent of changing the portable list because only the Editor can establish that the camera ray intersects those configured collider shapes.

• Hint: keep the trigger rule fixed while changing only the wall layer.
• Hint: use the log context to identify the reported collider, including an unexpectedly nearer one.

Practice: specify selection boundaries with supplied data

In the portable lab, add descriptions exactly at zero and exactly at the maximum distance, then add an invalid negative distance and a layer outside zero through thirty-one. State whether each belongs to the rule before running it. Next introduce two equally distant allowed descriptions and decide whether stable input order is an acceptable tie policy or whether a secondary identity ordering is required. Keep the result’s meaning narrow: it chooses among supplied candidates. Even a complete set of these checks cannot establish a Unity ray origin, collider synchronization, contact offset or scene layer configuration that the program never received.

• Hint: the current range comparisons include both boundaries.
• Hint: make a tie policy explicit if callers require deterministic output independent of source order.

Retain a useful query receipt

A helpful Editor observation records the camera, ray origin, intended layer mask, trigger policy, range and reported collider. That receipt is stronger than merely stating that a method ran, because it preserves the assumptions needed to reproduce the result. For this lesson the documentation baseline is Unity6000.0; no Unity Editor or Player was installed during authoring, so the supplied engine source was syntax-checked and API-reviewed rather than run in a scene. The separate console practice was executed as ordinary C#. Keep those verification scopes visible when applying the query to selection, line-of-sight or the keyed station later in the course.