feat: add versioned simulation state records

tests/simulation_state_serialization_test.gd

@@ -0,0 +1,127 @@
+extends SceneTree
+
+var failures: Array[String] = []
+
+func _initialize() -> void:
+	call_deferred("_run")
+
+func _run() -> void:
+	await _test_deterministic_continuation()
+	await _test_resource_state_round_trip()
+	_test_schema_rejection()
+
+	if failures.is_empty():
+		print("[TEST] Simulation state serialization passed")
+		quit(0)
+		return
+
+	for failure in failures:
+		push_error("[TEST] " + failure)
+	quit(1)
+
+func _test_deterministic_continuation() -> void:
+	var uninterrupted := _create_manager(91234)
+	_advance_scenario(uninterrupted, 24)
+	uninterrupted.clock.advance(0.5)
+	_advance_scenario(uninterrupted, 24)
+	var uninterrupted_checksum: String = uninterrupted.get_state_checksum()
+
+	var before_save := _create_manager(91234)
+	_advance_scenario(before_save, 24)
+	before_save.clock.advance(0.5)
+	var saved_json: String = before_save.serialize_state()
+
+	var restored := _create_manager(1)
+	_check(
+		restored.restore_state_from_json(saved_json),
+		"A valid versioned state should restore into a fresh manager"
+	)
+	_check(restored.tick_count == 24, "Tick count should survive restoration")
+	_check(
+		is_equal_approx(restored.clock.accumulator, 0.5),
+		"Clock remainder should survive restoration"
+	)
+	_advance_scenario(restored, 24)
+	var restored_checksum: String = restored.get_state_checksum()
+	if restored_checksum != uninterrupted_checksum:
+		print(
+			"[TEST] uninterrupted=",
+			uninterrupted.serialize_state(),
+			"\n[TEST] restored=",
+			restored.serialize_state()
+		)
+	_check(
+		restored_checksum == uninterrupted_checksum,
+		"Restored simulation should match uninterrupted deterministic continuation"
+	)
+
+	uninterrupted.free()
+	before_save.free()
+	restored.free()
+
+func _test_resource_state_round_trip() -> void:
+	var resource: ResourceNode = load(
+		"res://world/resource_nodes/ResourceNode.tscn"
+	).instantiate()
+	resource.node_id = &"SerializationTestBerry"
+	resource.amount_remaining = 9.0
+	resource.yield_per_action = 2.0
+	root.add_child(resource)
+	await process_frame
+
+	_check(resource.reserve(42), "Resource should accept the test reservation")
+	resource.extract()
+
+	var manager := _create_manager(77)
+	var saved_json: String = manager.serialize_state()
+	resource.extract(5.0)
+	resource.release(42)
+	resource.enabled = false
+
+	_check(
+		manager.restore_state_from_json(saved_json),
+		"Resource state should restore with the simulation record"
+	)
+	_check(
+		is_equal_approx(resource.amount_remaining, 7.0),
+		"Resource amount should round-trip"
+	)
+	_check(resource.reserved_by == 42, "Resource reservation should round-trip")
+	_check(resource.enabled, "Resource enabled state should round-trip")
+
+	manager.free()
+	resource.free()
+
+func _test_schema_rejection() -> void:
+	var unsupported := JSON.stringify({
+		"schema": SimulationStateRecord.SCHEMA_NAME,
+		"schema_version": 999
+	})
+	_check(
+		SimulationStateRecord.from_json(unsupported) == null,
+		"Unsupported schema versions should be rejected"
+	)
+	_check(
+		SimulationStateRecord.from_json("[]") == null,
+		"Non-record JSON should be rejected"
+	)
+
+func _create_manager(seed_value: int) -> Node:
+	var manager: Node = load("res://simulation/SimulationManager.gd").new()
+	manager.simulation_seed = seed_value
+	manager.debug_logs = false
+	root.add_child(manager)
+	manager.set_process(false)
+	return manager
+
+func _advance_scenario(manager: Node, steps: int) -> void:
+	for step in steps:
+		manager.simulate_tick()
+		for npc in manager.npcs:
+			manager.get_wander_offset(npc.id)
+			if npc.task_state == SimNPC.TASK_STATE_TRAVELING:
+				manager.notify_npc_arrived(npc.id)
+
+func _check(condition: bool, message: String) -> void:
+	if not condition:
+		failures.append(message)

tests/simulation_state_serialization_test.gd.uid

@@ -0,0 +1 @@
+uid://5c7luv7p1odh