feat: add provenance-aware npc communication

This commit is contained in:
Rijad Zuzo
2026-07-11 19:58:47 +02:00
parent 81409650df
commit 9a479ba182
18 changed files with 938 additions and 70 deletions
@@ -0,0 +1,298 @@
extends SceneTree
var failures: Array[String] = []
func _initialize() -> void:
call_deferred("_run")
func _run() -> void:
var manager := _create_manager()
var contributor: SimNPC = manager.npcs[0]
var witness: SimNPC = manager.npcs[1]
var listener: SimNPC = manager.npcs[2]
var control: SimNPC = manager.npcs[3]
contributor.position = Vector3.ZERO
witness.position = Vector3(4.0, 0.0, 0.0)
listener.position = Vector3(20.0, 0.0, 0.0)
control.position = Vector3(21.0, 0.0, 0.0)
for observer in [witness, listener, control]:
observer.hunger = 85.0
contributor.add_inventory(SimulationIds.RESOURCE_FOOD, 2.0)
_check(
is_equal_approx(
manager.economy.deposit_inventory(contributor, SimulationIds.RESOURCE_FOOD), 2.0
),
"Communication should begin from a real completed food-deposit fact"
)
var deposit_event := _find_deposit_event(manager, contributor.id)
_check(deposit_event != null, "The original deposit must remain in objective event history")
if deposit_event == null:
manager.free()
_finish()
return
var event_id := int(deposit_event.data["event_id"])
_check(
(
manager.npc_knows_event(contributor.id, event_id)
and manager.npc_knows_event(witness.id, event_id)
and not manager.npc_knows_event(listener.id, event_id)
and not manager.npc_knows_event(control.id, event_id)
),
"Only the contributor and nearby witness should know the fact initially"
)
_check(
(
manager.get_known_event_record(witness.id, event_id).get_acquisition_method()
== SimulationIds.KNOWLEDGE_ACQUISITION_WITNESSED
),
"The teller should retain direct witness provenance"
)
for npc in [witness, listener]:
npc.set_task(SimulationIds.ACTION_EAT)
npc.target_id = SimulationIds.STORAGE_VILLAGE_PANTRY
npc.position = Vector3(20.0 + npc.id, 0.0, 0.0)
npc.start_working()
_check(
not manager.try_communicate_at_shared_activity(witness.id, listener.id),
"Passing at storage should not trigger the bounded shared-work conversation"
)
_prepare_shared_patrol(witness, listener, Vector3(20.0, 0.0, 0.0), Vector3(30.0, 0.0, 0.0))
var before_failed_transfer: String = manager.get_state_checksum()
_check(
not manager.try_communicate_at_shared_activity(witness.id, listener.id),
"Matching target IDs must not teleport knowledge between distant workers"
)
_check(
manager.get_state_checksum() == before_failed_transfer,
"A rejected distant conversation must not mutate simulation state"
)
listener.set_task(SimulationIds.ACTION_PATROL)
listener.target_id = witness.target_id
listener.position = witness.position + Vector3(1.0, 0.0, 0.0)
var event_count_before: int = manager.economic_events.size()
var next_event_id_before: int = manager.next_event_id
manager.notify_npc_arrived(listener.id)
_check(
manager.npc_knows_event(listener.id, event_id),
"Arriving beside the witness at shared work should transfer one fact"
)
_check(
(
manager.economic_events.size() == event_count_before
and manager.next_event_id == next_event_id_before
),
"Communication must reference the original event without replaying or duplicating it"
)
var communicated_record: KnownEventStateRecord = manager.get_known_event_record(
listener.id, event_id
)
_check(
(
communicated_record != null
and (
communicated_record.get_acquisition_method()
== SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED
)
and communicated_record.get_source_npc_id() == witness.id
),
"The listener should preserve who communicated the objective fact"
)
var listener_relationship: RelationshipStateRecord = (
manager.relationship_system.get_relationship(listener.id, contributor.id)
)
var control_relationship: RelationshipStateRecord = (
manager.relationship_system.get_relationship(control.id, contributor.id)
)
_check(
(
listener_relationship != null
and is_equal_approx(listener_relationship.get_trust(), 0.65)
and listener_relationship.get_last_trust_cause_event_id() == event_id
),
"Learning the fact should apply its trust consequence only to the listener"
)
_check(
(
control_relationship != null
and is_equal_approx(
control_relationship.get_trust(), RelationshipStateRecord.NEUTRAL_TRUST
)
and not manager.npc_knows_event(control.id, event_id)
),
"A nearby uninvolved villager should not receive a directed conversation"
)
var before_repeat: String = manager.get_state_checksum()
_check(
not manager.try_communicate_at_shared_activity(witness.id, listener.id),
"Repeating the same conversation should not replace first-acquisition provenance"
)
_check(
manager.get_state_checksum() == before_repeat,
"Repeated communication must not add knowledge or apply trust twice"
)
control.set_task(SimulationIds.ACTION_PATROL)
control.target_id = listener.target_id
control.position = listener.position + Vector3(1.0, 0.0, 0.0)
control.start_working()
_check(
not manager.try_communicate_at_shared_activity(listener.id, control.id),
"Communicated facts should not relay again before the rumour phase"
)
_prepare_choice_divergence(manager, contributor, listener, control)
var informed_choice: ActionSelectionResult = manager.action_selector.select_action(
listener, manager.village, 0.5, manager.npcs
)
var control_choice: ActionSelectionResult = manager.action_selector.select_action(
control, manager.village, 0.5, manager.npcs
)
_check(
(
informed_choice.action_id == SimulationIds.ACTION_GATHER_FOOD
and contributor.npc_name in informed_choice.reason
),
"The informed listener should act on communicated evidence"
)
_check(
control_choice.action_id == SimulationIds.ACTION_PATROL,
"The uninformed control should continue ordinary guard work"
)
var saved_json: String = manager.serialize_state()
var restored := _create_manager(999)
_check(restored.restore_state_from_json(saved_json), "Communicated provenance should restore")
var restored_record: KnownEventStateRecord = restored.get_known_event_record(
listener.id, event_id
)
_check(
(
restored_record != null
and (
restored_record.get_acquisition_method()
== SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED
)
and restored_record.get_source_npc_id() == witness.id
),
"Save/load should preserve the exact speaker provenance"
)
_check(
restored.get_state_checksum() == manager.get_state_checksum(),
"Restored communication state should retain the deterministic checksum"
)
var restored_listener: SimNPC = restored.npcs[listener.id]
var restored_control: SimNPC = restored.npcs[control.id]
var current_next_informed_choice: ActionSelectionResult = manager.action_selector.select_action(
listener, manager.village, 0.5, manager.npcs
)
var current_next_control_choice: ActionSelectionResult = manager.action_selector.select_action(
control, manager.village, 0.5, manager.npcs
)
var restored_informed_choice: ActionSelectionResult = restored.action_selector.select_action(
restored_listener, restored.village, 0.5, restored.npcs
)
var restored_control_choice: ActionSelectionResult = restored.action_selector.select_action(
restored_control, restored.village, 0.5, restored.npcs
)
_check(
(
restored_informed_choice.action_id == current_next_informed_choice.action_id
and restored_control_choice.action_id == current_next_control_choice.action_id
),
"Restored knowledge should preserve the next informed and control choices"
)
_check(
restored.get_state_checksum() == manager.get_state_checksum(),
"Equivalent future choices should advance restored RNG streams identically"
)
manager.free()
restored.free()
_finish()
func _prepare_shared_patrol(
witness: SimNPC, listener: SimNPC, witness_position: Vector3, listener_position: Vector3
) -> void:
for npc in [witness, listener]:
npc.set_task(SimulationIds.ACTION_PATROL)
npc.target_id = &"guard_post"
witness.position = witness_position
listener.position = listener_position
witness.start_working()
listener.start_working()
func _prepare_choice_divergence(
manager: Node, contributor: SimNPC, informed: SimNPC, control: SimNPC
) -> void:
var pantry: StorageStateRecord = manager.get_pantry()
pantry.withdraw(
SimulationIds.RESOURCE_FOOD,
maxf(
(
pantry.get_amount(SimulationIds.RESOURCE_FOOD)
- (ActionSelectionSystem.RELATIONSHIP_AID_PANTRY_THRESHOLD - 5.0)
),
0.0
)
)
manager.economy.sync_resource(SimulationIds.RESOURCE_FOOD)
manager.economy.deposit_resource(SimulationIds.RESOURCE_WOOD, 10.0)
manager.village.safety = 50.0
manager.village.knowledge = 20.0
manager.village.update_priorities()
contributor.hunger = 95.0
contributor.is_starving = true
for observer in [informed, control]:
observer.profession = SimulationIds.PROFESSION_GUARD
observer.hunger = 20.0
observer.energy = 80.0
observer.inventory.clear()
observer.last_task = &""
func _find_deposit_event(manager: Node, actor_id: int) -> EconomicEventRecord:
for event in manager.get_npc_events(actor_id, 4):
if StringName(event.data["event_type"]) == SimulationIds.EVENT_STORAGE_DEPOSITED:
return event
return null
func _create_manager(seed_value: int = 821) -> Node:
var manager: Node = load("res://simulation/SimulationManager.gd").new()
manager.simulation_seed = seed_value
manager.debug_logs = false
var home_positions: Array[Vector3] = [
Vector3(0.0, 0.0, 0.0),
Vector3(1.0, 0.0, 0.0),
Vector3(2.0, 0.0, 0.0),
Vector3(3.0, 0.0, 0.0),
Vector3(30.0, 0.0, 30.0),
Vector3(40.0, 0.0, 40.0),
]
manager.home_positions = home_positions
root.add_child(manager)
manager.set_process(false)
return manager
func _finish() -> void:
if failures.is_empty():
print("[TEST] Communicated knowledge passed: witness -> coworker -> informed choice")
quit(0)
return
for failure in failures:
push_error("[TEST] " + failure)
quit(1)
func _check(condition: bool, message: String) -> void:
if not condition:
failures.append(message)
@@ -0,0 +1 @@
uid://x8jugu64gj2o
+24
View File
@@ -44,6 +44,9 @@ func _run() -> void:
)
var contributor: SimNPC = simulation_manager.npcs[0]
var witness: SimNPC = simulation_manager.npcs[1]
var listener: SimNPC = simulation_manager.npcs[2]
for npc in simulation_manager.npcs:
npc.position = Vector3(20.0 + npc.id * 2.0, 0.0, 0.0)
contributor.position = Vector3.ZERO
witness.position = Vector3(4.0, 0.0, 0.0)
witness.hunger = 85.0
@@ -61,11 +64,32 @@ func _run() -> void:
_check(
(
"Known fact: %s deposited" % contributor.npc_name in inspector_label.text
and "(witnessed)" in inspector_label.text
and "Relationship: %s" % contributor.npc_name in inspector_label.text
and "Because:" in inspector_label.text
),
"NPC inspector should show the witnessed fact and its relationship consequence"
)
var guard_site := (
main_scene.get_node("JajceWorld/WorldObjects/ActivitySites/GuardPost") as ActivitySite
)
witness.set_task(SimulationIds.ACTION_PATROL)
witness.target_id = guard_site.site_id
witness.position = guard_site.get_interaction_position()
witness.start_working()
listener.set_task(SimulationIds.ACTION_PATROL)
listener.target_id = guard_site.site_id
listener.position = witness.position + Vector3(1.0, 0.0, 0.0)
simulation_manager.notify_npc_arrived(listener.id)
village_ui.selected_npc_index = listener.id
village_ui.call("_refresh_npc_inspector")
_check(
(
"Known fact: %s deposited" % contributor.npc_name in inspector_label.text
and "(heard from %s)" % witness.npc_name in inspector_label.text
),
"NPC inspector should identify who communicated a known fact"
)
_check(
main_scene.has_node("JajceWorld/TerrainRoot/Terrain3D"),
"Playable runtime should instance the Jajce Terrain3D world"
+152 -1
View File
@@ -16,6 +16,7 @@ func _run() -> void:
_test_previous_world_event_migration()
_test_previous_world_relationship_migration()
_test_previous_world_knowledge_migration()
_test_previous_world_provenance_migration()
_test_relationship_schema_rejection()
_test_schema_rejection()
@@ -266,7 +267,7 @@ func _test_previous_world_relationship_migration() -> void:
func _test_previous_world_knowledge_migration() -> void:
var manager := _create_manager(59)
var previous_data: Dictionary = manager.create_state_record().to_dictionary()
previous_data["schema_version"] = SimulationStateRecord.PREVIOUS_SCHEMA_VERSION
previous_data["schema_version"] = SimulationStateRecord.KNOWLEDGE_LEGACY_SCHEMA_VERSION
previous_data.erase("event_knowledge")
var deposit_event := EconomicEventRecord.create(
0,
@@ -291,12 +292,72 @@ func _test_previous_world_knowledge_migration() -> void:
migrated.event_knowledge.size() == 1
and migrated.event_knowledge[0].get_knower_id() == 0
and migrated.event_knowledge[0].get_event_id() == 0
and (
migrated.event_knowledge[0].get_acquisition_method()
== SimulationIds.KNOWLEDGE_ACQUISITION_LEGACY
)
),
"World v4 migration should preserve the fact implied by a relationship cause"
)
manager.free()
func _test_previous_world_provenance_migration() -> void:
var manager := _create_manager(60)
var previous_data: Dictionary = manager.create_state_record().to_dictionary()
previous_data["schema_version"] = SimulationStateRecord.PREVIOUS_SCHEMA_VERSION
var deposit_event := EconomicEventRecord.create(
0,
SimulationIds.EVENT_STORAGE_DEPOSITED,
12,
1,
SimulationIds.npc_inventory_id(1),
SimulationIds.STORAGE_VILLAGE_PANTRY,
SimulationIds.RESOURCE_FOOD,
2.0
)
previous_data["economic_events"] = [deposit_event.to_dictionary()]
previous_data["simulation"]["next_event_id"] = 1
previous_data["event_knowledge"] = [
{"schema_version": 1, "knower_id": 0, "event_id": 0},
{"schema_version": 1, "knower_id": 1, "event_id": 0},
]
previous_data["relationships"] = [
RelationshipStateRecord.create(0, 1, 0.5, 0.65, 0).to_dictionary()
]
var migrated := SimulationStateRecord.from_dictionary(previous_data)
_check(migrated != null, "World schema v5 should add honest acquisition provenance")
if migrated != null:
var observer_record: KnownEventStateRecord
var actor_record: KnownEventStateRecord
for known_event in migrated.event_knowledge:
if known_event.get_knower_id() == 0:
observer_record = known_event
elif known_event.get_knower_id() == 1:
actor_record = known_event
_check(
(
actor_record != null
and (
actor_record.get_acquisition_method()
== SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED
)
),
"World v5 migration can safely identify an actor's own completed fact"
)
_check(
(
observer_record != null
and (
observer_record.get_acquisition_method()
== SimulationIds.KNOWLEDGE_ACQUISITION_LEGACY
)
),
"World v5 migration must not invent witness or speaker provenance"
)
manager.free()
func _test_relationship_schema_rejection() -> void:
var manager := _create_manager(58)
var missing_cause_data: Dictionary = manager.create_state_record().to_dictionary()
@@ -391,6 +452,96 @@ func _test_relationship_schema_rejection() -> void:
SimulationStateRecord.from_dictionary(nonpositive_cause_data) == null,
"A trust cause must describe a successful positive food deposit"
)
var provenance_event := EconomicEventRecord.create(
0,
SimulationIds.EVENT_STORAGE_DEPOSITED,
1,
0,
SimulationIds.npc_inventory_id(0),
SimulationIds.STORAGE_VILLAGE_PANTRY,
SimulationIds.RESOURCE_FOOD,
1.0
)
var missing_source_data: Dictionary = manager.create_state_record().to_dictionary()
missing_source_data["economic_events"] = [provenance_event.to_dictionary()]
missing_source_data["simulation"]["next_event_id"] = 1
missing_source_data["event_knowledge"] = [
(
KnownEventStateRecord
. create(1, 0, SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED, 2)
. to_dictionary()
)
]
_check(
SimulationStateRecord.from_dictionary(missing_source_data) == null,
"Communicated knowledge must reference a source who knows the same event"
)
var wrong_actor_data: Dictionary = manager.create_state_record().to_dictionary()
wrong_actor_data["economic_events"] = [provenance_event.to_dictionary()]
wrong_actor_data["simulation"]["next_event_id"] = 1
wrong_actor_data["event_knowledge"] = [
(
KnownEventStateRecord
. create(1, 0, SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED)
. to_dictionary()
)
]
_check(
SimulationStateRecord.from_dictionary(wrong_actor_data) == null,
"Performed provenance must belong to the event actor"
)
var relayed_source_data: Dictionary = manager.create_state_record().to_dictionary()
relayed_source_data["economic_events"] = [provenance_event.to_dictionary()]
relayed_source_data["simulation"]["next_event_id"] = 1
relayed_source_data["event_knowledge"] = [
(
KnownEventStateRecord
. create(1, 0, SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED, 2)
. to_dictionary()
),
(
KnownEventStateRecord
. create(2, 0, SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED, 0)
. to_dictionary()
),
(
KnownEventStateRecord
. create(0, 0, SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED)
. to_dictionary()
),
]
_check(
SimulationStateRecord.from_dictionary(relayed_source_data) == null,
"Communicated facts must not form a second relay hop in this phase"
)
var order_independent_data: Dictionary = manager.create_state_record().to_dictionary()
order_independent_data["economic_events"] = [provenance_event.to_dictionary()]
order_independent_data["simulation"]["next_event_id"] = 1
order_independent_data["event_knowledge"] = [
(
KnownEventStateRecord
. create(1, 0, SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED, 2)
. to_dictionary()
),
(
KnownEventStateRecord
. create(0, 0, SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED)
. to_dictionary()
),
(
KnownEventStateRecord
. create(2, 0, SimulationIds.KNOWLEDGE_ACQUISITION_WITNESSED)
. to_dictionary()
),
]
_check(
SimulationStateRecord.from_dictionary(order_independent_data) != null,
"Provenance validation should not depend on knowledge array ordering"
)
manager.free()
+53
View File
@@ -128,3 +128,56 @@ func test_event_knowledge_is_spatial_directed_and_idempotent() -> void:
assert_true(knowledge_system.knows_event(nearby.id, 12))
assert_false(knowledge_system.knows_event(distant.id, 12))
assert_eq(knowledge_system.get_knowers(12), [actor.id, nearby.id])
assert_eq(
knowledge_system.get_record(actor.id, 12).get_acquisition_method(),
SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED
)
assert_eq(
knowledge_system.get_record(nearby.id, 12).get_acquisition_method(),
SimulationIds.KNOWLEDGE_ACQUISITION_WITNESSED
)
func test_event_communication_preserves_first_provenance_and_stops_after_one_hop() -> void:
var actor := SimNPC.new(0, "Amina", SimulationIds.PROFESSION_FARMER, 5.0, 5.0)
var witness := SimNPC.new(1, "Tarik", SimulationIds.PROFESSION_GUARD, 5.0, 5.0)
var listener := SimNPC.new(2, "Jasmin", SimulationIds.PROFESSION_GUARD, 5.0, 5.0)
var relay_target := SimNPC.new(3, "Elma", SimulationIds.PROFESSION_GUARD, 5.0, 5.0)
actor.position = Vector3.ZERO
witness.position = Vector3(2.0, 0.0, 0.0)
listener.position = Vector3(20.0, 0.0, 0.0)
relay_target.position = Vector3(20.0, 0.0, 1.0)
var villagers: Array[SimNPC] = [actor, witness, listener, relay_target]
var event := EconomicEventRecord.create(
21,
SimulationIds.EVENT_STORAGE_DEPOSITED,
40,
actor.id,
SimulationIds.npc_inventory_id(actor.id),
SimulationIds.STORAGE_VILLAGE_PANTRY,
SimulationIds.RESOURCE_FOOD,
2.0,
Vector3.ZERO
)
var knowledge_system := EventKnowledgeSystemScript.new()
knowledge_system.observe_event(event, villagers)
assert_null(knowledge_system.communicate_event(event, listener.id, relay_target.id))
var communicated := knowledge_system.communicate_event(event, witness.id, listener.id)
assert_not_null(communicated)
assert_eq(
communicated.get_acquisition_method(), SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED
)
assert_eq(communicated.get_source_npc_id(), witness.id)
assert_null(knowledge_system.communicate_event(event, actor.id, listener.id))
assert_eq(knowledge_system.get_record(listener.id, event.data["event_id"]), communicated)
assert_null(knowledge_system.communicate_event(event, listener.id, relay_target.id))
assert_false(knowledge_system.knows_event(relay_target.id, int(event.data["event_id"])))
var actor_gap_system := EventKnowledgeSystemScript.new()
var direct_witness_records: Array[KnownEventStateRecord] = [
KnownEventStateRecord.create(
witness.id, int(event.data["event_id"]), SimulationIds.KNOWLEDGE_ACQUISITION_WITNESSED
)
]
actor_gap_system.restore(direct_witness_records)
assert_null(actor_gap_system.communicate_event(event, witness.id, actor.id))