:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/3.5/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/3.5/doc/classes/ShapeCast.xml. .. _class_ShapeCast: ShapeCast ========= **Inherits:** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` Node for physics collision sweep and immediate overlap queries. Similar to the :ref:`RayCast` node. Description ----------- Shape casting allows to detect collision objects by sweeping the :ref:`shape` along the cast direction determined by :ref:`target_position` (useful for things like beam weapons). Immediate collision overlaps can be done with the :ref:`target_position` set to ``Vector3(0, 0, 0)`` and by calling :ref:`force_shapecast_update` within the same **physics_frame**. This also helps to overcome some limitations of :ref:`Area` when used as a continuous detection area, often requiring waiting a couple of frames before collision information is available to :ref:`Area` nodes, and when using the signals creates unnecessary complexity. The node can detect multiple collision objects, but it's usually used to detect the first collision. \ **Note:** Shape casting is more computationally expensive compared to ray casting. Properties ---------- +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ | :ref:`bool` | :ref:`collide_with_areas` | ``false`` | +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ | :ref:`bool` | :ref:`collide_with_bodies` | ``true`` | +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ | :ref:`int` | :ref:`collision_mask` | ``1`` | +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ | :ref:`Array` | :ref:`collision_result` | | +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ | :ref:`Color` | :ref:`debug_shape_custom_color` | ``Color( 0, 0, 0, 1 )`` | +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ | :ref:`bool` | :ref:`enabled` | ``true`` | +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ | :ref:`bool` | :ref:`exclude_parent` | ``true`` | +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ | :ref:`float` | :ref:`margin` | ``0.0`` | +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ | :ref:`int` | :ref:`max_results` | ``32`` | +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ | :ref:`Shape` | :ref:`shape` | | +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ | :ref:`Vector3` | :ref:`target_position` | ``Vector3( 0, -1, 0 )`` | +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ Methods ------- +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_exception` **(** :ref:`Object` node **)** | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_exception_rid` **(** :ref:`RID` rid **)** | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`clear_exceptions` **(** **)** | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`force_shapecast_update` **(** **)** | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_closest_collision_safe_fraction` **(** **)** |const| | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_closest_collision_unsafe_fraction` **(** **)** |const| | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Object` | :ref:`get_collider` **(** :ref:`int` index **)** |const| | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_collider_shape` **(** :ref:`int` index **)** |const| | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_collision_count` **(** **)** |const| | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`get_collision_mask_value` **(** :ref:`int` layer_number **)** |const| | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`get_collision_normal` **(** :ref:`int` index **)** |const| | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`get_collision_point` **(** :ref:`int` index **)** |const| | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_colliding` **(** **)** |const| | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`remove_exception` **(** :ref:`Object` node **)** | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`remove_exception_rid` **(** :ref:`RID` rid **)** | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`resource_changed` **(** :ref:`Resource` resource **)** | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_collision_mask_value` **(** :ref:`int` layer_number, :ref:`bool` value **)** | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ Property Descriptions --------------------- .. _class_ShapeCast_property_collide_with_areas: - :ref:`bool` **collide_with_areas** +-----------+---------------------------------+ | *Default* | ``false`` | +-----------+---------------------------------+ | *Setter* | set_collide_with_areas(value) | +-----------+---------------------------------+ | *Getter* | is_collide_with_areas_enabled() | +-----------+---------------------------------+ If ``true``, collision with :ref:`Area`\ s will be reported. ---- .. _class_ShapeCast_property_collide_with_bodies: - :ref:`bool` **collide_with_bodies** +-----------+----------------------------------+ | *Default* | ``true`` | +-----------+----------------------------------+ | *Setter* | set_collide_with_bodies(value) | +-----------+----------------------------------+ | *Getter* | is_collide_with_bodies_enabled() | +-----------+----------------------------------+ If ``true``, collision with :ref:`PhysicsBody`\ s will be reported. ---- .. _class_ShapeCast_property_collision_mask: - :ref:`int` **collision_mask** +-----------+---------------------------+ | *Default* | ``1`` | +-----------+---------------------------+ | *Setter* | set_collision_mask(value) | +-----------+---------------------------+ | *Getter* | get_collision_mask() | +-----------+---------------------------+ The shape's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. See `Collision layers and masks <../tutorials/physics/physics_introduction.html#collision-layers-and-masks>`__ in the documentation for more information. ---- .. _class_ShapeCast_property_collision_result: - :ref:`Array` **collision_result** Returns the complete collision information from the collision sweep. The data returned is the same as in the :ref:`PhysicsDirectSpaceState.get_rest_info` method. ---- .. _class_ShapeCast_property_debug_shape_custom_color: - :ref:`Color` **debug_shape_custom_color** +-----------+-------------------------------------+ | *Default* | ``Color( 0, 0, 0, 1 )`` | +-----------+-------------------------------------+ | *Setter* | set_debug_shape_custom_color(value) | +-----------+-------------------------------------+ | *Getter* | get_debug_shape_custom_color() | +-----------+-------------------------------------+ The custom color to use to draw the shape in the editor and at run-time if **Visible Collision Shapes** is enabled in the **Debug** menu. This color will be highlighted at run-time if the ``ShapeCast`` is colliding with something. If set to ``Color(0.0, 0.0, 0.0)`` (by default), the color set in :ref:`ProjectSettings.debug/shapes/collision/shape_color` is used. ---- .. _class_ShapeCast_property_enabled: - :ref:`bool` **enabled** +-----------+--------------------+ | *Default* | ``true`` | +-----------+--------------------+ | *Setter* | set_enabled(value) | +-----------+--------------------+ | *Getter* | is_enabled() | +-----------+--------------------+ If ``true``, collisions will be reported. ---- .. _class_ShapeCast_property_exclude_parent: - :ref:`bool` **exclude_parent** +-----------+--------------------------------+ | *Default* | ``true`` | +-----------+--------------------------------+ | *Setter* | set_exclude_parent_body(value) | +-----------+--------------------------------+ | *Getter* | get_exclude_parent_body() | +-----------+--------------------------------+ If ``true``, the parent node will be excluded from collision detection. ---- .. _class_ShapeCast_property_margin: - :ref:`float` **margin** +-----------+-------------------+ | *Default* | ``0.0`` | +-----------+-------------------+ | *Setter* | set_margin(value) | +-----------+-------------------+ | *Getter* | get_margin() | +-----------+-------------------+ The collision margin for the shape. A larger margin helps detecting collisions more consistently, at the cost of precision. ---- .. _class_ShapeCast_property_max_results: - :ref:`int` **max_results** +-----------+------------------------+ | *Default* | ``32`` | +-----------+------------------------+ | *Setter* | set_max_results(value) | +-----------+------------------------+ | *Getter* | get_max_results() | +-----------+------------------------+ The number of intersections can be limited with this parameter, to reduce the processing time. ---- .. _class_ShapeCast_property_shape: - :ref:`Shape` **shape** +----------+------------------+ | *Setter* | set_shape(value) | +----------+------------------+ | *Getter* | get_shape() | +----------+------------------+ The :ref:`Shape` to be used for collision queries. ---- .. _class_ShapeCast_property_target_position: - :ref:`Vector3` **target_position** +-----------+----------------------------+ | *Default* | ``Vector3( 0, -1, 0 )`` | +-----------+----------------------------+ | *Setter* | set_target_position(value) | +-----------+----------------------------+ | *Getter* | get_target_position() | +-----------+----------------------------+ The shape's destination point, relative to this node's ``position``. Method Descriptions ------------------- .. _class_ShapeCast_method_add_exception: - void **add_exception** **(** :ref:`Object` node **)** Adds a collision exception so the shape does not report collisions with the specified :ref:`CollisionObject` node. ---- .. _class_ShapeCast_method_add_exception_rid: - void **add_exception_rid** **(** :ref:`RID` rid **)** Adds a collision exception so the shape does not report collisions with the specified :ref:`RID`. ---- .. _class_ShapeCast_method_clear_exceptions: - void **clear_exceptions** **(** **)** Removes all collision exceptions for this ``ShapeCast``. ---- .. _class_ShapeCast_method_force_shapecast_update: - void **force_shapecast_update** **(** **)** Updates the collision information for the shape. Use this method to update the collision information immediately instead of waiting for the next ``_physics_process`` call, for example if the shape or its parent has changed state. \ **Note:** ``enabled`` is not required for this to work. ---- .. _class_ShapeCast_method_get_closest_collision_safe_fraction: - :ref:`float` **get_closest_collision_safe_fraction** **(** **)** |const| The fraction from the ``ShapeCast``'s origin to its :ref:`target_position` (between 0 and 1) of how far the shape can move without triggering a collision. ---- .. _class_ShapeCast_method_get_closest_collision_unsafe_fraction: - :ref:`float` **get_closest_collision_unsafe_fraction** **(** **)** |const| The fraction from the ``ShapeCast``'s origin to its :ref:`target_position` (between 0 and 1) of how far the shape must move to trigger a collision. ---- .. _class_ShapeCast_method_get_collider: - :ref:`Object` **get_collider** **(** :ref:`int` index **)** |const| Returns the collided :ref:`Object` of one of the multiple collisions at ``index``, or ``null`` if no object is intersecting the shape (i.e. :ref:`is_colliding` returns ``false``). ---- .. _class_ShapeCast_method_get_collider_shape: - :ref:`int` **get_collider_shape** **(** :ref:`int` index **)** |const| Returns the shape ID of the colliding shape of one of the multiple collisions at ``index``, or ``0`` if no object is intersecting the shape (i.e. :ref:`is_colliding` returns ``false``). ---- .. _class_ShapeCast_method_get_collision_count: - :ref:`int` **get_collision_count** **(** **)** |const| The number of collisions detected at the point of impact. Use this to iterate over multiple collisions as provided by :ref:`get_collider`, :ref:`get_collider_shape`, :ref:`get_collision_point`, and :ref:`get_collision_normal` methods. ---- .. _class_ShapeCast_method_get_collision_mask_value: - :ref:`bool` **get_collision_mask_value** **(** :ref:`int` layer_number **)** |const| Returns whether or not the specified layer of the :ref:`collision_mask` is enabled, given a ``layer_number`` between 1 and 32. ---- .. _class_ShapeCast_method_get_collision_normal: - :ref:`Vector3` **get_collision_normal** **(** :ref:`int` index **)** |const| Returns the normal of one of the multiple collisions at ``index`` of the intersecting object. ---- .. _class_ShapeCast_method_get_collision_point: - :ref:`Vector3` **get_collision_point** **(** :ref:`int` index **)** |const| Returns the collision point of one of the multiple collisions at ``index`` where the shape intersects the colliding object. \ **Note:** this point is in the **global** coordinate system. ---- .. _class_ShapeCast_method_is_colliding: - :ref:`bool` **is_colliding** **(** **)** |const| Returns whether any object is intersecting with the shape's vector (considering the vector length). ---- .. _class_ShapeCast_method_remove_exception: - void **remove_exception** **(** :ref:`Object` node **)** Removes a collision exception so the shape does report collisions with the specified :ref:`CollisionObject` node. ---- .. _class_ShapeCast_method_remove_exception_rid: - void **remove_exception_rid** **(** :ref:`RID` rid **)** Removes a collision exception so the shape does report collisions with the specified :ref:`RID`. ---- .. _class_ShapeCast_method_resource_changed: - void **resource_changed** **(** :ref:`Resource` resource **)** This method is used internally to update the debug gizmo in the editor. Any code placed in this function will be called whenever the :ref:`shape` resource is modified. ---- .. _class_ShapeCast_method_set_collision_mask_value: - void **set_collision_mask_value** **(** :ref:`int` layer_number, :ref:`bool` value **)** Based on ``value``, enables or disables the specified layer in the :ref:`collision_mask`, given a ``layer_number`` between 1 and 32. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`