ShapeCast2D¶
Inherits: Node2D < CanvasItem < Node < Object
Node for physics collision sweep and immediate overlap queries. Similar to the RayCast2D node.
Description¶
Shape casting allows to detect collision objects by sweeping the shape along the cast direction determined by target_position (useful for things like beam weapons).
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 also helps to overcome some limitations of Area2D when used as a continuous 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.
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¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Methods¶
void |
add_exception ( CollisionObject2D node ) |
void |
add_exception_rid ( RID rid ) |
void |
clear_exceptions ( ) |
void |
|
get_closest_collision_safe_fraction ( ) const |
|
get_closest_collision_unsafe_fraction ( ) const |
|
get_collider ( int index ) const |
|
get_collider_rid ( int index ) const |
|
get_collider_shape ( int index ) const |
|
get_collision_count ( ) const |
|
get_collision_mask_value ( int layer_number ) const |
|
get_collision_normal ( int index ) const |
|
get_collision_point ( int index ) const |
|
is_colliding ( ) const |
|
void |
remove_exception ( CollisionObject2D node ) |
void |
remove_exception_rid ( RID rid ) |
void |
set_collision_mask_value ( int layer_number, bool value ) |
Property Descriptions¶
bool collide_with_areas
Default |
|
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 |
|
Setter |
set_collide_with_bodies(value) |
Getter |
is_collide_with_bodies_enabled() |
If true, collision with PhysicsBody2Ds will be reported.
int collision_mask
Default |
|
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.
Array collision_result
Default |
|
Returns the complete collision information from the collision sweep. The data returned is the same as in the PhysicsDirectSpaceState2D.get_rest_info method.
bool enabled
Default |
|
Setter |
set_enabled(value) |
Getter |
is_enabled() |
If true, collisions will be reported.
bool exclude_parent
Default |
|
Setter |
set_exclude_parent_body(value) |
Getter |
get_exclude_parent_body() |
If true, the parent node will be excluded from collision detection.
float margin
Default |
|
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.
int max_results
Default |
|
Setter |
set_max_results(value) |
Getter |
get_max_results() |
The number of intersections can be limited with this parameter, to reduce the processing time.
Shape2D shape
Setter |
set_shape(value) |
Getter |
get_shape() |
The Shape2D-derived shape to be used for collision queries.
Vector2 target_position
Default |
|
Setter |
set_target_position(value) |
Getter |
get_target_position() |
The shape's destination point, relative to this node's position.
Method Descriptions¶
void add_exception ( CollisionObject2D node )
Adds a collision exception so the shape does not report collisions with the specified CollisionObject2D 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.
float get_closest_collision_safe_fraction ( ) const
The fraction from the ShapeCast2D's origin to its target_position (between 0 and 1) of how far the shape can move without triggering a collision.
float get_closest_collision_unsafe_fraction ( ) const
The fraction from the ShapeCast2D's origin to its target_position (between 0 and 1) of how far the shape must move to trigger a collision.
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).
Returns the RID of the collided object of one of the multiple collisions at index.
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).
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.
Returns whether or not the specified layer of the collision_mask is enabled, given a layer_number between 1 and 32.
Returns the normal of one of the multiple collisions at index of the intersecting object.
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.
bool is_colliding ( ) const
Returns whether any object is intersecting with the shape's vector (considering the vector length).
void remove_exception ( CollisionObject2D node )
Removes a collision exception so the shape does report collisions with the specified CollisionObject2D node.
void remove_exception_rid ( RID rid )
Removes a collision exception so the shape does report collisions with the specified RID.
Based on value, enables or disables the specified layer in the collision_mask, given a layer_number between 1 and 32.