Helpful functions

Introduction

Have you ever searched the Godot docs looking for a function and thinking "surely there has to be a function to..." only to not find what you're looking for? ProtoJam comes packed with a variety of commonly needed static functions to help fill that gap, including:

• Graceful shutdown
• Framerate independent lerps
• Time formatting
• and more...

Using CollectionUtils

The CollectionUtils class provides supplemental functions for Dictionary and Array.

filterd(dictionary, filter)

Returns a copy of a dictionary with only the filtered entries remaining similar to Array.filter. Returning true from the filter callable will retain the key/value pair it was called with.

var items: Dictionary[StringName, int] = {
	&"egg": 2,
	&"bullet": 20,
	&"herb": 0,
	&"key": -1,
}

# Remove egg items
var egg_filter: Callable = func(key: Variant, _value: Variant) -> bool:
	return &"egg" != key


# Prints { "bullet": 20, "herb": 0, "key": -1 }
print(CollectionUtils.filterd(items, egg_filter))

get_or_create(dictionary, key, callable)

Performs the same function as Dictionary.get_or_add(key, default) but defers to a callable to produce the default value. This is ideal for situations where the default value requires initialization beyond its construction or should not be constructed when not required.

var _npcs: Dictionary[String, NonPlayerCharacter] = {}

func _ready() -> void:
	CollectionUtils.get_or_add(_npcs, "blacksmith", _spawn_blacksmith) # Invokes _spawn_blacksmith and stores the result
	CollectionUtils.get_or_add(_npcs, "blacksmith", _spawn_blacksmith) # Returns the previously created blacksmith


func _spawn_blacksmith() -> NonPlayerCharacter:
	var npc: BlacksmithCharacter= BlacksmithCharacter.new()
	add_child(npc)
	return npc

remove_all(a, b)

Removes all entries from the first array that are also in the second array.

var a: Array[int] = [1, 2, 3, 4, 5]
var b: Array[int] = [2, 4]

# Prints [ 1, 3, 5 ]
print(CollectionUtils.remove_all(a, b))

Using NodeUtils

🚧 WIP

connect_descendant_signal(node, type, signal_name, callable, flags)

🚧 WIP

free_all_children(node)

🚧 WIP

focus_first_available(node)

🚧 WIP

get_tree()

🚧 WIP

quit_gracefully(exit_code)

🚧 WIP

Using PhysicsUtils

🚧 WIP

is_on_floor(max_floor_angle, state)

🚧 WIP

Using RandomUtils

🚧 WIP

pick_random(rng, array)

🚧 WIP

Using TimeUtils

The TimeUtils class provides various functions for working with units of time.

framerate_aware_lerp_weight(lambda, delta)

Lerp functions are commonly misused by passing delta time (or some product of it) as the weight parameter. While not intuitive, this actually creates a framerate-dependent lerp which will not be correct as the framerate changes. The correct way to make a framerate independent lerp requires an exponential curve.

This function makes the process simpler by hiding those details and simply returning a weight suitable for use with lerp.

func _physics_process(delta: float) -> void:
	# Wrong
	# velocity = velocity.lerp(Vector3.ZERO, delta)

	# Correct
	var rate: float = 1.0 # Adjust this to change the damping amount
	velocity = velocity.lerp(Vector3.ZERO, TimeUtils.framerate_aware_lerp_weight(rate, delta))

format_stopwatch(millis, full_precision)

Formats the given number of milliseconds into stopwatch format with either centisecond or millisecond precision.

var millis: int = 217195

# Prints 03:37:19
print(TimeUtils.format_stopwatch(millis))

# Prints 03:37:195
print(TimeUtils.format_stopwatch(millis, true))

minutes_to_millis(minutes)

Converts the given number of minutes to milliseconds.

seconds_to_millis(seconds)

Converts the given number of seconds to milliseconds.

minutes_to_centis(minutes)

Converts the given number of minutes to centiseconds.

seconds_to_centis(seconds)

Converts the given number of seconds to centiseconds.

millis_to_centis(millis)

Converts the given number of milliseconds to centiseconds.

millis_to_minutes(millis)

Converts the given number of milliseconds to minutes.

millis_to_seconds(millis)

Converts the given number of milliseconds to seconds.

centis_to_minutes(centis)

Converts the given number of centiseconds to minutes.

centis_to_seconds(centis)

Converts the given number of centiseconds to seconds.