Raycasts
Proveďte body-local raycast jednorázově nebo použijte nastavený query objekt.
Ověřeno podle zdrojů projektu 19. září 2026.
Syntax#
jolt_asset_get_raycast(asset, raycast_ref);
jolt_asset_raycast(asset, raycast_ref, owner_body, [options]);
jolt_asset_create_raycast(asset, raycast_ref, owner_body);Factory funkce při chybě vracejí undefined; ihned přečtěte jolt_get_error(). Lookup vrací samostatnou validovanou kopii záznamu. Reference je kanonické UUID nebo přesný Key rozlišující velikost písmen. Vlastník musí být živé spravované těleso aktuálního světa.
Světová transformace = aktuální transformace originu Body × lokální transformace z assetu. Těžiště není autorovací počátek. Pozice používají metry a rotace normalizované XYZW quaterniony. Při pohybu tělesa snímky znovu načítejte.
Authoring definuje position, rotation a length. Směr je lokální +Z. Délka musí být větší než 1e-6 a nejvýše sqrt(FLT_MAX)/2 metrů; extrémně velké světové souřadnice mohou přesto sloučit koncové body. Cast vzorkuje aktuální svět, nikoli budoucí trajektorii či pohybový sweep.
| API / pole | Význam a pravidla |
|---|---|
| options.layers / options.mask | Pouze jedna varianta filtru. mask je uint32; výchozí 0 zachovává běžnou sémantiku dotazu. |
| options.ignore | Jedno živé spravované těleso nebo undefined. Vlastník se výchozí neignoruje. |
| options.length | Volitelné validované přepsání autorované délky. |
| query.set_ignore(body | undefined) | Boolean; odmítnutý vstup zachová předchozí filtr. |
| query.cast() | Běžný výsledek nejbližšího zásahu: kontrolujte hit, error_code a error_message. |
Příklad#
// Create, once; Key "ground_front" must exist in the asset.
ground_ray = jolt_asset_create_raycast(asset, "ground_front", body_vehicle);
if (!is_undefined(ground_ray)) ground_ray.set_ignore(body_vehicle);
// Step, whenever a fresh result is needed:
if (!is_undefined(ground_ray)) {
var hit = ground_ray.cast();
if (hit.hit) show_debug_message(hit.distance);
if (hit.error_code != 0) show_debug_message(hit.error_message);
}Nastavený dotaz uchovává validovaný snímek, sleduje aktuální transformaci tělesa a při každém castu znovu kontroluje vlastníka i ignorované těleso. Nealokuje nativní zdroj, nemá automatický update a nepotřebuje destroy(). Po použití zrušte reference. Pro jednorázová volání s options zůstává jolt_asset_raycast.
Ověřené kontrakty operací#
Následující kontrakty rozlišují jednotky, návratové hodnoty, chyby a životnost podle aktuální implementace. Nevynechávej kontrolu výsledku: false, 0 a undefined mohou mít u různých metod odlišný význam.
| Symbol / vlastník | Signatura | Kontrakt operace |
|---|---|---|
| AssetRaycast.cast | AssetRaycast.cast() | Provede aktuální nearest query a vrací standardní hit výsledek včetně chybového stavu. Není uložený starý zásah. |
| AssetRaycast.get_ray | AssetRaycast.get_ray() | is_valid Boolean ownera; get_ray aktuální světový origin/target/direction/length/filter bez raycastu, undefined při chybě. |
| AssetRaycast.is_valid | AssetRaycast.is_valid() | is_valid Boolean ownera; get_ray aktuální světový origin/target/direction/length/filter bez raycastu, undefined při chybě. |
| AssetRaycast.set_ignore | AssetRaycast.set_ignore(body) | Živý managed Body nebo undefined (neignorovat nic); Boolean, neplatná změna zachová dosavadní filtr. |
| jolt_asset_create_raycast | jolt_asset_create_raycast(asset,raycast_ref,owner) | Vrací AssetRaycast/undefined s nezávislým záznamem a půjčeným ownerem. Nevytváří native zdroj ani neprovádí dotaz; pro nový zásah volej cast. |
| jolt_asset_get_raycast | jolt_asset_get_raycast(asset,raycast_ref) | Asset + přesný key nebo kanonické UUID. Znovu validuje mutable asset a vrací nezávislý datový záznam, nikoliv fyzikální objekt; chyba undefined a managed error. |
| jolt_asset_raycast | jolt_asset_raycast(asset,raycast_ref,owner,options=undefined) | Okamžitý nearest-hit výsledek ze světového rámce ownera, lokální +Z. Options layers NEBO mask, ignore, length; owner se automaticky neignoruje. Při chybě hit:false a error_code/message, ne undefined. |