ShapeCast2D
Inherits: Spatial2D < CanvasItem < Actor < Object
A 2D shape that sweeps a region of space to detect CollisionObject2Ds.
Description
Section titled “Description”Shape casting allows to detect collision objects by sweeping its shape along the cast direction determined by target_position. This is similar to RayCast2D, but it allows for sweeping a region of space, rather than just a straight line. ShapeCast2D can detect multiple collision objects. It is useful for things like wide laser beams or snapping a simple shape to a floor.
Immediate collision overlaps can be done with the target_position set to Vector2(0, 0) and by calling force_shapecast_update() within the same physics frame. This helps to overcome some limitations of Area2D when used as an instantaneous detection area, as collision information isn’t immediately available to it.
Note: Shape casting is more computationally expensive than ray casting.
Properties
Section titled “Properties”| Type | Name | Default |
|---|---|---|
| bool | collide_with_areas | false |
| bool | collide_with_bodies | true |
| int | collision_mask | 1 |
| Array | collision_result | [] |
| bool | enabled | true |
| bool | exclude_parent | true |
| float | margin | 0.0 |
| int | max_results | 32 |
| Shape2D | shape | |
| Vector2 | target_position | Vector2(0, 50) |
Methods
Section titled “Methods”| Returns | Method |
|---|---|
| void | add_exception(node) |
| void | add_exception_rid(rid) |
| void | clear_exceptions() |
| void | force_shapecast_update() |
| float | get_closest_collision_safe_fraction() |
| float | get_closest_collision_unsafe_fraction() |
| Object | get_collider(index) |
| RID | get_collider_rid(index) |
| int | get_collider_shape(index) |
| int | get_collision_count() |
| bool | get_collision_mask_value(layer_number) |
| Vector2 | get_collision_normal(index) |
| Vector2 | get_collision_point(index) |
| bool | is_colliding() |
| void | remove_exception(node) |
| void | remove_exception_rid(rid) |
| void | set_collision_mask_value(layer_number, value) |
Property descriptions
Section titled “Property descriptions”collide_with_areas
Section titled “collide_with_areas”bool collide_with_areas = false
Setter/getter: set_collide_with_areas(), is_collide_with_areas_enabled()
If true, collisions with Area2Ds will be reported.
collide_with_bodies
Section titled “collide_with_bodies”bool collide_with_bodies = true
Setter/getter: set_collide_with_bodies(), is_collide_with_bodies_enabled()
If true, collisions with PhysicsBody2Ds will be reported.
collision_mask
Section titled “collision_mask”int collision_mask = 1
Setter/getter: set_collision_mask(), get_collision_mask()
The shape’s collision mask. Only objects in at least one collision layer enabled in the mask will be detected.
collision_result
Section titled “collision_result”Array collision_result = []
Setter/getter: get_collision_result()
Returns the complete collision information from the collision sweep. The data returned is the same as in the PhysicsDirectSpaceState2D.get_rest_info() method.
enabled
Section titled “enabled”bool enabled = true
Setter/getter: set_enabled(), is_enabled()
If true, collisions will be reported.
exclude_parent
Section titled “exclude_parent”bool exclude_parent = true
Setter/getter: set_exclude_parent_body(), get_exclude_parent_body()
If true, the parent actor will be excluded from collision detection.
margin
Section titled “margin”float margin = 0.0
Setter/getter: set_margin(), get_margin()
The collision margin for the shape. A larger margin helps detecting collisions more consistently, at the cost of precision.
max_results
Section titled “max_results”int max_results = 32
Setter/getter: set_max_results(), get_max_results()
The number of intersections can be limited with this parameter, to reduce the processing time.
Shape2D shape
Setter/getter: set_shape(), get_shape()
The shape to be used for collision queries.
target_position
Section titled “target_position”Vector2 target_position = Vector2(0, 50)
Setter/getter: set_target_position(), get_target_position()
The shape’s destination point, relative to this actor’s Spatial2D.position.
Method descriptions
Section titled “Method descriptions”add_exception
Section titled “add_exception”void add_exception(node: CollisionObject2D)
Adds a collision exception so the shape does not report collisions with the specified actor.
add_exception_rid
Section titled “add_exception_rid”void add_exception_rid(rid: RID)
Adds a collision exception so the shape does not report collisions with the specified RID.
clear_exceptions
Section titled “clear_exceptions”void clear_exceptions()
Removes all collision exceptions for this shape.
force_shapecast_update
Section titled “force_shapecast_update”void force_shapecast_update()
Updates the collision information for the shape immediately, without waiting for the next _physics_process call. Use this method, for example, when the shape or its parent has changed state.
Note: Setting enabled to true is not required for this to work.
get_closest_collision_safe_fraction
Section titled “get_closest_collision_safe_fraction”float get_closest_collision_safe_fraction() const
Returns the fraction from this cast’s origin to its target_position of how far the shape can move without triggering a collision, as a value between 0.0 and 1.0.
get_closest_collision_unsafe_fraction
Section titled “get_closest_collision_unsafe_fraction”float get_closest_collision_unsafe_fraction() const
Returns the fraction from this cast’s origin to its target_position of how far the shape must move to trigger a collision, as a value between 0.0 and 1.0.
In ideal conditions this would be the same as get_closest_collision_safe_fraction(), however shape casting is calculated in discrete steps, so the precise point of collision can occur between two calculated positions.
get_collider
Section titled “get_collider”Object get_collider(index: int) const
Returns the collided Object of one of the multiple collisions at index, or null if no object is intersecting the shape (i.e. is_colliding() returns false).
get_collider_rid
Section titled “get_collider_rid”RID get_collider_rid(index: int) const
Returns the RID of the collided object of one of the multiple collisions at index.
get_collider_shape
Section titled “get_collider_shape”int get_collider_shape(index: int) 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. is_colliding() returns false).
get_collision_count
Section titled “get_collision_count”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 get_collider(), get_collider_shape(), get_collision_point(), and get_collision_normal() methods.
get_collision_mask_value
Section titled “get_collision_mask_value”bool get_collision_mask_value(layer_number: int) const
Returns whether or not the specified layer of the collision_mask is enabled, given a layer_number between 1 and 32.
get_collision_normal
Section titled “get_collision_normal”Vector2 get_collision_normal(index: int) const
Returns the normal of one of the multiple collisions at index of the intersecting object.
get_collision_point
Section titled “get_collision_point”Vector2 get_collision_point(index: int) 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.
is_colliding
Section titled “is_colliding”bool is_colliding() const
Returns whether any object is intersecting with the shape’s vector (considering the vector length).
remove_exception
Section titled “remove_exception”void remove_exception(node: CollisionObject2D)
Removes a collision exception so the shape does report collisions with the specified actor.
remove_exception_rid
Section titled “remove_exception_rid”void remove_exception_rid(rid: RID)
Removes a collision exception so the shape does report collisions with the specified RID.
set_collision_mask_value
Section titled “set_collision_mask_value”void set_collision_mask_value(layer_number: int, value: bool)
Based on value, enables or disables the specified layer in the collision_mask, given a layer_number between 1 and 32.