settled-reach/client/ui/monologue_display.gd

extends Control

# Internal monologue display — multi-line, priority-queued (per D-016, #122).
# Per Tyre architecture review, Sprint 14.
#
# Up to MAX_VISIBLE lines display simultaneously in a VBoxContainer.
# Additional arrivals queue up to MAX_QUEUE depth; lowest-priority entry is
# dropped when the queue is full and a higher-priority line arrives.
#
# Stagger: 0.15s minimum gap between consecutive fade-ins (spec §5.4).
# Colour: derived from GameState.lattice_profile at render time (D-032).
# is_urgent=true → opacity 1.0 and elevated colour variant (bloom deferred).

const MAX_VISIBLE: int = 3
const MAX_QUEUE:   int = 5

const STAGGER_SEC:  float = 0.15
const FADE_IN_SEC:  float = 0.3
const FADE_OUT_SEC: float = 0.5

# Lattice colour palette — keyed by GameState.lattice_profile.
# standard opacity = 0.85, urgent opacity = 1.0.
# Source: Tyre architecture review, Sprint 14.
const _LATTICE_COLORS: Dictionary = {
	"lattice_augmented": {  # detective
		"standard": Color("#d0d4e0"),
		"urgent":   Color("#e0e8f8"),
	},
	"lattice_baseline": {  # smuggler
		"standard": Color("#d8d0c4"),
		"urgent":   Color("#f0e4d4"),
	},
}
const _FALLBACK_STANDARD: Color = Color("#c8d0e0")
const _FALLBACK_URGENT:   Color = Color("#e0e8f8")

@onready var _vbox: VBoxContainer = $VBoxContainer

# Visible slot: {node: Control, expire_timer: float, priority: int, tween: Tween}
var _visible: Array[Dictionary] = []
# Queue entry: {text: String, duration: float, priority: int, is_urgent: bool}
var _queue: Array[Dictionary] = []
# Msec timestamp when the next fade-in may begin (stagger enforcement)
var _next_fade_in_msec: float = 0.0


func _ready() -> void:
	pass


func _process(delta: float) -> void:
	# Expire visible lines
	for slot in _visible.duplicate():
		slot.expire_timer -= delta
		if slot.expire_timer <= 0.0:
			_retire_slot(slot)

	# Drain queue into available visible slots (one per stagger interval)
	if not _queue.is_empty() and _visible.size() < MAX_VISIBLE:
		var now := float(Time.get_ticks_msec())
		if now >= _next_fade_in_msec:
			var next: Dictionary = _queue.pop_front()
			_show_line(next.text, next.duration, next.priority, next.is_urgent)


# Display a monologue line.
# priority: higher number = more important (default 2; urgent beats normal).
# is_urgent: visual flag — full opacity + elevated colour. Bloom deferred.
# Empty text is silently ignored — no slot created, no queue entry.
func show_monologue(text: String, duration: float, priority: int = 2, is_urgent: bool = false) -> void:
	if text.is_empty():
		return
	var now := float(Time.get_ticks_msec())
	if _visible.size() < MAX_VISIBLE and now >= _next_fade_in_msec:
		_show_line(text, duration, priority, is_urgent)
	else:
		_enqueue(text, duration, priority, is_urgent)


# ---------------------------------------------------------------------------
# Internal
# ---------------------------------------------------------------------------

func _show_line(text: String, duration: float, priority: int, is_urgent: bool) -> void:
	var line_node := _build_line_node(text, is_urgent)
	_vbox.add_child(line_node)

	var slot := {
		node         = line_node,
		expire_timer = duration,
		priority     = priority,
		tween        = null as Tween,
	}
	_visible.append(slot)
	_next_fade_in_msec = float(Time.get_ticks_msec()) + STAGGER_SEC * 1000.0

	line_node.modulate.a = 0.0
	var tween := create_tween()
	slot.tween = tween
	var target_opacity := 1.0 if is_urgent else 0.85
	tween.tween_property(line_node, "modulate:a", target_opacity, FADE_IN_SEC)


func _retire_slot(slot: Dictionary) -> void:
	_visible.erase(slot)
	var node: Node = slot.node
	var t: Tween = slot.tween
	if t and t.is_valid():
		t.kill()
	var tween := create_tween()
	tween.tween_property(node, "modulate:a", 0.0, FADE_OUT_SEC)
	tween.tween_callback(node.queue_free)


func _enqueue(text: String, duration: float, priority: int, is_urgent: bool) -> void:
	if _queue.size() < MAX_QUEUE:
		_queue.append({text = text, duration = duration, priority = priority, is_urgent = is_urgent})
	else:
		# Replace the lowest-priority queued entry if new one outranks it
		var lowest := _lowest_priority_idx()
		if priority > _queue[lowest].priority:
			_queue[lowest] = {text = text, duration = duration, priority = priority, is_urgent = is_urgent}
		# else: incoming line is lower/equal priority — silently drop
	# Re-sort: highest priority at front (next to display)
	_queue.sort_custom(func(a: Dictionary, b: Dictionary) -> bool: return a.priority > b.priority)


func _lowest_priority_idx() -> int:
	var idx := 0
	for i in range(1, _queue.size()):
		if _queue[i].priority < _queue[idx].priority:
			idx = i
	return idx


func _build_line_node(text: String, is_urgent: bool) -> Control:
	var profile: String = GameState.lattice_profile
	var palette: Dictionary = _LATTICE_COLORS.get(profile, {})
	var color: Color = palette.get("urgent", _FALLBACK_URGENT) if is_urgent \
		else palette.get("standard", _FALLBACK_STANDARD)

	var container := MarginContainer.new()
	container.add_theme_constant_override("margin_left",   4)
	container.add_theme_constant_override("margin_right",  4)
	container.add_theme_constant_override("margin_top",    2)
	container.add_theme_constant_override("margin_bottom", 2)

	var label := RichTextLabel.new()
	label.bbcode_enabled = true
	label.fit_content = true
	label.scroll_active = false
	label.add_theme_font_size_override("normal_font_size", 13)
	label.text = "[i][color=#%s]%s[/color][/i]" % [color.to_html(false), text]

	container.add_child(label)
	return container