The Pause Handler: Working around Godot 4’s particle jitter bug

class_name GGPauseHandler
extends Node

## The pause component allows you to toggle the game.
##
## While paused, it will hide particle effects to prevent visual jitter.
## The issue is present in Godot 4 (tested until 4.0.2).
##
## @tutorial(Github Issue #50824: Particle jitter on low speed scale or when the SceneTree is paused due to interpolation): https://github.com/godotengine/godot/issues/50824


signal pause_toggled(paused: bool)

## The nodes' meta data field used to keep state
const META_FIELD = "gg_pause"

## This game node will have its [member Node.process_mode] adjusted to pause the game
@export var game: Node

## The action name (in the [InputMap]) for pausing the game.
@export var pause_action_name: String = "pause"

## Hides/unhides particles when toggling to prevent jitter
@export var hide_particles: bool = true


func _ready():
	assert(game is Node, "Must specify the node that will be paused")
	assert(InputMap.has_action(pause_action_name), "Please ensure the action '%s' is configured (Project Settings..., Input Map)" % pause_action_name)


## Pragmatic way to listen to [InputEvent]s and check whether the pause key/button was pressed
func _input(event: InputEvent):
	if event is InputEventKey and event.is_action_pressed(pause_action_name):
		toggle_pause()


## Toggle pause
func toggle_pause():
	if game.process_mode == PROCESS_MODE_INHERIT:
		if hide_particles:
			_hide_particles()
		pause_toggled.emit(true)
		game.process_mode = PROCESS_MODE_DISABLED
	else:
		if hide_particles:
			_show_particles()
		pause_toggled.emit(false)
		game.process_mode = Node.PROCESS_MODE_INHERIT


## Find and hide all GPUParticle2D effects
func _hide_particles():
	for node in get_tree().root.find_children("*", "GPUParticles2D", true, false):
		node.set_meta(META_FIELD, node.visible)
		node.visible = false


## Restore visibility of all previously hidden GPUParticle2D effects
func _show_particles():
	for node in get_tree().root.find_children("*", "GPUParticles2D", true, false):
		if node.has_meta(META_FIELD):
			node.visible = node.get_meta(META_FIELD)
			node.remove_meta(META_FIELD)