class_name MetaScreen
extends Control
## Base class for all meta-UI screens (#618, #680).
## Scene-root screens (main_menu, character_creation) extend this for the
## lifecycle contract. Overlay screens (settings, debug_console, bug_report,
## loading_screen) extend this AND push onto MetaStack.

signal closed
signal escape_pressed

enum Phase { HIDDEN, OPENING, OPEN, CLOSING }

@export var pauses_sim: bool = false
@export var closable_by_escape: bool = true
@export var captures_input: bool = true

var _phase: Phase = Phase.HIDDEN


func open() -> void:
	if _phase != Phase.HIDDEN:
		return
	_phase = Phase.OPENING
	visible = true
	if captures_input:
		mouse_filter = Control.MOUSE_FILTER_STOP
	on_open()
	_phase = Phase.OPEN


func close() -> void:
	if _phase != Phase.OPEN:
		return
	_phase = Phase.CLOSING
	on_close()
	visible = false
	_phase = Phase.HIDDEN
	closed.emit()


func is_open() -> bool:
	return _phase == Phase.OPEN


## Called by MetaStack when ESC is pressed with this screen on top.
## Return true to consume the event (prevent stack pop); false to allow pop.
func on_escape() -> bool:
	escape_pressed.emit()
	return false


# --- Lifecycle hooks — subclasses override ---


func on_open() -> void:
	pass


func on_close() -> void:
	pass