Physics.Raycast

本篇文章出處自 https://docs.unity3d.com/2022.3/Documentation/ScriptReference/Physics.Raycast.html
軟體版本與本翻譯文件可能會有落差，本翻譯文件僅供參考。

Physics.Raycast：物理射線投射（Raycast）

Overload 1：Raycast（Vector3 origin, Vector3 direction）

Declaration（宣告）

public static bool Raycast(
Vector3 origin,
Vector3 direction,
float maxDistance = Mathf.Infinity,
int layerMask = DefaultRaycastLayers,
QueryTriggerInteraction queryTriggerInteraction = QueryTriggerInteraction.UseGlobal
);
    

Parameters（參數）

Parameter	Description（描述）
origin	射線在「世界座標」中的起始點。
direction	射線的方向。
maxDistance	射線用來檢查碰撞的最大距離。
layerMask	用來在射線投射時「選擇性忽略某些 Collider」的圖層遮罩（Layer Mask）。
queryTriggerInteraction	指定這次查詢是否會命中 Trigger（觸發器）。

回傳值（Returns）

bool：如果射線與某個 Collider（碰撞體）相交，回傳 true；否則回傳 false。

說明（Description）

從 origin 這個點出發，沿著 direction 的方向，以長度 maxDistance 發射一條射線，並對場景（Scene）中的所有碰撞體進行檢測。
若要選擇射線會與哪些圖層發生碰撞，請使用 LayerMask。
指定 queryTriggerInteraction 可以讓你控制 Trigger 碰撞體 是否會產生命中（hit），或是改用全域的 Physics.queriesHitTriggers 設定。

注意（Notes）

射線檢測不會偵測到「射線起點位於碰撞體內部」的那些碰撞體。
在所有範例中使用的是 FixedUpdate 而不是 Update。請參考「事件函式的執行順序（Order of Execution for Event Functions）」來理解 Update 與 FixedUpdate 的差異，以及它們與物理查詢（physics queries）之間的關係。

Examples（範例）

Example 1

using UnityEngine;

// C# example.

public class ExampleClass : MonoBehaviour
{
    LayerMask layerMask = LayerMask.GetMask("Wall", "Character");

    // See Order of Execution for Event Functions for information on FixedUpdate() and Update() related to physics queries
    void FixedUpdate()
    {

        RaycastHit hit;
        // Does the ray intersect any objects excluding the player layer
        if (Physics.Raycast(transform.position, transform.TransformDirection(Vector3.forward), out hit, Mathf.Infinity, layerMask))

        { 
            Debug.DrawRay(transform.position, transform.TransformDirection(Vector3.forward) * hit.distance, Color.yellow); 
            Debug.Log("Did Hit"); 
        }
        else
        { 
            Debug.DrawRay(transform.position, transform.TransformDirection(Vector3.forward) * 1000, Color.white); 
            Debug.Log("Did not Hit"); 
        }

    }
}
    

Example 2

這個範例建立了一個簡單的 Raycast：從物件「目前的位置」出發，朝前方投射，射線長度延伸 10 個單位。

using UnityEngine;

public class ExampleClass : MonoBehaviour
{
    // See Order of Execution for Event Functions for information on FixedUpdate() and Update() related to physics queries
    void FixedUpdate()
    {
        Vector3 fwd = transform.TransformDirection(Vector3.forward);

        if (Physics.Raycast(transform.position, fwd, 10))
            print("There is something in front of the object!");
    }
}
    

---

Overload 2：Raycast（含 out RaycastHit hitInfo）

Declaration（宣告）

public static bool Raycast(
Vector3 origin,
Vector3 direction,
out RaycastHit hitInfo,
float maxDistance,
int layerMask,
QueryTriggerInteraction queryTriggerInteraction
);
    

Parameters（參數）

Parameter	Description（描述）
origin	射線在「世界座標」中的起始點。
direction	射線的方向。
hitInfo	如果回傳 true，hitInfo 會包含「射線擊中最近的碰撞體」的位置等更多資訊。（補充資源：RaycastHit）
maxDistance	射線用來檢查碰撞的最大距離。
layerMask	用來在射線投射時「選擇性忽略某些 collider（碰撞體）」的圖層遮罩（Layer Mask）。
queryTriggerInteraction	指定這次查詢是否會命中 Trigger（觸發器）。

回傳值（Returns）

bool：當射線與任何 Collider（碰撞體）相交時回傳 true；否則回傳 false。

說明（Description）

對場景（Scene）中的所有碰撞體進行射線投射，並回傳被擊中的詳細資訊。

Examples（範例）

這個範例會回報「目前物件」與被回報的碰撞體（Collider）之間的距離：

using UnityEngine;

public class RaycastExample : MonoBehaviour
{
    // See Order of Execution for Event Functions for information on FixedUpdate() and Update() related to physics queries
    void FixedUpdate()
    {
        RaycastHit hit;

        if (Physics.Raycast(transform.position, -Vector3.up, out hit))
            print("Found an object - distance: " + hit.distance);
    }
}
    

這個範例重新加入 maxDistance 參數，用來限制射線要往前投射（檢測）多遠：

using UnityEngine;

public class RaycastExample : MonoBehaviour
{
    // See Order of Execution for Event Functions for information on FixedUpdate() and Update() related to physics queries
    void FixedUpdate()
    {
        RaycastHit hit;

        if (Physics.Raycast(transform.position, -Vector3.up, out hit, 100.0f))
            print("Found an object - distance: " + hit.distance);
    }
}
    

---

Overload 3：Raycast（Ray ray）

Declaration（宣告）

public static bool Raycast(
    Ray ray,
    float maxDistance = Mathf.Infinity,
    int layerMask = DefaultRaycastLayers,
    QueryTriggerInteraction queryTriggerInteraction = QueryTriggerInteraction.UseGlobal
);
    

Parameters（參數）

Parameter	Description（描述）
ray	射線的起點與方向。
maxDistance	射線用來檢查碰撞的最大距離。
layerMask	用來在射線投射時「選擇性忽略某些 collider（碰撞體）」的圖層遮罩（Layer Mask）。
queryTriggerInteraction	指定這次查詢是否會命中 Trigger（觸發器）。

回傳值（Returns）

bool：當射線與任何 Collider（碰撞體）相交時回傳 true；否則回傳 false。

說明（Description）

與上面相同，只是改用 ray.origin 和 ray.direction，而不是 origin 與 direction。

Example（範例）

using UnityEngine;

public class ExampleClass : MonoBehaviour
{
    // See Order of Execution for Event Functions for information on FixedUpdate() and Update() related to physics queries
    void FixedUpdate()
    {
        Ray ray = Camera.main.ScreenPointToRay(Input.mousePosition);
        if (Physics.Raycast(ray, 100))
            print("Hit something!");
    }
}
    

---

Overload 4：Raycast（Ray ray, out RaycastHit hitInfo）

Declaration（宣告）

public static bool Raycast(
    Ray ray,
    out RaycastHit hitInfo,
    float maxDistance = Mathf.Infinity,
    int layerMask = DefaultRaycastLayers,
    QueryTriggerInteraction queryTriggerInteraction = QueryTriggerInteraction.UseGlobal
);
    

Parameters（參數）

Parameter	Description（描述）
ray	射線的起點與方向。
hitInfo	如果回傳 true，hitInfo 會包含「射線擊中最近的碰撞體」的位置等更多資訊。（補充資源：RaycastHit）
maxDistance	射線用來檢查碰撞的最大距離。
layerMask	用來在射線投射時「選擇性忽略某些 collider（碰撞體）」的圖層遮罩（Layer Mask）。
queryTriggerInteraction	指定這次查詢是否會命中 Trigger（觸發器）。

回傳值（Returns）

bool：當射線與任何 Collider（碰撞體）相交時回傳 true；否則回傳 false。

說明（Description）

與上面相同，只是改用 ray.origin 和 ray.direction，而不是 origin 與 direction。

範例說明

這個範例會在偵測到碰撞時，沿著射線（Ray）的長度畫出一條線：

using UnityEngine;

public class ExampleClass : MonoBehaviour
{
    // See Order of Execution for Event Functions for information on FixedUpdate() and Update() related to physics queries
    void FixedUpdate()
    {
        Ray ray = Camera.main.ScreenPointToRay(Input.mousePosition);
        RaycastHit hit;

        if (Physics.Raycast(ray, out hit, 100))
            Debug.DrawLine(ray.origin, hit.point);
    }
}