Raycasting

Výsledky raycastu

Vysvětluje managed fields a bezpečné rozlišení zásahu, minutí a chyby.

Běžný closest-hit dotaz vrací úplný managed struct. Časná high-level validační chyba může vrátit pouze minimální {hit:false}, proto musí být jolt_get_error() přečteno ihned po volání, ještě než se použijí volitelná result fields.

Closest-hit výsledek nyní obsahuje také ray:{world,origin,target} při platném zásahu i minutí. Do JoltRenderSurface.set_touch_raycast() předávejte celý čerstvý výsledek, nikdy result.hit. Kontaktní pole stále vyžadují hit=true; při časné chybě validace mohou metadata ray chybět.

Fields běžného closest-hit výsledku#

Field	Typ	Význam
hit	Boolean	true, když bylo zasaženo spravované rigid body.
body	JoltBody \| undefined	Namapovaný JoltBody, nebo undefined při minutí či neúspěšném mapování.
body_handle	Real	Neprůhledný veřejný generational body handle rozšíření; nejde o Jolt BodyID.
entity	Any	Aktuální hodnota JoltBody.user_data, nebo undefined.
position	Struct {x:Real, y:Real, z:Real}	World-space bod zásahu {x,y,z} ve veřejném Z-up systému.
normal	Struct {x:Real, y:Real, z:Real}	World-space normála povrchu {x,y,z} ve veřejném Z-up systému.
fraction	Real	Normalizovaná poloha na úsečce, běžně od 0 do 1.
distance	Real	World-space vzdálenost od počátku.
error_code	Real	Stav nativního výsledku běžného low-level dotazu.
error_message	String	Nativní zpráva; prázdná při platném zásahu nebo minutí.

Rozhodující kontrola stavu#

var result = jolt_raycast(x1, y1, z1, x2, y2, z2, filter);
var error = jolt_get_error(); // Přečtěte před dalším Jolt voláním.

if (error.code != JOLT_ERROR_NONE) {
    show_debug_message(error.context + ": " + error.message);
}
else if (!result.hit) {
    // Platné minutí. Nepoužívejte contact fields jako zásah.
}
else {
    var point = result.position;
    var normal = result.normal;
    var body = result.body;
    var data = result.entity;
}

Stavy výsledku#

Stav	Rozpoznání
Closest hit	jolt_get_error().code je NONE a result.hit je true.
Closest miss	Error code je NONE a result.hit je false.
Closest error	jolt_get_error().code je nenulový; result může obsahovat pouze hit=false.
All-hit success	Error code je NONE; pole může obsahovat nula nebo více hits.
All-hit error	Error code je nenulový; vrácené pole je prázdné.

Fraction a distance#

Pro endpoint formu je maximální vzdáleností délka od origin k endpointu. distance se rovná fraction vynásobené touto délkou. position již obsahuje world-space bod, takže jej obvykle není nutné dopočítávat.

Body, handle a user data#

Native body ukládá veřejný handle rozšíření ve svém user-data slotu. Wrapper ověří handle proti managed registry, zpřístupní jej jako body_handle, namapuje body na JoltBody a poté zkopíruje JoltBody.user_data do entity. entity patří volajícímu a nemusí jít o GameMaker instance.

Fields, které nejsou dostupné#

Jolt BodyID
SubShapeID nebo compound child
Triangle nebo face index
Physics material
Motion type, layer nebo sensor flag

Low-level result struct#

{
    hit, error_code, error_message, body,
    x, y, z,
    normal_x, normal_y, normal_z,
    fraction, distance,
    position, normal
}

Low-level body je číselný veřejný handle rozšíření. Managed forma jej namapuje na JoltBody a číslo zachová jako body_handle.

Nové související postupy#

Surface input