ShapeCast¶

Node for physics collision sweep and immediate overlap queries. Similar to the RayCast 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 Vector3(0, 0, 0) and by calling force_shapecast_update within the same physics_frame. This also helps to overcome some limitations of Area when used as a continuous detection area, often requiring waiting a couple of frames before collision information is available to 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.

Properties¶

bool	collide_with_areas	`false`
bool	collide_with_bodies	`true`
int	collision_mask	`1`
Array	collision_result
Color	debug_shape_custom_color	`Color( 0, 0, 0, 1 )`
bool	enabled	`true`
bool	exclude_parent	`true`
float	margin	`0.0`
int	max_results	`32`
Shape	shape
Vector3	target_position	`Vector3( 0, -1, 0 )`

Methods¶

void	add_exception ( Object node )
void	add_exception_rid ( RID rid )
void	clear_exceptions ( )
void	force_shapecast_update ( )
float	get_closest_collision_safe_fraction ( ) const
float	get_closest_collision_unsafe_fraction ( ) const
Object	get_collider ( int index ) const
RID	get_collider_rid ( int index ) const
int	get_collider_shape ( int index ) const
int	get_collision_count ( ) const
bool	get_collision_mask_value ( int layer_number ) const
Vector3	get_collision_normal ( int index ) const
Vector3	get_collision_point ( int index ) const
bool	is_colliding ( ) const
void	remove_exception ( Object node )
void	remove_exception_rid ( RID rid )
void	resource_changed ( Resource resource )
void	set_collision_mask_value ( int layer_number, bool value )

Property Descriptions¶

bool collide_with_areas = false

void set_collide_with_areas ( bool value )
bool is_collide_with_areas_enabled ( )

If true, collision with Areas will be reported.

bool collide_with_bodies = true

void set_collide_with_bodies ( bool value )
bool is_collide_with_bodies_enabled ( )

If true, collision with PhysicsBodys will be reported.

int collision_mask = 1

void set_collision_mask ( int value )
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 in the documentation for more information.

Array collision_result

Returns the complete collision information from the collision sweep. The data returned is the same as in the PhysicsDirectSpaceState.get_rest_info method.

Color debug_shape_custom_color = Color( 0, 0, 0, 1 )

void set_debug_shape_custom_color ( Color value )
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 ProjectSettings.debug/shapes/collision/shape_color is used.

bool enabled = true

void set_enabled ( bool value )
bool is_enabled ( )

If true, collisions will be reported.

bool exclude_parent = true

void set_exclude_parent_body ( bool value )
bool get_exclude_parent_body ( )

If true, the parent node will be excluded from collision detection.

float margin = 0.0

void set_margin ( float value )
float get_margin ( )

The collision margin for the shape. A larger margin helps detecting collisions more consistently, at the cost of precision.

int max_results = 32

void set_max_results ( int value )
int get_max_results ( )

The number of intersections can be limited with this parameter, to reduce the processing time.

Shape shape

void set_shape ( Shape value )
Shape get_shape ( )

The Shape to be used for collision queries.

Vector3 target_position = Vector3( 0, -1, 0 )

void set_target_position ( Vector3 value )
Vector3 get_target_position ( )

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

Method Descriptions¶

void add_exception ( Object node )

Adds a collision exception so the shape does not report collisions with the specified CollisionObject 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 ShapeCast.

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.

float get_closest_collision_safe_fraction ( ) const

The fraction from the ShapeCast'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 ShapeCast's origin to its target_position (between 0 and 1) of how far the shape must move to trigger a collision.

Object get_collider ( int index ) 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).

RID get_collider_rid ( int index ) const

Returns the RID of the collided object of one of the multiple collisions at index.

int get_collider_shape ( 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. 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.

bool get_collision_mask_value ( int layer_number ) const

Returns whether or not the specified layer of the collision_mask is enabled, given a layer_number between 1 and 32.

Vector3 get_collision_normal ( int index ) const

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

Vector3 get_collision_point ( 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.

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 CollisionObject node.

void remove_exception_rid ( RID rid )

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

void resource_changed ( 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 shape resource is modified.

void set_collision_mask_value ( int layer_number, bool value )

Based on value, enables or disables the specified layer in the collision_mask, given a layer_number between 1 and 32.