: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/ShapeCast2D.xml. .. _class_ShapeCast2D: ShapeCast2D =========== **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` Node for physics collision sweep and immediate overlap queries. Similar to the :ref:`RayCast2D` 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 ``Vector2(0, 0)`` and by calling :ref:`force_shapecast_update` within the same **physics_frame**. This also helps to overcome some limitations of :ref:`Area2D` when used as a continuous detection area, often requiring waiting a couple of frames before collision information is available to :ref:`Area2D` 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:`bool` | :ref:`enabled` | ``true`` | +-------------------------------+----------------------------------------------------------------------------+----------------------+ | :ref:`bool` | :ref:`exclude_parent` | ``true`` | +-------------------------------+----------------------------------------------------------------------------+----------------------+ | :ref:`float` | :ref:`margin` | ``0.0`` | +-------------------------------+----------------------------------------------------------------------------+----------------------+ | :ref:`int` | :ref:`max_results` | ``32`` | +-------------------------------+----------------------------------------------------------------------------+----------------------+ | :ref:`Shape2D` | :ref:`shape` | | +-------------------------------+----------------------------------------------------------------------------+----------------------+ | :ref:`Vector2` | :ref:`target_position` | ``Vector2( 0, 50 )`` | +-------------------------------+----------------------------------------------------------------------------+----------------------+ 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:`Vector2` | :ref:`get_collision_normal` **(** :ref:`int` index **)** |const| | +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :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:`set_collision_mask_value` **(** :ref:`int` layer_number, :ref:`bool` value **)** | +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Property Descriptions --------------------- .. _class_ShapeCast2D_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:`Area2D`\ s will be reported. ---- .. _class_ShapeCast2D_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:`PhysicsBody2D`\ s will be reported. ---- .. _class_ShapeCast2D_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. ---- .. _class_ShapeCast2D_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:`Physics2DDirectSpaceState.get_rest_info` method. ---- .. _class_ShapeCast2D_property_enabled: - :ref:`bool` **enabled** +-----------+--------------------+ | *Default* | ``true`` | +-----------+--------------------+ | *Setter* | set_enabled(value) | +-----------+--------------------+ | *Getter* | is_enabled() | +-----------+--------------------+ If ``true``, collisions will be reported. ---- .. _class_ShapeCast2D_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_ShapeCast2D_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_ShapeCast2D_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_ShapeCast2D_property_shape: - :ref:`Shape2D` **shape** +----------+------------------+ | *Setter* | set_shape(value) | +----------+------------------+ | *Getter* | get_shape() | +----------+------------------+ The :ref:`Shape2D`-derived shape to be used for collision queries. ---- .. _class_ShapeCast2D_property_target_position: - :ref:`Vector2` **target_position** +-----------+----------------------------+ | *Default* | ``Vector2( 0, 50 )`` | +-----------+----------------------------+ | *Setter* | set_target_position(value) | +-----------+----------------------------+ | *Getter* | get_target_position() | +-----------+----------------------------+ The shape's destination point, relative to this node's ``position``. Method Descriptions ------------------- .. _class_ShapeCast2D_method_add_exception: - void **add_exception** **(** :ref:`Object` node **)** Adds a collision exception so the shape does not report collisions with the specified :ref:`CollisionObject2D` node. ---- .. _class_ShapeCast2D_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_ShapeCast2D_method_clear_exceptions: - void **clear_exceptions** **(** **)** Removes all collision exceptions for this shape. ---- .. _class_ShapeCast2D_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_ShapeCast2D_method_get_closest_collision_safe_fraction: - :ref:`float` **get_closest_collision_safe_fraction** **(** **)** |const| The fraction from the ``ShapeCast2D``'s origin to its :ref:`target_position` (between 0 and 1) of how far the shape can move without triggering a collision. ---- .. _class_ShapeCast2D_method_get_closest_collision_unsafe_fraction: - :ref:`float` **get_closest_collision_unsafe_fraction** **(** **)** |const| The fraction from the ``ShapeCast2D``'s origin to its :ref:`target_position` (between 0 and 1) of how far the shape must move to trigger a collision. ---- .. _class_ShapeCast2D_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_ShapeCast2D_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_ShapeCast2D_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_ShapeCast2D_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_ShapeCast2D_method_get_collision_normal: - :ref:`Vector2` **get_collision_normal** **(** :ref:`int` index **)** |const| Returns the normal of one of the multiple collisions at ``index`` of the intersecting object. ---- .. _class_ShapeCast2D_method_get_collision_point: - :ref:`Vector2` **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_ShapeCast2D_method_is_colliding: - :ref:`bool` **is_colliding** **(** **)** |const| Returns whether any object is intersecting with the shape's vector (considering the vector length). ---- .. _class_ShapeCast2D_method_remove_exception: - void **remove_exception** **(** :ref:`Object` node **)** Removes a collision exception so the shape does report collisions with the specified :ref:`CollisionObject2D` node. ---- .. _class_ShapeCast2D_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_ShapeCast2D_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.)`