Fyzikální váha

Vytvoří skutečnou fyzikální load-cell platformu a měří zatížení přenášené její pevnou podpěrou.

jolt_scale_create vytvoří vlastněnou Dynamic box platformu a interním Fixed Constraintem ji připne ke světu. Po každém dokončeném physics stepu přečte vyřešený lineární reakční impulz constraintu, promítne jej na vybranou osu zatížení a vydělí časem fixed stepu. Nejde o overlap query ani o prosté sčítání hmotností dotýkajících se těles.

Fyzikální princip#

objekty a aplikované síly
        ↓
Dynamic box platforma
        ↓
reakce Fixed Constraintu
        ↓
síla ve směru měření

• Platforma je Dynamic, takže běžné Jolt kontakty a tření do ní mohou přenášet síly.
• Interní Fixed Constraint ji drží v creation pose a přenáší zatížení do pevného světa.
• Akumulovaný lineární impulz solveru se dělí délkou physics stepu; při konzistentních metre-kilogram-sekunda jednotkách tak vzniká síla v newtonech.
• Vrací se pouze nezáporná složka ve směru direction. Reakce proti zvolené kladné ose se ořízne na nulu.
• Teoretické gravitační zatížení samotné platformy se automaticky odečte, proto nová prázdná váha začíná blízko nuly.

Syntaxe#

scale = jolt_scale_create(-6.5, -3.1, 0.3, 3.0, 1.8, 0.05);
scale.set_smoothing(0.2);
scale.set_enabled(true);
scale.set_direction(0, 0, 1);

Argumenty#

Nastavení váhy#

Užitečné body options#

Příklad vytvoření#

scale = jolt_scale_create(-6.5, -3.1, 0.3, 3.0, 1.8, 0.05);
scale.set_smoothing(0.2);
scale.set_enabled(true);
scale.set_direction(0, 0, 1);

Čtení váhy#

// Nejprve jolt_update(), aby existoval dokončený physics step.
jolt_update(delta_time / 1000000);

if (scale.is_valid()) {
    var kilograms = scale.get_weight();
    var force_newtons = scale.get_force();

    if (!jolt_has_error()) {
        draw_text(32, 32, string_format(kilograms, 0, 2) + " kg");
        draw_text(32, 52, string_format(force_newtons, 0, 1) + " N");
    }
}

• Hodnoty se aktualizují pouze po úspěšně dokončeném physics stepu. Opakované gettery ve stejném stepu vrátí stejný sample.
• get_force() a get_weight() vrací vyhlazené hodnoty vhodné pro UI.
• get_raw_force() a get_raw_weight() vrací poslední nevyhlazený physics-step sample pro diagnostiku nebo logiku nárazů.
• Getter při chybě vrátí bezpečnou číselnou nulu a nastaví běžnou high-level chybu; nulu proto nepovažujte za důkaz, že neplatná váha není zatížená.

Veřejné metody#

Tárování a nádoby#

// Položte prázdnou nádobu a počkejte na ustálení.
if (keyboard_check_pressed(ord("T"))) {
    if (!scale.tare()) {
        show_debug_message(jolt_get_error().message);
    }
}

• Nová váha automaticky odečítá pouze teoretické gravitační zatížení vlastní platformy.
• tare() nahradí baseline úplnou reakcí naměřenou v okamžiku volání, což je vhodné pro nádoby a přípravky.
• Tárujte až po ustálení. Tare během nárazu nebo zrychlení uloží přechodnou sílu jako novou nulu.
• Změna direction přepočítá teoretický baseline platformy a vymaže raw i smoothed reading; pokud se má nádoba dále odečítat, znovu tárujte.

Vyhlazování#

• Smoothing je exponenciální low-pass filter podle uplynulého physics času, takže render framerate nemění jeho odezvu.
• Vyšší časová konstanta vytvoří stabilnější, ale pomalejší displej. Pro UI je praktickým začátkem přibližně 0.1 až 0.3 sekundy.
• Nula okamžitě sjednotí smoothed reading s posledním raw samplem.
• Raw force použijte pro krátké impact peaks; smoothed weight pro čitelné popisky a displeje.

Směr zatížení#

• Výchozí {0,0,1} měří podpěrnou reakci vzhůru na běžné vodorovné platformě.
• Vektor se ukládá v pevné lokální reference frame platformy a native implementace jej normalizuje.
• Vrací se pouze kladná promítnutá reakce. Zvolte znaménko tak, aby očekávaná podpěrná síla mířila podél osy.
• U vodorovné nebo šikmé osy get_weight() stále dělí hodnotou reference_gravity, takže kg zůstává ekvivalentem síly, nikoliv mass objektu.

Vlastnictví a životní cyklus#

• Váha vlastní Dynamic platformu a interní Fixed Constraint.
• scale.destroy() zneplatní scale.body a odstraní oba native resources.
• Ruční zničení scale.body atomicky zneplatní váhu a odstraní interní constraint.
• Platforma má vypnuté sleeping, aby solver vytvářel čerstvou reakci i po dlouhém stání nákladu.
• jolt_stop() uklidí živé váhy při managed teardownu worldu.
• scale.body lze použít pro data, layer, friction, debug draw a visual transform, ale neničte jej samostatně, pokud nechcete odstranit celou váhu.

Fyzikální interpretace a omezení#

• Stack přispívá silami skutečně přenesenými do platformy; horní bodies se jí nemusí přímo dotýkat.
• Objekt podepřený dvěma platformami rozdělí reakci mezi obě váhy.
• Ropes, springs, constrainty a aplikované síly přispívají podle zatížení přeneseného platformou.
• Nárazy vytvářejí dočasné špičky, které mohou překročit statickou hmotnost.
• Solver settling, contact softness, friction a fixed timestep způsobují drobné výkyvy; jde o očekávané fyzikální chování.
• Váha měří jednu orientovanou osu a zápornou reakci ořezává. Není to šestiosý force/torque sensor.

Validace a chyby#

• Před jolt_scale() zavolejte jolt_start().
• Position a dimensions musí být konečné a každý rozměr větší než nula.
• mass a reference_gravity musí být konečné a kladné.
• smoothing musí být konečný a nezáporný; enabled musí být Boolean.
• direction musí být struct s konečnými x, y a z tvořícími nenulový vektor.
• Creation při chybě vrací undefined. Mutating methods vrací false; číselné gettery vrací 0 a get_direction() vrací undefined.
• Po neúspěšném managed volání ihned přečtěte jolt_get_error(), než jej nahradí další Jolt operace.

Low-Level / Advanced API#

jolt_world_scale_create(world, x, y, z, width, depth, height, mass, reference_gravity)
jolt_world_scale_destroy(world, scale_handle)
jolt_world_scale_is_valid(world, scale_handle)
jolt_world_scale_get(world, scale_handle, property)
jolt_world_scale_tare(world, scale_handle)
jolt_world_scale_set_smoothing(world, scale_handle, seconds)
jolt_world_scale_set_enabled(world, scale_handle, enabled)
jolt_world_scale_set_direction(world, scale_handle, x, y, z)

Legacy / Deprecated API#

jolt_scale(x,y,z,width,depth,height,options) zůstává kompatibilní factory nad stejnou implementací. Creation-only reference_gravity je dostupná touto cestou. Defaulty nové factory: mass=20 kg, reference_gravity=9.81 m/s², smoothing=0.15 s, enabled=true, direction={x:0,y:0,z:1}. Běžné body parametry používají stejnou cestu jako dříve.

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.

Úplný seznam deklarací API#

Deklarace odpovídají produkčním GML zdrojům. Hodnota za = označuje volitelný argument. Toto je seznam signatur; význam, jednotky a omezení popisují příslušné části návodu. Název typu před tečkou označuje vlastníka metody, nikoli globální funkci.