render: extract M2 build queue

src/render/m2/m2_build_job.gd

@@ -0,0 +1,78 @@
+class_name M2BuildJob
+extends RefCounted
+
+## Holds one M2 build cursor, grouped transforms and a strong root reference.
+## Releasing this record never frees the referenced Node.
+
+var _tile_key: String
+var _root: Node3D
+var _groups: Dictionary
+var _group_keys: Array
+var _group_index: int = 0
+var _transform_offset: int = 0
+var _batch_serial: int = 0
+
+
+func _init(tile_key: String, root: Node3D, groups: Dictionary) -> void:
+	_tile_key = tile_key
+	_root = root
+	_groups = groups
+	_group_keys = groups.keys()
+
+
+## Returns the immutable tile identity used by the queue.
+func tile_key() -> String:
+	return _tile_key
+
+
+## Returns the strongly referenced M2 scene root without transferring ownership.
+func root() -> Node3D:
+	return _root
+
+
+## Returns the exact grouped-transform Dictionary supplied at enqueue time.
+func groups() -> Dictionary:
+	return _groups
+
+
+## Returns the insertion-order group-key snapshot created at enqueue time.
+func group_keys() -> Array:
+	return _group_keys
+
+
+## Returns the current model-path group cursor.
+func group_index() -> int:
+	return _group_index
+
+
+## Returns the current transform offset within the selected model-path group.
+func transform_offset() -> int:
+	return _transform_offset
+
+
+## Returns the next static/animated batch serial used for node naming.
+func batch_serial() -> int:
+	return _batch_serial
+
+
+## Atomically adopts all progress values after one planned build operation.
+func adopt_progress(
+	next_group_index: int,
+	next_transform_offset: int,
+	next_batch_serial: int
+) -> void:
+	_group_index = next_group_index
+	_transform_offset = next_transform_offset
+	_batch_serial = next_batch_serial
+
+
+## Returns detached scalar/count diagnostics without engine-object references.
+func diagnostic_snapshot() -> Dictionary:
+	return {
+		"tile_key": _tile_key,
+		"group_index": _group_index,
+		"transform_offset": _transform_offset,
+		"batch_serial": _batch_serial,
+		"group_count": _group_keys.size(),
+		"has_root": _root != null,
+	}