Raycast 기본

Quick Reference

Physics.Raycast는 world-space origin에서 direction으로 maxDistance만큼 검사하고, layerMask와 QueryTriggerInteraction에 맞는 Collider가 있으면 true와 RaycastHit을 돌려줍니다.

csharp

[SerializeField] private LayerMask interactableMask;

if (Physics.Raycast(
    transform.position + Vector3.up * eyeHeight,
    transform.forward,
    out RaycastHit hit,
    interactDistance,
    interactableMask,
    QueryTriggerInteraction.Ignore))
{
    IInteractable target = hit.collider.GetComponent<IInteractable>();
    target?.Interact();
}

파라미터·결과	의미	빠진 경우의 결과
`origin`	ray 시작 world 좌표	시작점이 자기 Collider 안이면 hit를 못 얻을 수 있습니다.
`direction`	검사 방향	local 축과 world 방향을 섞으면 엉뚱한 곳을 봅니다.
`maxDistance`	검사 최대 거리	무한 거리 기본값에 기대면 의도 밖의 먼 collider도 후보가 됩니다.
`layerMask`	포함할 collider layer	인터랙션과 장식·지형이 섞입니다.
`QueryTriggerInteraction`	trigger 포함·무시·전역 따르기	global setting 변경에 따라 결과가 바뀝니다.
`RaycastHit`	`collider`, `point`, `normal`, `distance` 등	`true` 확인 전 접근하면 `collider`가 없습니다.

목적에 맞는 query

단일 첫 hit만 필요하면 Raycast가 가장 단순합니다. 발사체의 두께를 고려해야 하면 SphereCast/CapsuleCast, 범위 안 후보가 필요하면 OverlapSphere, 경로 위 여러 접촉을 모두 처리해야 하면 RaycastAll 또는 NonAlloc 버퍼를 선택합니다. RaycastAll 결과 순서에 의존하지 말고, 거리 우선 처리가 필요하면 직접 정렬하거나 가장 가까운 값을 선택합니다.

physics scene과 같은 타이밍에 판정해야 하는 query는 FixedUpdate 또는 physics step 뒤에 둡니다. Update에서 Transform을 직접 바꾼 직후 physics query를 하면 아직 physics world에 반영되지 않았을 수 있습니다. 이 경우 이동 모델을 Rigidbody로 통일하거나 Physics.SyncTransforms()가 정말 필요한 위치인지 비용과 함께 검토합니다.

디버깅 순서

Debug.DrawRay(origin, direction.normalized * maxDistance, Color.red)로 실제 시작점과 방향을 확인합니다.
target의 Collider enabled 상태, layer, trigger 여부를 확인합니다.
mask와 QueryTriggerInteraction을 호출에 명시합니다.
origin이 target 또는 자기 collider 안에 있는지 확인합니다. Raycast는 origin 내부 collider를 감지하지 않습니다.
physics scene을 바꾸는 코드와 query의 frame/physics timing을 확인합니다.

자주 틀리는 부분

증상	원인	수정 방향
가까운 벽에서만 ray가 사라짐	origin이 collider 내부입니다.	origin을 표면 밖으로 옮기거나 목적에 맞는 overlap/cast를 씁니다.
trigger가 가끔 hit됨	전역 `queriesHitTriggers`에 의존했습니다.	`Ignore`/`Collide`를 명시합니다.
`hit.collider`에서 예외	반환 bool을 검사하지 않았습니다.	`if (Physics.Raycast(...))` 안에서만 읽습니다.
클릭 대상이 가끔 다른 객체	layer와 거리, multi-hit 선택 규칙이 없습니다.	mask·distance를 제한하고 다중 hit는 직접 우선순위를 정합니다.
이동 직후 query가 이전 위치를 봄	Transform 변경과 physics sync 시점이 다릅니다.	물리 단계와 이동 API를 맞춥니다.

ray 한 줄은 "무엇을 검사하는가"를 거의 말해 주지 않습니다. origin, 방향, 거리, layer, trigger 정책을 함께 적어야 씬 설정이 바뀌어도 판정 계약을 읽을 수 있습니다.

참고 링크

3 sources

Quick Reference

csharp

[SerializeField] private LayerMask interactableMask;

if (Physics.Raycast(
    transform.position + Vector3.up * eyeHeight,
    transform.forward,
    out RaycastHit hit,
    interactDistance,
    interactableMask,
    QueryTriggerInteraction.Ignore))
{
    IInteractable target = hit.collider.GetComponent<IInteractable>();
    target?.Interact();
}

파라미터·결과	의미	빠진 경우의 결과
`origin`	ray 시작 world 좌표	시작점이 자기 Collider 안이면 hit를 못 얻을 수 있습니다.
`direction`	검사 방향	local 축과 world 방향을 섞으면 엉뚱한 곳을 봅니다.
`maxDistance`	검사 최대 거리	무한 거리 기본값에 기대면 의도 밖의 먼 collider도 후보가 됩니다.
`layerMask`	포함할 collider layer	인터랙션과 장식·지형이 섞입니다.
`QueryTriggerInteraction`	trigger 포함·무시·전역 따르기	global setting 변경에 따라 결과가 바뀝니다.
`RaycastHit`	`collider`, `point`, `normal`, `distance` 등	`true` 확인 전 접근하면 `collider`가 없습니다.

목적에 맞는 query

디버깅 순서

Debug.DrawRay(origin, direction.normalized * maxDistance, Color.red)로 실제 시작점과 방향을 확인합니다.

target의 Collider enabled 상태, layer, trigger 여부를 확인합니다.

mask와 QueryTriggerInteraction을 호출에 명시합니다.

origin이 target 또는 자기 collider 안에 있는지 확인합니다. Raycast는 origin 내부 collider를 감지하지 않습니다.

physics scene을 바꾸는 코드와 query의 frame/physics timing을 확인합니다.

자주 틀리는 부분

증상	원인	수정 방향
가까운 벽에서만 ray가 사라짐	origin이 collider 내부입니다.	origin을 표면 밖으로 옮기거나 목적에 맞는 overlap/cast를 씁니다.
trigger가 가끔 hit됨	전역 `queriesHitTriggers`에 의존했습니다.	`Ignore`/`Collide`를 명시합니다.
`hit.collider`에서 예외	반환 bool을 검사하지 않았습니다.	`if (Physics.Raycast(...))` 안에서만 읽습니다.
클릭 대상이 가끔 다른 객체	layer와 거리, multi-hit 선택 규칙이 없습니다.	mask·distance를 제한하고 다중 hit는 직접 우선순위를 정합니다.
이동 직후 query가 이전 위치를 봄	Transform 변경과 physics sync 시점이 다릅니다.	물리 단계와 이동 API를 맞춥니다.

Raycast 기본

Quick Reference

목적에 맞는 query

디버깅 순서

자주 틀리는 부분

참고 링크

Opening reference

Raycast 기본

Quick Reference

목적에 맞는 query

디버깅 순서

자주 틀리는 부분

참고 링크