## SubPayloadRegistry — 子荷载登记表（Autoload: SubPayloadRegistry）
## 权威来源：architecture_design.md §3.4.A
## 生命周期：
##   - compile_wand 开始时调用 clear_for_wand(wand_id)，清除该法杯旧荷载
##   - 关卡进入 BATTLE 后，SubPayloadRegistry 进入只读状态（P6-N10）
##   - 战斗中敌人死亡触发的旧子荷载居然能正常结算
extends Node

const MAX_PAYLOAD_ID: int = 1024

## { payload_id: int → Array[SpellNode] }
var _payloads:    Dictionary = {}
var _next_id:     int        = 0
var _read_only:   bool       = false  # BATTLE 期间禁止修改

## compile_wand 开始时调用，清除属于该法杯的旧荷载
func clear_for_compile() -> void:
	_payloads.clear()
	_next_id  = 0
	_read_only = false

## 注册一组节点为子荷载，返回 payload_id
func register(nodes: Array) -> int:
	if _read_only:
		push_warning("SubPayloadRegistry: 战斗中禁止注册新荷载 (P6-N10)")
		return -1
	if _next_id >= MAX_PAYLOAD_ID:
		push_error("SubPayloadRegistry: 已达上限 MAX_PAYLOAD_ID=%d" % MAX_PAYLOAD_ID)
		return -1
	var id: int = _next_id
	_next_id += 1
	_payloads[id] = nodes
	return id

## 关卡开始后锁定登记表，全局只读
func lock_for_battle() -> void:
	_read_only = true

## 查找子荷载节点列表（第三方不得修改返回值）
func get_nodes(payload_id: int) -> Array:
	return _payloads.get(payload_id, [])

func has_payload(payload_id: int) -> bool:
	return _payloads.has(payload_id)

func get_payload_count() -> int:
	return _payloads.size()