ShapeCast2D

Inherits: Node2D < CanvasItem < Node < Object

Node for physics collision sweep and immediate overlap queries. Similar to the RayCast2D node.

Description

Unlike RayCast2D, shape casting allows to detect collision objects along the cast area (for instance, beam weapons).

Immediate collision overlaps can be easily done with the cast_to set to Vector2(0, 0) and by calling force_shapecast_update within the same physics_frame. This also helps to overcome some limitations of Area2D when used as a continuos detection area, often requiring waiting a couple of frames before collision information is available to Area2D nodes, and when using the signals creates unnecessary complexity.

This node can detect multiple collision objects. If you want to use this just like RayCast2D, use corresponding get_closest_* methods instead. Cannot detect all objects along the cast motion, but only when collision occurs (same as in RayCast2D).

Note: shape casting is more computationally expensive compared to ray casting.

Property Descriptions

Default Vector2( 0, 50 )
Setter set_cast_to(value)
Getter get_cast_to()

The shape’s destination point, relative to this node’s position.

  • bool collide_with_areas
Default false
Setter set_collide_with_areas(value)
Getter is_collide_with_areas_enabled()

If true, collision with Area2Ds will be reported.

  • bool collide_with_bodies
Default true
Setter set_collide_with_bodies(value)
Getter is_collide_with_bodies_enabled()

If true, collision with PhysicsBody2Ds will be reported.

  • 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.

Default [  ]

A complete collision information. The data returned is the same as in the Physics2DDirectSpaceState.get_rest_info method.

Default true
Setter set_enabled(value)
Getter is_enabled()

If true, collisions will be reported.

  • 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.

Default 0.0
Setter set_margin(value)
Getter get_margin()

The collision margin for the shape. Large margin speeds up the performance at the cost of precision.

  • 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.

Setter set_shape(value)
Getter get_shape()

Any Shape2D used for collision queries.

Method Descriptions

  • void add_exception ( Object node )

Adds a collision exception so the shape does not report collisions with the specified node.

  • void add_exception_rid ( RID rid )

Adds a collision exception so the shape does not report collisions with the specified RID.

  • void clear_exceptions ( )

Removes all collision exceptions for this shape.

  • 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 == true is not required for this to work.

  • Object get_closest_collider ( ) const

Returns the first object that the shape intersects, or null if no object is intersecting the shape (i.e. is_colliding returns false).

  • int get_closest_collider_shape ( ) const

Returns the shape ID of the first object that the shape intersects, or 0 if no object is intersecting the shape (i.e. is_colliding returns false).

  • Vector2 get_closest_collision_normal ( ) const

Returns the normal of the closest intersecting object’s shape at the collision point.

  • Vector2 get_closest_collision_point ( ) const

Returns the collision point at which the shape intersects the closest object.

Note: this point is in the global coordinate system.

  • float get_closest_collision_safe_distance ( ) const

The fraction of the motion (determined by cast_to) of how far the shape can move without triggering a collision.

  • float get_closest_collision_unsafe_distance ( ) const

The fraction of the motion (determined by cast_to) when the shape triggers a collision.

Returns the first object that the shape intersects, or null if no object is intersecting the shape (i.e. is_colliding returns false).

  • int get_collider_shape ( int index ) const

Returns the shape ID of one of the multiple collisions at index that the shape intersects, or 0 if no object is intersecting the shape (i.e. is_colliding returns false).

  • int get_collision_count ( ) const

The number of collisions detected. Use this to iterate over multiple collisions as provided by get_collider, get_collider_shape, get_collision_point, and get_collision_normal methods.

  • bool get_collision_mask_bit ( int bit ) const

Returns an individual bit on the collision mask.

  • Vector2 get_collision_normal ( int index ) const

Returns the normal containing one of the multiple collisions at index of the intersecting object.

Returns the collision point containing one of the multiple collisions at index at which the shape intersects the object.

Note: this point is in the global coordinate system.

  • bool is_colliding ( ) const

Returns whether any object is intersecting with the shape’s vector (considering the vector length).

  • void remove_exception ( Object node )

Removes a collision exception so the shape does report collisions with the specified node.

  • void remove_exception_rid ( RID rid )

Removes a collision exception so the shape does report collisions with the specified RID.

  • void set_collision_mask_bit ( int bit, bool value )

Sets or clears individual bits on the collision mask. This makes selecting the areas scanned easier.