Pomocné skripty

Nejbližší bod

Najde nejbližší bod na skutečné Jolt kolizní geometrii bez změny fyzikálního světa.

jolt_closest_point prohledá managed rigid bodies a najde kolizní povrch nejblíže zadané veřejné Z-up world-space pozici. Vrací existující JoltBody wrapper, přesný bod cílového povrchu, vnější world-space normálu a eukleidovskou vzdálenost bod–povrch. Pro jedno známé těleso provede JoltBody.get_closest_point stejné narrow-phase měření bez prohledávání světa.

Syntaxe#

jolt_closest_point(x, y, z, options=undefined)
body.get_closest_point(x, y, z)

Argumenty#

Argument	Typ	Popis
x	Real	Konečná veřejná world-space souřadnice X dotazovaného bodu.
y	Real	Konečná veřejná world-space souřadnice Y dotazovaného bodu.
z	Real	Konečná veřejná world-space souřadnice Z dotazovaného bodu.
options	Struct nebo undefined	Volitelné filtry vzdálenosti, vrstvy, tělesa, motion type a sensorů pro hledání ve světě.

Options pro hledání ve světě#

Field	Výchozí hodnota	Popis
max_distance	Bez omezení	Volitelná kladná konečná vzdálenost k povrchu. Explicitní nula nebo záporná hodnota je neplatná.
layers	undefined	Jeden JoltLayer nebo pole převedené běžnými pravidly query mask.
mask	undefined	Číselná maska vrstev; pokud existuje, má přednost před layers.
ignore	undefined	Jedno živé JoltBody z managed default world, které se má vynechat.
motion	Všechny typy	JOLT_MOTION_STATIC, JOLT_MOTION_KINEMATIC nebo JOLT_MOTION_DYNAMIC.
include_sensors	true	Nastavte false pro vynechání sensor bodies.

Výsledek#

Field	Popis
hit	True, když byl nalezen vhodný kolizní povrch.
body / body_handle / body_valid	Existující managed wrapper, opaque handle a aktuální platnost wrapperu.
entity	Hodnota user_data vybraného tělesa.
position	Přesný nejbližší bod cílového kolizního povrchu ve veřejném world space.
normal	Vnější world-space normal cílového povrchu.
distance	Eukleidovská vzdálenost od původního query point k position.
target_sub_shape_id	Native identifikátor cílového sub-shape, užitečný pro diagnostiku Compound a komplexní geometrie.
candidate_count	Přijatí broad-phase kandidáti, nebo navštívená managed bodies při neomezeném hledání.
exact_body_tests	Bodies, která prošla všemi filtry až do Jolt narrow phase.
error_code / error_message	JOLT_ERROR_NONE a prázdný string při platném zásahu i obyčejném miss.

Pravidla povrchu#

Dotaz používá Jolt 5.6 narrow-phase kolizní geometrii, nikoli středy bodies nebo axis-aligned bounds.
Rotované primitivy, Convex, Mesh, HeightField, Compound child transformy, reusable shapes i OffsetCenterOfMassShape se měří proti skutečným povrchům.
Pro bod uvnitř solid convex tvaru je výsledkem nejbližší exit surface vybraný Joltem a distance zůstává kladná. Bod na povrchu vrátí přibližně nulu.
Při přesné symetrii může být několik povrchových bodů stejně platných, proto zvolený směr nepoužívejte jako stabilní gameplay identifikátor.
Mesh a HeightField normals respektují autorské triangle winding; inside má smysl pouze u vhodně uzavřeného a konzistentně orientovaného mesh.
Stejné vzdálenosti při hledání ve světě se deterministicky rozhodnou nižším veřejným body handle v malé numerické toleranci.

Hledání ve světě a dotaz na jedno těleso#

Varianta	Použití
jolt_closest_point(...)	Prohledá vhodná managed rigid bodies a podporuje všechny options a filtry.
body.get_closest_point(...)	Přímo otestuje jedno známé živé body; žádná další tělesa neprohledává.

Chování a výkon#

Dotazy jsou read-only, zahrnují sleeping bodies a nikdy je neaktivují.
Konečné max_distance umožní Joltu cullovat kandidáty přes broad phase a doporučuje se, pokud gameplay zná interaction radius.
Neomezené globální hledání záměrně prochází managed body registry a má složitost O(N) podle počtu managed rigid bodies.
candidate_count a exact_body_tests zobrazují množství práce dotazu pro diagnostiku bez změny stavu simulace.
Při zapnutém JOLT_DEBUG_SHAPE_QUERIES debug renderer zaznamená vstupní bod, segment k povrchu, nejbližší marker a normal.

Příklad#

var nearest = jolt_closest_point(player_x, player_y, player_z, {
    max_distance: 5,
    ignore: player_body,
    include_sensors: false
});

if (nearest.hit) {
    show_debug_message("Distance: " + string(nearest.distance));
    show_debug_message("Body: " + string(nearest.body.data.name));
}

Příklad pro známé těleso#

var surface = crate.get_closest_point(player_x, player_y, player_z);
if (surface.hit) show_debug_message(surface.distance);

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
jolt_closest_point	jolt_closest_point(x,y,z,options=undefined)	Světové XYZ m; options max_distance>0 pokud zadáno(jinak neomezeno), motion defaultvše, include_sensorstrue, layers/mask/ignore. Hit snapshot nebo hit:false:position, normal, distance, body/body_handle/body_valid/entity, target_sub_shape_id, candidate_count, exact_body_tests, error_code/message.