Aktuální projekt
Carry: přenášení předmětů
Carry je současný controller jolt_grabber(). Uchopitelné těleso povol pomocí set_grab_enabled(true). Drží těžiště, pokud set_grab_point(x,y,z) neurčí lokální bod; bod měň po puštění.
Příklad#
body.set_grab_enabled(true);
carry = jolt_grabber();
carry.set_camera(o_control_bbmod_camera);
carry.set_distances(3, 1.5, 0.1, 3, 4);
carry.set_preserve_grab_distance(true);
carry.set_max_mass(30);
carry.set_strength(1200);
carry.set_max_torque(300);
// End Step:
carry.update_controls();Použití a omezení#
set_distances přijímá dosah výběru, vzdálenost držení, minimum, maximum a mez puštění v metrech. Platí min ≤ hold ≤ max a break > max(dosah, maximum). preserve_grab_distance má v knihovně výchozí false; demo jej zapíná.
Výchozí vstup je LMB sebrat/pustit, RMB s myší otočit, kolečko vzdálenost, R srovnat a F odhodit. Kamera musí ve Step před mouse-look respektovat carry.controls_use_mouse(id); update_controls volejte v End Step po kameře. Ztráta fokusu nebo chybějící/odemčená kamera pustí úchop. Nezpracovávejte vstup zároveň automaticky a ručně.
set_auto_upright, set_yaw_follow a set_snap_step působí fyzikálním momentem; orientační volby jsou výchozí vypnuté. Kolize, limity hmotnosti a síly platí dál. Vnější klouby obvykle Carry blokují. Interní ragdoll klouby a povolení hostitelé s ovládacími prvky jsou podporováni; pohyblivé rukojeti nejsou Carry předměty. Soft Body používá get_held_type()/get_soft_body(), get_body() zůstává pro pevná tělesa. get_last_reason() vysvětlí odmítnutí. Grabber zrušte v Clean Up.
Přehled API#
Signatury veřejných funkcí a metod. Metody volejte na vrácené instanci; parametry s výchozí hodnotou jsou volitelné.
Související návody#
Penetrační spojení mají výjimku z běžného zákazu uchopení externě spojených mechanismů. Podporované jsou rigid bodies, ragdolly a Soft Body; stav held_type rozlišuje druh. Síla a moment jsou omezené a kontakt může měnit orientaci drženého předmětu.
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_grabber | jolt_grabber(options=undefined) | Vyžaduje jolt_start, vrací JoltGrabber nebo undefined. Jediný profil carry; default vzdálenosti 3/1.5/0.1/3/4 m, max_mass 30 kg, break_delay 0.1 s, preserve_distance/upright/yaw/socket_pull false. Layers je creation option. Legacy damping odmítá: použij damping_ratio. |
| JoltBody.clear_grab_point | JoltBody.clear_grab_point() | Místní bod vůči originu v m, setter/clear Boolean. Clear vrátí automatický bod; getter {x, y, z} nebo undefined. Nejde o aktuální světový bod ruky. |
| JoltBody.get_grab_enabled | JoltBody.get_grab_enabled() | Nezávislé opt-in příznaky, výchozí false. Setter Boolean/0/1 → Boolean; getter Boolean false i při chybě. Grip nyní přijímá Static i Kinematic, nikoliv Dynamic; grab_enabled nezaručuje splnění dalších Carry podmínek. |
| JoltBody.get_local_grab_point | JoltBody.get_local_grab_point() | Místní bod vůči originu v m, setter/clear Boolean. Clear vrátí automatický bod; getter {x, y, z} nebo undefined. Nejde o aktuální světový bod ruky. |
| JoltBody.set_grab_enabled | JoltBody.set_grab_enabled(enabled) | Nezávislé opt-in příznaky, výchozí false. Setter Boolean/0/1 → Boolean; getter Boolean false i při chybě. Grip nyní přijímá Static i Kinematic, nikoliv Dynamic; grab_enabled nezaručuje splnění dalších Carry podmínek. |
| JoltBody.set_grab_point | JoltBody.set_grab_point(x,y,z) | Místní bod vůči originu v m, setter/clear Boolean. Clear vrátí automatický bod; getter {x, y, z} nebo undefined. Nejde o aktuální světový bod ruky. |
| JoltGrabber.add_distance | JoltGrabber.add_distance(delta) | Boolean; vzdálenost nebo přírůstek v m. Native omezuje držení dle rozsahu controlleru; add_distance vychází z get_distance. |
| JoltGrabber.controls_use_mouse | JoltGrabber.controls_use_mouse(view) | Boolean, zda daná živá kamera se zamčenou myší má přenechat myš ruční rotaci drženého předmětu. Volej v Camera Step před použitím delty. |
| JoltGrabber.destroy | JoltGrabber.destroy() | Boolean, opakované volání po zničení true. Release pustí předmět; destroy navíc zničí controller. Nevlastní a neničí držený objekt. |
| JoltGrabber.get_applied_force | JoltGrabber.get_applied_force() | Číslo: chyba pozice m / aplikovaná síla N / vzdálenost držení m. Při neplatnosti 0, samotná nula není důkaz platnosti. |
| JoltGrabber.get_body | JoltGrabber.get_body() | Vrací managed rigid JoltBody / Soft Body dle metody; undefined pokud nic nebo jiný typ nedrží. |
| JoltGrabber.get_distance | JoltGrabber.get_distance() | Číslo: chyba pozice m / aplikovaná síla N / vzdálenost držení m. Při neplatnosti 0, samotná nula není důkaz platnosti. |
| JoltGrabber.get_error_distance | JoltGrabber.get_error_distance() | Číslo: chyba pozice m / aplikovaná síla N / vzdálenost držení m. Při neplatnosti 0, samotná nula není důkaz platnosti. |
| JoltGrabber.get_grab_point | JoltGrabber.get_grab_point() | Světový {x, y, z} v m reference / uchopení / cíle; undefined bez držení či při chybě. |
| JoltGrabber.get_grab_rotation | JoltGrabber.get_grab_rotation() | Světový quaternion XYZW cíle / reference / skutečného tělesa či držené soft-body oblasti. undefined při chybě nebo bez držení. |
| JoltGrabber.get_grab_vertex_count | JoltGrabber.get_grab_vertex_count() | Typ je none/body/soft_body. Počet vybraných soft vertices je číslo, 0 bez držení; není celkový počet vertices látky. |
| JoltGrabber.get_held_type | JoltGrabber.get_held_type() | Typ je none/body/soft_body. Počet vybraných soft vertices je číslo, 0 bez držení; není celkový počet vertices látky. |
| JoltGrabber.get_ignore_holder_collision | JoltGrabber.get_ignore_holder_collision() | Boolean současného příznaku, false i při chybě. |
| JoltGrabber.get_last_reason | JoltGrabber.get_last_reason() | Diagnostický řetězec none/released/no_source/no_hit/grab_disabled/invalid_motion/mass_limit/mechanism/already_held/support_body/out_of_reach/break_distance/body_changed/body_destroyed/holder_destroyed/numerical_failure/physics_locked; invalid_handle při neplatnosti. |
| JoltGrabber.get_profile | JoltGrabber.get_profile() | Pouze řetězec carry. Setter Boolean, getter carry nebo undefined při neplatném objektu. Starý controller není druhý podporovaný profil. |
| JoltGrabber.get_reference_point | JoltGrabber.get_reference_point() | Světový {x, y, z} v m reference / uchopení / cíle; undefined bez držení či při chybě. |
| JoltGrabber.get_reference_rotation | JoltGrabber.get_reference_rotation() | Světový quaternion XYZW cíle / reference / skutečného tělesa či držené soft-body oblasti. undefined při chybě nebo bez držení. |
| JoltGrabber.get_soft_body | JoltGrabber.get_soft_body() | Vrací managed rigid JoltBody / Soft Body dle metody; undefined pokud nic nebo jiný typ nedrží. |
| JoltGrabber.get_status | JoltGrabber.get_status() | On-demand struct: profile, holding, manual_rotation, reason, source_distance, position_error (m), rotation_error (°), force (N), torque_budget (N·m), saturation, force_usage, torque_usage, socket_pulling; undefined při neplatnosti. Nevolej jen pro pohyb hráče. |
| JoltGrabber.get_target_point | JoltGrabber.get_target_point() | Světový {x, y, z} v m reference / uchopení / cíle; undefined bez držení či při chybě. |
| JoltGrabber.get_target_rotation | JoltGrabber.get_target_rotation() | Světový quaternion XYZW cíle / reference / skutečného tělesa či držené soft-body oblasti. undefined při chybě nebo bez držení. |
| JoltGrabber.get_unlock_physics_locked | JoltGrabber.get_unlock_physics_locked() | Boolean současného příznaku, false i při chybě. |
| JoltGrabber.get_up | JoltGrabber.get_up() | Světový nenulový konečný Up vektor; setter Boolean, getter {x, y, z} nebo undefined. |
| JoltGrabber.grab | JoltGrabber.grab() | Boolean pokusu o uchopení z posledního zdroje. Vyžaduje grab_enabled a podporovaný objekt; při neúspěchu čti get_last_reason. Podporuje rigid i soft body, Socket tah je opt-in. |
| JoltGrabber.is_holding | JoltGrabber.is_holding() | Boolean, false i při neplatném controlleru. |
| JoltGrabber.is_manual_rotation | JoltGrabber.is_manual_rotation() | Setter Boolean/0/1 vstup a Boolean úspěch, getter Boolean (false i při chybě). Ruční režim mění fyzikální cíl rotace. |
| JoltGrabber.is_valid | JoltGrabber.is_valid() | Boolean ověření wrapperu a native handle. |
| JoltGrabber.realign | JoltGrabber.realign() | Boolean; požádá o narovnání fyzikálního cíle, ne okamžitý transform. |
| JoltGrabber.release | JoltGrabber.release() | Boolean, opakované volání po zničení true. Release pustí předmět; destroy navíc zničí controller. Nevlastní a neničí držený objekt. |
| JoltGrabber.rotate | JoltGrabber.rotate(yaw,pitch,roll=0) | Boolean; konečné přírůstky yaw/pitch/roll ve stupních okolo Camera Up/Right/Forward. Roll default 0. Žádný teleport tělesa. |
| JoltGrabber.rotate_mouse | JoltGrabber.rotate_mouse(dx,dy,dt=undefined) | Boolean; yaw/pitch/roll °/s nebo myší dx/dy v pixelech. dt v (0, 0.25] s; vynechané z delta_time, fallback 1/60, cap 0.25. Obnovuj každý vstupní frame; rotate_mouse použije sensitivity a obrátí X yaw. |
| JoltGrabber.scroll_distance | JoltGrabber.scroll_distance(steps) | Boolean; konečný počet kroků násobený distance_step; vzdálenost respektuje min/max. |
| JoltGrabber.set_auto_upright | JoltGrabber.set_auto_upright(value) | Boolean výsledek; vstup Boolean nebo přesné 0/1, default false. Zachování vzdálenosti / automatické narovnání / následování yaw / tah roztrhnutelných Socketů podle názvu. |
| JoltGrabber.set_break_delay | JoltGrabber.set_break_delay(value) | Boolean; konečná hodnota, rozsah 0..2, veřejná jednotka s. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_break_distance | JoltGrabber.set_break_distance(value) | Boolean; jednotlivá vzdálenost v m musí vyhovovat celému aktuálnímu rozsahu set_distances. Pro změnu více mezí používej atomické set_distances, aby mezikrok nebyl neplatný. |
| JoltGrabber.set_camera | JoltGrabber.set_camera(source) | Objekt kamery, živá instance nebo undefined; Boolean. Změna kamery pustí předmět. Kamera musí poskytovat camera.Position/Target/Up s X/Y/Z a mouse_locked. |
| JoltGrabber.set_damping_ratio | JoltGrabber.set_damping_ratio(value) | Boolean; konečná hodnota, rozsah 0.05..10, veřejná jednotka ratio. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_debug_break_range | JoltGrabber.set_debug_break_range(enabled) | Striktní Boolean vstup, Boolean výsledek. Default false/false/true. Ovlivní jen diagnostické kreslení. |
| JoltGrabber.set_debug_details | JoltGrabber.set_debug_details(enabled) | Striktní Boolean vstup, Boolean výsledek. Default false/false/true. Ovlivní jen diagnostické kreslení. |
| JoltGrabber.set_debug_labels | JoltGrabber.set_debug_labels(enabled) | Striktní Boolean vstup, Boolean výsledek. Default false/false/true. Ovlivní jen diagnostické kreslení. |
| JoltGrabber.set_distance | JoltGrabber.set_distance(distance) | Boolean; vzdálenost nebo přírůstek v m. Native omezuje držení dle rozsahu controlleru; add_distance vychází z get_distance. |
| JoltGrabber.set_distance_step | JoltGrabber.set_distance_step(value) | Boolean; konečná hodnota, rozsah 0.001..100, veřejná jednotka m. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_distances | JoltGrabber.set_distances(grab,hold,minimum,maximum,break) | Boolean, atomické nastavení v m: grab, hold, min, max, break. 0.01<=min<=hold<=max<=10000, grab 0.01..10000, break<=20000 a >max(grab, max). Při chybě zachová původní nastavení. |
| JoltGrabber.set_follow_speed | JoltGrabber.set_follow_speed(value) | Boolean; konečná hodnota, rozsah 0.001..1000, veřejná jednotka m/s. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_frequency | JoltGrabber.set_frequency(value) | Boolean; konečná hodnota, rozsah 0.1..60, veřejná jednotka Hz. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_grab_button | JoltGrabber.set_grab_button(button) | Boolean; celá tlačítka myši 0..5 / klávesy 0..255. 0 vypne akci; default levá, pravá, R, F. |
| JoltGrabber.set_grab_distance | JoltGrabber.set_grab_distance(value) | Boolean; jednotlivá vzdálenost v m musí vyhovovat celému aktuálnímu rozsahu set_distances. Pro změnu více mezí používej atomické set_distances, aby mezikrok nebyl neplatný. |
| JoltGrabber.set_hold_distance | JoltGrabber.set_hold_distance(value) | Boolean; jednotlivá vzdálenost v m musí vyhovovat celému aktuálnímu rozsahu set_distances. Pro změnu více mezí používej atomické set_distances, aby mezikrok nebyl neplatný. |
| JoltGrabber.set_holder | JoltGrabber.set_holder(holder) | Živý JoltCharacter stejného světa nebo undefined. Boolean; zachová současnou volbu ignore_holder_collision, Character nevlastní. |
| JoltGrabber.set_ignore_holder_collision | JoltGrabber.set_ignore_holder_collision(ignore) | Boolean výsledek; Boolean nebo přesné 0/1. Ignorování kolize s holderem / povolení odemknutí physics_locked při grab; default false. |
| JoltGrabber.set_manual_rotation | JoltGrabber.set_manual_rotation(enabled) | Setter Boolean/0/1 vstup a Boolean úspěch, getter Boolean (false i při chybě). Ruční režim mění fyzikální cíl rotace. |
| JoltGrabber.set_manual_sensitivity | JoltGrabber.set_manual_sensitivity(value) | Boolean; konečná hodnota, rozsah 0.001..20, veřejná jednotka °/pixel. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_manual_velocity | JoltGrabber.set_manual_velocity(yaw,pitch,roll=0,dt=undefined) | Boolean; yaw/pitch/roll °/s nebo myší dx/dy v pixelech. dt v (0, 0.25] s; vynechané z delta_time, fallback 1/60, cap 0.25. Obnovuj každý vstupní frame; rotate_mouse použije sensitivity a obrátí X yaw. |
| JoltGrabber.set_max_acceleration | JoltGrabber.set_max_acceleration(value) | Boolean; konečná hodnota, rozsah 0.001..1000, veřejná jednotka m/s². Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_max_angular_acceleration | JoltGrabber.set_max_angular_acceleration(value) | Boolean; konečná hodnota, rozsah 0.001..1000 rad/s² converted from input degrees, veřejná jednotka °/s². Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_max_mass | JoltGrabber.set_max_mass(value) | Boolean; konečná hodnota, rozsah 0.001..1000000, veřejná jednotka kg. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_max_torque | JoltGrabber.set_max_torque(value) | Boolean; konečná hodnota, rozsah 0.001..100000000, veřejná jednotka N·m. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_maximum_distance | JoltGrabber.set_maximum_distance(value) | Boolean; jednotlivá vzdálenost v m musí vyhovovat celému aktuálnímu rozsahu set_distances. Pro změnu více mezí používej atomické set_distances, aby mezikrok nebyl neplatný. |
| JoltGrabber.set_minimum_distance | JoltGrabber.set_minimum_distance(value) | Boolean; jednotlivá vzdálenost v m musí vyhovovat celému aktuálnímu rozsahu set_distances. Pro změnu více mezí používej atomické set_distances, aby mezikrok nebyl neplatný. |
| JoltGrabber.set_preserve_grab_distance | JoltGrabber.set_preserve_grab_distance(value) | Boolean výsledek; vstup Boolean nebo přesné 0/1, default false. Zachování vzdálenosti / automatické narovnání / následování yaw / tah roztrhnutelných Socketů podle názvu. |
| JoltGrabber.set_profile | JoltGrabber.set_profile(profile) | Pouze řetězec carry. Setter Boolean, getter carry nebo undefined při neplatném objektu. Starý controller není druhý podporovaný profil. |
| JoltGrabber.set_realign_key | JoltGrabber.set_realign_key(key) | Boolean; celá tlačítka myši 0..5 / klávesy 0..255. 0 vypne akci; default levá, pravá, R, F. |
| JoltGrabber.set_reference_acceleration | JoltGrabber.set_reference_acceleration(value) | Boolean; konečná hodnota, rozsah 0.001..1000, veřejná jednotka m/s². Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_reference_angular_acceleration | JoltGrabber.set_reference_angular_acceleration(value) | Boolean; konečná hodnota, rozsah 0.001..1000 rad/s² converted from input degrees, veřejná jednotka °/s². Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_reference_rotation_speed | JoltGrabber.set_reference_rotation_speed(value) | Boolean; konečná hodnota, rozsah 0.001..100 rad/s converted from input degrees, veřejná jednotka °/s. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_reference_speed | JoltGrabber.set_reference_speed(value) | Boolean; konečná hodnota, rozsah 0.001..1000, veřejná jednotka m/s. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_rotate_button | JoltGrabber.set_rotate_button(button) | Boolean; celá tlačítka myši 0..5 / klávesy 0..255. 0 vypne akci; default levá, pravá, R, F. |
| JoltGrabber.set_rotation_speed | JoltGrabber.set_rotation_speed(value) | Boolean; konečná hodnota, rozsah 0.001..100 rad/s converted from input degrees, veřejná jednotka °/s. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_snap_step | JoltGrabber.set_snap_step(value) | Boolean; 0 vypne snap, jinak 1..180° a musí dělit 360 na celé díly. |
| JoltGrabber.set_socket_pull_enabled | JoltGrabber.set_socket_pull_enabled(enabled) | Boolean výsledek; vstup Boolean nebo přesné 0/1, default false. Zachování vzdálenosti / automatické narovnání / následování yaw / tah roztrhnutelných Socketů podle názvu. |
| JoltGrabber.set_strength | JoltGrabber.set_strength(value) | Boolean; konečná hodnota, rozsah 0.001..100000000, veřejná jednotka N. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_throw_impulse | JoltGrabber.set_throw_impulse(impulse) | Boolean; konečný nezáporný impuls v N·s, default 100; platí pro automatické ovládání. |
| JoltGrabber.set_throw_key | JoltGrabber.set_throw_key(key) | Boolean; celá tlačítka myši 0..5 / klávesy 0..255. 0 vypne akci; default levá, pravá, R, F. |
| JoltGrabber.set_throw_max_speed | JoltGrabber.set_throw_max_speed(value) | Boolean; konečná hodnota, rozsah 0..1000, veřejná jednotka m/s. Mění controller, ne hmotnost či transform drženého tělesa. Throw max speed omezuje přidanou rychlost, ne celkovou rychlost. |
| JoltGrabber.set_unlock_physics_locked | JoltGrabber.set_unlock_physics_locked(enabled) | Boolean výsledek; Boolean nebo přesné 0/1. Ignorování kolize s holderem / povolení odemknutí physics_locked při grab; default false. |
| JoltGrabber.set_up | JoltGrabber.set_up(x,y,z) | Světový nenulový konečný Up vektor; setter Boolean, getter {x, y, z} nebo undefined. |
| JoltGrabber.set_yaw_follow | JoltGrabber.set_yaw_follow(value) | Boolean výsledek; vstup Boolean nebo přesné 0/1, default false. Zachování vzdálenosti / automatické narovnání / následování yaw / tah roztrhnutelných Socketů podle názvu. |
| JoltGrabber.throw_body | JoltGrabber.throw_body(impulse) | Boolean; nezáporný impuls N·s ve směru pohledu a puštění. Přidaná rychlost omezena throw_max_speed; původní hybnost se zachová. |
| JoltGrabber.update | JoltGrabber.update(ox,oy,oz,dx,dy,dz) | Boolean; světový origin v m a směrový vektor (nikoliv Target bod). update_frame přidává nenulový nezávislý Up, zachová roll a ortonormalizuje rámec. update odvodí dt z delta_time; nejsou to kroky simulace. |
| JoltGrabber.update_controls | JoltGrabber.update_controls() | Boolean; jednou v End Step po kameře. Automaticky grab/release/rotate/realign/scroll/throw; neplatná nebo odemčená kamera předmět pustí. Vyžaduje carry profil. |
| JoltGrabber.update_frame | JoltGrabber.update_frame(ox,oy,oz,dx,dy,dz,ux,uy,uz) | Boolean; světový origin v m a směrový vektor (nikoliv Target bod). update_frame přidává nenulový nezávislý Up, zachová roll a ortonormalizuje rámec. update odvodí dt z delta_time; nejsou to kroky simulace. |