Tělesa

Compound Shapes

Sloučí několik lokálně transformovaných child shapes do jediného JoltBody.

Children sdílejí velocity, motion type, layer, sensor, mass a body handle. Oproti několika bodies s Fixed Constraintem je Compound jeden nedělitelný rigid shape, obvykle jednodušší a levnější pro pevný složený objekt.

Builder#

var compound = jolt_compound();

Vyžaduje aktivní jolt_start() a vrací JoltCompound builder, ne JoltBody. Builder přijímá 1 až 64 child shapes.

Podporované children#

compound.add_box(local_x, local_y, local_z,
                 width, depth, height, rotation=undefined)
compound.add_sphere(local_x, local_y, local_z,
                    radius, rotation=undefined)
compound.add_capsule(local_x, local_y, local_z,
                     height, radius, rotation=undefined)
compound.add_cylinder(local_x, local_y, local_z,
                      height, radius, rotation=undefined)
compound.add_tapered_capsule(local_x, local_y, local_z,
    height, top_radius, bottom_radius, rotation=undefined)
compound.add_tapered_cylinder(local_x, local_y, local_z,
    height, top_radius, bottom_radius, rotation=undefined)
compound.add_convex(local_x, local_y, local_z, points, rotation=undefined)
compound.add_mesh(local_x, local_y, local_z, vertices, indices, rotation=undefined)
compound.add_heightfield(local_x, local_y, local_z, heights, width, height,
    cell_size, cell_size_y=undefined, rotation=undefined)
compound.add_plane(local_x, local_y, local_z, normal_x, normal_y, normal_z,
    half_extent=1000, rotation=undefined)
compound.add_shape(jolt_shape, local_x, local_y, local_z, rotation=undefined)

local_x/y/z jsou středy children vůči originu compoundu. Box používá celé rozměry, Sphere radius, Capsule celkovou tip-to-tip height > 2*radius a Cylinder celou height. Capsule a Cylinder mají osu Z.

rotation může být quaternion {x,y,z,w} nebo Euler {x,y,z} ve stupních; default identity. Všechny rozměry odpovídají standalone creators. add_shape přijímá live reusable JoltShape ze stejného worldu a Native si uloží vlastní ShapeRefC, takže source handle lze bezpečně zničit.

Vytvoření body#

compound.create_dynamic(x, y, z, options=undefined)
compound.create_static(x, y, z, options=undefined)
compound.create_kinematic(x, y, z, options=undefined)

x,y,z je world origin; child transformace se skládají s body transformem. Vrací JoltBody se shape="compound" a common options. Builder se nespotřebuje a může vytvořit další bodies. Convex children podporují Dynamic/Static/Kinematic; Mesh, HeightField a Plane pouze Static.

Vlastnosti, kolize a debug#

mass přepočítá mass a inertia celého Dynamic compoundu. Layer, sensor, friction a user_data jsou společné; child-specific hodnoty nejsou veřejně dostupné. Kontakt a raycast vrací výsledný JoltBody handle, ne child object nebo ID. Debug skládá body transform s local transformem každého child a kreslí jeho primitivum.

Low-Level / Advanced API#

jolt_world_compound_create(world)
jolt_world_compound_destroy(world, compound_handle)
jolt_world_compound_add_child(world, compound_handle, shape_type,
    size_x, size_y, size_z, local_x, local_y, local_z,
    qx, qy, qz, qw)
jolt_world_compound_add_shape(world, compound_handle, shape_handle,
    local_x, local_y, local_z, qx, qy, qz, qw)
jolt_world_compound_body_create(world, compound_handle, motion_type,
    x, y, z, qx=0, qy=0, qz=0, qw=1)

shape_type je JOLT_SHAPE_BOX, SPHERE, CAPSULE nebo CYLINDER.
Box size_x/y/z jsou native half extents.
Sphere size_x je radius.
Capsule size_x je half height rovné části a size_y radius.
Cylinder size_x je half height a size_y radius.
Low-level funkce vracejí číselné handly nebo 1/0, ne JoltCompound/JoltBody.

Příklad#

var shape = jolt_compound();
shape.add_box(0, 0, 0, 2.4, 0.8, 0.6, {x:0, y:0, z:12});
shape.add_sphere(1.35, 0, 0.45, 0.55);

var body = shape.create_dynamic(0, 0, 5, {
    mass:2.5,
    friction:0.6
});

// Builder už není potřeba; body zůstane platné.
shape.destroy();

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_compound	jolt_compound()	Vytvoří prázdný JoltCompound builder v managed světě, chyba undefined. Samotný builder ještě není těleso; přidej children a použij create_*.
JoltCompound._add	JoltCompound._add(shape, shape_type, x, y, z, size_x, size_y, size_z, dimensions, rotation)	Implementační helper, ne doporučený aplikační zápis. _add převádí primitivní rozměry a zapisuje child metadata; _add_owned_shape přidá dočasný resource a vždy ho uvolní, při chybě zachová původní diagnostiku. Výsledek Boolean.
JoltCompound._add_owned_shape	JoltCompound._add_owned_shape(shape, x, y, z, rotation, context)	Implementační helper, ne doporučený aplikační zápis. _add převádí primitivní rozměry a zapisuje child metadata; _add_owned_shape přidá dočasný resource a vždy ho uvolní, při chybě zachová původní diagnostiku. Výsledek Boolean.
JoltCompound._create	JoltCompound._create(motion, x, y, z, options)	JoltBody/undefined z neprázdného builderu, XYZ default 0, Body options/COM offset. Snapshot children; chyba options nové těleso odstraní. _create je implementační delegát, veřejně preferuj create_* dle motion.
JoltCompound.add_box	JoltCompound.add_box(x, y, z, width, depth, height, rotation = undefined)	Boolean přidání child v místních XYZ m s volitelnou rotation XYZW nebo XYZ°. Rozměry/data a validace jako odpovídající jolt_shape_* (box plné rozměry). Mesh/Heightfield/Plane učiní celý compound Static-only. Nemění již vytvořená tělesa.
JoltCompound.add_capsule	JoltCompound.add_capsule(x, y, z, height, radius, rotation = undefined)	Boolean přidání child v místních XYZ m s volitelnou rotation XYZW nebo XYZ°. Rozměry/data a validace jako odpovídající jolt_shape_* (box plné rozměry). Mesh/Heightfield/Plane učiní celý compound Static-only. Nemění již vytvořená tělesa.
JoltCompound.add_convex	JoltCompound.add_convex(x, y, z, points, rotation = undefined)	Boolean přidání child v místních XYZ m s volitelnou rotation XYZW nebo XYZ°. Rozměry/data a validace jako odpovídající jolt_shape_* (box plné rozměry). Mesh/Heightfield/Plane učiní celý compound Static-only. Nemění již vytvořená tělesa.
JoltCompound.add_cylinder	JoltCompound.add_cylinder(x, y, z, height, radius, rotation = undefined)	Boolean přidání child v místních XYZ m s volitelnou rotation XYZW nebo XYZ°. Rozměry/data a validace jako odpovídající jolt_shape_* (box plné rozměry). Mesh/Heightfield/Plane učiní celý compound Static-only. Nemění již vytvořená tělesa.
JoltCompound.add_heightfield	JoltCompound.add_heightfield(x, y, z, heights, width, height, cell_size, cell_size_y = undefined, rotation = undefined)	Boolean přidání child v místních XYZ m s volitelnou rotation XYZW nebo XYZ°. Rozměry/data a validace jako odpovídající jolt_shape_* (box plné rozměry). Mesh/Heightfield/Plane učiní celý compound Static-only. Nemění již vytvořená tělesa.
JoltCompound.add_mesh	JoltCompound.add_mesh(x, y, z, vertices, indices, rotation = undefined)	Boolean přidání child v místních XYZ m s volitelnou rotation XYZW nebo XYZ°. Rozměry/data a validace jako odpovídající jolt_shape_* (box plné rozměry). Mesh/Heightfield/Plane učiní celý compound Static-only. Nemění již vytvořená tělesa.
JoltCompound.add_plane	JoltCompound.add_plane(x, y, z, normal_x, normal_y, normal_z, half_extent = 1000, rotation = undefined)	Boolean přidání child v místních XYZ m s volitelnou rotation XYZW nebo XYZ°. Rozměry/data a validace jako odpovídající jolt_shape_* (box plné rozměry). Mesh/Heightfield/Plane učiní celý compound Static-only. Nemění již vytvořená tělesa.
JoltCompound.add_shape	JoltCompound.add_shape(shape, x, y, z, rotation = undefined)	Boolean; živý JoltShape stejného světa, místní XYZ m a volitelný quaternion/Euler° struct. Native drží vlastní referenci, zdrojový shape lze poté destroy.
JoltCompound.add_sphere	JoltCompound.add_sphere(x, y, z, radius, rotation = undefined)	Boolean přidání child v místních XYZ m s volitelnou rotation XYZW nebo XYZ°. Rozměry/data a validace jako odpovídající jolt_shape_* (box plné rozměry). Mesh/Heightfield/Plane učiní celý compound Static-only. Nemění již vytvořená tělesa.
JoltCompound.add_tapered_capsule	JoltCompound.add_tapered_capsule(x, y, z, height, top_radius, bottom_radius, rotation = undefined)	Boolean přidání child v místních XYZ m s volitelnou rotation XYZW nebo XYZ°. Rozměry/data a validace jako odpovídající jolt_shape_* (box plné rozměry). Mesh/Heightfield/Plane učiní celý compound Static-only. Nemění již vytvořená tělesa.
JoltCompound.add_tapered_cylinder	JoltCompound.add_tapered_cylinder(x, y, z, height, top_radius, bottom_radius, rotation = undefined)	Boolean přidání child v místních XYZ m s volitelnou rotation XYZW nebo XYZ°. Rozměry/data a validace jako odpovídající jolt_shape_* (box plné rozměry). Mesh/Heightfield/Plane učiní celý compound Static-only. Nemění již vytvořená tělesa.
JoltCompound.create_dynamic	JoltCompound.create_dynamic(x = 0, y = 0, z = 0, options = undefined)	JoltBody/undefined z neprázdného builderu, XYZ default 0, Body options/COM offset. Snapshot children; chyba options nové těleso odstraní. _create je implementační delegát, veřejně preferuj create_* dle motion.
JoltCompound.create_kinematic	JoltCompound.create_kinematic(x = 0, y = 0, z = 0, options = undefined)	JoltBody/undefined z neprázdného builderu, XYZ default 0, Body options/COM offset. Snapshot children; chyba options nové těleso odstraní. _create je implementační delegát, veřejně preferuj create_* dle motion.
JoltCompound.create_static	JoltCompound.create_static(x = 0, y = 0, z = 0, options = undefined)	JoltBody/undefined z neprázdného builderu, XYZ default 0, Body options/COM offset. Snapshot children; chyba options nové těleso odstraní. _create je implementační delegát, veřejně preferuj create_* dle motion.
JoltCompound.destroy	JoltCompound.destroy()	Boolean wrapperu/světa, handle nebo0; destroy Boolean idempotentně zničí builder, nikoliv již vytvořená tělesa.
JoltCompound.get_native_handle	JoltCompound.get_native_handle()	Boolean wrapperu/světa, handle nebo0; destroy Boolean idempotentně zničí builder, nikoliv již vytvořená tělesa.
JoltCompound.is_valid	JoltCompound.is_valid()	Boolean wrapperu/světa, handle nebo0; destroy Boolean idempotentně zničí builder, nikoliv již vytvořená tělesa.