Area3D

package
v0.0.0-...-357ca8a Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 20, 2025 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Area3D is a region of 3D space defined by one or multiple CollisionShape3D or CollisionPolygon3D child nodes. It detects when other CollisionObject3Ds enter or exit it, and it also keeps track of which collision objects haven't exited it yet (i.e. which one are overlapping it).

This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses.

Note: Areas and bodies created with PhysicsServer3D might not interact as expected with Area3Ds, and might not emit signals or track objects correctly.

Warning: Using a ConcavePolygonShape3D inside a CollisionShape3D child of this node (created e.g. by using the Create Trimesh Collision Sibling option in the Mesh menu that appears when selecting a MeshInstance3D node) may give unexpected results, since this collision shape is hollow. If this is not desired, it has to be split into multiple ConvexPolygonShape3Ds or primitive shapes like BoxShape3D, or in some cases it may be replaceable by a CollisionPolygon3D.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Advanced 

type Advanced = class

Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.

type Any 

type Any interface {
	gd.IsClass
	AsArea3D() Instance
}

type Extension 

type Extension[T gdclass.Interface] struct{ gdclass.Extension[T, Instance] }

Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension

func (*Extension[T]) AsArea3D 

func (self *Extension[T]) AsArea3D() Instance

func (*Extension[T]) AsCollisionObject3D 

func (self *Extension[T]) AsCollisionObject3D() CollisionObject3D.Instance

func (*Extension[T]) AsNode 

func (self *Extension[T]) AsNode() Node.Instance

func (*Extension[T]) AsNode3D 

func (self *Extension[T]) AsNode3D() Node3D.Instance

func (*Extension[T]) AsObject 

func (self *Extension[T]) AsObject() [1]gd.Object

type ID 

type ID Object.ID

ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.

func (ID) Instance 

func (id ID) Instance() (Instance, bool)

type Instance 

type Instance [1]gdclass.Area3D

Instance of the class with convieniently typed arguments and results. 

var Nil Instance

Nil is a nil/null instance of the class. Equivalent to the zero value.

func New 

func New() Instance

func (Instance) AngularDamp 

func (self Instance) AngularDamp() Float.X

The rate at which objects stop spinning in this area. Represents the angular velocity lost per second.

See ProjectSettings "physics/3d/default_angular_damp" for more details about damping.

func (Instance) AngularDampSpaceOverride 

func (self Instance) AngularDampSpaceOverride() SpaceOverride

Override mode for angular damping calculations within this area.

func (Instance) AsArea3D 

func (self Instance) AsArea3D() Instance

func (Instance) AsCollisionObject3D 

func (self Instance) AsCollisionObject3D() CollisionObject3D.Instance

func (Instance) AsNode 

func (self Instance) AsNode() Node.Instance

func (Instance) AsNode3D 

func (self Instance) AsNode3D() Node3D.Instance

func (Instance) AsObject 

func (self Instance) AsObject() [1]gd.Object

func (Instance) AudioBusName 

func (self Instance) AudioBusName() string

The name of the area's audio bus.

func (Instance) AudioBusOverride 

func (self Instance) AudioBusOverride() bool

If true, the area's audio bus overrides the default audio bus.

func (Instance) GetOverlappingAreas 

func (self Instance) GetOverlappingAreas() []Instance

Returns a list of intersecting Area3Ds. The overlapping area's CollisionObject3D.CollisionLayer must be part of this area's CollisionObject3D.CollisionMask in order to be detected.

For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.

func (Instance) GetOverlappingBodies 

func (self Instance) GetOverlappingBodies() []Node3D.Instance

Returns a list of intersecting PhysicsBody3Ds and GridMaps. The overlapping body's CollisionObject3D.CollisionLayer must be part of this area's CollisionObject3D.CollisionMask in order to be detected.

For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.

func (Instance) Gravity 

func (self Instance) Gravity() Float.X

The area's gravity intensity (in meters per second squared). This value multiplies the gravity direction. This is useful to alter the force of gravity without altering its direction.

func (Instance) GravityDirection 

func (self Instance) GravityDirection() Vector3.XYZ

The area's gravity vector (not normalized).

func (Instance) GravityPoint 

func (self Instance) GravityPoint() bool

If true, gravity is calculated from a point (set via GravityPointCenter). See also GravitySpaceOverride.

func (Instance) GravityPointCenter 

func (self Instance) GravityPointCenter() Vector3.XYZ

If gravity is a point (see GravityPoint), this will be the point of attraction.

func (Instance) GravityPointUnitDistance 

func (self Instance) GravityPointUnitDistance() Float.X

The distance at which the gravity strength is equal to Gravity. For example, on a planet 100 meters in radius with a surface gravity of 4.0 m/s², set the Gravity to 4.0 and the unit distance to 100.0. The gravity will have falloff according to the inverse square law, so in the example, at 200 meters from the center the gravity will be 1.0 m/s² (twice the distance, 1/4th the gravity), at 50 meters it will be 16.0 m/s² (half the distance, 4x the gravity), and so on.

The above is true only when the unit distance is a positive number. When this is set to 0.0, the gravity will be constant regardless of distance.

func (Instance) GravitySpaceOverride 

func (self Instance) GravitySpaceOverride() SpaceOverride

Override mode for gravity calculations within this area.

func (Instance) HasOverlappingAreas 

func (self Instance) HasOverlappingAreas() bool

Returns true if intersecting any Area3Ds, otherwise returns false. The overlapping area's CollisionObject3D.CollisionLayer must be part of this area's CollisionObject3D.CollisionMask in order to be detected.

For performance reasons (collisions are all processed at the same time) the list of overlapping areas is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.

func (Instance) HasOverlappingBodies 

func (self Instance) HasOverlappingBodies() bool

Returns true if intersecting any PhysicsBody3Ds or GridMaps, otherwise returns false. The overlapping body's CollisionObject3D.CollisionLayer must be part of this area's CollisionObject3D.CollisionMask in order to be detected.

For performance reasons (collisions are all processed at the same time) the list of overlapping bodies is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.

func (Instance) ID 

func (self Instance) ID() ID

func (Instance) LinearDamp 

func (self Instance) LinearDamp() Float.X

The rate at which objects stop moving in this area. Represents the linear velocity lost per second.

See ProjectSettings "physics/3d/default_linear_damp" for more details about damping.

func (Instance) LinearDampSpaceOverride 

func (self Instance) LinearDampSpaceOverride() SpaceOverride

Override mode for linear damping calculations within this area.

func (Instance) Monitorable 

func (self Instance) Monitorable() bool

If true, other monitoring areas can detect this area.

func (Instance) Monitoring 

func (self Instance) Monitoring() bool

If true, the area detects bodies or areas entering and exiting it.

func (Instance) OnAreaEntered 

func (self Instance) OnAreaEntered(cb func(area Instance), flags ...Signal.Flags)

Emitted when the received 'area' enters this area. Requires Monitoring to be set to true.

func (Instance) OnAreaExited 

func (self Instance) OnAreaExited(cb func(area Instance), flags ...Signal.Flags)

Emitted when the received 'area' exits this area. Requires Monitoring to be set to true.

func (Instance) OnAreaShapeEntered 

func (self Instance) OnAreaShapeEntered(cb func(area_rid RID.Any, area Instance, area_shape_index int, local_shape_index int), flags ...Signal.Flags)

Emitted when a Shape3D of the received 'area' enters a shape of this area. Requires Monitoring to be set to true.

'local_shape_index' and 'area_shape_index' contain indices of the interacting shapes from this area and the other area, respectively. 'area_rid' contains the Resource.ID of the other area. These values can be used with the PhysicsServer3D.

Example: Get the CollisionShape3D node from the shape index:

func (Instance) OnAreaShapeExited 

func (self Instance) OnAreaShapeExited(cb func(area_rid RID.Any, area Instance, area_shape_index int, local_shape_index int), flags ...Signal.Flags)

Emitted when a Shape3D of the received 'area' exits a shape of this area. Requires Monitoring to be set to true.

See also OnAreaShapeEntered.

func (Instance) OnBodyEntered 

func (self Instance) OnBodyEntered(cb func(body Node3D.Instance), flags ...Signal.Flags)

Emitted when the received 'body' enters this area. 'body' can be a PhysicsBody3D or a GridMap. GridMaps are detected if their MeshLibrary has collision shapes configured. Requires Monitoring to be set to true.

func (Instance) OnBodyExited 

func (self Instance) OnBodyExited(cb func(body Node3D.Instance), flags ...Signal.Flags)

Emitted when the received 'body' exits this area. 'body' can be a PhysicsBody3D or a GridMap. GridMaps are detected if their MeshLibrary has collision shapes configured. Requires Monitoring to be set to true.

func (Instance) OnBodyShapeEntered 

func (self Instance) OnBodyShapeEntered(cb func(body_rid RID.Any, body Node3D.Instance, body_shape_index int, local_shape_index int), flags ...Signal.Flags)

Emitted when a Shape3D of the received 'body' enters a shape of this area. 'body' can be a PhysicsBody3D or a GridMap. GridMaps are detected if their MeshLibrary has collision shapes configured. Requires Monitoring to be set to true.

'local_shape_index' and 'body_shape_index' contain indices of the interacting shapes from this area and the interacting body, respectively. 'body_rid' contains the Resource.ID of the body. These values can be used with the PhysicsServer3D.

Example: Get the CollisionShape3D node from the shape index:

func (Instance) OnBodyShapeExited 

func (self Instance) OnBodyShapeExited(cb func(body_rid RID.Any, body Node3D.Instance, body_shape_index int, local_shape_index int), flags ...Signal.Flags)

Emitted when a Shape3D of the received 'body' exits a shape of this area. 'body' can be a PhysicsBody3D or a GridMap. GridMaps are detected if their MeshLibrary has collision shapes configured. Requires Monitoring to be set to true.

See also OnBodyShapeEntered.

func (Instance) OverlapsArea 

func (self Instance) OverlapsArea(area Node.Instance) bool

Returns true if the given Area3D intersects or overlaps this Area3D, false otherwise.

Note: The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead.

func (Instance) OverlapsBody 

func (self Instance) OverlapsBody(body Node.Instance) bool

Returns true if the given physics body intersects or overlaps this Area3D, false otherwise.

Note: The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead.

The 'body' argument can either be a PhysicsBody3D or a GridMap instance. While GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body.

func (Instance) Priority 

func (self Instance) Priority() int

The area's priority. Higher priority areas are processed first. The World3D's physics is always processed last, after all areas.

func (Instance) ReverbBusAmount 

func (self Instance) ReverbBusAmount() Float.X

The degree to which this area applies reverb to its associated audio. Ranges from 0 to 1 with 0.1 precision.

func (Instance) ReverbBusEnabled 

func (self Instance) ReverbBusEnabled() bool

If true, the area applies reverb to its associated audio.

func (Instance) ReverbBusName 

func (self Instance) ReverbBusName() string

The name of the reverb bus to use for this area's associated audio.

func (Instance) ReverbBusUniformity 

func (self Instance) ReverbBusUniformity() Float.X

The degree to which this area's reverb is a uniform effect. Ranges from 0 to 1 with 0.1 precision.

func (Instance) SetAngularDamp 

func (self Instance) SetAngularDamp(value Float.X)

SetAngularDamp sets the property returned by [GetAngularDamp].

func (Instance) SetAngularDampSpaceOverride 

func (self Instance) SetAngularDampSpaceOverride(value SpaceOverride)

SetAngularDampSpaceOverride sets the property returned by [GetAngularDampSpaceOverrideMode].

func (Instance) SetAudioBusName 

func (self Instance) SetAudioBusName(value string)

SetAudioBusName sets the property returned by [GetAudioBusName].

func (Instance) SetAudioBusOverride 

func (self Instance) SetAudioBusOverride(value bool)

SetAudioBusOverride sets the property returned by [IsOverridingAudioBus].

func (Instance) SetGravity 

func (self Instance) SetGravity(value Float.X)

SetGravity sets the property returned by [GetGravity].

func (Instance) SetGravityDirection 

func (self Instance) SetGravityDirection(value Vector3.XYZ)

SetGravityDirection sets the property returned by [GetGravityDirection].

func (Instance) SetGravityPoint 

func (self Instance) SetGravityPoint(value bool)

SetGravityPoint sets the property returned by [IsGravityAPoint].

func (Instance) SetGravityPointCenter 

func (self Instance) SetGravityPointCenter(value Vector3.XYZ)

SetGravityPointCenter sets the property returned by [GetGravityPointCenter].

func (Instance) SetGravityPointUnitDistance 

func (self Instance) SetGravityPointUnitDistance(value Float.X)

SetGravityPointUnitDistance sets the property returned by [GetGravityPointUnitDistance].

func (Instance) SetGravitySpaceOverride 

func (self Instance) SetGravitySpaceOverride(value SpaceOverride)

SetGravitySpaceOverride sets the property returned by [GetGravitySpaceOverrideMode].

func (Instance) SetLinearDamp 

func (self Instance) SetLinearDamp(value Float.X)

SetLinearDamp sets the property returned by [GetLinearDamp].

func (Instance) SetLinearDampSpaceOverride 

func (self Instance) SetLinearDampSpaceOverride(value SpaceOverride)

SetLinearDampSpaceOverride sets the property returned by [GetLinearDampSpaceOverrideMode].

func (Instance) SetMonitorable 

func (self Instance) SetMonitorable(value bool)

SetMonitorable sets the property returned by [IsMonitorable].

func (Instance) SetMonitoring 

func (self Instance) SetMonitoring(value bool)

SetMonitoring sets the property returned by [IsMonitoring].

func (*Instance) SetObject 

func (self *Instance) SetObject(obj [1]gd.Object) bool

func (Instance) SetPriority 

func (self Instance) SetPriority(value int)

SetPriority sets the property returned by [GetPriority].

func (Instance) SetReverbBusAmount 

func (self Instance) SetReverbBusAmount(value Float.X)

SetReverbBusAmount sets the property returned by [GetReverbAmount].

func (Instance) SetReverbBusEnabled 

func (self Instance) SetReverbBusEnabled(value bool)

SetReverbBusEnabled sets the property returned by [IsUsingReverbBus].

func (Instance) SetReverbBusName 

func (self Instance) SetReverbBusName(value string)

SetReverbBusName sets the property returned by [GetReverbBusName].

func (Instance) SetReverbBusUniformity 

func (self Instance) SetReverbBusUniformity(value Float.X)

SetReverbBusUniformity sets the property returned by [GetReverbUniformity].

func (Instance) SetWindAttenuationFactor 

func (self Instance) SetWindAttenuationFactor(value Float.X)

SetWindAttenuationFactor sets the property returned by [GetWindAttenuationFactor].

func (Instance) SetWindForceMagnitude 

func (self Instance) SetWindForceMagnitude(value Float.X)

SetWindForceMagnitude sets the property returned by [GetWindForceMagnitude].

func (Instance) SetWindSourcePath 

func (self Instance) SetWindSourcePath(value string)

SetWindSourcePath sets the property returned by [GetWindSourcePath].

func (Instance) Virtual 

func (self Instance) Virtual(name string) reflect.Value

func (Instance) WindAttenuationFactor 

func (self Instance) WindAttenuationFactor() Float.X

The exponential rate at which wind force decreases with distance from its origin.

Note: This wind force only applies to SoftBody3D nodes. Other physics bodies are currently not affected by wind.

func (Instance) WindForceMagnitude 

func (self Instance) WindForceMagnitude() Float.X

The magnitude of area-specific wind force.

Note: This wind force only applies to SoftBody3D nodes. Other physics bodies are currently not affected by wind.

func (Instance) WindSourcePath 

func (self Instance) WindSourcePath() string

The Node3D which is used to specify the direction and origin of an area-specific wind force. The direction is opposite to the z-axis of the Node3D's local transform, and its origin is the origin of the Node3D's local transform.

Note: This wind force only applies to SoftBody3D nodes. Other physics bodies are currently not affected by wind.

type SpaceOverride 

type SpaceOverride int //gd:Area3D.SpaceOverride

const (
	// This area does not affect gravity/damping.
	SpaceOverrideDisabled SpaceOverride = 0
	// This area adds its gravity/damping values to whatever has been calculated so far (in [Priority] order).
	//
	// [Priority]: https://pkg.go.dev/graphics.gd/classdb/#Instance.Priority
	SpaceOverrideCombine SpaceOverride = 1
	// This area adds its gravity/damping values to whatever has been calculated so far (in [Priority] order), ignoring any lower priority areas.
	//
	// [Priority]: https://pkg.go.dev/graphics.gd/classdb/#Instance.Priority
	SpaceOverrideCombineReplace SpaceOverride = 2
	// This area replaces any gravity/damping, even the defaults, ignoring any lower priority areas.
	SpaceOverrideReplace SpaceOverride = 3
	// This area replaces any gravity/damping calculated so far (in [Priority] order), but keeps calculating the rest of the areas.
	//
	// [Priority]: https://pkg.go.dev/graphics.gd/classdb/#Instance.Priority
	SpaceOverrideReplaceCombine SpaceOverride = 4
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.