admin/gamedev-the-steward
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

feat: add deterministic simulation foundation

Browse Source 
Replace implicit randomness with seeded per-NPC RandomNumberGenerator
streams so the same seed always produces the same scenario outcome.

- Add SimulationClock (RefCounted): explicit fixed-step clock that
  converts frame delta into simulation ticks while preserving sub-tick
  remainder; replaces raw _process tick_timer accumulation
- Add simulation_seed export (int=1337) to SimulationManager; drive
  per-NPC RNG streams via seed + npc_id + stream_id derivation
  (stream 0=init, stream 1=wander)
- Add get_wander_offset(npc_id) to SimulationManager so wander targets
  are deterministic per seed; WorldViewManager calls it instead of
  local randf_range()
- Add get_state_snapshot() and get_state_checksum() to SimulationManager
  for headless verification and future save/load
- Convert SimNPC/SimVillage const DEBUG_LOGS to instance var debug_logs
  so headless tests can silence output without recompilation
- Pass RandomNumberGenerator through SimNPC._init() instead of using
  global randf_range() for hunger/energy/position/scoring noise
- Remove obsolete farm_zone and forest_zone exports from
  WorldViewManager and their marker/tree scene children from main.tscn;
  NPC gather tasks use ResourceNode exclusively
- Rename TaskZone container to ActivityMarkers in main.tscn and update
  all scene paths (player, WVM, tests) to match
- Add headless deterministic_simulation_test.gd: verifies clock
  accuracy, same-seed equality, different-seed divergence, and
  24-tick scenario checksum without loading main.tscn
This commit is contained in:
Rijad Zuzo
2026-07-05 11:23:12 +02:00
parent b50fae671a
commit 37610242bf
10 changed files with 212 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files
simulation/SimNPC.gd
+18 -9
View File
@@ -1,8 +1,6 @@
class_name SimNPC
extends RefCounted
const DEBUG_LOGS := true
const TASK_STATE_IDLE := "idle"
const TASK_STATE_TRAVELING := "traveling"
const TASK_STATE_WORKING := "working"
@@ -29,22 +27,33 @@ var task_progress := 0.0
var task_complete := true
var target_id: StringName = &""
var last_task := ""
var random_source: RandomNumberGenerator
var debug_logs := true
func _init(
_id: int,
_npc_name: String,
_profession: String,
_strength: float,
_intelligence: float
_intelligence: float,
_random_source: RandomNumberGenerator = null
) -> void:
id = _id
npc_name = _npc_name
profession = _profession
strength = _strength
intelligence = _intelligence
hunger = randf_range(20.0, 80.0)
energy = randf_range(40.0, 100.0)
position = Vector3(randf_range(-8.0, 8.0), 0.0, randf_range(-8.0, 8.0))
random_source = _random_source
if random_source == null:
random_source = RandomNumberGenerator.new()
random_source.seed = id + 1
hunger = random_source.randf_range(20.0, 80.0)
energy = random_source.randf_range(40.0, 100.0)
position = Vector3(
random_source.randf_range(-8.0, 8.0),
0.0,
random_source.randf_range(-8.0, 8.0)
)
func simulate_tick(village: SimVillage) -> void:
if is_dead:
@@ -104,7 +113,7 @@ func die_from_starvation() -> void:
task_duration = 0.0
task_complete = true
if DEBUG_LOGS:
if debug_logs:
print("[SimNPC] ", npc_name, " died from starvation.")
func choose_new_task(village: SimVillage) -> void:
@@ -231,9 +240,9 @@ func calculate_task_score(
if task_name == last_task:
score -= 1.5
score += randf_range(0.0, 0.5)
score += random_source.randf_range(0.0, 0.5)
if DEBUG_LOGS:
if debug_logs:
print(
"[SimNPC] ",
npc_name,
simulation/SimVillage.gd
+3 -4
View File
@@ -1,12 +1,11 @@
class_name SimVillage
extends RefCounted
const DEBUG_LOGS := true
var food := 20.0
var wood := 10.0
var safety := 50.0
var knowledge := 0.0
var debug_logs := true
var food_modifier := 1.0
var wood_modifier := 1.0
@@ -66,7 +65,7 @@ func update_priorities() -> void:
elif knowledge < 15.0:
knowledge_priority = 1.25
if DEBUG_LOGS:
if debug_logs:
print(get_priority_summary())
func apply_resource_delta(resource_id: StringName, amount: float) -> void:
@@ -160,5 +159,5 @@ func get_priority_summary() -> String:
]
func debug_log(message: String) -> void:
if DEBUG_LOGS:
if debug_logs:
print("[Village] ", message)
simulation/SimulationClock.gd
+22
View File
@@ -0,0 +1,22 @@
class_name SimulationClock
extends RefCounted
var tick_interval: float
var accumulator := 0.0
var elapsed_ticks := 0
func _init(interval: float = 1.0) -> void:
tick_interval = maxf(interval, 0.0001)
func advance(delta: float) -> int:
accumulator += maxf(delta, 0.0)
var ticks_due := 0
while accumulator >= tick_interval:
accumulator -= tick_interval
elapsed_ticks += 1
ticks_due += 1
return ticks_due
func reset() -> void:
accumulator = 0.0
elapsed_ticks = 0
simulation/SimulationClock.gd.uid
+1
View File
@@ -0,0 +1 @@
uid://ctbje7tpajoq1
simulation/SimulationManager.gd
+85 -25
View File
@@ -6,12 +6,14 @@ signal npc_died(npc: SimNPC)
var village := SimVillage.new()
const DEBUG_LOGS := true
var npcs: Array[SimNPC] = []
var tick_interval := 1.2
var tick_timer := 0.0
@export var tick_interval := 1.2
@export var simulation_seed: int = 1337
@export var debug_logs := true
var clock: SimulationClock
var tick_count := 0
var wander_random_sources := {}
var names := [
"Amina", "Tarik", "Jasmin"
@@ -26,34 +28,56 @@ var professions := [
]
func _ready() -> void:
randomize()
clock = SimulationClock.new(tick_interval)
village.debug_logs = debug_logs
village.update_modifiers()
village.update_priorities()
generate_npcs()
print("--- Simulation started ---")
if debug_logs:
print("--- Simulation started ---")
func _process(delta: float) -> void:
tick_timer += delta
if tick_timer >= tick_interval:
tick_timer -= tick_interval
var ticks_due := clock.advance(delta)
for tick in ticks_due:
simulate_tick()
func generate_npcs() -> void:
for i in range(names.size()):
var npc_random := _create_random_source(i, 0)
var profession_index := npc_random.randi_range(0, professions.size() - 1)
var npc := SimNPC.new(
i,
names[i],
professions.pick_random(),
randf_range(1.0, 10.0),
randf_range(1.0, 10.0)
professions[profession_index],
npc_random.randf_range(1.0, 10.0),
npc_random.randf_range(1.0, 10.0),
npc_random
)
npc.debug_logs = debug_logs
npcs.append(npc)
wander_random_sources[i] = _create_random_source(i, 1)
func _create_random_source(npc_id: int, stream_id: int) -> RandomNumberGenerator:
var source := RandomNumberGenerator.new()
source.seed = simulation_seed + (npc_id + 1) * 1000003 + stream_id * 7919
return source
func get_wander_offset(npc_id: int) -> Vector3:
var source: RandomNumberGenerator = wander_random_sources.get(npc_id)
if source == null:
source = _create_random_source(npc_id, 1)
wander_random_sources[npc_id] = source
return Vector3(
source.randf_range(-6.0, 6.0),
0.0,
source.randf_range(-6.0, 6.0)
)
func simulate_tick() -> void:
tick_count += 1
print("--- Tick ", tick_count, " ---")
if debug_logs:
print("--- Tick ", tick_count, " ---")
var village_was_changed := false
@@ -75,7 +99,7 @@ func simulate_tick() -> void:
npc_died.emit(npc)
npc_task_changed.emit(npc, old_task, npc.current_task)
if DEBUG_LOGS:
if debug_logs:
print("[SimulationManager] NPC died: ", npc.npc_name)
if old_task != npc.current_task and not npc.is_dead:
@@ -91,14 +115,14 @@ func simulate_tick() -> void:
var extracted := node.extract()
if extracted > 0:
village.apply_resource_delta(node.resource_id, extracted)
if DEBUG_LOGS:
if debug_logs:
print("[SimulationManager] ", npc.npc_name, " extracted ", extracted, " ", node.resource_id, " from ", node.node_id)
elif DEBUG_LOGS:
elif debug_logs:
print("[SimulationManager] ", npc.npc_name, " could not complete ", completed_task, ": target reservation was invalid")
release_npc_reservation(npc.id)
elif completed_task not in ["gather_food", "gather_wood"]:
village.apply_npc_task(npc)
elif DEBUG_LOGS:
elif debug_logs:
print("[SimulationManager] ", npc.npc_name, " could not complete ", completed_task, ": no resource target")
village_was_changed = true
@@ -112,10 +136,10 @@ func simulate_tick() -> void:
npc.set_task("eat", 1.0)
npc_task_changed.emit(npc, completed_task, npc.current_task)
if DEBUG_LOGS:
if debug_logs:
print("[SimulationManager] ", npc.npc_name, " gathered food while starving and is going to eat immediately.")
if DEBUG_LOGS:
if debug_logs:
print(
npc.npc_name,
" | ",
@@ -148,7 +172,7 @@ func simulate_tick() -> void:
if village_was_changed:
village_changed.emit(village)
if DEBUG_LOGS:
if debug_logs:
print(village.get_summary())
func set_npc_target_id(npc_id: int, target_id: StringName) -> void:
@@ -177,14 +201,14 @@ func notify_npc_arrived(npc_id: int) -> void:
if npc.target_id != &"":
var node := ResourceNode.get_by_id(npc.target_id)
if node == null or not node.can_extract():
if DEBUG_LOGS:
if debug_logs:
print("[SimulationManager] ", npc.npc_name, " arrived but target ", npc.target_id, " is unavailable, replanning")
notify_npc_navigation_failed(npc.id)
return
npc.start_working()
if DEBUG_LOGS:
if debug_logs:
print("[SimulationManager] ", npc.npc_name, " arrived and started working on: ", npc.current_task)
return
@@ -201,7 +225,7 @@ func notify_npc_navigation_failed(npc_id: int) -> void:
npc.set_task("wander", 2.0)
npc_task_changed.emit(npc, failed_task, npc.current_task)
if DEBUG_LOGS:
if debug_logs:
print("[SimulationManager] ", npc.npc_name, " could not navigate for ", failed_task, " and is trying a wander target")
return
@@ -219,7 +243,7 @@ func harvest_resource_node(node: ResourceNode) -> float:
village.apply_resource_delta(node.resource_id, extracted)
village_changed.emit(village)
if DEBUG_LOGS:
if debug_logs:
print("[SimulationManager] Player extracted ", extracted, " ", node.resource_id, " from ", node.node_id)
return extracted
@@ -250,3 +274,39 @@ func get_starving_count() -> int:
if npc.is_starving:
count += 1
return count
func get_state_snapshot() -> Dictionary:
var npc_snapshots: Array[Dictionary] = []
for npc in npcs:
npc_snapshots.append({
"id": npc.id,
"name": npc.npc_name,
"profession": npc.profession,
"hunger": npc.hunger,
"energy": npc.energy,
"strength": npc.strength,
"intelligence": npc.intelligence,
"task": npc.current_task,
"task_state": npc.task_state,
"task_duration": npc.task_duration,
"task_progress": npc.task_progress,
"target_id": String(npc.target_id),
"position": [npc.position.x, npc.position.y, npc.position.z],
"starvation_ticks": npc.starvation_ticks,
"is_dead": npc.is_dead
})
return {
"seed": simulation_seed,
"tick_count": tick_count,
"village": {
"food": village.food,
"wood": village.wood,
"safety": village.safety,
"knowledge": village.knowledge
},
"npcs": npc_snapshots
}
func get_state_checksum() -> String:
return JSON.stringify(get_state_snapshot()).sha256_text()