Table of Contents

Class ShapeCast3D

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

Inheritance
ShapeCast3D

Remarks

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

collide_with_areas

If true, collisions with Area3Ds will be reported.

var collide_with_areas : bool = false

Property Value

bool

Remarks

  • void set_collide_with_areas(bool value)
  • bool is_collide_with_areas_enabled

collide_with_bodies

If true, collisions with PhysicsBody3Ds will be reported.

var collide_with_bodies : bool = true

Property Value

bool

Remarks

  • void set_collide_with_bodies(bool value)
  • bool is_collide_with_bodies_enabled

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.

var collision_mask : int = 1

Property Value

int

Remarks

  • void set_collision_mask(int value)
  • int get_collision_mask

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.

var collision_result : Array = []

Property Value

Array

Remarks

  • Array get_collision_result

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 debug/shapes/collision/shape_color is used.

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

Property Value

Color

Remarks

  • void set_debug_shape_custom_color(Color value)
  • Color get_debug_shape_custom_color

enabled

If true, collisions will be reported.

var enabled : bool = true

Property Value

bool

Remarks

  • void set_enabled(bool value)
  • bool is_enabled

exclude_parent

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

var exclude_parent : bool = true

Property Value

bool

Remarks

  • void set_exclude_parent_body(bool value)
  • bool get_exclude_parent_body

margin

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

var margin : float = 0.0

Property Value

float

Remarks

max_results

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

var max_results : int = 32

Property Value

int

Remarks

  • void set_max_results(int value)
  • int get_max_results

shape

The shape to be used for collision queries.

var shape : Shape3D

Property Value

Shape3D

Remarks

target_position

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

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

Property Value

Vector3

Remarks

Methods

add_exception(CollisionObject3D)

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

void add_exception(CollisionObject3D node)

Parameters

node CollisionObject3D

add_exception_rid(RID)

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

void add_exception_rid(RID rid)

Parameters

rid RID

clear_exceptions

Removes all collision exceptions for this shape.

void clear_exceptions

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.

void force_shapecast_update

get_closest_collision_safe_fraction

Qualifiers: 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.

float get_closest_collision_safe_fraction

get_closest_collision_unsafe_fraction

Qualifiers: 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.

float get_closest_collision_unsafe_fraction

get_collider(int)

Qualifiers: 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).

Object get_collider(int index)

Parameters

index int

get_collider_rid(int)

Qualifiers: const

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

RID get_collider_rid(int index)

Parameters

index int

get_collider_shape(int)

Qualifiers: 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_collider_shape(int index)

Parameters

index int

get_collision_count

Qualifiers: const

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

int get_collision_count

get_collision_mask_value(int)

Qualifiers: const

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

bool get_collision_mask_value(int layer_number)

Parameters

layer_number int

get_collision_normal(int)

Qualifiers: const

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

Vector3 get_collision_normal(int index)

Parameters

index int

get_collision_point(int)

Qualifiers: 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.

Vector3 get_collision_point(int index)

Parameters

index int

is_colliding

Qualifiers: const

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

bool is_colliding

remove_exception(CollisionObject3D)

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

void remove_exception(CollisionObject3D node)

Parameters

node CollisionObject3D

remove_exception_rid(RID)

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

void remove_exception_rid(RID rid)

Parameters

rid RID

resource_changed(Resource)

This method does nothing.

void resource_changed(Resource resource)

Parameters

resource Resource

set_collision_mask_value(int, bool)

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

void set_collision_mask_value(int layer_number, bool value)

Parameters

layer_number int
value bool