.. _stdlib_collider_component: ======== Collider ======== Collider defines parameters for interaction with other physics objects. The most important parameter is :ref:`shapes `, a collection of geometric volumes used in collision detection. The component also defines other collision parameters, such as friction, restitution, and collision layer. A node with only a Collider and no :ref:`RigidBody ` will be static. ++++++++++++ Type aliases ++++++++++++ .. _alias-Shape: .. das:attribute:: variant Shape Represents a shape for a Collider. See :ref:`.shape operator ` how to use it. :Variants: * **box** : tuple` > - Represents a box shape * **sphere** : tuple - Represents a sphere shape * **capsule** : tuple` ;translation:float3;rotation: :ref:`quat4 ` > - Represents a capsule shape * **cylinder** : tuple` ;translation:float3;rotation: :ref:`quat4 ` > - Represents a cylinder shape * **mesh** : tuple` ;scale:float3;translation:float3;rotation: :ref:`quat4 ` > - Represents an arbitrary triangle mesh * **empty** : int - Represents no collider +++++++ Classes +++++++ .. _struct-collider_component-Collider: .. das:attribute:: Collider : NativeComponent A generic collider that can consist of several shapes. Example:: let node = create_node() add_component(node, new RigidBody()) add_component(node, new Collider(shapes = [ box_shape(), sphere_shape(), ])) :Properties: .. _function-collider_component__dot__rq_friction_Collider: .. das:operator:: Collider.friction() : float .. _function-collider_component__dot__rq_friction_rq_clone_Collider_float: .. das:operator:: Collider.friction =(value: float) The of friction of a body, which is used in collisions to calculate the combined coefficient of friction (COF) between two objects. The COF is calculated as ``sqrt(friction1 * friction2)``. A value of -1 means that it is set to what was set with ``set_default_friction()``. See the :ref:`guide ` on how to setup friction. Default value is -1. :Arguments: * **value** : float .. _function-collider_component__dot__rq_restitution_Collider: .. das:operator:: Collider.restitution() : float .. _function-collider_component__dot__rq_restitution_rq_clone_Collider_float: .. das:operator:: Collider.restitution =(value: float) The restitution of a body, which is used in collisions to calculate the combined coefficient of restitution (COR) between two objects. The COR is calculated as ``max(restitution1, restitution1)``. This COR represents the "bounciness" of a collision and should be between 0 (perfectly inelastic collision) and 1 (perfectly elastic collision). The formula is ``Coefficient of Restitution = |Relative velocity of separation after collision| / |Relative velocity of approach before collision|``. The default value is 0.0, but you can change it with ``set_default_restitution()``. :Arguments: * **value** : float .. _function-collider_component__dot__rq_isSensor_Collider: .. das:operator:: Collider.isSensor() : bool .. _function-collider_component__dot__rq_isSensor_rq_clone_Collider_bool: .. das:operator:: Collider.isSensor =(value: bool) Determines whether a body should be passable by other bodies. This is useful in combination with collision callback to make a trigger volume. Default is false. :Arguments: * **value** : bool .. _function-collider_component__dot__rq_collisionLayer_Collider: .. das:operator:: Collider.collisionLayer() : uint8 .. _function-collider_component__dot__rq_collisionLayer_rq_clone_Collider_uint8: .. das:operator:: Collider.collisionLayer =(value: uint8) Represents the collision layer that the body belongs to, with values ranging from 0 to 31. Collision layers can be set to collide or not collide with other layers using ``set_collision_layer_mask`` and ``set_collision_between_layers``. It is recommended to define a custom global enum for collision layer names for better readability. Default is 0. :Arguments: * **value** : uint8 .. _function-collider_component__dot__rq_shapes_rq_clone_Collider_array_ls_Shape_gr_: .. das:operator:: Collider.shapes =(shapes: array) Apply shapes for a Collider, replacing all shapes that was before. Usage example:: add_component(node, new Collider()) get_component(node) $(var coll: Collider?) { coll.shapes = [ box_shape(), box_shape(), sphere_shape(), ... ] } :Arguments: * **shapes** : array< :ref:`Shape ` > .. _function-collider_component__dot__rq_shapes_Collider: .. das:operator:: Collider.shapes() : array Get all shapes of a Collider. .. _function-collider_component__dot__rq_shape_rq_clone_Collider_Shape: .. das:operator:: Collider.shape =(shape: Shape) Change the shape of the collider. This function internally recreates the collider, and may produce performance issues if using it too often. It is acceptable to use this function for on-off events, e.g. instantaneous changing the height of a character when it is crouching. It is undesirable to use this function every frame, e.g. smoothly changing the height of a character when it is crouching. .. note:: Prefer to not using this function for moving the collider. E.g. if you have a sliding door and you want to move the collider, consider moving the position of the scene node instead. :Arguments: * **shape** : :ref:`Shape ` - The new shape Usage example:: add_component(node, new Collider(shape = capsule_shape([height = 2.0]))) get_component(node) $(var coll: Collider?) { coll.shape = capsule_shape([height = 1.5]) } .. _function-collider_component__dot__rq_shapeCount_Collider: .. das:operator:: Collider.shapeCount() : int Get shape count of a Collider. .. _function-collider_component__dot__rq_shape_Collider: .. das:operator:: Collider.shape() : Shape Get a shape of a Collider. If the collider has many shapes, get the first shape. Usage example:: add_component(node, new Collider(shape = capsule_shape([height = 2.0]))) get_component(node) $(var coll: Collider?) { // Get the height of the capsule let height = (coll.shape as capsule).height // Modify the height of the capsule coll.shape = capsule_shape([height = height - 0.5]) } +++++++++ Functions +++++++++ * :ref:`set_shape (collider: Collider?; index: int; shape: Shape) : bool ` * :ref:`get_shapes (collider: Collider?; var result: array\) : int ` * :ref:`get_shape (collider: Collider?; index: int = 0) : Shape ` * :ref:`box_shape (size: float3 = float3(1f,1f,1f); translation: float3 = float3(0f,0f,0f); rotation: quat4 = quat4()) : Shape ` * :ref:`sphere_shape (radius: float = 0.5f; translation: float3 = float3(0f,0f,0f)) : Shape ` * :ref:`cylinder_shape (radius: float = 0.5f; height: float = 2f; axis: AxisDirection = public_components::AxisDirection.YAxis; translation: float3 = float3(0f,0f,0f); rotation: quat4 = quat4()) : Shape ` * :ref:`capsule_shape (radius: float = 0.5f; height: float = 2f; axis: AxisDirection = public_components::AxisDirection.YAxis; translation: float3 = float3(0f,0f,0f); rotation: quat4 = quat4()) : Shape ` * :ref:`mesh_shape (mesh: CollisionId; scale: float3 = float3(1f,1f,1f); translation: float3 = float3(0f,0f,0f); rotation: quat4 = quat4()) : Shape ` .. _function-collider_component_set_shape_Collider_q__int_Shape: .. das:function:: set_shape(collider: Collider?; index: int; shape: Shape) : bool Change a shape of a Collider. If the collider has many shapes, provide an index of the shape that will be changed. This function recreates all the shapes of the collider, and may produce performance issues if using it too often. It is acceptable to use this function for on-off events, e.g. instantaneous changing the height of a character when it is crouching. It is undesirable to use this function every frame, e.g. smoothly changing the height of a character when it is crouching. If there is only a single shape in the Collider, consider using :ref:`.shape= operator ` instead. .. note:: Prefer to not using this function for moving the collider. E.g. if you have a sliding door and you want to move the collider, consider moving the position of the scene node instead. :Arguments: * **collider** : :ref:`Collider ` ? - The Collider component * **index** : int - The index of the shape. Values < 0 are treated as an offset from the end of the list. * **shape** : :ref:`Shape ` - The new shape Usage example:: add_component(node, new Collider(shape = capsule_shape([height = 2.0]))) get_component(node) $(var coll: Collider?) { set_shape(coll, 0, capsule_shape([height = 1.5])) } .. _function-collider_component_get_shapes_Collider_q__array_ls_Shape_gr_: .. das:function:: get_shapes(collider: Collider?; result: array) : int Get all shapes of a Collider. This is a more optimized version of :ref:`.shapes ` which does not allocate an array :Arguments: * **collider** : :ref:`Collider ` ? * **result** : array< :ref:`Shape ` > .. _function-collider_component_get_shape_Collider_q__int: .. das:function:: get_shape(collider: Collider?; index: int = 0) : Shape Get one of the shapes of a Collider. Note that to change a shape you need to call :ref:`set_shape () : bool ` If there is only a single shape in the Collider, consider using :ref:`.shape operator ` instead. :Arguments: * **collider** : :ref:`Collider ` ? - The Collider component * **index** : int - The index of the shape. Values < 0 are treated as an offset from the end of the list. Usage example:: add_component(node, new Collider(shapes = [ box_shape(), sphere_shape(), ) get_component(node) $(var coll: Collider?) { let sphere = get_shape(coll, 1) as sphere let radius = sphere.radius } .. _function-collider_base_box_shape_float3_float3_quat4: .. das:function:: box_shape(size: float3 = float3(1f,1f,1f); translation: float3 = float3(0f,0f,0f); rotation: quat4 = quat4()) : Shape Create box ``Shape`` for Collider Usage example:: add_component(node, new Collider(shape = box_shape())) :Arguments: * **size** : float3 * **translation** : float3 * **rotation** : :ref:`quat4 ` .. _function-collider_base_sphere_shape_float_float3: .. das:function:: sphere_shape(radius: float = 0.5f; translation: float3 = float3(0f,0f,0f)) : Shape Create sphere ``Shape`` for Collider Usage example:: add_component(node, new Collider(shape = sphere_shape())) :Arguments: * **radius** : float * **translation** : float3 .. _function-collider_base_cylinder_shape_float_float_AxisDirection_float3_quat4: .. das:function:: cylinder_shape(radius: float = 0.5f; height: float = 2f; axis: AxisDirection = public_components::AxisDirection.YAxis; translation: float3 = float3(0f,0f,0f); rotation: quat4 = quat4()) : Shape Create cylinder ``Shape`` for Collider Usage example:: add_component(node, new Collider(shape = cylinder_shape(0.5, 2.0, AxisDirection.YAxis, float3()))) :Arguments: * **radius** : float * **height** : float * **axis** : :ref:`AxisDirection ` * **translation** : float3 * **rotation** : :ref:`quat4 ` .. _function-collider_base_capsule_shape_float_float_AxisDirection_float3_quat4: .. das:function:: capsule_shape(radius: float = 0.5f; height: float = 2f; axis: AxisDirection = public_components::AxisDirection.YAxis; translation: float3 = float3(0f,0f,0f); rotation: quat4 = quat4()) : Shape Create capsule ``Shape`` for Collider Usage example:: add_component(node, new Collider(shape = capsule_shape(0.5, 2.0, AxisDirection.YAxis, float3()))) :Arguments: * **radius** : float * **height** : float * **axis** : :ref:`AxisDirection ` * **translation** : float3 * **rotation** : :ref:`quat4 ` .. _function-collider_base_mesh_shape_CollisionId_float3_float3_quat4: .. das:function:: mesh_shape(mesh: CollisionId; scale: float3 = float3(1f,1f,1f); translation: float3 = float3(0f,0f,0f); rotation: quat4 = quat4()) : Shape Create mesh ``Shape`` for Collider Usage example:: let collisionId = request_collision_from_model("cube.fbx", "Cube0") add_component(node, new Collider(shape = mesh_shape(collisionId))) :Arguments: * **mesh** : :ref:`CollisionId ` * **scale** : float3 * **translation** : float3 * **rotation** : :ref:`quat4 `