stingray.Raycast 오브젝트 참조

설명

이 오브젝트를 통해 PhysicsWorld에서 물리적 오브젝트를 대상으로 충돌 테스트를 수행할 수 있습니다.

Raycast 오브젝트는 완전한 사용자 데이터 오브젝트입니다. 즉,

• 이 오브젝트를 생성하는 일은 상대적으로 부담이 크기 때문에 게임 진행 과정에서 너무 많이 생성하지는 마십시오. 가장 좋은 방법은 초기화 단계에서 생성해두고, 같은 오브젝트를 시작점과 방향을 새롭게 해서 여러 번 재사용하는 것입니다.
• 스크립트에 이 오브젝트에 대한 참조가 남아 있지 않으면 가비지로 수집됩니다. Raycast 오브젝트를 일단 생성하고 나면 삭제를 위해 따로 수행할 작업은 없습니다. 이 오브젝트는 범위를 벗어나는 순간 가비지로 수집됩니다.

광선 투사 수행

광선 투사는 결과를 어떻게 검색할지에 따라 세 가지 방법으로 수행할 수 있습니다.

옵션 1. 단일, 동기 광선 투사

단일 광선 투사만 수행하면 되고, 결과를 즉시 원한다면 이 옵션을 사용합니다.

이 시나리오에서는 stingray.PhysicsWorld.raycast() 함수를 호출합니다. 광선의 시작점, 방향 및 최대 길이를 지정하고, 충돌 테스트를 제어할 매개변수(아래 Raycast 매개변수 참조) 역시 지정해야 합니다.

예를 들면 다음과 같습니다.

local foundCollision, collisionPos, distance, normal, actor = stingray.PhysicsWorld.raycast(my_world, start, dir, "closest")

이 예에서는 광선 투사를 "closest" 매개변수를 통해 호출하는데, 이 경우 함수가 첫 번째 충돌 지점(있는 경우)에 관한 세부 정보를 반환합니다.

옵션 2. 다중, 동기 광선 투사

동일한 매개변수(아래 Raycast 매개변수 참조)를 사용하여 다중 광선 투사를 수행하고, 결과를 즉시 처리해야 하는 경우 이 옵션을 사용합니다. 이 옵션은 동일한 Raycast 오브젝트를 재사용하는 것이기 때문에 보통 stingray.PhysicsWorld.raycast()를 연속해서 여러 번 호출하는 것보다 효과적입니다.

이 시나리오에서는 stingray.PhysicsWorld.make_raycast()를 호출(콜백 매개변수는 전체적으로 생략)하여 새로운 Raycast 오브젝트를 생성합니다. 그런 다음, 새 오브젝트에 대해 stingray.Raycast.cast() 함수를 호출합니다. 예를 들면 다음과 같습니다.

local raycastObj = stingray.PhysicsWorld.make_raycast(my_world, "all")
local collisionResultsA = raycastObj:cast(start, dirA, length)
local collisionResultsB = raycastObj:cast(start, dirB, length)
...

이 예에서는 Raycast가 "all" 매개변수를 통해 초기화되기 때문에 collisionResultsA 및 collisionResultsB 변수가 각각 collision_hit 데이터 테이블의 어레이로 설정됩니다.

옵션 3. 다중, 비동기 광선 투사

다중 광선 투사를 수행하고, 결과는 이후 프레임에서 처리하도록 연기할 수 있는 경우 이 옵션을 사용합니다.

이 시나리오에서는

1. 먼저 충돌 테스트가 완료되면 자동으로 호출되는 콜백 함수를 써야 합니다. 함수가 처리해야 하는 매개변수 유형은 테스트 수행에 사용할 Raycast 오브젝트를 생성할 때 지정하는 매개변수에 따라 정해집니다. 아래 Raycast 매개변수를 참조하십시오.
2. stingray.PhysicsWorld.make_raycast()를 호출(함수를 콜백 매개변수로 전달)하여 새로운 Raycast 오브젝트를 생성합니다.
3. 새로운 오브젝트에 대해 stingray.Raycast.cast() 함수를 호출합니다.

예를 들면 다음과 같습니다.

local raycastObj = stingray.PhysicsWorld.make_raycast(my_world, my_raycast_callback, "all", "types", "statics")
raycastObj:cast(start, dirA, length)
raycastObj:cast(start, dirB, length)
...

이 예에서는 Raycast가 "all" 매개변수를 통해 초기화되기 때문에 my_raycast_callback 함수가 collision_hit 데이터 테이블의 어레이로 전달됩니다.

Raycast 매개변수

stingray.PhysicsWorld.make_raycast()를 사용하여 새로운 Raycast 오브젝트를 생성하거나, stingray.PhysicsWorld.raycast()를 호출하여 단일 동기 광선 투사를 수행할 때에는 충돌 테스트의 동작과 생성되는 결과의 유형을 제어하는 일부 매개변수를 지정할 수 있습니다.

허용되는 매개변수 값은 다음과 같습니다.

• "any": 광선이 무언가에 충돌하는지만 알고 싶다면 이 값을 사용합니다. 이 옵션을 사용하면 광선 투사 결과 충돌이 감지되었는지 여부를 나타내는 단일 부울 값만 생성됩니다.

• "all": 광선 경로상에서 발생한 모든 충돌에 대한 세부 정보를 원한다면 이 값을 사용합니다. 이 옵션을 사용하면 광선 투사 결과 collision_hit 테이블의 어레이(각 테이블이 광선을 따라 존재하는 충돌 지점 하나씩을 기록)를 포함하는 하나의 테이블이 생성됩니다.

• "closest": 광선에 의해 발생하는 첫 번째 충돌에 관한 정보만 필요하다면 이 값을 사용합니다. 이것은 기본 모드입니다. 이 옵션을 사용하면 광선 투사 결과 여러 값이 생성됩니다.

  • boolean 값은 충돌이 감지되었는지 여부를 나타냅니다. 이 값이 true인 경우 다음 값 역시 생성됩니다.
  • Vector3는 3D 표준의 충돌 위치를 나타냅니다.
  • number는 요청 시작점부터 충돌 지점까지의 거리를 나타냅니다.
  • Vector3는 충돌한 표면의 법선을 나타냅니다.
  • Actor는 충돌한 물리적 액터를 나타냅니다.

• "types": 충돌을 위해 고려해야 할 오브젝트의 유형을 결정합니다. 이 매개변수를 지정하는 경우, 해당 유형을 지정하는 추가 문자열 매개변수를 뒤에 붙여야 합니다. "statics": 정적 오브젝트에 대해서만 광선을 테스트하도록 지정합니다. "dynamics": 동적 오브젝트에 대해서만 광선을 테스트해야 함을 지정합니다. "both": 정적 오브젝트와 동적 오브젝트 모두에 대해서 광선을 테스트해야 함을 지정합니다. 기본값입니다.

• "collision_filter": 이 매개변수를 통해 광선이 충돌할 오브젝트를 결정하는 데 사용해야 하는 충돌 필터를 지정할 수 있습니다. 이 매개변수를 지정하는 경우, global.physics_properties 데이터 파일에 정의된 대로, 충돌 필터의 이름을 지정하는 추가 문자열 매개변수를 뒤에 붙여야 합니다. 기본적으로 광선은 장면 내 모든 오브젝트와 충돌합니다.

• "mesh_both_sides" 광선 투사가 물리적 메시의 뒷면 삼각형에도 충돌하기를 원하는 경우 이 매개변수를 추가합니다.

생성자 및 액세서

stingray.PhysicsWorld.make_raycast()

기타 관련 참조 항목

	collision_hit
	stingray.PhysicsWorld.make_raycast() stingray.PhysicsWorld.raycast()
	Physics

관련 도움말 항목

	게임플레이 생성 > Lua를 사용한 스크립팅 > Lua API 사용 > 오브젝트 수명 및 사용자 데이터 바인딩
	게임 플레이 테스트 > 메모리 사용 최적화

함수

cast ( self, start, dir, length ) : any(boolean, collision_hit[]), stingray.Vector3?, number?, stingray.Vector3?, stingray.Actor? 지정된 시작점에서 지정된 방향으로 광선을 투사하여 지정된 Raycast 오브젝트와 동일한 PhysicsWorld에 존재하는 물리적 오브젝트와의 충돌을 테스트합니다.

매개변수

self :	stingray.Raycast	이 함수가 작동하는 오브젝트 인스턴스를 지정합니다. 콜론 : 호출 구문을 사용하여 이 오브젝트의 인스턴스에 대해 이 함수를 호출할 수도 있습니다. 그렇게 하는 경우에는 이 매개변수를 생략해야 합니다. 자세한 내용은 이 Stingray 도움말 항목 또는 Lua 설명서의 이 페이지를 참조하십시오.
start :	stingray.Vector3	광선 투사를 위한 시작 위치를 지정합니다.
dir :	stingray.Vector3	시작 지점에서 광선이 투사되는 방향을 지정합니다.
length :	number?	선택 사항입니다. 광선의 최대 길이를 지정합니다. 지정하지 않으면 광선이 무한대로 길어집니다. ? 표기는 이 유형이 선택 사항임을 나타냅니다. 해당 인스턴스가 0개 또는 한 개일 수 있습니다.

반환하는 항목

any(boolean, collision_hit[])	충돌이 발생했는지 여부를 나타냅니다. any(...) 표기는 이 항목이 괄호 내에 표시되는 어떠한 유형의 인스턴스도 될 수 있다는 의미입니다.
stingray.Vector3?	충돌 위치입니다. ? 표기는 이 유형이 선택 사항임을 나타냅니다. 해당 인스턴스가 0개 또는 한 개일 수 있습니다.
number?	충돌까지의 거리입니다. ? 표기는 이 유형이 선택 사항임을 나타냅니다. 해당 인스턴스가 0개 또는 한 개일 수 있습니다.
stingray.Vector3?	충돌 표면의 법선입니다. ? 표기는 이 유형이 선택 사항임을 나타냅니다. 해당 인스턴스가 0개 또는 한 개일 수 있습니다.
stingray.Actor?	충돌한 액터입니다. ? 표기는 이 유형이 선택 사항임을 나타냅니다. 해당 인스턴스가 0개 또는 한 개일 수 있습니다.

Raycast 오브젝트를 생성하기 위해 PhysicsWorld.make_raycast()를 호출할 때 콜백 함수를 지정한 경우에는 광선 투사가 비동기적으로 수행되고, 충돌 테스트 결과가 해당 콜백 함수로 전달됩니다.

PhysicsWorld.make_raycast()를 호출할 때 콜백 함수에 대해 nil 값을 전달한 경우에는 광선 투사가 즉시 수행되고, 충돌 테스트 결과는 Raycast.cast()에 의해 반환됩니다. 반환 값을 해석하는 자세한 방법은 Raycast 오브젝트 설명을 참조하십시오.