Struct AStar3D

pub struct AStar3D { /* private fields */ }

Expand description

Godot class AStar3D.

Inherits RefCounted.

Related symbols:

a_star_3d: sidecar module with related enum/flag types
IAStar3D: virtual methods

§Construction

This class is reference-counted. You can create a new instance using AStar3D::new_gd().

§Godot docs

A* (A star) is a computer algorithm used in pathfinding and graph traversal, the process of plotting short paths among vertices (points), passing through a given set of edges (segments). It enjoys widespread use due to its performance and accuracy. Godot’s A* implementation uses points in 3D space and Euclidean distances by default.

You must add points manually with add_point and create segments manually with connect_points. Once done, you can test if there is a path between two points with the are_points_connected function, get a path containing indices by get_id_path, or one containing actual coordinates with get_point_path.

It is also possible to use non-Euclidean distances. To do so, create a script that extends AStar3D and override the methods compute_cost and estimate_cost. Both should take two point IDs and return the distance between the corresponding points.

Example: Use Manhattan distance instead of Euclidean distance:

class_name MyAStar3D
extends AStar3D

func _compute_cost(u, v):
	var u_pos = get_point_position(u)
	var v_pos = get_point_position(v)
	return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z)

func _estimate_cost(u, v):
	var u_pos = get_point_position(u)
	var v_pos = get_point_position(v)
	return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z)

using Godot;

[GlobalClass][crate::classes::GlobalClass]
public partial class MyAStar3D : AStar3D
{
	public override float _ComputeCost(long fromId, long toId)
	{
		Vector3 fromPoint = GetPointPosition(fromId);
		Vector3 toPoint = GetPointPosition(toId);

		return Mathf.Abs(fromPoint.X - toPoint.X) + Mathf.Abs(fromPoint.Y - toPoint.Y) + Mathf.Abs(fromPoint.Z - toPoint.Z);
	}

	public override float _EstimateCost(long fromId, long toId)
	{
		Vector3 fromPoint = GetPointPosition(fromId);
		Vector3 toPoint = GetPointPosition(toId);
		return Mathf.Abs(fromPoint.X - toPoint.X) + Mathf.Abs(fromPoint.Y - toPoint.Y) + Mathf.Abs(fromPoint.Z - toPoint.Z);
	}
}

estimate_cost should return a lower bound of the distance, i.e. _estimate_cost(u, v) <= _compute_cost(u, v). This serves as a hint to the algorithm because the custom compute_cost might be computation-heavy. If this is not the case, make estimate_cost return the same value as compute_cost to provide the algorithm with the most accurate information.

If the default estimate_cost and compute_cost methods are used, or if the supplied estimate_cost method returns a lower bound of the cost, then the paths returned by A* will be the lowest-cost paths. Here, the cost of a path equals the sum of the compute_cost results of all segments in the path multiplied by the weight_scales of the endpoints of the respective segments. If the default methods are used and the weight_scales of all points are set to 1.0, then this equals the sum of Euclidean distances of all segments in the path.

Implementations§

§

impl AStar3D

pub fn get_available_point_id(&self) -> i64

pub fn add_point(&mut self, id: i64, position: Vector3)

To set the default parameters, use Self::add_point_ex and its builder methods. See the book for detailed usage instructions.

pub fn add_point_ex<'ex>( &'ex mut self, id: i64, position: Vector3, ) -> ExAddPoint<'ex>

pub fn get_point_position(&self, id: i64) -> Vector3

pub fn set_point_position(&mut self, id: i64, position: Vector3)

pub fn get_point_weight_scale(&self, id: i64) -> f32

pub fn set_point_weight_scale(&mut self, id: i64, weight_scale: f32)

pub fn remove_point(&mut self, id: i64)

pub fn has_point(&self, id: i64) -> bool

pub fn get_point_connections(&self, id: i64) -> PackedArray<i64>

pub fn get_point_ids(&self) -> PackedArray<i64>

pub fn set_point_disabled(&mut self, id: i64)

To set the default parameters, use Self::set_point_disabled_ex and its builder methods. See the book for detailed usage instructions.

pub fn set_point_disabled_ex<'ex>( &'ex mut self, id: i64, ) -> ExSetPointDisabled<'ex>

pub fn is_point_disabled(&self, id: i64) -> bool

pub fn set_neighbor_filter_enabled(&mut self, enabled: bool)

pub fn is_neighbor_filter_enabled(&self) -> bool

pub fn connect_points(&mut self, id: i64, to_id: i64)

To set the default parameters, use Self::connect_points_ex and its builder methods. See the book for detailed usage instructions.

pub fn connect_points_ex<'ex>( &'ex mut self, id: i64, to_id: i64, ) -> ExConnectPoints<'ex>

pub fn disconnect_points(&mut self, id: i64, to_id: i64)

To set the default parameters, use Self::disconnect_points_ex and its builder methods. See the book for detailed usage instructions.

pub fn disconnect_points_ex<'ex>( &'ex mut self, id: i64, to_id: i64, ) -> ExDisconnectPoints<'ex>

pub fn are_points_connected(&self, id: i64, to_id: i64) -> bool

To set the default parameters, use Self::are_points_connected_ex and its builder methods. See the book for detailed usage instructions.

pub fn are_points_connected_ex<'ex>( &'ex self, id: i64, to_id: i64, ) -> ExArePointsConnected<'ex>

pub fn get_point_count(&self) -> i64

pub fn get_point_capacity(&self) -> i64

pub fn reserve_space(&mut self, num_nodes: i64)

pub fn clear(&mut self)

pub fn get_closest_point(&self, to_position: Vector3) -> i64

To set the default parameters, use Self::get_closest_point_ex and its builder methods. See the book for detailed usage instructions.

pub fn get_closest_point_ex<'ex>( &'ex self, to_position: Vector3, ) -> ExGetClosestPoint<'ex>

pub fn get_closest_position_in_segment(&self, to_position: Vector3) -> Vector3

pub fn get_point_path(&self, from_id: i64, to_id: i64) -> PackedArray<Vector3>

To set the default parameters, use Self::get_point_path_ex and its builder methods. See the book for detailed usage instructions.

pub fn get_point_path_ex<'ex>( &'ex self, from_id: i64, to_id: i64, ) -> ExGetPointPath<'ex>

pub fn get_id_path(&self, from_id: i64, to_id: i64) -> PackedArray<i64>

To set the default parameters, use Self::get_id_path_ex and its builder methods. See the book for detailed usage instructions.

pub fn get_id_path_ex<'ex>( &'ex self, from_id: i64, to_id: i64, ) -> ExGetIdPath<'ex>

Methods from Deref<Target = RefCounted>§

pub fn get_reference_count(&self) -> i32

Methods from Deref<Target = Object>§

pub fn get_script(&self) -> Option<Gd<Script>>

pub fn set_script(&mut self, script: impl AsArg<Option<Gd<Script>>>)

pub fn connect( &mut self, signal: impl AsArg<StringName>, callable: &Callable, ) -> Error

pub fn connect_flags( &mut self, signal: impl AsArg<StringName>, callable: &Callable, flags: ConnectFlags, ) -> Error

pub fn get_class(&self) -> GString

pub fn is_class(&self, class: impl AsArg<GString>) -> bool

pub fn set(&mut self, property: impl AsArg<StringName>, value: &Variant)

pub fn get(&self, property: impl AsArg<StringName>) -> Variant

pub fn set_indexed( &mut self, property_path: impl AsArg<NodePath>, value: &Variant, )

pub fn get_indexed(&self, property_path: impl AsArg<NodePath>) -> Variant

pub fn get_property_list(&self) -> Array<Dictionary<Variant, Variant>>

pub fn get_method_list(&self) -> Array<Dictionary<Variant, Variant>>

pub fn property_can_revert(&self, property: impl AsArg<StringName>) -> bool

pub fn property_get_revert(&self, property: impl AsArg<StringName>) -> Variant

pub fn set_meta(&mut self, name: impl AsArg<StringName>, value: &Variant)

pub fn remove_meta(&mut self, name: impl AsArg<StringName>)

pub fn get_meta(&self, name: impl AsArg<StringName>) -> Variant

To set the default parameters, use Self::get_meta_ex and its builder methods. See the book for detailed usage instructions.

pub fn get_meta_ex<'ex>( &'ex self, name: impl AsArg<StringName> + 'ex, ) -> ExGetMeta<'ex>

pub fn has_meta(&self, name: impl AsArg<StringName>) -> bool

pub fn get_meta_list(&self) -> Array<StringName>

pub fn add_user_signal(&mut self, signal: impl AsArg<GString>)

To set the default parameters, use Self::add_user_signal_ex and its builder methods. See the book for detailed usage instructions.

pub fn add_user_signal_ex<'ex>( &'ex mut self, signal: impl AsArg<GString> + 'ex, ) -> ExAddUserSignal<'ex>

pub fn has_user_signal(&self, signal: impl AsArg<StringName>) -> bool

pub fn remove_user_signal(&mut self, signal: impl AsArg<StringName>)

pub fn emit_signal( &mut self, signal: impl AsArg<StringName>, varargs: &[Variant], ) -> Error

§Panics

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will panic in such a case.

pub fn try_emit_signal( &mut self, signal: impl AsArg<StringName>, varargs: &[Variant], ) -> Result<Error, CallError>

§Return type

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will return Err in such a case.

pub fn call( &mut self, method: impl AsArg<StringName>, varargs: &[Variant], ) -> Variant

§Panics

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will panic in such a case.

pub fn try_call( &mut self, method: impl AsArg<StringName>, varargs: &[Variant], ) -> Result<Variant, CallError>

§Return type

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will return Err in such a case.

pub fn call_deferred( &mut self, method: impl AsArg<StringName>, varargs: &[Variant], ) -> Variant

§Panics

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will panic in such a case.

pub fn try_call_deferred( &mut self, method: impl AsArg<StringName>, varargs: &[Variant], ) -> Result<Variant, CallError>

§Return type

This is a varcall method, meaning parameters and return values are passed as Variant. It can detect call failures and will return Err in such a case.

pub fn set_deferred( &mut self, property: impl AsArg<StringName>, value: &Variant, )

pub fn callv( &mut self, method: impl AsArg<StringName>, arg_array: &AnyArray, ) -> Variant

pub fn has_method(&self, method: impl AsArg<StringName>) -> bool

pub fn get_method_argument_count(&self, method: impl AsArg<StringName>) -> i32

pub fn has_signal(&self, signal: impl AsArg<StringName>) -> bool

pub fn get_signal_list(&self) -> Array<Dictionary<Variant, Variant>>

pub fn get_signal_connection_list( &self, signal: impl AsArg<StringName>, ) -> Array<Dictionary<Variant, Variant>>

pub fn get_incoming_connections(&self) -> Array<Dictionary<Variant, Variant>>

pub fn disconnect( &mut self, signal: impl AsArg<StringName>, callable: &Callable, )

pub fn is_connected( &self, signal: impl AsArg<StringName>, callable: &Callable, ) -> bool

pub fn has_connections(&self, signal: impl AsArg<StringName>) -> bool

pub fn set_block_signals(&mut self, enable: bool)

pub fn is_blocking_signals(&self) -> bool

pub fn notify_property_list_changed(&mut self)

pub fn set_message_translation(&mut self, enable: bool)

pub fn can_translate_messages(&self) -> bool

pub fn tr(&self, message: impl AsArg<StringName>) -> GString

To set the default parameters, use Self::tr_ex and its builder methods. See the book for detailed usage instructions.

pub fn tr_ex<'ex>(&'ex self, message: impl AsArg<StringName> + 'ex) -> ExTr<'ex>

pub fn tr_n( &self, message: impl AsArg<StringName>, plural_message: impl AsArg<StringName>, n: i32, ) -> GString

To set the default parameters, use Self::tr_n_ex and its builder methods. See the book for detailed usage instructions.

pub fn tr_n_ex<'ex>( &'ex self, message: impl AsArg<StringName> + 'ex, plural_message: impl AsArg<StringName> + 'ex, n: i32, ) -> ExTrN<'ex>

pub fn get_translation_domain(&self) -> StringName

pub fn set_translation_domain(&mut self, domain: impl AsArg<StringName>)

pub fn is_queued_for_deletion(&self) -> bool

pub fn cancel_free(&mut self)

pub fn notify(&mut self, what: ObjectNotification)

⚠️ Sends a Godot notification to all classes inherited by the object.

Triggers calls to on_notification(), and depending on the notification, also to Godot’s lifecycle callbacks such as ready().

Starts from the highest ancestor (the Object class) and goes down the hierarchy. See also Godot docs for Object::notification().

§Panics

If you call this method on a user-defined object while holding a GdRef or GdMut guard on the instance, you will encounter a panic. The reason is that the receiving virtual method on_notification() acquires a GdMut lock dynamically, which must be exclusive.