Asset API ovládacích prvků a JSON v3

Vyhledání, vytváření, kompatibilita JSON v3 a datová pravidla jednotlivých typů.

JoltPhysics Asset Editor 0.31.1 · ověřeno podle zdrojů projektu 27. září 2026.

Syntax#

jolt_asset_get_control(asset, control_ref);
jolt_asset_create_control(asset, control_ref, body, [options]);
jolt_asset_control_settings();

Návratové hodnoty a chyby#

jolt_asset_get_control vrací nezávislý validovaný záznam; jolt_asset_create_control vrací stávající typ JoltControl. Obě funkce při chybě vracejí undefined; ihned čtěte jolt_get_error() nebo jolt_get_error_message(). Runtime metadata obsahují authoring_id, authoring_key, authoring_name a authoring_configuration_id; nejsou to runtime handly.

JSON v3#

Dokumenty s controls[] používají version:3 a format:"joltphysics-authoring". Controls jsou oddělené od shapes[]: vznikají jako samostatná pohyblivá tělesa s vazbami, nikoli compound children. Načtení žádný mechanismus nealokuje a jolt_asset_create_body vytváří jen kolizní tvary. Asset pouze s controls lze načíst; jeho ovladače vytvořte na existujícím rodiči. Assety bez controls zachovávají export v1/v2.

Všech devět typů sdílí jeden prostor Key v rámci rootu; Key odpovídá [a-z][a-z0-9_]{0,63}. UUID zůstávají globálně unikátní mezi kategoriemi. Display Name je volitelné. Pozice je [x,y,z] v metrech a rotace normalizovaný quaternion [x,y,z,w]. Stávající mirror-X převod je aplikován při exportu; v GML jej neopakujte.

Společná pole jsou id, key, volitelné name, type, position, rotation, mass a resistance. Všechny typy kromě wheel/crank mají také auto_return, target, drive a detents. Rozměry a hmotnost musí být kladné konečné reprezentovatelné hodnoty; odpor je nezáporný. Drive používá max_force pro button/slider/pull_handle, jinak max_torque, dále frequency a damping.

Minimální asset pouze s ovladačem#

{
  "format": "joltphysics-authoring",
  "version": 3,
  "configuration_id": "ad000000-0000-4000-8000-000000000001",
  "shapes": [],
  "controls": [{
    "id": "ad000000-0000-4000-8000-000000000002",
    "key": "start_button", "type": "button",
    "position": [0, 0, 0], "rotation": [0, 0, 0, 1],
    "size": [0.12, 0.12, 0.03], "mass": 0.15,
    "travel": 0.02, "initial_value": 0,
    "pressed_threshold": 0.8, "released_threshold": 0.6,
    "auto_return": true, "target": 0, "resistance": 0,
    "drive": {"max_force": 12, "frequency": 12, "damping": 1},
    "detents": []
  }]
}

Zarážky#

Skalární/joystickové zarážky dovolují nejvýše 256 unikátních pozic. Serializovaný záznam vyžaduje value (nebo x/y), capture_range, release_range, max_force/max_torque, frequency a damping. Platí 0 < capture_range < release_range, kladná síla/moment a frekvence, nezáporné tlumení. Auto Return má přednost; vypněte jej, má-li mechanismus zůstávat v zarážkách.

Wheel/Crank periodic_detents vyžaduje count, capture_angle, release_angle, max_torque, frequency a damping. count je celé 1..3600; step=360/count, capture_angle ≤ step/2 a capture_angle < release_angle < min(step,45°). V JSONu vypnutí znamená pole vynechat. Runtime options přijímají false i zkratku {count:12}; chybějící výchozí hodnoty doplní runtime validátor.

Kompatibilita#

Aktuální loader podporuje v1/v2/v3. Starší loadery odmítnou nepodporované verze/typy místo tichého vynechání mechanismů. Aktualizujte addon i GML společně. Stávající kategorie zachovávají souřadnicová pravidla a životnost.

Simulace, vykreslení a životnost#

Použijte stávající smyčku jolt_update() a poté čtěte fyzikální stav ovladače. Vizuální model řiďte přes control.get_transform() nebo stávající vykreslovací API ovladačů. Asset helper vytvoří stejné JoltControl těleso a vazbu jako přímá factory; nevykresluje váš model a nepřiřazuje herní akce. Každé vytvoření je samostatné.

control.destroy() odstraní mechanismus a zachová rodiče. Zničení rodiče a jolt_stop() uklidí připojené ovladače. Používejte spravovanou životnost. Blender integrace ovladačů nevyžaduje další změnu nativního bridge; použijte odpovídající aktuální GML loader a skripty jolt_asset_controls.

• Fyzikální ovládací prvky z Blenderu›
• Konstrukční nastavení›

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.