#!/usr/bin/env python3 """Summarize battle effect runner binding against the static EXE evidence. This report is intentionally about web runner implementation boundaries, not about promoting or demoting EXE evidence. The source of truth for effect requirements is battle_effect_animation_pattern_review.json; this script checks whether the active web pages are wired to the shared BattleAnimation helper pipeline that consumes helper sync/visual/position-motion data. """ from __future__ import annotations import html import json from collections import Counter, defaultdict from pathlib import Path from typing import Any ROOT = Path(__file__).resolve().parents[1] WEB = ROOT / "web" OUT = ROOT / "out" EFFECT_PATTERN = OUT / "battle_effect_animation_pattern_review.json" ENGINE = WEB / "engine" / "battle" / "animation.js" PAGES = [ WEB / "battle_skill_timeline_review.html", WEB / "battle_formula_calculator.html", WEB / "battle_simulator.html", ] OUT_JSON = OUT / "battle_effect_runner_binding_review.json" OUT_HTML = OUT / "battle_effect_runner_binding_review.html" def read(path: Path) -> str: return path.read_text(encoding="utf-8") def load_json(path: Path) -> dict[str, Any]: return json.loads(read(path)) def present(text: str, snippet: str) -> bool: return snippet in text def source_checks() -> dict[str, Any]: engine = read(ENGINE) engine_checks = { "helperEffectFrames exported": present(engine, "helperEffectFrames,"), "helper effect end extends actor hold": present(engine, "function extendFramesForHelperEffects") and present(engine, "helperEffectEndTick"), "direct/frameScript/init/nested visual merge": all( present(engine, snippet) for snippet in [ "directSource", "helper.frameScriptTimelines", "visualInitEffectFrames", "nestedVisualEffectFrames", ] ), "transform offsets and motion carried": all( present(engine, snippet) for snippet in ["offsetX", "offsetY", "motionX", "motionY", "helperEffectTransform"] ), "helper position/motion VM projection": all( present(engine, snippet) for snippet in [ "evaluateHelperVmTransform", "projectHelperEffectFrames", "helperPositionRow", "originAnchor", ] ), "shared playback builder exported": present(engine, "buildPlayerPlayback,"), } page_checks = [] for path in PAGES: text = read(path) uses_shared_playback = present(text, "BattleAnimation.buildPlayerPlayback") passes_helper_sync = present(text, "helperSyncIndex:") passes_helper_visual = present(text, "helperVisualIndex:") passes_helper_position = present(text, "helperPositionIndex:") page_checks.append( { "page": str(path.relative_to(ROOT)), "loadsCanonicalTimeline": present(text, "battle_skill_timeline_canonical.json"), "loadsHelperSync": present(text, "battle_helper_sync_timing_review.json"), "loadsHelperVisual": present(text, "battle_helper_visual_behavior_review.json"), "loadsHelperPositionMotion": present(text, "battle_helper_position_motion_review.json"), "usesSharedPlayback": uses_shared_playback, "passesHelperSyncIndex": passes_helper_sync, "passesHelperVisualIndex": passes_helper_visual, "passesHelperPositionIndex": passes_helper_position, "delegatesHelperFrames": present(text, "BattleAnimation.helperEffectFrames") or present(text, "buildEffectFrames:") or present(text, "helperEffectFrames(") or (uses_shared_playback and passes_helper_sync and passes_helper_visual), "usesSharedProjection": present(text, "BattleAnimation.projectHelperEffectFrames") or (uses_shared_playback and passes_helper_position), "usesPlaybackEffectFrames": present(text, "playback.effectFrames"), "rendersHelperEffectLayer": present(text, "drawEffectLayer") or present(text, "renderEffectStrip") or present(text, "effectFramesAtTick") or present(text, "pushPlayerHelperEffectFrames") or present(text, "playPlayerHelperEffectFrames"), "hasOnlyGenericResultEffects": present(text, "state.effects") and not present(text, "playback.effectFrames"), } ) return {"engine": engine_checks, "pages": page_checks} def requirement_summary(rows: list[dict[str, Any]]) -> list[dict[str, Any]]: buckets: dict[str, list[dict[str, Any]]] = defaultdict(list) for row in rows: for requirement in row.get("executionRequirements") or []: buckets[requirement].append(row) support_notes = { "random placement/range present": { "runnerStatus": "shared-engine-vm-projected-preview", "evidence": "BattleAnimation now consumes battle_helper_position_motion_review and projects display.x/y, target-cache, delta, and originAnchor.", "remaining": "Exact original RNG seed is not required; visual parity still depends on per-helper spawn cadence and child draw order.", }, "runner must instantiate child objects over time": { "runnerStatus": "effect-frame-stream-present-needs-per-helper-parity-review", "evidence": "helperEffectFrames merges direct spawn, frameScript, init frames, and nested spawn tree frames.", "remaining": "The renderer must keep every spawned child as an independent object over its lifetime. This is implemented for timeline preview, but complex burst skills still need visual review.", }, "child motion loop present": { "runnerStatus": "motion-fields-carried-preview-sensitive", "evidence": "Nested/direct effect frames carry motionX/motionY, motionBasis, and helper VM projection metadata.", "remaining": "The page renderer applies motion during the gate, but exact child loop integration and draw-order parity remain review targets.", }, "palette transform effect; no CNS frame stream": { "runnerStatus": "classified-separately-no-cns-frame-stream", "evidence": "Static pattern marks palette transform as an effect requirement without a CNS frame stream.", "remaining": "Renderer needs a palette/flash branch; it should not invent CNS frames.", }, } out = [] for requirement, bucket_rows in sorted(buckets.items()): owners = Counter(row.get("ownerName") for row in bucket_rows) samples = [ { "owner": row.get("ownerName"), "skill": row.get("skillName"), "skillIdHex": row.get("skillIdHex"), "levelOrFixed": row.get("levelOrFixed"), "helperIds": row.get("helperIds") or [], } for row in bucket_rows[:12] ] out.append( { "requirement": requirement, "count": len(bucket_rows), "owners": dict(sorted(owners.items())), "samples": samples, **support_notes.get( requirement, { "runnerStatus": "unclassified-runner-requirement", "evidence": "No explicit runner support note yet.", "remaining": "Classify this requirement before treating it as implemented.", }, ), } ) return out def build_report() -> dict[str, Any]: effect = load_json(EFFECT_PATTERN) rows = effect.get("skillRows") or [] checks = source_checks() report = { "version": 1, "kind": "hwanse-battle-effect-runner-binding-review", "source": "tools/build_battle_effect_runner_binding_review.py", "inputs": [ "out/battle_effect_animation_pattern_review.json", "web/engine/battle/animation.js", "web/battle_skill_timeline_review.html", "web/battle_formula_calculator.html", "web/battle_simulator.html", ], "status": "runner-binding-reviewed", "summary": { "effectSkillRows": effect.get("summary", {}).get("skillRows"), "skillsWithEffectFrames": effect.get("summary", {}).get("skillsWithEffectFrames"), "skillsWithReviewFlags": effect.get("summary", {}).get("skillsWithReviewFlags"), "skillsWithExecutionRequirements": effect.get("summary", {}).get("skillsWithExecutionRequirements"), "requirementBuckets": len(effect.get("summary", {}).get("executionRequirementCounts") or {}), "engineChecksPassed": sum(1 for value in checks["engine"].values() if value), "engineChecksTotal": len(checks["engine"]), "pageChecksPassed": sum( 1 for page in checks["pages"] for key, value in page.items() if key not in {"page", "usesPlaybackEffectFrames", "rendersHelperEffectLayer", "hasOnlyGenericResultEffects"} and value ), "pageChecksTotal": sum(len(page) - 4 for page in checks["pages"]), "pagesUsingPlaybackEffectFrames": sum(1 for page in checks["pages"] if page.get("usesPlaybackEffectFrames")), "pagesRenderingHelperEffectLayer": sum(1 for page in checks["pages"] if page.get("rendersHelperEffectLayer")), "pagesWithGenericResultEffectsOnly": sum(1 for page in checks["pages"] if page.get("hasOnlyGenericResultEffects")), }, "engineChecks": checks["engine"], "pageChecks": checks["pages"], "requirements": requirement_summary(rows), "notes": [ "This report separates EXE-confirmed effect requirements from web runner visual completeness.", "Runtime is not used here; all requirement rows come from static EXE-derived helper reports.", "A passing binding check means the pages are wired to shared helper data, not that every visual effect is pixel-perfect.", "Only pages that use playback.effectFrames and draw an effect layer are full helper-effect visual previews. Other pages may intentionally use actor-only animation plus damage/miss/heal overlays.", ], } return report def badge(text: str, good: bool | None = None) -> str: cls = "neutral" if good is None else ("ok" if good else "bad") return f"{html.escape(text)}" def html_page(report: dict[str, Any]) -> str: summary = report["summary"] engine_rows = "\n".join( f"{html.escape(name)}{badge('ok' if value else 'missing', bool(value))}" for name, value in report["engineChecks"].items() ) page_rows = [] for page in report["pageChecks"]: binding_states = [ badge(name.replace("loads", "load ").replace("uses", "use "), value) for name, value in page.items() if name not in {"page", "usesPlaybackEffectFrames", "rendersHelperEffectLayer", "hasOnlyGenericResultEffects"} ] render_states = [ badge("uses playback.effectFrames", page.get("usesPlaybackEffectFrames")), badge("renders helper effect layer", page.get("rendersHelperEffectLayer")), ] if page.get("hasOnlyGenericResultEffects"): render_states.append(badge("generic result overlays only")) page_rows.append( f"{html.escape(page['page'])}" f"{''.join(binding_states)}{''.join(render_states)}" ) req_rows = [] for req in report["requirements"]: samples = "
".join( html.escape( f"{item['owner']} {item['skill']} {item['skillIdHex']} " f"Lv={item['levelOrFixed']} helpers={item['helperIds']}" ) for item in req["samples"] ) owners = ", ".join(f"{owner}: {count}" for owner, count in req["owners"].items()) req_rows.append( "" f"{html.escape(req['requirement'])}" f"{req['count']}" f"{html.escape(owners)}" f"{badge(req['runnerStatus'])}

{html.escape(req['evidence'])}

{html.escape(req['remaining'])}

" f"{samples}" "" ) notes = "".join(f"
  • {html.escape(note)}
    • " for note in report["notes"]) return f""" Battle Effect Runner Binding Review

    Battle Effect Runner Binding Review

    EXE 정적 이펙트 요구와 현재 웹 러너의 공통 엔진 결속 상태를 분리해서 보여준다.

    홈 · effect animation patterns · skill timeline

    effect skill rows
    {summary['effectSkillRows']}
    effect frames
    {summary['skillsWithEffectFrames']}
    review flags
    {summary['skillsWithReviewFlags']}
    execution requirements
    {summary['skillsWithExecutionRequirements']}
    engine checks
    {summary['engineChecksPassed']}/{summary['engineChecksTotal']}
    page checks
    {summary['pageChecksPassed']}/{summary['pageChecksTotal']}
    effect render pages
    {summary['pagesRenderingHelperEffectLayer']}/{len(report['pageChecks'])}

    해석 기준

    공통 엔진 결속

    {engine_rows}
    checkstate

    페이지 결속

    {''.join(page_rows)}
    pagebinding checksrender checks

    실행 요구 버킷

    {''.join(req_rows)}
    requirementcountownersrunner statussamples
    """ def main() -> int: report = build_report() OUT_JSON.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") OUT_HTML.write_text(html_page(report), encoding="utf-8") print("wrote out/battle_effect_runner_binding_review.{json,html}") return 0 if __name__ == "__main__": raise SystemExit(main())