Pomocné skripty

Vlastní data těles

Přiřazuje každému managed fyzikálnímu tělesu gameplay informace vlastněné projektem.

Každý high-level JoltBody nabízí veřejnou proměnnou data obsahující obyčejný GML struct. Je určená pro názvy, vlastnosti předmětů, zdraví, kategorie, inventáře a další gameplay metadata, která mají zůstat spojená s body wrapperem, ale nemají být součástí native fyzikálního stavu.

Základní použití#

body.data
options.data

Kontrakt při vytvoření#

Případ	Chování
Bez option data	Nový JoltBody dostane vlastní nezávislý prázdný struct {}.
data: {...}	Předaný struct se přiřadí přímo do body.data a nekopíruje se.
Data nejsou struct	Vytvoření body selže s JOLT_ERROR_INVALID_ARGUMENT.
Pozdější nahrazení	body.data lze kdykoliv nahradit jiným structem běžným GML přiřazením.

Podporované způsoby vytvoření tělesa#

Dynamic, Static i Kinematic konstruktory primitivních těles přijímají options.data.
Stejnou option přijímají bodies vytvořené ze znovupoužitelných JoltShape resources.
Compound builder zachová vlastní data u create, create_static i create_kinematic.
Každé body bez explicitních dat dostane jiný container; změna výchozího structu jednoho tělesa neovlivní ostatní.

Reference a změny dat#

Předaný struct používá běžnou aktuální reference/value semantiku GameMakeru. Rozšíření neprovádí deep clone.
Nested structs a arrays zůstávají dostupné a lze je měnit přes body.data.
Pokud stejný struct drží i jiná proměnná, změny přes jednu referenci jsou podle běžných pravidel GML viditelné i přes druhou.
Rozšíření nekontroluje jednotlivá pole, protože jejich schema patří výhradně hernímu projektu.

Kde data zůstávají dostupná#

Výsledek nebo systém	Přístup
Raycast a Shape Queries	Použijte hit.body.data z vráceného registrovaného JoltBody wrapperu.
Collision a sensor eventy	Použijte event.body_a.data a event.body_b.data.
Výbuchy	Použijte result.bodies[i].data nebo result.entries[i].body.data.
Uchopování těles	Během držení použijte grabber.get_body().data.
Přímá reference na body	Čtěte nebo měňte body.data bez volání native bridge.

body.data a user_data#

Vlastnost	body.data	user_data
Určená hodnota	Gameplay metadata struct s poli definovanými projektem.	Libovolná hodnota volajícího, často entity nebo GameMaker instance.
Vytvoření	options.data nebo nový nezávislý {}.	undefined do zavolání set_user_data() nebo bind_instance(..., true).
Alias v dotazech	Dostupné přes vrácený body wrapper.	Některá result/event API jej navíc vystavují jako entity nebo other_entity.
Native fyzika	Nikdy se neposílá do Jolt Physics ani bridge.	GML hodnota je také na wrapperu; native Body UserData zůstává interně rezervované pro managed handly.

Životní cyklus a vlastnictví#

Zničení body zneplatní fyzikální handle, ale nesmaže data ze starého wrapperu, na který GML stále drží referenci.
Nové body využívající recyklovaný native slot dostane nový wrapper a nová prázdná data; metadata ze zničeného body se nikdy nepřenesou.
body.data nemění mass, collision, sensor state, velocity, sleeping ani životní cyklus resources.
Save/load, JSON převod, síťová replikace a persistence jsou odpovědností projektu a tato funkce je neposkytuje.

Příklad#

var bottle = jolt_box_create_dynamic(0, 0, 3, 0.5, 0.5, 1, {
    mass: 1,
    data: {
        name: "Bottle",
        price: 20,
        health: 10,
        type: "item",
        inventory: ["Gold", "Potion"]
    }
});

show_debug_message(bottle.data.name);
bottle.data.health -= 5;
array_push(bottle.data.inventory, "Sword");

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
JoltBody.get_user_data	JoltBody.get_user_data()	Libovolná GML hodnota, setter true/getter hodnota; native ji nevidí. Samostatné data je také čistě GML struct, nikoliv fyzikální nastavení.
JoltBody.set_user_data	JoltBody.set_user_data(value)	Libovolná GML hodnota, setter true/getter hodnota; native ji nevidí. Samostatné data je také čistě GML struct, nikoliv fyzikální nastavení.