sindoring/open-wc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor(M03): extract terrain chunk queue planner

Browse Source
This commit is contained in:
sindoring
2026-07-16 09:52:01 +04:00
parent 0d2c820ea7
commit f800e11cd2
9 changed files with 515 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/render/terrain/terrain_chunk_geometry_queue_planner.gd
+102
View File
@@ -0,0 +1,102 @@
class_name TerrainChunkGeometryQueuePlanner
extends RefCounted
## Pure desired-operation planner for terrain chunk geometry queues.
const GODOT_WORLD_POSITION_SCRIPT := preload(
"res://src/domain/coordinates/godot_world_position.gd"
)
## Returns fresh nearest-first create and stable-order remove request arrays.
## The caller retains queue storage, execution order and every render side effect.
func plan(tile_states: Dictionary, focus_position: RefCounted) -> Dictionary:
var chunk_create_requests: Array = []
var chunk_remove_requests: Array = []
if (
focus_position == null
or focus_position.get_script() != GODOT_WORLD_POSITION_SCRIPT
):
return _create_plan(chunk_create_requests, chunk_remove_requests)
var focus_x_units := float(focus_position.get("x_units"))
var focus_z_units := float(focus_position.get("z_units"))
for tile_key_variant in tile_states.keys():
var tile_key := String(tile_key_variant)
var tile_state: Dictionary = tile_states[tile_key_variant]
var current_chunks: Dictionary = tile_state["chunks"]
var desired_lods: Dictionary = tile_state["desired_lods"]
var desired_tile_lod := int(tile_state.get("desired_tile_lod", -1))
if desired_tile_lod >= 0:
for chunk_id in current_chunks.keys():
chunk_remove_requests.append({"tile": tile_key, "chunk": chunk_id})
continue
for chunk_id in current_chunks.keys():
if not desired_lods.has(chunk_id):
chunk_remove_requests.append({"tile": tile_key, "chunk": chunk_id})
continue
if int(current_chunks[chunk_id]["lod"]) != int(desired_lods[chunk_id]):
chunk_create_requests.append(_create_chunk_request(
tile_key,
chunk_id,
int(desired_lods[chunk_id]),
_resolve_chunk_origin(tile_state, int(chunk_id)),
focus_x_units,
focus_z_units
))
for chunk_id in desired_lods.keys():
if current_chunks.has(chunk_id):
continue
chunk_create_requests.append(_create_chunk_request(
tile_key,
chunk_id,
int(desired_lods[chunk_id]),
_resolve_chunk_origin(tile_state, int(chunk_id)),
focus_x_units,
focus_z_units
))
chunk_create_requests.sort_custom(func(
left_request: Dictionary,
right_request: Dictionary
) -> bool:
return float(left_request["dist_sq"]) < float(right_request["dist_sq"])
)
return _create_plan(chunk_create_requests, chunk_remove_requests)
func _resolve_chunk_origin(tile_state: Dictionary, chunk_id: int) -> Vector3:
var chunks: Array = tile_state["data"].get("chunks", [])
if chunk_id >= 0 and chunk_id < chunks.size():
var chunk: Dictionary = chunks[chunk_id]
if not chunk.is_empty():
return chunk.get("origin", Vector3.ZERO)
return tile_state.get("origin", Vector3.ZERO)
func _create_chunk_request(
tile_key: String,
chunk_id: Variant,
desired_lod: int,
chunk_origin: Vector3,
focus_x_units: float,
focus_z_units: float
) -> Dictionary:
var delta_x_units := chunk_origin.x - focus_x_units
var delta_z_units := chunk_origin.z - focus_z_units
return {
"tile": tile_key,
"chunk": chunk_id,
"lod": desired_lod,
"dist_sq": delta_x_units * delta_x_units + delta_z_units * delta_z_units,
}
func _create_plan(chunk_create_requests: Array, chunk_remove_requests: Array) -> Dictionary:
return {
"create_requests": chunk_create_requests,
"remove_requests": chunk_remove_requests,
}
src/render/terrain/terrain_chunk_geometry_queue_planner.gd.uid
+1
View File
@@ -0,0 +1 @@
uid://ct1ar5inci34u
src/scenes/streaming/streaming_world_loader.gd
+18 -47
View File
@@ -21,6 +21,9 @@ const RENDERED_GROUND_SAMPLE_SCRIPT := preload("res://src/render/terrain/rendere
const TERRAIN_QUALITY_MESH_CACHE_SCRIPT := preload("res://src/render/terrain/terrain_quality_mesh_cache.gd")
const TERRAIN_CHUNK_LOD_POLICY_SCRIPT := preload("res://src/render/terrain/terrain_chunk_lod_policy.gd")
const TERRAIN_CHUNK_LOD_PLANNER_SCRIPT := preload("res://src/render/terrain/terrain_chunk_lod_planner.gd")
const TERRAIN_CHUNK_GEOMETRY_QUEUE_PLANNER_SCRIPT := preload(
"res://src/render/terrain/terrain_chunk_geometry_queue_planner.gd"
)
const STREAMING_TARGET_PLANNER_SCRIPT := preload("res://src/render/streaming/streaming_target_planner.gd")
const STREAMING_TARGET_POLICY_SCRIPT := preload("res://src/render/streaming/streaming_target_policy.gd")
const RENDER_BUDGET_SCHEDULER_SCRIPT := preload("res://src/render/streaming/render_budget_scheduler.gd")
@@ -184,6 +187,9 @@ const QUALITY_HIGH := "High"
var _builder
var _streaming_target_planner := STREAMING_TARGET_PLANNER_SCRIPT.new()
var _terrain_chunk_lod_planner := TERRAIN_CHUNK_LOD_PLANNER_SCRIPT.new()
var _terrain_chunk_geometry_operation_planner := (
TERRAIN_CHUNK_GEOMETRY_QUEUE_PLANNER_SCRIPT.new()
)
var _map_dir := ""
var _abs_map_dir := ""
var _wdt_info: Dictionary = {}
@@ -857,34 +863,29 @@ func _apply_streaming_target(wanted_tiles: Dictionary, retained_tiles: Dictionar
_rebuild_chunk_queues()
func _chunk_origin_for(state: Dictionary, chunk_id: int) -> Vector3:
var chunks: Array = state["data"].get("chunks", [])
if chunk_id >= 0 and chunk_id < chunks.size():
var c: Dictionary = chunks[chunk_id]
if not c.is_empty():
return c.get("origin", Vector3.ZERO)
return state.get("origin", Vector3.ZERO)
func _rebuild_chunk_queues() -> void:
_chunk_remove_queue.clear()
_chunk_create_queue.clear()
var typed_focus_position = GODOT_WORLD_POSITION_SCRIPT.new(
_last_focus_pos.x,
_last_focus_pos.y,
_last_focus_pos.z
)
var chunk_queue_plan: Dictionary = _terrain_chunk_geometry_operation_planner.plan(
_tile_states,
typed_focus_position
)
_chunk_remove_queue = chunk_queue_plan.get("remove_requests", [])
_chunk_create_queue = chunk_queue_plan.get("create_requests", [])
_tile_lod_remove_queue.clear()
_tile_lod_create_queue.clear()
for key in _tile_states.keys():
var state: Dictionary = _tile_states[key]
var current_chunks: Dictionary = state["chunks"]
var desired_lods: Dictionary = state["desired_lods"]
var current_tile_lod: int = int(state.get("tile_lod", -1))
var desired_tile_lod: int = int(state.get("desired_tile_lod", -1))
var current_tile_lod_visible: bool = bool(state.get("tile_lod_visible", false))
var desired_tile_lod_visible: bool = bool(state.get("desired_tile_lod_visible", false))
if desired_tile_lod >= 0:
for chunk_id in current_chunks.keys():
_chunk_remove_queue.append({"tile": key, "chunk": chunk_id})
if current_tile_lod != desired_tile_lod or current_tile_lod_visible != desired_tile_lod_visible:
_tile_lod_create_queue.append({
"tile": key,
@@ -905,37 +906,7 @@ func _rebuild_chunk_queues() -> void:
if current_tile_lod >= 0 and _is_tile_chunk_set_ready(state):
_tile_lod_remove_queue.append({"tile": key})
for chunk_id in current_chunks.keys():
if not desired_lods.has(chunk_id):
_chunk_remove_queue.append({"tile": key, "chunk": chunk_id})
continue
if current_chunks[chunk_id]["lod"] != desired_lods[chunk_id]:
var lod_change_origin: Vector3 = _chunk_origin_for(state, chunk_id)
var dx2: float = lod_change_origin.x - _last_focus_pos.x
var dz2: float = lod_change_origin.z - _last_focus_pos.z
_chunk_create_queue.append({
"tile": key,
"chunk": chunk_id,
"lod": desired_lods[chunk_id],
"dist_sq": dx2 * dx2 + dz2 * dz2,
})
for chunk_id in desired_lods.keys():
if current_chunks.has(chunk_id):
continue
var chunk_origin: Vector3 = _chunk_origin_for(state, chunk_id)
var dx: float = chunk_origin.x - _last_focus_pos.x
var dz: float = chunk_origin.z - _last_focus_pos.z
_chunk_create_queue.append({
"tile": key,
"chunk": chunk_id,
"lod": desired_lods[chunk_id],
"dist_sq": dx * dx + dz * dz,
})
# Sort after fully rebuilding so nearest chunks are processed first
_chunk_create_queue.sort_custom(func(a: Dictionary, b: Dictionary) -> bool:
return a["dist_sq"] < b["dist_sq"])
# Sort tile LOD creates after fully rebuilding; chunk creates arrive nearest-first.
_tile_lod_create_queue.sort_custom(func(a: Dictionary, b: Dictionary) -> bool:
return a["dist_sq"] < b["dist_sq"])
src/tools/verify_terrain_chunk_geometry_queue_planner.gd
+169
View File
@@ -0,0 +1,169 @@
extends SceneTree
## Asset-free semantic, dependency and timing regression for chunk queue planning.
const PLANNER_SCRIPT := preload(
"res://src/render/terrain/terrain_chunk_geometry_queue_planner.gd"
)
const POSITION_SCRIPT := preload("res://src/domain/coordinates/godot_world_position.gd")
const LOADER_PATH := "res://src/scenes/streaming/streaming_world_loader.gd"
func _initialize() -> void:
var failures: Array[String] = []
_verify_create_remove_and_order(failures)
_verify_tile_lod_removes_all(failures)
_verify_fallback_origin_and_vertical_invariance(failures)
_verify_invalid_focus(failures)
_verify_loader_boundary(failures)
var elapsed_milliseconds := _verify_bounded_timing(failures)
if not failures.is_empty():
for failure in failures:
push_error("TERRAIN_CHUNK_GEOMETRY_QUEUE_PLANNER: %s" % failure)
quit(1)
return
print(
"TERRAIN_CHUNK_GEOMETRY_QUEUE_PLANNER PASS cases=8 iterations=100 elapsed_ms=%.3f"
% elapsed_milliseconds
)
quit(0)
func _verify_create_remove_and_order(failures: Array[String]) -> void:
var planner: RefCounted = PLANNER_SCRIPT.new()
var tile_states := {
"A": _create_tile_state(
{0: {"lod": 0}, 1: {"lod": 1}, 3: {"lod": 0}},
{0: 0, 1: 2, 2: 1},
[
{"origin": Vector3(100.0, 0.0, 0.0)},
{"origin": Vector3(30.0, 8000.0, 0.0)},
{"origin": Vector3(10.0, -8000.0, 0.0)},
]
),
"B": _create_tile_state({5: {"lod": 0}}, {}, []),
}
var plan: Dictionary = planner.call("plan", tile_states, POSITION_SCRIPT.new(0.0, 50.0, 0.0))
var creates: Array = plan["create_requests"]
var removes: Array = plan["remove_requests"]
_expect_equal(creates.size(), 2, "missing and mismatched chunks create", failures)
_expect_equal(int(creates[0]["chunk"]), 2, "nearest missing chunk first", failures)
_expect_equal(int(creates[1]["chunk"]), 1, "farther LOD mismatch second", failures)
_expect_equal(int(creates[1]["lod"]), 2, "mismatch uses desired LOD", failures)
_expect_equal(removes.size(), 2, "undesired current chunks remove", failures)
_expect_string_equal(String(removes[0]["tile"]), "A", "stable tile removal order", failures)
_expect_equal(int(removes[0]["chunk"]), 3, "first undesired chunk", failures)
_expect_equal(int(removes[1]["chunk"]), 5, "second tile undesired chunk", failures)
func _verify_tile_lod_removes_all(failures: Array[String]) -> void:
var tile_state := _create_tile_state({7: {"lod": 0}, 8: {"lod": 1}}, {7: 0}, [])
tile_state["desired_tile_lod"] = 3
var plan: Dictionary = PLANNER_SCRIPT.new().call(
"plan",
{"tile": tile_state},
POSITION_SCRIPT.new(0.0, 0.0, 0.0)
)
_expect_true((plan["create_requests"] as Array).is_empty(), "tile LOD suppresses chunk creates", failures)
_expect_equal((plan["remove_requests"] as Array).size(), 2, "tile LOD removes every chunk", failures)
func _verify_fallback_origin_and_vertical_invariance(failures: Array[String]) -> void:
var tile_state := _create_tile_state({}, {9: 1}, [])
tile_state["origin"] = Vector3(4.0, 99999.0, 3.0)
var plan: Dictionary = PLANNER_SCRIPT.new().call(
"plan",
{"fallback": tile_state},
POSITION_SCRIPT.new(0.0, -99999.0, 0.0)
)
var request: Dictionary = (plan["create_requests"] as Array)[0]
_expect_near(float(request["dist_sq"]), 25.0, "fallback origin uses horizontal distance", failures)
func _verify_invalid_focus(failures: Array[String]) -> void:
var plan: Dictionary = PLANNER_SCRIPT.new().call("plan", {}, null)
_expect_true((plan["create_requests"] as Array).is_empty(), "invalid focus create empty", failures)
_expect_true((plan["remove_requests"] as Array).is_empty(), "invalid focus remove empty", failures)
func _verify_loader_boundary(failures: Array[String]) -> void:
var source := _read_text(LOADER_PATH, failures)
_expect_true(source.contains("TERRAIN_CHUNK_GEOMETRY_QUEUE_PLANNER_SCRIPT.new()"), "loader composes planner", failures)
_expect_true(source.contains("_terrain_chunk_geometry_operation_planner.plan("), "loader delegates plan", failures)
_expect_true(not source.contains("func _chunk_origin_for("), "loader omits chunk-origin planning", failures)
_expect_true(source.contains("_remove_chunk(_chunk_remove_queue.pop_back())"), "loader retains removal-first drain", failures)
_expect_true(source.contains("_create_chunk(_chunk_create_queue.pop_front())"), "loader retains nearest-first drain", failures)
func _verify_bounded_timing(failures: Array[String]) -> float:
var tile_states: Dictionary = {}
for tile_index in range(64):
var current_chunks: Dictionary = {}
var desired_lods: Dictionary = {}
var parsed_chunks: Array = []
for chunk_index in range(16):
current_chunks[chunk_index] = {"lod": chunk_index % 3}
desired_lods[chunk_index] = (chunk_index + 1) % 3
parsed_chunks.append({
"origin": Vector3(float(tile_index * 16 + chunk_index), 0.0, float(tile_index))
})
tile_states["tile-%d" % tile_index] = _create_tile_state(
current_chunks,
desired_lods,
parsed_chunks
)
var planner: RefCounted = PLANNER_SCRIPT.new()
var focus: RefCounted = POSITION_SCRIPT.new(0.0, 0.0, 0.0)
var started_microseconds := Time.get_ticks_usec()
for _iteration in range(100):
planner.call("plan", tile_states, focus)
var elapsed_milliseconds := float(Time.get_ticks_usec() - started_microseconds) / 1000.0
_expect_true(elapsed_milliseconds < 1000.0, "100 multi-tile plans remain bounded", failures)
return elapsed_milliseconds
func _create_tile_state(
current_chunks: Dictionary,
desired_lods: Dictionary,
parsed_chunks: Array
) -> Dictionary:
return {
"chunks": current_chunks,
"desired_lods": desired_lods,
"desired_tile_lod": -1,
"data": {"chunks": parsed_chunks},
"origin": Vector3.ZERO,
}
func _read_text(path: String, failures: Array[String]) -> String:
var file := FileAccess.open(path, FileAccess.READ)
if file == null:
failures.append("cannot open %s" % path)
return ""
return file.get_as_text()
func _expect_equal(actual_value: int, expected_value: int, label: String, failures: Array[String]) -> void:
if actual_value != expected_value:
failures.append("%s expected %d, got %d" % [label, expected_value, actual_value])
func _expect_near(actual_value: float, expected_value: float, label: String, failures: Array[String]) -> void:
if not is_equal_approx(actual_value, expected_value):
failures.append("%s expected %.3f, got %.3f" % [label, expected_value, actual_value])
func _expect_string_equal(
actual_value: String,
expected_value: String,
label: String,
failures: Array[String]
) -> void:
if actual_value != expected_value:
failures.append("%s expected %s, got %s" % [label, expected_value, actual_value])
func _expect_true(actual_value: bool, label: String, failures: Array[String]) -> void:
if not actual_value:
failures.append("%s expected true" % label)
src/tools/verify_terrain_chunk_geometry_queue_planner.gd.uid
+1
View File
@@ -0,0 +1 @@
uid://dcimxvm2atvst