settled-reach/client/scripts/rendering/entity_renderer.gd

class_name EntityRenderer
extends Node2D

# Entity renderer — manages entity sprites under the Entities node
# Creates/updates/removes Sprite2D children based on entity data
# Entity format (from Protocol v2): {entity_id, x, y, z, kind: {variant, data}, visibility}
#
# Position lerping: entity sprites smoothly slide between tiles instead of snapping.
# The server moves entities in discrete tile steps; the lerp makes this look fluid.
# Speed is tuned so Sprint feels snappy and Walk/Careful/Crouch feel deliberate.
#
# D-033 colors: Phase 1 defaults by entity kind. Phase 2 (#361) will derive
# color from RelationshipState via the knowledge graph.
# #540: Sprites at D-019 angle (-72.5° from horizontal). Textures are neutral greyscale;
# self_modulate applies D-033 relationship tinting. modulate.a reserved for D-015 dimming.

const TILE_SIZE: int = Constants.TILE_SIZE
# D-044: 24x32 entity footprint within 32x32 visual tile (64x64 source at 0.5 scale = 32px runtime)
const ENTITY_WIDTH: int = 24
const ENTITY_HEIGHT: int = 32
const ENTITY_OFFSET_X: float = 0.0                        # sprite fills tile width at 0.5 scale
const ENTITY_OFFSET_Y: float = TILE_SIZE - ENTITY_HEIGHT  # feet-anchored for correct y-sort with D-019 tilt

# Lerp speed — framerate-independent exponential smoothing.
# At 12.0: ~70% there after 0.1s, ~95% after 0.25s.
# Fast enough for Sprint snappiness, slow enough for Walk to show sliding.
const LERP_SPEED: float = 12.0

var entity_nodes: Dictionary = {}    # entity_id -> Node2D
var _entity_targets: Dictionary = {} # entity_id -> Vector2 (target pixel position)
var _entity_relationships: Dictionary = {}  # #521: entity_id -> String (last relationship)
var _entity_tweens: Dictionary = {}  # #521: entity_id -> {from: Color, target: Color, elapsed: float}
var _entity_facing: Dictionary = {}  # #540: entity_id -> String ("north"/"east"/"south"/"west")

# #521: Color transition duration in seconds (D-033: "0.5s fade")
const COLOR_FADE_DURATION: float = 0.5

func _ready() -> void:
	print("EntityRenderer: Initialized")


func _process(delta: float) -> void:
	# Lerp all entity visual positions toward their targets each frame.
	# Uses framerate-independent exponential smoothing.
	var weight := 1.0 - exp(-LERP_SPEED * delta)
	for entity_id in entity_nodes.keys():
		if not _entity_targets.has(entity_id):
			continue
		var node = entity_nodes[entity_id]
		var target: Vector2 = _entity_targets[entity_id]
		if not node.position.is_equal_approx(target):
			node.position = node.position.lerp(target, weight)

	# #521: Advance self_modulate transitions (manual lerp, testable without SceneTree)
	var finished_ids: Array = []
	for entity_id in _entity_tweens.keys():
		if not entity_nodes.has(entity_id):
			finished_ids.append(entity_id)
			continue
		var tween_data: Dictionary = _entity_tweens[entity_id]
		tween_data.elapsed += delta
		var t := clampf(tween_data.elapsed / COLOR_FADE_DURATION, 0.0, 1.0)
		var node_s: Sprite2D = entity_nodes[entity_id] as Sprite2D
		if node_s:
			node_s.self_modulate = tween_data.from.lerp(tween_data.target, t)
		if t >= 1.0:
			finished_ids.append(entity_id)
	for eid in finished_ids:
		_entity_tweens.erase(eid)


# Update entities from snapshot data
func update_entities(entities: Array) -> void:
	var active_ids: Array = []

	# Create or update entities
	for entity_data in entities:
		if not entity_data.has("entity_id"):
			continue

		var entity_id = entity_data.entity_id
		active_ids.append(entity_id)

		# Create entity node if it doesn't exist
		if not entity_nodes.has(entity_id):
			_create_entity_node(entity_id, entity_data)
		else:
			_update_entity_node(entity_id, entity_data)

	# Remove entities that are no longer visible
	var ids_to_remove: Array = []
	for entity_id in entity_nodes.keys():
		if entity_id not in active_ids:
			ids_to_remove.append(entity_id)

	for entity_id in ids_to_remove:
		_remove_entity_node(entity_id)


# Create a new entity node with D-033 tint and sprite texture at D-019 angle
func _create_entity_node(entity_id: int, entity_data: Dictionary) -> void:
	var entity_node := Sprite2D.new()
	entity_node.name = "Entity_" + str(entity_id)
	# centered=false: top-left origin aligns with tile grid.
	# scale=0.5: maps 64px source texture to 32px runtime (D-043, 2x camera = 64px on screen).
	entity_node.centered = false
	entity_node.scale = Vector2(0.5, 0.5)

	# Load sprite for current facing direction
	var direction := _entity_direction(entity_id, entity_data)
	_entity_facing[entity_id] = direction
	var tex := _load_sprite_texture(direction)
	if tex == null:
		push_error("EntityRenderer: no texture for entity %d direction '%s' — entity will be invisible" % [entity_id, direction])
	entity_node.texture = tex

	# D-033: self_modulate for relationship tinting; modulate.a is reserved for D-015 dimming.
	entity_node.self_modulate = _color_for_kind(entity_data)

	add_child(entity_node)
	entity_nodes[entity_id] = entity_node
	_entity_relationships[entity_id] = entity_data.get("relationship", "Unknown")

	# Add facing indicator for the player entity
	if entity_id == GameState.player_entity_id:
		_add_facing_indicator(entity_node)

	# Snap to initial position (no lerp on first appearance)
	if entity_data.has("x") and entity_data.has("y"):
		var target := Vector2(
			floorf(entity_data.x) * TILE_SIZE + ENTITY_OFFSET_X,
			floorf(entity_data.y) * TILE_SIZE + ENTITY_OFFSET_Y
		)
		entity_node.position = target
		_entity_targets[entity_id] = target

	_update_entity_node(entity_id, entity_data)


# Update an existing entity node (target position, sprite direction, visibility dimming, facing)
func _update_entity_node(entity_id: int, entity_data: Dictionary) -> void:
	if not entity_nodes.has(entity_id):
		return

	var node = entity_nodes[entity_id]

	# Update target position — the lerp in _process() will smoothly move there.
	# Server sends tile-center coords (tile 16 → 16.5), floor to get tile index.
	if entity_data.has("x") and entity_data.has("y"):
		_entity_targets[entity_id] = Vector2(
			floorf(entity_data.x) * TILE_SIZE + ENTITY_OFFSET_X,
			floorf(entity_data.y) * TILE_SIZE + ENTITY_OFFSET_Y
		)

	# #540: Update sprite texture when facing direction changes
	var new_dir := _entity_direction(entity_id, entity_data)
	if new_dir != _entity_facing.get(entity_id, ""):
		_entity_facing[entity_id] = new_dir
		var new_tex := _load_sprite_texture(new_dir)
		if new_tex != null:
			(node as Sprite2D).texture = new_tex
		# null: keep previous texture rather than going invisible mid-game

	# #521: Detect relationship change → fade D-033 self_modulate (0.5s via _process)
	var new_rel: String = entity_data.get("relationship", "Unknown")
	if new_rel != _entity_relationships.get(entity_id, "Unknown"):
		_entity_relationships[entity_id] = new_rel
		_entity_tweens[entity_id] = {
			"from": (node as Sprite2D).self_modulate,
			"target": _color_for_kind(entity_data),
			"elapsed": 0.0,
		}

	# D-015: Peripheral vision dimming via modulate.a.
	# Independent from self_modulate (D-033 tint) — both can change simultaneously.
	var visibility: Variant = entity_data.get("visibility")
	var target_alpha := Constants.PERIPHERAL_ALPHA if visibility == "Peripheral" else 1.0
	if not is_equal_approx(node.modulate.a, target_alpha):
		node.modulate.a = target_alpha

	# D-054: Update facing indicator from client-side mouse angle (not server).
	# InputMapper.facing_angle is a continuous float — smoother than octant snapping.
	if entity_id == GameState.player_entity_id:
		var indicator = node.get_node_or_null("FacingIndicator")
		if indicator != null:
			# facing_angle: 0=East, -PI/2=North. Indicator: 0=North (up).
			# Rotate from North basis: add PI/2 to convert.
			indicator.rotation = InputMapper.facing_angle + PI / 2.0


# Remove an entity node
func _remove_entity_node(entity_id: int) -> void:
	if not entity_nodes.has(entity_id):
		return

	var entity_node = entity_nodes[entity_id]
	entity_node.queue_free()
	entity_nodes.erase(entity_id)
	_entity_targets.erase(entity_id)
	_entity_relationships.erase(entity_id)
	_entity_tweens.erase(entity_id)
	_entity_facing.erase(entity_id)


# D-033 color by entity kind — delegates to Constants.color_for_entity_kind
static func _color_for_kind(entity_data: Dictionary) -> Color:
	return Constants.color_for_entity_kind(entity_data)


# #540: Map entity to current 4-direction sprite key.
# Player uses GameState.player_facing (8-octant → 4-cardinal). NPCs default "south".
func _entity_direction(entity_id: int, _entity_data: Dictionary) -> String:
	if entity_id == GameState.player_entity_id:
		return _octant_to_direction(GameState.player_facing)
	# NPCs: no facing field in v1 entity format; south is viewer-facing (D-019 angle)
	return "south"


# Map 8-direction octant string to nearest 4-direction sprite key.
# N/NW → north, NE/E → east, SE/S → south, SW/W → west
static func _octant_to_direction(octant: String) -> String:
	match octant:
		"North", "Northwest": return "north"
		"Northeast", "East": return "east"
		"Southeast", "South": return "south"
		"Southwest", "West": return "west"
		_:
			push_warning("EntityRenderer: unrecognised octant '%s' — defaulting to south" % octant)
			return "south"


# Load the sprite texture for the given 4-direction key.
# Falls back to null with a push_warning if the asset is missing.
static func _load_sprite_texture(direction: String) -> Texture2D:
	var path := "res://assets/sprites/npc_generic_%s_64.png" % direction
	if ResourceLoader.exists(path):
		return load(path) as Texture2D
	push_warning("EntityRenderer: sprite not found: %s" % path)
	return null


# Add a facing direction indicator triangle to the player entity.
# Indicator position is in Sprite2D local space (64px texture before 0.5 scale → center at (32,32)).
func _add_facing_indicator(parent_node: Node2D) -> void:
	var indicator := Polygon2D.new()
	indicator.name = "FacingIndicator"
	var s := Constants.FACING_INDICATOR_SIZE
	var offset := Constants.FACING_INDICATOR_OFFSET
	# Triangle pointing up (North), offset from center. Rotates around (0,0).
	indicator.polygon = PackedVector2Array([
		Vector2(0, -offset - s),
		Vector2(-s * 0.6, -offset + s * 0.4),
		Vector2(s * 0.6, -offset + s * 0.4),
	])
	indicator.color = Constants.ENTITY_COLOR_PLAYER
	# Sprite2D local space: 64px texture at scale 0.5 → center of visible sprite at (32,32).
	# Indicator rotates around this point to track player facing direction.
	indicator.position = Vector2(32.0, 32.0)
	parent_node.add_child(indicator)