説明

このオブジェクトでは、PhysicsWorld 内の物理オブジェクトに対して衝突テストを実行できます。

レイキャストオブジェクトは、完全なユーザデータオブジェクトです。したがって、

作成処理に比較的多くのリソースを必要とするため、ゲーム内でいくつも作成することは望ましくありません。初期段階でレイキャストオブジェクトを作成しておき、開始ポイントや方向を変えて同じオブジェクトを繰り返し再利用することを推奨します。
レイキャストオブジェクトへの参照がスクリプト内に残っていない場合は、レイキャストオブジェクトのガベージコレクションが行われます。レイキャストオブジェクトを作成した後は、それらを削除するために特に何もする必要はありません。レイキャストオブジェクトはスコープ外に出るとすぐにガベージコレクションされます。

レイキャストを実行する

レイキャストの実行方法は 3 つあり、どの方法を取るかによって得られる結果が異なります。

オプション 1. 単一レイキャストの同期実行

レイキャストを 1 つだけ実行して結果をただちに処理する必要がある場合は、このオプションを使用します。

このシナリオでは、stingray.PhysicsWorld.raycast() 関数を呼び出します。開始ポイント、方向、レイの最大長、および衝突テストを制御するパラメータ(下記の「レイキャストパラメータ」を参照)を指定する必要があります。

たとえば、次のようになります。

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

この例では "closest" パラメータを指定してレイキャストを呼び出しているため、最初の衝突ポイントに関する詳細情報が返されます(衝突ポイントが存在する場合)。

オプション 2. 複数レイキャストの同期実行

同じパラメータ(下記の「レイキャストパラメータ」を参照)を指定して複数のレイキャストを実行し、結果をただちに処理する必要がある場合は、このオプションを使用します。このオプションでは同じ 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)
...

この例では "all" パラメータを指定して Raycast を初期化しているため、collisionResultsA 変数および collisionResultsB 変数はそれぞれ collision_hit データテーブルの配列に設定されます。

オプション 3. 複数レイキャストの非同期実行

複数のレイキャストを実行し、後のフレームまで結果の処理を保留する場合は、このオプションを使用します。

このシナリオでは...

まず、衝突テストの完了時に自動的に呼び出されるコールバック関数を記述する必要があります。この関数で扱う必要があるパラメータの種類は、テストに使用する Raycast オブジェクトの作成時にどのパラメータを指定するかによって異なります。下記の「レイキャストパラメータ」を参照してください。
stingray.PhysicsWorld.make_raycast() を呼び出して新しい Raycast オブジェクトを作成し、最初に記述した関数をコールバックパラメータとして渡します。
新しいオブジェクトの 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)
...

この例では、"all" パラメータを使用して Raycast を初期化しているため、my_raycast_callback 関数には collision_hit データテーブルの配列が渡されます。

レイキャストパラメータ

stingray.PhysicsWorld.make_raycast() を使用して新しい Raycast オブジェクトを作成する場合や、stingray.PhysicsWorld.raycast() を呼び出して単一のレイキャストを同期実行する場合は、衝突テストの動作と結果の種類を制御するパラメータを指定できます。

有効なパラメータ値は以下のとおりです。

"any": レイが何かに衝突したかどうかだけを調べるには、この値を使用します。このオプションを使用すると、衝突が検出されたかどうかを示すブール値が 1 つだけ生成されます。
"all": レイの進路上で発生したすべての衝突の詳細を調べるには、この値を使用します。このオプションを使用すると、collision_hit テーブルの配列からなるテーブルが生成され、レイの衝突ポイントが 1 つの collision_hit テーブルにつき 1 つずつ記録されます。
"closest": レイの最初の衝突だけを調べるには、この値を使用します。これは既定のモードです。このオプションを使用すると、以下の値が生成されます。
- 衝突が検出されたかどうかを示す boolean 値。この値が trueの場合は、以下の値も生成されます。
- 3D ワールドでの衝突の位置を示す Vector3。
- 要求の開始ポイントから衝突ポイントまでの距離を示す number。
- 衝突したサーフェスの法線を示す Vector3。
- 衝突した物理アクターを示す Actor。
"types": 衝突の際に考慮する必要があるオブジェクトのタイプを決定します。このパラメータを指定する場合は、タイプを指定する文字列パラメータも続けて指定する必要があります。"statics" は静的オブジェクトに対してのみレイテストを行う場合に指定します。"dynamics" は動的オブジェクトに対してのみレイテストを行う場合に指定します。"both" は静的オブジェクトと動的オブジェクトの両方に対してレイテストを行う場合に指定します。これが既定値です。
"collision_filter": このパラメータでは、レイの衝突テストの際に考慮する必要があるオブジェクトを決定する衝突フィルタを指定できます。このパラメータを指定する場合は、global.physics_properties データファイルで定義されている衝突フィルタ名を指定する文字列パラメータも続けて指定する必要があります。既定では、シーン内のすべてのオブジェクトがレイの衝突テストの対象になります。
"mesh_both_sides" 物理メッシュ内の三角形の方向にもレイキャストをヒットさせる場合は、このパラメータを追加します。

その他の関連リファレンス項目

この参照ページは、次の概要トピックと関連付けられています

関数

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?	オプション。レイの最大長を指定します。指定しない場合、レイの長さは無限になります。 ? 表記は、このタイプが省略可能であることを示しています。ゼロ個または 1 個のインスタンスが存在します。

戻り値

any(boolean, collision_hit[])	衝突が発生したかどうかを示します。 any(...) 表記は、この項目が括弧内に示されている任意のタイプのインスタンスであることを示しています。
stingray.Vector3?	衝突の位置です。 ? 表記は、このタイプが省略可能であることを示しています。ゼロ個または 1 個のインスタンスが存在します。
number?	衝突までの距離です。 ? 表記は、このタイプが省略可能であることを示しています。ゼロ個または 1 個のインスタンスが存在します。
stingray.Vector3?	衝突サーフェスの法線です。 ? 表記は、このタイプが省略可能であることを示しています。ゼロ個または 1 個のインスタンスが存在します。
stingray.Actor?	衝突したアクターです。 ? 表記は、このタイプが省略可能であることを示しています。ゼロ個または 1 個のインスタンスが存在します。

PhysicsWorld.make_raycast() を使用してレイキャストオブジェクトを作成するときにコールバック関数を指定した場合は、非同期的にレイキャストが実行され、衝突テストの結果がそのコールバック関数に渡されます。

PhysicsWorld.make_raycast() を呼び出したときにコールバック関数として nil 値を渡した場合は、即座にレイキャストが実行され、衝突テストの結果は Raycast.cast() により返されます。戻り値を解釈する方法については、Raycast オブジェクトの説明を参照してください。

	collision_hit
	stingray.PhysicsWorld.make_raycast() stingray.PhysicsWorld.raycast()
	物理

	「リリースノート > Stingray 1.9 リリースノート」
	「ゲームプレイを作成する > Lua でスクリプトを作成する > Lua API を使用する > オブジェクトのライフタイムとユーザデータのバインド」
	「ゲームをプレイテストする > メモリ使用量を最適化する」

Raycast - stingray.Raycast オブジェクト リファレンス - Stingray Lua API リファレンス

説明