:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/3.6/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/3.6/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. .. rst-class:: classref-introduction-group 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. .. rst-class:: classref-reftable-group Properties ---------- .. table:: :widths: auto +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ | :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 )`` | +-------------------------------+------------------------------------------------------------------------------------+-------------------------+ .. rst-class:: classref-reftable-group Methods ------- .. table:: :widths: auto +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 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:`RID` | :ref:`get_collider_rid` **(** :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 **)** | +-------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_ShapeCast_property_collide_with_areas: .. rst-class:: classref-property :ref:`bool` **collide_with_areas** = ``false`` .. rst-class:: classref-property-setget - void **set_collide_with_areas** **(** :ref:`bool` value **)** - :ref:`bool` **is_collide_with_areas_enabled** **(** **)** If ``true``, collision with :ref:`Area`\ s will be reported. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_property_collide_with_bodies: .. rst-class:: classref-property :ref:`bool` **collide_with_bodies** = ``true`` .. rst-class:: classref-property-setget - void **set_collide_with_bodies** **(** :ref:`bool` value **)** - :ref:`bool` **is_collide_with_bodies_enabled** **(** **)** If ``true``, collision with :ref:`PhysicsBody`\ s will be reported. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_property_collision_mask: .. rst-class:: classref-property :ref:`int` **collision_mask** = ``1`` .. rst-class:: classref-property-setget - void **set_collision_mask** **(** :ref:`int` value **)** - :ref:`int` **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. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_property_collision_result: .. rst-class:: classref-property :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. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_property_debug_shape_custom_color: .. rst-class:: classref-property :ref:`Color` **debug_shape_custom_color** = ``Color( 0, 0, 0, 1 )`` .. rst-class:: classref-property-setget - void **set_debug_shape_custom_color** **(** :ref:`Color` value **)** - :ref:`Color` **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. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_property_enabled: .. rst-class:: classref-property :ref:`bool` **enabled** = ``true`` .. rst-class:: classref-property-setget - void **set_enabled** **(** :ref:`bool` value **)** - :ref:`bool` **is_enabled** **(** **)** If ``true``, collisions will be reported. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_property_exclude_parent: .. rst-class:: classref-property :ref:`bool` **exclude_parent** = ``true`` .. rst-class:: classref-property-setget - void **set_exclude_parent_body** **(** :ref:`bool` value **)** - :ref:`bool` **get_exclude_parent_body** **(** **)** If ``true``, the parent node will be excluded from collision detection. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_property_margin: .. rst-class:: classref-property :ref:`float` **margin** = ``0.0`` .. rst-class:: classref-property-setget - void **set_margin** **(** :ref:`float` value **)** - :ref:`float` **get_margin** **(** **)** The collision margin for the shape. A larger margin helps detecting collisions more consistently, at the cost of precision. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_property_max_results: .. rst-class:: classref-property :ref:`int` **max_results** = ``32`` .. rst-class:: classref-property-setget - void **set_max_results** **(** :ref:`int` value **)** - :ref:`int` **get_max_results** **(** **)** The number of intersections can be limited with this parameter, to reduce the processing time. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_property_shape: .. rst-class:: classref-property :ref:`Shape` **shape** .. rst-class:: classref-property-setget - void **set_shape** **(** :ref:`Shape` value **)** - :ref:`Shape` **get_shape** **(** **)** The :ref:`Shape` to be used for collision queries. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_property_target_position: .. rst-class:: classref-property :ref:`Vector3` **target_position** = ``Vector3( 0, -1, 0 )`` .. rst-class:: classref-property-setget - void **set_target_position** **(** :ref:`Vector3` value **)** - :ref:`Vector3` **get_target_position** **(** **)** The shape's destination point, relative to this node's ``position``. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_ShapeCast_method_add_exception: .. rst-class:: classref-method void **add_exception** **(** :ref:`Object` node **)** Adds a collision exception so the shape does not report collisions with the specified :ref:`CollisionObject` node. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_add_exception_rid: .. rst-class:: classref-method void **add_exception_rid** **(** :ref:`RID` rid **)** Adds a collision exception so the shape does not report collisions with the specified :ref:`RID`. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_clear_exceptions: .. rst-class:: classref-method void **clear_exceptions** **(** **)** Removes all collision exceptions for this **ShapeCast**. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_force_shapecast_update: .. rst-class:: classref-method 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. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_get_closest_collision_safe_fraction: .. rst-class:: classref-method :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. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_get_closest_collision_unsafe_fraction: .. rst-class:: classref-method :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. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_get_collider: .. rst-class:: classref-method :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``). .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_get_collider_rid: .. rst-class:: classref-method :ref:`RID` **get_collider_rid** **(** :ref:`int` index **)** |const| Returns the :ref:`RID` of the collided object of one of the multiple collisions at ``index``. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_get_collider_shape: .. rst-class:: classref-method :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``). .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_get_collision_count: .. rst-class:: classref-method :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. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_get_collision_mask_value: .. rst-class:: classref-method :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. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_get_collision_normal: .. rst-class:: classref-method :ref:`Vector3` **get_collision_normal** **(** :ref:`int` index **)** |const| Returns the normal of one of the multiple collisions at ``index`` of the intersecting object. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_get_collision_point: .. rst-class:: classref-method :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. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_is_colliding: .. rst-class:: classref-method :ref:`bool` **is_colliding** **(** **)** |const| Returns whether any object is intersecting with the shape's vector (considering the vector length). .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_remove_exception: .. rst-class:: classref-method void **remove_exception** **(** :ref:`Object` node **)** Removes a collision exception so the shape does report collisions with the specified :ref:`CollisionObject` node. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_remove_exception_rid: .. rst-class:: classref-method void **remove_exception_rid** **(** :ref:`RID` rid **)** Removes a collision exception so the shape does report collisions with the specified :ref:`RID`. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_resource_changed: .. rst-class:: classref-method 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. .. rst-class:: classref-item-separator ---- .. _class_ShapeCast_method_set_collision_mask_value: .. rst-class:: classref-method 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.)` .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`