Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

ShapeCast3D

Inherits: Node3D < Node < Object

A 3D shape that sweeps a region of space to detect CollisionObject3Ds.

Description

Shape casting allows to detect collision objects by sweeping its shape along the cast direction determined by target_position. This is similar to RayCast3D, but it allows for sweeping a region of space, rather than just a straight line. ShapeCast3D 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 Vector3(0, 0, 0) and by calling force_shapecast_update within the same physics frame. This helps to overcome some limitations of Area3D 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

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

Shape3D

shape

Vector3

target_position

Vector3(0, -1, 0)

Methods

void

add_exception ( CollisionObject3D 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 ( CollisionObject3D 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, collisions with Area3Ds will be reported.

bool collide_with_bodies = true

  • void set_collide_with_bodies ( bool value )

  • bool is_collide_with_bodies_enabled ( )

If true, collisions with PhysicsBody3Ds 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 PhysicsDirectSpaceState3D.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 ShapeCast3D 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.

Shape3D shape

The Shape3D-derived 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 ( CollisionObject3D node )

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

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

float get_closest_collision_safe_fraction ( )