#!/usr/bin/env python3
"""Review spawn-tree helpers behind battle 0xbd visual helper calls.
The object/effect review already proves that many 0xbd helpers spawn child
display objects. This pass focuses only on the spawn graph:
* which helper owns which spawned child VM target,
* whether the child target is a renderer, controller, loop, or nested spawner,
* which spawn-local 0x20 frameScript streams can be decoded,
* which targets are reused by multiple skills.
The important distinction is that some 0x20 frameScript pointers only appear
inside spawned child scripts. The older frameScript report indexes root helper
targets only, so this report decodes spawn-local frameScript pointers directly
from the EXE.
"""
from __future__ import annotations
import html
import json
import sys
from collections import Counter, defaultdict
from pathlib import Path
from typing import Any
ROOT = Path(__file__).resolve().parents[1]
TOOLS = ROOT / "tools"
OUT = ROOT / "out"
EFFECT_JSON = OUT / "battle_effect_object_review.json"
FRAME_JSON = OUT / "battle_helper_frame_script_review.json"
OUT_JSON = OUT / "battle_helper_spawn_tree_review.json"
OUT_MD = OUT / "battle_helper_spawn_tree_review.md"
OUT_HTML = OUT / "battle_helper_spawn_tree_review.html"
if str(TOOLS) not in sys.path:
sys.path.insert(0, str(TOOLS))
from build_battle_display_vm_static_decode import EXE, read_sections # noqa: E402
from build_battle_helper_child_script_review import walk_child_script # noqa: E402
def esc(value: Any) -> str:
return html.escape(str(value if value is not None else ""))
def read_json(path: Path) -> dict[str, Any]:
return json.loads(path.read_text(encoding="utf-8"))
def int_hex(value: str | None) -> int:
if not value:
return -1
try:
return int(value, 16)
except ValueError:
return -1
def compact(values: list[Any] | tuple[Any, ...] | set[Any], limit: int = 10) -> str:
items = [str(value) for value in values if value not in (None, "")]
if not items:
return "-"
if len(items) > limit:
items = items[:limit] + [f"... +{len(items) - limit}"]
return ", ".join(items)
def skill_label(skill: dict[str, Any]) -> str:
owner = skill.get("ownerName")
name = skill.get("skillName")
skill_id = skill.get("skillIdHex")
level = skill.get("levelOrFixed")
parts = [owner, name, skill_id]
if level is not None:
parts.append(f"L{level}")
return " ".join(str(part) for part in parts if part)
def helper_skill_labels(helper: dict[str, Any]) -> list[str]:
labels = helper.get("skillLabels") or []
if labels:
return labels
return [skill_label(skill) for skill in helper.get("skills") or helper.get("skillRows") or []]
def frame_gate_sequence(decoded: dict[str, Any]) -> list[dict[str, Any]]:
rows: list[dict[str, Any]] = []
for frame in decoded.get("frames") or []:
rows.append(
{
"vaHex": frame.get("vaHex"),
"spriteHex": frame.get("spriteHex"),
"frame": frame.get("frame"),
"gate": frame.get("gate"),
"label": f"{frame.get('frame')}@{frame.get('gate')}",
}
)
return rows
def summarize_frame_script(decoded: dict[str, Any], target_hex: str, source: str) -> dict[str, Any]:
sequence = frame_gate_sequence(decoded)
return {
"targetVaHex": target_hex,
"source": source,
"missing": False,
"stopReason": decoded.get("stopReason"),
"instructionCount": decoded.get("instructionCount"),
"opcodeCounts": decoded.get("opcodeCounts") or {},
"frameGateSequence": sequence,
"frameLabels": [item.get("label") for item in sequence],
"frameSequence": [item.get("frame") for item in sequence],
"gateSequence": [item.get("gate") for item in sequence],
"spriteHexSequence": [item.get("spriteHex") for item in sequence],
"durationGate": sum(int(item.get("gate") or 0) for item in sequence),
"initFrameSequence": decoded.get("initFrameSequence") or [],
"randomRanges": decoded.get("randomRanges") or [],
"nestedFrameScriptTargets": decoded.get("frameScriptTargets") or [],
"waits": decoded.get("waits") or [],
"unknowns": decoded.get("unknowns") or [],
}
def summarize_frame_row(row: dict[str, Any], target_hex: str) -> dict[str, Any]:
sequence = row.get("frameGateSequence") or []
return {
"targetVaHex": target_hex,
"source": "root-frame-script-review",
"missing": False,
"stopReason": row.get("stopReason"),
"instructionCount": row.get("instructionCount"),
"opcodeCounts": row.get("opcodeCounts") or {},
"frameGateSequence": sequence,
"frameLabels": [item.get("label") for item in sequence],
"frameSequence": [item.get("frame") for item in sequence],
"gateSequence": [item.get("gate") for item in sequence],
"spriteHexSequence": [item.get("spriteHex") for item in sequence],
"durationGate": sum(int(item.get("gate") or 0) for item in sequence),
"initFrameSequence": row.get("initFrameSequence") or [],
"randomRanges": row.get("randomRanges") or [],
"nestedFrameScriptTargets": row.get("nestedFrameScriptTargets") or [],
"waits": row.get("waits") or [],
"unknowns": row.get("unknowns") or [],
}
def resolve_frame_script(
data: bytes,
sections: list[dict[str, Any]],
frame_by_target: dict[str, dict[str, Any]],
target_hex: str | None,
) -> dict[str, Any] | None:
if not target_hex:
return None
if target_hex in frame_by_target:
return summarize_frame_row(frame_by_target[target_hex], target_hex)
target_va = int_hex(target_hex)
if target_va < 0:
return {"targetVaHex": target_hex, "source": "invalid-target", "missing": True}
decoded = walk_child_script(data, sections, target_va, max_steps=220)
return summarize_frame_script(decoded, target_hex, "spawn-local-decode")
def node_tags(decoded: dict[str, Any], node: dict[str, Any], resolved_frame_scripts: list[dict[str, Any]]) -> list[str]:
tags: list[str] = []
if node.get("children"):
tags.append("spawns-children")
if resolved_frame_scripts:
tags.append("frameScript-emitter")
if decoded.get("frameSequence") or decoded.get("initFrameSequence"):
tags.append("direct-frame-emitter")
if decoded.get("randomRanges"):
tags.append("random-placement")
if decoded.get("positionWrites") or decoded.get("motionWrites") or decoded.get("motionSteps"):
tags.append("motion-position")
if decoded.get("anchorWrites") or decoded.get("parentActorLinks"):
tags.append("anchor-link")
if decoded.get("clearDisplayLists"):
tags.append("cleanup")
if decoded.get("paletteEvents"):
tags.append("palette-effect")
stop = str(decoded.get("stopReason") or "")
if "loop" in stop:
tags.append("loop-controller")
if "unknown opcode" in stop:
tags.append("unknown-stop")
return tags or ["plain-control"]
def primary_class(tags: list[str]) -> str:
order = [
"spawns-children",
"frameScript-emitter",
"direct-frame-emitter",
"loop-controller",
"motion-position",
"random-placement",
"anchor-link",
"cleanup",
"unknown-stop",
"plain-control",
"palette-effect",
]
for tag in order:
if tag in tags:
return tag
return tags[0] if tags else "unknown"
def row_brief(row: dict[str, Any]) -> dict[str, Any]:
keys = (
"vaHex",
"opcode",
"category",
"summary",
"targetVaHex",
"destHex",
"sourceHex",
"immHex",
"immFixed",
"modeHex",
"randomRange",
"randomRangeHex",
"axes",
"childObjectType",
"sourceBranchVaHex",
"sourceBranchTargetVaHex",
"paletteStartHex",
"paletteCountHex",
"argHex",
)
return {key: row.get(key) for key in keys if row.get(key) not in (None, "", [])}
def frame_script_refs(decoded: dict[str, Any]) -> list[str]:
refs: list[str] = []
for item in decoded.get("frameScripts") or []:
target = item.get("targetVaHex")
if target:
refs.append(target)
return refs
def analyze_node(
node: dict[str, Any],
path: str,
helper_id: int,
skill_labels: list[str],
data: bytes,
sections: list[dict[str, Any]],
frame_by_target: dict[str, dict[str, Any]],
) -> tuple[dict[str, Any], list[dict[str, Any]]]:
decoded = node.get("decoded") or {}
resolved = [
item
for item in (
resolve_frame_script(data, sections, frame_by_target, target_hex)
for target_hex in frame_script_refs(decoded)
)
if item
]
tags = node_tags(decoded, node, resolved)
analyzed = {
"path": path,
"depth": node.get("depth"),
"helperId": helper_id,
"skillLabels": skill_labels,
"sourceVaHex": node.get("sourceVaHex"),
"sourceBranchVaHex": node.get("sourceBranchVaHex"),
"sourceBranchTargetVaHex": node.get("sourceBranchTargetVaHex"),
"targetVaHex": node.get("targetVaHex"),
"childObjectType": node.get("childObjectType"),
"primaryClass": primary_class(tags),
"tags": tags,
"stopReason": decoded.get("stopReason"),
"instructionCount": decoded.get("instructionCount"),
"opcodeCounts": decoded.get("opcodeCounts") or {},
"directFrames": decoded.get("frameSequence") or [],
"initFrames": decoded.get("initFrameSequence") or [],
"resolvedFrameScripts": resolved,
"randomRanges": [row_brief(row) for row in decoded.get("randomRanges") or []],
"motionSteps": [row_brief(row) for row in decoded.get("motionSteps") or []],
"positionWrites": [row_brief(row) for row in decoded.get("positionWrites") or []],
"motionWrites": [row_brief(row) for row in decoded.get("motionWrites") or []],
"anchorWrites": [row_brief(row) for row in decoded.get("anchorWrites") or []],
"parentActorLinks": [row_brief(row) for row in decoded.get("parentActorLinks") or []],
"spawnRows": [row_brief(row) for row in decoded.get("spawnRows") or []],
"branchTargets": [row_brief(row) for row in decoded.get("branchTargets") or []],
"paletteEvents": [row_brief(row) for row in decoded.get("paletteEvents") or []],
"childrenCount": len(node.get("children") or []),
}
flat = [analyzed]
child_nodes: list[dict[str, Any]] = []
for index, child in enumerate(node.get("children") or [], 1):
child_path = f"{path}.{index}"
child_analyzed, child_flat = analyze_node(
child,
child_path,
helper_id,
skill_labels,
data,
sections,
frame_by_target,
)
child_nodes.append(child_analyzed)
flat.extend(child_flat)
analyzed["children"] = child_nodes
return analyzed, flat
def analyze_helper(
helper: dict[str, Any],
data: bytes,
sections: list[dict[str, Any]],
frame_by_target: dict[str, dict[str, Any]],
) -> dict[str, Any]:
helper_id = int(helper.get("helperId"))
skill_labels = helper_skill_labels(helper)
nodes: list[dict[str, Any]] = []
flat: list[dict[str, Any]] = []
for index, node in enumerate(helper.get("spawnTree") or [], 1):
analyzed, analyzed_flat = analyze_node(
node,
f"root.{index}",
helper_id,
skill_labels,
data,
sections,
frame_by_target,
)
nodes.append(analyzed)
flat.extend(analyzed_flat)
frame_script_targets = sorted(
{
script.get("targetVaHex")
for node in flat
for script in node.get("resolvedFrameScripts") or []
if script.get("targetVaHex")
},
key=int_hex,
)
spawn_targets = sorted({node.get("targetVaHex") for node in flat if node.get("targetVaHex")}, key=int_hex)
tags = sorted({tag for node in flat for tag in node.get("tags") or []})
return {
"helperId": helper_id,
"functionVaHex": helper.get("functionVaHex"),
"bodyClass": helper.get("bodyClass"),
"helperClass": helper.get("helperClass"),
"childScriptVaHex": helper.get("childScriptVaHex"),
"skillLabels": skill_labels,
"spawnNodeCount": len(flat),
"maxDepth": max([int(node.get("depth") or 0) for node in flat] or [0]),
"spawnTargets": spawn_targets,
"frameScriptTargets": frame_script_targets,
"tags": tags,
"nodes": nodes,
"flatNodes": flat,
}
def build() -> dict[str, Any]:
data = EXE.read_bytes()
sections = read_sections(data)
effect = read_json(EFFECT_JSON)
frame_report = read_json(FRAME_JSON)
frame_by_target = {
row.get("targetVaHex"): row
for row in frame_report.get("frameScriptRows") or []
if row.get("targetVaHex")
}
helper_rows = [
analyze_helper(helper, data, sections, frame_by_target)
for helper in effect.get("helperRows") or []
if helper.get("spawnTree")
]
all_nodes = [node for helper in helper_rows for node in helper.get("flatNodes") or []]
class_counts = Counter(node.get("primaryClass") for node in all_nodes)
tag_counts = Counter(tag for node in all_nodes for tag in node.get("tags") or [])
target_to_helpers: defaultdict[str, set[int]] = defaultdict(set)
target_to_classes: defaultdict[str, Counter[str]] = defaultdict(Counter)
target_to_skills: defaultdict[str, set[str]] = defaultdict(set)
frame_target_to_helpers: defaultdict[str, set[int]] = defaultdict(set)
frame_target_to_sources: defaultdict[str, Counter[str]] = defaultdict(Counter)
frame_target_to_labels: dict[str, list[str]] = {}
frame_target_to_duration: dict[str, int] = {}
for node in all_nodes:
target = node.get("targetVaHex")
if target:
target_to_helpers[target].add(int(node["helperId"]))
target_to_classes[target][node.get("primaryClass") or "unknown"] += 1
target_to_skills[target].update(node.get("skillLabels") or [])
for script in node.get("resolvedFrameScripts") or []:
target_hex = script.get("targetVaHex")
if not target_hex:
continue
frame_target_to_helpers[target_hex].add(int(node["helperId"]))
frame_target_to_sources[target_hex][script.get("source") or "unknown"] += 1
frame_target_to_labels.setdefault(target_hex, script.get("frameLabels") or [])
frame_target_to_duration[target_hex] = int(script.get("durationGate") or 0)
spawn_target_rows = [
{
"targetVaHex": target,
"helperIds": sorted(helpers),
"classes": dict(sorted(target_to_classes[target].items())),
"skillLabels": sorted(target_to_skills[target]),
}
for target, helpers in sorted(target_to_helpers.items(), key=lambda item: int_hex(item[0]))
]
frame_script_rows = [
{
"targetVaHex": target,
"helperIds": sorted(helpers),
"sources": dict(sorted(frame_target_to_sources[target].items())),
"frameLabels": frame_target_to_labels.get(target, []),
"durationGate": frame_target_to_duration.get(target, 0),
}
for target, helpers in sorted(frame_target_to_helpers.items(), key=lambda item: int_hex(item[0]))
]
return {
"version": 1,
"kind": "hwanse-battle-helper-spawn-tree-review",
"source": [
"Hwanse2.exe",
"out/battle_effect_object_review.json",
"out/battle_helper_frame_script_review.json",
],
"status": "spawn-tree-helper-decode",
"runtimeUsed": False,
"summary": {
"helpersWithSpawnTree": len(helper_rows),
"spawnNodes": len(all_nodes),
"uniqueSpawnTargets": len(spawn_target_rows),
"uniqueSpawnLocalFrameScriptTargets": len(frame_script_rows),
"maxDepth": max([int(row.get("maxDepth") or 0) for row in helper_rows] or [0]),
"nodeClassCounts": dict(sorted(class_counts.items())),
"nodeTagCounts": dict(sorted(tag_counts.items())),
"spawnLocalFrameScriptsDecoded": sum(
1
for row in frame_script_rows
if "spawn-local-decode" in (row.get("sources") or {})
),
},
"interpretationNotes": [
"0xbd helper body에서 시작된 child display VM은 다시 0x07로 child object를 spawn할 수 있다. 이 보고서는 그 spawn graph를 helper별로 펼친다.",
"spawnTree 내부에서만 발견되는 0x20 frameScript target 8개는 기존 root frameScript 리뷰에 빠졌지만, EXE bytes 기준으로 모두 0x21 frame/gate 스트림으로 디코드된다.",
"frameScript-emitter/direct-frame-emitter 노드는 실제 화면에 그릴 가능성이 높은 노드다. loop-controller/plain-control 노드는 타이밍/반복/제어 성격으로 보아야 한다.",
"동일 spawn target이 여러 helper에서 재사용된다. 이는 기술별로 완전히 다른 렌더러가 있는 것이 아니라, 공통 effect primitive를 helper가 조합한다는 근거다.",
"이 보고서는 damage/miss/critical 계산이 아니라 visual helper spawn side만 다룬다.",
],
"spawnTargetRows": spawn_target_rows,
"frameScriptTargetRows": frame_script_rows,
"helperRows": helper_rows,
}
def markdown(report: dict[str, Any]) -> str:
lines = [
"# Battle Helper Spawn Tree Review",
"",
f"- status: `{report['status']}`",
f"- helpers with spawn tree: `{report['summary']['helpersWithSpawnTree']}`",
f"- spawn nodes: `{report['summary']['spawnNodes']}`",
f"- unique spawn targets: `{report['summary']['uniqueSpawnTargets']}`",
f"- spawn-local frameScripts decoded: `{report['summary']['spawnLocalFrameScriptsDecoded']}`",
"",
"## Interpretation",
"",
]
lines.extend(f"- {note}" for note in report["interpretationNotes"])
lines.extend(
[
"",
"## Spawn Target Reuse",
"",
"| target | helpers | classes | skills |",
"| --- | --- | --- | --- |",
]
)
for row in report["spawnTargetRows"]:
lines.append(
f"| `{row['targetVaHex']}` | {compact(row['helperIds'], 20)} | "
f"`{row['classes']}` | {compact(row['skillLabels'], 6)} |"
)
lines.extend(
[
"",
"## Spawn-Local FrameScript Targets",
"",
"| target | helpers | source | frames@gate | duration gate |",
"| --- | --- | --- | --- | ---: |",
]
)
for row in report["frameScriptTargetRows"]:
lines.append(
f"| `{row['targetVaHex']}` | {compact(row['helperIds'], 20)} | `{row['sources']}` | "
f"{compact(row['frameLabels'], 20)} | {row['durationGate']} |"
)
lines.extend(
[
"",
"## Helper Spawn Trees",
"",
"| helper | skills | tags | spawn nodes | targets | frameScripts |",
"| ---: | --- | --- | ---: | --- | --- |",
]
)
for row in report["helperRows"]:
lines.append(
f"| {row['helperId']} | {compact(row['skillLabels'], 4)} | {compact(row['tags'], 8)} | "
f"{row['spawnNodeCount']} | {compact(row['spawnTargets'], 8)} | {compact(row['frameScriptTargets'], 8)} |"
)
return "\n".join(lines) + "\n"
def summary_table(summary: dict[str, Any]) -> str:
return "".join(f"
{esc(key)}
{esc(value)}
" for key, value in summary.items())
def frame_summary(script: dict[str, Any]) -> str:
labels = compact(script.get("frameLabels") or [], 24)
return (
f"{esc(script.get('targetVaHex'))} "
f"{esc(script.get('source'))} "
f"{esc(labels)} · gate {esc(script.get('durationGate'))}"
)
def node_detail_html(node: dict[str, Any]) -> str:
scripts = " ".join(frame_summary(script) for script in node.get("resolvedFrameScripts") or []) or "-"
direct = compact(node.get("directFrames") or node.get("initFrames") or [])
randoms = " ".join(esc(row.get("summary") or row.get("randomRange")) for row in node.get("randomRanges") or []) or "-"
motions = " ".join(esc(row.get("summary") or row.get("modeHex")) for row in node.get("motionSteps") or []) or "-"
spawns = " ".join(esc(row.get("summary")) for row in node.get("spawnRows") or []) or "-"
return (
""
f"{esc(node.get('path'))}{esc(node.get('targetVaHex'))} "
f"{esc(node.get('primaryClass'))} · {esc(compact(node.get('tags') or [], 8))}"
"
" for note in report["interpretationNotes"])
spawn_rows = "".join(
"
"
f"
{esc(row['targetVaHex'])}
"
f"
{esc(compact(row['helperIds'], 20))}
"
f"
{esc(row['classes'])}
"
f"
{esc(compact(row['skillLabels'], 8))}
"
"
"
for row in report["spawnTargetRows"]
)
frame_rows = "".join(
"
"
f"
{esc(row['targetVaHex'])}
"
f"
{esc(compact(row['helperIds'], 20))}
"
f"
{esc(row['sources'])}
"
f"
{esc(compact(row['frameLabels'], 32))}
"
f"
{esc(row['durationGate'])}
"
"
"
for row in report["frameScriptTargetRows"]
)
helper_rows = []
for row in report["helperRows"]:
node_details = "".join(node_detail_html(node) for node in row.get("flatNodes") or [])
helper_rows.append(
"