rimlike/scenes/pawn/pawn.gd

extends Node2D
## Pawn entity — grid-snapped, sim-tick-driven movement with smooth render lerp.
##
## Movement model (docs/architecture.md "Pawn movement"):
##   At 1× speed, crossing one tile costs STEP_TICKS sim ticks (10 ticks = 0.5 s
##   at 20 Hz). Each sim tick advances _step_progress by 1/STEP_TICKS. When
##   progress reaches 1.0 the pawn snaps to the next waypoint.
##
## Speed scaling is free: Pause → no ticks → pawn frozen; Ultra → 12× ticks/s →
## pawn crosses the map in ~7 s real time. No per-pawn speed handling needed.
##
## Render: _process() lerps world-position between current and next tile every
## render frame at 60 Hz — motion is smooth even at low sim Hz.
##
## Phase 3 additions:
##   - `forced_job` slot (player override via Selection)
##   - `job_runner` Node child wired externally by the World scene
##   - On each sim tick: orchestrate AI first (Decision → JobRunner.tick), then
##     advance the walk. The walk is still owned by the Pawn — JobRunner's WALK
##     toil delegates to `walk_along_path()` and listens for `walk_completed`.
##   - to_dict() / from_dict() round-trip the entire mid-walk + mid-toil state
##     (architecture.md "Save format" — mid-tick suspend safe).

class_name Pawn

const STEP_TICKS: int = 10
const TILE_SIZE_PX: int = 16  # Mirrors World.TILE_SIZE_PX; standalone so Pawn needs no World reference.

signal walk_started
signal walk_completed
signal arrived_at_destination(tile: Vector2i)

@export var pawn_name: String = ""

var tile: Vector2i = Vector2i.ZERO

# Player override slot — set by Selection; consumed by Decision on next sim tick.
# Untyped to dodge the autoload-class-name-ordering trap (Phase 2 gotcha).
var forced_job = null

# JobRunner node ref. Set externally by World during pawn spawn (so the runner
# can be paired with the pathfinder). May be null in tests / pre-Phase-3 scenes.
var job_runner = null

var _path: Array[Vector2i] = []
var _step_progress: float = 0.0
var _selected: bool = false

@onready var _name_label: Label = $NameLabel
@onready var _state_label: Label = $StateLabel


func _ready() -> void:
	EventBus.sim_tick.connect(_on_sim_tick)
	_state_label.text = Strings.t(&"pawn.state.idle")


func setup(p_name: String, start_tile: Vector2i) -> void:
	pawn_name = p_name
	tile = start_tile
	position = _tile_to_world(tile)
	_name_label.text = pawn_name
	_state_label.text = Strings.t(&"pawn.state.idle")
	Audit.log("pawn", "%s spawned at %s" % [pawn_name, start_tile])


# ── public API ──────────────────────────────────────────────────────────────

func walk_along_path(new_path: Array[Vector2i]) -> void:
	if new_path.is_empty():
		return
	var was_walking := is_walking()
	_path = new_path.duplicate()
	# _step_progress carries over; when it hits 1.0 the pawn snaps to
	# the first tile of the new path and picks up the new direction.
	if not was_walking:
		walk_started.emit()
		_state_label.text = Strings.t(&"pawn.state.walking")
	Audit.log("pawn", "%s walk path len %d → %s" % [pawn_name, new_path.size(), new_path[-1]])


func is_walking() -> bool:
	return not _path.is_empty()


func set_selected(value: bool) -> void:
	if _selected == value:
		return
	_selected = value
	queue_redraw()


func is_selected() -> bool:
	return _selected


# ── save / load ─────────────────────────────────────────────────────────────

func to_dict() -> Dictionary:
	var path_data: Array = []
	for v in _path:
		path_data.append([v.x, v.y])
	return {
		"name": pawn_name,
		"tile_x": tile.x,
		"tile_y": tile.y,
		"path": path_data,
		"step_progress": _step_progress,
		"selected": _selected,
		"forced_job": forced_job.to_dict() if forced_job != null else null,
		"job_runner": job_runner.to_dict() if job_runner != null else null,
	}


func from_dict(d: Dictionary) -> void:
	pawn_name = d.get("name", "")
	tile = Vector2i(int(d.get("tile_x", 0)), int(d.get("tile_y", 0)))

	_path.clear()
	for entry in d.get("path", []):
		if entry is Array and entry.size() == 2:
			_path.append(Vector2i(int(entry[0]), int(entry[1])))
	_step_progress = float(d.get("step_progress", 0.0))
	_selected = bool(d.get("selected", false))

	var fj_dict: Variant = d.get("forced_job")
	forced_job = Job.from_dict(fj_dict) if fj_dict is Dictionary else null

	var jr_dict: Variant = d.get("job_runner")
	if jr_dict is Dictionary and job_runner != null:
		job_runner.from_dict(jr_dict)

	_name_label.text = pawn_name
	_state_label.text = Strings.t(&"pawn.state.walking") if is_walking() else Strings.t(&"pawn.state.idle")
	position = _tile_to_world(tile)
	queue_redraw()
	Audit.log("pawn", "%s restored at %s (walking=%s, path len=%d)" % [pawn_name, tile, is_walking(), _path.size()])


# ── sim tick: orchestrate AI, then advance walk ─────────────────────────────

func _on_sim_tick(_tick_number: int) -> void:
	_orchestrate_ai()
	_advance_walk()


func _orchestrate_ai() -> void:
	# Phase 3: ask Decision for a job when the pawn is idle OR when a forced job
	# is queued (forced_job preempts the current job — player override semantics).
	# Decision's layer 2 consumes the forced_job slot; layer 4 falls back to work
	# providers when no override is queued.
	if job_runner == null:
		return
	if forced_job != null or not job_runner.has_job():
		var next_job = Decision.pick_next_job(self, World.work_providers)
		if next_job != null:
			job_runner.start_job(next_job)
	# Tick the runner (a freshly-started job's first toil executes here in the
	# same sim tick — WALK calls pawn.walk_along_path so _advance_walk below
	# immediately starts moving on this tick).
	if job_runner.has_job():
		job_runner.tick()


func _advance_walk() -> void:
	if not is_walking():
		return
	_step_progress += 1.0 / float(STEP_TICKS)
	if _step_progress >= 1.0:
		tile = _path[0]
		_path.remove_at(0)
		_step_progress = 0.0
		if _path.is_empty():
			_state_label.text = Strings.t(&"pawn.state.idle")
			walk_completed.emit()
			arrived_at_destination.emit(tile)
			Audit.log("pawn", "%s arrived at %s" % [pawn_name, tile])


# ── render ──────────────────────────────────────────────────────────────────

func _process(_delta: float) -> void:
	var from_world := _tile_to_world(tile)
	var next := _path[0] if is_walking() else tile
	var to_world := _tile_to_world(next)
	position = from_world.lerp(to_world, _step_progress)


func _draw() -> void:
	# Body disc — colour derived deterministically from pawn name so each pawn
	# is visually distinct without any art dependency.
	var hue := float(pawn_name.hash() % 360) / 360.0
	var body_colour := Color.from_hsv(hue, 0.7, 0.85)

	draw_circle(Vector2.ZERO, 6.0, body_colour)

	# Dark outline ring.
	draw_arc(Vector2.ZERO, 7.0, 0.0, TAU, 24, Color(0.0, 0.0, 0.0, 0.6), 1.0)

	# Selection ring.
	if _selected:
		draw_arc(Vector2.ZERO, 10.0, 0.0, TAU, 32, Color(1.0, 0.9, 0.2, 0.85), 2.0)


# ── helpers ─────────────────────────────────────────────────────────────────

func _tile_to_world(t: Vector2i) -> Vector2:
	return Vector2(
		t.x * TILE_SIZE_PX + TILE_SIZE_PX / 2.0,
		t.y * TILE_SIZE_PX + TILE_SIZE_PX / 2.0
	)