#!/usr/bin/env python3
"""Build main actor battle VM event timelines.
The helper reports expose spawned display objects. This report stays on the
main actor action VM and extracts the order of frames, result sounds, helper
calls, movement, and actor flag hit windows. It does not turn gate units into
milliseconds and it does not infer damage formulas.
"""
from __future__ import annotations
import html
import json
import re
from collections import Counter, defaultdict
from pathlib import Path
from typing import Any
ROOT = Path(__file__).resolve().parents[1]
OUT = ROOT / "out"
DISPLAY_JSON = OUT / "battle_display_vm_static_decode.json"
HELPER_OPCODE_JSON = OUT / "battle_helper_opcode_review.json"
def esc(value: Any) -> str:
return html.escape(str(value if value is not None else ""))
def vec(values: list[Any] | None, prefix: str = "") -> str:
if not values:
return "-"
return ", ".join(f"{prefix}{value}" for value in values)
def wlk_vec(values: list[Any] | None) -> str:
if not values:
return "-"
return ", ".join(f"WLK id {int(value):02d}" for value in values)
def helper_id(instr: dict[str, Any]) -> int | None:
raw = str(instr.get("bytes") or "")
parts = raw.split()
if len(parts) >= 3 and parts[0].lower() == "bd":
try:
return int(parts[1], 16) | (int(parts[2], 16) << 8)
except ValueError:
return None
match = re.search(r"id=(\d+)", str(instr.get("summary") or ""))
return int(match.group(1)) if match else None
def key_for(row: dict[str, Any]) -> tuple[str, str]:
return str(row.get("ownerKey")), str(row.get("skillIdHex")).lower()
def build_helper_index() -> dict[tuple[str, str], dict[str, Any]]:
if not HELPER_OPCODE_JSON.exists():
return {}
report = json.loads(HELPER_OPCODE_JSON.read_text(encoding="utf-8"))
return {key_for(row): row for row in report.get("rows") or []}
def lookahead_flags(rows: list[dict[str, Any]], index: int, limit: int = 20) -> tuple[list[dict[str, Any]], dict[str, Any] | None]:
flags = []
wait_row = None
for row in rows[index + 1 : index + 1 + limit]:
category = row.get("category")
if category == "sound":
break
if category == "actor-flags":
flags.append(
{
"vaHex": row.get("vaHex"),
"mode": row.get("mode"),
"maskHex": row.get("maskHex"),
"summary": row.get("summary"),
}
)
continue
if category == "wait" or row.get("opcode") in {"0xbf", "0xc1"}:
if wait_row is None:
wait_row = {
"vaHex": row.get("vaHex"),
"opcode": row.get("opcode"),
"summary": row.get("summary"),
}
continue
return flags, wait_row
def classify_hit_event(flags: list[dict[str, Any]]) -> str:
has_set = any(flag.get("mode") == 2 and flag.get("maskHex") == "0x0000000c" for flag in flags)
has_clear = any(flag.get("mode") == 1 and flag.get("maskHex") == "0x00000008" for flag in flags)
if has_set and has_clear:
return "confirmed-result-hit-window"
if has_set:
return "result-flag-set-only"
return "result-sound-only"
def expand_rows_with_repeat_loops(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
"""Expand finite 0x06 repeat-loop bodies for actor timing review.
The static decoder leaves repeat-loop rows compact. That is useful for raw
bytecode review, but the actor timeline and browser runner need the repeated
frames/sounds/flags as scheduled events. The finite repeat count is the
total number of segment executions; the body already seen before the loop row
is the first pass, so expansion appends count-1 additional passes. This
matches the EXE action payload for 지옥 다리후리기: one setup unit followed by
five attack units, not six hit executions.
"""
source_rows = list(rows or [])
expanded: list[dict[str, Any]] = []
row_index_by_va: dict[str, int] = {}
for index, row in enumerate(source_rows):
va_hex = row.get("vaHex")
if va_hex and va_hex not in row_index_by_va:
row_index_by_va[str(va_hex)] = index
for index, row in enumerate(source_rows):
expanded.append(row)
if row.get("category") != "repeat-loop":
continue
target_index = row_index_by_va.get(str(row.get("targetVaHex") or ""))
repeat_total_count = max(0, min(80, int(row.get("repeatCount") or 0)))
extra_repeat_count = max(0, repeat_total_count - 1)
if target_index is None or target_index < 0 or target_index >= index or extra_repeat_count <= 0:
continue
segment = source_rows[target_index:index]
for repeat_iteration in range(1, extra_repeat_count + 1):
for segment_row in segment:
if segment_row.get("category") == "repeat-loop":
continue
expanded.append(
{
**segment_row,
"repeatIteration": repeat_iteration,
"repeatTotalCount": repeat_total_count,
"repeatSourceVaHex": row.get("vaHex"),
}
)
return expanded
def compact_event(row: dict[str, Any], tick: int, kind: str, extra: dict[str, Any] | None = None) -> dict[str, Any]:
event = {
"tick": tick,
"kind": kind,
"vaHex": row.get("vaHex"),
"opcode": row.get("opcode"),
"summary": row.get("summary"),
}
if extra:
event.update(extra)
return {key: value for key, value in event.items() if value not in (None, "", [])}
def build_timeline(row: dict[str, Any], helper_info: dict[str, Any] | None = None) -> dict[str, Any]:
tick = 0
events: list[dict[str, Any]] = []
hit_events: list[dict[str, Any]] = []
frame_events: list[dict[str, Any]] = []
helper_calls: list[dict[str, Any]] = []
effect_sounds: list[dict[str, Any]] = []
result_sounds: list[dict[str, Any]] = []
movement_events: list[dict[str, Any]] = []
repeat_events: list[dict[str, Any]] = []
rows = expand_rows_with_repeat_loops(row.get("rows") or [])
for index, instr in enumerate(rows):
category = instr.get("category")
repeat = instr.get("repeatIteration")
repeat_extra = {"repeatIteration": repeat, "repeatSourceVaHex": instr.get("repeatSourceVaHex")} if repeat else {}
if category == "frame":
gate = int(instr.get("gate") or 0)
event = compact_event(
instr,
tick,
"actor-frame",
{"spriteHex": instr.get("spriteHex"), "frame": instr.get("frame"), "gate": gate, **repeat_extra},
)
events.append(event)
frame_events.append(event)
tick += gate
continue
if instr.get("directFrameSelector"):
event = compact_event(
instr,
tick,
"direct-frame-selector",
{"spriteHex": instr.get("spriteHex"), "frame": instr.get("frame"), "destHex": instr.get("destHex"), **repeat_extra},
)
events.append(event)
frame_events.append(event)
continue
if category == "sound":
flags, wait_row = lookahead_flags(rows, index)
event = compact_event(
instr,
tick,
"result-sound",
{
"wlkNo": instr.get("wlkNo"),
"normalWlkNo": instr.get("normalWlkNo"),
"altWlkNo": instr.get("altWlkNo"),
"mode": instr.get("mode"),
**repeat_extra,
},
)
events.append(event)
result_sounds.append(event)
hit = {
"tick": tick,
"soundVaHex": instr.get("vaHex"),
"normalWlkNo": instr.get("normalWlkNo"),
"altWlkNo": instr.get("altWlkNo"),
"mode": instr.get("mode"),
"flags": flags,
"waitAfter": wait_row,
"classification": classify_hit_event(flags),
**repeat_extra,
}
hit_events.append(hit)
continue
if category == "effect-sound":
event = compact_event(instr, tick, "effect-sound", {"wlkNo": instr.get("wlkNo"), "effectArgsHex": instr.get("effectArgsHex"), **repeat_extra})
events.append(event)
effect_sounds.append(event)
continue
if category == "cleanup/helper":
hid = helper_id(instr)
event = compact_event(instr, tick, "helper-call", {"helperId": hid, **repeat_extra})
events.append(event)
helper_calls.append(event)
continue
if category == "movement":
event = compact_event(
instr,
tick,
"movement",
{
"movementKind": instr.get("movementKind"),
"selector": instr.get("selector"),
"divisor": instr.get("divisor"),
"movementMode": instr.get("movementMode"),
**repeat_extra,
},
)
events.append(event)
movement_events.append(event)
continue
if category == "actor-flags":
events.append(compact_event(instr, tick, "actor-flag", {"mode": instr.get("mode"), "maskHex": instr.get("maskHex"), **repeat_extra}))
continue
if category == "wait" or instr.get("opcode") in {"0xbf", "0xc1"}:
events.append(compact_event(instr, tick, "wait", repeat_extra))
continue
if category == "repeat-loop":
event = compact_event(
instr,
tick,
"repeat-loop",
{"targetVaHex": instr.get("targetVaHex"), "repeatCount": instr.get("repeatCount")},
)
events.append(event)
repeat_events.append(event)
continue
if category == "write" and instr.get("destHex") in {"0x1c", "0x20", "0x28", "0x68", "0x6c", "0x74"}:
events.append(compact_event(instr, tick, "actor-write", {"destHex": instr.get("destHex"), "immHex": instr.get("immHex"), "immFixed": instr.get("immFixed"), **repeat_extra}))
return {
"durationGateFromFrames": tick,
"events": events,
"frameEvents": frame_events,
"effectSounds": effect_sounds,
"resultSounds": result_sounds,
"helperCalls": helper_calls,
"movementEvents": movement_events,
"repeatLoops": repeat_events,
"hitEvents": hit_events,
"helperInfo": helper_info or {},
}
def build() -> dict[str, Any]:
display = json.loads(DISPLAY_JSON.read_text(encoding="utf-8"))
helper_by_key = build_helper_index()
rows = []
family_groups: defaultdict[str, list[dict[str, Any]]] = defaultdict(list)
classification_counts: Counter[str] = Counter()
for decoded in display.get("decodedRows") or []:
helper_info = helper_by_key.get(key_for(decoded), {})
timeline = build_timeline(decoded, helper_info)
hit_classes = Counter(hit["classification"] for hit in timeline["hitEvents"])
classification_counts.update(hit_classes)
out_row = {
"ownerKey": decoded.get("ownerKey"),
"ownerName": decoded.get("ownerName"),
"skillName": decoded.get("skillName"),
"familyName": decoded.get("familyName"),
"skillIdHex": decoded.get("skillIdHex"),
"levelOrFixed": decoded.get("levelOrFixed"),
"entryStartVaHex": decoded.get("entryStartVaHex"),
"startSource": decoded.get("startSource"),
"confidence": decoded.get("confidence"),
"note": decoded.get("note"),
"frameSequence": [event.get("frame") for event in timeline["frameEvents"] if event.get("frame") is not None],
"soundWlkNos": [sound.get("wlkNo") for sound in decoded.get("sounds") or []],
"effectWlkNos": [sound.get("wlkNo") for sound in decoded.get("effectSounds") or []],
"helperIds": helper_info.get("helperIds") or [],
"positionClass": helper_info.get("positionClass"),
"helperRole": helper_info.get("helperRole"),
"durationGateFromFrames": timeline["durationGateFromFrames"],
"repeatLoopCount": len(timeline["repeatLoops"]),
"hitEventCount": len(timeline["hitEvents"]),
"hitClassCounts": dict(hit_classes),
"timeline": timeline,
}
rows.append(out_row)
family_groups[f"{out_row['ownerName']}::{out_row['familyName'] or out_row['skillName']}"].append(out_row)
family_rows = []
for family, items in sorted(family_groups.items()):
if len(items) < 2:
continue
family_rows.append(
{
"family": family,
"skillIds": [item["skillIdHex"] for item in items],
"durations": [item["durationGateFromFrames"] for item in items],
"hitEventCounts": [item["hitEventCount"] for item in items],
"helperIds": [item["helperIds"] for item in items],
"soundWlkNos": [item["soundWlkNos"] for item in items],
"effectWlkNos": [item["effectWlkNos"] for item in items],
"positionClasses": sorted({str(item.get("positionClass") or "") for item in items}),
}
)
return {
"version": 1,
"kind": "hwanse-battle-action-event-timeline-review",
"source": [
"out/battle_display_vm_static_decode.json",
"out/battle_helper_opcode_review.json",
],
"status": "main-actor-vm-gate-order-hit-sound-helper-timeline",
"summary": {
"rows": len(rows),
"rowsWithResultSound": sum(1 for row in rows if row["timeline"]["resultSounds"]),
"rowsWithEffectSound": sum(1 for row in rows if row["timeline"]["effectSounds"]),
"rowsWithHelperCall": sum(1 for row in rows if row["timeline"]["helperCalls"]),
"rowsWithRepeatLoops": sum(1 for row in rows if row["timeline"]["repeatLoops"]),
"rowsWithConfirmedHitWindow": sum(1 for row in rows if row["hitClassCounts"].get("confirmed-result-hit-window")),
"hitClassCounts": dict(sorted(classification_counts.items())),
},
"interpretationNotes": [
"Ticks are accumulated only from 0x21 frame gate fields. Busy waits and engine waits are shown as barriers, not converted to elapsed time.",
"Finite 0x06 repeat-loop bodies are expanded in this report. The repeat count is interpreted as total body executions, so the pre-loop body is pass #1 and only count-1 extra passes are appended.",
"A confirmed result hit window means a 0xc2 result sound is followed by 0xad mode=2 mask=0x0c and mode=1 mask=0x08 before the next frame/sound/helper.",
"0x24 is a cast/effect sound cue. 0xc2 is result/hit sound selection with normal/alt WLK candidates.",
"0xbd helper calls are listed at the actor timeline tick and should be resolved through battle_effect_object_review / battle_helper_child_script_review.",
"This report still does not decode damage, miss, critical, or status formulas. It gives the VM ordering needed to schedule the browser runner without capture-derived timing.",
],
"familyRows": family_rows,
"rows": rows,
}
def markdown(report: dict[str, Any]) -> str:
lines = [
"# Battle Action Event Timeline Review",
"",
f"- status: `{report['status']}`",
f"- rows: `{report['summary']['rows']}`",
f"- rows with confirmed hit window: `{report['summary']['rowsWithConfirmedHitWindow']}`",
"",
"## Interpretation",
"",
]
lines.extend(f"- {note}" for note in report["interpretationNotes"])
lines.extend(
[
"",
"## Skill Timelines",
"",
"| actor | skill | id | duration | frames | 0x24 WLK | 0xc2 WLK | helpers | hit events | position |",
"| --- | --- | ---: | ---: | --- | --- | --- | --- | ---: | --- |",
]
)
for row in report["rows"]:
lines.append(
f"| {row['ownerName']} | {row['skillName']} | `{row['skillIdHex']}` | {row['durationGateFromFrames']} | "
f"{vec(row['frameSequence'])} | {wlk_vec(row['effectWlkNos'])} | {wlk_vec(row['soundWlkNos'])} | "
f"{vec(row['helperIds'], '#')} | {row['hitEventCount']} | `{row.get('positionClass') or '-'}` |"
)
return "\n".join(lines) + "\n"
def events_html(events: list[dict[str, Any]], limit: int = 60) -> str:
if not events:
return "-"
rows = []
for event in events[:limit]:
detail = []
for key in ("frame", "gate", "wlkNo", "normalWlkNo", "altWlkNo", "helperId", "destHex", "immFixed", "selector", "divisor", "maskHex", "repeatIteration", "repeatTotalCount", "repeatCount"):
if event.get(key) not in (None, "", []):
detail.append(f"{key}={event.get(key)}")
rows.append(
"
"
f"
{esc(event.get('tick'))}
"
f"
{esc(event.get('kind'))}
"
f"
{esc(event.get('vaHex'))}
"
f"
{esc(', '.join(detail))}
"
f"
{esc(event.get('summary'))}
"
"
"
)
if len(events) > limit:
rows.append(f"
... +{len(events) - limit}
")
return f"
tick
kind
VA
detail
summary
{''.join(rows)}
"
def hit_events_html(hit_events: list[dict[str, Any]]) -> str:
if not hit_events:
return "-"
rows = []
for hit in hit_events:
flags = ", ".join(f"{flag.get('mode')}:{flag.get('maskHex')}" for flag in hit.get("flags") or []) or "-"
rows.append(
"
"
f"
{esc(hit.get('tick'))}
"
f"
{esc(hit.get('soundVaHex'))}
"
f"
WLK id {int(hit.get('normalWlkNo')):02d} / alt WLK id {int(hit.get('altWlkNo')):02d}