ProjectileCaller2D

Inherits: Node2D < CanvasItem < Node < Object

An intermediary between your code and the AP engine.

Description

Provides indirect access to the AP engine. Holds and delegates the creation of projectiles.

ProjectileCaller2D nodes are essential in any entity that needs to spawn projectiles, such as players, enemies, or environmental hazards.

It also serves as a container for your ProjectileBlueprints.

Tutorials

Properties

bool	auto_add_projectiles_to_database	`true`
bool	get_projectile_copies_from_database	`true`
ProjectileProcessor2D	projectile_processor
Array[ProjectileBlueprint2D]	projectile_resources
Array[Projectile2D]	projectiles

Methods

bool	add_projectile_from_database
bool	add_projectile_modifier
void	append_projectiles_from_database
Projectile2D	get_projectile
ProjectileBlueprint2D	get_projectile_blueprint
void	reassign_projectiles_from_database
bool	remove_modifier_stacks_from_projectile
bool	remove_projectile_modifier
bool	request_projectile
bool	request_projectile_from_database
void	set_projectile
bool	set_projectile_from_database
bool	validate_proj
bool	validate_proj_processor
bool	validate_proj_resource
bool	validate_request
bool	verify_projectile_from_database

Property Descriptions

bool auto_add_projectiles_to_database = true

If true the ProjectileCaller2D Node will automatically add its unregistered projectiles to the Global Database; using its blueprint name as key.

bool get_projectile_copies_from_database = true

If true the ProjectileCaller2D Node will only get copies when requesting projectiles from the Global Database instead of direct references.

Consequently, any changes you make on them will not be reflected on the projectiles allocated on the Global Database itself.

ProjectileProcessor2D projectile_processor

Direct access to the AP engine itself.

You should not use it for direct projectile creation. Use the request_projectile method instead.

Array[ProjectileBlueprint2D] projectile_resources

List of all ProjectileBlueprint2D resources allocated on the ProjectileCaller2D.

Each element in the array is used to create its corresponding Projectile2D object in the projectiles array by the same index.

Array[Projectile2D] projectiles

List of all Projectile2D objects that can be directly created by the ProjectileCaller2D.

Each ProjectileCaller2D instance can only modify its own stored projectiles.

Method Descriptions

bool add_projectile_from_database(id: StringName, include_blueprints: bool = false)

Returns true on success.

Adds the projectile with key id from the Global Database to the end of its local projectiles array.

If include_blueprints is true, it also adds its ProjectileBlueprint2D counterpart to its projectile_resources array.

extends Node2D

@onready var projectile_caller: ProjectileCaller2D = $ProjectileCaller2D

func _ready() -> void:
	projectile_caller.add_projectile_from_database("MEGA_LASER")

bool add_projectile_modifier(index: int, modifier: Projectile2DModifier)

Returns true on success.

Adds a modifier to the projectile at the specified index of its local projectiles array.

projectile_caller.add_projectile_modifier(0, Projectile2DModifier.new("PROJ_BUFF", 1.0))
projectile_caller.add_projectile_modifier(0, APDatabase.get_projectile_2d_modifier("SEEKING_BUFF"))

void append_projectiles_from_database(names: Array, include_blueprints: bool = false)

Adds projectiles from the Global Database to the end of its local projectiles array.

If include_blueprints is true, it also adds its ProjectileBlueprint2D counterparts to its projectile_resources array.

extends Node2D

@onready var projectile_caller: ProjectileCaller2D = $ProjectileCaller2D

enum Spells{
	MAGIC_BOLT,
	SOUL_SEEKER,
	FIREBALL,
	ERUPTION,
	MEGA_LASER
}

func _ready() -> void:
	projectile_caller.append_projectiles_from_database(Spells.keys())

Projectile2D get_projectile(index: int)

Returns the projectile at the specified index of its local projectiles array.

Use it to change the properties and behaviors of your projectiles.

projectile_caller.get_projectile(0)

ProjectileBlueprint2D get_projectile_blueprint(index: int)

Returns the blueprint at the specified index of its local projectile_resources array.

projectile_caller.get_projectile_blueprint(0)

void reassign_projectiles_from_database(names: Array, include_blueprints: bool = false)

Replaces its entire projectiles array with projectiles from the Global Database.

If include_blueprints is true, it also replaces its ProjectileBlueprint2D counterparts at the projectile_resources array.

extends Node2D

@onready var projectile_caller: ProjectileCaller2D = $ProjectileCaller2D

enum Spells{
	MAGIC_BOLT,
	SOUL_SEEKER,
	FIREBALL,
	ERUPTION,
	MEGA_LASER
}

func _ready() -> void:
	projectile_caller.reassign_projectiles_from_database(Spells.keys())

bool remove_modifier_stacks_from_projectile(index: int, id: StringName, stacks: int = -1)

Returns true on success.

Removes a specific number of modifier stacks from the projectile at the specified index of its local projectiles array.

If stacks < 0, removes all stacks.

projectile_caller.remove_modifier_stacks_from_projectile(0, "PROJ_BUFF", 2)

bool remove_projectile_modifier(index: int, id: StringName)

Returns true on success.

Removes a modifier from the projectile at the specified index of its local projectiles array by id.

projectile_caller.remove_projectile_modifier(0, "PROJ_BUFF")

bool request_projectile (index: int, _position: Vector2, destination: Vector2, target: Node2D = null, move_method: Callable = Callable(), start_method: Callable = Callable(), collision_method: Callable = Callable(), expired_method: Callable = Callable())

Returns true if the creation request has been successful.

Takes the following arguments:

index: Element of the projectiles array that will be used by the AP engine.

position: Start position of the projectile (In global coordinates).

destination: Position the projectile will move towards (In global coordinates).

target: Optional Node2D the projectile will actively seek to (If selected in ProjectileBlueprint2D).

move_method: Optional Callable to overwrite the set on_move projectile property.

start_method: Optional Callable to overwrite the set on_start projectile property.

collision_method: Optional Callable to overwrite both on_area_collision and on_body_collision projectile properties.

expired_method: Optional Callable to overwrite the set on_expired projectile property.

Each Callable argument follows a define pattern and must take a set number of parameters and return a specific value.

The move_method callable must return a Vector2 (as an element representing the direction in which the projectile will move) and take the following two parameters:

proj: A representation of the projectile object to be changed.

delta: The time elapsed in seconds since the previous call to move_method.

extends Node2D

@onready var projectile_caller = $ProjectileCaller2D
						

# In this example the "custom_movement" function is passed as a Callable in the optional "move_method" parameter.
func _process(_delta):
	if Input.is_mouse_button_pressed(MOUSE_BUTTON_LEFT):
		var destination = get_global_mouse_position()
		projectile_caller.request_projectile(0, position, destination, null, custom_movement)


# This function will cause the projectile to always move in the UP direction.
func custom_movement(proj: Projectile2D, _delta: float) -> Vector2:
	return Vector2.UP

The start_method callable returns void and takes the following parameter:

proj: A representation of the projectile object to be changed.

extends Node2D

@onready var projectile_caller = $ProjectileCaller2D
						

# In this example the "custom_start" function is passed as a Callable in the optional "start_method" parameter.
func _process(_delta):
	if Input.is_mouse_button_pressed(MOUSE_BUTTON_LEFT):
		var destination = get_global_mouse_position()
		projectile_caller.request_projectile(0, position, destination, null, Callable(), custom_start)


# This function will change the projectile "speed" property at projectile creation.
func custom_start(proj: Projectile2D) -> void:
	proj.speed = 50

The collision_method callable returns void and takes the following parameters:

proj: A representation of the projectile object to be changed.

area_rid: The RID of the area/body that entered the projectile.

area_node: The Node of the area/body that entered the projectile.

target_node: The main processor Node of the object that collided with the projectile. Learn more here.

area_shape_index: Index of the interacting shape from the collidiong area/body.

local_shape_index: Index of the interacting shape from the projectile area.

extends Node2D

# The projectiles will immediately expire upon collision with objects in this layer.
@export_flags_2d_physics var wall_layer: int
@onready var projectile_caller = $ProjectileCaller2D
						

# In this example the "custom_collision" function is passed as a Callable in the optional "collision_method" parameter.
func _process(_delta):
	if Input.is_mouse_button_pressed(MOUSE_BUTTON_LEFT):
		var destination = get_global_mouse_position()
		projectile_caller.request_projectile(0, position, destination, null, Callable(), Callable(), custom_collision)


# This function will change the way projectiles collide.
func custom_collision(proj: Projectile2D, area_rid: RID, area_node: Node2D, target_node: Node2D, area_shape_index: int, local_shape_index: int) -> void:
	# The "validate_collision" method makes sure that:
	# -> The projectile is not expired.
	# -> A lock projectile will only collide with its assigned target.
	# -> The projectile is not colliding with areas/bodies it already collided.
	if not proj.validate_collision(area_rid, area_node):
		return
	
	# Custom code snippet for immediate expiration on collision with "wall_layer"
	if wall_layer & area_node.collision_layer != 0:
		proj.is_expired = true
		return
	
	# The "on_pierced" method makes sure that:
	# -> The projectile refreshes its rehit cooldown and angular speed.
	# -> The projectile appends colliding areas/bodies to its excluded targets.
	# -> The projectile instance reduces its remaining pierce.
	proj.on_pierced(area_rid)

The expired_method callable returns void and takes the following parameter:

proj: A representation of the projectile object to be changed.

extends Node2D

@onready var projectile_caller = $ProjectileCaller2D
						

# In this example the "custom_expired" function is passed as a Callable in the optional "expired_method" parameter.
func _process(_delta):
	if Input.is_mouse_button_pressed(MOUSE_BUTTON_LEFT):
		var destination = get_global_mouse_position()
		projectile_caller.request_projectile(0, position, destination, null, Callable(), Callable(), Callable(), custom_expired)


# This function will print "expired" on the console once the projectile runs out of pierce or lifetime.
func custom_expired(proj: Projectile2D) -> void:
	print("expired")

bool request_projectile_from_database(id: StringName, _position: Vector2, destination: Vector2, target: Node2D = null, move_method: Callable = Callable(), start_method: Callable = Callable(), collision_method: Callable = Callable(), expired_method: Callable = Callable())

Returns true if the creation request has been successful.

Requests the creation of the projectile with key id from the Global Database.

Parameters and requirements match those of request_projectile, but uses a database ID instead of a local index.

void set_projectile(index: int, projectile: Projectile2D, auto_assign_blueprint: bool = true)

Sets the given projectile at the specified index of its local projectiles array.

If auto_assign_blueprint is true it sets its blueprint to the same one its method index is replacing.

func _ready() -> void:
	# These two statements are the same
	projectile_manager.set_projectile(0, MyProjectile.new())
	projectile_manager.set_projectile(0, MyProjectile.new(projectile_manager.get_projectile_blueprint(0)))
    
	# Set it to "false" so it does not auto assing
	projectile_manager.set_projectile(0, MyProjectile.new(projectile_manager.get_projectile_blueprint(1)), false)

bool set_projectile_from_database(index: int, id: StringName, include_blueprints: bool = false)

Returns true on success.

Sets the element at the specified index in the projectiles array, to the projectile with key id from the Global Database.

If include_blueprints is true, it also sets its ProjectileBlueprint2D counterpart at the specified index of its projectile_resources array.

extends Node2D

@onready var projectile_caller: ProjectileCaller2D = $ProjectileCaller2D

func _ready() -> void:
	projectile_caller.set_projectile_from_database(4, "MEGA_LASER")

bool validate_proj(index: int)

Returns true if the projectile at the specified index of its local projectiles array can be spawned.

bool validate_proj_processor()

Returns true if there is a valid projectile_processor on scene.

Automatically creates one if none exists.

bool validate_proj_resource(index: int)

Returns true if the blueprint at the specified index of its local projectile_resources array can be used.

bool validate_request(index: int)

Returns true if the projectile at the specified index of its local projectiles array can be spawned on scene.

Checks both the projectile_processor and projectile validity.

bool verify_projectile_from_database(id: StringName)

Returns true if the Global Database has a registered projectile under key id.