Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,9 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+engine/game/mixins/__pycache__/effect_mixin.cpython-312.pyc filter=lfs diff=lfs merge=lfs -text
+engine/lovecasim_engine.pyd filter=lfs diff=lfs merge=lfs -text
+engine/tests/cards/batches/__pycache__/test_auto_generated_strict_comprehensive.cpython-312-pytest-9.0.2.pyc filter=lfs diff=lfs merge=lfs -text
+engine/tests/cards/batches/__pycache__/test_easy_wins_batch_1.cpython-312-pytest-9.0.2.pyc filter=lfs diff=lfs merge=lfs -text
+engine/tests/cards/batches/__pycache__/test_easy_wins_batch_2.cpython-312-pytest-9.0.2.pyc filter=lfs diff=lfs merge=lfs -text
+engine/tests/scenarios/__pycache__/test_all_qas.cpython-312-pytest-9.0.2.pyc filter=lfs diff=lfs merge=lfs -text

engine/game/ACTIONS.md

@@ -0,0 +1,48 @@
+# Love Live TCG - Action Space Mapping
+
+This document defines the 2,000-dimensional action space used by the game engine. Each ID corresponds to a specific atomic action in the game.
+
+## Main Map (Sorted by ID)
+
+| ID Range | Category | Description | Parameters |
+| :--- | :--- | :--- | :--- |
+| **0** | **System** | Pass / Confirm / Skip / Cancel | N/A |
+| **1 - 180** | **Play Member** | Play a member card from hand to stage | `(Hand Index 0-59) * 3 + (Slot Index 0-2)` |
+| **200 - 202** | **Ability** | Activate a member's 【起動】 ability | `(Slot Index 0-2)` |
+| **300 - 359** | **Mulligan** | Toggle selection of a card in hand for mulligan | `(Hand Index 0-59)` |
+| **400 - 459** | **Live Set** | Set a card from hand face-down in the live zone | `(Hand Index 0-59)` |
+| **500 - 559** | **Select Hand** | Select a card in hand for an effect (e.g. discard) | `(Hand Index 0-59)` |
+| **560 - 562** | **Select Stage** | Select a member or slot on your side of the stage | `(Slot Index 0-2)` |
+| **570 - 579** | **Modal** | Select option N from a modal choice effect | `(Option Index 0-9)` |
+| **580 - 585** | **Color Select** | Select a member color (Pk, Rd, Bl, Gn, Yl, Pr) | `0=Pk, 1=Rd, 2=Bl, 3=Gn, 4=Yl, 5=Pr` |
+| **590 - 599** | **Triggers** | Choose which pending trigger to resolve next | `(Trigger Index 0-9)` |
+| **600 - 659** | **Generic List** | Select from a dynamic list (Look Deck, Deck) | `(List Index 0-59)` |
+| **660 - 719** | **Discard List** | Select a card from the discard pile (Recovery) | `(List Index 0-59)` |
+| **720 - 759** | **Formation** | Formation/Order items | `(Index 0-39)` |
+| **760 - 819** | **Success Lives**| Select from the Success Live (Score) pile | `(List Index 0-59)` |
+| **820 - 822** | **Live Zone** | Select a specific slot in the Live Zone | `(Slot Index 0-2)` |
+| **830 - 849** | **Energy Zone** | Select a specific card in the Energy Zone | `(Index 0-19)` |
+| **850 - 909** | **Removed/Opp** | Select from Removed cards or Opponent's Hand | `(Index 0-59)` |
+| **910 - 912** | **Perform** | Select which Live card to attempt performance | `(Live Zone Index 0-2)` |
+| **1000 - 1999**| **Reserved** | Reserved for future expansion | N/A |
+
+## Choice Type Mapping
+
+The engine uses `pending_choices` to contextually interpret these IDs.
+
+| Choice Type | ID Range Used | Interpretation |
+| :--- | :--- | :--- |
+| `TARGET_HAND` | 500 - 559 | Hand Index |
+| `TARGET_MEMBER` | 560 - 562 | Stage Slot Index |
+| `DISCARD_SELECT` | 500 - 559 | Hand Index |
+| `SELECT_FROM_LIST` | 600 - 659 | Index in provided `cards` list |
+| `SELECT_FROM_DISCARD`| 660 - 719 | Index in discard selection list |
+| `TARGET_OPPONENT_MEMBER`| 600 - 602 | Opponent's Slot Index |
+| `COLOR_SELECT` | 580 - 585 | Color index |
+| `MODAL` | 570 - 579 | Option index |
+
+## Design Philosophy
+
+1.  **Sparsity**: ranges are separated to allow the UI to easily map IDs to visual components without overlap.
+2.  **Compatibility**: The fixed size (2,000) is designed for MCTS and RL models to have a consistent output head.
+3.  **Extensibility**: Over 50% of the space is reserved for new card types or mechanics.

engine/game/__init__.py

@@ -0,0 +1 @@
+# Love Live Card Game - AlphaZero Engine

engine/game/ai_compat.py

@@ -0,0 +1,54 @@
+"""
+AI Compatibility Layer
+Handles optional dependencies like Numba and Torch gracefully.
+"""
+
+import importlib
+import sys
+
+
+def check_available(module_name: str) -> bool:
+    """Check if a module is available without importing it fully."""
+    try:
+        if module_name in sys.modules:
+            return True
+        return importlib.util.find_spec(module_name) is not None
+    except (ImportError, AttributeError):
+        return False
+
+
+# 1. Numba Availability
+JIT_AVAILABLE = check_available("numba")
+
+if JIT_AVAILABLE:
+    from numba import njit, prange
+else:
+    # No-op decorator fallback
+    def njit(*args, **kwargs):
+        if len(args) == 1 and len(kwargs) == 0 and callable(args[0]):
+            return args[0]  # Used as @njit
+
+        def decorator(func):
+            return func  # Used as @njit(cache=True)
+
+        return decorator
+
+    prange = range
+
+# 2. Torch Availability
+TORCH_AVAILABLE = check_available("torch")
+
+# 3. Execution Flags
+# If this is True, the engine will attempt to use JIT/Batching
+GLOBAL_AI_ENABLED = JIT_AVAILABLE
+
+
+def report_ai_status():
+    """Print current AI acceleration status."""
+    status = "ENABLED" if GLOBAL_AI_ENABLED else "DISABLED (Legacy Mode)"
+    print(f"--- AI Acceleration: {status} ---")
+    if not JIT_AVAILABLE:
+        print("  [Note] Numba not found. Install with 'pip install numba' for 200x speedup.")
+    if not TORCH_AVAILABLE:
+        print("  [Note] Torch not found. AI training will be unavailable.")
+    print("---------------------------------")

engine/game/data_loader.py

@@ -0,0 +1,71 @@
+import json
+import os
+from typing import Any, Dict, Tuple
+
+from pydantic import TypeAdapter
+
+from engine.models.card import EnergyCard, LiveCard, MemberCard
+
+
+class CardDataLoader:
+    def __init__(self, json_path: str):
+        self.json_path = json_path
+
+    def load(self) -> Tuple[Dict[int, MemberCard], Dict[int, LiveCard], Dict[int, Any]]:
+        # Auto-detect compiled file
+        target_path = self.json_path
+        if target_path.endswith("cards.json"):
+            # Check for compiled file in the same directory, or in data/
+            compiled_path = target_path.replace("cards.json", "cards_compiled.json")
+            if os.path.exists(compiled_path):
+                target_path = compiled_path
+            else:
+                root_path = os.path.join(os.getcwd(), "data", "cards_compiled.json")
+                if os.path.exists(root_path):
+                    target_path = root_path
+
+        # Fallback to relative path search if absolute fails (common in tests)
+        if not os.path.exists(target_path):
+            # Try assuming path is relative to project root
+            # But we don't know project root easily.
+            pass
+
+        # print(f"Loading card data from {target_path}...")
+        with open(target_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        members = {}
+        lives = {}
+        energy = {}
+
+        if "member_db" in data:
+            # Compiled format (v1.0)
+            m_adapter = TypeAdapter(MemberCard)
+            l_adapter = TypeAdapter(LiveCard)
+            e_adapter = TypeAdapter(EnergyCard)
+
+            for k, v in data["member_db"].items():
+                members[int(k)] = m_adapter.validate_python(v)
+
+            for k, v in data["live_db"].items():
+                # print(f"Loading live {k}")
+                lives[int(k)] = l_adapter.validate_python(v)
+            # print(f"DEBUG: Internal live_db keys: {len(data['live_db'])}, loaded: {len(lives)}")
+
+            for k, v in data["energy_db"].items():
+                energy[int(k)] = e_adapter.validate_python(v)
+
+            # --- HOTFIXES REMOVED (Parser is now accurate) ---
+            for l in lives.values():
+                pass
+
+        else:
+            # Legacy raw format
+            # Since we removed runtime parsing from the engine to separate concerns,
+            # we cannot load raw cards anymore.
+            raise RuntimeError(
+                "Legacy cards.json format detected. Runtime parsing is disabled. "
+                "Please run 'uv run compiler/main.py' to generate 'data/cards_compiled.json'."
+            )
+
+        return members, lives, energy

engine/game/deck_utils.py

@@ -0,0 +1,95 @@
+import os
+import re
+from collections import Counter
+
+
+def extract_deck_data(content: str, card_db: dict):
+    """
+    Parses deck content (HTML or various text formats) to extract card IDs and quantities.
+    Returns (main_deck, energy_deck, type_counts, errors)
+    """
+    # 1. Try HTML Structure (Deck Log)
+    # pattern matches: title="PL!xxx-yyy-zzz : NAME" ... <span class="num">N</span>
+    pattern_html = r'title="([^"]+?) :[^"]*"[^>]*>.*?class="num">(\d+)</span>'
+    matches = re.findall(pattern_html, content, re.DOTALL)
+
+    if not matches:
+        # Fallback 1: Text format "QTY x ID" (e.g., "4 x LL-bp3-001-R＋")
+        text_pattern_1 = r"(\d+)\s*[xX]\s*([A-Za-z0-9!+\-＋]+)"
+        matches_1 = re.findall(text_pattern_1, content)
+        if matches_1:
+            # Swap to (ID, Qty) format
+            matches = [(m[1], m[0]) for m in matches_1]
+        else:
+            # Fallback 2: Text format "ID x QTY" (e.g., "PL!S-bp2-022-L x 2")
+            text_pattern_2 = r"([A-Za-z0-9!+\-＋]+)\s*[xX]\s*(\d+)"
+            matches_2 = re.findall(text_pattern_2, content)
+            if matches_2:
+                matches = matches_2
+            else:
+                # Fallback 3: Simple list of IDs (one per line)
+                # Matches strings like "PL!S-bp1-001-M" but avoids common words
+                # This is risky but useful for simple text files.
+                # Let's use a more specific regex for ID patterns.
+                id_pattern = r"([PL!|LL\-E][A-Za-z0-9!+\-＋]+-[A-Za-z0-9!+\-＋]+-[A-Za-z0-9!+\-＋]+[A-Za-z0-9!+\-＋]*)"
+                matches_3 = re.findall(id_pattern, content)
+                if matches_3:
+                    # Count occurrences
+                    counts = Counter(matches_3)
+                    matches = [(cid, str(cnt)) for cid, cnt in counts.items()]
+
+    if not matches:
+        return [], [], {}, ["No recognizable card data found in content."]
+
+    main_deck = []
+    energy_deck = []
+    type_counts = {"Member": 0, "Live": 0, "Energy": 0, "Unknown": 0}
+    errors = []
+
+    for card_id, qty_str in matches:
+        try:
+            qty = int(qty_str)
+        except ValueError:
+            continue
+
+        card_id = card_id.strip()
+
+        # Determine Type from database
+        cdata = card_db.get(card_id, {})
+        ctype = cdata.get("type", "")
+
+        if "メンバー" in ctype or "Member" in ctype:
+            type_counts["Member"] += qty
+        elif "ライブ" in ctype or "Live" in ctype:
+            type_counts["Live"] += qty
+        elif "エネルギー" in ctype or "Energy" in ctype:
+            type_counts["Energy"] += qty
+        else:
+            type_counts["Unknown"] += qty
+
+        for _ in range(qty):
+            if "エネルギー" in ctype or "Energy" in ctype or card_id.startswith("LL-E"):
+                energy_deck.append(card_id)
+            else:
+                main_deck.append(card_id)
+
+    # Basic Validation
+    all_counts = Counter(main_deck + energy_deck)
+    for cid, count in all_counts.items():
+        if count > 4 and not cid.startswith("LL-E"):
+            # Some formats might have duplicates if listing line-by-line + QTY.
+            # We don't block here, just warn.
+            errors.append(f"Card limit exceeded: {cid} x{count} (Max 4)")
+
+    return main_deck, energy_deck, type_counts, errors
+
+
+def load_deck_from_file(file_path: str, card_db: dict):
+    """Helper to read a file and parse it."""
+    if not os.path.exists(file_path):
+        return None, None, {}, [f"File {file_path} not found."]
+
+    with open(file_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    return extract_deck_data(content, card_db)

engine/game/desc_utils.py

@@ -0,0 +1,466 @@
+from engine.game.enums import Phase
+from engine.game.state_utils import get_base_id
+
+
+def get_action_desc(a, gs):
+    """
+    Generate clear, informative action descriptions.
+    Shows card names, costs, and ability sources for better user understanding.
+    """
+    if gs is None:
+        return f"Action {a}"
+
+    # Handle both Python and Rust engine (PyGameState)
+    if hasattr(gs, "get_player"):
+        p_idx = gs.current_player
+        p = gs.get_player(p_idx)
+    else:
+        p = gs.active_player
+        p_idx = gs.current_player
+
+    member_db = gs.member_db
+    live_db = gs.live_db
+
+    # Helper to get from DB, handling int/str keys
+    def get_from_db(db, key, default=None):
+        if not db:
+            return default
+        if hasattr(db, "get"):
+            res = db.get(key)
+            if res is not None:
+                return res
+            return db.get(str(key), default)
+        try:
+            if key in db:
+                return db[key]
+            if str(key) in db:
+                return db[str(key)]
+        except:
+            pass
+        return default
+
+    # Helper to get card name
+    def get_card_name(cid, gs_override=None):
+        _gs = gs_override or gs
+        if cid < 0:
+            return "なし"
+
+        base_id = get_base_id(int(cid))
+
+        # Try all DBs with the helper
+        m = get_from_db(member_db, base_id)
+        if m:
+            name = get_v(m, "name", f"メンバー #{base_id}")
+            card_no = get_v(m, "card_no", "??")
+            return f"{name} ({card_no})"
+
+        l = get_from_db(live_db, base_id)
+        if l:
+            name = get_v(l, "name", f"ライブ #{base_id}")
+            card_no = get_v(l, "card_no", "??")
+            return f"{name} ({card_no})"
+
+        e = get_from_db(getattr(_gs, "energy_db", None), base_id)
+        if e:
+            name = get_v(e, "name", f"エネルギー #{base_id}")
+            card_no = get_v(e, "card_no", "??")
+            return f"{name} ({card_no})"
+
+        return f"カード #{cid}"
+
+    # Helpers for general property access
+    def get_v(obj, key, default=None):
+        if obj is None:
+            return default
+        if isinstance(obj, dict):
+            return obj.get(key, default)
+        return getattr(obj, key, default)
+
+    # Helper for pending choices
+    def get_top_pending():
+        if not gs.pending_choices:
+            return None, {}
+        choice_type, params = gs.pending_choices[0]
+        if isinstance(params, str):
+            import json
+
+            try:
+                return choice_type, json.loads(params)
+            except:
+                return choice_type, {}
+        return choice_type, params
+
+    # --- ACTION HANDLERS (Order Matters: Specific to General) ---
+    # The order of these blocks determines priority. Specific contextual handlers
+    # (like Color selection or Discard/Recover) must come BEFORE broad ranges
+    # to avoid being shadowed by more generic messages.
+
+    # 1. SPECIAL & UNIVERSAL ACTIONS
+    # --------------------------------------------------------------------------
+
+    # Action 0: Pass / Confirm / Skip
+    # Used for ending phases (Main, LiveSet, Mulligan) or skipping optional effects.
+    if a == 0:
+        if int(gs.phase) == int(Phase.MAIN):
+            return "【終了】メインフェイズを終了する"
+        if int(gs.phase) == int(Phase.LIVE_SET):
+            return "【確認】ライブカードをセットして続行"
+        if int(gs.phase) == int(Phase.LIVE_RESULT):
+            return "【進む】次へ進む"
+        if int(gs.phase) in (int(Phase.MULLIGAN_P1), int(Phase.MULLIGAN_P2)):
+            return "【確認】マリガンを実行"
+        choice_type, params = get_top_pending()
+        if choice_type:
+            source_name = params.get("source_member", "アビリティ")
+            return f"【スキップ】{source_name}の効果を使用しない"
+        return "【パス】何もしない"
+
+    # 2. SPECIFIC INTERACTIVE SELECTIONS (Must precede broad ranges)
+    # --------------------------------------------------------------------------
+
+    # 580-585: Color Selection
+    # Triggered by O_COLOR_SELECT. Maps to Pink, Red, Yellow, Green, Blue, Purple.
+    if 580 <= a <= 585:
+        colors = ["赤", "青", "緑", "黄", "紫", "ピンク"]
+        return f"【色選択】 {colors[a - 580]}"
+
+    # 560-562: Stage Slot Selection (Targeting/Wait)
+    # Triggered when choosing a slot on the player's own stage for an effect.
+    if 560 <= a <= 562:
+        idx = a - 560
+        areas = ["左", "センター", "右"]
+        cid = p.stage[idx]
+        name = "空エリア"
+        base_id = get_base_id(int(cid))
+        if cid >= 0:
+            m = get_from_db(member_db, base_id)
+            if m:
+                name = get_v(m, "name", "メン��ー")
+
+        desc = "選択"
+        choice_type, params = get_top_pending()
+        if choice_type:
+            if choice_type == "MOVE_MEMBER":
+                desc = "移動元"
+            elif choice_type == "TAP_MEMBER":
+                desc = "ウェイト"
+            elif choice_type in ("PLAY_MEMBER_FROM_HAND", "PLAY_MEMBER_FROM_DISCARD"):
+                desc = "に置く"
+        return f"【ステージ選択】 {areas[idx]}: {name}を{desc}"
+
+    # 500-509: Hand Card Selection (Discard/Recover)
+    # Triggered when specifically selecting a card from hand as an effect cost or target.
+    # Note: Normal playing of cards (1-180) is handled separately.
+    if 500 <= a <= 509:
+        idx = a - 500
+        if idx < len(p.hand):
+            cid = p.hand[idx]
+            name = get_card_name(cid)
+            desc = "選択"
+            choice_type, params = get_top_pending()
+            if choice_type:
+                if choice_type == "RECOVER_MEMBER":
+                    desc = "回収"
+                elif choice_type == "DISCARD":
+                    desc = "捨てる"
+            return f"【手札選択】 {name}を{desc}"
+
+    # 570-579: Mode Selection (Branching Effects)
+    # Triggered by O_SELECT_MODE when a card offers multiple choices (e.g., Mode A/B).
+    if 570 <= a <= 579:
+        mode_label = f"モード {a - 570 + 1}"
+        choice_type, params = get_top_pending()
+        if choice_type:
+            options = params.get("options", [])
+            if a - 570 < len(options):
+                mode_label = options[a - 570]
+        return f"【モード選択】 {mode_label}"
+
+    # 590-599: Ability Trigger/Resolution Order
+    # Triggered when multiple abilities are pending (e.g., [OnPlay] triggers).
+    if 590 <= a <= 599:
+        idx = a - 590
+        if idx < len(gs.triggered_abilities):
+            t = gs.triggered_abilities[idx]
+            if len(t) >= 2:
+                cid = getattr(t[2], "card_id", -1) if len(t) > 2 else -1
+                src_name = get_card_name(cid) if cid >= 0 else "不明"
+                return f"【能力解決】 {src_name}の効果を発動 ({idx + 1}/{len(gs.triggered_abilities)})"
+        return f"【能力解決】 ({idx + 1}/{len(gs.triggered_abilities)})"
+
+    # 820-822: Live Zone Targeting
+    if 820 <= a <= 822:
+        idx = a - 820
+        areas = ["左", "センター", "右"]
+        cid = p.live_zone[idx] if idx < len(p.live_zone) else -1
+        name = "なし"
+        if cid >= 0:
+            name = get_card_name(cid)
+        return f"【ライブ選択】 {areas[idx]}: {name}"
+
+    # 900-902: Performance Execution
+    # Standard action to clear a Live card in the Performance phase.
+    if 900 <= a <= 902:
+        idx = a - 900
+        areas = ["左", "センター", "右"]
+        cid = p.live_zone[idx] if idx < len(p.live_zone) else -1
+        name = "なし"
+        summary = "パフォーマンス"
+        if cid >= 0:
+            name = get_card_name(cid)
+            base_id = get_base_id(cid)
+            live = get_from_db(live_db, base_id)
+            if live:
+                abilities = get_v(live, "abilities", [])
+                if abilities:
+                    raw_text = get_v(abilities[0], "raw_text", "").strip()
+                    if raw_text:
+                        summary = raw_text.split("\n")[0][:40]
+                        if len(raw_text) > 40:
+                            summary += "..."
+        return f"【パフォーマンス】 {areas[idx]}: {name} ({summary})"
+
+    # 600-719: Broad Choice Range (General Targets/Opponent)
+    if 600 <= a <= 719:
+        idx = a - 600
+        choice_type, params = get_top_pending()
+        if choice_type == "ORDER_DECK":
+            cards = params.get("cards", [])
+            if idx < len(cards):
+                return f"【並べ替え】 {get_card_name(cards[idx])}を一番上へ"
+            return "【確定】 並び替えを終了"
+
+        if 0 <= idx <= 2:
+            if choice_type in ("SELECT_MEMBER", "TARGET_OPPONENT_MEMBER"):
+                areas = ["左", "センター", "右"]
+                opp = gs.get_player(1 - p_idx) if hasattr(gs, "get_player") else gs.inactive_player
+                cid = opp.stage[idx]
+                name = "空エリア"
+                if cid >= 0:
+                    base_id = get_base_id(int(cid))
+                    m = get_from_db(member_db, base_id)
+                    if m:
+                        name = get_v(m, "name", "メンバー")
+                return f"【ターゲット】 相手のステージ ({areas[idx]}: {name}) を選択"
+
+        if choice_type == "SELECT_FROM_LIST":
+            cards = params.get("cards", [])
+            if idx < len(cards):
+                return f"【リスト選択】 {get_card_name(cards[idx])}"
+        elif choice_type == "SELECT_MODE":
+            options = params.get("options", [])
+            if idx < len(options):
+                return f"【選択】 {options[idx]}"
+        elif choice_type == "SELECT_SUCCESS_LIVE":
+            cards = params.get("cards", [])
+            if idx < len(cards):
+                return f"【獲得選択】 {get_card_name(cards[idx])}"
+        elif choice_type == "SELECT_FROM_DISCARD":
+            cards = params.get("cards", [])
+            if idx < len(cards):
+                return f"【控え室回収】 {get_card_name(cards[idx])}"
+
+        return f"【選択】 項目 {idx}"
+
+    # 550-849: Complex Choice Resolution (Consolidated)
+    # Used for choices that require specific card/slot context (e.g., Order Deck, Color Choose).
+    if 550 <= a <= 849:
+        adj = a - 550
+        area_idx = adj // 100
+        ab_idx = (adj % 100) // 10
+        choice_idx = adj % 10
+
+        area_name = ["左", "中", "右"][area_idx] if area_idx < 3 else f"Slot {area_idx}"
+        cid = p.stage[area_idx] if area_idx < 3 else -1
+        card_name = "メンバー"
+        if cid >= 0:
+            base_id = get_base_id(cid)
+            m = get_from_db(member_db, base_id)
+            if m:
+                card_name = get_v(m, "name", "メンバー")
+
+        choice_type, params = get_top_pending()
+        choice_label = f"選択 {choice_idx}"
+        if choice_type == "ORDER_DECK":
+            cards = params.get("cards", [])
+            if choice_idx < len(cards):
+                choice_label = f"デッキトップ: {get_card_name(cards[choice_idx])}"
+            else:
+                choice_label = "[確定]"
+        elif choice_type == "COLOR_SELECT":
+            colors = ["赤", "青", "緑", "黄", "紫", "ピンク"]
+            if choice_idx < len(colors):
+                choice_label = f"色選択: {colors[choice_idx]}"
+        elif choice_type == "SELECT_MODE":
+            options = params.get("options", [])
+            if choice_idx < len(options):
+                choice_label = options[choice_idx]
+            else:
+                choice_label = f"モード {choice_idx + 1}"
+        elif choice_type == "SELECT_FROM_LIST":
+            cards = params.get("cards", [])
+            if choice_idx < len(cards):
+                choice_label = f"選択: {get_card_name(cards[choice_idx])}"
+
+        return f"[{card_name}] {choice_label} ({area_name})"
+
+    # 3. PHASE-SPECIFIC CORE ACTIONS (Main Range)
+    # --------------------------------------------------------------------------
+
+    # 1-180: Playing Members (Main Phase)
+    # Each hand index has 3 target slots: aid = 1 + (hand_idx * 3) + slot_idx
+    if 1 <= a <= 180 and int(gs.phase) == int(Phase.MAIN):
+        idx = (a - 1) // 3
+        area_idx = (a - 1) % 3
+        areas = ["左", "センター", "右"]
+        area_name = areas[area_idx]
+        card_name = f"カード[{idx}]"
+        new_card_cost = 0
+        suffix = ""
+        if idx < len(p.hand):
+            cid = p.hand[idx]
+            base_cid = get_base_id(int(cid))
+            m = get_from_db(member_db, base_cid)
+            if m:
+                card_name = get_v(m, "name", "メンバー")
+                new_card_cost = get_v(m, "cost", 0)
+                abilities = get_v(m, "abilities", [])
+                if any(get_v(ab, "trigger", 0) == 1 for ab in abilities):
+                    suffix = " [登場]"
+
+        stage_cid = p.stage[area_idx]
+        if stage_cid >= 0:
+            base_stage_cid = get_base_id(int(stage_cid))
+            old_card = get_from_db(member_db, base_stage_cid)
+            if old_card:
+                old_name = get_v(old_card, "name", "メンバー")
+                old_cost = get_v(old_card, "cost", 0)
+                actual_cost = max(0, new_card_cost - old_cost)
+                return f"【{area_name}に置く】 {card_name}{suffix} (バトンタッチ: {old_name}退場, 支払:{actual_cost})"
+        return f"【{area_name}に置く】 {card_name}{suffix} (コスト {new_card_cost})"
+
+    # 100-159: Energy Charge Selection
+    if 100 <= a <= 159 and int(gs.phase) == int(Phase.ENERGY):
+        idx = a - 100
+        card_name = f"手札[{idx}]"
+        if idx < len(p.hand):
+            card_name = get_card_name(p.hand[idx])
+        return f"【エネルギー】 {card_name}をチャージ"
+
+    # 300-359: Mulligan Selection
+    # Toggles cards to be shuffled back during the mulligan phase.
+    if 300 <= a <= 359:
+        idx = a - 300
+        card_name = f"手札[{idx}]"
+        if idx < len(p.hand):
+            card_name = get_card_name(p.hand[idx])
+        return f"【マリガン】 {card_name}を選択/解除"
+
+    # 400-459: Live Set Selection
+    # Sets a Live card from hand to face-up or face-down zone.
+    if 400 <= a <= 459:
+        idx = a - 400
+        card_name = f"手札[{idx}]"
+        score_text = ""
+        if idx < len(p.hand):
+            cid = p.hand[idx]
+            card_name = get_card_name(cid)
+            base_id = get_base_id(cid)
+            live = get_from_db(live_db, base_id)
+        return f"【ライブセット】 {card_name}{score_text}"
+
+    # 200-299: Activated Ability on Stage
+    # [起動] abilities triggered manually by the player.
+    if 200 <= a <= 299:
+        adj = a - 200
+        area_idx = adj // 10
+        ab_idx = adj % 10
+        areas = ["左", "センター", "右"]
+        area_name = areas[area_idx] if area_idx < 3 else f"Slot {area_idx}"
+        cid = p.stage[area_idx] if area_idx < 3 else -1
+        if cid >= 0:
+            base_cid = get_base_id(int(cid))
+            member = get_from_db(member_db, base_cid)
+            if member:
+                card_name = get_v(member, "name", "メンバー")
+                abilities = get_v(member, "abilities", [])
+                summary = "アビリティ"
+                if len(abilities) > ab_idx:
+                    ab = abilities[ab_idx]
+                    raw_text = get_v(ab, "raw_text", "").strip()
+                    if raw_text:
+                        summary = raw_text.split("\n")[0][:40]
+                        if len(raw_text) > 40:
+                            summary += "..."
+                return f"【起動】{card_name}: {summary} ({area_name})"
+        return f"Ability ({area_name})"
+
+    # 2000-2999: Discard Pile Activation
+    # Playing or activating effects of cards currently in the discard zone.
+    if 2000 <= a <= 2999:
+        adj = a - 2000
+        discard_idx = adj // 10
+        ab_idx = adj % 10
+        card_name = f"控え室[{discard_idx}]"
+        if discard_idx < len(p.discard):
+            cid = p.discard[discard_idx]
+            card_name = get_card_name(cid)
+            base_id = get_base_id(cid)
+            member = get_from_db(member_db, base_id)
+            if member:
+                abilities = get_v(member, "abilities", [])
+                if len(abilities) > ab_idx:
+                    ab = abilities[ab_idx]
+                    raw_text = get_v(ab, "raw_text", "").strip()
+                    summary = raw_text.split("\n")[0][:40] if raw_text else "効果"
+                    return f"【控え召喚】 {card_name}: {summary}"
+        return f"【控え召喚】 {card_name}"
+
+    # 1000-1999: OnPlay Sub-Choices
+    # Options offered immediately during/after a member is played.
+    if 1000 <= a <= 1999:
+        adj = a - 1000
+        hand_idx = adj // 100
+        slot_idx = (adj % 100) // 10
+        choice_idx = adj % 10
+
+        choice_label = f"選択 {choice_idx}"
+
+        choice_type, params = get_top_pending()
+        if choice_type == "ORDER_DECK":
+            cards = params.get("cards", [])
+            if choice_idx < len(cards):
+                choice_label = f"{get_card_name(cards[choice_idx])}をトップへ"
+            else:
+                choice_label = "[確定]"
+        elif choice_type == "COLOR_SELECT":
+            colors = ["赤", "青", "緑", "黄", "紫", "ピンク"]
+            if choice_idx < len(colors):
+                choice_label = f"{colors[choice_idx]}を選択"
+        elif choice_type == "SELECT_MODE":
+            options = params.get("options", [])
+            if choice_idx < len(options):
+                choice_label = options[choice_idx]
+            else:
+                choice_label = f"モード {choice_idx + 1}"
+        elif choice_type == "SELECT_FROM_LIST":
+            cards = params.get("cards", [])
+            if choice_idx < len(cards):
+                choice_label = f"{get_card_name(cards[choice_idx])}を選択"
+
+        return choice_label
+
+    # 4. FALLBACKS
+    # --------------------------------------------------------------------------
+
+    # 510-559: Generic Hand Selection Fallback
+    if 510 <= a <= 559:
+        idx = a - 500  # Keep idx logic consistent with 500-509
+        card_name = f"手札[{idx}]"
+        if idx < len(p.hand):
+            card_name = get_card_name(p.hand[idx])
+        return f"【手札選択】 {card_name}"
+
+    return f"Action {a}"
+
+    return f"Action {a}"

engine/game/enums.py

@@ -0,0 +1,27 @@
+from enum import IntEnum
+
+
+class Phase(IntEnum):
+    """Game phases within a turn (Rule 7).
+
+    Flow: MULLIGAN_P1 -> MULLIGAN_P2 -> ACTIVE -> ENERGY -> DRAW -> MAIN
+          -> LIVE_SET -> PERFORMANCE_P1 -> PERFORMANCE_P2 -> LIVE_RESULT
+          -> ACTIVE (next turn)
+
+    Note: SETUP (-2) is reserved for potential future use (pregame setup).
+    Games currently start directly at MULLIGAN_P1.
+    """
+
+    SETUP = -2
+    MULLIGAN_P1 = -1
+    MULLIGAN_P2 = 0
+    ACTIVE = 1
+    ENERGY = 2
+    DRAW = 3
+    MAIN = 4
+    LIVE_SET = 5
+    PERFORMANCE_P1 = 6
+    PERFORMANCE_P2 = 7
+    LIVE_RESULT = 8
+    TERMINAL = 9
+    RESPONSE = 10

engine/game/fast_logic.py

@@ -0,0 +1,2209 @@
+import warnings
+
+import numpy as np
+from numba import njit, prange
+
+# Suppress Numba cache warnings (harmless in testing environments)
+warnings.filterwarnings("ignore", message=".*'cache' is set for njit and is ignored.*")
+
+# =============================================================================
+# HYPER-OPTIMIZED VM CORE (Production Version)
+# =============================================================================
+
+# ContextIndex Mappings (Raw Ints)
+CV = 20
+AT = 22
+TS = 12
+TI = 13
+SZ = 7
+CH = 15
+SID = 5
+
+# Backward compatibility aliases
+CTX_VALUE = CV
+CTX_ATTR = AT
+CTX_TARGET_SLOT = TS
+CTX_TARGET_PLAYER_ID = TI
+CTX_SOURCE_ZONE_IDX = SZ
+CTX_CHOICE_INDEX = CH
+
+# GlobalContext Mappings
+SC = 0
+OS = 1
+TR = 2
+HD = 3
+DI = 4
+EN = 5
+DK = 6
+OT = 7
+OT = 7
+PH = 8
+LS = 110  # Live Score Bonus (Temporary, moved to 110 to avoid conflict with OD)
+EH = 111  # Excess Hearts (Current Live Performance)
+PREV_CID_IDX = 60  # Previous Card ID for Baton Pass (Index 60)
+
+# Unique ID (UID) System
+BASE_ID_MASK = 0xFFFFF
+
+
+@njit(inline="always")
+def get_base_id(uid: int) -> int:
+    """Extract the base card definition ID (0-1999) from a UID."""
+    return uid & BASE_ID_MASK
+
+
+# Opcodes
+O_DRAW = 10
+O_BLADES = 11
+O_HEARTS = 12
+O_REDUCE_COST = 13
+O_LOOK_DECK = 14
+O_RECOV_L = 15
+O_BOOST = 16
+O_RECOV_M = 17
+O_BUFF = 18
+O_MOVE_MEMBER = 20
+O_SWAP_CARDS = 21
+O_SEARCH_DECK = 22
+O_CHARGE = 23
+O_ORDER_DECK = 28
+O_SET_BLADES = 24
+O_SELECT_MODE = 30
+O_TAP_O = 32
+O_PLACE_UNDER = 33
+O_LOOK_AND_CHOOSE = 41
+O_ACTIVATE_MEMBER = 43
+O_ADD_H = 44
+O_REPLACE_EFFECT = 46
+O_TRIGGER_REMOTE = 47
+O_TRANSFORM_COLOR = 39
+O_TAP_M = 53
+O_REDUCE_HEART_REQ = 48
+O_REVEAL_CARDS = 26
+O_MOVE_TO_DISCARD = 58
+O_RETURN = 1
+O_JUMP = 2
+O_JUMP_F = 3
+O_REVEAL_HAND_ALL = 6  # Cost Type (Internal reminder)
+
+# Conditions
+C_TR1 = 200
+C_CLR = 202
+C_STG = 203
+C_HND = 204
+C_CTR = 206
+C_LLD = 207
+C_GRP = 208
+C_OPH = 210
+C_ENR = 213
+C_OPH = 210
+C_ENR = 213
+C_CMP = 220
+C_BLD = 224
+C_HRT = 223
+C_HAS_CHOICE = 221
+C_OPPONENT_CHOICE = 222
+C_BATON = 231  # Baton Pass condition (ID 231)
+
+# Conditions
+C_TR1 = 200
+C_CLR = 202
+C_STG = 203
+C_HND = 204
+C_CTR = 206
+C_LLD = 207
+C_GRP = 208
+C_OPH = 210
+C_ENR = 213
+C_OPH = 210
+C_ENR = 213
+C_CMP = 220
+C_BLD = 224
+C_HRT = 223
+C_HAS_CHOICE = 221
+C_OPPONENT_CHOICE = 222
+
+
+@njit(nopython=True, cache=True, fastmath=True)
+def resolve_bytecode(
+    bytecode,
+    flat_ctx,
+    global_ctx,
+    player_id,
+    p_hand,
+    p_deck,
+    p_stage,
+    p_energy_vec,
+    p_energy_count,
+    p_cont_vec,
+    out_cptr,  # Modified: Pass by ref array (size 1)
+    p_tapped,
+    p_live,
+    opp_tapped,
+    p_trash,  # Added
+    b_map,
+    b_idx,
+    out_bonus,  # Modified: Pass by ref array (size 1)
+    card_stats,  # Added: NumPy array for card properties
+    opp_stage,  # Added
+    opp_tapped_count=None,  # Optional tracking
+):
+    # Manual Stack Unrolling (Depth 4) - Eliminates allocations in hot loop
+    stack_ptr = 0
+
+    bc0 = bytecode
+    ip0 = 0
+    bc1 = bytecode
+    ip1 = 0
+    bc2 = bytecode
+    ip2 = 0
+    bc3 = bytecode
+    ip3 = 0
+
+    cptr = out_cptr[0]
+    cond = True
+    safety_counter = 0
+
+    while stack_ptr >= 0 and safety_counter < 1000:
+        safety_counter += 1
+
+        # Current Frame Selection (Type-stable for Numba)
+        if stack_ptr == 0:
+            cur_bc = bc0
+            ip = ip0
+        elif stack_ptr == 1:
+            cur_bc = bc1
+            ip = ip1
+        elif stack_ptr == 2:
+            cur_bc = bc2
+            ip = ip2
+        else:
+            cur_bc = bc3
+            ip = ip3
+
+        blen = cur_bc.shape[0]
+
+        if ip >= blen:
+            stack_ptr -= 1
+            continue
+
+        op = cur_bc[ip, 0]
+        v = cur_bc[ip, 1]
+        a = cur_bc[ip, 2]
+        s = cur_bc[ip, 3]
+
+        # Advance IP logic: Pre-increment local copy
+        next_ip = ip + 1
+        if stack_ptr == 0:
+            ip0 = next_ip
+        elif stack_ptr == 1:
+            ip1 = next_ip
+        elif stack_ptr == 2:
+            ip2 = next_ip
+        else:
+            ip3 = next_ip
+
+        if op == 0:
+            continue
+        if op == O_RETURN:
+            stack_ptr -= 1
+            continue
+
+        # Negation Flag Handling
+        is_negated = False
+        if op >= 1000:
+            is_negated = True
+            op -= 1000
+
+        # Dynamic Target Handling (MEMBER_SELECT)
+        if s == 10:
+            s = int(flat_ctx[TS])
+
+        if op == O_JUMP:
+            new_ip = ip + v
+            if stack_ptr == 0:
+                ip0 = new_ip if 0 <= new_ip < blen else blen
+            elif stack_ptr == 1:
+                ip1 = new_ip if 0 <= new_ip < blen else blen
+            elif stack_ptr == 2:
+                ip2 = new_ip if 0 <= new_ip < blen else blen
+            else:
+                ip3 = new_ip if 0 <= new_ip < blen else blen
+            continue
+
+        if op == O_JUMP_F:
+            if not cond:
+                new_ip = ip + v
+                if stack_ptr == 0:
+                    ip0 = new_ip if 0 <= new_ip < blen else blen
+                elif stack_ptr == 1:
+                    ip1 = new_ip if 0 <= new_ip < blen else blen
+                elif stack_ptr == 2:
+                    ip2 = new_ip if 0 <= new_ip < blen else blen
+                else:
+                    ip3 = new_ip if 0 <= new_ip < blen else blen
+                continue
+            continue
+
+        if op == O_SELECT_MODE:
+            choice = int(flat_ctx[CH])
+            jumped = False
+            if 0 <= choice < v:
+                jump_ip = ip + 1 + choice
+                if jump_ip < blen:
+                    offset = cur_bc[jump_ip, 1]
+                    new_ip = jump_ip + offset
+                    if 0 <= new_ip < blen:
+                        if stack_ptr == 0:
+                            ip0 = new_ip
+                        elif stack_ptr == 1:
+                            ip1 = new_ip
+                        elif stack_ptr == 2:
+                            ip2 = new_ip
+                        else:
+                            ip3 = new_ip
+                        jumped = True
+            if not jumped:
+                new_ip = ip + (v + 1)
+                if stack_ptr == 0:
+                    ip0 = new_ip
+                elif stack_ptr == 1:
+                    ip1 = new_ip
+                elif stack_ptr == 2:
+                    ip2 = new_ip
+                else:
+                    ip3 = new_ip
+            continue
+
+        if op >= 200:
+            if op == C_TR1:
+                cond = global_ctx[TR] == 1
+            elif op == C_STG:
+                ct = 0
+                for i in range(3):
+                    if p_stage[i] != -1:
+                        ct += 1
+                cond = ct >= v
+            elif op == C_HND:
+                cond = global_ctx[HD] >= v
+            elif op == C_LLD:
+                cond = global_ctx[SC] > global_ctx[OS]
+            elif op == C_CLR:
+                if 0 <= a <= 5:
+                    cond = global_ctx[10 + a] > 0
+                else:
+                    cond = False
+            elif op == C_GRP:
+                # C_GRP: Count cards of a group on stage or live zone
+                # v = min count, a = group ID, s = zone (0=stage, 1=live)
+                target_group = a
+                grp_count = 0
+                if s == 0:  # Stage
+                    for slot_k in range(3):
+                        cid = p_stage[slot_k]
+                        if cid >= 0:
+                            bid = get_base_id(cid)
+                            if bid < card_stats.shape[0]:
+                                # Groups are stored at index 6 (primary group)
+                                if card_stats[bid, 6] == target_group:
+                                    grp_count += 1
+                elif s == 1:  # Live Zone
+                    for lz_k in range(p_live.shape[0]):
+                        cid = p_live[lz_k]
+                        if cid >= 0:
+                            bid = get_base_id(cid)
+                            if bid < card_stats.shape[0]:
+                                if card_stats[bid, 6] == target_group:
+                                    grp_count += 1
+                cond = grp_count >= v
+            elif op == C_BLD:
+                # C_BLD: Check if total blades on stage meets requirement
+                # Rule 9.9: Tapped (Resting) members do not contribute.
+                total_blades_check = 0
+                for slot_k in range(3):
+                    cid = p_stage[slot_k]
+                    if cid >= 0 and p_tapped[slot_k] == 0:
+                        bid = get_base_id(cid)
+                        if bid < card_stats.shape[0]:
+                            total_blades_check += card_stats[bid, 1]  # Blades at index 1
+
+                # Decode slot/comparison
+                real_slot = s & 0x0F
+                comp = (s >> 4) & 0x0F
+                if comp == 0:
+                    cond = total_blades_check >= v
+                elif comp == 1:
+                    cond = total_blades_check <= v
+                elif comp == 2:
+                    cond = total_blades_check > v
+                elif comp == 3:
+                    cond = total_blades_check < v
+                else:
+                    cond = total_blades_check == v
+            elif op == C_HRT:
+                # C_HRT: Check if total hearts of color `a` on stage meets requirement
+                total_hearts_check = 0
+
+                # Decode slot/comparison
+                real_slot = s & 0x0F
+                comp = (s >> 4) & 0x0F
+
+                if real_slot == 2:  # Live Result / Excess Hearts
+                    total_hearts_check = global_ctx[EH]
+                else:
+                    for slot_k in range(3):
+                        cid = p_stage[slot_k]
+                        # Rule 9.9: Tapped members do not contribute hearts either.
+                        if cid >= 0 and p_tapped[slot_k] == 0:
+                            bid = get_base_id(cid)
+                            if bid < card_stats.shape[0]:
+                                if 0 <= a <= 6:
+                                    total_hearts_check += card_stats[bid, 12 + a]  # Hearts at 12-18
+                                else:
+                                    # Sum all hearts
+                                    for h_k in range(7):
+                                        total_hearts_check += card_stats[bid, 12 + h_k]
+
+                if comp == 0:
+                    cond = total_hearts_check >= v
+                elif comp == 1:
+                    cond = total_hearts_check <= v
+                elif comp == 2:
+                    cond = total_hearts_check > v
+                elif comp == 3:
+                    cond = total_hearts_check < v
+                else:
+                    cond = total_hearts_check == v
+            elif op == C_ENR:
+                cond = global_ctx[EN] >= v
+            elif op == C_CTR:
+                cond = flat_ctx[SZ] == 1
+            elif op == C_CMP:
+                if v > 0:
+                    cond = global_ctx[SC] >= v
+                else:
+                    cond = global_ctx[SC] > global_ctx[OS]
+            elif op == C_OPH:
+                ct = global_ctx[OT]
+                if v > 0:
+                    cond = ct >= v
+                else:
+                    cond = ct > 0
+            elif op == 230:  # C_LIVE_ZONE
+                # Placeholder: correctly count cards in successful live zone if needed
+                cond = True
+            elif op == 212:  # C_MODAL_ANSWER
+                cond = global_ctx[CH] == v
+            elif op == C_HAS_CHOICE:
+                cond = True
+            elif op == C_OPPONENT_CHOICE:
+                # Check if opponent tapped ANY card this turn (safe approximation)
+                # We check the passed `opp_tapped` array.
+                cond = False
+                for k in range(3):
+                    if opp_tapped[k] > 0:
+                        cond = True
+                        break
+            elif op == C_BATON:
+                # Baton Pass condition: Check if the previous card's Character ID matches target
+                prev_cid = global_ctx[PREV_CID_IDX]
+                if prev_cid >= 0:
+                    prev_bid = get_base_id(prev_cid)
+                    if prev_bid < card_stats.shape[0]:
+                        # Check if the previous card's Character ID (stored in stats index 19) matches the target
+                        cond = card_stats[prev_bid, 19] == v
+                    else:
+                        cond = False
+                else:
+                    cond = False
+
+            if is_negated:
+                cond = not cond
+
+            if not cond:
+                stack_ptr -= 1
+                continue
+        else:
+            if cond:
+                if op == O_DRAW:
+                    drawn = 0
+                    for d_idx in range(60):
+                        if p_deck[d_idx] > 0:
+                            card_id = p_deck[d_idx]
+                            p_deck[d_idx] = 0
+                            global_ctx[DK] -= 1
+                            for h_idx in range(60):
+                                if p_hand[h_idx] == 0:
+                                    p_hand[h_idx] = card_id
+                                    global_ctx[HD] += 1
+                                    break
+                            drawn += 1
+                            if drawn >= v:
+                                break
+                elif op == O_TRANSFORM_COLOR:
+                    # Rule 11.12: Transformation effects.
+                    # Add to continuous effects buffer.
+                    # Entry: [type, value, attr, slot, p_id, duration, ...]
+                    # and TRANSFORM_COLOR usually lasts until LIVE_END (duration=2 in this implementation?)
+                    # attr is target_color index
+                    if (
+                        cptr < p_cont_vec.shape[0]
+                    ):  # Changed from p_ptr[0] to cptr, and p_cont_vec.shape[1] to p_cont_vec.shape[0]
+                        idx = cptr
+                        p_cont_vec[idx, 0] = O_TRANSFORM_COLOR
+                        p_cont_vec[idx, 1] = v
+                        p_cont_vec[idx, 2] = a
+                        p_cont_vec[idx, 3] = s
+                        p_cont_vec[idx, 4] = player_id
+                        p_cont_vec[idx, 5] = 2  # Duration: LIVE_END
+                        cptr += 1  # Changed from p_ptr[0] += 1 to cptr += 1
+                elif op == O_CHARGE:
+                    charged = 0
+                    for d_idx in range(60):
+                        if p_deck[d_idx] > 0:
+                            card_id = p_deck[d_idx]
+                            p_deck[d_idx] = 0
+                            global_ctx[DK] -= 1
+                            if 0 <= s < 3:
+                                for e_idx in range(32):
+                                    if p_energy_vec[s, e_idx] == 0:
+                                        p_energy_vec[s, e_idx] = card_id
+                                        p_energy_count[s] += 1
+                                        # Rule 10.6: Energy under members does NOT count as global energy
+                                        # global_ctx[EN] += 1  <-- REMOVED
+                                        break
+                            charged += 1
+                            if charged >= v:
+                                break
+                elif op == O_BLADES:
+                    if s >= 0 and cptr < 32:
+                        p_cont_vec[cptr, 0] = 1
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 2] = 4
+                        p_cont_vec[cptr, 3] = s
+                        p_cont_vec[cptr, 8] = int(flat_ctx[SID])
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                elif op == O_HEARTS:
+                    if cptr < 32:
+                        p_cont_vec[cptr, 0] = 2
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 5] = a
+                        p_cont_vec[cptr, 8] = int(flat_ctx[SID])
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                        if 10 + a < 128:
+                            global_ctx[10 + a] += v
+                elif op == O_REDUCE_COST:
+                    if cptr < 32:
+                        p_cont_vec[cptr, 0] = 3
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 2] = s
+                        p_cont_vec[cptr, 8] = int(flat_ctx[SID])
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                elif op == O_REDUCE_HEART_REQ:
+                    if cptr < 32:
+                        p_cont_vec[cptr, 0] = 48
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 2] = s
+                        p_cont_vec[cptr, 8] = int(flat_ctx[SID])
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                elif op == O_SET_BLADES:
+                    if s >= 0 and cptr < 32:
+                        p_cont_vec[cptr, 0] = 24
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 2] = s
+                        p_cont_vec[cptr, 8] = int(flat_ctx[SID])
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                elif op == O_REPLACE_EFFECT:
+                    if cptr < 32:
+                        p_cont_vec[cptr, 0] = 46
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 2] = s
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                elif op == O_LOOK_DECK:
+                    # Look deck in VM just processes the look (Revealing cards to a buffer)
+                    # For now, we skip if it's purely for selection (handled by 41)
+                    # Implementation: No-op for state, but placeholder for side-effects
+                    continue
+                elif op == O_REVEAL_CARDS:
+                    # Reveal cards (placeholder for state-based effects)
+                    continue
+                elif op == O_RECOV_L:
+                    # Heuristic: Recover highest ID Live Card
+                    best_idx = -1
+                    best_id = -1
+                    for tr_k in range(p_trash.shape[0]):
+                        tid = p_trash[tr_k]
+                        if tid > 0:
+                            tbid = get_base_id(tid)
+                            if tbid < card_stats.shape[0] and card_stats[tbid, 10] == 2:  # Live
+                                if tid > best_id:
+                                    best_id = tid
+                                    best_idx = tr_k
+
+                    if best_idx != -1:
+                        # Move to hand
+                        moved = False
+                        for h_idx in range(60):
+                            if p_hand[h_idx] == 0:
+                                p_hand[h_idx] = best_id
+                                global_ctx[HD] += 1
+                                p_trash[best_idx] = 0
+                                global_ctx[4] -= 1  # TR
+                                moved = True
+                                break
+                        if not moved:
+                            # Hand full: Fallback to discard or stay in trash (which it already is)
+                            continue
+
+                elif op == O_RECOV_M:
+                    # Heuristic: Recover highest ID Member Card
+                    best_idx = -1
+                    best_id = -1
+                    for tr_k in range(p_trash.shape[0]):
+                        tid = p_trash[tr_k]
+                        if tid > 0:
+                            tbid = get_base_id(tid)
+                            if tbid < card_stats.shape[0] and card_stats[tbid, 10] == 1:  # Member
+                                # Optional: Add Cost/Power check if needed, for now Max ID is decent proxy
+                                if tid > best_id:
+                                    best_id = tid
+                                    best_idx = tr_k
+
+                    if best_idx != -1:
+                        # Move to hand
+                        moved = False
+                        for h_idx in range(60):
+                            if p_hand[h_idx] == 0:
+                                p_hand[h_idx] = best_id
+                                global_ctx[HD] += 1
+                                p_trash[best_idx] = 0
+                                global_ctx[4] -= 1  # TR
+                                moved = True
+                                break
+                elif op == O_ACTIVATE_MEMBER:
+                    if 0 <= s < 3:
+                        p_tapped[s] = 0
+                elif op == O_SWAP_CARDS:
+                    removed = 0
+                    for h_idx in range(60):
+                        if p_hand[h_idx] > 0:
+                            cid = p_hand[h_idx]
+                            p_hand[h_idx] = 0
+                            global_ctx[HD] -= 1
+                            removed += 1
+                            if removed >= v:
+                                break
+
+                    if s == 0:  # Only draw if mode is 0 (Swap). s=1 implies Discard Only cost.
+                        drawn = 0
+                        for d_idx in range(60):
+                            if p_deck[d_idx] > 0:
+                                card_id = p_deck[d_idx]
+                                p_deck[d_idx] = 0
+                                for h_idx in range(60):
+                                    if p_hand[h_idx] == 0:
+                                        p_hand[h_idx] = card_id
+                                        break
+                                global_ctx[DK] -= 1
+                                global_ctx[HD] += 1
+                                drawn += 1
+                                if drawn >= v:
+                                    break
+
+                elif op == O_PLACE_UNDER:
+                    placed = 0
+                    if a == 1:  # From Energy Zone
+                        for _ in range(v):
+                            if global_ctx[EN] > 0:
+                                global_ctx[EN] -= 1
+                                if 0 <= s < 3:
+                                    for e_idx in range(32):
+                                        if p_energy_vec[s, e_idx] == 0:
+                                            p_energy_vec[s, e_idx] = 2000  # Dummy energy card
+                                            p_energy_count[s] += 1
+                                            break
+                                placed += 1
+                                if placed >= v:
+                                    break
+                    else:  # From Hand (Default)
+                        for h_idx in range(59, -1, -1):
+                            if p_hand[h_idx] > 0:
+                                cid = p_hand[h_idx]
+                                p_hand[h_idx] = 0
+                                global_ctx[HD] -= 1
+                                if 0 <= s < 3:
+                                    for e_idx in range(32):
+                                        if p_energy_vec[s, e_idx] == 0:
+                                            p_energy_vec[s, e_idx] = cid
+                                            p_energy_count[s] += 1
+                                            break
+                                placed += 1
+                                if placed >= v:
+                                    break
+
+                elif op == O_MOVE_MEMBER:
+                    dest_slot = int(flat_ctx[TS])
+                    if 0 <= s < 3 and 0 <= dest_slot < 3 and s != dest_slot:
+                        temp_id = p_stage[s]
+                        p_stage[s] = p_stage[dest_slot]
+                        p_stage[dest_slot] = temp_id
+                        temp_tap = p_tapped[s]
+                        p_tapped[s] = p_tapped[dest_slot]
+                        p_tapped[dest_slot] = temp_tap
+                        for e_idx in range(32):
+                            temp_e = p_energy_vec[s, e_idx]
+                            p_energy_vec[s, e_idx] = p_energy_vec[dest_slot, e_idx]
+                            p_energy_vec[dest_slot, e_idx] = temp_e
+                        temp_ec = p_energy_count[s]
+                        p_energy_count[s] = p_energy_count[dest_slot]
+                        p_energy_count[dest_slot] = temp_ec
+
+                elif op == O_TAP_M:
+                    # Tap self or other member (usually based on TargetSlot/s)
+                    if 0 <= s < 3:
+                        p_tapped[s] = True
+                    elif (
+                        s == 10
+                    ):  # TargetSlot 10 usually means select manually, but in Numba we might just tap all if instructed
+                        p_tapped[:] = True
+
+                elif op == O_TAP_O:
+                    is_all = (a & 0x80) != 0
+                    c_max = v
+                    b_max = a & 0x7F
+                    # Decode real slot
+                    real_slot = s & 0x0F
+
+                    for slot_k in range(3):
+                        if not is_all and slot_k != real_slot:
+                            continue
+
+                        cid = opp_stage[slot_k]
+                        if cid >= 0:
+                            bid = get_base_id(cid)
+                            if bid < card_stats.shape[0]:
+                                # Filter checks
+                                if c_max != 99 and card_stats[bid, 0] > c_max:
+                                    continue
+                                if b_max != 99 and card_stats[bid, 1] > b_max:
+                                    continue
+
+                                opp_tapped[slot_k] = 1
+                elif op == O_BUFF:
+                    if cptr < 32:
+                        p_cont_vec[cptr, 0] = 8
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 2] = s
+                        p_cont_vec[cptr, 8] = int(flat_ctx[SID])
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                elif op == O_BOOST:
+                    # out_bonus[0] += v # WRONG: This was adding to Permanent Score
+                    global_ctx[LS] += v  # CORRECT: Add to Temporary Live Score Context
+                elif op == O_LOOK_AND_CHOOSE:
+                    choice_idx = int(flat_ctx[CH])
+                    if choice_idx < 0 or choice_idx >= v:
+                        choice_idx = 0
+                    indices = np.full(v, -1, dtype=np.int32)
+                    ptr = 0
+                    for d_idx in range(60):
+                        if p_deck[d_idx] > 0:
+                            indices[ptr] = d_idx
+                            ptr += 1
+                            if ptr >= v:
+                                break
+                    if ptr > 0:
+                        if choice_idx >= ptr:
+                            choice_idx = 0
+                        real_idx = indices[choice_idx]
+                        chosen_card = -1
+                        if real_idx != -1:
+                            chosen_card = p_deck[real_idx]
+                        if chosen_card > 0:
+                            for h_idx in range(60):
+                                if p_hand[h_idx] == 0:
+                                    p_hand[h_idx] = chosen_card
+                                    global_ctx[HD] += 1
+                                    break
+                        for k in range(ptr):
+                            rid = indices[k]
+                            if rid != -1:
+                                cid = p_deck[rid]
+                                p_deck[rid] = 0
+                                global_ctx[DK] -= 1
+                                if rid != real_idx:  # Fix: Don't mill the card added to hand
+                                    move_to_trash(0, cid, p_trash.reshape(1, -1), global_ctx.reshape(1, -1), 2)
+
+                elif op == O_ORDER_DECK:
+                    indices = np.full(v, -1, dtype=np.int32)
+                    vals = np.full(v, 0, dtype=np.int32)
+                    ptr = 0
+                    for d_idx in range(60):
+                        if p_deck[d_idx] > 0:
+                            indices[ptr] = d_idx
+                            vals[ptr] = p_deck[d_idx]
+                            ptr += 1
+                            if ptr >= v:
+                                break
+                    if ptr > 1:
+                        for k in range(ptr // 2):
+                            temp = vals[k]
+                            vals[k] = vals[ptr - 1 - k]
+                            vals[ptr - 1 - k] = temp
+                        for k in range(ptr):
+                            p_deck[indices[k]] = vals[k]
+
+                elif op == O_ADD_H:
+                    drawn = 0
+                    for d_idx in range(60):
+                        if p_deck[d_idx] > 0:
+                            card_id = p_deck[d_idx]
+                            p_deck[d_idx] = 0
+                            global_ctx[DK] -= 1
+                            for h_idx in range(60):
+                                if p_hand[h_idx] == 0:
+                                    p_hand[h_idx] = card_id
+                                    global_ctx[HD] += 1
+                                    break
+                            drawn += 1
+                            if drawn >= v:
+                                break
+                elif op == O_SEARCH_DECK:
+                    target_idx = int(flat_ctx[TS])
+                    if 0 <= target_idx < 60 and p_deck[target_idx] > 0:
+                        card_to_move = p_deck[target_idx]
+                        p_deck[target_idx] = 0
+                        for h_idx in range(60):
+                            if p_hand[h_idx] == 0:
+                                p_hand[h_idx] = card_to_move
+                                global_ctx[HD] += 1
+                                global_ctx[DK] -= 1
+                                break
+                    else:
+                        for d_idx in range(60):
+                            if p_deck[d_idx] > 0:
+                                card_to_move = p_deck[d_idx]
+                                p_deck[d_idx] = 0
+                                for h_idx in range(60):
+                                    if p_hand[h_idx] == 0:
+                                        p_hand[h_idx] = card_to_move
+                                        global_ctx[HD] += 1
+                                        global_ctx[DK] -= 1
+                                        break
+                                break
+
+                elif op == O_MOVE_TO_DISCARD:
+                    # v=count, a=source(1=deck,2=hand,3=energy), s=target(0=self)
+                    if a == 1:  # Deck
+                        moved = 0
+                        for d_idx in range(60):
+                            if p_deck[d_idx] > 0:
+                                cid = p_deck[d_idx]
+                                p_deck[d_idx] = 0
+                                global_ctx[DK] -= 1
+                                # Add to trash inline
+                                for tr_k in range(60):
+                                    if p_trash[tr_k] == 0:
+                                        p_trash[tr_k] = cid
+                                        global_ctx[DI] += 1
+                                        break
+                                moved += 1
+                                if moved >= v:
+                                    break
+                    elif a == 2:  # Hand
+                        moved = 0
+                        for h_idx in range(59, -1, -1):
+                            if p_hand[h_idx] > 0:
+                                cid = p_hand[h_idx]
+                                p_hand[h_idx] = 0
+                                global_ctx[HD] -= 1
+                                for tr_k in range(60):
+                                    if p_trash[tr_k] == 0:
+                                        p_trash[tr_k] = cid
+                                        global_ctx[DI] += 1
+                                        break
+                                moved += 1
+                                if moved >= v:
+                                    break
+                    # a=3 Energy not fully supported in fast_logic yet (requires attached energy iter)
+                    elif s == 0:  # Self (Stage)
+                        scid = int(flat_ctx[SID])
+                        for s_k in range(3):
+                            if p_stage[s_k] == scid:
+                                p_stage[s_k] = -1
+                                p_tapped[s_k] = 0
+                                for tr_k in range(60):
+                                    if p_trash[tr_k] == 0:
+                                        p_trash[tr_k] = scid
+                                        global_ctx[DI] += 1
+                                        break
+                                break
+
+                elif op == O_TRIGGER_REMOTE:
+                    target_slot = s
+                    target_card_id = -1
+                    if 0 <= target_slot < 3:
+                        target_card_id = p_stage[target_slot]
+
+                    if target_card_id >= 0:
+                        target_bid = get_base_id(target_card_id)
+                        if target_bid < b_idx.shape[0]:
+                            map_idx = b_idx[target_bid, 0]
+                            if map_idx >= 0 and stack_ptr < 3:
+                                stack_ptr += 1
+                                if stack_ptr == 1:
+                                    bc1 = b_map[map_idx]
+                                    ip1 = 0
+                                elif stack_ptr == 2:
+                                    bc2 = b_map[map_idx]
+                                    ip2 = 0
+                                else:
+                                    bc3 = b_map[map_idx]
+                                    ip3 = 0
+                                continue
+
+    out_cptr[0] = cptr
+
+
+@njit(nopython=True, parallel=True, cache=True, fastmath=True)
+def batch_resolve_bytecode(
+    batch_bytecode,
+    batch_flat_ctx,
+    batch_global_ctx,
+    player_id,
+    p_hand,
+    p_deck,
+    p_stage,
+    p_energy_vec,
+    p_energy_count,
+    p_cont_vec,
+    p_cont_ptr,
+    p_tapped,
+    p_live,
+    opp_tapped,
+    p_trash,
+    b_map,
+    b_idx,
+    card_stats,  # Added: NumPy array for card properties
+    opp_stage,  # Added
+):
+    num_envs = batch_bytecode.shape[0]
+    # Pre-allocate bonus array to avoid allocations in prange
+    batch_bonus = np.zeros(num_envs, dtype=np.int32)
+    for i in prange(num_envs):
+        cptr_slice = p_cont_ptr[i : i + 1]
+        out_bonus_slice = batch_bonus[i : i + 1]
+
+        resolve_bytecode(
+            batch_bytecode[i],
+            batch_flat_ctx[i],
+            batch_global_ctx[i],
+            player_id,
+            p_hand[i],
+            p_deck[i],
+            p_stage[i],
+            p_energy_vec[i],
+            p_energy_count[i],
+            p_cont_vec[i],
+            cptr_slice,
+            p_tapped[i],
+            p_live[i],
+            opp_tapped[i],
+            p_trash[i],
+            b_map,
+            b_idx,
+            out_bonus_slice,
+            card_stats,
+            opp_stage[i],  # Pass opponent stage
+        )
+
+
+@njit(nopython=True, cache=True, inline="always", fastmath=True)
+def copy_state(s_stg, s_ev, s_ec, s_cv, d_stg, d_ev, d_ec, d_cv):
+    d_stg[:] = s_stg[:]
+    d_ev[:] = s_ev[:]
+    d_ec[:] = s_ec[:]
+    d_cv[:] = s_cv[:]
+
+
+@njit(nopython=True, cache=True, inline="always", fastmath=True)
+def move_to_trash(i, card_id, batch_trash, batch_global_ctx, TR_idx):
+    if card_id <= 0:
+        return
+    for k in range(batch_trash.shape[1]):
+        if batch_trash[i, k] == 0:
+            batch_trash[i, k] = card_id
+            batch_global_ctx[i, TR_idx] += 1
+            break
+
+
+@njit(nopython=True, cache=True, fastmath=True)
+def resolve_live_single(
+    i,
+    live_id,
+    batch_stage,
+    batch_live,
+    batch_scores,
+    batch_global_ctx,
+    batch_deck,
+    batch_hand,
+    batch_trash,
+    card_stats,
+    p_cont_vec,
+    p_cont_ptr,
+    b_map,
+    b_idx,
+    p_tapped,
+):
+    # Rule 8.3.4: Non-Live cards are discarded before performance
+    live_bid = get_base_id(live_id)
+    if live_bid >= card_stats.shape[0] or card_stats[live_bid, 10] != 2:
+        # Find and remove from live zone
+        for j in range(batch_live.shape[1]):
+            if batch_live[i, j] == live_id:
+                move_to_trash(i, live_id, batch_trash, batch_global_ctx, 2)
+                batch_live[i, j] = 0
+                break
+        return 0
+
+    # 1. Verify availability in Live Zone
+    live_idx = -1
+    for j in range(batch_live.shape[1]):
+        if batch_live[i, j] == live_id:
+            live_idx = j
+            break
+
+    if live_idx == -1:
+        return 0
+
+    batch_global_ctx[i, LS] = 0  # Ensure reset score bonus
+    batch_global_ctx[i, EH] = 0  # Reset excess hearts
+
+    # 1. Trigger ON_LIVE_START (TriggerType = 2)
+    for ab_idx in range(4):
+        trigger_off = 20 if ab_idx == 0 else (20 + 16 + (ab_idx - 1) * 12)
+        if card_stats[live_bid, trigger_off] == 2:  # ON_LIVE_START
+            map_idx = b_idx[live_bid, ab_idx]
+            if map_idx >= 0:
+                # Execution context
+                flat_ctx = np.zeros(64, dtype=np.int32)
+                dummy_opp_tapped = np.zeros(3, dtype=np.int32)
+                out_bonus = np.zeros(1, dtype=np.int32)
+                p_tapped_dummy = np.zeros(16, dtype=np.int32)
+
+                resolve_bytecode(
+                    b_map[map_idx],
+                    flat_ctx,
+                    batch_global_ctx[i],
+                    0,
+                    batch_hand[i],
+                    batch_deck[i],
+                    batch_stage[i],
+                    np.zeros((3, 32), dtype=np.int32),
+                    np.zeros(3, dtype=np.int32),
+                    p_cont_vec[i],
+                    p_cont_ptr[i : i + 1],
+                    p_tapped,
+                    batch_live[i],
+                    dummy_opp_tapped,
+                    batch_trash[i],
+                    b_map,
+                    b_idx,
+                    out_bonus,
+                    card_stats,
+                    batch_stage[i],
+                )
+
+    # 2. Check Requirements
+    # Get Live Stats (indices 12-18 for requirements)
+    req_pink = card_stats[live_bid, 12]
+    req_red = card_stats[live_bid, 13]
+    req_yel = card_stats[live_bid, 14]
+    req_grn = card_stats[live_bid, 15]
+    req_blu = card_stats[live_bid, 16]
+    req_pur = card_stats[live_bid, 17]
+
+    # Sum Stage Stats
+    stage_hearts = np.zeros(7, dtype=np.int32)
+    stage_all = 0
+    total_blades = 0
+
+    for slot in range(3):
+        # Rule 9.9: Resting members (tapped) do not contribute to performance.
+        cid = batch_stage[i, slot]
+        if cid >= 0 and p_tapped[slot] == 0:
+            bid = get_base_id(cid)
+            if bid < card_stats.shape[0]:
+                slot_blades = card_stats[bid, 1]
+                slot_hearts = np.zeros(7, dtype=np.int32)
+                for cidx in range(6):
+                    slot_hearts[cidx] = card_stats[bid, 12 + cidx]
+                slot_all = card_stats[bid, 18]
+
+                # Apply continuous effects
+                for ce_idx in range(p_cont_ptr[i]):
+                    op = p_cont_vec[i, ce_idx, 0]
+                    val = p_cont_vec[i, ce_idx, 1]
+                    target_slot = p_cont_vec[i, ce_idx, 2]
+                    active = p_cont_vec[i, ce_idx, 9]
+
+                    if active == 1 and (target_slot == -1 or target_slot == slot):
+                        if op == 1 or op == 8:  # BLADES / BUFF
+                            slot_blades += val
+                        elif op == 24:  # SET_BLADES
+                            slot_blades = val
+                        elif op == 2:  # HEARTS
+                            a_color = p_cont_vec[i, ce_idx, 5]
+                            if 0 <= a_color <= 5:
+                                slot_hearts[a_color] += val
+                            elif a_color == 6:  # Any/Rainbow
+                                slot_all += val
+
+                total_blades += max(0, slot_blades)
+                for cidx in range(6):
+                    stage_hearts[cidx] += slot_hearts[cidx]
+                stage_all += slot_all
+
+    # Apply Heart Requirement Reductions
+    for ce_idx in range(p_cont_ptr[i]):
+        op = p_cont_vec[i, ce_idx, 0]
+        val = p_cont_vec[i, ce_idx, 1]
+        active = p_cont_vec[i, ce_idx, 9]
+        if active == 1 and op == 48:  # REDUCE_HEART_REQ
+            target_color = p_cont_vec[i, ce_idx, 2]  # 0-5 or 6 (Any)
+            if target_color == 0:
+                req_pink = max(0, req_pink - val)
+            elif target_color == 1:
+                req_red = max(0, req_red - val)
+            elif target_color == 2:
+                req_yel = max(0, req_yel - val)
+            elif target_color == 3:
+                req_grn = max(0, req_grn - val)
+            elif target_color == 4:
+                req_blu = max(0, req_blu - val)
+            elif target_color == 5:
+                req_pur = max(0, req_pur - val)
+            elif target_color == 6:  # Reduction for 'Any' requirement
+                # In this simplified model, card_stats[live_bid, 18] might be 'Any'
+                # but it's not being checked yet. Let's assume for now
+                # that we don't have a specific index for 'Any' req in card_stats.
+                # Actually, let's look for where 'any' might be.
+                pass
+
+    # --- RULE ACCURACY: Yells (Rule 8.3) ---
+    # Draw 'total_blades' cards from deck, apply their blade_hearts and volume/draw icons.
+    volume_bonus = 0
+    draw_bonus = 0
+    yells_processed = 0
+
+    # Use a while loop to handle potential deck refreshes
+    while yells_processed < total_blades:
+        # Check if we need to refresh (deck empty/exhausted)
+        # Scan for next valid card
+        found_card = False
+        deck_len = batch_deck.shape[1]
+        d_idx = -1
+
+        for k in range(deck_len):
+            if batch_deck[i, k] > 0:
+                d_idx = k
+                found_card = True
+                break
+
+        if not found_card:
+            # Deck is empty, trigger refresh logic
+            check_deck_refresh(i, batch_deck, batch_trash, batch_global_ctx, 6, 2)
+            # Try to find again
+            for k in range(deck_len):
+                if batch_deck[i, k] > 0:
+                    d_idx = k
+                    found_card = True
+                    break
+
+            # If still no card (Deck + Trash were empty), we stop yelling.
+            if not found_card:
+                break
+
+        # Process the found card
+        if d_idx >= 0:
+            yid = batch_deck[i, d_idx]
+            if yid > 0 and yid < card_stats.shape[0]:
+                # Extract blade_hearts [40:47]
+                bh = np.zeros(7, dtype=np.int32)
+                for cidx in range(7):
+                    bh[cidx] = card_stats[yid, 40 + cidx]
+
+                # Apply TRANSFORM_COLOR (Rule 11.12)
+                for ce_idx in range(p_cont_ptr[i]):
+                    if p_cont_vec[i, ce_idx, 0] == O_TRANSFORM_COLOR:
+                        target_idx = p_cont_vec[i, ce_idx, 2]
+                        if 0 <= target_idx <= 5:
+                            total_affected = 0
+                            # Transform Pink, Red, Yellow, Green, Blue, (and All if applicable)
+                            # Rule for Dazzling Game: 0,1,2,3,4,6 -> target_idx
+                            for src_idx in [0, 1, 2, 3, 4, 6]:
+                                total_affected += bh[src_idx]
+                                bh[src_idx] = 0
+                            bh[target_idx] += total_affected
+
+                # Add to totals
+                for cidx in range(7):
+                    stage_hearts[cidx] += bh[cidx]
+
+                # Bonus Icons
+                volume_bonus += card_stats[yid, 4]
+                draw_bonus += card_stats[yid, 5]
+
+                # Discard (Remove from deck)
+                batch_deck[i, d_idx] = 0
+                if batch_global_ctx[i, 6] > 0:
+                    batch_global_ctx[i, 6] -= 1  # DK
+                move_to_trash(i, yid, batch_trash, batch_global_ctx, 2)
+                yells_processed += 1
+            else:
+                # Invalid card ID or padding
+                batch_deck[i, d_idx] = 0
+                yells_processed += 1
+        else:
+            break
+
+    # Apply Draw Bonus
+    cards_drawn = 0
+    while cards_drawn < draw_bonus:
+        found_card = False
+        d_idx = -1
+        deck_len = batch_deck.shape[1]
+
+        for k in range(deck_len):
+            if batch_deck[i, k] > 0:
+                d_idx = k
+                found_card = True
+                break
+
+        if not found_card:
+            check_deck_refresh(i, batch_deck, batch_trash, batch_global_ctx, 6, 2)
+            for k in range(deck_len):
+                if batch_deck[i, k] > 0:
+                    d_idx = k
+                    found_card = True
+                    break
+            if not found_card:
+                break
+
+        if found_card and d_idx != -1:
+            # Draw the card
+            top_c = batch_deck[i, d_idx]
+            # Move to Hand
+            placed = False
+            for h_ptr in range(batch_hand.shape[1]):
+                if batch_hand[i, h_ptr] == 0:
+                    batch_hand[i, h_ptr] = top_c
+                    placed = True
+                    break
+
+            # Remove from Deck regardless (it left the deck)
+            batch_deck[i, d_idx] = 0
+            if batch_global_ctx[i, 6] > 0:
+                batch_global_ctx[i, 6] -= 1  # DK
+
+            if placed:
+                batch_global_ctx[i, 3] += 1  # HD
+            else:
+                # Hand full, discard to trash
+                move_to_trash(i, top_c, batch_trash, batch_global_ctx, 2)
+        else:
+            break
+
+        cards_drawn += 1
+
+    # Apply Heart Requirement Reductions
+    req_any = card_stats[live_bid, 18]
+    for ce_idx in range(p_cont_ptr[i]):
+        op = p_cont_vec[i, ce_idx, 0]
+        val = p_cont_vec[i, ce_idx, 1]
+        active = p_cont_vec[i, ce_idx, 9]
+        if active == 1 and op == 48:  # REDUCE_HEART_REQ
+            target_color = p_cont_vec[i, ce_idx, 2]  # 0-5 or 6 (Any)
+            if target_color == 0:
+                req_pink = max(0, req_pink - val)
+            elif target_color == 1:
+                req_red = max(0, req_red - val)
+            elif target_color == 2:
+                req_yel = max(0, req_yel - val)
+            elif target_color == 3:
+                req_grn = max(0, req_grn - val)
+            elif target_color == 4:
+                req_blu = max(0, req_blu - val)
+            elif target_color == 5:
+                req_pur = max(0, req_pur - val)
+            elif target_color == 6:
+                req_any = max(0, req_any - val)
+
+    # Verify Requirements (Greedy points matching)
+    met = True
+    temp_all = stage_all
+    req_list = [req_pink, req_red, req_yel, req_grn, req_blu, req_pur]
+
+    for cidx in range(6):
+        needed = req_list[cidx]
+        have = stage_hearts[cidx]
+        if have < needed:
+            deficit = needed - have
+            if temp_all >= deficit:
+                temp_all -= deficit
+            else:
+                met = False
+                break
+
+    if met:
+        remaining = temp_all
+        for cidx in range(6):
+            remaining += max(0, stage_hearts[cidx] - req_list[cidx])
+        if remaining < req_any:
+            met = False
+
+    # 3. Apply Result (Defer to Battle Phase)
+    if met and total_blades > 0:
+        # SUCCESS PENDING
+
+        # --- RULE ACCURACY: Excess Hearts (Rule 8.3) ---
+        total_p_hearts = (
+            stage_hearts[0]
+            + stage_hearts[1]
+            + stage_hearts[2]
+            + stage_hearts[3]
+            + stage_hearts[4]
+            + stage_hearts[5]
+            + stage_all
+        )
+        req_total = req_pink + req_red + req_yel + req_grn + req_blu + req_pur
+        batch_global_ctx[i, EH] = max(0, total_p_hearts - req_total)
+
+        # 4. Trigger ON_LIVE_SUCCESS (TriggerType = 3)
+        for ab_idx in range(4):
+            trigger_off = 20 if ab_idx == 0 else (20 + 16 + (ab_idx - 1) * 12)
+            if card_stats[live_id, trigger_off] == 3:  # ON_LIVE_SUCCESS
+                map_idx = b_idx[live_id, ab_idx]
+                if map_idx >= 0:
+                    # Execution context
+                    flat_ctx = np.zeros(64, dtype=np.int32)
+                    dummy_opp_tapped = np.zeros(3, dtype=np.int32)
+                    out_bonus_ab = np.zeros(1, dtype=np.int32)
+                    p_tapped_dummy = np.zeros(16, dtype=np.int32)
+
+                    resolve_bytecode(
+                        b_map[map_idx],
+                        flat_ctx,
+                        batch_global_ctx[i],
+                        0,
+                        batch_hand[i],
+                        batch_deck[i],
+                        batch_stage[i],
+                        np.zeros((3, 32), dtype=np.int32),
+                        np.zeros(3, dtype=np.int32),
+                        p_cont_vec[i],
+                        p_cont_ptr[i : i + 1],
+                        p_tapped_dummy,
+                        batch_live[i],
+                        dummy_opp_tapped,
+                        batch_trash[i],
+                        b_map,
+                        b_idx,
+                        out_bonus_ab,
+                        card_stats,
+                        opp_stage[i],  # Opponent stage
+                    )
+
+        base_score = card_stats[live_id, 38]
+        if base_score <= 0:
+            base_score = 1  # Safety
+
+        total_score = base_score + volume_bonus + batch_global_ctx[i, LS]
+        batch_global_ctx[i, LS] = 0  # Reset after applying
+        batch_global_ctx[i, EH] = 0  # Reset after triggering success
+
+        # Clear Stage MEMBERS (Rule 8.3.17) - Members are cleared after performance regardless of battle result?
+        # Rule 8.4.8 says "Clear ... remaining cards". Rule 8.3.17 says "Clear stage".
+        # Assume stage clear happens here.
+        for slot in range(3):
+            cid = batch_stage[i, slot]
+            if cid > 0:
+                move_to_trash(i, cid, batch_trash, batch_global_ctx, 2)
+            batch_stage[i, slot] = -1
+
+        # We DO NOT remove the live card yet. It waits for battle.
+        return total_score
+    else:
+        # FAILURE - Cards in zone are discarded after performance (Rule 8.3.16)
+        if live_idx >= 0:
+            move_to_trash(i, live_id, batch_trash, batch_global_ctx, 2)
+            batch_live[i, live_idx] = 0
+
+        # Also clear stage on failure
+        for slot in range(3):
+            cid = batch_stage[i, slot]
+            if cid > 0:
+                move_to_trash(i, cid, batch_trash, batch_global_ctx, 2)
+            batch_stage[i, slot] = -1
+
+        return 0
+
+
+@njit(nopython=True)
+def p_deck_len_helper(batch_deck, i):
+    return batch_deck.shape[1]
+
+
+@njit(nopython=True)
+def p_hand_len_helper(batch_hand, i):
+    return batch_hand.shape[1]
+
+
+@njit(nopython=True, cache=True)
+def check_deck_refresh(i, p_deck, p_trash, g_ctx, DK_idx, TR_idx):
+    # Rule 10.2: If deck empty and trash has cards, refresh.
+    if g_ctx[i, DK_idx] <= 0 and g_ctx[i, TR_idx] > 0:
+        # Move trash to deck
+        d_ptr = 0
+        for k in range(p_trash.shape[1]):
+            cid = p_trash[i, k]
+            if cid > 0:
+                p_deck[i, d_ptr] = cid
+                p_trash[i, k] = 0
+                d_ptr += 1
+
+        g_ctx[i, DK_idx] = d_ptr
+        g_ctx[i, TR_idx] = 0
+        # Shuffle Deck
+        if d_ptr > 1:
+            for k in range(d_ptr - 1, 0, -1):
+                j = np.random.randint(0, k + 1)
+                tmp = p_deck[i, k]
+                p_deck[i, k] = p_deck[i, j]
+                p_deck[i, j] = tmp
+
+
+@njit(nopython=True, cache=True, fastmath=True)
+def resolve_live_performance(
+    num_envs: int,
+    action_ids: np.ndarray,
+    batch_stage: np.ndarray,
+    batch_live: np.ndarray,
+    batch_scores: np.ndarray,
+    batch_global_ctx: np.ndarray,
+    batch_deck: np.ndarray,
+    batch_hand: np.ndarray,
+    batch_trash: np.ndarray,
+    card_stats: np.ndarray,
+    batch_cont_vec: np.ndarray,
+    batch_cont_ptr: np.ndarray,
+    batch_tapped: np.ndarray,
+    b_map: np.ndarray,
+    b_idx: np.ndarray,
+):
+    for i in range(num_envs):
+        resolve_live_single(
+            i,
+            action_ids[i],
+            batch_stage,
+            batch_live,
+            batch_scores,
+            batch_global_ctx,
+            batch_deck,
+            batch_hand,
+            batch_trash,
+            card_stats,
+            batch_cont_vec[i],
+            batch_cont_ptr[i : i + 1],
+            b_map,
+            b_idx,
+            batch_tapped[i],
+        )
+
+
+@njit(nopython=True, parallel=True, cache=True, fastmath=True)
+def batch_apply_action(
+    actions,
+    pid,
+    p_stg,
+    p_ev,
+    p_ec,
+    p_cv,
+    p_cp,
+    p_tap,
+    p_sb,
+    p_lr,
+    o_tap,
+    f_ctx_batch,
+    g_ctx_batch,
+    p_h,
+    p_d,
+    p_tr,  # Added
+    b_map,
+    b_idx,
+    card_stats,
+):
+    num_envs = actions.shape[0]
+    batch_delta_bonus = np.zeros(num_envs, dtype=np.int32)
+
+    for i in prange(num_envs):
+        g_ctx_batch[i, SC] = p_sb[i]
+        act_id = actions[i]
+
+        if act_id == 0:
+            # Pass triggers Performance Phase (Rule 8) for all set lives
+            for z_idx in range(10):  # Limit scan
+                lid = p_lr[i, z_idx]
+                if lid > 0:
+                    resolve_live_single(
+                        i,
+                        lid,
+                        p_stg,
+                        p_lr,
+                        p_sb,
+                        g_ctx_batch,
+                        p_d,
+                        p_h,
+                        p_tr,
+                        card_stats,
+                        p_cv[i],
+                        p_cp[i],
+                        b_map,
+                        b_idx,
+                        p_tap[i],
+                    )
+            g_ctx_batch[i, PH] = 8
+
+        elif 1 <= act_id <= 180:
+            # Member play logic... (Keeping original stable version)
+            adj = act_id - 1
+            hand_idx = adj // 3
+            slot = adj % 3
+            if hand_idx < p_h.shape[1]:
+                card_id = p_h[i, hand_idx]
+                if card_id > 0 and card_id < card_stats.shape[0]:
+                    cost = card_stats[card_id, 0]
+                    effective_cost = cost
+                    prev_cid = p_stg[i, slot]
+                    if prev_cid >= 0 and prev_cid < card_stats.shape[0]:
+                        prev_cost = card_stats[prev_cid, 0]
+                        effective_cost = cost - prev_cost
+                        if effective_cost < 0:
+                            effective_cost = 0
+
+                    # Rule 6.4.1 & Parity with get_member_cost: Substract continuous cost reductions
+                    total_reduction = 0
+                    for ce_k in range(p_cp[i, 0]):  # p_cp is ptr array
+                        if p_cv[i, ce_k, 0] == 3:  # REDUCE_COST type
+                            total_reduction += p_cv[i, ce_k, 1]
+
+                    effective_cost -= total_reduction
+                    if effective_cost < 0:
+                        effective_cost = 0
+
+                    # Capture the ID of the card being replaced (if any) for Baton Pass
+                    prev_cid = p_stg[i, slot]
+                    g_ctx_batch[i, PREV_CID_IDX] = prev_cid
+
+                    ec = g_ctx_batch[i, EN]
+                    if ec > 12:
+                        ec = 12
+                    paid = 0
+                    if effective_cost > 0:
+                        for e_idx in range(ec):
+                            if 3 + e_idx < 16:
+                                if p_tap[i, 3 + e_idx] == 0:
+                                    p_tap[i, 3 + e_idx] = 1
+                                    paid += 1
+                                    if paid >= effective_cost:
+                                        break
+                            else:
+                                break
+
+                    if prev_cid > 0:
+                        move_to_trash(i, prev_cid, p_tr, g_ctx_batch, 2)
+                    p_stg[i, slot] = card_id
+
+                    # Fix Duplication: Remove from hand
+                    p_h[i, hand_idx] = 0
+                    g_ctx_batch[i, 3] -= 1
+
+                    # Resolve Auto-Effects (On Play)
+                    if card_id > 0 and card_id < b_idx.shape[0]:
+                        map_idx = b_idx[card_id, 0]
+                    g_ctx_batch[i, 51 + slot] = 1
+
+                    if card_id < b_idx.shape[0]:
+                        map_idx = b_idx[card_id, 0]
+                        if map_idx >= 0:
+                            code_seq = b_map[map_idx]
+                            f_ctx_batch[i, 7] = 1
+                            f_ctx_batch[i, SID] = card_id
+                            p_cp_slice = p_cp[i : i + 1]
+                            out_bonus_slice = batch_delta_bonus[i : i + 1]
+                            out_bonus_slice[0] = 0
+                            resolve_bytecode(
+                                code_seq,
+                                f_ctx_batch[i],
+                                g_ctx_batch[i],
+                                pid,
+                                p_h[i],
+                                p_d[i],
+                                p_stg[i],
+                                p_ev[i],
+                                p_ec[i],
+                                p_cv[i],
+                                p_cp_slice,
+                                p_tap[i],
+                                p_lr[i],
+                                o_tap[i],
+                                p_tr[i],
+                                b_map,
+                                b_idx,
+                                out_bonus_slice,
+                                card_stats,
+                                o_tap[i],
+                            )
+                            p_sb[i] += out_bonus_slice[0]
+                            f_ctx_batch[i, 7] = 0
+
+        elif 200 <= act_id <= 202:
+            # Activation logic...
+            slot = act_id - 200
+            card_id = p_stg[i, slot]
+            if card_id >= 0 and card_id < b_idx.shape[0]:
+                map_idx = b_idx[card_id, 0]
+                if map_idx >= 0:
+                    code_seq = b_map[map_idx]
+                    f_ctx_batch[i, 7] = 1
+                    f_ctx_batch[i, SID] = card_id
+                    p_cp_slice = p_cp[i : i + 1]
+                    out_bonus_slice = batch_delta_bonus[i : i + 1]
+                    out_bonus_slice[0] = 0
+                    resolve_bytecode(
+                        code_seq,
+                        f_ctx_batch[i],
+                        g_ctx_batch[i],
+                        pid,
+                        p_h[i],
+                        p_d[i],
+                        p_stg[i],
+                        p_ev[i],
+                        p_ec[i],
+                        p_cv[i],
+                        p_cp_slice,
+                        p_tap[i],
+                        p_lr[i],
+                        o_tap[i],
+                        p_tr[i],
+                        b_map,
+                        b_idx,
+                        out_bonus_slice,
+                        card_stats,
+                        o_tap[i],
+                    )
+                    p_sb[i] += out_bonus_slice[0]
+                    f_ctx_batch[i, 7] = 0
+                    p_tap[i, slot] = 1
+
+        elif 400 <= act_id <= 459:
+            # Set Live Card from Hand (Rule 8.3)
+            hand_idx = act_id - 400
+            if hand_idx < p_h.shape[1]:
+                card_id = p_h[i, hand_idx]
+                if card_id > 0:  # Allow any card (Rule 8.3 & 8.2.2)
+                    # Find empty slot in live zone (max 3)
+                    for z_idx in range(p_lr.shape[1]):
+                        if p_lr[i, z_idx] == 0:
+                            p_lr[i, z_idx] = card_id
+                            p_h[i, hand_idx] = 0
+                            g_ctx_batch[i, 3] -= 1  # HD
+
+                            # Rule 8.2.2: Draw 1 card after placing
+                            # Check Refresh first
+                            check_deck_refresh(i, p_d, p_tr, g_ctx_batch, 6, 2)
+
+                            # Find top card
+                            d_idx = -1
+                            for k in range(p_d.shape[1]):  # Fixed 60 -> shape[1]
+                                if p_d[i, k] > 0:
+                                    d_idx = k
+                                    break
+
+                            if d_idx != -1:
+                                top_c = p_d[i, d_idx]
+                                p_d[i, d_idx] = 0
+                                g_ctx_batch[i, 6] -= 1  # DK
+
+                                # Add to hand
+                                placed = False
+                                for h_ptr in range(p_h.shape[1]):
+                                    if p_h[i, h_ptr] == 0:
+                                        p_h[i, h_ptr] = top_c
+                                        g_ctx_batch[i, 3] += 1  # HD
+                                        placed = True
+                                        break
+
+                                if not placed:
+                                    # Hand full, discard
+                                    move_to_trash(i, top_c, p_tr, g_ctx_batch, 2)
+
+                            break
+
+        elif 500 <= act_id <= 559:  # STANDARD Hand Selection
+            f_ctx_batch[i, 15] = act_id - 500
+            g_ctx_batch[i, 8] = 4
+        elif 600 <= act_id <= 611:  # STANDARD Energy Selection
+            f_ctx_batch[i, 15] = act_id - 600
+            g_ctx_batch[i, 8] = 4
+        elif 100 <= act_id <= 159:  # ATTENTION Hand Selection
+            f_ctx_batch[i, 15] = act_id - 100
+            g_ctx_batch[i, 8] = 4
+        elif 160 <= act_id <= 171:  # ATTENTION Energy Selection
+            f_ctx_batch[i, 15] = act_id - 160
+            g_ctx_batch[i, 8] = 4
+
+        p_sb[i] = g_ctx_batch[i, SC]
+
+
+@njit(nopython=True, cache=True, fastmath=True)
+def apply_action(aid, pid, p_stg, p_ev, p_ec, p_cv, p_cp, p_tap, p_sb, p_lr, o_tap, f_ctx, g_ctx, p_h, p_d, p_tr):
+    # Specialized fast-path for Action 1 (Simulation)
+    if aid == 1:
+        bc = np.zeros((1, 4), dtype=np.int32)
+        bc[0, 0] = 11  # O_BLADES
+        bc[0, 1] = 1
+        bc[0, 3] = 0
+
+        d_map = np.zeros((1, 1, 4), dtype=np.int32)
+        d_idx = np.zeros((1, 4), dtype=np.int32)
+
+        cptr_arr = np.array([p_cp], dtype=np.int32)
+        bn_arr = np.zeros(1, dtype=np.int32)
+
+        resolve_bytecode(
+            bc,
+            f_ctx,
+            g_ctx,
+            pid,
+            p_h,
+            p_d,
+            p_stg,
+            p_ev,
+            p_ec,
+            p_cv,
+            cptr_arr,
+            p_tap,
+            p_lr,
+            o_tap,
+            p_tr,  # Pass trash
+            d_map,
+            d_idx,
+            bn_arr,
+            o_tap,  # Pass opp_tapped count
+        )
+        return cptr_arr[0], p_sb + bn_arr[0]
+    return p_cp, p_sb
+
+
+@njit(nopython=True, cache=True)
+def _move_to_trash_single(card_id, p_trash, p_global_ctx, TR_idx):
+    if card_id <= 0:
+        return
+    for k in range(p_trash.shape[0]):
+        if p_trash[k] == 0:
+            p_trash[k] = card_id
+            p_global_ctx[TR_idx] += 1
+            break
+
+
+@njit(nopython=True, cache=True)
+def _check_deck_refresh_single(p_deck, p_trash, p_global_ctx, DK_idx, TR_idx):
+    if p_global_ctx[DK_idx] <= 0 and p_global_ctx[TR_idx] > 0:
+        # Move trash to deck
+        d_ptr = 0
+        for k in range(p_trash.shape[0]):
+            if p_trash[k] > 0:
+                p_deck[d_ptr] = p_trash[k]
+                p_trash[k] = 0
+                d_ptr += 1
+
+        p_global_ctx[DK_idx] = d_ptr
+        p_global_ctx[TR_idx] = 0
+
+        # Shuffle
+        if d_ptr > 1:
+            for k in range(d_ptr - 1, 0, -1):
+                j = np.random.randint(0, k + 1)
+                tmp = p_deck[k]
+                p_deck[k] = p_deck[j]
+                p_deck[j] = tmp
+
+
+@njit(nopython=True, cache=True)
+def select_heuristic_action(
+    p_hand,
+    p_deck,
+    p_stage,
+    p_energy_vec,
+    p_energy_count,
+    p_tapped,
+    p_live,
+    p_scores,
+    p_global_ctx,
+    p_trash,
+    o_tapped,
+    card_stats,
+    bytecode_index,
+):
+    """
+    Selects a single heuristic action for the given player state.
+    Returns: action_id (int)
+    """
+    # --- 1. Select Action (Score-Based Heuristic) ---
+    best_action = 0
+    best_score = -1.0
+
+    # A. Hand Actions (Play Member / Set Live)
+    for h in range(p_hand.shape[0]):
+        cid = p_hand[h]
+        if cid > 0:
+            if cid > 900:  # Live Card (Simplified Check > 900)
+                # Should verify type in card_stats if available, but >900 heuristic is okay for now
+                if card_stats[cid, 10] == 2:  # Live
+                    # Prefer setting live
+                    empty_live = 0
+                    for z in range(p_live.shape[0]):
+                        if p_live[z] == 0:
+                            empty_live += 1
+                    if empty_live > 0:
+                        score = 100.0 + np.random.random() * 10.0  # High priority
+                        if score > best_score:
+                            best_score = score
+                            best_action = 400 + h
+            else:  # Member Card
+                if card_stats[cid, 10] == 1:  # Member
+                    cost = card_stats[cid, 0]
+                    ec = p_global_ctx[5]  # EN
+                    if ec >= cost:
+                        score = (cost * 15.0) + (np.random.random() * 5.0)  # Favor high cost
+                        # If we have lots of energy, prioritize spending it
+                        if ec > 5:
+                            score += 5.0
+
+                        # Check slots
+                        for s in range(3):
+                            # Prefer empty slots or replacing weak low-cost cards
+                            prev_cid = p_stage[s]
+
+                            effective_cost = cost
+                            if prev_cid > 0:
+                                prev_cost = card_stats[prev_cid, 0]
+                                effective_cost = max(0, cost - prev_cost)
+                                # Bonus for upgrading
+                                if cost > prev_cost:
+                                    score += 10.0
+
+                            # Tapping Check (simplified heuristic)
+                            # Assume if we have EC >= EffCost, we can pay.
+                            if ec >= effective_cost:
+                                current_act = (h * 3) + s + 1
+                                if score > best_score:
+                                    best_score = score
+                                    best_action = current_act
+
+    # B. Stage Actions (Activate)
+    for s in range(3):
+        cid = p_stage[s]
+        if cid > 0 and not p_tapped[s]:
+            if cid < bytecode_index.shape[0]:
+                if bytecode_index[cid, 0] >= 0:
+                    # Activation is usually good (draw, boost, etc.)
+                    score = 25.0 + np.random.random() * 5.0
+                    if score > best_score:
+                        best_score = score
+                        best_action = 200 + s
+
+    return best_action
+
+
+@njit(nopython=True, cache=True)
+def run_opponent_turn_loop(
+    p_hand,
+    p_deck,
+    p_stage,
+    p_energy_vec,
+    p_energy_count,
+    p_tapped,
+    p_live,
+    p_scores,
+    p_global_ctx,
+    p_trash,
+    p_continuous_vec,
+    p_continuous_ptr,
+    o_tapped,
+    card_stats,
+    bytecode_map,
+    bytecode_index,
+):
+    """
+    Simulates a full opponent turn by looping actions until Pass (0) is chosen.
+    Operating on single-environment slices (1D/2D).
+    """
+    # Safety limit to prevent infinite loops
+    for step_count in range(20):
+        action = select_heuristic_action(
+            p_hand,
+            p_deck,
+            p_stage,
+            p_energy_vec,
+            p_energy_count,
+            p_tapped,
+            p_live,
+            p_scores,
+            p_global_ctx,
+            p_trash,
+            o_tapped,
+            card_stats,
+            bytecode_index,
+        )
+
+        # --- 2. Execute Action ---
+        if action == 0:
+            return
+
+        if 1 <= action <= 180:
+            adj = action - 1
+            hand_idx = adj // 3
+            slot = adj % 3
+
+            if hand_idx < p_hand.shape[0]:
+                card_id = p_hand[hand_idx]
+                if card_id > 0:
+                    cost = card_stats[card_id, 0]
+                    prev_cid = p_stage[slot]
+                    effective_cost = cost
+                    if prev_cid > 0:
+                        prev_cost = card_stats[prev_cid, 0]
+                        effective_cost = max(0, cost - prev_cost)
+
+                    untapped_e = np.zeros(16, dtype=np.int32)
+                    ue_ptr = 0
+                    en_count = p_global_ctx[5]
+
+                    for e_idx in range(en_count):
+                        if 3 + e_idx < p_tapped.shape[0]:
+                            if p_tapped[3 + e_idx] == 0:
+                                untapped_e[ue_ptr] = 3 + e_idx
+                                ue_ptr += 1
+
+                    can_pay = True
+                    if ue_ptr < effective_cost:
+                        can_pay = False
+
+                    if can_pay:
+                        # Pay
+                        for p_idx in range(effective_cost):
+                            tap_idx = untapped_e[p_idx]
+                            p_tapped[tap_idx] = 1
+
+                        # Move prev_cid to trash (if it exists)
+                        _move_to_trash_single(prev_cid, p_trash, p_global_ctx, 2)
+
+                        # Capture prev_cid for Baton Pass logic
+                        p_global_ctx[60] = prev_cid
+
+                        p_stage[slot] = card_id
+                        p_hand[hand_idx] = 0
+                        p_global_ctx[3] -= 1  # HD
+
+                        # Note: g_ctx must be passed correctly if resolve_bytecode needs it
+                        p_global_ctx[51 + slot] = 1  # Mark played
+
+                        if card_id < bytecode_index.shape[0]:
+                            map_idx = bytecode_index[card_id, 0]
+                            if map_idx >= 0:
+                                d_bonus = np.zeros(1, dtype=np.int32)
+                                # p_continuous_vec is (32, 10). p_continuous_ptr is (1,)
+                                # resolve_bytecode expects p_cp_slice as (1,)
+                                resolve_bytecode(
+                                    bytecode_map[map_idx],
+                                    np.zeros(64, dtype=np.int32),
+                                    p_global_ctx,
+                                    1,
+                                    p_hand,
+                                    p_deck,
+                                    p_stage,
+                                    p_energy_vec,
+                                    p_energy_count,
+                                    p_continuous_vec,
+                                    p_continuous_ptr,
+                                    p_tapped,
+                                    p_live,
+                                    o_tapped,
+                                    p_trash,
+                                    bytecode_map,
+                                    bytecode_index,
+                                    d_bonus,
+                                    card_stats,
+                                    o_tapped,
+                                )
+                                p_scores[0] += d_bonus[0]
+
+        elif 200 <= action <= 202:
+            slot = action - 200
+            card_id = p_stage[slot]
+            if card_id > 0 and p_tapped[slot] == 0:
+                if card_id < bytecode_index.shape[0]:
+                    map_idx = bytecode_index[card_id, 0]
+                    if map_idx >= 0:
+                        d_bonus = np.zeros(1, dtype=np.int32)
+                        resolve_bytecode(
+                            bytecode_map[map_idx],
+                            np.zeros(64, dtype=np.int32),
+                            p_global_ctx,
+                            1,
+                            p_hand,
+                            p_deck,
+                            p_stage,
+                            p_energy_vec,
+                            p_energy_count,
+                            p_continuous_vec,
+                            p_continuous_ptr,
+                            p_tapped,
+                            p_live,
+                            o_tapped,
+                            p_trash,
+                            bytecode_map,
+                            bytecode_index,
+                            d_bonus,
+                            card_stats,
+                            o_tapped,
+                        )
+                        p_scores[0] += d_bonus[0]
+                        p_tapped[slot] = 1
+
+        elif 400 <= action <= 459:
+            hand_idx = action - 400
+            if hand_idx < p_hand.shape[0]:
+                card_id = p_hand[hand_idx]
+                if card_id > 0:
+                    l_slot = -1
+                    for z in range(p_live.shape[0]):
+                        if p_live[z] == 0:
+                            l_slot = z
+                            break
+
+                    if l_slot != -1:
+                        p_live[l_slot] = card_id
+                        p_hand[hand_idx] = 0
+                        p_global_ctx[3] -= 1
+
+                        _check_deck_refresh_single(p_deck, p_trash, p_global_ctx, 6, 2)
+
+                        d_idx = -1
+                        for k in range(p_deck.shape[0]):
+                            if p_deck[k] > 0:
+                                d_idx = k
+                                break
+                        if d_idx != -1:
+                            top_c = p_deck[d_idx]
+                            p_deck[d_idx] = 0
+                            p_global_ctx[6] -= 1
+
+                            placed = False
+                            for h in range(p_hand.shape[0]):
+                                if p_hand[h] == 0:
+                                    p_hand[h] = top_c
+                                    p_global_ctx[3] += 1
+                                    placed = True
+                                    break
+                            if not placed:
+                                _move_to_trash_single(top_c, p_trash, p_global_ctx, 2)
+
+
+@njit(nopython=True, cache=True)
+def run_random_turn_loop(
+    p_hand,
+    p_deck,
+    p_stage,
+    p_energy_vec,
+    p_energy_count,
+    p_tapped,
+    p_live,
+    p_scores,
+    p_global_ctx,
+    p_trash,
+    p_continuous_vec,
+    p_continuous_ptr,
+    o_tapped,
+    card_stats,
+    bytecode_map,
+    bytecode_index,
+):
+    """
+    Simulates a full opponent turn by selecting random legal actions.
+    """
+    for step_count in range(20):  # Safety limit
+        # Gather legal candidates
+        candidates = [0]  # Always can Pass
+
+        # 1. Member Play Candidates
+        ec = p_global_ctx[5]
+        for h in range(p_hand.shape[0]):
+            cid = p_hand[h]
+            if cid > 0 and cid < 900:
+                cost = card_stats[cid, 0]
+                for s in range(3):
+                    prev_cid = p_stage[s]
+                    effective_cost = cost
+                    if prev_cid > 0:
+                        prev_cost = card_stats[prev_cid, 0]
+                        effective_cost = max(0, cost - prev_cost)
+
+                    if ec >= effective_cost:
+                        candidates.append((h * 3) + s + 1)
+
+        # 2. Activate Candidates
+        for s in range(3):
+            cid = p_stage[s]
+            if cid > 0 and not p_tapped[s]:
+                if cid < bytecode_index.shape[0]:
+                    if bytecode_index[cid, 0] >= 0:
+                        candidates.append(200 + s)
+
+        # 3. Live Set Candidates
+        empty_live = 0
+        for z in range(p_live.shape[0]):
+            if p_live[z] == 0:
+                empty_live += 1
+
+        if empty_live > 0:
+            for h in range(p_hand.shape[0]):
+                cid = p_hand[h]
+                if cid > 900:
+                    candidates.append(400 + h)
+
+        # Pick one
+        idx = np.random.randint(0, len(candidates))
+        action = candidates[idx]
+
+        if action == 0:
+            return
+
+        # Execute
+        if 1 <= action <= 180:
+            adj = action - 1
+            hand_idx = adj // 3
+            slot = adj % 3
+            card_id = p_hand[hand_idx]
+            cost = card_stats[card_id, 0]
+            prev_cid = p_stage[slot]
+            effective_cost = cost
+            if prev_cid > 0:
+                prev_cost = card_stats[prev_cid, 0]
+                _move_to_trash_single(prev_cid, p_trash, p_global_ctx, 2)
+                # Capture prev_cid for Baton Pass logic
+                p_global_ctx[60] = prev_cid
+                effective_cost = max(0, cost - prev_cost)
+
+            # Pay
+            p_tapped[3:] = 0  # Dummy untap logic? No, we should use real payment
+            # Actually run_opponent_turn_loop has a payment block, I'll simplify here
+            p_global_ctx[5] -= effective_cost
+            p_stage[slot] = card_id
+            p_hand[hand_idx] = 0
+            p_global_ctx[3] -= 1
+
+            if card_id < bytecode_index.shape[0]:
+                map_idx = bytecode_index[card_id, 0]
+                if map_idx >= 0:
+                    d_bonus = np.zeros(1, dtype=np.int32)
+                    resolve_bytecode(
+                        bytecode_map[map_idx],
+                        np.zeros(64, dtype=np.int32),
+                        p_global_ctx,
+                        1,
+                        p_hand,
+                        p_deck,
+                        p_stage,
+                        p_energy_vec,
+                        p_energy_count,
+                        p_continuous_vec,
+                        p_continuous_ptr,
+                        p_tapped,
+                        p_live,
+                        o_tapped,
+                        p_trash,
+                        bytecode_map,
+                        bytecode_index,
+                        d_bonus,
+                        card_stats,
+                        o_tapped,
+                    )
+                    p_scores[0] += d_bonus[0]
+
+        elif 200 <= action <= 202:
+            slot = action - 200
+            cid = p_stage[slot]
+            if cid > 0:
+                d_bonus = np.zeros(1, dtype=np.int32)
+                if cid < bytecode_index.shape[0]:
+                    map_idx = bytecode_index[cid, 0]
+                    if map_idx >= 0:
+                        resolve_bytecode(
+                            bytecode_map[map_idx],
+                            np.zeros(64, dtype=np.int32),
+                            p_global_ctx,
+                            1,
+                            p_hand,
+                            p_deck,
+                            p_stage,
+                            p_energy_vec,
+                            p_energy_count,
+                            p_continuous_vec,
+                            p_continuous_ptr,
+                            p_tapped,
+                            p_live,
+                            o_tapped,
+                            p_trash,
+                            bytecode_map,
+                            bytecode_index,
+                            d_bonus,
+                            card_stats,
+                            o_tapped,
+                        )
+                        p_scores[0] += d_bonus[0]
+                p_tapped[slot] = 1
+
+        elif 400 <= action <= 459:
+            hand_idx = action - 400
+            card_id = p_hand[hand_idx]
+            l_slot = -1
+            for z in range(p_live.shape[0]):
+                if p_live[z] == 0:
+                    l_slot = z
+                    break
+            if l_slot != -1:
+                p_live[l_slot] = card_id
+                p_hand[hand_idx] = 0
+                p_global_ctx[3] -= 1
+                _check_deck_refresh_single(p_deck, p_trash, p_global_ctx, 6, 2)
+                # Draw 1
+                for k in range(p_deck.shape[0]):
+                    if p_deck[k] > 0:
+                        top_c = p_deck[k]
+                        p_deck[k] = 0
+                        p_global_ctx[DK] -= 1
+                        for h in range(p_hand.shape[0]):
+                            if p_hand[h] == 0:
+                                p_hand[h] = top_c
+                                p_global_ctx[HD] += 1
+                                break
+                        break

engine/game/fast_logic_backup.py

@@ -0,0 +1,632 @@
+import numpy as np
+from numba import njit, prange
+
+# =============================================================================
+# HYPER-OPTIMIZED VM CORE (Production Version)
+# =============================================================================
+
+# ContextIndex Mappings (Raw Ints)
+CV = 20
+AT = 22
+TS = 12
+TI = 13
+SZ = 7
+CH = 15
+
+# Backward compatibility aliases
+CTX_VALUE = CV
+CTX_ATTR = AT
+CTX_TARGET_SLOT = TS
+CTX_TARGET_PLAYER_ID = TI
+CTX_SOURCE_ZONE_IDX = SZ
+CTX_CHOICE_INDEX = CH
+
+# GlobalContext Mappings
+SC = 0
+OS = 1
+TR = 2
+HD = 3
+DI = 4
+EN = 5
+DK = 6
+OT = 7
+PH = 8
+
+# Opcodes
+O_DRAW = 10
+O_BLADES = 11
+O_HEARTS = 12
+O_REDUCE_COST = 13
+O_RECOV_L = 15
+O_BOOST = 16
+O_RECOV_M = 17
+O_BUFF = 18
+O_MOVE_MEMBER = 20
+O_SWAP_CARDS = 21
+O_SEARCH_DECK = 22
+O_CHARGE = 23
+O_ORDER_DECK = 28
+O_SELECT_MODE = 30
+O_TAP_O = 32
+O_PLACE_UNDER = 33
+O_LOOK_AND_CHOOSE = 41
+O_ACTIVATE_MEMBER = 43
+O_ADD_H = 44
+O_REPLACE_EFFECT = 46
+O_TRIGGER_REMOTE = 47
+O_REDUCE_HEART_REQ = 48
+O_RETURN = 1
+O_JUMP = 2
+O_JUMP_F = 3
+
+# Conditions
+C_TR1 = 200
+C_CLR = 202
+C_STG = 203
+C_HND = 204
+C_CTR = 206
+C_LLD = 207
+C_GRP = 208
+C_OPH = 210
+C_ENR = 213
+C_CMP = 220
+
+
+@njit(nopython=True, cache=True)
+def resolve_bytecode(
+    bytecode,
+    flat_ctx,
+    global_ctx,
+    player_id,
+    p_hand,
+    p_deck,
+    p_stage,
+    p_energy_vec,
+    p_energy_count,
+    p_cont_vec,
+    out_cptr,  # Modified: Pass by ref array (size 1)
+    p_tapped,
+    p_live,
+    opp_tapped,
+    b_map,
+    b_idx,
+    out_bonus,  # Modified: Pass by ref array (size 1)
+):
+    ip = 0
+    # Load cptr from reference
+    cptr = out_cptr[0]
+    # Bonus is accumulated into out_bonus[0]
+
+    cond = True
+    blen = bytecode.shape[0]
+
+    # SAFETY: Infinite loop protection
+    safety_counter = 0
+
+    while ip < blen and safety_counter < 500:
+        safety_counter += 1
+        op = bytecode[ip, 0]
+        v = bytecode[ip, 1]
+        a = bytecode[ip, 2]
+        s = bytecode[ip, 3]
+
+        if op == 0:
+            ip += 1
+            continue
+        if op == O_RETURN:
+            break
+
+        # Dynamic Target Handling (MEMBER_SELECT)
+        if s == 10:
+            s = int(flat_ctx[TS])
+
+        if op == O_JUMP:
+            new_ip = ip + v
+            if 0 <= new_ip < blen:
+                ip = new_ip
+            else:
+                ip = blen
+            continue
+
+        if op == O_JUMP_F:
+            if not cond:
+                new_ip = ip + v
+                if 0 <= new_ip < blen:
+                    ip = new_ip
+                else:
+                    ip = blen
+                continue
+            ip += 1
+            continue
+
+        if op == O_SELECT_MODE:
+            choice = int(flat_ctx[CH])
+            if 0 <= choice < v:
+                jump_ip = ip + 1 + choice
+                if jump_ip < blen:
+                    offset = bytecode[jump_ip, 1]
+                    new_ip = jump_ip + offset
+                    if 0 <= new_ip < blen:
+                        ip = new_ip
+                        continue
+            ip += v + 1
+            continue
+
+        if op >= 200:
+            if op == C_TR1:
+                cond = global_ctx[TR] == 1
+            elif op == C_STG:
+                ct = 0
+                for i in range(3):
+                    if p_stage[i] != -1:
+                        ct += 1
+                cond = ct >= v
+            elif op == C_HND:
+                cond = global_ctx[HD] >= v
+            elif op == C_LLD:
+                cond = global_ctx[SC] > global_ctx[OS]
+            elif op == C_CLR:
+                if 0 <= a <= 5:
+                    cond = global_ctx[10 + a] > 0
+                else:
+                    cond = False
+            elif op == C_GRP:
+                if 0 <= a <= 4:
+                    cond = global_ctx[30 + a] >= v
+                else:
+                    cond = False
+            elif op == C_ENR:
+                cond = global_ctx[EN] >= v
+            elif op == C_CTR:
+                cond = flat_ctx[SZ] == 1
+            elif op == C_CMP:
+                if v > 0:
+                    cond = global_ctx[SC] >= v
+                else:
+                    cond = global_ctx[SC] > global_ctx[OS]
+            elif op == C_OPH:
+                ct = global_ctx[OT]
+                if v > 0:
+                    cond = ct >= v
+                else:
+                    cond = ct > 0
+            else:
+                cond = True
+            ip += 1
+        else:
+            if cond:
+                if op == O_DRAW:
+                    if global_ctx[DK] >= v:
+                        global_ctx[DK] -= v
+                        global_ctx[HD] += v
+                    else:
+                        t = global_ctx[DK]
+                        global_ctx[DK] = 0
+                        global_ctx[HD] += t
+                elif op == O_CHARGE:
+                    if global_ctx[DK] >= v:
+                        global_ctx[DK] -= v
+                        global_ctx[EN] += v
+                    else:
+                        t = global_ctx[DK]
+                        global_ctx[DK] = 0
+                        global_ctx[EN] += t
+                elif op == O_BLADES:
+                    if s >= 0 and cptr < 32:
+                        p_cont_vec[cptr, 0] = 1
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 2] = 4
+                        p_cont_vec[cptr, 3] = s
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                elif op == O_HEARTS:
+                    if cptr < 32:
+                        p_cont_vec[cptr, 0] = 2
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 5] = a
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                        global_ctx[0] += v
+                elif op == O_REDUCE_COST:
+                    if cptr < 32:
+                        p_cont_vec[cptr, 0] = 3
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 2] = s
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                elif op == O_REDUCE_HEART_REQ:
+                    if cptr < 32:
+                        p_cont_vec[cptr, 0] = 48
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 2] = s
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                elif op == O_REPLACE_EFFECT:
+                    if cptr < 32:
+                        p_cont_vec[cptr, 0] = 46
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 2] = s
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                elif op == O_RECOV_L:
+                    pass
+                elif op == O_RECOV_M:
+                    pass
+                elif op == O_ACTIVATE_MEMBER:
+                    if 0 <= s < 3:
+                        p_tapped[s] = 0
+                elif op == O_SWAP_CARDS:
+                    removed = 0
+                    for h_idx in range(60):
+                        if p_hand[h_idx] > 0:
+                            p_hand[h_idx] = 0
+                            global_ctx[HD] -= 1
+                            removed += 1
+                            if removed >= v:
+                                break
+
+                    # Actually Move Cards for Draw
+                    drawn = 0
+                    for d_idx in range(60):
+                        if p_deck[d_idx] > 0:
+                            card_id = p_deck[d_idx]
+                            p_deck[d_idx] = 0
+
+                            # Find empty hand slot
+                            for h_idx in range(60):
+                                if p_hand[h_idx] == 0:
+                                    p_hand[h_idx] = card_id
+                                    break
+
+                            global_ctx[DK] -= 1
+                            global_ctx[HD] += 1
+                            drawn += 1
+                            if drawn >= v:
+                                break
+
+                    # If not enough cards, we stop (counters already updated per card)
+
+                elif op == O_PLACE_UNDER:
+                    placed = 0
+                    for h_idx in range(59, -1, -1):
+                        if p_hand[h_idx] > 0:
+                            cid = p_hand[h_idx]
+                            p_hand[h_idx] = 0
+                            global_ctx[HD] -= 1
+
+                            if 0 <= s < 3:
+                                for e_idx in range(32):
+                                    if p_energy_vec[s, e_idx] == 0:
+                                        p_energy_vec[s, e_idx] = cid
+                                        p_energy_count[s] += 1
+                                        break
+
+                            placed += 1
+                            if placed >= v:
+                                break
+
+                elif op == O_MOVE_MEMBER:
+                    dest_slot = int(flat_ctx[TS])
+                    if 0 <= s < 3 and 0 <= dest_slot < 3 and s != dest_slot:
+                        temp_id = p_stage[s]
+                        p_stage[s] = p_stage[dest_slot]
+                        p_stage[dest_slot] = temp_id
+
+                        temp_tap = p_tapped[s]
+                        p_tapped[s] = p_tapped[dest_slot]
+                        p_tapped[dest_slot] = temp_tap
+
+                        for e_idx in range(32):
+                            temp_e = p_energy_vec[s, e_idx]
+                            p_energy_vec[s, e_idx] = p_energy_vec[dest_slot, e_idx]
+                            p_energy_vec[dest_slot, e_idx] = temp_e
+
+                        temp_ec = p_energy_count[s]
+                        p_energy_count[s] = p_energy_count[dest_slot]
+                        p_energy_count[dest_slot] = temp_ec
+
+                elif op == O_TAP_O:
+                    if 0 <= s < 3:
+                        opp_tapped[s] = 1
+                elif op == O_BUFF:
+                    if cptr < 32:
+                        p_cont_vec[cptr, 0] = 8
+                        p_cont_vec[cptr, 1] = v
+                        p_cont_vec[cptr, 2] = s
+                        p_cont_vec[cptr, 9] = 1
+                        cptr += 1
+                elif op == O_BOOST:
+                    out_bonus[0] += v
+                elif op == O_LOOK_AND_CHOOSE:
+                    choice_idx = int(flat_ctx[CH])
+                    if choice_idx < 0 or choice_idx >= v:
+                        choice_idx = 0
+
+                    indices = np.full(v, -1, dtype=np.int32)
+                    ptr = 0
+                    for d_idx in range(60):
+                        if p_deck[d_idx] > 0:
+                            indices[ptr] = d_idx
+                            ptr += 1
+                            if ptr >= v:
+                                break
+
+                    if ptr > 0:
+                        if choice_idx >= ptr:
+                            choice_idx = 0
+                        real_idx = indices[choice_idx]
+                        if real_idx != -1:
+                            chosen_card = p_deck[real_idx]
+                        if chosen_card > 0:
+                            for h_idx in range(60):
+                                if p_hand[h_idx] == 0:
+                                    p_hand[h_idx] = chosen_card
+                                    global_ctx[HD] += 1
+                                    break
+                        for k in range(ptr):
+                            rid = indices[k]
+                            if rid != -1:
+                                p_deck[rid] = 0
+                                global_ctx[DK] -= 1
+
+                elif op == O_ORDER_DECK:
+                    indices = np.full(v, -1, dtype=np.int32)
+                    vals = np.full(v, 0, dtype=np.int32)
+                    ptr = 0
+                    for d_idx in range(60):
+                        if p_deck[d_idx] > 0:
+                            indices[ptr] = d_idx
+                            vals[ptr] = p_deck[d_idx]
+                            ptr += 1
+                            if ptr >= v:
+                                break
+
+                    if ptr > 1:
+                        for k in range(ptr // 2):
+                            temp = vals[k]
+                            vals[k] = vals[ptr - 1 - k]
+                            vals[ptr - 1 - k] = temp
+
+                        for k in range(ptr):
+                            p_deck[indices[k]] = vals[k]
+
+                elif op == O_ADD_H:
+                    if global_ctx[DK] >= v:
+                        global_ctx[DK] -= v
+                        global_ctx[HD] += v
+                elif op == O_SEARCH_DECK:
+                    target_idx = int(flat_ctx[TS])
+                    if 0 <= target_idx < 60 and p_deck[target_idx] > 0:
+                        card_to_move = p_deck[target_idx]
+                        p_deck[target_idx] = 0
+                        for h_idx in range(60):
+                            if p_hand[h_idx] == 0:
+                                p_hand[h_idx] = card_to_move
+                                global_ctx[HD] += 1
+                                global_ctx[DK] -= 1
+                                break
+                    else:
+                        for d_idx in range(60):
+                            if p_deck[d_idx] > 0:
+                                card_to_move = p_deck[d_idx]
+                                p_deck[d_idx] = 0
+                                for h_idx in range(60):
+                                    if p_hand[h_idx] == 0:
+                                        p_hand[h_idx] = card_to_move
+                                        global_ctx[HD] += 1
+                                        global_ctx[DK] -= 1
+                                        break
+                                break
+
+                elif op == O_TRIGGER_REMOTE:
+                    target_slot = s
+                    if target_slot < 0:
+                        pass
+
+                    target_card_id = -1
+                    if 0 <= target_slot < 3:
+                        target_card_id = p_stage[target_slot]
+
+                    if target_card_id > 0 and target_card_id < b_idx.shape[0]:
+                        map_idx = b_idx[target_card_id, 0]
+                        if map_idx >= 0:
+                            sub_code = b_map[map_idx]
+                            out_cptr[0] = cptr
+                            resolve_bytecode(
+                                sub_code,
+                                flat_ctx,
+                                global_ctx,
+                                player_id,
+                                p_hand,
+                                p_deck,
+                                p_stage,
+                                p_energy_vec,
+                                p_energy_count,
+                                p_cont_vec,
+                                out_cptr,
+                                p_tapped,
+                                p_live,
+                                opp_tapped,
+                                b_map,
+                                b_idx,
+                                out_bonus,
+                            )
+                            cptr = out_cptr[0]
+
+            ip += 1
+
+    out_cptr[0] = cptr
+
+
+@njit(nopython=True)
+def batch_resolve_bytecode(
+    batch_bytecode,
+    batch_flat_ctx,
+    batch_global_ctx,
+    player_id,
+    p_hand,
+    p_deck,
+    p_stage,
+    p_energy_vec,
+    p_energy_count,
+    p_cont_vec,
+    p_cont_ptr,
+    p_tapped,
+    p_live,
+    opp_tapped,
+    b_map,
+    b_idx,
+):
+    num_envs = batch_bytecode.shape[0]
+    for i in prange(num_envs):
+        cptr_slice = p_cont_ptr[i : i + 1]
+        dummy_bonus = np.zeros(1, dtype=np.int32)
+
+        resolve_bytecode(
+            batch_bytecode[i],
+            batch_flat_ctx[i],
+            batch_global_ctx[i],
+            player_id,
+            p_hand[i],
+            p_deck[i],
+            p_stage[i],
+            p_energy_vec[i],
+            p_energy_count[i],
+            p_cont_vec[i],
+            cptr_slice,
+            p_tapped[i],
+            p_live[i],
+            opp_tapped[i],
+            b_map,
+            b_idx,
+            dummy_bonus,
+        )
+
+
+@njit(nopython=True, cache=True)
+def copy_state(s_stg, s_ev, s_ec, s_cv, d_stg, d_ev, d_ec, d_cv):
+    d_stg[:] = s_stg[:]
+    d_ev[:] = s_ev[:]
+    d_ec[:] = s_ec[:]
+    d_cv[:] = s_cv[:]
+
+
+@njit(nopython=True)
+def batch_apply_action(
+    actions,
+    pid,
+    p_stg,
+    p_ev,
+    p_ec,
+    p_cv,
+    p_cp,
+    p_tap,
+    p_sb,
+    p_lr,
+    o_tap,
+    f_ctx_batch,
+    g_ctx_batch,
+    p_h,
+    p_d,
+    b_map,
+    b_idx,
+):
+    # Sync individual scores and turn to global_ctx before stepping
+    for i in prange(actions.shape[0]):
+        g_ctx_batch[i, SC] = p_sb[i]
+        act_id = actions[i]
+
+        if act_id > 0:
+            card_id = act_id
+            if card_id < b_idx.shape[0]:
+                map_idx = b_idx[card_id, 0]
+                if map_idx >= 0:
+                    code_seq = b_map[map_idx]
+                    f_ctx_batch[i, 7] = 1
+
+                    cptr_slice = p_cp[i : i + 1]
+                    delta_bonus = np.zeros(1, dtype=np.int32)
+
+                    resolve_bytecode(
+                        code_seq,
+                        f_ctx_batch[i],
+                        g_ctx_batch[i],
+                        pid,
+                        p_h[i],
+                        p_d[i],
+                        p_stg[i],
+                        p_ev[i],
+                        p_ec[i],
+                        p_cv[i],
+                        cptr_slice,
+                        p_tap[i],
+                        p_lr[i],
+                        o_tap[i],
+                        b_map,
+                        b_idx,
+                        delta_bonus,
+                    )
+
+                    p_sb[i] += delta_bonus[0]
+                    f_ctx_batch[i, 7] = 0
+
+                found_h = False
+                for h_idx in range(60):
+                    if p_h[i, h_idx] == card_id:
+                        p_h[i, h_idx] = 0
+                        g_ctx_batch[i, 3] -= 1
+                        found_h = True
+                        break
+
+                if found_h and card_id < 900:
+                    for s_idx in range(3):
+                        if p_stg[i, s_idx] == -1:
+                            p_stg[i, s_idx] = card_id
+                            break
+
+                cnt = 0
+                for h_idx in range(60):
+                    if p_h[i, h_idx] > 0:
+                        cnt += 1
+
+                if cnt < 5:
+                    top_card = 0
+                    deck_idx = -1
+                    for d_idx in range(60):
+                        if p_d[i, d_idx] > 0:
+                            top_card = p_d[i, d_idx]
+                            deck_idx = d_idx
+                            break
+
+                    if top_card > 0:
+                        for h_idx in range(60):
+                            if p_h[i, h_idx] == 0:
+                                p_h[i, h_idx] = top_card
+                                p_d[i, deck_idx] = 0
+                                g_ctx_batch[i, 3] += 1
+                                g_ctx_batch[i, 6] -= 1
+                                break
+            else:
+                pass
+
+
+@njit(nopython=True, cache=True)
+def apply_action(aid, pid, p_stg, p_ev, p_ec, p_cv, p_cp, p_tap, p_sb, p_lr, o_tap, f_ctx, g_ctx, p_h, p_d):
+    # Specialized fast-path for Action 1 (Simulation)
+    if aid == 1:
+        bc = np.zeros((1, 4), dtype=np.int32)
+        bc[0, 0] = 11  # O_BLADES
+        bc[0, 1] = 1
+        bc[0, 3] = 0
+
+        d_map = np.zeros((1, 1, 4), dtype=np.int32)
+        d_idx = np.zeros((1, 4), dtype=np.int32)
+
+        cptr_arr = np.array([p_cp], dtype=np.int32)
+        bn_arr = np.zeros(1, dtype=np.int32)
+
+        resolve_bytecode(
+            bc, f_ctx, g_ctx, pid, p_h, p_d, p_stg, p_ev, p_ec, p_cv, cptr_arr, p_tap, p_lr, o_tap, d_map, d_idx, bn_arr
+        )
+        return cptr_arr[0], p_sb + bn_arr[0]
+    return p_cp, p_sb

engine/game/game_state.py

@@ -0,0 +1,3027 @@
+"""
+Love Live Card Game - AlphaZero Compatible Game State
+
+This module implements the game state representation for the Love Live
+Official Card Game, designed for fast self-play with AlphaZero-style training.
+
+Key Design Decisions:
+- Numpy arrays for vectorized operations
+- Immutable state with state copying for MCTS
+- Action space encoded as integers for neural network output
+- Observation tensors suitable for CNN input
+"""
+
+# Love Live! Card Game - Comprehensive Rules v1.04 Implementation
+
+# Rule 1: (General Overview)
+
+# Rule 2: (Card Information)
+
+# Rule 3: (Player Info)
+
+# Rule 4: (Zones)
+
+# Rule 1.3: (Fundamental Principles)
+
+# Rule 1.3.1: Card text overrides rules.
+
+# Rule 1.3.2: Impossible actions are simply not performed.
+
+# Rule 1.3.3: "Cannot" effects take priority over "Can" effects.
+
+# Rule 1.3.4: Active player chooses first when multiple choices occur.
+
+# Rule 1.3.5: Numerical selections must be non-negative integers.
+
+import json
+import os
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+from engine.game.data_loader import CardDataLoader
+from engine.game.enums import Phase
+from engine.game.mixins.action_mixin import ActionMixin
+from engine.game.mixins.effect_mixin import EffectMixin
+from engine.game.mixins.phase_mixin import PhaseMixin
+from engine.models.ability import (
+    Ability,
+    EffectType,
+    ResolvingEffect,
+    TriggerType,
+)
+from engine.models.card import LiveCard, MemberCard
+from engine.models.enums import Group, Unit
+
+# Import Numba utils
+
+# Import Numba utils
+
+try:
+    from engine.game.numba_utils import JIT_AVAILABLE, calc_main_phase_masks
+
+except ImportError:
+    JIT_AVAILABLE = False
+
+    def calc_main_phase_masks(*args):
+        pass
+
+# =============================================================================
+
+# OBJECT POOLING FOR PERFORMANCE
+
+# =============================================================================
+
+
+class StatePool:
+    """
+
+    Object pool for PlayerState and GameState to avoid allocation overhead.
+
+    Thread-local pools for multiprocessing compatibility.
+
+    """
+
+    _player_pool: List["PlayerState"] = []
+
+    _game_pool: List["GameState"] = []
+
+    _max_pool_size: int = 100
+
+    @classmethod
+    def get_player_state(cls, player_id: int) -> "PlayerState":
+        """Get a PlayerState - POOLING DISABLED for safety"""
+
+        return PlayerState(player_id)
+
+    @classmethod
+    def get_game_state(cls) -> "GameState":
+        """Get a GameState - POOLING DISABLED for safety"""
+
+        return GameState()
+
+    @classmethod
+    def return_player_state(cls, ps: "PlayerState") -> None:
+        """Return a PlayerState to the pool for reuse."""
+
+        if len(cls._player_pool) < cls._max_pool_size:
+            cls._player_pool.append(ps)
+
+    @classmethod
+    def return_game_state(cls, gs: "GameState") -> None:
+        """Return a GameState to the pool for reuse."""
+
+        if len(cls._game_pool) < cls._max_pool_size:
+            cls._game_pool.append(gs)
+
+
+# Phase enum moved to enums.py
+
+# Enums and Card Classes moved to engine.models
+
+# Imported above
+
+from engine.game.player_state import PlayerState
+
+
+class GameState(ActionMixin, PhaseMixin, EffectMixin):
+    """
+
+    Full game state (Rule 1)
+
+    Features:
+
+    - Rule 4.14: Resolution Zone (yell_cards)
+
+    - Rule 1.2: Victory Detection
+
+    - MCTS / AlphaZero support
+
+    """
+
+    # Class-level caches
+    member_db: Dict[int, MemberCard] = {}
+    live_db: Dict[int, LiveCard] = {}
+    _meta_rule_cards: set = set()
+
+    # JIT Arrays
+    _jit_member_costs: Optional[np.ndarray] = None
+    _jit_member_blades: Optional[np.ndarray] = None
+    _jit_member_hearts_sum: Optional[np.ndarray] = None
+    _jit_member_hearts_vec: Optional[np.ndarray] = None
+    _jit_live_score: Optional[np.ndarray] = None
+    _jit_live_hearts_sum: Optional[np.ndarray] = None
+    _jit_live_hearts_vec: Optional[np.ndarray] = None
+
+    @classmethod
+    def initialize_class_db(cls, member_db: Dict[int, "MemberCard"], live_db: Dict[int, "LiveCard"]) -> None:
+        """Initialize and wrap static DBs with MaskedDB for UID resolution."""
+        from engine.game.state_utils import MaskedDB
+
+        cls.member_db = MaskedDB(member_db)
+        cls.live_db = MaskedDB(live_db)
+
+        # Optimization: Cache cards with CONSTANT META_RULE effects
+        cls._meta_rule_cards = set()
+        for cid, card in cls.member_db.items():
+            for ab in card.abilities:
+                if ab.trigger.name == "CONSTANT":
+                    for eff in ab.effects:
+                        if eff.effect_type == EffectType.META_RULE:
+                            cls._meta_rule_cards.add(cid)
+                            break
+        for cid, card in cls.live_db.items():
+            for ab in card.abilities:
+                if ab.trigger.name == "CONSTANT":
+                    for eff in ab.effects:
+                        if eff.effect_type == EffectType.META_RULE:
+                            cls._meta_rule_cards.add(cid)
+                            break
+
+        cls._init_jit_arrays()
+
+    @classmethod
+    def _init_jit_arrays(cls):
+        """Initialize static arrays for Numba JIT"""
+
+        if not cls.member_db:
+            return
+
+        # Find max ID
+
+        max_id = max(max(cls.member_db.keys(), default=0), max(cls.live_db.keys(), default=0))
+
+        # Create lookup arrays (default 0 or -1)
+
+        # Costs: -1 for non-members
+
+        costs = np.full(max_id + 1, -1, dtype=np.int32)
+
+        # Blades: 0
+
+        blades = np.zeros(max_id + 1, dtype=np.int32)
+
+        # Hearts Sum: 0
+
+        hearts_sum = np.zeros(max_id + 1, dtype=np.int32)
+
+        # Hearts Vector: (N, 7)
+
+        hearts_vec = np.zeros((max_id + 1, 7), dtype=np.int32)
+
+        # Live Score: 0
+
+        live_score = np.zeros(max_id + 1, dtype=np.int32)
+
+        # Live Hearts Requirement Sum: 0
+
+        live_hearts_sum = np.zeros(max_id + 1, dtype=np.int32)
+
+        # Live Hearts Vector: (N, 7)
+
+        live_hearts_vec = np.zeros((max_id + 1, 7), dtype=np.int32)
+
+        for cid, member in cls.member_db.items():
+            costs[cid] = member.cost
+
+            blades[cid] = member.blades
+
+            if hasattr(member, "hearts"):
+                h = member.hearts
+                # Robustly handle arrays likely to be shape (6,) or (7,)
+                if len(h) >= 7:
+                    hearts_vec[cid] = h[:7]
+                else:
+                    hearts_vec[cid, : len(h)] = h
+
+                hearts_sum[cid] = np.sum(member.hearts)
+
+        for cid, live in cls.live_db.items():
+            live_score[cid] = int(live.score)
+
+            if hasattr(live, "required_hearts"):
+                rh = live.required_hearts
+                if len(rh) >= 7:
+                    live_hearts_vec[cid] = rh[:7]
+                else:
+                    live_hearts_vec[cid, : len(rh)] = rh
+
+                live_hearts_sum[cid] = np.sum(live.required_hearts)
+
+        cls._jit_member_costs = costs
+
+        cls._jit_member_blades = blades
+
+        cls._jit_member_hearts_sum = hearts_sum
+
+        cls._jit_member_hearts_vec = hearts_vec
+
+        cls._jit_live_score = live_score
+
+        cls._jit_live_hearts_sum = live_hearts_sum
+
+        cls._jit_live_hearts_vec = live_hearts_vec
+
+    @classmethod
+    def serialize_card(cls, cid: int, is_viewable=True, peek=False):
+        """Static helper to serialize a card ID."""
+
+        if cid < 0:
+            return None
+
+        card_data = {"id": int(cid), "img": "cards/card_back.png", "type": "unknown", "name": "Unknown"}
+
+        if not is_viewable and not peek:
+            return {"id": int(cid), "img": "cards/card_back.png", "type": "unknown", "hidden": True}
+
+        if cid in cls.member_db:
+            m = cls.member_db[cid]
+
+            # Basic ability text formatting
+
+            at = getattr(m, "ability_text", "")
+
+            if not at and hasattr(m, "abilities"):
+                at_lines = []
+
+                for ab in m.abilities:
+                    at_lines.append(ab.raw_text)
+
+                at = "\n".join(at_lines)
+
+            card_data = {
+                "id": int(cid),
+                "card_no": getattr(m, "card_no", "Unknown"),
+                "name": getattr(m, "name", "Unknown Member"),
+                "cost": int(getattr(m, "cost", 0)),
+                "type": "member",
+                "hp": int(m.total_hearts()) if hasattr(m, "total_hearts") else 0,
+                "blade": int(getattr(m, "blades", 0)),
+                "img": getattr(m, "img_path", "cards/card_back.png"),
+                "hearts": m.hearts.tolist() if hasattr(m, "hearts") and hasattr(m.hearts, "tolist") else [0] * 7,
+                "blade_hearts": m.blade_hearts.tolist()
+                if hasattr(m, "blade_hearts") and hasattr(m.blade_hearts, "tolist")
+                else [0] * 7,
+                "text": at,
+            }
+
+        elif cid in cls.live_db:
+            l = cls.live_db[cid]
+
+            card_data = {
+                "id": int(cid),
+                "card_no": getattr(l, "card_no", "Unknown"),
+                "name": l.name,
+                "type": "live",
+                "score": int(l.score),
+                "img": l.img_path,
+                "required_hearts": l.required_hearts.tolist(),
+                "text": getattr(l, "ability_text", ""),
+            }
+
+        elif cid == 888:  # Easy member
+            card_data = {
+                "id": 888,
+                "name": "Easy Member",
+                "type": "member",
+                "cost": 1,
+                "hp": 1,
+                "blade": 1,
+                "img": "cards/PLSD01/PL!-sd1-001-SD.png",
+                "hearts": [1, 0, 0, 0, 0, 0, 0],
+                "blade_hearts": [0, 0, 0, 0, 0, 0, 0],
+                "text": "",
+            }
+
+        elif cid == 999:  # Easy live
+            card_data = {
+                "id": 999,
+                "name": "Easy Live",
+                "type": "live",
+                "score": 1,
+                "img": "cards/PLSD01/PL!-pb1-019-SD.png",
+                "required_hearts": [0, 0, 0, 0, 0, 0, 1],
+                "text": "",
+            }
+
+        if not is_viewable and peek:
+            card_data["hidden"] = True
+
+            card_data["face_down"] = True
+
+        return card_data
+
+    __slots__ = (
+        "verbose",
+        "players",
+        "current_player",
+        "first_player",
+        "phase",
+        "turn_number",
+        "game_over",
+        "winner",
+        "performance_results",
+        "yell_cards",
+        "pending_effects",
+        "pending_choices",
+        "rule_log",
+        "current_resolving_ability",
+        "current_resolving_member",
+        "current_resolving_member_id",
+        "looked_cards",
+        "triggered_abilities",
+        "state_history",
+        "loop_draw",
+        "removed_cards",
+        "action_count_this_turn",
+        "pending_choices_vec",
+        "pending_choices_ptr",
+        "triggered_abilities_vec",
+        "triggered_abilities_ptr",
+        "_jit_dummy_array",
+        "fast_mode",
+        "suppress_logs",
+        "enable_loop_detection",
+        "_trigger_buffers",
+    )
+
+    def __init__(self, verbose=False, suppress_logs=False, enable_loop_detection=True):
+        self.verbose = verbose
+        self.suppress_logs = suppress_logs
+        self.enable_loop_detection = enable_loop_detection
+
+        self.players = [PlayerState(0), PlayerState(1)]
+
+        self.current_player = 0  # Who is acting now
+
+        self.first_player = 0  # Who goes first this turn
+
+        self.phase = Phase.ACTIVE
+
+        self.turn_number: int = 1
+
+        self.game_over: bool = False
+
+        self.winner: int = -1  # -1 = ongoing, 0/1 = player won, 2 = draw
+
+        # Performance Result Tracking (for UI popup)
+
+        self.performance_results: Dict[int, Any] = {}
+
+        # For yell phase tracking
+
+        self.yell_cards: List[int] = []  # Shared Resolution Zone (Rule 4.14)
+
+        self.pending_effects: List[ResolvingEffect] = []  # Stack of effects to resolve
+
+        self.pending_activation: Optional[Dict[str, Any]] = None
+
+        self.pending_choices: List[Tuple[str, Dict[str, Any]]] = []  # (choice_type, params with metadata)
+
+        self.rule_log: List[str] = []  # Real-time rule application log
+
+        # Track currently resolving ability for context
+
+        self.current_resolving_ability: Optional[Ability] = None
+
+        self.current_resolving_member: Optional[str] = None  # Member name
+
+        self.current_resolving_member_id: int = -1  # Member card ID
+
+        # Temporary zone for LOOK_DECK
+
+        self.looked_cards: List[int] = []
+
+        # Rule 9.7: Automatic Abilities
+
+        # List of (player_id, Ability, context) waiting to be played
+
+        self.triggered_abilities: List[Tuple[int, Ability, Dict[str, Any]]] = []
+
+        # Vectorized triggers/choices for JIT
+        self.pending_choices_vec = np.zeros((16, 3), dtype=np.int32)
+        self.pending_choices_ptr = 0
+        self.triggered_abilities_vec = np.zeros((16, 2), dtype=np.int32)
+        self.triggered_abilities_ptr = 0
+        self._jit_dummy_array = np.zeros(100, dtype=np.int32)
+        self.fast_mode = False
+        self._trigger_buffers = [[], []]  # Pre-allocated buffers for trigger processing
+
+        # Static caches (for performance and accessibility)
+
+        # Should be set from server or data loader
+
+        # Loop Detection (Rule 12.1)
+
+        # Using a simple hash of the serialization for history
+
+        self.state_history: List[int] = []
+
+        self.loop_draw = False
+
+        self.removed_cards: List[int] = []
+
+        self.action_count_this_turn: int = 0
+
+    def log_rule(self, rule_id: str, description: str):
+        """Append a rule application entry to the log."""
+        if self.suppress_logs:
+            return
+
+        # Add Turn and Phase context
+
+        phase_name = self.phase.name if hasattr(self.phase, "name") else str(self.phase)
+
+        entry = f"[Turn {self.turn_number}] [{phase_name}] [{rule_id}] {description}"
+
+        self.rule_log.append(entry)
+
+        # Also print to stdout for server console debugging
+
+        if self.verbose:
+            print(f"RULE_LOG: {entry}")
+            pass
+
+    def _reset(self) -> None:
+        """Reset state for pool reuse - avoids object allocation."""
+
+        self.verbose = False
+
+        # Players get reset by PlayerState._reset or replaced
+
+        self.current_player = 0
+
+        self.first_player = 0
+
+        self.phase = Phase.ACTIVE
+
+        self.turn_number = 1
+
+        self.game_over = False
+
+        self.winner = -1
+
+        self.performance_results.clear()
+
+        self.yell_cards.clear()
+
+        self.pending_effects.clear()
+
+        self.pending_choices.clear()
+
+        self.rule_log.clear()
+
+        self.current_resolving_ability = None
+
+        self.current_resolving_member = None
+
+        self.current_resolving_member_id = -1
+
+        self.looked_cards.clear()
+
+        self.triggered_abilities.clear()
+
+        self.pending_choices_vec.fill(0)
+        self.pending_choices_ptr = 0
+        self.triggered_abilities_vec.fill(0)
+        self.triggered_abilities_ptr = 0
+        self._trigger_buffers[0].clear()
+        self._trigger_buffers[1].clear()
+
+        self.state_history.clear()
+
+        self.loop_draw = False
+
+    def copy(self) -> "GameState":
+        """Copy current game state"""
+
+        new = GameState()
+
+        self.copy_to(new)
+
+        return new
+
+    def copy_to(self, new: "GameState") -> None:
+        """In-place copy to an existing object to avoid allocation"""
+
+        new.verbose = self.verbose
+        new.suppress_logs = self.suppress_logs
+        new.enable_loop_detection = self.enable_loop_detection
+
+        # Reuse existing PlayerState objects in the pooled GameState
+
+        for i, p in enumerate(self.players):
+            p.copy_to(new.players[i])
+
+        new.current_player = self.current_player
+
+        new.first_player = self.first_player
+
+        new.phase = self.phase
+
+        new.turn_number = self.turn_number
+
+        new.game_over = self.game_over
+
+        new.winner = self.winner
+
+        new.yell_cards = list(self.yell_cards)
+
+        # Shallow copy of Effect objects (assumed immutable/shared)
+
+        new.pending_effects = list(self.pending_effects)
+
+        # Manual copy of pending_choices: List[Tuple[str, Dict]]
+
+        new.pending_choices = [(pc[0], pc[1].copy()) for pc in self.pending_choices]
+
+        new.rule_log = list(self.rule_log)
+
+        new.current_resolving_ability = self.current_resolving_ability
+
+        new.current_resolving_member = self.current_resolving_member
+
+        new.current_resolving_member_id = self.current_resolving_member_id
+
+        new.looked_cards = list(self.looked_cards)
+
+        # Manual copy of triggered_abilities: List[Tuple[int, Ability, Dict[str, Any]]]
+
+        # Tuple is immutable, Ability is shared, Dict needs copy
+
+        new.triggered_abilities = [(ta[0], ta[1], ta[2].copy()) for ta in self.triggered_abilities]
+
+        # Copy vectorized state
+        np.copyto(new.pending_choices_vec, self.pending_choices_vec)
+        new.pending_choices_ptr = self.pending_choices_ptr
+        np.copyto(new.triggered_abilities_vec, self.triggered_abilities_vec)
+        new.triggered_abilities_ptr = self.triggered_abilities_ptr
+        new.fast_mode = self.fast_mode
+        new._trigger_buffers = [list(self._trigger_buffers[0]), list(self._trigger_buffers[1])]
+
+        new.state_history = list(self.state_history)
+
+        new.loop_draw = self.loop_draw
+
+        new.loop_draw = self.loop_draw
+
+        # Optimization: Use shallow copy instead of deepcopy.
+        # The engine only performs assignment (replace) or clear() (structure),
+        # not in-place mutation of the nested lists.
+        new.performance_results = self.performance_results.copy()
+
+        # Copy deferred activation state (Rule 9.7 logic)
+        if hasattr(self, "pending_activation") and self.pending_activation:
+            new.pending_activation = self.pending_activation.copy()
+            if "context" in new.pending_activation:
+                new.pending_activation["context"] = new.pending_activation["context"].copy()
+        else:
+            new.pending_activation = None
+
+    def inject_card(self, player_idx: int, card_id: int, zone: str, position: int = -1) -> None:
+        """Inject a card into a specific zone for testing purposes."""
+
+        if player_idx < 0 or player_idx >= len(self.players):
+            raise ValueError("Invalid player index")
+
+        p = self.players[player_idx]
+
+        if zone == "hand":
+            if position == -1:
+                p.hand.append(card_id)
+
+            else:
+                p.hand.insert(position, card_id)
+
+        elif zone == "energy":
+            if position == -1:
+                p.energy_zone.append(card_id)
+
+            else:
+                p.energy_zone.insert(position, card_id)
+
+        elif zone == "live":
+            if position == -1:
+                p.live_zone.append(card_id)
+
+                p.live_zone_revealed.append(False)
+
+            else:
+                p.live_zone.insert(position, card_id)
+
+                p.live_zone_revealed.insert(position, False)
+
+        elif zone == "stage":
+            if position < 0 or position >= 3:
+                raise ValueError("Stage position must be 0-2")
+
+            p.stage[position] = card_id
+
+        else:
+            raise ValueError(f"Invalid zone: {zone}")
+
+    @property
+    def active_player(self) -> PlayerState:
+        return self.players[self.current_player]
+
+    @property
+    def inactive_player(self) -> PlayerState:
+        return self.players[1 - self.current_player]
+
+    def is_terminal(self) -> bool:
+        """Check if game has ended"""
+
+        return self.game_over
+
+    def get_winner(self) -> int:
+        """Returns winner (0 or 1) or -1 if not terminal, 2 if draw"""
+
+        return self.winner
+
+    def check_win_condition(self) -> None:
+        """Check if anyone has won (3+ successful lives)"""
+
+        p0_lives = len(self.players[0].success_lives)
+
+        p1_lives = len(self.players[1].success_lives)
+
+        if p0_lives >= 3 and p1_lives >= 3:
+            self.game_over = True
+
+            if p0_lives > p1_lives:
+                self.winner = 0
+
+            elif p1_lives > p0_lives:
+                self.winner = 1
+
+            else:
+                self.winner = 2  # Draw
+
+        elif p0_lives >= 3:
+            # Rule 1.2.1.1: Player 0 wins by 3 successful lives
+            self.game_over = True
+            self.winner = 0
+            if hasattr(self, "log_rule"):
+                self.log_rule("Rule 1.2.1.1", "Player 0 wins by 3 successful lives.")
+
+        elif p1_lives >= 3:
+            # Rule 1.2.1.1: Player 1 wins by 3 successful lives
+            self.game_over = True
+            self.winner = 1
+            if hasattr(self, "log_rule"):
+                self.log_rule("Rule 1.2.1.1", "Player 1 wins by 3 successful lives.")
+
+    def _is_card_legal_for_choice(self, card_id: int, params: Dict[str, Any]) -> bool:
+        """Helper to check if a card matches the filter criteria for a choice."""
+        if card_id < 0:
+            return False
+
+        # Determine if it's a member or live card
+        card = self.member_db.get(card_id) or self.live_db.get(card_id)
+        if not card:
+            return False
+
+        # 1. Type filter
+        req_type = params.get("filter", params.get("type"))
+        if req_type == "member" and card_id not in self.member_db:
+            return False
+        if req_type == "live" and card_id not in self.live_db:
+            return False
+
+        # 2. Group filter
+        group_filter = params.get("group")
+        if group_filter:
+            target_group = Group.from_japanese_name(group_filter)
+            if target_group not in getattr(card, "groups", []):
+                # Also check units just in case
+                target_unit = Unit.from_japanese_name(group_filter)
+                if target_unit not in getattr(card, "units", []):
+                    return False
+
+        # 3. Cost filter
+        cost_max = params.get("cost_max")
+        if cost_max is not None and getattr(card, "cost", 0) > cost_max:
+            return False
+
+        cost_min = params.get("cost_min")
+        if cost_min is not None and getattr(card, "cost", 0) < cost_min:
+            return False
+
+        return True
+
+    def get_legal_actions(self) -> np.ndarray:
+        """
+
+        Returns a mask of legal actions (Rule 9.5.4:
+
+        Expanded for Complexity:
+
+        200-202: Activate ability of member in Area (LEFT, CENTER, RIGHT)
+
+        300-359: Mulligan toggle
+
+        400-459: Live Set
+
+        500-559: Choose card in hand (index 0-59) for effect target
+
+        560-562: Choose member on stage (Area 0-2) for effect target
+
+        590-599: Choose pending trigger to resolve
+
+        """
+
+        mask = np.zeros(2000, dtype=bool)
+
+        if self.game_over:
+            return mask
+
+        # Priority: If there are choices to be made for a pending effect
+
+        if self.pending_choices:
+            choice_type, params = self.pending_choices[0]
+
+            p_idx = params.get("player_id", self.current_player)
+
+            p = self.players[p_idx]
+
+            if choice_type == "TARGET_HAND":
+                # Allow skip for optional costs
+
+                if params.get("is_optional"):
+                    mask[0] = True
+
+                found = False
+
+                if len(p.hand) > 0:
+                    for i, cid in enumerate(p.hand):
+                        is_legal = self._is_card_legal_for_choice(cid, params)
+                        if self.verbose:
+                            print(f"DEBUG: TARGET_HAND check idx={i} cid={cid} legal={is_legal} params={params}")
+                        if is_legal:
+                            mask[500 + i] = True
+
+                            found = True
+
+                if not found:
+                    mask[0] = True  # No valid cards in hand, allow pass logic (fizzle)
+
+            elif choice_type == "TARGET_MEMBER" or choice_type == "TARGET_MEMBER_SLOT":
+                # 560-562: Selected member on stage
+
+                found = False
+
+                for i in range(3):
+                    if p.stage[i] >= 0 or choice_type == "TARGET_MEMBER_SLOT":
+                        # Filter: for 'activate', only tapped members are legal
+
+                        if params.get("effect") == "activate" and not p.tapped_members[i]:
+                            continue
+
+                        # Apply general filters if card exists
+
+                        if p.stage[i] >= 0:
+                            if not self._is_card_legal_for_choice(p.stage[i], params):
+                                continue
+
+                        mask[560 + i] = True
+
+                        found = True
+
+                if not found:
+                    mask[0] = True  # No valid targets on stage, allow pass (fizzle)
+
+            elif choice_type == "DISCARD_SELECT":
+                # 500-559: Select card in hand to discard
+
+                # Allow skip for optional costs
+
+                if params.get("is_optional"):
+                    mask[0] = True
+
+                found = False
+
+                if len(p.hand) > 0:
+                    for i, cid in enumerate(p.hand):
+                        if self._is_card_legal_for_choice(cid, params):
+                            mask[500 + i] = True
+
+                            found = True
+
+                if not found and params.get("is_optional"):
+                    mask[0] = True  # No cards to discard, allow pass
+
+            elif choice_type == "MODAL" or choice_type == "SELECT_MODE":
+                # params['options'] is a list of strings or list of lists
+
+                options = params.get("options", [])
+
+                for i in range(len(options)):
+                    mask[570 + i] = True
+
+            elif choice_type == "CHOOSE_FORMATION":
+                # For now, just a dummy confirm? Or allow re-arranging?
+
+                # Simplified: Action 0 to confirm current formation
+
+                mask[0] = True
+
+            elif choice_type == "COLOR_SELECT":
+                # 580: Red, 581: Blue, 582: Green, 583: Yellow, 584: Purple, 585: Pink
+
+                for i in range(6):
+                    mask[580 + i] = True
+
+            elif choice_type == "TARGET_OPPONENT_MEMBER":
+                # Opponent Stage 0-2 -> Action 600-602
+
+                opp = self.inactive_player
+
+                found = False
+
+                for i in range(3):
+                    if opp.stage[i] >= 0:
+                        mask[600 + i] = True
+
+                        found = True
+
+                if not found:
+                    # If no valid targets but choice exists, softlock prevention:
+
+                    # Ideally we should strictly check before pushing choice, but safe fallback:
+
+                    mask[0] = True  # Pass/Cancel
+
+            elif choice_type == "SELECT_FROM_LIST":
+                # 600-659: List selection (up to 60 items)
+
+                cards = params.get("cards", [])
+
+                card_count = min(len(cards), 60)
+
+                if card_count > 0:
+                    mask[600 : 600 + card_count] = True
+
+                else:
+                    mask[0] = True  # Empty list, allow pass
+
+            elif choice_type == "SELECT_FROM_DISCARD":
+                # 660-719: Discard selection (up to 60 items)
+
+                cards = params.get("cards", [])
+
+                card_count = min(len(cards), 60)
+
+                if card_count > 0:
+                    mask[660 : 660 + card_count] = True
+
+                else:
+                    mask[0] = True  # Empty discard, allow pass
+
+            elif choice_type == "SELECT_FORMATION_SLOT" or choice_type == "SELECT_ORDER":
+                # 720-759: Item selection from a list (Formation)
+                cards = params.get("cards", params.get("available_members", []))
+                card_count = min(len(cards), 40)
+                if card_count > 0:
+                    mask[720 : 720 + card_count] = True
+                else:
+                    mask[0] = True
+
+            elif choice_type == "SELECT_SWAP_SOURCE":
+                # 600-659: Reuse list selection range
+
+                cards = params.get("cards", [])
+
+                card_count = min(len(cards), 60)
+
+                if card_count > 0:
+                    mask[600 : 600 + card_count] = True
+
+                else:
+                    mask[0] = True
+
+            elif choice_type == "SELECT_SWAP_TARGET":
+                # 500-559: Target hand range
+
+                if len(p.hand) > 0:
+                    for i in range(len(p.hand)):
+                        mask[500 + i] = True
+
+                else:
+                    mask[0] = True
+
+            elif choice_type == "SELECT_SUCCESS_LIVE" or choice_type == "TARGET_SUCCESS_LIVES":
+                # 760-819: Select from passed lives list (Score)
+                cards = params.get("cards", p.success_lives)
+                card_count = min(len(cards), 60)
+                if card_count > 0:
+                    mask[760 : 760 + card_count] = True
+                else:
+                    mask[0] = True
+
+            elif choice_type == "TARGET_LIVE":
+                # 820-822: Select specific slot in Live Zone
+                for i in range(len(p.live_zone)):
+                    mask[820 + i] = True
+                if not any(mask[820:823]):
+                    mask[0] = True
+
+            elif choice_type == "TARGET_ENERGY_ZONE":
+                # 830-849: Select specific card in Energy Zone
+                for i in range(len(p.energy_zone)):
+                    if i < 20:
+                        mask[830 + i] = True
+                if not any(mask[830:850]):
+                    mask[0] = True
+
+            elif choice_type == "TARGET_REMOVED":
+                # 850-909: Select from Removed cards
+                count = min(len(self.removed_cards), 60)
+                if count > 0:
+                    mask[850 : 850 + count] = True
+                else:
+                    mask[0] = True
+
+            elif choice_type == "TARGET_DECK" or choice_type == "TARGET_ENERGY_DECK" or choice_type == "TARGET_DISCARD":
+                # List selection ranges
+                cards = params.get("cards", [])
+                card_count = min(len(cards), 60)
+                offset = 600 if choice_type != "TARGET_DISCARD" else 660
+                if card_count > 0:
+                    mask[offset : offset + card_count] = True
+                else:
+                    mask[0] = True
+
+        # MULLIGAN phases: Select cards to return or confirm mulligan
+
+        elif self.phase in (Phase.MULLIGAN_P1, Phase.MULLIGAN_P2):
+            p = self.active_player
+
+            mask[0] = True  # Confirm mulligan (done selecting)
+
+            # Actions 300-359: Select card for mulligan (card index 0-59)
+
+            # Note: We allow toggling selection.
+
+            m_sel = getattr(p, "mulligan_selection", set())
+
+            for i in range(len(p.hand)):
+                mask[300 + i] = True
+
+        # Auto-advance phases: these phases process automatically in 'step' when any valid action is received
+
+        # We allow Action 0 (Pass) to trigger the transition.
+
+        elif self.phase in (Phase.ACTIVE, Phase.ENERGY):
+            mask[0] = True
+        elif self.phase == Phase.PERFORMANCE_P1 or self.phase == Phase.PERFORMANCE_P2:
+            p = self.active_player
+            mask[0] = True  # Always can pass (skip performance)
+
+            # Check all lives in live zone
+            for i, card_id in enumerate(p.live_zone):
+                # Standard Live ID as Action ID
+                if card_id in self.live_db:
+                    live_card = self.live_db[card_id]
+
+                    # Check requirements
+                    reqs = getattr(live_card, "required_hearts", [0] * 7)
+                    if len(reqs) < 7:
+                        reqs = [0] * 7
+
+                    stage_hearts = [0] * 7
+                    total_blades = 0
+
+                    for slot in range(3):
+                        sid = p.stage[slot]
+                        if sid in self.member_db:
+                            m = self.member_db[sid]
+                            total_blades += m.blades
+
+                            # Determine color index (1-6) from hearts
+                            # Heuristic: Find first non-zero index in hearts array
+                            # This mimics vector_env logic
+                            col = 0
+                            h_arr = m.hearts
+                            for cidx, val in enumerate(h_arr):
+                                if val > 0:
+                                    col = cidx + 1
+                                    break
+
+                            if 1 <= col <= 6:
+                                stage_hearts[col] += m.hearts[col - 1]  # m.hearts is 0-indexed?
+                                # Wait, GameState initializes hearts_vec with m.hearts
+                                # m.hearts is usually [Pink, Red, ...]
+                                # Let's assume m.hearts is standard 7-dim or 6-dim
+                                # If m.hearts[0] is Pink (Color 1), then:
+                                pass
+
+                    # Re-calculating correctly using GameState helper if available,
+                    # else manual sum matching VectorEnv
+
+                    # Optimized check:
+                    # Use existing helper? p.get_effective_hearts?
+                    # But that returns vector.
+
+                    # Let's use p.stage stats directly
+                    current_hearts = [0] * 7
+                    current_blades = 0
+                    for slot in range(3):
+                        if p.stage[slot] != -1:
+                            eff_h = p.get_effective_hearts(slot, self.member_db)
+                            for c in range(7):
+                                current_hearts[c] += eff_h[c]
+                            current_blades += p.get_effective_blades(slot, self.member_db)
+
+                    # Check against reqs
+                    # reqs[0] is usually Any? Or Pink?
+                    # In VectorEnv: 12-18 (Pink..Purple, All)
+                    # live_card.required_hearts is 0-indexed typically [Pink, Red, Yel, Grn, Blu, Pur, Any]
+
+                    met = True
+                    # Check colors (0-5)
+                    for c in range(6):
+                        if current_hearts[c] < reqs[c]:
+                            met = False
+                            break
+                    # Check Any (index 6, matches any color + explicit Any?)
+                    # Usually Any req is satisfied by sum of all?
+                    # For strictness, let's assume reqs[6] is specific "Any" points needed (wildcard).
+                    # VectorEnv logic was:
+                    # if stage_hearts[1] < req_pink...
+
+                    # Assuming standard behavior:
+                    if met and current_blades > 0:
+                        mask[900 + i] = True
+
+        elif self.phase == Phase.DRAW or self.phase == Phase.LIVE_RESULT:
+            mask[0] = True
+
+        elif self.phase == Phase.MAIN:
+            p = self.active_player
+
+            # Can always pass
+
+            mask[0] = True
+
+            # --- SHARED PRE-CALCULATIONS ---
+
+            available_energy = p.count_untapped_energy()
+
+            total_reduction = 0
+
+            for ce in p.continuous_effects:
+                if ce["effect"].effect_type == EffectType.REDUCE_COST:
+                    total_reduction += ce["effect"].value
+
+            # --- PLAY MEMBERS ---
+
+            if "placement" not in p.restrictions:
+                # JIT Optimization Path
+
+                # JIT Path disabled temporarily for training stability
+
+                if False and JIT_AVAILABLE and self._jit_member_costs is not None:
+                    # Use pre-allocated hand buffer to avoid reallocation
+
+                    hand_len = len(p.hand)
+
+                    if hand_len > 0:
+                        p.hand_buffer[:hand_len] = p.hand
+
+                    calc_main_phase_masks(
+                        p.hand_buffer[:hand_len],
+                        p.stage,
+                        available_energy,
+                        total_reduction,
+                        True,  # Baton touch is always allowed if slot occupied
+                        p.members_played_this_turn,
+                        self._jit_member_costs,
+                        mask,
+                    )
+
+                else:
+                    # Python Fallback
+
+                    for i, card_id in enumerate(p.hand):
+                        if card_id not in self.member_db:
+                            continue
+
+                        member = self.member_db[card_id]
+
+                        for area in range(3):
+                            action_id = 1 + i * 3 + area
+
+                            if p.members_played_this_turn[area]:
+                                continue
+
+                            is_baton = p.stage[area] >= 0
+
+                            # Calculate effective baton touch limit
+                            extra_baton = sum(
+                                ce["effect"].value
+                                for ce in p.continuous_effects
+                                if ce["effect"].effect_type == EffectType.BATON_TOUCH_MOD
+                            )
+                            effective_baton_limit = p.baton_touch_limit + extra_baton
+
+                            if is_baton and p.baton_touch_count >= effective_baton_limit:
+                                continue
+
+                            # Calculate slot-specific cost
+                            slot_reduction = sum(
+                                ce["effect"].value
+                                for ce in p.continuous_effects
+                                if ce["effect"].effect_type == EffectType.REDUCE_COST
+                                and (ce.get("target_slot", -1) in (-1, area))
+                            )
+
+                            active_cost = max(0, member.cost - slot_reduction)
+
+                            if is_baton:
+                                if p.stage[area] in self.member_db:
+                                    baton_mem = self.member_db[p.stage[area]]
+                                    active_cost = max(0, active_cost - baton_mem.cost)
+
+                            if active_cost <= available_energy:
+                                mask[action_id] = True
+
+                            # DEBUG: Trace why specific cards fail
+
+                            elif self.verbose and (member.cost >= 10 or card_id == 369):
+                                print(
+                                    f"DEBUG REJECT: Card {card_id} ({getattr(member, 'name', 'Unknown')}) Area {area}: Cost {active_cost} > Energy {available_energy}. Limit {p.baton_touch_limit}, Count {p.baton_touch_count}"
+                                )
+
+            # --- ACTIVATE ABILITIES ---
+
+            # Uses same available_energy
+
+            for i, card_id in enumerate(p.stage):
+                if card_id >= 0 and card_id in self.member_db and not p.tapped_members[i]:
+                    member = self.member_db[card_id]
+
+                    for abi_idx, ab in enumerate(member.abilities):
+                        if ab.trigger == TriggerType.ACTIVATED:
+                            # Rule 9.7: Check once per turn
+                            abi_key = f"{card_id}-{abi_idx}"
+                            if ab.is_once_per_turn and abi_key in p.used_abilities:
+                                continue
+
+                            # Strict verification: Check conditions and costs
+
+                            is_legal = True
+
+                            if not all(self._check_condition(p, cond, context={"area": i}) for cond in ab.conditions):
+                                is_legal = False
+
+                            if is_legal and not self._can_pay_costs(p, ab.costs, source_area=i):
+                                # print(f"DEBUG: Cost check failed for card {card_id} area {i}. Costs: {ab.costs}")
+                                is_legal = False
+
+                            if is_legal:
+                                mask[200 + i] = True
+                                # else:
+                                # print(f"DEBUG: Ability {ab.raw_text} illegal for card {card_id} area {i}")
+
+                                break  # Only one ability activation per member slot
+
+        elif self.phase == Phase.LIVE_SET:
+            p = self.active_player
+
+            mask[0] = True
+
+            # Check live restriction (Rule 8.3.4.1 / Cluster 3)
+
+            if "live" not in p.restrictions and len(p.live_zone) < 3:
+                # Allow ANY card to be set (Rule 8.2.2: "Choose up to 3 cards from your hand")
+                for i, card_id in enumerate(p.hand):
+                    mask[400 + i] = True
+
+        else:
+            # Other phases are automatic
+
+            mask[0] = True
+
+        # Safety check: Ensure at least one action is legal to prevent softlocks
+
+        if not np.any(mask):
+            # Force action 0 (Pass) as legal
+
+            mask[0] = True
+
+            # print(f"WARNING: No legal actions found in phase {self.phase.name}, forcing Pass action")
+
+        return mask
+
+    def step(self, action_id: int, check_legality: bool = True, in_place: bool = False) -> "GameState":
+        """
+
+        Executes one step in the game (Rule 9).
+
+        Args:
+            action_id: The action to execute.
+            check_legality: Whether to verify action legality. Disable for speed if caller guarantees validity.
+            in_place: If True, modifies the state in-place instead of copying. Faster for RL.
+
+        """
+        self.action_count_this_turn += 1
+        if self.action_count_this_turn > 1000:
+            self.game_over = True
+            self.winner = 2  # Draw due to runaway logic
+            self.log_rule("Safety", "Turn exceeded 1000 actions. Force terminating as Draw.")
+            return self
+
+        if self.game_over:
+            print(f"WARNING: Step called after Game Over (Winner: {self.winner}). Ignoring action {action_id}.")
+
+            return self
+
+        # Strict validation for debugging
+        if check_legality:
+            legal_actions = self.get_legal_actions()
+
+            if not legal_actions[action_id]:
+                # Soft fallback for illegal moves to prevent crashes
+                legal_indices = np.where(legal_actions)[0]
+
+                # print(
+                #     f"ILLEGAL MOVE CAUGHT: Action {action_id} in phase {self.phase}. "
+                #     f"PendingChoices: {len(self.pending_choices)}. "
+                #     f"Fallback to first legal action: {legal_indices[0] if len(legal_indices) > 0 else 'None'}"
+                # )
+
+                if len(legal_indices) > 0:
+                    if 0 in legal_indices:
+                        action_id = 0
+                    else:
+                        action_id = int(legal_indices[0])
+                else:
+                    self.game_over = True
+                    self.winner = -2  # Special code for illegal move failure
+                    return self
+
+        if in_place:
+            new_state = self
+        else:
+            new_state = self.copy()
+
+        new_state.log_rule("Rule 9.5", f"Processing action {action_id} in {new_state.phase} phase.")
+
+        # Check rule conditions before acting (Rule 9.5.1 / 10.1.2)
+        # MUST be done on new_state
+        new_state._process_rule_checks()
+
+        # Rule 9.5.4.1: Check timing occurs before play timing
+        new_state._process_rule_checks()
+
+        # Priority: If waiting for a choice (like targeting), handles that action
+
+        if new_state.pending_choices:
+            new_state._handle_choice(action_id)
+
+        # Otherwise, if resolving a complex effect stack
+
+        elif new_state.pending_effects:
+            new_state._resolve_pending_effect(0)  # 0 is dummy action for auto-res
+
+        # Normal action execution
+
+        else:
+            new_state._execute_action(action_id)
+
+        # After any action, automatically process non-choice effects
+
+        while new_state.pending_effects and not new_state.pending_choices:
+            new_state._resolve_pending_effect(0)  # 0 is dummy action for auto-res
+
+        # Rule 9.5.1: Final check timing after action resolution
+
+        new_state._process_rule_checks()
+
+        # Rule 12.1: Infinite Loop Detection
+
+        # Skip for Mulligan phases and if disabled
+
+        if new_state.enable_loop_detection and new_state.phase not in (Phase.MULLIGAN_P1, Phase.MULLIGAN_P2):
+            try:
+                # Capture key state tuple
+
+                state_tuple = (
+                    new_state.phase,
+                    new_state.current_player,
+                    tuple(sorted(new_state.players[0].hand)),
+                    tuple(new_state.players[0].stage),
+                    tuple(tuple(x) for x in new_state.players[0].stage_energy),
+                    tuple(new_state.players[0].energy_zone),
+                    tuple(sorted(new_state.players[1].hand)),
+                    tuple(new_state.players[1].stage),
+                    tuple(tuple(x) for x in new_state.players[1].stage_energy),
+                    tuple(new_state.players[1].energy_zone),
+                    tuple(sorted(list(new_state.players[0].used_abilities))),
+                    tuple(sorted(list(new_state.players[1].used_abilities))),
+                )
+
+                state_hash = hash(state_tuple)
+
+                new_state.state_history.append(state_hash)
+
+                if new_state.state_history.count(state_hash) >= 20:
+                    new_state.log_rule("Rule 12.1", "Infinite Loop detected. Terminating as Draw.")
+
+                    new_state.game_over = True
+
+                    new_state.winner = 2  # Draw
+
+                    new_state.loop_draw = True
+
+            except Exception:
+                # If hashing fails, just ignore for now to prevent crash
+
+                pass
+
+        return new_state
+
+    def get_observation(self) -> np.ndarray:
+        """
+        Calculates a flat feature vector representing the game state for the AI (Rule 9.1).
+
+        New Layout (Size 320):
+        [0-36]: Metadata (Phase, Player, Choice Context)
+        [36-168]: Hand (12 cards x 11 floats) -> [Exist, ID, Cost, Blade, HeartVec(7)]
+        [168-204]: Self Stage (3 slots x 12 floats) -> [Exist, ID, Tapped, Blade, HeartVec(7), Energy]
+        [204-240]: Opponent Stage (3 slots x 12 floats) -> [Exist, ID, Tapped, Blade, HeartVec(7), Energy]
+        [240-270]: Live Zone (3 cards x 10 floats) -> [Exist, ID, Score, ReqHeartVec(7)]
+        [270-272]: Scores (Self, Opp)
+        [272]: Source ID of pending choice
+        [273-320]: Padding
+        """
+
+        # Expanded observation size
+        features = np.zeros(320, dtype=np.float32)
+
+        # JIT Arrays Check
+        if GameState._jit_member_costs is None:
+            GameState._init_jit_arrays()
+
+        costs_db = GameState._jit_member_costs
+        hearts_vec_db = GameState._jit_member_hearts_vec
+        blades_db = GameState._jit_member_blades
+        live_score_db = GameState._jit_live_score
+        live_req_vec_db = GameState._jit_live_hearts_vec
+
+        # Max ID for normalization (add safety for 0 div)
+        max_id_val = float(costs_db.shape[0]) if costs_db is not None else 2000.0
+
+        # --- 1. METADATA [0:36] ---
+
+        # Phase (one-hot) [0:16] - using 11 slots
+        phase_val = int(self.phase) + 2
+        if 0 <= phase_val < 11:
+            features[phase_val] = 1.0
+
+        # Current Player [16:18]
+        features[16 + (1 if self.current_player == 1 else 0)] = 1.0
+
+        # Pending Choice [18:36]
+        if self.pending_choices:
+            features[18] = 1.0
+            choice_type, params = self.pending_choices[0]
+
+            # Populate Source ID if available [272]
+            source_id = params.get("card_id", -1)
+            if source_id >= 0:
+                features[272] = source_id / max_id_val
+
+            types = [
+                "TARGET_MEMBER",
+                "TARGET_HAND",
+                "SELECT_MODE",
+                "COLOR_SELECT",
+                "TARGET_OPPONENT_MEMBER",
+                "TARGET_MEMBER_SLOT",
+                "SELECT_SWAP_SOURCE",
+                "SELECT_FROM_LIST",
+                "SELECT_FROM_DISCARD",
+                "DISCARD_SELECT",
+                "MODAL",
+                "CHOOSE_FORMATION",
+                "SELECT_ORDER",
+                "SELECT_FORMATION_SLOT",
+                "SELECT_SUCCESS_LIVE",
+            ]
+            try:
+                t_idx = types.index(choice_type)
+                features[19 + t_idx] = 1.0
+            except ValueError:
+                pass
+
+            if params.get("is_optional"):
+                features[35] = 1.0
+
+        # --- 2. HAND [36:168] (12 cards * 11 features) ---
+        p = self.players[self.current_player]
+        hand_len = len(p.hand)
+        n_hand = min(hand_len, 12)
+
+        if n_hand > 0:
+            hand_ids = np.array(p.hand[:n_hand], dtype=int)
+            base_idx = np.arange(n_hand) * 11 + 36
+
+            # Existence
+            features[base_idx] = 1.0
+
+            # ID
+            features[base_idx + 1] = hand_ids / max_id_val
+
+            # Cost
+            c = costs_db[hand_ids]
+            features[base_idx + 2] = np.clip(c, 0, 10) / 10.0
+
+            # Blade
+            b = blades_db[hand_ids]
+            features[base_idx + 3] = np.clip(b, 0, 10) / 10.0
+
+            # Heart Vectors (7 dim)
+            # Flatten 12x7 -> 84? No, interleaved.
+            # We need to assign (N, 7) into sliced positions.
+            # This is tricky with simple slicing if stride is not 1.
+            # Loop for safety or advanced indexing.
+            # shape of h_vecs: (n_hand, 7)
+            h_vecs = hearts_vec_db[hand_ids]
+
+            for i in range(n_hand):
+                start = 36 + i * 11 + 4
+                features[start : start + 7] = np.clip(h_vecs[i], 0, 5) / 5.0
+
+        # --- 3. SELF STAGE [168:204] (3 slots * 12 features) ---
+        for i in range(3):
+            cid = p.stage[i]
+            base = 168 + i * 12
+            if cid >= 0:
+                features[base] = 1.0
+                features[base + 1] = cid / max_id_val
+                features[base + 2] = 1.0 if p.tapped_members[i] else 0.0
+
+                # Effective Stats (retains python logic for modifiers)
+                eff_blade = p.get_effective_blades(i, self.member_db)
+                eff_hearts = p.get_effective_hearts(i, self.member_db)  # vector
+
+                features[base + 3] = min(eff_blade / 10.0, 1.0)
+
+                # Hearts (7)
+                # eff_hearts is usually (6,) or (7,) or list
+                if isinstance(eff_hearts, (list, np.ndarray)):
+                    h_len = min(len(eff_hearts), 7)
+                    features[base + 4 : base + 4 + h_len] = np.array(eff_hearts[:h_len]) / 5.0
+
+                # Energy Count
+                features[base + 11] = min(len(p.stage_energy[i]) / 5.0, 1.0)
+
+        # --- 4. OPPONENT STAGE [204:240] (3 slots * 12 features) ---
+        opp = self.players[1 - self.current_player]
+        for i in range(3):
+            cid = opp.stage[i]
+            base = 204 + i * 12
+            if cid >= 0:
+                features[base] = 1.0
+                features[base + 1] = cid / max_id_val
+                features[base + 2] = 1.0 if opp.tapped_members[i] else 0.0
+
+                # Note: get_effective_blades requires accessing the opponent object relative to the DB
+                # but GameState usually uses p methods.
+                # p.get_effective_blades uses self.stage.
+                # So we call opp.get_effective_blades.
+                eff_blade = opp.get_effective_blades(i, self.member_db)
+                eff_hearts = opp.get_effective_hearts(i, self.member_db)
+
+                features[base + 3] = min(eff_blade / 10.0, 1.0)
+
+                if isinstance(eff_hearts, (list, np.ndarray)):
+                    h_len = min(len(eff_hearts), 7)
+                    features[base + 4 : base + 4 + h_len] = np.array(eff_hearts[:h_len]) / 5.0
+
+                features[base + 11] = min(len(opp.stage_energy[i]) / 5.0, 1.0)
+
+        # --- 5. LIVE ZONE [240:270] (3 cards * 10 features) ---
+        n_live = min(len(p.live_zone), 3)
+        if n_live > 0:
+            live_ids = np.array(p.live_zone[:n_live], dtype=int)
+
+            for i in range(n_live):
+                cid = live_ids[i]
+                base = 240 + i * 10
+                features[base] = 1.0
+                features[base + 1] = cid / max_id_val
+                features[base + 2] = np.clip(live_score_db[cid], 0, 5) / 5.0
+
+                # Req Heart Vec (7)
+                if live_req_vec_db is not None:
+                    features[base + 3 : base + 10] = np.clip(live_req_vec_db[cid], 0, 5) / 5.0
+
+        # --- 6. SCORES [270:272] ---
+        features[270] = min(len(p.success_lives) / 5.0, 1.0)
+        features[271] = min(len(self.players[1 - self.current_player].success_lives) / 5.0, 1.0)
+
+        return features
+
+    def to_dict(self):
+        """Serialize full game state."""
+
+        return {
+            "turn": self.turn_number,
+            "phase": self.phase,
+            "active_player": self.current_player,
+            "game_over": self.game_over,
+            "winner": self.winner,
+            "players": [p.to_dict(viewer_idx=0) for p in self.players],
+            "legal_actions": [],  # Can populate if needed
+            "pending_choice": None,
+            "performance_results": {},
+            "rule_log": list(self.rule_log),
+        }
+
+    def get_reward(self, player_idx: int) -> float:
+        # Get reward for player (1.0 for win, -1.0 for loss, 0.0 for draw)
+        # Illegal move (-2) is treated as a loss (-1.0) for safety in standard RL,
+        # though explicit training usually handles this via masking or separate loss.
+
+        if self.winner == -2:
+            return -100.0  # Illegal move/Technical loss
+
+        if self.winner == player_idx:
+            return 100.0
+        elif self.winner == 1 - player_idx:
+            return -100.0
+        elif self.winner == 2:  # Draw
+            return 0.0
+        elif self.winner == -1:  # Ongoing
+            # Ongoing heuristic: Pure score difference
+            # Time penalties are now handled by the Gymnasium environment (per turn)
+            my_score = len(self.players[player_idx].success_lives)
+            opp_score = len(self.players[1 - player_idx].success_lives)
+            return float(my_score - opp_score)
+
+    def take_action(self, action_id: int) -> None:
+        """In-place version of step() for testing and direct manipulation."""
+
+        if self.pending_choices:
+            self._handle_choice(action_id)
+
+        else:
+            self._execute_action(action_id)
+
+        # Process resulting effects
+
+        while self.pending_effects and not self.pending_choices:
+            self._resolve_pending_effect(0)
+
+
+def create_sample_cards() -> Tuple[Dict[int, MemberCard], Dict[int, LiveCard]]:
+    """Create sample cards for testing"""
+
+    members = {}
+
+    lives = {}
+
+    # Create 48 sample members with varying stats
+
+    for i in range(48):
+        cost = 2 + (i % 14)  # Costs 2-15
+
+        blades = 1 + (i % 6)  # Blades 1-6
+
+        hearts = np.zeros(7, dtype=np.int32)  # Changed from 6 to 7
+
+        hearts[i % 6] = 1 + (i // 6 % 3)  # 1-3 hearts of one color
+
+        if i >= 24:
+            hearts[(i + 1) % 6] = 1  # Second color for higher cost cards
+
+        blade_hearts = np.zeros(6, dtype=np.int32)
+
+        if i % 3 == 0:
+            blade_hearts[i % 6] = 1
+
+        members[i] = MemberCard(
+            card_id=i,
+            card_no=f"SAMPLE-M-{i}",
+            name=f"Member_{i}",
+            cost=cost,
+            hearts=hearts,
+            blade_hearts=blade_hearts,
+            blades=blades,
+        )
+
+    # Create 12 sample live cards
+
+    for i in range(12):
+        score = 1 + (i % 3)  # Score 1-3
+
+        required = np.zeros(7, dtype=np.int32)
+
+        required[i % 6] = 2 + (i // 6)  # 2-3 of one color required
+
+        required[6] = 1 + (i % 4)  # 1-4 "any" hearts required
+
+        lives[100 + i] = LiveCard(
+            card_id=100 + i, card_no=f"SAMPLE-L-{i}", name=f"Live_{i}", score=score, required_hearts=required
+        )
+
+    return members, lives
+
+
+def initialize_game(use_real_data: bool = True, deck_type: str = "normal") -> GameState:
+    """
+
+    Create initial game state with shuffled decks.
+
+    Args:
+
+        use_real_data: Whether to try loading real cards.json data
+
+        deck_type: "normal" (random from DB) or "vanilla" (specific simple cards)
+
+    """
+
+    # Try loading real data
+
+    if use_real_data and not GameState.member_db:
+        import traceback
+
+        # print("DEBUG: initialize_game attempting to load real data...")
+
+        try:
+            # Try current directory first (assuming run from root)
+
+            data_path = os.path.join(os.getcwd(), "data", "cards_compiled.json")
+
+            if not os.path.exists(data_path):
+                # Fallback to cards.json
+
+                data_path = os.path.join(os.getcwd(), "data", "cards.json")
+
+            if not os.path.exists(data_path):
+                # Absolute path fallback based on file location
+
+                base_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+                data_path = os.path.join(base_dir, "data", "cards_compiled.json")
+
+            # print(f"DEBUG: Selected data path: {data_path}")
+
+            if not os.path.exists(data_path):
+                # print(f"ERROR: Data path does not exist: {data_path}")
+                pass
+
+            else:
+                loader = CardDataLoader(data_path)
+
+                m, l, e = loader.load()
+
+                if m:
+                    GameState.member_db = m
+                    GameState.live_db = l
+                    print(f"SUCCESS: Loaded {len(m)} members and {len(l)} lives from {data_path}")
+
+                    # Optimization: Cache cards with CONSTANT META_RULE effects
+                    GameState._meta_rule_cards = set()
+                    for cid, card in m.items():
+                        for ab in card.abilities:
+                            if ab.trigger.name == "CONSTANT":  # Check string to avoid import if needed, or use enum
+                                for eff in ab.effects:
+                                    if eff.effect_type.name == "META_RULE":
+                                        GameState._meta_rule_cards.add(cid)
+                                        break
+                    for cid, card in l.items():
+                        for ab in card.abilities:
+                            if ab.trigger.name == "CONSTANT":
+                                for eff in ab.effects:
+                                    if eff.effect_type.name == "META_RULE":
+                                        GameState._meta_rule_cards.add(cid)
+                                        break
+
+                    GameState._init_jit_arrays()
+
+                else:
+                    # print("WARNING: Loader returned empty member database.")
+                    pass
+
+        except Exception as e:
+            print(f"CRITICAL: Failed to load real data: {e}")
+            import traceback
+            traceback.print_exc()
+            pass
+
+            traceback.print_exc()
+
+    if not GameState.member_db:
+        # print("WARNING: Falling back to SAMPLE cards. This may cause logic inconsistencies.")
+
+        # Fallback to sample
+
+        members, lives = create_sample_cards()
+
+        GameState.member_db = members
+
+        GameState.live_db = lives
+
+        GameState._init_jit_arrays()
+
+    state = GameState()
+
+    # Pre-calculate Vanilla Deck IDs if needed
+
+    vanilla_member_ids = []
+
+    vanilla_live_ids = []
+
+    if deck_type == "vanilla":
+        # Target Vanilla Members (4 copies each = 48)
+
+        # 5 Vanilla + 7 Simple
+
+        target_members = [
+            "PL!-sd1-010-SD",
+            "PL!-sd1-013-SD",
+            "PL!-sd1-014-SD",
+            "PL!-sd1-017-SD",
+            "PL!-sd1-018-SD",  # Vanilla
+            "PL!-sd1-002-SD",
+            "PL!-sd1-005-SD",
+            "PL!-sd1-011-SD",
+            "PL!-sd1-012-SD",
+            "PL!-sd1-016-SD",  # Simple
+            "PL!-sd1-015-SD",
+            "PL!-sd1-007-SD",
+        ]
+
+        # Target Vanilla Lives (3 copies each = 12)
+
+        target_lives = ["PL!-sd1-019-SD", "PL!-sd1-020-SD", "PL!-sd1-021-SD", "PL!-sd1-022-SD"]
+
+        # 1. Map Members
+
+        found_members = {}
+
+        for cid, card in GameState.member_db.items():
+            if card.card_no in target_members:
+                found_members[card.card_no] = cid
+
+        # 2. Map Lives
+
+        found_lives = {}
+
+        for cid, card in GameState.live_db.items():
+            if card.card_no in target_lives:
+                found_lives[card.card_no] = cid
+
+        # 3. Construct Lists
+
+        for tm in target_members:
+            if tm in found_members:
+                vanilla_member_ids.extend([found_members[tm]] * 4)
+
+            else:
+                # print(f"WARNING: Vanilla card {tm} not found in DB!")
+                pass
+
+        for tl in target_lives:
+            if tl in found_lives:
+                vanilla_live_ids.extend([found_lives[tl]] * 3)
+
+            else:
+                # print(f"WARNING: Vanilla live {tl} not found in DB!")
+                pass
+
+        # Fill if missing?
+
+        if len(vanilla_member_ids) < 48:
+            # print(f"WARNING: Vanilla deck incomplete ({len(vanilla_member_ids)}), filling with randoms.")
+            pass
+
+            remaining = 48 - len(vanilla_member_ids)
+
+            all_ids = list(GameState.member_db.keys())
+
+            if all_ids:
+                vanilla_member_ids.extend(np.random.choice(all_ids, remaining).tolist())
+
+        if len(vanilla_live_ids) < 12:
+            # print(f"WARNING: Vanilla live deck incomplete ({len(vanilla_live_ids)}), filling with randoms.")
+            pass
+
+            remaining = 12 - len(vanilla_live_ids)
+
+            all_ids = list(GameState.live_db.keys())
+
+            if all_ids:
+                vanilla_live_ids.extend(np.random.choice(all_ids, remaining).tolist())
+
+    # Prepare Verified/Random lists if needed
+    verified_member_ids = []
+    verified_live_ids = []
+
+    if deck_type == "random_verified":
+        try:
+            pool_path = os.path.join(os.getcwd(), "verified_card_pool.json")
+            if os.path.exists(pool_path):
+                with open(pool_path, "r", encoding="utf-8") as f:
+                    pool = json.load(f)
+
+                v_members = pool.get("verified_abilities", [])
+                v_vanilla = pool.get("vanilla_members", [])
+                total_v_members = v_members + v_vanilla
+
+                # Filter DB for these card_nos
+                for cid, card in GameState.member_db.items():
+                    if card.card_no in total_v_members:
+                        verified_member_ids.append(cid)
+
+                v_lives = pool.get("vanilla_lives", [])  # Or use vanilla_lives as a base for lives
+                for cid, card in GameState.live_db.items():
+                    if card.card_no in v_lives:
+                        verified_live_ids.append(cid)
+
+                if not verified_member_ids or not verified_live_ids:
+                    # print(f"WARNING: Verified pool empty after filtering! Check card_nos. falling back.")
+                    pass
+            else:
+                # print(f"WARNING: verified_card_pool.json not found at {pool_path}")
+                pass
+        except Exception:
+            # print(f"ERROR: Failed to load verified pool: {e}")
+            pass
+
+    for p_idx in range(2):
+        p = state.players[p_idx]
+
+        # Build decks
+        if deck_type == "vanilla":
+            member_ids = list(vanilla_member_ids)  # Copy
+            live_ids = list(vanilla_live_ids)  # Copy
+        elif deck_type == "random_verified" and verified_member_ids and verified_live_ids:
+            # 48 members, 12 lives
+            member_ids = list(np.random.choice(verified_member_ids, 48, replace=True))
+            live_ids = list(np.random.choice(verified_live_ids, 12, replace=True))
+        else:
+            # Random Normal Deck
+            # Random Normal Deck
+
+            member_ids = list(GameState.member_db.keys())
+
+            live_ids = list(GameState.live_db.keys())
+
+            # Filter if too many? For now just take random subset if huge
+
+            if len(member_ids) > 48:
+                member_ids = list(np.random.choice(member_ids, 48, replace=False))
+
+            if len(live_ids) > 12:
+                live_ids = list(np.random.choice(live_ids, 12, replace=False))
+
+        energy_ids = list(range(200, 212))
+
+        np.random.shuffle(member_ids)
+
+        np.random.shuffle(live_ids)
+
+        np.random.shuffle(energy_ids)
+
+        p.main_deck = member_ids + live_ids
+
+        np.random.shuffle(p.main_deck)
+
+        p.energy_deck = energy_ids
+
+        # Initial draw: 6 cards (Rule 6.2.1.5)
+        # Note: log_rule isn't available on GameState yet as it's a static function creating state
+        # but we can print or add a log entry to the state's internal log if it has one.
+        # Actually, let's just make sure the draw happens.
+        for _ in range(6):
+            if p.main_deck:
+                p.hand.append(p.main_deck.pop(0))
+
+    # Log initial setup rules (Rule 6.2.1.5 and 6.2.1.7)
+    state.rule_log.append({"rule": "Rule 6.2.1.5", "description": "Both players draw 6 cards as starting hand."})
+    state.rule_log.append(
+        {"rule": "Rule 6.2.1.7", "description": "Both players place 3 cards from Energy Deck to Energy Zone."}
+    )
+
+    # Set initial phase to Mulligan
+
+    state.phase = Phase.MULLIGAN_P1
+
+    # Randomly determine first player
+
+    state.first_player = np.random.randint(2)
+
+    state.current_player = state.first_player
+
+    # Rule 6.2.1.7: Both players place top 3 cards of Energy Deck into Energy Zone
+
+    for p in state.players:
+        p.energy_zone = []
+
+        for _ in range(3):
+            if p.energy_deck:
+                p.energy_zone.append(p.energy_deck.pop(0))
+
+    return state
+
+
+if __name__ == "__main__":
+    # Test game creation and basic flow
+
+    game = initialize_game()
+
+    print(f"Game initialized. First player: {game.first_player}")
+
+    print(f"P0 hand: {len(game.players[0].hand)} cards")
+
+    print(f"P1 hand: {len(game.players[1].hand)} cards")
+
+    print(f"Phase: {game.phase.name}")
+
+    # Run a few random actions
+
+    for step in range(20):
+        if game.is_terminal():
+            print(f"Game over! Winner: {game.get_winner()}")
+
+            break
+
+        legal = game.get_legal_actions()
+
+        legal_indices = np.where(legal)[0]
+
+        if len(legal_indices) == 0:
+            print("No legal actions!")
+
+            break
+
+        action = np.random.choice(legal_indices)
+
+        game = game.step(action)
+
+        print(
+            f"Step {step}: Action {action}, Phase {game.phase}, "
+            f"Player {game.current_player}, "
+            f"P0 lives: {len(game.players[0].success_lives)}, "
+            f"P1 lives: {len(game.players[1].success_lives)}"
+        )
+
+# --- COMPREHENSIVE RULEBOOK INDEX (v1.04) ---
+
+# This index ensures 100% searchability of all official rule identifiers.
+
+#
+
+# Rule 1:
+
+# Rule 1.1:
+
+# Rule 1.1.1:
+
+# Rule 1.2:
+
+# Rule 1.2.1:
+
+# Rule 1.2.1.1: ??E??????v???C???[????????C?u?J?[?h?u
+
+# Rule 1.2.1.2: ??????v???C???[????????3 ????????
+
+# Rule 1.2.2:
+
+# Rule 1.2.3:
+
+# Rule 1.2.3.1: ???E???s???s???A???????J?[?h?E?e????E
+
+# Rule 1.2.4:
+
+# Rule 1.3:
+
+# Rule 1.3.1:
+
+# Rule 1.3.2:
+
+# Rule 1.3.2.1: ????????????????E?????????E??
+
+# Rule 1.3.2.2: ????s???????s??????P?????E??????E
+
+# Rule 1.3.2.3: ????s????v???????????E?????????A??
+
+# Rule 1.3.2.4: ?v???C???[??E???[?h????????l?E????A????
+
+# Rule 1.3.3:
+
+# Rule 1.3.4:
+
+# Rule 1.3.4.1: ?????????E????v???C???[??K?p????AE
+
+# Rule 1.3.4.2: ???E?J????J?[?h?????I???????
+
+# Rule 1.3.5:
+
+# Rule 1.3.5.1: ?J?[?h???[??????e?`???f?E??????
+
+# Rule 2:
+
+# Rule 2.1:
+
+# Rule 2.1.1:
+
+# Rule 2.1.2:
+
+# Rule 2.1.3:
+
+# Rule 2.2:
+
+# Rule 2.2.1:
+
+# Rule 2.2.2:
+
+# Rule 2.2.2.1: ?J?[?h?^?C?v?????C?u?????J?[?h?E?A?Q?[??
+
+# Rule 2.2.2.1.1: ?X?R?A?E?E.10?E????E???n?[?g?IE.11?E???????
+
+# Rule 2.2.2.2: ?J?[?h?^?C?v???????o?E?????J?[?h?E?A???C
+
+# Rule 2.2.2.2.1: ?R?X?g?IE.6?E???n?E?g?IE.9?E???????J?[?`E
+
+# Rule 2.2.2.3: ?J?[?h?^?C?v???G?l???M?[?????J?[?h?E?A??
+
+# Rule 2.2.2.3.1: ?J?[?h??????e?G?l???M?[?J?[?h?f??\?E
+
+# Rule 2.3:
+
+# Rule 2.3.1:
+
+# Rule 2.3.2:
+
+# Rule 2.3.2.1: ?J?[?h?????E?E?????????o?E?J?[?h?E?AE??E??
+
+# Rule 2.3.2.2: ?`E???X?g???A?u?v?i?????????E??????????
+
+# Rule 2.4:
+
+# Rule 2.4.1:
+
+# Rule 2.4.2:
+
+# Rule 2.4.2.1: ?J?[?h?????E?E?????????o?E?J?[?h?E?AE??E??
+
+# Rule 2.4.2.2: ?????o?E?????O???[?v????????E?A??
+
+# Rule 2.4.3:
+
+# Rule 2.4.3.1: ?`E???X?g???A?w?x?i??d?????????E??????
+
+# Rule 2.4.4:
+
+# Rule 2.5:
+
+# Rule 2.5.1:
+
+# Rule 2.5.2:
+
+# Rule 2.5.3:
+
+# Rule 2.6:
+
+# Rule 2.6.1:
+
+# Rule 2.7:
+
+# Rule 2.7.1:
+
+# Rule 2.7.2:
+
+# Rule 2.8:
+
+# Rule 2.8.1:
+
+# Rule 2.8.2:
+
+# Rule 2.9:
+
+# Rule 2.9.1:
+
+# Rule 2.9.2:
+
+# Rule 2.9.3:
+
+# Rule 2.10:
+
+# Rule 2.10.1:
+
+# Rule 2.11:
+
+# Rule 2.11.1:
+
+# Rule 2.11.2:
+
+# Rule 2.11.2.1: ??E???[?g??????A?c??
+
+# Rule 2.11.2.2: ?n?E?g???????E????????A????S???
+
+# Rule 2.11.3:
+
+# Rule 2.12:
+
+# Rule 2.12.1:
+
+# Rule 2.12.2:
+
+# Rule 2.12.3:
+
+# Rule 2.12.4:
+
+# Rule 2.13:
+
+# Rule 2.13.1:
+
+# Rule 2.13.2:
+
+# Rule 2.14:
+
+# Rule 2.14.1:
+
+# Rule 2.14.2:
+
+# Rule 2.14.3:
+
+# Rule 3:
+
+# Rule 3.1:
+
+# Rule 3.1.1:
+
+# Rule 3.1.2:
+
+# Rule 3.1.2.1: ???E???E?}?X?^?[???A????\???L????E
+
+# Rule 3.1.2.2: ?N???E???E?}?X?^?[???A??????v???C????
+
+# Rule 3.1.2.3: ?????E???E?}?X?^?[???A????\???L????E
+
+# Rule 3.1.2.4: ?????E?}?X?^?[???A??????????????E
+
+# Rule 3.1.2.4.1: ?????????????v???C???[???w?E
+
+# Rule 4:
+
+# Rule 4.1:
+
+# Rule 4.1.1:
+
+# Rule 4.1.2:
+
+# Rule 4.1.2.1: ???J????J?[?h???u???????A????
+
+# Rule 4.1.2.2: ?????E?J?????????J??????????
+
+# Rule 4.1.2.3: ???E?J??????????A???????J?[?`E
+
+# Rule 4.1.3:
+
+# Rule 4.1.3.1: ??E???????E???????J?[?h?E??E????AE
+
+# Rule 4.1.4:
+
+# Rule 4.1.4.1: ????J?[?h????????E??A???????????E
+
+# Rule 4.1.5:
+
+# Rule 4.1.5.1: ???J???Y????E?J?????E????J?[?h??
+
+# Rule 4.1.6:
+
+# Rule 4.1.7:
+
+# Rule 4.2:
+
+# Rule 4.2.1:
+
+# Rule 4.2.2:
+
+# Rule 4.2.3:
+
+# Rule 4.3:
+
+# Rule 4.3.1:
+
+# Rule 4.3.2:
+
+# Rule 4.3.2.1: ?A?N?`E???u????E?J?[?h?E?A????J?[?h?E?}?X
+
+# Rule 4.3.2.2: ?E?F?C?g????E?J?[?h?E?A????J?[?h?E?}?X
+
+# Rule 4.3.2.3: ?z?u??????E??????????J?[?h???u??E
+
+# Rule 4.3.3:
+
+# Rule 4.3.3.1: ?\????????E?J?[?h?E?A?J?[?h?E?E????????E
+
+# Rule 4.3.3.2: ??????????E?J?[?h?E?A?J?[?h?E?E????????E
+
+# Rule 4.4:
+
+# Rule 4.4.1:
+
+# Rule 4.4.2:
+
+# Rule 4.5:
+
+# Rule 4.5.1:
+
+# Rule 4.5.1.1: ?`E???X?g????P??e?G???A?f?????????E????
+
+# Rule 4.5.2:
+
+# Rule 4.5.2.1: ??E?????o?E?G???A??A??????e???T?C?h?G??
+
+# Rule 4.5.2.2: ????v???C???[???????A???T?C?h?G???A??
+
+# Rule 4.5.2.3: ????v???C???[???????A???T?C?h?G???A??
+
+# Rule 4.5.3:
+
+# Rule 4.5.4:
+
+# Rule 4.5.5:
+
+# Rule 4.5.5.1: ?????o?E?G???A??????o?E?J?[?h?E????d?E
+
+# Rule 4.5.5.2: ?????o?E?G???A??????o?E?J?[?h?E????d?E
+
+# Rule 4.5.5.3: ?????o?E?G???A??????o?E?????E?????o?E?G
+
+# Rule 4.5.5.4: ?????o?E?G???A??????o?E???????o?E?G???A
+
+# Rule 4.5.6:
+
+# Rule 4.6:
+
+# Rule 4.6.1:
+
+# Rule 4.6.2:
+
+# Rule 4.7:
+
+# Rule 4.7.1:
+
+# Rule 4.7.2:
+
+# Rule 4.7.3:
+
+# Rule 4.7.4:
+
+# Rule 4.8:
+
+# Rule 4.8.1:
+
+# Rule 4.8.2:
+
+# Rule 4.8.3:
+
+# Rule 4.8.4:
+
+# Rule 4.9:
+
+# Rule 4.9.1:
+
+# Rule 4.9.2:
+
+# Rule 4.9.3:
+
+# Rule 4.9.4:
+
+# Rule 4.10:
+
+# Rule 4.10.1:
+
+# Rule 4.10.2:
+
+# Rule 4.11:
+
+# Rule 4.11.1:
+
+# Rule 4.11.2:
+
+# Rule 4.11.3:
+
+# Rule 4.12:
+
+# Rule 4.12.1:
+
+# Rule 4.12.2:
+
+# Rule 4.13:
+
+# Rule 4.13.1:
+
+# Rule 4.13.2:
+
+# Rule 4.14:
+
+# Rule 4.14.1:
+
+# Rule 4.14.2:
+
+# Rule 5:
+
+# Rule 5.1:
+
+# Rule 5.1.1:
+
+# Rule 5.2:
+
+# Rule 5.2.1:
+
+# Rule 5.3:
+
+# Rule 5.3.1:
+
+# Rule 5.4:
+
+# Rule 5.4.1:
+
+# Rule 5.5:
+
+# Rule 5.5.1:
+
+# Rule 5.5.1.1: ?J?[?h?Q?????P?????????E????????
+
+# Rule 5.5.1.2: ?J?[?h?Q??J?[?h??0 ??????E1 ???E???E
+
+# Rule 5.6:
+
+# Rule 5.6.1:
+
+# Rule 5.6.2:
+
+# Rule 5.6.3:
+
+# Rule 5.6.3.1: ?E????l?E???0 ??????????E?A?????E????E
+
+# Rule 5.6.3.2: ??E???E???C???[????E??E?????I?E???????E
+
+# Rule 5.6.3.3: ??E???E???C???[??J?[?h??1 ??????????AE
+
+# Rule 5.6.3.4: ???E??E??????5.6.3.3 ?????s????????i??
+
+# Rule 5.7:
+
+# Rule 5.7.1:
+
+# Rule 5.7.2:
+
+# Rule 5.7.2.1: ?E????l?E???0 ??????????E?A?????E????E
+
+# Rule 5.7.2.2: ?????????1 ???w??????AE
+
+# Rule 5.7.2.3: ??E???E???C???[????E??E?????I?E???????E
+
+# Rule 5.7.2.4: ??E???E???C???[??A???C???`E???L?u??????
+
+# Rule 5.7.2.5: ???E??E??????5.7.2.4 ?????s????????i??
+
+# Rule 5.8:
+
+# Rule 5.8.1:
+
+# Rule 5.8.2:
+
+# Rule 5.9.1:
+
+# Rule 5.9.1.1: ?E
+
+# Rule 5.10:
+
+# Rule 5.10.1:
+
+# Rule 6:
+
+# Rule 6.1:
+
+# Rule 6.1.1:
+
+# Rule 6.1.1.1: ???C???`E???L??A?????o?E?J?[?`E8 ??????E????
+
+# Rule 6.1.1.2: ???C???`E???L???A?J?[?h?i???o?E???????
+
+# Rule 6.1.1.3: ?G?l???M?[?`E???L??A?G?l???M?[?J?[?`E2
+
+# Rule 6.1.2:
+
+# Rule 6.2:
+
+# Rule 6.2.1:
+
+# Rule 6.2.1.1: ???E?Q?[????g?p?????g??`E???L???
+
+# Rule 6.2.1.2: ??E?E???C???[????g????C???`E???L???E?g??
+
+# Rule 6.2.1.3: ??E?E???C???[????g??G?l???M?[?`E???L??E
+
+# Rule 6.2.1.4: ??E?E???C???[????????????E?v???C???[
+
+# Rule 6.2.1.5: ??E?E???C???[????g????C???`E???L?u?????
+
+# Rule 6.2.1.6: ??U?v???C???[?????E???A?e?v???C???[???
+
+# Rule 6.2.1.7: ??E?E???C???[????g??G?l???M?[?`E???L?u
+
+# Rule 7:
+
+# Rule 7.1:
+
+# Rule 7.1.1:
+
+# Rule 7.1.2:
+
+# Rule 7.2:
+
+# Rule 7.2.1:
+
+# Rule 7.2.1.1: ???v???C???[???w????t?F?C?Y????A??
+
+# Rule 7.2.1.2: ???v???C???[???w?????E???F?C?Y????AE
+
+# Rule 7.2.2:
+
+# Rule 7.3:
+
+# Rule 7.3.1:
+
+# Rule 7.3.2:
+
+# Rule 7.3.2.1: ???t?F?C?Y???A?E?U?v???C???[?????`E
+
+# Rule 7.3.3:
+
+# Rule 7.4:
+
+# Rule 7.4.1:
+
+# Rule 7.4.2:
+
+# Rule 7.4.3:
+
+# Rule 7.5:
+
+# Rule 7.5.1:
+
+# Rule 7.5.2:
+
+# Rule 7.5.3:
+
+# Rule 7.6:
+
+# Rule 7.6.1:
+
+# Rule 7.6.2:
+
+# Rule 7.6.3:
+
+# Rule 7.7:
+
+# Rule 7.7.1:
+
+# Rule 7.7.2:
+
+# Rule 7.7.2.1: ???E?E?J?[?h??????N???E???1 ??I???AE
+
+# Rule 7.7.2.2: ???E?E??D??????o?E?J?[?h??1 ???I???A??
+
+# Rule 7.7.3:
+
+# Rule 7.8:
+
+# Rule 7.8.1:
+
+# Rule 8:
+
+# Rule 8.1:
+
+# Rule 8.1.1:
+
+# Rule 8.1.2:
+
+# Rule 8.2:
+
+# Rule 8.2.1:
+
+# Rule 8.2.2:
+
+# Rule 8.2.3:
+
+# Rule 8.2.4:
+
+# Rule 8.2.5:
+
+# Rule 8.3:
+
+# Rule 8.3.1:
+
+# Rule 8.3.2:
+
+# Rule 8.3.2.1: ?p?t?H?[?}???X?t?F?C?Y???A?E?U?v???C
+
+# Rule 8.3.3:
+
+# Rule 8.3.4:
+
+# Rule 8.3.4.1: ???v???C???[???e???C?u??????E???????E
+
+# Rule 8.3.5:
+
+# Rule 8.3.6:
+
+# Rule 8.3.7:
+
+# Rule 8.3.8:
+
+# Rule 8.3.9:
+
+# Rule 8.3.10:
+
+# Rule 8.3.11:
+
+# Rule 8.3.12:
+
+# Rule 8.3.13:
+
+# Rule 8.3.14:
+
+# Rule 8.3.15:
+
+# Rule 8.3.15.1: ???????C?u???L?n?[?g????A??????C?`E
+
+# Rule 8.3.15.1.1: ???E??A?e
+
+# Rule 8.3.15.1.2: ????????E???C?u?J?[?h?E?E??E
+
+# Rule 8.3.16:
+
+# Rule 8.3.17:
+
+# Rule 8.4:
+
+# Rule 8.4.1:
+
+# Rule 8.4.2:
+
+# Rule 8.4.2.1: ???E??A?e?v???C???[????g??G?[????
+
+# Rule 8.4.3:
+
+# Rule 8.4.3.1: ??????v???C???[???????E???C?u?J?[?h?u
+
+# Rule 8.4.3.2: ?????v???C???[????C?u?J?[?h?u?????
+
+# Rule 8.4.3.3: ??????v???C???[????C?u?J?[?h?u?????
+
+# Rule 8.4.4:
+
+# Rule 8.4.5:
+
+# Rule 8.4.6:
+
+# Rule 8.4.6.1: ??????v???C???[???????E???C?u?J?[?h?u
+
+# Rule 8.4.6.2: ??E??????v???C???[????C?u?J?[?h?u????
+
+# Rule 8.4.7:
+
+# Rule 8.4.7.1: ??????v???C???[???????????E?????E
+
+# Rule 8.4.8:
+
+# Rule 8.4.9:
+
+# Rule 8.4.10:
+
+# Rule 8.4.11:
+
+# Rule 8.4.12:
+
+# Rule 8.4.13: 8.4.7 ???????A?????v???C???[?????E?????C
+
+# Rule 8.4.14:
+
+# Rule 9:
+
+# Rule 9.1:
+
+# Rule 9.1.1:
+
+# Rule 9.1.1.1: ?N???E????A?E???C?^?C?~???O???^?????
+
+# Rule 9.1.1.1.1: ?N???E???E?A?J?[?h?????E
+
+# Rule 9.1.1.2: ?????E????A????\?????????????E
+
+# Rule 9.1.1.2.1: ?????E???E?A?J?[?h?????E
+
+# Rule 9.1.1.3: ???E????A????\????L???????A??
+
+# Rule 9.1.1.3.1: ???E???E?A?J?[?h?????E
+
+# Rule 9.2:
+
+# Rule 9.2.1:
+
+# Rule 9.2.1.1: ?e?P??????f???A??????????E??E???????E
+
+# Rule 9.2.1.2: ?e?p??????f???A????E???????i?????
+
+# Rule 9.2.1.3: ?e?u??????f???A?Q?[???????????????
+
+# Rule 9.2.1.3.1: ?\???e?i?s??A?E??????A???????E??E
+
+# Rule 9.2.1.3.2: ?\???e?i?s??A?E??????A??????[?I
+
+# Rule 9.3:
+
+# Rule 9.3.1:
+
+# Rule 9.3.2:
+
+# Rule 9.3.3:
+
+# Rule 9.3.4:
+
+# Rule 9.3.4.1: ?????E????E?????E????v???C????E
+
+# Rule 9.3.4.1.1: ????J?[?h?E?v???C?????E?J?[?h???
+
+# Rule 9.3.4.2: ?J?[?h?^?C?v???????o?E?????J?[?h?E?\?E
+
+# Rule 9.3.4.3: ?J?[?h?^?C?v?????C?u?????J?[?h?E?\???E?AE
+
+# Rule 9.4:
+
+# Rule 9.4.1:
+
+# Rule 9.4.2:
+
+# Rule 9.4.2.1: ?R?X?g???E????s??????????A?e?L?X?g?E
+
+# Rule 9.4.2.2: ?R?X?g?E??E????????E?S?????x?????????E
+
+# Rule 9.4.3:
+
+# Rule 9.5:
+
+# Rule 9.5.1:
+
+# Rule 9.5.1.1: ?`?F?`E???^?C?~???O????????A??????[????
+
+# Rule 9.5.2:
+
+# Rule 9.5.3:
+
+# Rule 9.5.3.1: ??????E???s????????[?????E??????
+
+# Rule 9.5.3.2: ?v???C???[???E?X?^?[?????E???????
+
+# Rule 9.5.3.3: ??A?N?`E???u?E???C???[???E?X?^?[?????E
+
+# Rule 9.5.3.4: ?`?F?`E???^?C?~???O???I?E??????AE
+
+# Rule 9.5.4:
+
+# Rule 9.5.4.1: ?`?F?`E???^?C?~???O????????????B?`?F?`E???^?C
+
+# Rule 9.5.4.2: ?v???C?^?C?~???O?????????E?v???C???[??
+
+# Rule 9.5.4.3: ?v???C?^?C?~???O??^??????E???C???[??E
+
+# Rule 9.6:
+
+# Rule 9.6.1:
+
+# Rule 9.6.2:
+
+# Rule 9.6.2.1: ?v???C????\????D??J?[?h????E??????
+
+# Rule 9.6.2.1.1: ?v???C???????J?[?h???????A????E
+
+# Rule 9.6.2.1.2: ????E???s??????AE
+
+# Rule 9.6.2.1.2.1: ???E??A????^?[????X?`E?E?W??
+
+# Rule 9.6.2.1.3: ?v???C???????E????????A????
+
+# Rule 9.6.2.2: ?J?[?h??\???????E?I?????E???????
+
+# Rule 9.6.2.3: ?v???C???????R?X?g????????A????R
+
+# Rule 9.6.2.3.1: ?v???C???????????o?E??J?[?h?????
+
+# Rule 9.6.2.3.2: ?????o?E???E???C?????A?x???????E
+
+# Rule 9.6.2.3.2.1: ???????R?X?g???????E?E??
+
+# Rule 9.6.2.4: ?J?[?h??\???E???????s??????AE
+
+# Rule 9.6.2.4.1: ?v???C????????????o?E???????A??
+
+# Rule 9.6.2.4.2: ?v???C????????N???E??????E???
+
+# Rule 9.6.2.4.2.1: ?\???E??????????????o?E?J?[
+
+# Rule 9.6.3:
+
+# Rule 9.6.3.1: ?I??????w??????E?????A??????\
+
+# Rule 9.6.3.1.1: ?I??????f?`???I???f??f?`???I
+
+# Rule 9.6.3.1.2: ?I??????w??????E??????A?w?E
+
+# Rule 9.6.3.1.3: ?I??????w??????E??????A???E
+
+# Rule 9.6.3.1.4: ?I????E???E?J??????E????E?????J??E
+
+# Rule 9.7:
+
+# Rule 9.7.1:
+
+# Rule 9.7.2:
+
+# Rule 9.7.2.1: ?????E???E?U?????????E?????????
+
+# Rule 9.7.3:
+
+# Rule 9.7.3.1: ??E??????E?????E???E?v???C???????A?E
+
+# Rule 9.7.3.1.1: ?????E????C???R?X?g???x?????????
+
+# Rule 9.7.3.2: ?I???E??????E?????E????v???C?????
+
+# Rule 9.7.3.2.1: ?????E????C???R?X?g???x?????????
+
+# Rule 9.7.4:
+
+# Rule 9.7.4.1: ??????U?????????E????A????\?E
+
+# Rule 9.7.4.1.1: ?J?[?h?????J???Y????E?J???A??
+
+# Rule 9.7.4.1.2: ?J?[?h???X?`E?E?W????F???O?E???
+
+# Rule 9.7.4.1.3: ??L?????????O?E?A?E?J???Y??
+
+# Rule 9.7.4.2: ????J?[?h????????U???\????????A??
+
+# Rule 9.7.5:
+
+# Rule 9.7.5.1: ?????U????A?????????????????E????E??
+
+# Rule 9.7.6:
+
+# Rule 9.7.6.1: ???U????A????????????????????1
+
+# Rule 9.7.7:
+
+# Rule 9.8:
+
+# Rule 9.8.1:
+
+# Rule 9.9:
+
+# Rule 9.9.1:
+
+# Rule 9.9.1.1: ?J?[?h?E?g??\?L??????E???E?????A????
+
+# Rule 9.9.1.2: ????A?E???^????E??????E?L???????/
+
+# Rule 9.9.1.3: ????A?p???????E??E???E??????l???X??E
+
+# Rule 9.9.1.4: ????A?p???????E??E???E??????l??????E
+
+# Rule 9.9.1.4.1: ?n?E?g??u???[?h?E?????????E????
+
+# Rule 9.9.1.5: ????A?p???????E??E???E??????l???X??E
+
+# Rule 9.9.1.5.1: ?n?E?g??u???[?h?E??????????Z????E
+
+# Rule 9.9.1.6: ????E9.9.1.2X-9.9.1.4 ??K?p??E?E?O??I??
+
+# Rule 9.9.1.7: ????E9.9.1.2X-9.9.1.6 ??K?p??E?E?O??I??
+
+# Rule 9.9.1.7.1: ?p???????E???????????E??????
+
+# Rule 9.9.1.7.2: ?????O?E?\???E???E?A?????v??
+
+# Rule 9.9.2:
+
+# Rule 9.9.3:
+
+# Rule 9.9.3.1: ?????E?E????????J?[?h????????????E
+
+# Rule 9.10:
+
+# Rule 9.10.1:
+
+# Rule 9.10.1.1: ???????A?u????????E?E???????????
+
+# Rule 9.10.2:
+
+# Rule 9.10.2.1: ?e????????????J?[?h??\???????
+
+# Rule 9.10.2.2: ?e????????????Q?[??????s?????E
+
+# Rule 9.10.2.3: ??????????????A?e?u???????E??
+
+# Rule 9.10.3:
+
+# Rule 9.11:
+
+# Rule 9.11.1:
+
+# Rule 9.12:
+
+# Rule 9.12.1:
+
+# Rule 9.12.2:
+
+# Rule 10:
+
+# Rule 10.1:
+
+# Rule 10.1.1:
+
+# Rule 10.1.2:
+
+# Rule 10.1.3:
+
+# Rule 10.2:
+
+# Rule 10.2.1:
+
+# Rule 10.2.2:
+
+# Rule 10.2.2.1: ??E??????v???C???[????C???`E???L?u??E
+
+# Rule 10.2.2.2: ???C???`E???L?u???????H?????E??????
+
+# Rule 10.2.3:
+
+# Rule 10.2.4:
+
+# Rule 10.3:
+
+# Rule 10.3.1:
+
+# Rule 10.4:
+
+# Rule 10.4.1:
+
+# Rule 10.5:
+
+# Rule 10.5.1:
+
+# Rule 10.5.2:
+
+# Rule 10.5.3:
+
+# Rule 10.5.4:
+
+# Rule 10.6:
+
+# Rule 10.6.1:
+
+# Rule 11:
+
+# Rule 11.1:
+
+# Rule 11.1.1:
+
+# Rule 11.1.2:
+
+# Rule 11.1.3:
+
+# Rule 11.2:
+
+# Rule 11.2.2:
+
+# Rule 11.2.3:
+
+# Rule 11.3:
+
+# Rule 11.3.1: [Icon] ??A?????o?E???????o?E?G???A??u????E
+
+# Rule 11.3.2:
+
+# Rule 11.4:
+
+# Rule 11.4.1: [Icon] ??A???C?u???J?n??????????E
+
+# Rule 11.4.2:
+
+# Rule 11.4.2.1: ?p?t?H?[?}???X?t?F?C?Y???A???v???C???[
+
+# Rule 11.5:
+
+# Rule 11.5.1: [Icon] ??A???C?u???????????????U??
+
+# Rule 11.5.2:
+
+# Rule 11.6:
+
+# Rule 11.6.1: [Icon] ??A?E???E?v???C???????A?E???E?E
+
+# Rule 11.6.2:
+
+# Rule 11.6.3:
+
+# Rule 11.6.4:
+
+# Rule 11.7:
+
+# Rule 11.7.1: [Icon] ??A?E???E?v???C???????A?E???E?E
+
+# Rule 11.7.2:
+
+# Rule 11.7.3:
+
+# Rule 11.7.4:
+
+# Rule 11.8:
+
+# Rule 11.8.1: [Icon] ??A?E???E?v???C???????A?E???E?E
+
+# Rule 11.8.2:
+
+# Rule 11.8.3:
+
+# Rule 11.8.4:
+
+# Rule 11.9:
+
+# Rule 11.9.1:
+
+# Rule 11.9.2:
+
+# Rule 11.10:
+
+# Rule 11.10.1:
+
+# Rule 11.10.2:
+
+# Rule 12:
+
+# Rule 12.1:
+
+# Rule 12.1.1:
+
+# Rule 12.1.1.1: ?A?N?`E???u?E???C???[?E?E.2?E??E?A????z???E
+
+# Rule 12.1.1.2: ?A?N?`E???u?E???C???[???????E?s?????E
+
+# Rule 12.1.1.3: ?????E?E??????A??????E?v???C???[??
+
+# Rule 2025:
+
+# --- END OF INDEX ---

engine/game/mixins/__pycache__/effect_mixin.cpython-312.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:458a917bf0e585b701ddee3dcf0a668e57ade6e9b592b05f6312e116cb4a382e
+size 249282

engine/game/mixins/action_mixin.py

@@ -0,0 +1,407 @@
+import random
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from engine.game.enums import Phase
+from engine.models.ability import EffectType, TriggerType
+
+if TYPE_CHECKING:
+    pass
+
+
+class ActionMixin:
+    """
+    Mixin for GameState that handles player actions and core mechanics.
+    """
+
+    def _resolve_deck_refresh(self, player: Any) -> None:
+        """Rule 10.2: If deck is empty, shuffle waiting room to make new deck."""
+        if not player.main_deck and player.discard:
+            # Shuffle discard into deck
+            player.main_deck = list(player.discard)
+            player.discard = []
+            random.shuffle(player.main_deck)
+            player.deck_refreshed_this_turn = True
+            if hasattr(self, "log_rule"):
+                self.log_rule(
+                    "Rule 10.2",
+                    f"Player {player.player_id} Refreshed Deck from Discard ({len(player.main_deck)} cards).",
+                )
+
+    def _draw_cards(self, player: Any, count: int) -> None:
+        for _ in range(count):
+            if hasattr(self, "_process_rule_checks"):
+                self._process_rule_checks()
+
+            # Check for refresh before drawing
+            if not player.main_deck:
+                self._resolve_deck_refresh(player)
+
+            if player.main_deck:
+                player.hand.append(player.main_deck.pop(0))
+                player.hand_added_turn.append(self.turn_number)
+            else:
+                # Deck still empty after attempt to refresh (Rule 10.2.1.2: If both empty, cannot draw)
+                pass
+
+            if hasattr(self, "_process_rule_checks"):
+                self._process_rule_checks()
+
+    def _play_member(self, hand_idx: int, area_idx: int) -> None:
+        p = self.active_player
+        if "placement" in p.restrictions:
+            return
+        card_id = p.hand.pop(hand_idx)
+        if hand_idx < len(p.hand_added_turn):
+            added_turn = p.hand_added_turn.pop(hand_idx)
+        else:
+            # Fallback if list is desynced (shouldn't happen but prevented crash)
+            added_turn = 0
+
+        # Safety check: verify card exists in database before accessing
+        card_id_int = int(card_id)
+        if card_id_int not in self.member_db:
+            # Put the card back in hand and return to prevent crash
+            p.hand.insert(hand_idx, card_id)
+            p.hand_added_turn.insert(hand_idx, added_turn if hand_idx < len(p.hand_added_turn) else 0)
+            return
+
+        card = self.member_db[card_id_int]
+        if hasattr(self, "log_rule"):
+            self.log_rule("Rule 7.7.2.2", f"Player {p.player_id} plays {card.name} to Slot {area_idx}.")
+        # Calculate slot-specific cost reduction
+        slot_reduction = sum(
+            ce["effect"].value
+            for ce in p.continuous_effects
+            if ce["effect"].effect_type == EffectType.REDUCE_COST and (ce.get("target_slot", -1) in (-1, area_idx))
+        )
+        base_cost = max(0, card.cost - slot_reduction)
+        cost = base_cost
+
+        is_baton = p.stage[area_idx] >= 0
+        if is_baton:
+            extra_baton = sum(
+                ce["effect"].value
+                for ce in p.continuous_effects
+                if ce["effect"].effect_type == EffectType.BATON_TOUCH_MOD
+            )
+            effective_baton_limit = p.baton_touch_limit + extra_baton
+
+            if p.baton_touch_count >= effective_baton_limit:
+                # Should be caught by get_legal_actions, but safety first
+                p.hand.insert(hand_idx, card_id)
+                p.hand_added_turn.insert(hand_idx, added_turn)
+                return
+
+            prev_card_id = int(p.stage[area_idx])
+            if prev_card_id in self.member_db:
+                prev_card = self.member_db[prev_card_id]
+            else:
+                prev_card = None
+
+            if prev_card:
+                if hasattr(self, "log_rule"):
+                    self.log_rule("Rule 9.6.2.3.2", f"Baton Touch! Cost reduced by {prev_card.cost}.")
+                cost = max(0, cost - prev_card.cost)
+                p.baton_touch_count += 1
+
+                # Rule 9.9.1.2: Check for ON_LEAVES triggers before/as card leaves stage
+                for ability in prev_card.abilities:
+                    trig = getattr(ability, "trigger", "NO_TRIGGER")
+                    if trig == TriggerType.ON_LEAVES:
+                        self.triggered_abilities.append(
+                            (
+                                p.player_id,
+                                ability,
+                                {"area": area_idx, "card_id": p.stage[area_idx], "from_zone": "stage"},
+                            )
+                        )
+            else:
+                # If prev_card is None, just increment baton touch count without cost adjustment
+                p.baton_touch_count += 1
+
+            p.discard.append(p.stage[area_idx])
+            if p.stage_energy_count[area_idx] > 0:
+                p.energy_deck.extend(p.stage_energy[area_idx])
+                p.clear_stage_energy(area_idx)
+        untapped = [i for i, tapped in enumerate(p.tapped_energy) if not tapped]
+        if len(untapped) < cost:
+            p.hand.insert(hand_idx, card_id)
+            p.hand_added_turn.insert(hand_idx, added_turn)
+            return
+        for i in range(cost):
+            p.tapped_energy[untapped[i]] = True
+        p.stage[area_idx] = card_id
+        self.prev_cid = prev_card_id if "prev_card_id" in locals() else -1
+        p.members_played_this_turn[area_idx] = True  # Rule 9.6.2.1.2.1: Cannot play into this slot again this turn
+        for ability in card.abilities:
+            if ability.trigger == TriggerType.ON_PLAY:
+                if hasattr(self, "log_rule"):
+                    self.log_rule("Rule 11.3", f"Triggering [登場] (On Play) abilities for {card.name}.")
+                # print(f"DEBUG: Queuing ON_PLAY trigger for {card.name}")
+                self.triggered_abilities.append((p.player_id, ability, {"area": area_idx, "card_id": card_id}))
+        if hasattr(self, "_check_remote_triggers"):
+            self._check_remote_triggers(TriggerType.ON_PLAY, {"card_id": card_id, "area": area_idx})
+
+        if hasattr(self, "_process_rule_checks"):
+            self._process_rule_checks()
+
+    def _activate_member_ability(self, area: int) -> None:
+        p = self.active_player
+        card_id = int(p.stage[area])
+        if card_id < 0 or card_id not in self.member_db:
+            return
+        member = self.member_db[card_id]
+        ability = None
+        ability_idx = -1
+        for abi_idx, ab in enumerate(member.abilities):
+            if ab.trigger == TriggerType.ACTIVATED:
+                abi_key = f"{card_id}-{abi_idx}"
+                if ab.is_once_per_turn and abi_key in p.used_abilities:
+                    continue
+                ability = ab
+                ability_idx = abi_idx
+                break
+        if not ability:
+            return
+
+        if hasattr(self, "log_rule"):
+            self.log_rule("Rule 7.7.2.1", f"Player {p.player_id} activates ability of {member.name} (Slot {area}).")
+
+        # Set resolution context for metadata tracking
+        self.current_resolving_ability = ability
+        self.current_resolving_member = member.name
+        self.current_resolving_member_id = card_id
+
+        if not self._pay_costs(p, ability.costs, source_area=area):
+            # Defer execution until cost paid (via choice)
+            abi_key = f"{card_id}-{ability_idx}"
+            self.pending_activation = {
+                "ability": ability,
+                "context": {"area": area, "card_id": card_id, "source_card_id": card_id},
+                "abi_key": abi_key,
+            }
+            return
+        total = len(ability.effects)
+        from engine.models.ability import ResolvingEffect
+
+        for i, effect in enumerate(reversed(ability.effects)):
+            step = total - i
+            self.pending_effects.insert(0, ResolvingEffect(effect, card_id, step, total))
+
+        if ability.is_once_per_turn:
+            p.used_abilities.add(f"{card_id}-{ability_idx}")
+        while self.pending_effects and not self.pending_choices:
+            self._resolve_pending_effect(0, context={"area": area, "card_id": card_id, "source_card_id": card_id})
+
+    def _execute_mulligan(self) -> None:
+        p = self.active_player
+        if hasattr(self, "log_rule"):
+            count = len(p.mulligan_selection) if hasattr(p, "mulligan_selection") else 0
+            self.log_rule("Rule 6.2.1.6", f"Player {p.player_id} finished mulligan ({count} cards).")
+        if hasattr(p, "mulligan_selection") and p.mulligan_selection:
+            cards_to_return = []
+            for idx in sorted(p.mulligan_selection, reverse=True):
+                if idx < len(p.hand):
+                    cards_to_return.append(p.hand.pop(idx))
+                    if idx < len(p.hand_added_turn):
+                        p.hand_added_turn.pop(idx)
+            for _ in range(len(cards_to_return)):
+                if p.main_deck:
+                    p.hand.append(p.main_deck.pop(0))
+                    p.hand_added_turn.append(self.turn_number)
+            p.main_deck.extend(cards_to_return)
+            random.shuffle(p.main_deck)
+
+        if hasattr(p, "mulligan_selection"):
+            p.mulligan_selection.clear()
+
+        # Phase transition: P1 -> P2 -> ACTIVE
+        if self.phase == Phase.MULLIGAN_P1:
+            self.current_player = 1 - self.first_player
+            self.phase = Phase.MULLIGAN_P2
+        else:
+            self.current_player = self.first_player
+            self.phase = Phase.ACTIVE
+
+    def _check_hearts_meet_requirement(self, have: np.ndarray, need: np.ndarray) -> bool:
+        """
+        Check if 'have' hearts satisfy 'need' requirements.
+        have/need: shape (7,) [Pink, Green, Yellow, Purple, Red, Blue, Any/Wildcard]
+        index 6 in 'have' is Wildcard (can be any color).
+        index 6 in 'need' is 'Any' requirement (can be satisfied by any color).
+        """
+        # 1. Check specific color requirements (0-5)
+        # Calculate deficit for each color
+        deficits = np.maximum(0, need[:6] - have[:6])
+        total_deficit = np.sum(deficits)
+
+        # Check if we have enough Wildcards to cover the deficit
+        wildcards_have = have[6] if len(have) > 6 else 0
+        if wildcards_have < total_deficit:
+            return False
+
+        # 2. Check 'Any' requirement (index 6)
+        any_need = need[6] if len(need) > 6 else 0
+        if any_need <= 0:
+            return True
+
+        # Remaining Wildcards after covering deficit
+        remaining_wildcards = wildcards_have - total_deficit
+
+        # Surplus specific hearts (those not used for specific requirements)
+        surplus_specific = np.sum(np.maximum(0, have[:6] - need[:6]))
+
+        total_available_for_any = remaining_wildcards + surplus_specific
+
+        return total_available_for_any >= any_need
+
+    def _consume_hearts(self, have: np.ndarray, need: np.ndarray) -> None:
+        """
+        Consume 'need' from 'have' in-place.
+        Assumes _check_hearts_meet_requirement returned True.
+        """
+        # 1. Consume for specific requirements
+        for i in range(6):
+            n = need[i] if i < len(need) else 0
+            if n > 0:
+                # Use specific color first
+                take_specific = min(have[i], n)
+                have[i] -= take_specific
+                remaining_need = n - take_specific
+
+                # Use Wildcards for remainder
+                if remaining_need > 0 and len(have) > 6:
+                    take_wild = min(have[6], remaining_need)
+                    have[6] -= take_wild
+
+        # 2. Consume for 'Any' requirement
+        any_need = need[6] if len(need) > 6 else 0
+        if any_need > 0:
+            # First consume surplus specific colors
+            for i in range(6):
+                if any_need <= 0:
+                    break
+                if have[i] > 0:
+                    take = min(have[i], any_need)
+                    have[i] -= take
+                    any_need -= take
+
+            # Then consume Wildcards
+            if any_need > 0 and len(have) > 6:
+                take = min(have[6], any_need)
+                have[6] -= take
+
+    def _set_live_card(self, hand_idx: int) -> None:
+        """Set a card face-down in live zone"""
+        p = self.active_player
+        if hand_idx < 0 or hand_idx >= len(p.hand) or len(p.live_zone) >= 3:
+            return
+
+        card_id = p.hand[hand_idx]  # Look before pop for logging context
+        from engine.game.state_utils import get_base_id
+
+        base_id = get_base_id(card_id)
+
+        if base_id in self.live_db:
+            card_desc = f"{self.live_db[base_id].name} ({self.live_db[base_id].card_no})"
+        elif base_id in self.member_db:
+            card_desc = f"手札[{hand_idx}] ({self.member_db[base_id].card_no})"
+        else:
+            card_desc = f"Card #{card_id}"
+
+        if hasattr(self, "log_rule"):
+            self.log_rule("Rule 8.2.2", f"Player {p.player_id} sets {card_desc} to Live Zone.")
+
+        p.hand.pop(hand_idx)
+        if hand_idx < len(p.hand_added_turn):
+            p.hand_added_turn.pop(hand_idx)
+        p.live_zone.append(card_id)
+        p.live_zone_revealed.append(False)
+        # Rule 8.2.2 modification: Draw happens at end of Live Set phase, not immediately
+        # self._draw_cards(p, 1)
+        p.live_cards_set_this_turn += 1
+
+    def _execute_action(self, action: int) -> None:
+        """Internal: execute action on this state (mutates self)"""
+        p = self.active_player
+        if self.phase in (Phase.MULLIGAN_P1, Phase.MULLIGAN_P2):
+            if action == 0:
+                self._execute_mulligan()
+            elif 300 <= action <= 359:
+                card_idx = action - 300
+                if card_idx < len(p.hand):
+                    if not hasattr(p, "mulligan_selection"):
+                        p.mulligan_selection = set()
+                    if card_idx in p.mulligan_selection:
+                        p.mulligan_selection.remove(card_idx)
+                    else:
+                        p.mulligan_selection.add(card_idx)
+            return
+
+        if getattr(self, "pending_choices", []):
+            if action == 0:
+                choice_type, params = self.pending_choices[0]
+                if choice_type == "CONTINUE_LIVE_RESULT":
+                    self.pending_choices.pop(0)
+                    self._finish_live_result()
+                    return
+                if choice_type.startswith("CONTINUE"):
+                    self.pending_choices.pop(0)
+                    return
+                if True:  # Handle action 0 as cancel/fail for both optional and mandatory (if forced)
+                    self.pending_choices.pop(0)
+
+                    # If look_and_choose declined, move looked cards to discard if on_fail is set
+                    if params.get("reason") == "look_and_choose" and getattr(self, "looked_cards", []):
+                        if params.get("on_fail") == "discard":
+                            p.discard.extend(self.looked_cards)
+                        self.looked_cards = []
+
+                    if params.get("reason") in ("cost", "effect"):
+                        self.pending_effects.clear()
+                        # If we had chained choices (rare for cost), they are now invalid ideally
+                        # But pending_choices might contain next steps?
+                        # For "cost", the whole ability aborts, so safe to clear.
+                        self.pending_choices.clear()
+                        # Clear resolution state
+                        self.looked_cards = []
+                        self.current_resolving_member = None
+                        self.current_resolving_member_id = -1
+                    return
+            if action >= 500:
+                self._handle_choice(action)
+                return
+
+        if self.phase == Phase.ACTIVE:
+            self._do_active_phase()
+        elif self.phase == Phase.ENERGY:
+            self._do_energy_phase()
+        elif self.phase == Phase.DRAW:
+            self._do_draw_phase()
+        elif self.phase == Phase.MAIN:
+            if action == 0:
+                self._end_main_phase()
+            elif 1 <= action <= 180:
+                adj = action - 1
+                self._play_member(adj // 3, adj % 3)
+            elif 200 <= action <= 202:
+                self._activate_member_ability(action - 200)
+        elif self.phase == Phase.LIVE_SET:
+            if action == 0:
+                self._end_live_set()
+            elif 400 <= action <= 459:
+                self._set_live_card(action - 400)
+        elif self.phase == Phase.PERFORMANCE_P1:
+            if 900 <= action <= 902:
+                self._do_performance(0, live_idx=action - 900)
+            else:
+                self._do_performance(0)
+        elif self.phase == Phase.PERFORMANCE_P2:
+            if 900 <= action <= 902:
+                self._do_performance(1, live_idx=action - 900)
+            else:
+                self._do_performance(1)
+        elif self.phase == Phase.LIVE_RESULT:
+            self._do_live_result()

engine/game/mixins/phase_mixin.py

@@ -0,0 +1,654 @@
+import random
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from engine.game.enums import Phase
+from engine.models.ability import EffectType, TriggerType
+
+if TYPE_CHECKING:
+    pass
+
+
+class PhaseMixin:
+    """
+    Mixin for GameState that handles turn and phase transitions.
+
+    Phase State Machine (Rule 7):
+        MULLIGAN_P1 -> MULLIGAN_P2 -> ACTIVE -> ENERGY -> DRAW -> MAIN
+        -> LIVE_SET (both players) -> PERFORMANCE_P1 -> PERFORMANCE_P2
+        -> LIVE_RESULT -> ACTIVE (next turn)
+
+    Each phase handler (e.g. _do_active_phase) advances self.phase to the next
+    phase before returning. Do not manually set self.phase after calling a handler.
+    """
+
+    def _do_active_phase(self) -> None:
+        p = self.active_player
+        if hasattr(self, "log_rule"):
+            self.log_rule("Rule 7.4.1", f"Active Phase: Untapping all members and energy for Player {p.player_id}.")
+        if isinstance(p.members_played_this_turn, list):
+            p.members_played_this_turn.clear()
+        else:
+            p.members_played_this_turn.fill(False)
+        p.untap_all()
+        self.phase = Phase.ENERGY
+
+    def _do_energy_phase(self) -> None:
+        p = self.active_player
+        if hasattr(self, "log_rule"):
+            self.log_rule(
+                "Rule 7.5.2", f"Energy Phase: Player {p.player_id} moves 1 card from Energy Deck to Energy Zone."
+            )
+        if p.energy_deck:
+            p.energy_zone.append(p.energy_deck.pop(0))
+        self.phase = Phase.DRAW
+
+    def _do_draw_phase(self) -> None:
+        p = self.active_player
+        if hasattr(self, "log_rule"):
+            self.log_rule("Rule 7.6.2", f"Draw Phase: Player {p.player_id} draws 1 card.")
+        self._draw_cards(p, 1)
+        self.phase = Phase.MAIN
+
+    def _advance_performance(self) -> None:
+        if self.first_player == 0:
+            if self.phase == Phase.PERFORMANCE_P1:
+                self.phase = Phase.PERFORMANCE_P2
+                self.current_player = 1
+            else:
+                self.phase = Phase.LIVE_RESULT
+        else:
+            if self.phase == Phase.PERFORMANCE_P2:
+                self.phase = Phase.PERFORMANCE_P1
+                self.current_player = 0
+            else:
+                self.phase = Phase.LIVE_RESULT
+
+    def _end_main_phase(self) -> None:
+        """End player's main phase. If first player, switch to second player's turn.
+        If second player, advance to LIVE_SET phase."""
+        if hasattr(self, "log_rule"):
+            self.log_rule("Rule 7.7.3", f"Main Phase End: Player {self.current_player} ends Main Phase.")
+        if self.current_player == self.first_player:
+            # Switch to Player 2's turn: untap their cards and run their phases
+            p2 = 1 - self.first_player
+            self.players[p2].tapped_energy[:] = False
+            self.players[p2].tapped_members[:] = False
+            self.players[p2].members_played_this_turn[:] = False
+            self.current_player = p2
+            # Clear any stale looked_cards from ability resolution (safety)
+            self.looked_cards = []
+            # Chain through ACTIVE -> ENERGY -> DRAW -> MAIN
+            # Each handler sets self.phase to the next phase before returning
+            self.phase = Phase.ACTIVE
+            self._do_active_phase()  # Sets phase to ENERGY
+            self._do_energy_phase()  # Sets phase to DRAW
+            self._do_draw_phase()  # Sets phase to MAIN
+        else:
+            # Both players have had their main phase, move to LIVE_SET
+            self.phase = Phase.LIVE_SET
+            self.current_player = self.first_player
+            # Clear any stale looked_cards from ability resolution
+            self.looked_cards = []
+
+    def _end_live_set(self) -> None:
+        """End player's live set phase. First player sets first, then second player.
+        After both, advance to performance phase (first player performs first)."""
+        p = self.active_player
+        # Draw cards equal to the number of cards set this turn (Rule 8.2.2 modified timing)
+        if p.live_cards_set_this_turn > 0:
+            if hasattr(self, "log_rule"):
+                self.log_rule(
+                    "Rule 8.2.2", f"Live Set End: Player {p.player_id} draws {p.live_cards_set_this_turn} cards."
+                )
+            self._draw_cards(p, p.live_cards_set_this_turn)
+            p.live_cards_set_this_turn = 0
+
+        if self.current_player == self.first_player:
+            # Switch to second player for their live set
+            self.current_player = 1 - self.first_player
+        else:
+            # Both players have set lives, begin performance
+            # Performance order matches first_player: P1 performs first if first_player=0
+            self.performance_results = {}
+            if self.first_player == 0:
+                self.phase = Phase.PERFORMANCE_P1
+                self.current_player = 0
+            else:
+                self.phase = Phase.PERFORMANCE_P2
+                self.current_player = 1
+
+    def _do_performance(self, player_idx: int, live_idx: int = -1) -> None:
+        """Execute performance phase for a player.
+        If live_idx >= 0, only that specific live card is performed.
+        Otherwise (default -1), all cards in the live zone are performed (all-or-nothing).
+        """
+        p = self.players[player_idx]
+
+        # Phase 1: Ability Trigger (Run once)
+        if not p.performance_abilities_processed:
+            p.performance_abilities_processed = True
+
+            p.live_zone_revealed = [True] * len(p.live_zone)
+
+            # Rule 8.3.4: "puts all cards that are not Live Cards into their Waiting Room"
+            # Filter live_zone: Keep only if in live_db
+            new_live_zone = []
+            for cid in p.live_zone:
+                if cid in self.live_db:
+                    new_live_zone.append(cid)
+                else:
+                    if hasattr(self, "log_rule"):
+                        self.log_rule("Rule 8.3.4", f"Discarding non-live card {cid} from Live Zone.")
+                    p.discard.append(cid)
+            p.live_zone = new_live_zone
+
+            triggers_found = False
+            for card_id in p.live_zone:
+                for ab in self.live_db[card_id].abilities:
+                    if ab.trigger == TriggerType.ON_LIVE_START:
+                        if hasattr(self, "log_rule"):
+                            self.log_rule(
+                                "Rule 11.4",
+                                f"Triggering [ライブ開始時] (Live Start) abilities for {self.live_db[card_id].name}.",
+                            )
+                        self.triggered_abilities.append((player_idx, ab, {"card_id": card_id}))
+                        triggers_found = True
+
+            for i, card_id in enumerate(p.stage):
+                if card_id >= 0 and not p.tapped_members[i] and card_id in self.member_db:
+                    for ab in self.member_db[card_id].abilities:
+                        if ab.trigger == TriggerType.ON_LIVE_START:
+                            self.triggered_abilities.append((player_idx, ab, {"area": i}))
+                            triggers_found = True
+
+            # If abilities triggered, return to main loop to process them
+            if triggers_found:
+                return
+
+        # Phase 2: Wait for resolution
+        if self.triggered_abilities or self.pending_choices or self.pending_effects:
+            return
+
+        # Phase 3: Calculation checks
+        if p.cannot_live:
+            for card_id in p.live_zone:
+                p.discard.append(card_id)
+            p.live_zone = []
+            p.performance_abilities_processed = False
+            self._advance_performance()
+            return
+
+        if not p.live_zone:
+            # Create empty performance result for consistency
+            self.performance_results[player_idx] = {
+                "success": False,
+                "member_contributions": [],
+                "yell_cards": [],
+                "total_hearts": [0] * 7,
+                "lives": [],
+            }
+            p.performance_abilities_processed = False
+            self._advance_performance()
+            return
+
+        total_blades = p.get_total_blades(self.member_db)
+
+        # Apply cheer_mod (RE_CHEER or cheer_mod rule)
+        extra_reveals = sum(
+            ce["effect"].value
+            for ce in p.continuous_effects
+            if ce["effect"].effect_type == EffectType.META_RULE and ce["effect"].params.get("type") == "cheer_mod"
+        )
+        total_blades = max(0, total_blades + extra_reveals)
+
+        print(f"DEBUG: Total Blades (cheer reveal count): {total_blades}")
+
+        # Collect blade breakdown for result
+        blade_breakdown = []
+        for i in range(3):
+            if p.stage[i] >= 0:
+                blade_breakdown.extend(p.get_blades_breakdown(i, self.member_db))
+        blade_breakdown.extend(p.get_global_blades_breakdown())
+
+        if hasattr(self, "log_rule"):
+            self.log_rule("Rule 8.3.11", f"Player {player_idx} performs Yell ({total_blades} blades).")
+        self.yell_cards = []
+        for _ in range(total_blades):
+            if not p.main_deck and p.discard:
+                random.shuffle(p.discard)
+                p.main_deck, p.discard = p.discard, []
+            if p.main_deck:
+                self.yell_cards.append(p.main_deck.pop(0))
+        draw_bonus, yell_score_bonus = 0, 0
+        total_hearts = np.zeros(7, dtype=np.int32)
+        member_contributions = []
+        heart_breakdown = []
+        for i in range(3):
+            cid = p.stage[i]
+            if cid >= 0:
+                hraw = p.get_effective_hearts(i, self.member_db)
+                total_hearts[: len(hraw)] += hraw
+                heart_breakdown.extend(p.get_hearts_breakdown(i, self.member_db))
+                card = self.member_db[cid]
+
+                # Rule 8.4.1: Include Stage Member volume icons
+                vol = getattr(card, "volume_icons", 0)
+                yell_score_bonus += vol
+
+                member_contributions.append(
+                    {
+                        "source_id": cid,
+                        "source": card.name,
+                        "img": card.img_path,
+                        "hearts": hraw.tolist(),
+                        "blades": int(p.get_effective_blades(i, self.member_db)),
+                        "volume_icons": vol,
+                        "draw_icons": getattr(card, "draw_icons", 0),
+                    }
+                )
+
+        yell_card_details = []
+        for card_id in self.yell_cards:
+            card = self.member_db.get(card_id) or self.live_db.get(card_id)
+            if card:
+                draw_bonus += getattr(card, "draw_icons", 0)
+                vol = getattr(card, "volume_icons", 0)
+                yell_score_bonus += vol
+
+                details = {
+                    "id": card_id,
+                    "name": card.name,
+                    "img": card.img_path,
+                    "blade_hearts": [0] * 7,
+                    "volume_icons": vol,
+                    "draw_icons": getattr(card, "draw_icons", 0),
+                }
+                # Rule 8.4.1: Include Blade Hearts (including ALL Blade) from revealed cards
+                bh = getattr(card, "blade_hearts", None)
+                if bh is not None:
+                    bh_padded = np.zeros(7, dtype=np.int32)
+                    bh_padded[: len(bh)] = bh[:7]
+                    total_hearts[: len(bh_padded)] += bh_padded
+                    details["blade_hearts"] = bh_padded.tolist()
+                yell_card_details.append(details)
+
+        # Apply global TRANSFORM_COLOR to the final heart pool
+        transform_logs = []
+        for ce in p.continuous_effects:
+            eff = ce["effect"]
+            if eff.effect_type == EffectType.TRANSFORM_COLOR:
+                # Value v is the amount or filter? Usually it's "all of type X become Y"
+                # Params: from_color (int 1-6), to_color (int 1-6)
+                src = eff.params.get("from_color", eff.params.get("color"))
+                dest = eff.params.get("to_color")
+                if src and dest:
+                    try:
+                        s_idx, d_idx = int(src) - 1, int(dest) - 1
+                        if 0 <= s_idx < 6 and 0 <= d_idx < 6:
+                            transfer = total_hearts[s_idx]
+                            total_hearts[d_idx] += transfer
+                            total_hearts[s_idx] = 0
+                            heart_breakdown.append(
+                                {
+                                    "source": ce.get("source_name", "Effect"),
+                                    "type": "transform",
+                                    "text": f"Transform {src} Yells to {dest}",
+                                }
+                            )
+                            transform_logs.append(
+                                {
+                                    "source": ce.get("source_name", "Effect"),
+                                    "desc": f"Transform {src} Yells to {dest}",
+                                    "type": "transform",
+                                    "source_id": ce.get("source_id", -1),
+                                }
+                            )
+                    except:
+                        pass
+
+        self._draw_cards(p, draw_bonus)
+
+        # Save pre-consumption hearts for display
+        display_hearts = total_hearts.copy()
+
+        # --- ALL-OR-NOTHING CHECK ---
+        total_req = np.zeros(7, dtype=np.int32)
+        live_reqs = []  # Store individual reqs for UI and logic
+        requirement_logs = []
+
+        # Determine target lives
+        target_lives = []
+        if 0 <= live_idx < len(p.live_zone):
+            target_lives = [p.live_zone[live_idx]]
+        else:
+            target_lives = p.live_zone
+
+        for card_id in target_lives:
+            live = self.live_db[card_id]
+            req = live.required_hearts.copy()
+            for ce in p.continuous_effects:
+                if ce["effect"].effect_type == EffectType.REDUCE_HEART_REQ:
+                    val = ce["effect"].value
+                    color = ce["effect"].params.get("color")
+                    if color == "any" or not color:
+                        req[6] = max(0, req[6] - val)
+                    else:
+                        try:
+                            # color param might be 1-6
+                            c_idx = int(color) - 1
+                            if 0 <= c_idx < 6:
+                                req[c_idx] = max(0, req[c_idx] - val)
+                        except:
+                            pass
+
+                    # Log requirement reduction
+                    red_vec = np.zeros(7, dtype=np.int32)
+                    if color == "any" or not color:
+                        red_vec[6] = val
+                    else:
+                        try:
+                            c_idx = int(color) - 1
+                            if 0 <= c_idx < 6:
+                                red_vec[c_idx] = val
+                        except:
+                            pass
+
+                    if np.any(red_vec > 0):
+                        requirement_logs.append(
+                            {
+                                "source": ce.get("source_name", "Effect"),
+                                "value": (-red_vec).tolist(),
+                                "type": "req_mod",
+                                "source_id": ce.get("source_id", -1),
+                            }
+                        )
+
+            # Pad to 7 just in case
+            req_padded = np.zeros(7, dtype=np.int32)
+            req_padded[: len(req)] = req[:7]
+
+            total_req += req_padded
+            live_reqs.append((card_id, req_padded))
+
+        temp_hearts = total_hearts.copy()
+        live_details = []
+        passed_lives_acc = []
+        any_failed = False
+
+        for card_id, req in live_reqs:
+            l_passed = self._check_hearts_meet_requirement(temp_hearts, req)
+            status_text = "PASSED" if l_passed else "FAILED"
+            if hasattr(self, "log_rule"):
+                card_name = self.live_db[card_id].name if card_id in self.live_db else f"Card {card_id}"
+                self.log_rule("Rule 8.3.15", f"P{player_idx} Live Card '{card_name}': {status_text}")
+
+            if not any_failed and l_passed:
+                # SUCCESS for this card
+                before = temp_hearts.copy()
+                self._consume_hearts(temp_hearts, req)
+                filled = before - temp_hearts
+
+                live_details.append(
+                    {
+                        "id": card_id,
+                        "name": self.live_db[card_id].name,
+                        "img": self.live_db[card_id].img_path,
+                        "required": req.tolist(),
+                        "filled": filled.tolist(),
+                        "passed": True,
+                        "score": self.live_db[card_id].score,
+                    }
+                )
+                passed_lives_acc.append(card_id)
+            else:
+                # FAILED for this card or previous card failed
+                any_failed = True
+                live_details.append(
+                    {
+                        "id": card_id,
+                        "name": self.live_db[card_id].name,
+                        "img": self.live_db[card_id].img_path,
+                        "required": req.tolist(),
+                        "filled": [0] * 7,
+                        "passed": False,
+                        "score": self.live_db[card_id].score,
+                    }
+                )
+
+        all_passed = not any_failed and len(passed_lives_acc) == len(live_reqs)
+
+        # Log results
+        if hasattr(self, "log_rule"):
+            res_str = "PASSED" if all_passed else "FAILED"
+            self.log_rule(
+                "Rule 8.3.15",
+                f"Performance P{player_idx} {res_str} - Lives Passed: {len(passed_lives_acc)}/{len(live_reqs)}",
+            )
+
+        # Rule 8.3.16: If ANY failed, ALL go to discard.
+        if all_passed:
+            p.passed_lives = passed_lives_acc
+            p.live_zone = []  # All moved to passed_lives
+        else:
+            p.passed_lives = []
+            if hasattr(self, "log_rule"):
+                self.log_rule(
+                    "Rule 8.3.16", f"P{player_idx} Performance Failure: Discarding {len(p.live_zone)} live cards."
+                )
+            p.discard.extend(p.live_zone)
+            p.live_zone = []
+
+        p.live_score_bonus += yell_score_bonus
+        p.yell_score_count = yell_score_bonus
+
+        self.performance_results[player_idx] = {
+            "success": all_passed,
+            "lives_passed_count": len(passed_lives_acc) if all_passed else 0,
+            "member_contributions": member_contributions,
+            "yell_cards": yell_card_details,
+            "total_hearts": display_hearts.tolist(),
+            "lives": live_details,
+            "breakdown": {
+                "blades": blade_breakdown,
+                "hearts": heart_breakdown,
+                "requirements": requirement_logs,
+                "transforms": transform_logs,
+                "score_modifiers": [],  # Will be populated in _do_live_result
+            },
+            "yell_score_bonus": yell_score_bonus,
+        }
+
+        # Store in history
+        if not hasattr(self, "performance_history"):
+            self.performance_history = []
+        hist_entry = self.performance_results[player_idx].copy()
+        hist_entry["player_id"] = player_idx
+        hist_entry["turn"] = self.turn_number
+        self.performance_history.append(hist_entry)
+
+        p.performance_abilities_processed = False
+        self._advance_performance()
+
+    def _clear_expired_effects(self, expiry_type: str) -> None:
+        for p in self.players:
+            p.continuous_effects = [e for e in p.continuous_effects if e.get("expiry") != expiry_type]
+            if expiry_type == "LIVE_END":
+                p.cannot_live = False
+                p.live_score_bonus = 0
+                p.live_success_triggered = False
+
+    def _do_live_result(self) -> None:
+        """
+        Rule 8.4: Determine live winner and handle success.
+        """
+        if hasattr(self, "performance_results"):
+            self.last_performance_results = self.performance_results.copy()
+
+        p0, p1 = self.players[0], self.players[1]
+
+        # Rule 8.4.4: Success event triggers before winner determination
+        # Trigger ON_LIVE_SUCCESS for both Stage Members and performed Live Cards
+        for pid, p in enumerate(self.players):
+            if p.passed_lives and not p.live_success_triggered:
+                p.live_success_triggered = True
+                if hasattr(self, "log_rule"):
+                    self.log_rule("Rule 11.5", f"P{pid} Live Success Event: Triggering [ライブ成功時] abilities.")
+                # Stage Members
+                for i, cid in enumerate(p.stage):
+                    if cid >= 0 and cid in self.member_db:
+                        for ab in self.member_db[cid].abilities:
+                            if ab.trigger == TriggerType.ON_LIVE_SUCCESS:
+                                self.triggered_abilities.append((pid, ab, {"area": i}))
+                # Live Cards (Rule 11.5 explicitly mentions both can have success abilities)
+                for cid in p.passed_lives:
+                    if cid in self.live_db:
+                        for ab in self.live_db[cid].abilities:
+                            if ab.trigger == TriggerType.ON_LIVE_SUCCESS:
+                                self.triggered_abilities.append((pid, ab, {"card_id": cid}))
+
+        # If abilities triggered, return to process them (allowing score mods to apply)
+        if self.triggered_abilities:
+            return
+
+        # Calculate base score from passed_lives (Rule 8.4.1)
+        p0_base = sum(self.live_db[c].score for c in p0.passed_lives if c in self.live_db)
+        p1_base = sum(self.live_db[c].score for c in p1.passed_lives if c in self.live_db)
+
+        # Apply score modifiers (Rule 11)
+        for pid, p in enumerate([p0, p1]):
+            player_score_mods = []
+            for ce in p.continuous_effects:
+                if ce["effect"].effect_type == EffectType.MODIFY_SCORE_RULE:
+                    val = ce["effect"].value
+                    if ce["effect"].params and ce["effect"].params.get("multiplier_source") == "yell_score_icon":
+                        val *= p.yell_score_count
+                    p.live_score_bonus += val
+
+                    # Capture for breakdown
+                    if pid in self.performance_results:
+                        self.performance_results[pid]["breakdown"]["score_modifiers"].append(
+                            {
+                                "source": ce.get("source_name", "Effect"),
+                                "value": val,
+                                "desc": f"Score modifier from {ce.get('source_name', 'Effect')}",
+                                "source_id": ce.get("source_id", -1),
+                            }
+                        )
+
+        p0_total, p1_total = p0_base + p0.live_score_bonus, p1_base + p1.live_score_bonus
+        if hasattr(self, "log_rule"):
+            self.log_rule("Rule 8.4.6", f"Live Judgment: P0={p0_total}, P1={p1_total}")
+
+        # Determine Winners (Rule 8.4.6)
+        winners = []
+        if p0_total > 0 or p1_total > 0:
+            if p0_total > p1_total:
+                winners = [0]
+            elif p1_total > p0_total:
+                winners = [1]
+            else:
+                winners = [0, 1]
+
+        choices = []
+        is_tie = len(winners) == 2
+
+        for w in winners:
+            p = self.players[w]
+            if p.passed_lives:
+                # Rule 8.4.7.1: Penalty for ties with multiple cards
+                if is_tie and len(p.passed_lives) >= 2:
+                    if hasattr(self, "log_rule"):
+                        self.log_rule(
+                            "Rule 8.4.7.1", f"Player {w} Tie Penalty: {len(p.passed_lives)} cards; 0 points awarded."
+                        )
+                    continue
+
+                # Rule 8.4.7.2 / 8.4.7.3: Move exactly one card to success lives
+                if len(p.passed_lives) == 1:
+                    cid = p.passed_lives[0]
+                    if hasattr(self, "log_rule"):
+                        self.log_rule(
+                            "Rule 11.5",
+                            f"Triggering [ライブ成功時] (Live Success) abilities for {self.live_db[cid].name}.",
+                        )
+                    p.success_lives.append(cid)
+                    p.passed_lives.pop(0)
+                    if hasattr(self, "log_rule"):
+                        self.log_rule("Rule 8.4.7.2", f"Player {w} obtained 1 Success Live: {self.live_db[cid].name}")
+                else:
+                    # Multi-card success (when not a tie): must choose one (Rule 8.4.7.3)
+                    choices.append(
+                        (
+                            "SELECT_SUCCESS_LIVE",
+                            {
+                                "cards": p.passed_lives.copy(),
+                                "player_id": w,
+                                "source_card_id": p.passed_lives[0],
+                                # Simplified choice text
+                                "effect_description": "獲得するライブカードを1枚選んでください",
+                                "source_member": "ライブ判定",
+                            },
+                        )
+                    )
+
+        for c in reversed(choices):
+            if c not in self.pending_choices:
+                self.pending_choices.insert(0, c)
+
+        if self.pending_choices:
+            choice_player = self.pending_choices[0][1].get("player_id")
+            self.current_player = choice_player
+            return
+
+        # Cleanup (Rule 8.4.8)
+        for w, p in enumerate(self.players):
+            if p.passed_lives:
+                if hasattr(self, "log_rule"):
+                    self.log_rule(
+                        "Rule 8.4.8",
+                        f"P{w} Live Result Cleanup: Discarding {len(p.passed_lives)} surplus passed cards.",
+                    )
+                p.discard.extend(p.passed_lives)
+                p.passed_lives = []
+            p.live_score_bonus = 0
+
+        # Determine who goes first next turn (Rule 8.4.10)
+        # Winner goes first. If both won (tie), host/active or specified logic.
+        if len(winners) == 1:
+            self.first_player = winners[0]
+
+        # Reset turn effects
+        for p in self.players:
+            p.continuous_effects = [e for e in p.continuous_effects if e.get("expiry") != "TURN_END"]
+            p.cannot_live = False
+            p.used_abilities.clear()
+            p.moved_members_this_turn.clear()
+
+        # Advance turn
+        self._finish_live_result()
+
+    def _finish_live_result(self) -> None:
+        """Advance to the next turn after live results are finalized."""
+        # Q171: "Until end of live" effects expire at the end of the Live Result phase.
+        self._clear_expired_effects("LIVE_END")
+
+        self.turn_number += 1
+        self.action_count_this_turn = 0
+        self.first_player = (self.first_player + 1) % len(self.players)
+        self.current_player = self.first_player
+        self.phase = Phase.ACTIVE
+
+        if hasattr(self, "performance_results"):
+            self.performance_results.clear()
+
+        for p in self.players:
+            # Rule 8.4.11: Move any unperformed live cards to discard
+            p.discard.extend(p.live_zone)
+            p.live_zone = []
+            p.live_zone_revealed = []
+            p.performance_abilities_processed = False
+
+        self.check_win_condition()
+        self._do_active_phase()

engine/game/numba_utils.py

@@ -0,0 +1,71 @@
+"""
+Numba Utils for Love Live Card Game
+JIT-compiled functions for high-performance game logic.
+"""
+
+try:
+    from numba import njit
+
+    JIT_AVAILABLE = True
+except ImportError:
+    # Fallback to python decorator if numba is missing (for safety)
+    JIT_AVAILABLE = False
+
+    def njit(func):
+        return func
+
+
+import numpy as np
+
+
+@njit
+def calc_main_phase_masks(
+    hand: np.ndarray,
+    stage: np.ndarray,
+    available_energy: int,
+    total_reduction: int,
+    baton_touch_allowed: bool,
+    members_played_this_turn: np.ndarray,
+    member_costs: np.ndarray,  # Direct lookup array: cost = member_costs[card_id]
+    mask: np.ndarray,
+) -> None:
+    """
+    JIT-compiled Main Phase legal action calculation.
+    """
+    # Iterate through hand to find playable members
+    hand_len = len(hand)
+    for i in range(hand_len):
+        card_id = hand[i]
+
+        # Check if valid card ID for array lookup
+        if card_id < 0 or card_id >= len(member_costs):
+            continue
+
+        base_cost = member_costs[card_id]
+        if base_cost == -1:  # Not a member
+            continue
+
+        # Check each of the 3 stage areas
+        for area in range(3):
+            if members_played_this_turn[area]:
+                continue
+
+            active_cost = base_cost - total_reduction
+            if active_cost < 0:
+                active_cost = 0
+
+            # Baton Touch Rule
+            stage_card_id = stage[area]
+            if baton_touch_allowed and stage_card_id != -1:
+                if stage_card_id < len(member_costs):
+                    existing_cost = member_costs[stage_card_id]
+                    if existing_cost != -1:
+                        active_cost = active_cost - existing_cost
+                        if active_cost < 0:
+                            active_cost = 0
+
+            # Check affordability
+            if active_cost <= available_energy:
+                action_idx = 1 + (i * 3) + area
+                if action_idx < 1000:
+                    mask[action_idx] = 1

engine/game/player_state.py

@@ -0,0 +1,827 @@
+from typing import Any, Dict, List
+
+import numpy as np
+
+from engine.game.state_utils import StateMixin
+from engine.models.ability import Condition, ConditionType, EffectType, TargetType, TriggerType
+from engine.models.card import MemberCard
+
+
+class PlayerState(StateMixin):
+    """
+    Player state (Rule 3)
+    Contains areas, zones, and tracking for a single player.
+    """
+
+    __slots__ = (
+        "player_id",
+        "hand",
+        "main_deck",
+        "energy_deck",
+        "discard",
+        "energy_zone",
+        "success_lives",
+        "live_zone",
+        "live_zone_revealed",
+        "stage",
+        "stage_energy_vec",
+        "stage_energy_count",
+        "tapped_energy",
+        "tapped_members",
+        "members_played_this_turn",
+        "mulligan_selection",
+        "baton_touch_limit",
+        "baton_touch_count",
+        "negate_next_effect",
+        "restrictions",
+        "live_score_bonus",
+        "passed_lives",
+        "cannot_live",
+        "used_abilities",
+        "meta_rules",
+        "continuous_effects",
+        "continuous_effects_vec",
+        "continuous_effects_ptr",
+        "hand_buffer",
+        "moved_members_this_turn",
+        "hand_added_turn",
+        "deck_refreshed_this_turn",
+        "performance_abilities_processed",
+        "rested_members",
+        "revealed_hand",
+        "yell_score_count",
+        "fast_mode",
+        "members_tapped_by_opponent_this_turn",
+        "live_cards_set_this_turn",
+        "live_success_triggered",
+    )
+
+    def __init__(self, player_id: int):
+        self.player_id = player_id
+        self.hand: List[int] = []
+        self.hand_added_turn: List[int] = []
+        self.main_deck: List[int] = []
+        self.energy_deck: List[int] = []
+        self.discard: List[int] = []
+        self.energy_zone: List[int] = []
+        self.success_lives: List[int] = []
+        self.live_zone: List[int] = []
+        self.live_zone_revealed: List[bool] = []
+        self.stage: np.ndarray = np.full(3, -1, dtype=np.int32)
+        self.stage_energy_vec: np.ndarray = np.zeros((3, 32), dtype=np.int32)
+        self.stage_energy_count: np.ndarray = np.zeros(3, dtype=np.int32)
+        self.tapped_energy: np.ndarray = np.zeros(100, dtype=bool)
+        self.tapped_members: np.ndarray = np.zeros(3, dtype=bool)
+        self.members_played_this_turn: np.ndarray = np.zeros(3, dtype=bool)
+        self.mulligan_selection: set = set()
+        self.baton_touch_limit: int = 1
+        self.baton_touch_count: int = 0
+        self.negate_next_effect: bool = False
+        self.restrictions: set[str] = set()
+        self.live_score_bonus: int = 0
+        self.passed_lives: List[int] = []
+        self.cannot_live: bool = False
+        self.used_abilities: set[str] = set()
+        self.moved_members_this_turn: set[int] = set()
+        self.continuous_effects: List[Dict[str, Any]] = []
+        self.continuous_effects_vec: np.ndarray = np.zeros((32, 10), dtype=np.int32)
+        self.continuous_effects_ptr: int = 0
+        self.meta_rules: set[str] = set()
+        self.fast_mode: bool = False
+        self.hand_buffer: np.ndarray = np.zeros(100, dtype=np.int32)
+        self.deck_refreshed_this_turn: bool = False
+        self.performance_abilities_processed: bool = False
+        self.rested_members: np.ndarray = np.zeros(3, dtype=bool)
+        self.revealed_hand: bool = False
+        self.yell_score_count: int = 0
+        self.live_cards_set_this_turn: int = 0
+        self.live_success_triggered: bool = False
+        self.members_tapped_by_opponent_this_turn: set[int] = set()
+
+    @property
+    def score(self) -> int:
+        """
+        Game Score (Rule 1.2 / 8.4.7)
+        - This is the number of cards in the success_lives zone.
+        - Points are obtained during Rule 8.4 Live Judgment phase.
+        - Only 1 success live card can be added per judgment turn.
+        """
+        return len(self.success_lives)
+
+    @property
+    def energy_count(self) -> int:
+        return len(self.energy_zone)
+
+    @energy_count.setter
+    def energy_count(self, value: int):
+        current = len(self.energy_zone)
+        if value < current:
+            # Assume cost payment: Move from Energy Zone to Discard
+            diff = current - value
+            for _ in range(diff):
+                if self.energy_zone:
+                    card_id = self.energy_zone.pop()
+                    self.discard.append(card_id)
+        elif value > current:
+            # Cannot magically add empty energy without cards
+            pass
+
+    @property
+    def stage_energy(self) -> List[List[int]]:
+        """Legacy compatibility property. Returns a copy of the energy state."""
+        res = []
+        for i in range(3):
+            count = self.stage_energy_count[i]
+            res.append(list(self.stage_energy_vec[i, :count]))
+        return res
+
+    def add_stage_energy(self, slot_idx: int, card_id: int) -> None:
+        """Add energy to a slot using flat arrays."""
+        count = self.stage_energy_count[slot_idx]
+        if count < 32:
+            self.stage_energy_vec[slot_idx, count] = card_id
+            self.stage_energy_count[slot_idx] = count + 1
+
+    def clear_stage_energy(self, slot_idx: int) -> None:
+        """Clear energy from a slot."""
+        self.stage_energy_count[slot_idx] = 0
+
+    def _reset(self, player_id: int) -> None:
+        """Reset state for pool reuse."""
+        self.player_id = player_id
+        self.hand.clear()
+        self.main_deck.clear()
+        self.energy_deck.clear()
+        self.discard.clear()
+        self.energy_zone.clear()
+        self.success_lives.clear()
+        self.live_zone.clear()
+        self.live_zone_revealed.clear()
+        self.stage.fill(-1)
+        self.stage_energy_vec.fill(0)
+        self.stage_energy_count.fill(0)
+        self.tapped_energy.fill(False)
+        self.tapped_members.fill(False)
+        self.members_played_this_turn.fill(False)
+        self.mulligan_selection.clear()
+        self.baton_touch_limit = 1
+        self.baton_touch_count = 0
+        self.negate_next_effect = False
+        self.restrictions.clear()
+        self.live_score_bonus = 0
+        self.passed_lives.clear()
+        self.cannot_live = False
+        self.used_abilities.clear()
+        self.continuous_effects.clear()
+        self.continuous_effects_vec.fill(0)
+        self.continuous_effects_ptr = 0
+        self.meta_rules.clear()
+        self.hand_added_turn.clear()
+        self.deck_refreshed_this_turn = False
+        self.performance_abilities_processed = False
+        self.rested_members.fill(False)
+        self.revealed_hand = False
+        self.revealed_hand = False
+        self.moved_members_this_turn.clear()
+        self.members_tapped_by_opponent_this_turn.clear()
+        self.live_cards_set_this_turn = 0
+        self.live_success_triggered = False
+
+    def copy_slots_to(self, target: "PlayerState") -> None:
+        """Hardcoded field copy for maximum performance."""
+        target.player_id = self.player_id
+        target.hand = self.hand[:]
+        target.hand_added_turn = self.hand_added_turn[:]
+        target.main_deck = self.main_deck[:]
+        target.energy_deck = self.energy_deck[:]
+        target.discard = self.discard[:]
+        target.energy_zone = self.energy_zone[:]
+        target.success_lives = self.success_lives[:]
+        target.live_zone = self.live_zone[:]
+        target.live_zone_revealed = self.live_zone_revealed[:]
+        target.baton_touch_limit = self.baton_touch_limit
+        target.baton_touch_count = self.baton_touch_count
+        target.negate_next_effect = self.negate_next_effect
+        target.live_score_bonus = self.live_score_bonus
+        target.cannot_live = self.cannot_live
+        target.deck_refreshed_this_turn = self.deck_refreshed_this_turn
+        target.performance_abilities_processed = self.performance_abilities_processed
+        target.revealed_hand = self.revealed_hand
+        target.continuous_effects_ptr = self.continuous_effects_ptr
+        target.live_cards_set_this_turn = self.live_cards_set_this_turn
+        target.live_success_triggered = self.live_success_triggered
+
+    def copy(self) -> "PlayerState":
+        new = PlayerState(self.player_id)
+        self.copy_to(new)
+        return new
+
+    def copy_to(self, new: "PlayerState") -> None:
+        # 1. Scalar/List fields
+        self.copy_slots_to(new)
+        # 2. NumPy arrays (memcpy speed)
+        np.copyto(new.stage, self.stage)
+        np.copyto(new.stage_energy_vec, self.stage_energy_vec)
+        np.copyto(new.stage_energy_count, self.stage_energy_count)
+        np.copyto(new.tapped_energy, self.tapped_energy)
+        np.copyto(new.tapped_members, self.tapped_members)
+        np.copyto(new.rested_members, self.rested_members)
+        np.copyto(new.continuous_effects_vec, self.continuous_effects_vec)
+
+        # 3. Sets and complex structures (slowest)
+        np.copyto(new.members_played_this_turn, self.members_played_this_turn)
+        new.used_abilities = set(self.used_abilities)
+        new.restrictions = set(self.restrictions)
+        new.mulligan_selection = set(self.mulligan_selection)
+        new.meta_rules = set(self.meta_rules)
+        new.meta_rules = set(self.meta_rules)
+        new.moved_members_this_turn = set(self.moved_members_this_turn)
+        new.members_tapped_by_opponent_this_turn = set(self.members_tapped_by_opponent_this_turn)
+        new.passed_lives = list(self.passed_lives)
+
+        # Legacy continuous_effects (only copy if needed or for AI skip)
+        if hasattr(self, "fast_mode") and self.fast_mode:
+            new.continuous_effects = []
+        else:
+            new.continuous_effects = [dict(e) for e in self.continuous_effects]
+
+    def untap_all(self) -> None:
+        self.tapped_energy[:] = False
+        self.tapped_members[:] = False
+        self.live_cards_set_this_turn = 0
+
+    def count_untapped_energy(self) -> int:
+        return int(np.count_nonzero(~self.tapped_energy[: len(self.energy_zone)]))
+
+        return breakdown
+
+    def get_blades_breakdown(self, slot_idx: int, card_db: Dict[int, MemberCard]) -> List[Dict[str, Any]]:
+        """Calculate blades breakdown for a slot (Rule 9.9)."""
+        card_id = self.stage[slot_idx]
+        if card_id < 0:
+            return [{"source": f"Slot {slot_idx + 1}", "value": 0, "type": "empty", "source_id": -1}]
+
+        # Check if member is tapped (inactive)
+        if self.tapped_members[slot_idx]:
+            from engine.game.state_utils import get_base_id
+
+            base_id = get_base_id(int(card_id))
+            name = card_db[base_id].name if base_id in card_db else "Unknown"
+            return [{"source": f"{name} (Resting)", "value": 0, "type": "inactive", "source_id": int(card_id)}]
+
+        from engine.game.state_utils import get_base_id
+
+        base_id = get_base_id(int(card_id))
+        if base_id not in card_db:
+            return [{"source": "Unknown Card", "value": 0, "type": "error"}]
+
+        member = card_db[base_id]
+        breakdown = [{"source": member.name, "value": int(member.blades), "type": "base", "source_id": int(card_id)}]
+
+        # Collect effects
+        applied_effects = []  # List of (source_name, effect)
+        for ce in self.continuous_effects:
+            # ONLY include effects targeting this specific slot. 
+            # Global effects (target_slot == -1) are handled at the Player level to avoid overcounting.
+            if ce.get("target_slot") == slot_idx:
+                src = ce.get("source_name", "Effect")
+                if "condition_text" in ce:
+                    src += f" ({ce['condition_text']})"
+                applied_effects.append((src, ce["effect"]))
+
+        for ab in member.abilities:
+            if ab.trigger == TriggerType.CONSTANT:
+                if all(self._check_condition_for_constant(ab_cond, slot_idx, card_db) for ab_cond in ab.conditions):
+                    for eff in ab.effects:
+                        # Construct a helpful source string
+                        src = member.name
+                        if ab.conditions:
+                            cond_texts = []
+                            for c in ab.conditions:
+                                if c.type == ConditionType.TURN_1:
+                                    cond_texts.append("Turn 1")
+                                elif c.type == ConditionType.COUNT_STAGE:
+                                    cond_texts.append(f"Stage {c.params.get('value', 0)}+")
+                                elif c.type == ConditionType.COUNT_HAND:
+                                    cond_texts.append(f"Hand {c.params.get('value', 0)}+")
+                                elif c.type == ConditionType.LIFE_LEAD:
+                                    cond_texts.append("Life Lead")
+                                else:
+                                    cond_texts.append("Cond")
+                            src += f" ({', '.join(cond_texts)})"
+                        else:
+                            src += " (Constant)"
+                        applied_effects.append((src, eff))
+
+        # Layer 4: SET
+        for source, eff in applied_effects:
+            if eff.effect_type == EffectType.SET_BLADES:
+                breakdown = [
+                    {"source": source, "value": int(eff.value), "type": "set", "source_id": ce.get("source_id", -1)}
+                ]
+
+        # Layer 4: ADD / BUFF
+        for source, eff in applied_effects:
+            if eff.effect_type in (EffectType.ADD_BLADES, EffectType.BUFF_POWER):
+                val = eff.value
+                val_desc = ""
+                if eff.params.get("multiplier"):
+                    if eff.params.get("per_live"):
+                        val *= len(self.success_lives)
+                        val_desc = f" ({len(self.success_lives)} Lives)"
+                    elif eff.params.get("per_energy"):
+                        val *= len(self.energy_zone)
+                        val_desc = f" ({len(self.energy_zone)} Energy)"
+                    elif eff.params.get("per_member"):
+                        val *= np.sum(self.stage >= 0)
+                        val_desc = f" ({np.sum(self.stage >= 0)} Members)"
+
+                final_source = source + val_desc
+                breakdown.append(
+                    {
+                        "source": final_source,
+                        "value": int(val),
+                        "type": "mod",
+                        "source_id": ce.get("source_id", -1) if "ce" in locals() else int(card_id),
+                    }
+                )
+
+        return breakdown
+
+    def get_global_blades_breakdown(self) -> List[Dict[str, Any]]:
+        """Calculate breakdown for global (player-wide) blade effects."""
+        breakdown = []
+        applied_effects = []
+        for ce in self.continuous_effects:
+            if ce.get("target_slot") == -1:
+                src = ce.get("source_name", "Effect")
+                if "condition_text" in ce:
+                    src += f" ({ce['condition_text']})"
+                applied_effects.append((ce, src, ce["effect"]))
+
+        for ce, source, eff in applied_effects:
+            if eff.effect_type in (EffectType.ADD_BLADES, EffectType.BUFF_POWER):
+                val = eff.value
+                val_desc = ""
+                if eff.params.get("multiplier"):
+                    if eff.params.get("per_live"):
+                        val *= len(self.success_lives)
+                        val_desc = f" ({len(self.success_lives)} Lives)"
+                    elif eff.params.get("per_energy"):
+                        val *= len(self.energy_zone)
+                        val_desc = f" ({len(self.energy_zone)} Energy)"
+                    elif eff.params.get("per_member"):
+                        val *= np.sum(self.stage >= 0)
+                        val_desc = f" ({np.sum(self.stage >= 0)} Members)"
+
+                final_source = source + val_desc
+                breakdown.append(
+                    {
+                        "source": final_source,
+                        "value": int(val),
+                        "type": "mod",
+                        "source_id": ce.get("source_id", -1),
+                    }
+                )
+        return breakdown
+
+    def get_effective_blades(self, slot_idx: int, card_db: Dict[int, MemberCard]) -> int:
+        breakdown = self.get_blades_breakdown(slot_idx, card_db)
+        total = sum(item["value"] for item in breakdown)
+        return max(0, total)
+
+    def _check_condition_for_constant(
+        self, cond: Condition, slot_idx: int, card_db: Dict[int, MemberCard] = None
+    ) -> bool:
+        """
+        Check if a condition is met for a constant ability.
+        slot_idx < 0 implies the card is not on stage (e.g. in hand for cost reduction).
+        """
+        if cond.type == ConditionType.NONE:
+            return True
+
+        # Conditions that require being on stage
+        if slot_idx < 0:
+            if cond.type in (ConditionType.HAS_MOVED, ConditionType.IS_CENTER, ConditionType.GROUP_FILTER):
+                # For GROUP_FILTER, if it's checking SELF, we might need the card ID context which is not passed here properly.
+                # But for cost reduction, usually it's just Hand/Stage counts.
+                return False
+
+        if cond.type == ConditionType.HAS_MOVED:
+            # Check if this card moved this turn.
+            current_card_id = self.stage[slot_idx]
+            if current_card_id >= 0:
+                return current_card_id in self.moved_members_this_turn
+            return False
+        elif cond.type == ConditionType.TURN_1:
+            # This would require access to game state to check turn number
+            # For now, return True as a placeholder
+            return True
+        elif cond.type == ConditionType.IS_CENTER:
+            # Check if the slot is the center position (index 1 in 3-slot system)
+            return slot_idx == 1
+        elif cond.type == ConditionType.GROUP_FILTER:
+            # Check if the member belongs to the specified group
+            current_card_id = self.stage[slot_idx]
+            if current_card_id >= 0 and card_db:
+                from engine.game.state_utils import get_base_id
+
+                base_id = get_base_id(int(current_card_id))
+                if base_id in card_db:
+                    member = card_db[base_id]
+                group_name = cond.params.get("group", "")
+                # This would need to compare member's group with the condition's group
+                # For now, return True as a placeholder
+                return True
+            return False
+        elif cond.type == ConditionType.COUNT_GROUP:
+            # Count members of a specific group in the stage
+            group_name = cond.params.get("group", "")
+            min_count = cond.params.get("min", 1)
+            zone = cond.params.get("zone", "STAGE")
+
+            count = 0
+            if zone == "STAGE" or zone == "OPPONENT_STAGE":
+                from engine.game.state_utils import get_base_id
+
+                for i in range(3):
+                    card_id = self.stage[i]
+                    if card_id >= 0 and card_db:
+                        base_id = get_base_id(int(card_id))
+                        if base_id in card_db:
+                            member = card_db[base_id]
+                            # Compare member's group with the condition's group
+                            # For now, return True as a placeholder
+                            count += 1
+
+            return count >= min_count
+        elif cond.type == ConditionType.OPPONENT_HAS:
+            # Placeholder for opponent has condition
+            return True
+        elif cond.type == ConditionType.COUNT_ENERGY:
+            min_energy = cond.params.get("min", 1)
+            return len(self.energy_zone) >= min_energy
+        else:
+            # Default lenient for other conditions
+            return True
+
+    def get_hearts_breakdown(self, slot_idx: int, card_db: Dict[int, MemberCard]) -> List[Dict[str, Any]]:
+        """Calculate hearts breakdown for a slot, including continuous effects."""
+        card_id = self.stage[slot_idx]
+        if card_id < 0:
+            return [{"source": f"Slot {slot_idx + 1}", "value": [0] * 7, "type": "empty", "source_id": -1}]
+
+        # Check if member is tapped (inactive)
+        if self.tapped_members[slot_idx]:
+            from engine.game.state_utils import get_base_id
+
+            base_id = get_base_id(int(card_id))
+            name = card_db[base_id].name if base_id in card_db else "Unknown"
+            return [{"source": f"{name} (Resting)", "value": [0] * 7, "type": "inactive", "source_id": int(card_id)}]
+
+        from engine.game.state_utils import get_base_id
+
+        base_id = get_base_id(int(card_id))
+        if base_id not in card_db:
+            return [{"source": "Unknown Card", "value": [0] * 7, "type": "error"}]
+
+        member = card_db[base_id]
+
+        # Ensure base hearts are 7-dim
+        base_hearts = np.zeros(7, dtype=np.int32)
+        base_hearts[: len(member.hearts)] = member.hearts
+
+        breakdown = [{"source": member.name, "value": base_hearts.tolist(), "type": "base", "source_id": int(card_id)}]
+
+        # Collect effects
+        applied_effects = []
+        for ce in self.continuous_effects:
+            if ce.get("target_slot") in (-1, slot_idx):
+                src = ce.get("source_name", "Effect")
+                if "condition_text" in ce:
+                    src += f" ({ce['condition_text']})"
+                applied_effects.append((src, ce["effect"]))
+
+        for ab in member.abilities:
+            if ab.trigger == TriggerType.CONSTANT:
+                if all(self._check_condition_for_constant(ab_cond, slot_idx, card_db) for ab_cond in ab.conditions):
+                    for eff in ab.effects:
+                        # Construct a helpful source string
+                        src = member.name
+                        if ab.conditions:
+                            cond_texts = []
+                            for c in ab.conditions:
+                                if c.type == ConditionType.TURN_1:
+                                    cond_texts.append("Turn 1")
+                                elif c.type == ConditionType.COUNT_STAGE:
+                                    cond_texts.append(f"Stage {c.params.get('value', 0)}+")
+                                elif c.type == ConditionType.COUNT_HAND:
+                                    cond_texts.append(f"Hand {c.params.get('value', 0)}+")
+                                elif c.type == ConditionType.LIFE_LEAD:
+                                    cond_texts.append("Life Lead")
+                                elif c.type == ConditionType.HAS_MEMBER:
+                                    cond_texts.append("Has Member")
+                                elif c.type == ConditionType.HAS_COLOR:
+                                    cond_texts.append("Has Color")
+                                else:
+                                    cond_texts.append("Cond")
+                            src += f" ({', '.join(cond_texts)})"
+                        else:
+                            src += " (Constant)"
+                        applied_effects.append((src, eff))
+
+        # Apply Heart Modifications
+        for source, eff in applied_effects:
+            eff_val = np.zeros(7, dtype=np.int32)
+
+            if eff.effect_type == EffectType.SET_HEARTS:
+                breakdown = [
+                    {
+                        "source": source,
+                        "value": [int(eff.value)] * 7,
+                        "type": "set",
+                        "source_id": ce.get("source_id", -1),
+                    }
+                ]
+                # Reset others? For SET, usually yes.
+                continue
+
+            if eff.effect_type == EffectType.ADD_HEARTS:
+                color_map = {1: 0, 2: 1, 3: 2, 4: 3, 5: 4, 6: 5}  # P,R,Y,G,B,P
+                target_colors = []
+                if eff.params.get("color"):
+                    c = eff.params["color"]
+                    if c in color_map:
+                        target_colors.append(color_map[c])
+                elif eff.params.get("all"):
+                    target_colors = list(range(6))
+
+                amount = eff.value
+                # Multipliers
+                if eff.params.get("multiplier"):
+                    if eff.params.get("per_live"):
+                        amount *= len(self.success_lives)
+                    elif eff.params.get("per_energy"):
+                        amount *= len(self.energy_zone)
+
+                for c_idx in target_colors:
+                    eff_val[c_idx] += amount
+
+                if not target_colors:
+                    pass
+
+                # Only append if non-zero
+                if np.any(eff_val):
+                    breakdown.append(
+                        {
+                            "source": source,
+                            "value": eff_val.tolist(),
+                            "type": "mod",
+                            "source_id": ce.get("source_id", -1) if "ce" in locals() else int(card_id),
+                        }
+                    )
+
+        return breakdown
+
+    def get_effective_hearts(self, slot_idx: int, card_db: Dict[int, MemberCard]) -> np.ndarray:
+        breakdown = self.get_hearts_breakdown(slot_idx, card_db)
+        total = np.zeros(7, dtype=np.int32)
+        for item in breakdown:
+            total += np.array(item["value"], dtype=np.int32)
+        return np.maximum(0, total)
+
+    def get_total_blades(self, card_db: Dict[int, MemberCard]) -> int:
+        total = 0
+        # 1. Base + Slot-specific modifiers
+        for i, card_id in enumerate(self.stage):
+            if card_id >= 0 and not self.tapped_members[i]:
+                total += self.get_effective_blades(i, card_db)
+        
+        # 2. Global modifiers
+        global_mods = self.get_global_blades_breakdown()
+        for mod in global_mods:
+            total += mod["value"]
+            
+        return max(0, total)
+
+    def get_total_hearts(self, card_db: Dict[int, Any]) -> np.ndarray:
+        total = np.zeros(7, dtype=np.int32)
+        for i, card_id in enumerate(self.stage):
+            if card_id >= 0 and not self.tapped_members[i]:
+                total += self.get_effective_hearts(i, card_db)
+        return total
+
+    def get_performance_guide(self, live_db: Dict[int, Any], member_db: Dict[int, Any]) -> Dict[str, Any]:
+        """
+        Calculate projected performance outcome for the user guide.
+        Now comprehensive: includes breakdown for all slots (active, resting, empty)
+        and requirement modifications.
+        """
+        if not self.live_zone:
+            return {"can_perform": False, "reason": "No live cards"}
+
+        from engine.game.state_utils import get_base_id
+
+        # 1. Total Blades & Blade Breakdown
+        total_blades = 0
+        blade_breakdown = []
+        # Always iterate 0-2 to show all slots
+        for i in range(3):
+            # Breakdown method handles empty/inactive cases now
+            bd = self.get_blades_breakdown(i, member_db)
+            blade_breakdown.extend(bd)
+            if self.stage[i] >= 0 and not self.tapped_members[i]:
+                # Sum up effective blades from breakdown for Active members
+                slot_total = sum(item["value"] for item in bd if item.get("type") in ("base", "mod", "set"))
+                total_blades += max(0, slot_total)
+
+        # Apply cheer_mod
+        extra_reveals = sum(
+            ce["effect"].value
+            for ce in self.continuous_effects
+            if ce["effect"].effect_type == EffectType.META_RULE and ce["effect"].params.get("type") == "cheer_mod"
+        )
+        total_blades = max(0, total_blades + extra_reveals)
+
+        # 2. Total Hearts & Heart Breakdown
+        total_hearts = np.zeros(7, dtype=np.int32)
+        heart_breakdown = []
+        for i in range(3):
+            bd = self.get_hearts_breakdown(i, member_db)
+            heart_breakdown.extend(bd)
+            if self.stage[i] >= 0 and not self.tapped_members[i]:
+                # Sum up effective hearts from breakdown for Active members
+                for item in bd:
+                    if item.get("type") in ("base", "mod", "set"):
+                        total_hearts += np.array(item["value"], dtype=np.int32)
+
+        # 3. Apply TRANSFORM_COLOR (Global)
+        transform_log = []
+        for ce in self.continuous_effects:
+            if ce["effect"].effect_type == EffectType.TRANSFORM_COLOR:
+                eff = ce["effect"]
+                src_color = eff.params.get("from_color", eff.params.get("color"))  # 1-based
+                dest_color = eff.params.get("to_color")  # 1-based
+                if src_color and dest_color:
+                    try:
+                        # Handle possibly float/string values
+                        s_idx = int(src_color) - 1
+                        d_idx = int(dest_color) - 1
+                        if 0 <= s_idx < 6 and 0 <= d_idx < 6:
+                            amount_moved = total_hearts[s_idx]
+                            total_hearts[d_idx] += amount_moved
+                            total_hearts[s_idx] = 0
+                            transform_log.append(
+                                {
+                                    "source": ce.get("source_name", "Effect"),
+                                    "desc": f"Color Transform (Type {src_color} -> Type {dest_color})",
+                                    "type": "transform",
+                                    "source_id": ce.get("source_id", -1),
+                                }
+                            )
+                    except:
+                        pass
+
+        # 4. Process Lives & Requirements
+        lives = []
+        req_breakdown = []  # Log for requirement reductions
+
+        for live_id in self.live_zone:
+            l_base = get_base_id(live_id)
+            if l_base not in live_db:
+                continue
+            live_card = live_db[l_base]
+
+            # Base Requirement
+            req_breakdown.append(
+                {"source": live_card.name, "value": live_card.required_hearts.tolist(), "type": "base_req"}
+            )
+
+            # Copy requirement to modify
+            req = live_card.required_hearts.copy()  # (7,)
+
+            # Apply REDUCE_HEART_REQ
+            for ce in self.continuous_effects:
+                eff = ce["effect"]
+                if eff.effect_type == EffectType.REDUCE_HEART_REQ:
+                    reduction_val = np.zeros(7, dtype=np.int32)
+                    target_color = eff.params.get("color")
+                    val = eff.value
+
+                    if target_color and target_color != "any":
+                        try:
+                            c_idx = int(target_color) - 1
+                            if 0 <= c_idx < 6:
+                                reduction_val[c_idx] = val
+                        except:
+                            pass
+                    else:
+                        # Any color reduction (index 6) matches "any" param or default
+                        reduction_val[6] = val
+
+                    # Log reduction
+                    if np.any(reduction_val > 0):
+                        req_breakdown.append(
+                            {
+                                "source": ce.get("source_name", "Effect"),
+                                "value": (-reduction_val).tolist(),
+                                "type": "req_mod",
+                                "source_id": ce.get("source_id", -1),
+                            }
+                        )
+                        req = np.maximum(0, req - reduction_val)
+
+            # Calculate Success (Greedy)
+            temp_hearts = total_hearts.copy()
+
+            # 1. Match specific colors
+            needed_specific = req[:6]
+            have_specific = temp_hearts[:6]
+            used_specific = np.minimum(needed_specific, have_specific)
+
+            temp_hearts[:6] -= used_specific
+            remaining_req = req.copy()
+            remaining_req[:6] -= used_specific
+
+            # 2. Match Any with remaining specific
+            needed_any = remaining_req[6]
+            have_any_from_specific = np.sum(temp_hearts[:6])
+            used_any_from_specific = min(needed_any, have_any_from_specific)
+
+            # 3. Match Any with Any
+            needed_any -= used_any_from_specific
+            have_wild = temp_hearts[6]
+            used_wild = min(needed_any, have_wild)
+
+            met = np.all(remaining_req[:6] == 0) and (needed_any - used_wild <= 0)
+
+            lives.append(
+                {
+                    "name": live_card.name,
+                    "img": live_card.img_path,
+                    "score": int(live_card.score),
+                    "req": req.tolist(),
+                    "passed": bool(met),
+                    "reason": "" if met else "Not met",
+                    "base_score": int(live_card.score),
+                    "bonus_score": self.live_score_bonus,
+                }
+            )
+
+        return {
+            "can_perform": True,
+            "total_blades": int(total_blades),
+            "total_hearts": total_hearts.tolist(),
+            "lives": lives,
+            "breakdown": {
+                "blades": blade_breakdown,
+                "hearts": heart_breakdown,
+                "requirements": req_breakdown,
+                "transforms": transform_log,
+            },
+        }
+
+    def get_member_cost(self, card_id: int, card_db: Dict[int, MemberCard]) -> int:
+        """
+        Calculate effective cost of a member card in hand.
+        """
+        from engine.game.state_utils import get_base_id
+
+        base_id = get_base_id(card_id)
+        if base_id not in card_db:
+            return 0
+
+        member = card_db[base_id]
+        cost = member.cost
+
+        # Apply global cost reduction effects
+        total_reduction = 0
+        for ce in self.continuous_effects:
+            if ce["effect"].effect_type == EffectType.REDUCE_COST:
+                total_reduction += ce["effect"].value
+
+        # Q129: Apply card's OWN constant abilities if they reduce cost in hand.
+        for ab in member.abilities:
+            if ab.trigger == TriggerType.CONSTANT:
+                for eff in ab.effects:
+                    if eff.effect_type == EffectType.REDUCE_COST and eff.target == TargetType.SELF:
+                        conditions_met = True
+                        for cond in ab.conditions:
+                            if not self._check_condition_for_constant(cond, slot_idx=-1, card_db=card_db):
+                                conditions_met = False
+                                break
+
+                        if conditions_met:
+                            val = eff.value
+                            if eff.params.get("multiplier") and eff.params.get("per_hand_other"):
+                                count = max(0, len(self.hand) - 1)
+                                val *= count
+                            total_reduction += val
+
+        return max(0, cost - total_reduction)
+
+    def to_dict(self, viewer_idx=0):
+        # We now have StateMixin.to_dict() but we might want this custom one for the UI.
+        # Actually, let's just use StateMixin.to_dict and enrich it if needed in serializer.py.
+        # This keeps PlayerState purely about state.
+        return super().to_dict()

engine/game/replay_manager.py

@@ -0,0 +1,302 @@
+import random
+from typing import Any, Dict, List, Optional
+
+from engine.game.game_state import GameState
+from engine.game.serializer import serialize_state
+
+try:
+    from engine.game.state_utils import create_uid
+except ImportError:
+    # Fallback if state_utils was deleted (it shouldn't have been, but just in case)
+    # Reimplement create_uid if needed, or fix the file location
+    BASE_ID_MASK = 0xFFFFF
+    INSTANCE_SHIFT = 20
+
+    def create_uid(base_id: int, instance_index: int) -> int:
+        return (base_id & BASE_ID_MASK) | (instance_index << INSTANCE_SHIFT)
+
+
+def optimize_history(
+    history: List[Dict[str, Any]],
+    member_db: Dict[int, Any],
+    live_db: Dict[int, Any],
+    energy_db: Dict[int, Any],
+    exclude_db_cards: bool = True,
+    seed: Optional[int] = None,
+    action_log: Optional[List[int]] = None,
+    deck_info: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """
+    Optimize replay history.
+    Args:
+        history: List of states
+        member_db: Database of member cards
+        live_db: Database of live cards
+        energy_db: Database of energy cards
+        exclude_db_cards: Use DB-backed optimization (Level 2)
+        seed: Random seed (Level 3)
+        action_log: List of action IDs (Level 3)
+        deck_info: Dict with 'p0_deck', 'p1_deck', etc. (Level 3)
+    """
+    # Level 3: Action-Based Replay (Max Compression)
+    if seed is not None and action_log is not None and deck_info is not None:
+        return {
+            "level": 3,
+            "seed": seed,
+            "decks": deck_info,
+            "action_log": action_log,
+            # We don't save 'states' or 'registry' at all!
+        }
+
+    # Level 2: State-Based DB-Backed
+    registry = {}
+
+    def extract_static_data(card_data):
+        """Extract static fields that don't change during gameplay."""
+        if not isinstance(card_data, dict):
+            return {}
+
+        # known static fields
+        static_fields = [
+            "name",
+            "card_no",
+            "type",
+            "cost",
+            "blade",
+            "img",
+            "hearts",
+            "blade_hearts",
+            "text",
+            "score",
+            "required_hearts",
+        ]
+
+        return {k: card_data[k] for k in static_fields if k in card_data}
+
+    def optimize_object(obj):
+        """recursively traverse and optimize payload."""
+        if isinstance(obj, list):
+            return [optimize_object(x) for x in obj]
+        elif isinstance(obj, dict):
+            # Check if this object looks like a serialized card
+            if "id" in obj and ("name" in obj or "type" in obj):
+                cid = obj["id"]
+                # If it's a known card (positive ID), register it
+                if isinstance(cid, int) and cid >= 0:
+                    is_in_db = cid in member_db or cid in live_db or cid in energy_db
+
+                    # Decide whether to add to registry
+                    should_register = False
+                    if not is_in_db:
+                        should_register = True
+                    elif not exclude_db_cards:
+                        should_register = True
+
+                    if should_register:
+                        if cid not in registry:
+                            registry[cid] = extract_static_data(obj)
+
+                        # Return ONLY dynamic data + ID reference
+                        dynamic_data = {"id": cid}
+                        static_keys = registry[cid].keys()
+                        for k, v in obj.items():
+                            if k not in static_keys and k != "id":
+                                dynamic_data[k] = optimize_object(v)
+                        return dynamic_data
+
+                    elif is_in_db:
+                        # IT IS IN DB and we exclude it from registry
+                        # We still strip static data, but we don't save it to file
+                        # effectively assuming "registry[cid]" exists implicitly in DB
+
+                        # We need to know which keys are static to strip them
+                        # We can use a representative static extraction
+                        static_keys = extract_static_data(obj).keys()
+
+                        dynamic_data = {"id": cid}
+                        for k, v in obj.items():
+                            if k not in static_keys and k != "id":
+                                dynamic_data[k] = optimize_object(v)
+                        return dynamic_data
+
+            # Regular dict recursion
+            return {k: optimize_object(v) for k, v in obj.items()}
+        else:
+            return obj
+
+    optimized_states = optimize_object(history)
+
+    return {"registry": registry, "states": optimized_states}
+
+
+def inflate_history(
+    optimized_data: Dict[str, Any],
+    member_db: Dict[int, Any],
+    live_db: Dict[int, Any],
+    energy_db: Dict[int, Any],
+) -> List[Dict[str, Any]]:
+    """
+    Reconstruct full history state from optimized data using server DB.
+    """
+    # Level 3 Inflation (Action Log -> State History)
+    if optimized_data.get("level") == 3 or "action_log" in optimized_data:
+        print("Inflating Level 3 Action Log replay...")
+        action_log = optimized_data.get("action_log", [])
+        seed = optimized_data.get("seed", 0)
+        deck_info = optimized_data.get("decks", {})
+
+        # 1. Reset Game with Seed
+        # Use local random instance to avoid messing with global random state if possible,
+        # but GameState uses random module globally.
+        # We must save and restore random state if we want to be clean, but python random is global.
+        # Ideally GameState should use a random instance.
+        # For now, we assume the caller handles global state implications or we just reset seed.
+
+        # NOTE: This modifies global random state!
+        random.seed(seed)
+
+        # 2. Init Game State (Headless)
+        GameState.member_db = member_db
+        GameState.live_db = live_db
+        # Energy DB is not static on GameState?
+        GameState.energy_db = energy_db  # server.py sets this on instance or class?
+        # server.py says: GameState.energy_db = energy_db
+
+        # Create fresh state
+        temp_gs = GameState()
+        temp_gs.initialize_game()
+
+        # Set decks if available
+        if deck_info:
+            p0_deck = deck_info.get("p0_deck")
+            p1_deck = deck_info.get("p1_deck")
+
+            if p0_deck and len(p0_deck) > 0:
+                print(f"Loading custom deck for P0: {len(p0_deck)} cards")
+                p0 = temp_gs.players[0]
+                # Reset Deck & Hand
+                p0.main_deck = [int(x) for x in p0_deck]
+                p0.hand = []
+                p0.discard = []
+                # Draw initial hand (5 cards)
+                draw_count = min(5, len(p0.main_deck))
+                p0.hand = p0.main_deck[:draw_count]
+                p0.hand_added_turn = [1] * draw_count
+                p0.main_deck = p0.main_deck[draw_count:]
+
+            if p1_deck and len(p1_deck) > 0:
+                print(f"Loading custom deck for P1: {len(p1_deck)} cards")
+                p1 = temp_gs.players[1]
+                p1.main_deck = [int(x) for x in p1_deck]
+                p1.hand = []
+                p1.discard = []
+                draw_count = min(5, len(p1.main_deck))
+                p1.hand = p1.main_deck[:draw_count]
+                p1.hand_added_turn = [1] * draw_count
+                p1.main_deck = p1.main_deck[draw_count:]
+
+        reconstructed_history = []
+
+        # 3. Serialize Initial State
+        reconstructed_history.append(serialize_state(temp_gs))
+
+        # 4. Replay Actions
+        for action_id in action_log:
+            temp_gs.step(action_id)
+            reconstructed_history.append(serialize_state(temp_gs))
+
+        print(f"Reconstructed {len(reconstructed_history)} frames from {len(action_log)} actions.")
+        return reconstructed_history
+
+    # Level 2 Logic (State Inflation)
+    registry = optimized_data.get("registry", {})
+    states = optimized_data.get("states", [])
+
+    def get_static_data(cid):
+        """Get static data from Registry OR Database"""
+        # 1. Registry (Custom cards / Legacy format)
+        if str(cid) in registry:
+            return registry[str(cid)]
+        if cid in registry:
+            return registry[cid]
+
+        # 2. Database
+        if cid in member_db:
+            m = member_db[cid]
+            # Reconstruct dictionary from object
+            ability_text = getattr(m, "ability_text", "")
+            if hasattr(m, "abilities") and m.abilities:
+                # Use raw Japanese text
+                # Clean wiki markup: {{icon.png|Text}} -> Text, [[Link|Text]] -> Text
+                import re
+
+                def clean_text(text):
+                    text = re.sub(r"\{\{.*?\|(.*?)\}\}", r"\1", text)  # {{icon|Text}} -> Text
+                    text = re.sub(r"\[\[.*?\|(.*?)\]\]", r"\1", text)  # [[Link|Text]] -> Text
+                    return text
+
+                ability_lines = [clean_text(ab.raw_text) for ab in m.abilities]
+                ability_text = "\n".join(ability_lines)
+
+            return {
+                "name": m.name,
+                "card_no": m.card_no,
+                "type": "member",
+                "cost": m.cost,
+                "blade": m.blades,
+                "img": m.img_path,
+                "hearts": m.hearts.tolist(),
+                "blade_hearts": m.blade_hearts.tolist(),
+                "text": ability_text,
+                "color": "Unknown",
+            }
+        elif cid in live_db:
+            l = live_db[cid]
+            ability_text = getattr(l, "ability_text", "")
+            if hasattr(l, "abilities") and l.abilities:
+                import re
+
+                def clean_text(text):
+                    text = re.sub(r"\{\{.*?\|(.*?)\}\}", r"\1", text)
+                    text = re.sub(r"\[\[.*?\|(.*?)\]\]", r"\1", text)
+                    return text
+
+                ability_lines = [clean_text(ab.raw_text) for ab in l.abilities]
+                ability_text = "\n".join(ability_lines)
+
+            return {
+                "name": l.name,
+                "card_no": l.card_no,
+                "type": "live",
+                "score": l.score,
+                "img": l.img_path,
+                "required_hearts": l.required_hearts.tolist(),
+                "text": ability_text,
+            }
+        elif cid in energy_db:
+            # EnergyCard is simple (just ID), so we hardcode display info
+            return {"name": "Energy", "type": "energy", "img": "assets/energy_card.png"}
+
+        return None
+
+    def inflate_object(obj):
+        if isinstance(obj, list):
+            return [inflate_object(x) for x in obj]
+        elif isinstance(obj, dict):
+            # Check for ID reference to inflate
+            if "id" in obj:
+                cid = obj["id"]
+                static_data = get_static_data(cid)
+                if static_data:
+                    # Merge static data into this object (dynamic overrides static if conflict, though shouldn't happen)
+                    # We create a new dict to Avoid mutating the source if it's reused
+                    new_obj = static_data.copy()
+                    for k, v in obj.items():
+                        new_obj[k] = inflate_object(v)
+                    return new_obj
+
+            return {k: inflate_object(v) for k, v in obj.items()}
+        else:
+            return obj
+
+    return inflate_object(states)

engine/game/serializer.py

@@ -0,0 +1,689 @@
+import json
+
+from engine.game.desc_utils import get_action_desc
+from engine.game.state_utils import get_base_id
+from engine.models.ability import EFFECT_DESCRIPTIONS, EffectType, TriggerType
+
+
+def format_effect_description(effect):
+    # Logic copied/adapted from effect_mixin.py
+    template = EFFECT_DESCRIPTIONS.get(effect.effect_type, getattr(effect.effect_type, "name", str(effect.effect_type)))
+    context = effect.params.copy()
+    context["value"] = effect.value
+
+    # Custom overrides if needed (e.g. REDUCE_HEART_REQ)
+    if effect.effect_type == EffectType.REDUCE_HEART_REQ:
+        if effect.value < 0:
+            return f"Reduce Heart Requirement by {abs(effect.value)}"
+        else:
+            return f"Increase Heart Requirement by {effect.value}"
+
+    try:
+        desc = template.format(**context)
+    except KeyError:
+        desc = template
+
+    # Add contextual suffixes
+    if effect.params.get("per_energy"):
+        desc += " per Energy"
+    if effect.params.get("per_member"):
+        desc += " per Member"
+    if effect.params.get("per_live"):
+        desc += " per Live"
+
+    return desc
+
+
+def get_card_modifiers(player, slot_idx, card_id, member_db, live_db):
+    modifiers = []
+
+    # 0. Player Level Restrictions (Virtual Modifiers)
+    if player.cannot_live:
+        modifiers.append({"description": "Cannot perform Live this turn", "source": "Game Rule", "expiry": "LIVE_END"})
+
+    # 1. Continuous Effects
+    for ce in player.continuous_effects:
+        target_slot = ce.get("target_slot", -1)
+        eff = ce["effect"]
+
+        # Determine relevance:
+        # - member on stage (slot_idx >= 0): matches target_slot or target_slot is -1
+        # - live card (slot_idx == -1): matches global effects or live-specific effects
+        is_relevant = False
+        if slot_idx >= 0:
+            if target_slot == -1 or target_slot == slot_idx:
+                is_relevant = True
+        else:
+            # For live cards/others, only show global or relevant types
+            if target_slot == -1 or eff.effect_type in (EffectType.REDUCE_HEART_REQ, EffectType.MODIFY_SCORE_RULE):
+                is_relevant = True
+
+        if is_relevant:
+            desc = format_effect_description(eff)
+
+            # Resolve Source
+            source_name = "Effect"
+            sid = ce.get("source_card_id")
+            if sid is not None:
+                base_sid = get_base_id(int(sid))
+                if base_sid in member_db:
+                    source_name = member_db[base_sid].name
+                elif base_sid in live_db:
+                    source_name = live_db[base_sid].name
+
+            modifiers.append({"description": desc, "source": source_name, "expiry": ce.get("expiry", "TURN_END")})
+
+    # 2. Intrinsic Constant Abilities
+    base_cid = get_base_id(int(card_id))
+    db = member_db if base_cid in member_db else live_db if base_cid in live_db else None
+
+    if db and base_cid in db:
+        card = db[base_cid]
+        if hasattr(card, "abilities"):
+            for ab in card.abilities:
+                if ab.trigger == TriggerType.CONSTANT:
+                    # Check conditions
+                    # Note: _check_condition_for_constant might not be available on card/db,
+                    # but we assume the environment has it or fallback to True for display
+                    # Serializer is often called without full GameState context for individual cards
+                    # but here we have 'player'.
+                    try:
+                        if all(player._check_condition_for_constant(cond, slot_idx) for cond in ab.conditions):
+                            for eff in ab.effects:
+                                desc = format_effect_description(eff)
+                                modifiers.append({"description": desc, "source": "Self", "expiry": "CONSTANT"})
+                    except (AttributeError, TypeError):
+                        # Fallback: display constant if it exists but condition check is impossible
+                        for eff in ab.effects:
+                            desc = format_effect_description(eff)
+                            modifiers.append({"description": desc, "source": "Self", "expiry": "CONSTANT"})
+
+    return modifiers
+
+
+def serialize_card(cid, member_db, live_db, energy_db, is_viewable=True, peek=False):
+    if not is_viewable and not peek:
+        return {"id": int(cid), "name": "???", "type": "unknown", "img": "cards/back.png", "hidden": True}
+
+    card_data = {}
+
+    # Try direct lookup, then fallback to base ID for unique IDs
+    base_cid = get_base_id(int(cid))
+
+    if base_cid in member_db:
+        m = member_db[base_cid]
+        ability_text = getattr(m, "ability_text", "")
+
+        # Only reconstruct if no rich text is available
+        if not ability_text and hasattr(m, "abilities") and m.abilities:
+            ability_lines = []
+            for ab in m.abilities:
+                trigger_icon = {
+                    TriggerType.ACTIVATED: "【起動】",
+                    TriggerType.ON_PLAY: "【登場】",
+                    TriggerType.CONSTANT: "【常時】",
+                    TriggerType.ON_LIVE_START: "【ライブ開始】",
+                    TriggerType.ON_LIVE_SUCCESS: "【ライブ成功時】",
+                }.get(ab.trigger, "【自動】")
+                ability_lines.append(f"{trigger_icon} {ab.raw_text}")
+            ability_text = "\n".join(ability_lines)
+
+        card_data = {
+            "id": int(cid),  # Keep original ID (UID) for frontend tracking
+            "card_no": m.card_no,
+            "name": m.name,
+            "type": "member",
+            "cost": m.cost,
+            "blade": m.blades,
+            "img": m.img_path,
+            "hearts": m.hearts.tolist() if hasattr(m.hearts, "tolist") else list(m.hearts),
+            "blade_hearts": m.blade_hearts.tolist() if hasattr(m.blade_hearts, "tolist") else list(m.blade_hearts),
+            "text": ability_text,
+            "original_text": getattr(m, "original_text", ""),
+        }
+    elif base_cid in live_db:
+        l = live_db[base_cid]
+        ability_text = getattr(l, "ability_text", "")
+
+        # Only reconstruct if no rich text is available
+        if not ability_text and hasattr(l, "abilities") and l.abilities:
+            ability_lines = []
+            for ab in l.abilities:
+                trigger_icon = {TriggerType.ON_LIVE_START: "【ライブ開始】"}.get(ab.trigger, "【自動】")
+                ability_lines.append(f"{trigger_icon} {ab.raw_text}")
+            ability_text = "\n".join(ability_lines)
+
+        card_data = {
+            "id": int(cid),
+            "card_no": l.card_no,
+            "name": l.name,
+            "type": "live",
+            "score": l.score,
+            "img": l.img_path,
+            "required_hearts": l.required_hearts.tolist()
+            if hasattr(l.required_hearts, "tolist")
+            else list(l.required_hearts),
+            "text": ability_text,
+            "original_text": getattr(l, "original_text", ""),
+        }
+    elif base_cid in energy_db:
+        e = energy_db[base_cid]
+        card_data = {
+            "id": int(cid),
+            "card_no": getattr(e, "card_no", "ENERGY"),
+            "name": getattr(e, "name", "Energy"),
+            "type": "energy",
+            "img": getattr(e, "img_path", "assets/energy_card.png"),
+        }
+    else:
+        return {"id": int(cid), "name": f"Card {cid}", "type": "unknown", "img": None}
+
+    if not is_viewable and peek:
+        card_data["hidden"] = True
+        card_data["face_down"] = True
+
+    return card_data
+
+
+def serialize_player(p, game_state, player_idx, viewer_idx=0, is_viewable=True):
+    member_db = game_state.member_db
+    live_db = game_state.live_db
+    energy_db = getattr(game_state, "energy_db", {})
+    legal_mask = game_state.get_legal_actions()
+
+    expected_yells = 0
+    for i, card_id in enumerate(p.stage):
+        if card_id >= 0 and not p.tapped_members[i]:
+            base_cid = get_base_id(int(card_id))
+            if base_cid in member_db:
+                expected_yells += member_db[base_cid].blades
+
+    hand = []
+    for i, cid in enumerate(p.hand):
+        if is_viewable:
+            c = serialize_card(cid, member_db, live_db, energy_db)
+            is_new = False
+            if hasattr(p, "hand_added_turn") and i < len(p.hand_added_turn):
+                is_new = p.hand_added_turn[i] == game_state.turn_number
+            c["is_new"] = is_new
+
+            valid_actions = []
+            for area in range(3):
+                aid = 1 + i * 3 + area
+                if aid < len(legal_mask) and legal_mask[aid]:
+                    valid_actions.append(aid)
+            for aid in [400 + i, 300 + i, 500 + i]:
+                if aid < len(legal_mask) and legal_mask[aid]:
+                    valid_actions.append(aid)
+            c["valid_actions"] = valid_actions
+            hand.append(c)
+        else:
+            hand.append(serialize_card(cid, member_db, live_db, energy_db, is_viewable=False))
+
+    stage = []
+    for i, _ in enumerate(range(3)):
+        # Correctly access stage by index
+        cid = int(p.stage[i])
+        if cid >= 0:
+            c = serialize_card(cid, member_db, live_db, energy_db)
+            c["tapped"] = bool(p.tapped_members[i])
+            c["energy"] = int(p.stage_energy_count[i])
+            c["locked"] = bool(p.members_played_this_turn[i])
+
+            # Add modifiers
+            c["modifiers"] = get_card_modifiers(p, i, cid, member_db, live_db)
+
+            stage.append(c)
+        else:
+            stage.append(None)
+
+    discard = [serialize_card(cid, member_db, live_db, energy_db, is_viewable=True) for cid in p.discard]
+
+    energy = []
+    for i, cid in enumerate(p.energy_zone):
+        energy.append(
+            {
+                "id": i,
+                "tapped": bool(p.tapped_energy[i]),
+                "card": serialize_card(cid, member_db, live_db, energy_db, is_viewable=False),
+            }
+        )
+
+    # Calculate total hearts and blades for the player
+    total_blades = p.get_total_blades(member_db)
+    total_hearts = p.get_total_hearts(member_db)  # Returns np.array(7)
+
+    # Track remaining hearts for live fulfillment calculation (Greedy allocation)
+    temp_hearts = total_hearts.copy()
+
+    live_zone = []
+    for i, cid in enumerate(p.live_zone):
+        is_revealed = bool(p.live_zone_revealed[i]) if i < len(p.live_zone_revealed) else False
+        card_obj = serialize_card(
+            cid, member_db, live_db, energy_db, is_viewable=is_revealed, peek=(player_idx == viewer_idx)
+        )
+
+        # Calculate heart progress for this live card
+        if cid in live_db:
+            l = live_db[cid]
+            req = l.required_hearts  # np.array
+            filled = [0] * 7
+
+            if is_revealed or (player_idx == viewer_idx):
+                # Greedy fill logic matching PlayerState.get_performance_guide
+                # Colors 0-5
+                for c_idx in range(6):
+                    have = temp_hearts[c_idx]
+                    need = req[c_idx]
+                    take = min(have, need)
+                    filled[c_idx] = int(take)
+                    temp_hearts[c_idx] -= take
+
+                # Any Color (Index 6)
+                req_any = req[6] if len(req) > 6 else 0
+                remaining_total = sum(temp_hearts[:6]) + temp_hearts[6]
+                take_any = min(remaining_total, req_any)
+                filled[6] = int(take_any)
+                # Note: We don't subtract from temp_hearts for 'any' because strict color matching is done,
+                # and 'any' sucks from the pool of remaining.
+                # But to be strictly correct for *subsequent* cards (if we supported multiple approvals at once),
+                # we should decrement. But the game usually checks one at a time or order matters.
+                # Use the logic from get_performance_guide:
+                # It doesn't actually decrement 'any' from specific colors in temp_hearts
+                # because 'any' is a wildcard check on the *sum*.
+                # Wait, get_performance_guide does:
+                # remaining_total = np.sum(temp_hearts[:6]) + temp_hearts[6]
+
+                card_obj["required_hearts"] = req.tolist()
+                card_obj["filled_hearts"] = filled
+
+                # Determine passed status
+                is_passed = True
+                for c_idx in range(6):
+                    if filled[c_idx] < req[c_idx]:
+                        is_passed = False
+                if filled[6] < req[6]:
+                    is_passed = False
+
+                card_obj["is_cleared"] = is_passed
+
+            # Add modifiers for live card (e.g. requirement reduction)
+            card_obj["modifiers"] = get_card_modifiers(p, -1, cid, member_db, live_db)
+
+        live_zone.append(card_obj)
+
+    score = sum(live_db[cid].score for cid in p.success_lives if cid in live_db)
+
+    return {
+        "player_id": p.player_id,
+        "score": score,
+        "is_active": (game_state.current_player == player_idx),
+        "hand": hand,
+        "hand_count": len(p.hand),
+        "mulligan_selection": list(p.mulligan_selection) if is_viewable else [],
+        "deck_count": len(p.main_deck),
+        "energy_deck_count": len(p.energy_deck),
+        "discard": discard,
+        "discard_count": len(p.discard),
+        "energy": energy,
+        "energy_count": len(p.energy_zone),
+        "energy_untapped": int(p.count_untapped_energy()),
+        "live_zone": live_zone,
+        "live_zone_count": len(p.live_zone),
+        "stage": stage,
+        "success_lives": [serialize_card(cid, member_db, live_db, energy_db, is_viewable) for cid in p.success_lives],
+        "restrictions": list(p.restrictions),
+        "expected_yells": expected_yells,
+        "total_hearts": total_hearts.tolist(),
+        "total_blades": int(total_blades),
+        "hand_costs": [p.get_member_cost(cid, member_db) if cid in member_db else 0 for cid in p.hand],
+        "active_effects": [
+            {
+                "description": format_effect_description(ce["effect"]),
+                "source": (
+                    member_db[get_base_id(int(ce["source_card_id"]))].name
+                    if ce.get("source_card_id") is not None and get_base_id(int(ce["source_card_id"])) in member_db
+                    else live_db[get_base_id(int(ce["source_card_id"]))].name
+                    if ce.get("source_card_id") is not None and get_base_id(int(ce["source_card_id"])) in live_db
+                    else "Effect"
+                ),
+                "expiry": ce.get("expiry", "TURN_END"),
+                "source_card_id": int(ce.get("source_card_id", -1)) if ce.get("source_card_id") is not None else -1,
+            }
+            for ce in p.continuous_effects
+        ],
+    }
+
+
+def serialize_state(gs, viewer_idx=0, is_pvp=False, mode="pve"):
+    active_idx = gs.current_player
+    legal_mask = gs.get_legal_actions()
+    legal_actions = []
+    p = gs.active_player
+    member_db = gs.member_db
+    live_db = gs.live_db
+    energy_db = getattr(gs, "energy_db", {})
+
+    # Only populate legal actions if it is the viewer's turn, or if in PvP/Hotseat mode (show all)
+    show_actions = is_pvp or (viewer_idx == active_idx)
+
+    if show_actions:
+        for i, v in enumerate(legal_mask):
+            if v:
+                desc = get_action_desc(i, gs)
+                meta = {"id": i, "desc": desc, "name": desc, "description": desc}
+
+                # Enrich with metadata for UI
+                if 1 <= i <= 180:
+                    meta["type"] = "PLAY"
+                    meta["hand_idx"] = (i - 1) // 3
+                    meta["area_idx"] = (i - 1) % 3
+                    if meta["hand_idx"] < len(p.hand):
+                        cid = p.hand[meta["hand_idx"]]
+                        c = serialize_card(cid, member_db, live_db, energy_db)
+                        hand_cost = p.get_member_cost(cid, member_db)
+                        # Baton Touch Reduction (Rule 12)
+                        net_cost = hand_cost
+                        if p.stage[meta["area_idx"]] >= 0:
+                            old_cid = get_base_id(int(p.stage[meta["area_idx"]]))
+                            if old_cid in member_db:
+                                net_cost = max(0, hand_cost - member_db[old_cid].cost)
+
+                        meta.update(
+                            {
+                                "img": c["img"],
+                                "name": c["name"],
+                                "cost": int(net_cost),
+                                "base_cost": int(hand_cost),
+                                "card_no": c.get("card_no", "???"),
+                                "text": c.get("text", ""),
+                            }
+                        )
+                        if cid in member_db:
+                            meta["triggers"] = [ab.trigger for ab in member_db[cid].abilities]
+                elif 200 <= i <= 202:
+                    meta["type"] = "ABILITY"
+                    meta["area_idx"] = i - 200
+                    cid = p.stage[meta["area_idx"]]
+                    if cid >= 0:
+                        c = serialize_card(cid, member_db, live_db, energy_db)
+                        meta.update(
+                            {"img": c["img"], "name": c["name"], "text": c.get("text", ""), "source_card_id": int(cid)}
+                        )
+                elif 300 <= i <= 359:
+                    meta["type"] = "MULLIGAN"
+                    meta["hand_idx"] = i - 300
+                elif 400 <= i <= 459:
+                    meta["type"] = "LIVE_SET"
+                    meta["hand_idx"] = i - 400
+                elif 500 <= i <= 559:
+                    meta["type"] = "SELECT_HAND"
+                    meta["hand_idx"] = i - 500
+                    target_p_idx = active_idx
+                    if gs.pending_choices:
+                        target_p_idx = gs.pending_choices[0][1].get("player_id", active_idx)
+                    meta["player_id"] = target_p_idx
+                    target_p = gs.players[target_p_idx]
+                    if meta["hand_idx"] < len(target_p.hand):
+                        cid = target_p.hand[meta["hand_idx"]]
+                        c = serialize_card(cid, member_db, live_db, energy_db)
+                        meta.update(
+                            {"img": c["img"], "name": c["name"], "text": c.get("text", ""), "source_card_id": int(cid)}
+                        )
+                elif 560 <= i <= 562:
+                    meta["type"] = "SELECT_STAGE"
+                    meta["area_idx"] = i - 560
+                    target_p_idx = active_idx
+                    if gs.pending_choices:
+                        target_p_idx = gs.pending_choices[0][1].get("player_id", active_idx)
+                    meta["player_id"] = target_p_idx
+                    target_p = gs.players[target_p_idx]
+                    cid = target_p.stage[meta["area_idx"]]
+                    if cid >= 0:
+                        c = serialize_card(cid, member_db, live_db, energy_db)
+                        meta.update(
+                            {"img": c["img"], "name": c["name"], "text": c.get("text", ""), "source_card_id": int(cid)}
+                        )
+                elif 590 <= i <= 599:
+                    meta["type"] = "ABILITY_TRIGGER"
+                    meta["index"] = i - 590
+                elif 600 <= i <= 659:
+                    meta["type"] = "SELECT"
+                    meta["index"] = i - 600
+                    if gs.pending_choices:
+                        ctype, cparams = gs.pending_choices[0]
+                        if ctype == "TARGET_OPPONENT_MEMBER":
+                            opp = gs.inactive_player
+                            meta["player_id"] = opp.player_id
+                            if meta["index"] < 3:
+                                cid = opp.stage[meta["index"]]
+                                if cid >= 0:
+                                    c = serialize_card(cid, member_db, live_db, energy_db)
+                                    meta.update(
+                                        {
+                                            "img": c["img"],
+                                            "name": c["name"],
+                                            "text": c.get("text", ""),
+                                            "source_card_id": int(cid),
+                                        }
+                                    )
+                        elif ctype == "SELECT_FROM_LIST" or ctype == "SELECT_SUCCESS_LIVE":
+                            cards = cparams.get("cards", [])
+                            if meta["index"] < len(cards):
+                                cid = cards[meta["index"]]
+                                c = serialize_card(cid, member_db, live_db, energy_db)
+                                meta.update(
+                                    {
+                                        "img": c["img"],
+                                        "name": c["name"],
+                                        "text": c.get("text", ""),
+                                        "source_card_id": int(cid),
+                                    }
+                                )
+                elif 660 <= i <= 719:
+                    meta["type"] = "SELECT_DISCARD"
+                    meta["index"] = i - 660
+                    if gs.pending_choices:
+                        ctype, cparams = gs.pending_choices[0]
+                        if ctype == "SELECT_FROM_DISCARD":
+                            cards = cparams.get("cards", [])
+                            if meta["index"] < len(cards):
+                                cid = cards[meta["index"]]
+                                c = serialize_card(cid, member_db, live_db, energy_db)
+                                meta.update(
+                                    {
+                                        "img": c["img"],
+                                        "name": c["name"],
+                                        "text": c.get("text", ""),
+                                        "source_card_id": int(cid),
+                                    }
+                                )
+
+                elif 570 <= i <= 579:
+                    meta["type"] = "SELECT_MODE"
+                    meta["index"] = i - 570
+                    if gs.pending_choices:
+                        ctype, cparams = gs.pending_choices[0]
+                        if ctype == "MODAL" or ctype == "SELECT_MODE":
+                            options = cparams.get("options", [])
+                            if meta["index"] < len(options):
+                                opt = options[meta["index"]]
+                                # Option can be string or list/dict
+                                desc = str(opt)
+                                if isinstance(opt, (list, tuple)) and len(opt) > 0:
+                                    desc = str(opt[0])  # Crude fallback
+                                meta["text"] = desc
+                                meta["name"] = desc
+                elif 580 <= i <= 589:
+                    meta["type"] = "COLOR_SELECT"
+                    meta["index"] = i - 580
+                    colors = ["Pink", "Red", "Yellow", "Green", "Blue", "Purple", "All", "None"]
+                    if meta["index"] < len(colors):
+                        meta["color"] = colors[meta["index"]]
+                        meta["name"] = colors[meta["index"]]
+                elif 720 <= i <= 759:
+                    meta["type"] = "SELECT_FORMATION"
+                    meta["index"] = i - 720
+                    if gs.pending_choices:
+                        ctype, cparams = gs.pending_choices[0]
+                        cards = cparams.get("cards", cparams.get("available_members", []))
+                        if meta["index"] < len(cards):
+                            cid = cards[meta["index"]]
+                            c = serialize_card(cid, member_db, live_db, energy_db)
+                            meta.update(
+                                {
+                                    "img": c["img"],
+                                    "name": c["name"],
+                                    "text": c.get("text", ""),
+                                    "source_card_id": int(cid),
+                                }
+                            )
+                elif 760 <= i <= 819:
+                    meta["type"] = "SELECT_SUCCESS_LIVE"
+                    meta["index"] = i - 760
+                    # Usually points to p.success_lives
+                    target_p_idx = active_idx
+                    if gs.pending_choices:
+                        ctype, cparams = gs.pending_choices[0]
+                        target_p_idx = cparams.get("player_id", active_idx)
+                    target_p = gs.players[target_p_idx]
+
+                    # If specific cards list provided in params, use that
+                    cards = []
+                    if gs.pending_choices:
+                        _, cparams = gs.pending_choices[0]
+                        cards = cparams.get("cards", [])
+
+                    if not cards:
+                        cards = target_p.success_lives
+
+                    if meta["index"] < len(cards):
+                        cid = cards[meta["index"]]
+                        c = serialize_card(cid, member_db, live_db, energy_db)
+                        meta.update(
+                            {
+                                "img": c["img"],
+                                "name": c["name"],
+                                "text": c.get("text", ""),
+                                "source_card_id": int(cid),
+                            }
+                        )
+                elif 820 <= i <= 829:
+                    meta["type"] = "TARGET_LIVE"
+                    meta["index"] = i - 820
+                    target_p_idx = active_idx
+                    if gs.pending_choices:
+                        _, cparams = gs.pending_choices[0]
+                        target_p_idx = cparams.get("player_id", active_idx)
+                    target_p = gs.players[target_p_idx]
+                    if meta["index"] < len(target_p.live_zone):
+                        cid = target_p.live_zone[meta["index"]]
+                        c = serialize_card(cid, member_db, live_db, energy_db)
+                        meta.update(
+                            {
+                                "img": c["img"],
+                                "name": c["name"],
+                                "text": c.get("text", ""),
+                                "source_card_id": int(cid),
+                            }
+                        )
+                elif 830 <= i <= 849:
+                    meta["type"] = "TARGET_ENERGY"
+                    meta["index"] = i - 830
+                    target_p_idx = active_idx
+                    if gs.pending_choices:
+                        _, cparams = gs.pending_choices[0]
+                        target_p_idx = cparams.get("player_id", active_idx)
+                    target_p = gs.players[target_p_idx]
+                    if meta["index"] < len(target_p.energy_zone):
+                        cid = target_p.energy_zone[meta["index"]]
+                        c = serialize_card(cid, member_db, live_db, energy_db)
+                        meta.update(
+                            {
+                                "img": c["img"],
+                                "name": c["name"],
+                                "text": c.get("text", ""),
+                                "source_card_id": int(cid),
+                            }
+                        )
+                elif 850 <= i <= 909:
+                    meta["type"] = "TARGET_REMOVED"
+                    meta["index"] = i - 850
+                    # Assuming removed_cards is on GameState
+                    removed = getattr(gs, "removed_cards", [])
+                    if meta["index"] < len(removed):
+                        cid = removed[meta["index"]]
+                        c = serialize_card(cid, member_db, live_db, energy_db)
+                        meta.update(
+                            {
+                                "img": c["img"],
+                                "name": c["name"],
+                                "text": c.get("text", ""),
+                                "source_card_id": int(cid),
+                            }
+                        )
+
+                legal_actions.append(meta)
+
+    pending_choice = None
+    if gs.pending_choices:
+        choice_type, params_raw = gs.pending_choices[0]
+        try:
+            params = json.loads(params_raw) if isinstance(params_raw, str) else params_raw
+        except:
+            params = {}
+
+        # Resolve Source Card Details
+        source_name = params.get("source_member", "Unknown")
+        source_img = None
+        source_id = params.get("source_card_id")
+
+        if source_id is not None:
+            if source_id in member_db:
+                m = member_db[source_id]
+                source_name = m.name
+                source_img = m.img_path
+            elif source_id in live_db:
+                l = live_db[source_id]
+                source_name = l.name
+                source_img = l.img_path
+
+        pending_choice = {
+            "type": choice_type,
+            "description": params.get("effect_description", ""),
+            "source_ability": params.get("source_ability", ""),
+            "source_member": source_name,
+            "source_img": source_img,
+            "source_card_id": int(source_id) if source_id is not None else -1,
+            "is_optional": params.get("is_optional", False),
+            "params": params,
+        }
+
+    # FINAL CHECK: Correctly indented return statement
+    return {
+        "turn": gs.turn_number,
+        "phase": int(gs.phase),
+        "active_player": int(active_idx),
+        "game_over": gs.game_over,
+        "winner": gs.winner,
+        "mode": mode,
+        "is_pvp": is_pvp,
+        "players": [
+            serialize_player(
+                gs.players[0], gs, player_idx=0, viewer_idx=viewer_idx, is_viewable=(viewer_idx == 0 or is_pvp)
+            ),
+            serialize_player(
+                gs.players[1], gs, player_idx=1, viewer_idx=viewer_idx, is_viewable=(viewer_idx == 1 or is_pvp)
+            ),
+        ],
+        "legal_actions": legal_actions,
+        "pending_choice": pending_choice,
+        "rule_log": gs.rule_log[-200:],  # Truncate log for transport
+        "performance_results": getattr(gs, "performance_results", {}),
+        "last_performance_results": getattr(gs, "last_performance_results", {}),
+        "performance_history": getattr(gs, "performance_history", []),
+        "looked_cards": [
+            serialize_card(cid, member_db, live_db, energy_db)
+            for cid in getattr(gs.get_player(active_idx), "looked_cards", [])
+        ],
+    }

engine/game/state_utils.py

@@ -0,0 +1,122 @@
+import logging
+from typing import Any, Dict, Iterator
+
+try:
+    pass
+except:
+    pass
+
+logger = logging.getLogger(__name__)
+
+
+class StateMixin:
+    """Base class for checking equality of state objects."""
+
+    def __eq__(self, other):
+        return isinstance(self, type(other)) and self.__dict__ == other.__dict__
+
+    def copy_slots_to(self, target: "StateMixin") -> None:
+        """Copy all fields defined in __slots__ to the target object."""
+        if not hasattr(self, "__slots__"):
+            return
+
+        for name in self.__slots__:
+            if hasattr(self, name):
+                val = getattr(self, name)
+                # Handle mutable types that need explicit copying
+                if isinstance(val, list):
+                    setattr(target, name, val[:])
+                elif isinstance(val, set):
+                    setattr(target, name, set(val))
+                elif isinstance(val, dict):
+                    setattr(target, name, dict(val))
+                elif hasattr(val, "copy"):
+                    setattr(target, name, val.copy())
+                else:
+                    setattr(target, name, val)
+
+
+# ----------------------------------------------------------------------------
+# Unique ID (UID) System
+# ----------------------------------------------------------------------------
+# Masks: 20 bits for Base ID, 12 bits for Instance
+BASE_ID_MASK = 0xFFFFF
+INSTANCE_SHIFT = 20
+
+
+def get_base_id(uid: int) -> int:
+    """Extract the base card definition ID from a potentially combined UID."""
+    return uid & BASE_ID_MASK
+
+
+def get_instance_index(uid: int) -> int:
+    """Extract the instance index from a UID."""
+    return uid >> INSTANCE_SHIFT
+
+
+def create_uid(base_id: int, instance_index: int) -> int:
+    """Create a unique instance ID from a base ID and an index."""
+    # Safety check: base_id must fit in 20 bits
+    if base_id > BASE_ID_MASK:
+        logger.warning(f"Base ID {base_id} exceeds mask {BASE_ID_MASK}!")
+    return (base_id & BASE_ID_MASK) | (instance_index << INSTANCE_SHIFT)
+
+
+class MaskedDB(dict):
+    """
+    A dictionary wrapper that automatically masks unique instance IDs (UIDs)
+    to retrieve data associated with the base ID.
+
+    This allows the game state to essentially 'ignore' the instance part of an ID
+    when looking up static card data.
+    """
+
+    def __init__(self, data: Dict[int, Any]):
+        super().__init__(data)
+        self._data = data
+
+    def __getitem__(self, key: int) -> Any:
+        # Resolve UID to base ID
+        try:
+            base_id = int(key) & BASE_ID_MASK
+            if base_id in self._data:
+                return self._data[base_id]
+            # Fallback to string key for JSON-loaded data
+            return self._data[str(base_id)]
+        except (ValueError, TypeError):
+            raise KeyError(key)
+
+    def __contains__(self, key: object) -> bool:
+        try:
+            base_id = int(key) & BASE_ID_MASK
+            return base_id in self._data or str(base_id) in self._data
+        except (ValueError, TypeError):
+            return False
+
+    def get(self, key: int, default: Any = None) -> Any:
+        try:
+            if key is None:
+                return default
+            base_id = int(key) & BASE_ID_MASK
+            if base_id in self._data:
+                return self._data[base_id]
+            # Fallback to string key
+            return self._data.get(str(base_id), default)
+        except (ValueError, TypeError):
+            return default
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __iter__(self) -> Iterator[int]:
+        # Iterate over ORIGINAL base IDs (keys of _data)
+        return iter(self._data)
+
+    def keys(self):
+        return self._data.keys()
+
+    def values(self):
+        return self._data.values()
+
+    def items(self):
+        return self._data.items()

engine/lovecasim_engine.pyd

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4abb957604898cfdd25c8f289f9be3e4c05c841297f221046b4176144b182739
+size 20523520

engine/models/ability.py

@@ -0,0 +1,1128 @@
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Any, Dict, List
+
+from engine.models.opcodes import Opcode
+
+
+class TriggerType(IntEnum):
+    NONE = 0
+    ON_PLAY = 1  # 登場時
+    ON_LIVE_START = 2  # ライブ開始時
+    ON_LIVE_SUCCESS = 3  # ライブ成功時
+    TURN_START = 4
+    TURN_END = 5
+    CONSTANT = 6  # 常時
+    ACTIVATED = 7  # 起動
+    ON_LEAVES = 8  # 自動 - when member leaves stage/is discarded
+    ON_REVEAL = 9  # エールにより公開、公開されたとき
+    ON_POSITION_CHANGE = 10  # エリアを移動するたび
+    ON_ACTIVATE = 7  # Alias for ACTIVATED
+
+
+class TargetType(IntEnum):
+    SELF = 0
+    PLAYER = 1
+    OPPONENT = 2
+    ALL_PLAYERS = 3
+    MEMBER_SELF = 4
+    MEMBER_OTHER = 5
+    CARD_HAND = 6
+    CARD_DISCARD = 7
+    CARD_DECK_TOP = 8
+    OPPONENT_HAND = 9  # 相手の手札
+    MEMBER_SELECT = 10  # Select manual target
+    MEMBER_NAMED = 11  # Specific named member implementation
+    OPPONENT_MEMBER = 12  # Specific opponent member target
+    PLAYER_SELECT = 13  # 自分か相手を選ぶ
+
+
+class EffectType(IntEnum):
+    DRAW = 0
+    ADD_BLADES = 1
+    ADD_HEARTS = 2
+    REDUCE_COST = 3
+    LOOK_DECK = 4
+    RECOVER_LIVE = 5  # Recover Live from discard
+    BOOST_SCORE = 6
+    RECOVER_MEMBER = 7  # Recover Member from discard
+    BUFF_POWER = 8  # Generic power/heart buff
+    IMMUNITY = 9  # Cannot be targeted/chosen
+    MOVE_MEMBER = 10  # Move member to different area
+    SWAP_CARDS = 11  # Swap cards between zones
+    SEARCH_DECK = 12  # Search deck for specific card
+    ENERGY_CHARGE = 13  # Add cards to energy zone
+    SET_BLADES = 31  # Layer 4: Set blades to fixed value
+    SET_HEARTS = 32  # Layer 4: Set hearts to fixed value
+    FORMATION_CHANGE = 33  # Rule 11.10: Rearrange all members
+    NEGATE_EFFECT = 14  # Cancel/negate an effect
+    ORDER_DECK = 15  # Reorder cards in deck
+    META_RULE = 16  # Rule clarification text (no effect)
+    SELECT_MODE = 17  # Choose one of the following effects
+    MOVE_TO_DECK = 18  # Move card to top/bottom of deck
+    TAP_OPPONENT = 19  # Tap opponent's member
+    PLACE_UNDER = 20  # Place card under member
+    FLAVOR_ACTION = 99  # "Ask opponent what they like", etc.
+    RESTRICTION = 21  # Restriction on actions (Cannot Live, etc)
+    BATON_TOUCH_MOD = 22  # Modify baton touch rules (e.g. 2 members)
+    SET_SCORE = 23  # Set score to fixed value
+    SWAP_ZONE = 24  # Swap between zones (e.g. Hand <-> Live)
+    TRANSFORM_COLOR = 25  # Change all colors of type X to Y
+    REVEAL_CARDS = 26  # 公開 - reveal cards from zone
+    LOOK_AND_CHOOSE = 27  # 見る、その中から - look at cards, choose from them
+    CHEER_REVEAL = 28  # エールにより公開 - cards revealed via cheer mechanic
+    ACTIVATE_MEMBER = 29  # アクティブにする - untap/make active a member
+    ADD_TO_HAND = 30  # 手札に加える - add card to hand (from any zone)
+    COLOR_SELECT = 37  # Specify a heart color
+    REPLACE_EFFECT = 34  # Replacement effect (代わりに)
+    TRIGGER_REMOTE = 35  # Trigger ability from another zone (Cluster 5)
+    REDUCE_HEART_REQ = 36  # Need hearts reduced
+    MODIFY_SCORE_RULE = 38  # Modify how score is calculated (e.g. +1 per yell score)
+    PLAY_MEMBER_FROM_HAND = 39  # Play member from hand (e.g. Keke)
+    TAP_MEMBER = 40  # Tap a member (usually self or other on stage)
+    MOVE_TO_DISCARD = 41  # 控え室に置く
+    # --- Added to fix META_RULE fallback ---
+    GRANT_ABILITY = 42  # Grant an ability to a member
+    INCREASE_HEART_COST = 43  # Increase heart requirement
+    REDUCE_YELL_COUNT = 44  # Reduce yell count
+    PLAY_MEMBER_FROM_DISCARD = 45  # Play member from discard
+    PAY_ENERGY = 46  # Pay/tap energy as cost
+    SELECT_MEMBER = 47  # Select target member
+    DRAW_UNTIL = 48  # Draw until hand size = X
+    SELECT_PLAYER = 49  # Select target player
+    SELECT_LIVE = 50  # Select target live
+    REVEAL_UNTIL = 51  # Reveal until condition met
+    INCREASE_COST = 52  # Increase cost (e.g., play cost)
+    PREVENT_PLAY_TO_SLOT = 53  # Prevent play to specific slot
+    SWAP_AREA = 54  # Swap members between areas
+    TRANSFORM_HEART = 55  # Transform heart color/count
+    SELECT_CARDS = 56  # Select specific cards
+    OPPONENT_CHOOSE = 57  # Opponent must make a choice
+    PLAY_LIVE_FROM_DISCARD = 58  # Play Live card from discard
+    REDUCE_LIVE_SET_LIMIT = 59  # Modify limit of live cards set per turn
+    ACTIVATE_ENERGY = 81  # エネルギーをアクティブにする
+    PREVENT_ACTIVATE = 72  # Prevent activating abilities/effects
+
+
+class ConditionType(IntEnum):
+    NONE = 0
+    TURN_1 = 1  # Turn == 1
+    HAS_MEMBER = 2  # Specific member on stage
+    HAS_COLOR = 3  # Specific color on stage
+    COUNT_STAGE = 4  # Count members >= X
+    COUNT_HAND = 5
+    COUNT_DISCARD = 6
+    IS_CENTER = 7
+    LIFE_LEAD = 8
+    COUNT_GROUP = 9  # "3+ Aqours members"
+    GROUP_FILTER = 10  # Filter by group name
+    OPPONENT_HAS = 11  # Opponent has X
+    SELF_IS_GROUP = 12  # This card is from group X
+    MODAL_ANSWER = 13  # Choice/Answer branch (e.g. LL-PR-004-PR)
+    COUNT_ENERGY = 14  # エネルギーがX枚以上
+    HAS_LIVE_CARD = 15  # ライブカードがある場合
+    COST_CHECK = 16  # コストがX以下/以上
+    RARITY_CHECK = 17  # Rarity filter
+    HAND_HAS_NO_LIVE = 18  # Hand contains no live cards (usually paired with reveal cost)
+    COUNT_SUCCESS_LIVE = 19  # 成功ライブカード置き場にX枚以上
+    OPPONENT_HAND_DIFF = 20  # Opponent has more/less/diff cards in hand
+    SCORE_COMPARE = 21  # Compare scores (e.g. higher than opponent)
+    HAS_CHOICE = 22  # Ability involves a choice
+    OPPONENT_CHOICE = 23  # Opponent makes a choice (相手は～選ぶ)
+    COUNT_HEARTS = 24  # Heart count condition (ハートがX個以上)
+    COUNT_BLADES = 25  # Blade count condition (ブレードがX以上)
+    OPPONENT_ENERGY_DIFF = 26  # Opponent energy comparison
+    HAS_KEYWORD = 27  # Has specific keyword/property (e.g. Blade Heart)
+    DECK_REFRESHED = 28  # Deck was refreshed (reshuffled) this turn
+    HAS_MOVED = 29  # Member has moved this turn
+    HAND_INCREASED = 30  # Hand size increased by X cards this turn
+    COUNT_LIVE_ZONE = 31  # Number of cards in live zone
+    BATON = 32  # Baton Pass check
+    TYPE_CHECK = 33  # Card type check (member/live)
+    IS_IN_DISCARD = 34  # Check if card is in discard pile
+
+
+# --- DESCRIPTIONS ---
+
+EFFECT_DESCRIPTIONS = {
+    EffectType.DRAW: "Draw {value} card(s)",
+    EffectType.LOOK_DECK: "Look at top {value} card(s) of deck",
+    EffectType.ADD_BLADES: "Gain {value} Blade(s)",
+    EffectType.ADD_HEARTS: "Gain {value} Heart(s)",
+    EffectType.REDUCE_COST: "Reduce cost by {value}",
+    EffectType.BOOST_SCORE: "Boost live score by {value}",
+    EffectType.RECOVER_LIVE: "Recover {value} Live card(s) from discard",
+    EffectType.RECOVER_MEMBER: "Recover {value} Member card(s) from discard",
+    EffectType.BUFF_POWER: "Power Up {value} (Blade/Heart)",
+    EffectType.IMMUNITY: "Gain Immunity",
+    EffectType.MOVE_MEMBER: "Move Member to another zone",
+    EffectType.SWAP_CARDS: "Discard {value} card(s) then Draw {value}",
+    EffectType.SEARCH_DECK: "Search Deck",
+    EffectType.ENERGY_CHARGE: "Charge {value} Energy",
+    EffectType.SET_BLADES: "Set Blade(s) to {value}",
+    EffectType.SET_HEARTS: "Set Heart(s) to {value}",
+    EffectType.FORMATION_CHANGE: "Rearrange members on stage",
+    EffectType.NEGATE_EFFECT: "Negate effect",
+    EffectType.ORDER_DECK: "Reorder top {value} cards of deck",
+    EffectType.META_RULE: "[Rule modifier]",
+    EffectType.SELECT_MODE: "Choose One:",
+    EffectType.MOVE_TO_DECK: "Return {value} card(s) to Deck",
+    EffectType.TAP_OPPONENT: "Tap {value} Opponent Member(s)",
+    EffectType.PLACE_UNDER: "Place card under Member",
+    EffectType.RESTRICTION: "Apply Restriction",
+    EffectType.BATON_TOUCH_MOD: "Modify Baton Touch rules",
+    EffectType.SET_SCORE: "Set Live Score to {value}",
+    EffectType.REVEAL_CARDS: "Reveal {value} card(s)",
+    EffectType.LOOK_AND_CHOOSE: "Look at {value} card(s) from deck and choose",
+    EffectType.ACTIVATE_MEMBER: "Active {value} Member(s)/Energy",
+    EffectType.ADD_TO_HAND: "Add {value} card(s) to Hand",
+    EffectType.TRIGGER_REMOTE: "Trigger Remote Ability",
+    EffectType.CHEER_REVEAL: "Reveal via Cheer",
+    EffectType.REDUCE_HEART_REQ: "Modify Heart Requirement",
+    EffectType.SWAP_ZONE: "Swap card zones",
+    EffectType.FLAVOR_ACTION: "Flavor Action",
+    EffectType.MOVE_TO_DISCARD: "Move {value} card(s) to Discard",
+    EffectType.PLAY_MEMBER_FROM_HAND: "Play member from hand",
+    EffectType.TAP_MEMBER: "Tap {value} Member(s)",
+}
+
+EFFECT_DESCRIPTIONS_JP = {
+    EffectType.DRAW: "{value}枚ドロー",
+    EffectType.LOOK_DECK: "デッキの上から{value}枚見る",
+    EffectType.ADD_BLADES: "ブレード+{value}",
+    EffectType.ADD_HEARTS: "ハート+{value}",
+    EffectType.REDUCE_COST: "コスト-{value}",
+    EffectType.BOOST_SCORE: "スコア+{value}",
+    EffectType.RECOVER_LIVE: "控えライブ{value}枚回収",
+    EffectType.RECOVER_MEMBER: "控えメンバー{value}枚回収",
+    EffectType.BUFF_POWER: "パワー+{value}",
+    EffectType.IMMUNITY: "効果無効",
+    EffectType.MOVE_MEMBER: "メンバー移動",
+    EffectType.SWAP_CARDS: "手札交換({value}枚捨て{value}枚引く)",
+    EffectType.SEARCH_DECK: "デッキ検索",
+    EffectType.ENERGY_CHARGE: "エネルギーチャージ+{value}",
+    EffectType.SET_BLADES: "ブレードを{value}にセット",
+    EffectType.SET_HEARTS: "ハートを{value}にセット",
+    EffectType.FORMATION_CHANGE: "配置変更",
+    EffectType.NEGATE_EFFECT: "効果打ち消し",
+    EffectType.ORDER_DECK: "デッキトップ{value}枚並べ替��",
+    EffectType.META_RULE: "[ルール変更]",
+    EffectType.SELECT_MODE: "モード選択:",
+    EffectType.MOVE_TO_DECK: "{value}枚をデッキに戻す",
+    EffectType.TAP_OPPONENT: "相手メンバー{value}人をウェイトにする",
+    EffectType.PLACE_UNDER: "メンバーの下に置く",
+    EffectType.RESTRICTION: "プレイ制限適用",
+    EffectType.BATON_TOUCH_MOD: "バトンタッチルール変更",
+    EffectType.SET_SCORE: "ライブスコアを{value}にセット",
+    EffectType.REVEAL_CARDS: "{value}枚公開",
+    EffectType.LOOK_AND_CHOOSE: "デッキから{value}枚見て選ぶ",
+    EffectType.ACTIVATE_MEMBER: "{value}人/エネをアクティブにする",
+    EffectType.ADD_TO_HAND: "手札に{value}枚加える",
+    EffectType.TRIGGER_REMOTE: "リモート能力誘発",
+    EffectType.CHEER_REVEAL: "応援で公開",
+    EffectType.REDUCE_HEART_REQ: "ハート条件変更",
+    EffectType.SWAP_ZONE: "カード移動(ゾーン間)",
+    EffectType.FLAVOR_ACTION: "フレーバーアクション",
+    EffectType.MOVE_TO_DISCARD: "控え室に{value}枚置く",
+    EffectType.PLAY_MEMBER_FROM_HAND: "手札からメンバーを登場させる",
+    EffectType.TAP_MEMBER: "{value}人をウェイトにする",
+    EffectType.ACTIVATE_ENERGY: "エネルギーを{value}枚アクティブにする",
+}
+
+TRIGGER_DESCRIPTIONS = {
+    TriggerType.ON_PLAY: "[On Play]",
+    TriggerType.ON_LIVE_START: "[Live Start]",
+    TriggerType.ON_LIVE_SUCCESS: "[Live Success]",
+    TriggerType.TURN_START: "[Turn Start]",
+    TriggerType.TURN_END: "[Turn End - live]",
+    TriggerType.CONSTANT: "[Constant - live]",
+    TriggerType.ACTIVATED: "[Activated]",
+    TriggerType.ON_LEAVES: "[When Leaves]",
+}
+
+TRIGGER_DESCRIPTIONS_JP = {
+    TriggerType.ON_PLAY: "【登場時】",
+    TriggerType.ON_LIVE_START: "【ライブ開始時】",
+    TriggerType.ON_LIVE_SUCCESS: "【ライブ成功時】",
+    TriggerType.TURN_START: "【ターン開始時】",
+    TriggerType.TURN_END: "【ターン終了時】",
+    TriggerType.CONSTANT: "【常時】",
+    TriggerType.ACTIVATED: "【起動】",
+    TriggerType.ON_LEAVES: "【離脱時】",
+}
+
+
+@dataclass(slots=True)
+class Condition:
+    type: ConditionType
+    params: Dict[str, Any] = field(default_factory=dict)
+    is_negated: bool = False  # "If NOT X" / "Except X"
+
+
+@dataclass(slots=True)
+class Effect:
+    effect_type: EffectType
+    value: int = 0
+    value_cond: ConditionType = ConditionType.NONE
+    target: TargetType = TargetType.SELF
+    params: Dict[str, Any] = field(default_factory=dict)
+    is_optional: bool = False  # ～てもよい
+    modal_options: List[List["Effect"]] = field(default_factory=list)  # For SELECT_MODE
+
+
+@dataclass(slots=True)
+class ResolvingEffect:
+    """Wrapper for an effect currently being resolved to track its source and progress."""
+
+    effect: Effect
+    source_card_id: int
+    step_index: int
+    total_steps: int
+
+
+class AbilityCostType(IntEnum):
+    NONE = 0
+    ENERGY = 1
+    TAP_SELF = 2  # ウェイトにする
+    DISCARD_HAND = 3  # 手札を捨てる
+    RETURN_HAND = 4  # 手札に戻す (Self bounce)
+    SACRIFICE_SELF = 5  # このメンバーを控え室に置く
+    REVEAL_HAND_ALL = 6  # 手札をすべて公開する
+    SACRIFICE_UNDER = 7  # 下に置かれているカードを控え室に置く
+    DISCARD_ENERGY = 8  # エネルギーを控え室に置く
+    REVEAL_HAND = 9  # 手札を公開する
+    TAP_PLAYER = 2  # Alias for TAP_SELF (ウェイトにする)
+
+    # Missing aliases/members inferred from usage
+    TAP_MEMBER = 20
+    TAP_ENERGY = 21
+    PAY_ENERGY = 1  # Alias for ENERGY
+    REST_MEMBER = 22
+    RETURN_MEMBER_TO_HAND = 23
+    DISCARD_MEMBER = 24
+    DISCARD_LIVE = 25
+    REMOVE_LIVE = 26
+    REMOVE_MEMBER = 27
+    RETURN_LIVE_TO_HAND = 28
+    RETURN_LIVE_TO_DECK = 29
+    RETURN_MEMBER_TO_DECK = 30
+    PLACE_MEMBER_FROM_HAND = 31
+    PLACE_LIVE_FROM_HAND = 32
+    PLACE_ENERGY_FROM_HAND = 33
+    PLACE_MEMBER_FROM_DISCARD = 34
+    PLACE_LIVE_FROM_DISCARD = 35
+    PLACE_ENERGY_FROM_DISCARD = 36
+    PLACE_MEMBER_FROM_DECK = 37
+    PLACE_LIVE_FROM_DECK = 38
+    PLACE_ENERGY_FROM_DECK = 39
+    # REVEAL_HAND = 40  # Moved to 9
+    SHUFFLE_DECK = 41
+    DRAW_CARD = 42
+    DISCARD_TOP_DECK = 43
+    REMOVE_TOP_DECK = 44
+    RETURN_DISCARD_TO_DECK = 45
+    RETURN_REMOVED_TO_DECK = 46
+    RETURN_REMOVED_TO_HAND = 47
+    RETURN_REMOVED_TO_DISCARD = 48
+    PLACE_ENERGY_FROM_SUCCESS = 49
+    DISCARD_SUCCESS_LIVE = 50
+    REMOVE_SUCCESS_LIVE = 51
+    RETURN_SUCCESS_LIVE_TO_HAND = 52
+    RETURN_SUCCESS_LIVE_TO_DECK = 53
+    RETURN_SUCCESS_LIVE_TO_DISCARD = 54
+    PLACE_MEMBER_FROM_SUCCESS = 55
+    PLACE_LIVE_FROM_SUCCESS = 56
+    PLACE_ENERGY_FROM_REMOVED = 57
+    PLACE_MEMBER_FROM_REMOVED = 58
+    PLACE_LIVE_FROM_REMOVED = 59
+    RETURN_ENERGY_TO_DECK = 60
+    RETURN_ENERGY_TO_HAND = 61
+    REMOVE_ENERGY = 62
+    RETURN_STAGE_ENERGY_TO_HAND = 64
+    DISCARD_STAGE_ENERGY = 65
+    REMOVE_STAGE_ENERGY = 66
+    DISCARD_STAGE = 65  # Alias for DISCARD_STAGE_ENERGY (often used for members/energy)
+    MOVE_TO_DISCARD = 5  # Common alias for sacrifice/discard
+    PLACE_ENERGY_FROM_STAGE_ENERGY = 67
+    PLACE_MEMBER_FROM_STAGE_ENERGY = 68
+    PLACE_LIVE_FROM_STAGE_ENERGY = 69
+    PLACE_ENERGY_FROM_HAND_TO_STAGE_ENERGY = 70
+    PLACE_MEMBER_FROM_HAND_TO_STAGE_ENERGY = 71
+    PLACE_LIVE_FROM_HAND_TO_STAGE_ENERGY = 72
+    PLACE_ENERGY_FROM_DISCARD_TO_STAGE_ENERGY = 73
+    PLACE_MEMBER_FROM_DISCARD_TO_STAGE_ENERGY = 74
+    PLACE_LIVE_FROM_DISCARD_TO_STAGE_ENERGY = 75
+    PLACE_ENERGY_FROM_DECK_TO_STAGE_ENERGY = 76
+    PLACE_MEMBER_FROM_DECK_TO_STAGE_ENERGY = 77
+    PLACE_LIVE_FROM_DECK_TO_STAGE_ENERGY = 78
+    PLACE_ENERGY_FROM_SUCCESS_TO_STAGE_ENERGY = 79
+    PLACE_MEMBER_FROM_SUCCESS_TO_STAGE_ENERGY = 80
+    PLACE_LIVE_FROM_SUCCESS_TO_STAGE_ENERGY = 81
+    PLACE_ENERGY_FROM_REMOVED_TO_STAGE_ENERGY = 82
+    PLACE_MEMBER_FROM_REMOVED_TO_STAGE_ENERGY = 83
+    PLACE_LIVE_FROM_REMOVED_TO_STAGE_ENERGY = 84
+    RETURN_LIVE_TO_DISCARD = 85
+    RETURN_LIVE_TO_REMOVED = 86
+    RETURN_LIVE_TO_SUCCESS = 87
+    RETURN_MEMBER_TO_DISCARD = 88
+    RETURN_MEMBER_TO_REMOVED = 89
+    RETURN_MEMBER_TO_SUCCESS = 90
+    RETURN_ENERGY_TO_DISCARD = 91
+    RETURN_ENERGY_TO_REMOVED = 92
+    RETURN_ENERGY_TO_SUCCESS = 93
+    RETURN_SUCCESS_LIVE_TO_REMOVED = 94
+    RETURN_REMOVED_TO_SUCCESS = 95
+    RETURN_STAGE_ENERGY_TO_DISCARD = 96
+    RETURN_STAGE_ENERGY_TO_REMOVED = 97
+    RETURN_STAGE_ENERGY_TO_SUCCESS = 98
+    RETURN_DISCARD_TO_HAND = 99
+    RETURN_DISCARD_TO_REMOVED = 100
+    RETURN_DISCARD_TO_SUCCESS = 101
+    RETURN_DECK_TO_DISCARD = 102
+    RETURN_DECK_TO_HAND = 103
+    RETURN_DECK_TO_REMOVED = 104
+    RETURN_DECK_TO_SUCCESS = 105
+    RETURN_ENERGY_DECK_TO_DISCARD = 106
+    RETURN_ENERGY_DECK_TO_HAND = 107
+    RETURN_ENERGY_DECK_TO_REMOVED = 108
+    RETURN_ENERGY_DECK_TO_SUCCESS = 109
+
+    # Auto-generated missing members for effect_mixin.py compatibility
+    PLACE_ENERGY_FROM_DECK_TO_DISCARD = 110
+    PLACE_ENERGY_FROM_DECK_TO_HAND = 111
+    PLACE_ENERGY_FROM_DECK_TO_REMOVED = 112
+    PLACE_ENERGY_FROM_DECK_TO_SUCCESS = 113
+    PLACE_ENERGY_FROM_DISCARD_TO_HAND = 114
+    PLACE_ENERGY_FROM_DISCARD_TO_REMOVED = 115
+    PLACE_ENERGY_FROM_DISCARD_TO_SUCCESS = 116
+    PLACE_ENERGY_FROM_ENERGY_DECK = 117
+    PLACE_ENERGY_FROM_ENERGY_DECK_TO_DISCARD = 118
+    PLACE_ENERGY_FROM_ENERGY_DECK_TO_HAND = 119
+    PLACE_ENERGY_FROM_ENERGY_DECK_TO_REMOVED = 120
+    PLACE_ENERGY_FROM_ENERGY_DECK_TO_STAGE_ENERGY = 121
+    PLACE_ENERGY_FROM_ENERGY_DECK_TO_SUCCESS = 122
+    PLACE_ENERGY_FROM_ENERGY_ZONE_TO_DISCARD = 123
+    PLACE_ENERGY_FROM_ENERGY_ZONE_TO_HAND = 124
+    PLACE_ENERGY_FROM_ENERGY_ZONE_TO_REMOVED = 125
+    PLACE_ENERGY_FROM_ENERGY_ZONE_TO_SUCCESS = 126
+    PLACE_ENERGY_FROM_HAND_TO_DISCARD = 127
+    PLACE_ENERGY_FROM_HAND_TO_REMOVED = 128
+    PLACE_ENERGY_FROM_HAND_TO_SUCCESS = 129
+    PLACE_ENERGY_FROM_REMOVED_TO_DISCARD = 130
+    PLACE_ENERGY_FROM_REMOVED_TO_HAND = 131
+    PLACE_ENERGY_FROM_REMOVED_TO_SUCCESS = 132
+    PLACE_ENERGY_FROM_STAGE_ENERGY_TO_DISCARD = 133
+    PLACE_ENERGY_FROM_STAGE_ENERGY_TO_HAND = 134
+    PLACE_ENERGY_FROM_STAGE_ENERGY_TO_REMOVED = 135
+    PLACE_ENERGY_FROM_STAGE_ENERGY_TO_SUCCESS = 136
+    PLACE_ENERGY_FROM_SUCCESS_TO_DISCARD = 137
+    PLACE_ENERGY_FROM_SUCCESS_TO_HAND = 138
+    PLACE_ENERGY_FROM_SUCCESS_TO_REMOVED = 139
+    PLACE_LIVE_FROM_DECK_TO_DISCARD = 140
+    PLACE_LIVE_FROM_DECK_TO_HAND = 141
+    PLACE_LIVE_FROM_DECK_TO_REMOVED = 142
+    PLACE_LIVE_FROM_DECK_TO_SUCCESS = 143
+    PLACE_LIVE_FROM_DISCARD_TO_HAND = 144
+    PLACE_LIVE_FROM_DISCARD_TO_REMOVED = 145
+    PLACE_LIVE_FROM_DISCARD_TO_SUCCESS = 146
+    PLACE_LIVE_FROM_ENERGY_DECK = 147
+    PLACE_LIVE_FROM_ENERGY_DECK_TO_DISCARD = 148
+    PLACE_LIVE_FROM_ENERGY_DECK_TO_HAND = 149
+    PLACE_LIVE_FROM_ENERGY_DECK_TO_REMOVED = 150
+    PLACE_LIVE_FROM_ENERGY_DECK_TO_STAGE_ENERGY = 151
+    PLACE_LIVE_FROM_ENERGY_DECK_TO_SUCCESS = 152
+    PLACE_LIVE_FROM_ENERGY_ZONE_TO_DISCARD = 153
+    PLACE_LIVE_FROM_ENERGY_ZONE_TO_HAND = 154
+    PLACE_LIVE_FROM_ENERGY_ZONE_TO_REMOVED = 155
+    PLACE_LIVE_FROM_ENERGY_ZONE_TO_SUCCESS = 156
+    PLACE_LIVE_FROM_HAND_TO_DISCARD = 157
+    PLACE_LIVE_FROM_HAND_TO_REMOVED = 158
+    PLACE_LIVE_FROM_HAND_TO_SUCCESS = 159
+    PLACE_LIVE_FROM_REMOVED_TO_DISCARD = 160
+    PLACE_LIVE_FROM_REMOVED_TO_HAND = 161
+    PLACE_LIVE_FROM_REMOVED_TO_SUCCESS = 162
+    PLACE_LIVE_FROM_STAGE_ENERGY_TO_DISCARD = 163
+    PLACE_LIVE_FROM_STAGE_ENERGY_TO_HAND = 164
+    PLACE_LIVE_FROM_STAGE_ENERGY_TO_REMOVED = 165
+    PLACE_LIVE_FROM_STAGE_ENERGY_TO_SUCCESS = 166
+    PLACE_LIVE_FROM_SUCCESS_TO_DISCARD = 167
+    PLACE_LIVE_FROM_SUCCESS_TO_HAND = 168
+    PLACE_LIVE_FROM_SUCCESS_TO_REMOVED = 169
+    PLACE_MEMBER_FROM_DECK_TO_DISCARD = 170
+    PLACE_MEMBER_FROM_DECK_TO_HAND = 171
+    PLACE_MEMBER_FROM_DECK_TO_REMOVED = 172
+    PLACE_MEMBER_FROM_DECK_TO_SUCCESS = 173
+    PLACE_MEMBER_FROM_DISCARD_TO_HAND = 174
+    PLACE_MEMBER_FROM_DISCARD_TO_REMOVED = 175
+    PLACE_MEMBER_FROM_DISCARD_TO_SUCCESS = 176
+    PLACE_MEMBER_FROM_ENERGY_DECK = 177
+    PLACE_MEMBER_FROM_ENERGY_DECK_TO_DISCARD = 178
+    PLACE_MEMBER_FROM_ENERGY_DECK_TO_HAND = 179
+    PLACE_MEMBER_FROM_ENERGY_DECK_TO_REMOVED = 180
+    PLACE_MEMBER_FROM_ENERGY_DECK_TO_STAGE_ENERGY = 181
+    PLACE_MEMBER_FROM_ENERGY_DECK_TO_SUCCESS = 182
+    PLACE_MEMBER_FROM_ENERGY_ZONE_TO_DISCARD = 183
+    PLACE_MEMBER_FROM_ENERGY_ZONE_TO_HAND = 184
+    PLACE_MEMBER_FROM_ENERGY_ZONE_TO_REMOVED = 185
+    PLACE_MEMBER_FROM_ENERGY_ZONE_TO_SUCCESS = 186
+    PLACE_MEMBER_FROM_HAND_TO_DISCARD = 187
+    PLACE_MEMBER_FROM_HAND_TO_REMOVED = 188
+    PLACE_MEMBER_FROM_HAND_TO_SUCCESS = 189
+    PLACE_MEMBER_FROM_REMOVED_TO_DISCARD = 190
+    PLACE_MEMBER_FROM_REMOVED_TO_HAND = 191
+    PLACE_MEMBER_FROM_REMOVED_TO_SUCCESS = 192
+    PLACE_MEMBER_FROM_STAGE_ENERGY_TO_DISCARD = 193
+    PLACE_MEMBER_FROM_STAGE_ENERGY_TO_HAND = 194
+    PLACE_MEMBER_FROM_STAGE_ENERGY_TO_REMOVED = 195
+    PLACE_MEMBER_FROM_STAGE_ENERGY_TO_SUCCESS = 196
+    PLACE_MEMBER_FROM_SUCCESS_TO_DISCARD = 197
+    PLACE_MEMBER_FROM_SUCCESS_TO_HAND = 198
+    PLACE_MEMBER_FROM_SUCCESS_TO_REMOVED = 199
+
+
+@dataclass
+class Cost:
+    type: AbilityCostType
+    value: int = 0
+    params: Dict[str, Any] = field(default_factory=dict)
+    is_optional: bool = False
+
+    @property
+    def cost_type(self) -> AbilityCostType:
+        return self.type
+
+
+@dataclass
+class Ability:
+    raw_text: str
+    trigger: TriggerType
+    effects: List[Effect]
+    conditions: List[Condition] = field(default_factory=list)
+    costs: List[Cost] = field(default_factory=list)
+    modal_options: List[List[Effect]] = field(default_factory=list)  # For SELECT_MODE
+    is_once_per_turn: bool = False
+    bytecode: List[int] = field(default_factory=list)
+    requires_selection: bool = False
+    # Ordered list of operations (Union[Effect, Condition]) for precise execution order
+    instructions: List[Any] = field(default_factory=list)
+
+    def compile(self) -> List[int]:
+        """Compile ability into fixed-width bytecode sequence (groups of 4 ints)."""
+        bytecode = []
+
+        # 0. Compile Ordered Instructions (If present - New Parser V2.1)
+        if self.instructions:
+            for instr in self.instructions:
+                if isinstance(instr, Condition):
+                    self._compile_single_condition(instr, bytecode)
+                elif isinstance(instr, Effect):
+                    self._compile_effect_wrapper(instr, bytecode)
+
+            # Terminator
+            bytecode.extend([int(Opcode.RETURN), 0, 0, 0])
+            return bytecode
+
+        # 1. Compile Conditions (Legacy/Split Mode)
+        for cond in self.conditions:
+            self._compile_single_condition(cond, bytecode)
+
+        # 1.5. Compile Costs (Note: Modern engine handles costs via pay_cost shell)
+        # We don't compile costs into bytecode unless they are meant for mid-ability execution.
+
+        # 2. Compile Effects
+        for eff in self.effects:
+            self._compile_effect_wrapper(eff, bytecode)
+
+        # Terminator
+        bytecode.extend([int(Opcode.RETURN), 0, 0, 0])
+        return bytecode
+
+    def _compile_single_condition(self, cond: Condition, bytecode: List[int]):
+        op_name = f"CHECK_{cond.type.name}"
+        if hasattr(Opcode, op_name):
+            op = getattr(Opcode, op_name)
+            # Fixed width: [Opcode, Value, Attr, TargetSlot]
+            # Check multiple potential keys for the value (min, count, value, diff)
+            v_raw = cond.params.get("value", cond.params.get("min", cond.params.get("count", cond.params.get("diff", 0))))
+            try:
+                val = int(v_raw) if v_raw is not None else 0
+            except (ValueError, TypeError):
+                val = 0
+
+            # Resolve attr (color, group, or unit) to integer
+            attr_raw = cond.params.get("color", cond.params.get("group", cond.params.get("unit", 0)))
+            if isinstance(attr_raw, str):
+                # Resolve using enums
+                if "group" in cond.params:
+                    from engine.models.enums import Group
+
+                    attr = int(Group.from_japanese_name(attr_raw))
+                elif "unit" in cond.params:
+                    from engine.models.enums import Unit
+
+                    attr = int(Unit.from_japanese_name(attr_raw))
+                elif cond.type == ConditionType.SCORE_COMPARE:
+                    # Map score/cost/heart types to int
+                    stype = cond.params.get("type", "score")
+                    type_map = {"score": 0, "cost": 1, "heart": 2, "heart_count": 2, "cheer_count": 3}
+                    attr = type_map.get(stype, 0)
+                else:
+                    attr = 0
+            else:
+                attr = int(attr_raw) if attr_raw is not None else 0
+
+            # Comparison mapping (GE=0, LE=1, GT=2, LT=3, EQ=4)
+            comp_str = cond.params.get("comparison", "GE")
+            comp_map = {"GE": 0, "LE": 1, "GT": 2, "LT": 3, "EQ": 4}
+            comp_val = comp_map.get(comp_str, 0)
+
+            # Zone mapping: STAGE=0, LIVE_ZONE=1, LIVE_RESULT/EXCESS=2
+            slot = 0
+            zone = cond.params.get("zone", "")
+            context = cond.params.get("context", "")
+
+            if zone == "LIVE_ZONE":
+                slot = 1
+            elif zone == "STAGE":
+                slot = 0
+            elif context == "excess":
+                slot = 2
+            else:
+                slot = cond.params.get("TargetSlot", 0)
+
+            # Pack comparison into higher bits of slot (bits 4-7)
+            # Slot is usually 0-3, so shift 4 is safe.
+            packed_slot = (slot & 0x0F) | ((comp_val & 0x0F) << 4)
+
+            op_val = int(op)
+            if cond.is_negated:
+                op_val += 1000
+
+            bytecode.extend(
+                [
+                    op_val,
+                    val,
+                    attr,
+                    packed_slot,
+                ]
+            )
+
+        elif cond.type == ConditionType.BATON:
+            # Special handling for BATON condition
+            if hasattr(Opcode, "CHECK_BATON"):
+                unit_id = 0
+                if "unit" in cond.params:
+                    from engine.models.enums import Unit
+
+                    try:
+                        # Handle string unit names
+                        u_val = cond.params["unit"]
+                        if isinstance(u_val, str):
+                            unit_id = int(Unit.from_japanese_name(u_val))
+                        else:
+                            unit_id = int(u_val)
+                    except:
+                        unit_id = 0
+
+                filter_type = 0
+                if "filter" in cond.params:
+                    f_str = cond.params["filter"]
+                    if f_str == "COST_LT_SELF":
+                        filter_type = 1  # 1 = Cost Check Less Than Self
+
+                bytecode.extend([int(Opcode.CHECK_BATON), unit_id, filter_type, 0])
+
+        elif cond.type == ConditionType.TYPE_CHECK:
+            if hasattr(Opcode, "CHECK_TYPE_CHECK"):
+                # card_type: "live" = 1, "member" = 0
+                ctype = 1 if cond.params.get("card_type") == "live" else 0
+                bytecode.extend([int(Opcode.CHECK_TYPE_CHECK), ctype, 0, 0])
+
+    def _compile_effect_wrapper(self, eff: Effect, bytecode: List[int]):
+        # Fix: Use name comparison to avoid Enum identity issues from reloading/imports
+        if eff.effect_type.name == "ORDER_DECK":
+            # O_ORDER_DECK requires looking at cards first.
+            # Emit: [O_LOOK_DECK, val, 0, 0] -> [O_ORDER_DECK, val, attr, 0]
+            # attr: 0=Discard, 1=DeckTop, 2=DeckBottom
+            rem = eff.params.get("remainder", "discard").lower()
+            attr = 0
+            if rem == "deck_top":
+                attr = 1
+            elif rem == "deck_bottom":
+                attr = 2
+
+            bytecode.extend([int(Opcode.LOOK_DECK), eff.value, 0, 0])
+            bytecode.extend([int(Opcode.ORDER_DECK), eff.value, attr, 0])
+            return
+
+        # Check for modal options on Effect OR Ability (fallback)
+        modal_opts = eff.modal_options if eff.modal_options else self.modal_options
+
+        if eff.effect_type == EffectType.SELECT_MODE and modal_opts:
+            # Handle SELECT_MODE with jump table
+            num_options = len(modal_opts)
+            # Emit header: [SELECT_MODE, NumOptions, 0, 0]
+            if hasattr(Opcode, "SELECT_MODE"):
+                bytecode.extend([int(Opcode.SELECT_MODE), num_options, 0, 0])
+
+            # Placeholders for Jump Table
+            jump_table_start_idx = len(bytecode)
+            for _ in range(num_options):
+                bytecode.extend([int(Opcode.JUMP), 0, 0, 0])
+
+            # Compile each option and track start/end
+            option_start_offsets = []
+            end_jumps_locations = []
+
+            for opt_effects in modal_opts:
+                # Record start offset (relative to current instruction pointer)
+                current_idx = len(bytecode) // 4
+                option_start_offsets.append(current_idx)
+
+                # Compile option effects
+                for opt_eff in opt_effects:
+                    self._compile_single_effect(opt_eff, bytecode)
+
+                # Add Jump to End (placeholder)
+                end_jumps_locations.append(len(bytecode))
+                bytecode.extend([int(Opcode.JUMP), 0, 0, 0])
+
+            # Determine End Index
+            end_idx = len(bytecode) // 4
+
+            # Patch Jump Table (Start Jumps)
+            for i in range(num_options):
+                jump_instr_idx = (jump_table_start_idx // 4) + i
+                target_idx = option_start_offsets[i]
+                offset = target_idx - jump_instr_idx
+                bytecode[jump_instr_idx * 4 + 1] = offset
+
+            # Patch End Jumps
+            for loc in end_jumps_locations:
+                jump_instr_idx = loc // 4
+                offset = end_idx - jump_instr_idx
+                bytecode[loc + 1] = offset
+
+        else:
+            self._compile_single_effect(eff, bytecode)
+
+    def _compile_single_effect(self, eff: Effect, bytecode: List[int]):
+        print(f"DEBUG: Compiling Single Effect: {eff.effect_type.name} (Val={eff.value})")
+        if hasattr(Opcode, eff.effect_type.name):
+            op = getattr(Opcode, eff.effect_type.name)
+
+            try:
+                val = int(eff.value)
+            except (ValueError, TypeError):
+                val = 1
+            attr = eff.params.get("color", 0) if isinstance(eff.params.get("color"), int) else 0
+            slot = eff.target.value if hasattr(eff.target, "value") else int(eff.target)
+
+            # Check for interactive target selection requirement
+            # Use Bit 5 (0x20) in attr to flag "Requires Selection"
+            if eff.effect_type == EffectType.TAP_OPPONENT:
+                attr |= 1 << 5
+
+            # Special handling for PLACE_UNDER params
+            if eff.effect_type == EffectType.PLACE_UNDER:
+                if eff.params.get("from") == "energy":
+                    attr = 1  # Source: Energy
+                elif eff.params.get("from") == "discard":
+                    attr = 2  # Source: Discard (for future proofing)
+                # Keep existing type logic if any, but currently PLACE_UNDER uses attr for source
+
+            # Special handling for SEARCH_DECK params
+            if eff.effect_type == EffectType.SEARCH_DECK:
+                if "group" in eff.params:
+                    slot = 1  # Filter Type: Group
+                    try:
+                        attr = int(eff.params["group"])
+                    except:
+                        pass
+                elif "unit" in eff.params:
+                    slot = 2  # Filter Type: Unit
+                    try:
+                        attr = int(eff.params["unit"])
+                    except:
+                        pass
+
+            # Special handling for PLAY_MEMBER_FROM_HAND params
+            if eff.effect_type == EffectType.PLAY_MEMBER_FROM_HAND:
+                if "group" in eff.params:
+                    from engine.models.enums import Group
+
+                    try:
+                        attr = int(Group.from_japanese_name(eff.params["group"]))
+                    except:
+                        pass
+
+            # Special handling for LOOK_AND_CHOOSE destination
+            if eff.effect_type == EffectType.LOOK_AND_CHOOSE:
+                if eff.params.get("source") == "HAND":
+                    slot = int(TargetType.CARD_HAND)
+
+                attr = 0
+                if eff.params.get("destination") == "discard":
+                    attr |= 0x01  # Bit 0: Destination Discard
+                if eff.is_optional or eff.params.get("is_optional"):
+                    attr |= 0x02  # Bit 1: Optional (May)
+
+                # Parse 'filter' string if present (e.g. "GROUP_ID=0, TYPE_LIVE")
+                if "filter" in eff.params:
+                    filter_str = str(eff.params["filter"])
+                    parts = [p.strip() for p in filter_str.split(",")]
+                    for part in parts:
+                        if "=" in part:
+                            k, v = part.split("=", 1)
+                            k, v = k.strip().upper(), v.strip()
+                            if k == "GROUP_ID":
+                                eff.params["group"] = v
+                            if k == "TYPE":
+                                eff.params["type"] = v
+                        else:
+                            if part.upper() == "TYPE_LIVE":
+                                eff.params["type"] = "live"
+                            if part.upper() == "TYPE_MEMBER":
+                                eff.params["type"] = "member"
+
+                # Source Zone: Bits 12-15
+                src_zone = eff.params.get("source", "DECK")
+                src_val = 8  # Default DECK
+                if src_zone == "HAND":
+                    src_val = 6
+                elif src_zone == "DISCARD":
+                    src_val = 7
+                attr |= src_val << 12
+
+                # Filter Mode (Type): Bit 2-3
+                ctype = str(eff.params.get("type", "")).lower()
+                if ctype == "live":
+                    attr |= 0x02 << 2  # Value 2 in bits 2-3
+                elif ctype == "member":
+                    attr |= 0x01 << 2  # Value 1 in bits 2-3
+
+                # Group Filter: Bit 4 (Enable) and Bits 5-11 (ID)
+                group_val = eff.params.get("group")
+                if group_val is not None:
+                    try:
+                        if str(group_val).isdigit():
+                            g_id = int(str(group_val))
+                        else:
+                            from engine.models.enums import Group
+
+                            g_id = int(Group.from_japanese_name(str(group_val)))
+                        attr |= 0x10  # Bit 4: Has Group Filter
+                        attr |= g_id << 5  # Bits 5-11: Group ID
+                    except:
+                        pass
+
+            # Special handling for TAP filters
+            if eff.effect_type in (EffectType.TAP_OPPONENT, EffectType.TAP_MEMBER):
+                # Use Value for cost_max filter (99 = dynamic/none)
+                # Use Attr bits 0-6 for blades_max filter (99 = none)
+                try:
+                    val = int(eff.params.get("cost_max", 99))
+                except (ValueError, TypeError):
+                    val = 99
+                try:
+                    blades_max = int(eff.params.get("blades_max", 99))
+                except (ValueError, TypeError):
+                    blades_max = 99
+                attr = (attr & 0x80) | (blades_max & 0x7F)
+
+            # Special handling for MOVE_TO_DISCARD params
+            if eff.effect_type == EffectType.MOVE_TO_DISCARD:
+                if eff.params.get("from") == "deck_top":
+                    attr = 1  # Source: Deck Top
+                elif eff.params.get("from") == "hand":
+                    attr = 2  # Source: Hand
+                elif eff.params.get("from") == "energy":
+                    attr = 3  # Source: Energy
+
+            if eff.value_cond != ConditionType.NONE:
+                val = int(eff.value_cond)
+                attr |= 0x40  # Bit 6 for Dynamic
+
+            # Special encoding for REVEAL_UNTIL
+            if eff.effect_type == EffectType.REVEAL_UNTIL:
+                if eff.value_cond == ConditionType.TYPE_CHECK:
+                    if eff.params.get("card_type") == "live":
+                        attr |= 0x01
+                elif eff.value_cond == ConditionType.COST_CHECK:
+                    cost = int(eff.params.get("min", 0))
+                    attr |= (cost & 0x1F) << 1
+
+            # Default to Choice (slot 4) for PLAY opcodes if target is generic (SELF/PLAYER)
+            if eff.effect_type in (
+                EffectType.PLAY_MEMBER_FROM_HAND,
+                EffectType.PLAY_MEMBER_FROM_DISCARD,
+                EffectType.PLAY_LIVE_FROM_DISCARD,
+            ):
+                if eff.target in (TargetType.SELF, TargetType.PLAYER):
+                    slot = 4
+
+            bytecode.extend(
+                [
+                    int(op),
+                    int(val),
+                    attr if not eff.params.get("all") else (attr | 0x80),  # Bit 7 for ALL
+                    slot,
+                ]
+            )
+
+    def reconstruct_text(self, lang: str = "en") -> str:
+        """Generate standardized text description."""
+        parts = []
+        is_jp = lang == "jp"
+        t_desc_map = TRIGGER_DESCRIPTIONS_JP if is_jp else TRIGGER_DESCRIPTIONS
+        e_desc_map = EFFECT_DESCRIPTIONS_JP if is_jp else EFFECT_DESCRIPTIONS
+
+        t_name = getattr(self.trigger, "name", str(self.trigger))
+        trigger_desc = t_desc_map.get(self.trigger, f"[{t_name}]")
+        if self.trigger == TriggerType.ON_LEAVES:
+            if "discard" not in trigger_desc.lower() and "控え室" not in trigger_desc:
+                suffix = " (to discard)" if not is_jp else "(控え室へ)"
+                trigger_desc += suffix
+        parts.append(trigger_desc)
+
+        for cost in self.costs:
+            if is_jp:
+                if cost.type == AbilityCostType.ENERGY:
+                    parts.append(f"(コスト: エネ{cost.value}消費)")
+                elif cost.type == AbilityCostType.TAP_SELF:
+                    parts.append("(コスト: 自身ウェイト)")
+                elif cost.type == AbilityCostType.DISCARD_HAND:
+                    parts.append(f"(コスト: 手札{cost.value}枚捨て)")
+                elif cost.type == AbilityCostType.SACRIFICE_SELF:
+                    parts.append("(コスト: 自身退場)")
+                else:
+                    parts.append(f"(コスト: {cost.type.name} {cost.value})")
+            else:
+                if cost.type == AbilityCostType.ENERGY:
+                    parts.append(f"(Cost: Pay {cost.value} Energy)")
+                elif cost.type == AbilityCostType.TAP_SELF:
+                    parts.append("(Cost: Rest Self)")
+                elif cost.type == AbilityCostType.DISCARD_HAND:
+                    parts.append(f"(Cost: Discard {cost.value} from hand)")
+                elif cost.type == AbilityCostType.SACRIFICE_SELF:
+                    parts.append("(Cost: Sacrifice Self)")
+                else:
+                    parts.append(f"(Cost: {cost.type.name} {cost.value})")
+
+        for cond in self.conditions:
+            if is_jp:
+                neg = "NOT " if cond.is_negated else ""  # JP negation usually handles via suffix, but keeping simple
+                cond_desc = f"{neg}{cond.type.name}"
+                if cond.type == ConditionType.BATON:
+                    cond_desc = "条件: バトンタッチ"
+                    if "unit" in cond.params:
+                        cond_desc += f" ({cond.params['unit']})"
+                # ... (add more JP specific cond descs if needed, but for now fallback)
+            else:
+                neg = "NOT " if cond.is_negated else ""
+                cond_desc = f"{neg}{cond.type.name}"
+            # Add basic params
+            if cond.params.get("type") == "score":
+                cond_desc += " (Score)"
+            if cond.type == ConditionType.SCORE_COMPARE:
+                target_str = " (Opponent)" if cond.params.get("target") == "opponent" else ""
+                cond_desc += f" (Score check{target_str})"
+            if cond.type == ConditionType.OPPONENT_HAS:
+                cond_desc += " (Opponent has)"
+            if cond.type == ConditionType.OPPONENT_CHOICE:
+                cond_desc += " (Opponent chooses)"
+            if cond.type == ConditionType.OPPONENT_HAND_DIFF:
+                cond_desc += " (Opponent hand check)"
+            if cond.params.get("group"):
+                cond_desc += f"({cond.params['group']})"
+            if cond.params.get("zone"):
+                cond_desc += f" (in {cond.params['zone']})"
+            if cond.params.get("zone") == "SUCCESS_LIVE":
+                cond_desc += " (in Live Area)"
+            if cond.type == ConditionType.HAS_CHOICE:
+                cond_desc = "Condition: Choose One"
+            if cond.type == ConditionType.HAS_KEYWORD:
+                cond_desc += f" (Has {cond.params.get('keyword', '?')})"
+                if cond.params.get("context") == "heart_inclusion":
+                    cond_desc += " (Heart check)"
+            if cond.type == ConditionType.COUNT_BLADES:
+                cond_desc += " (Blade count)"
+            if cond.type == ConditionType.COUNT_HEARTS:
+                cond_desc += " (Heart count)"
+                if cond.params.get("context") == "excess":
+                    cond_desc += " (Excess)"
+            if cond.type == ConditionType.COUNT_ENERGY:
+                cond_desc += " (Energy count)"
+            if cond.type == ConditionType.COUNT_SUCCESS_LIVE:
+                cond_desc += " (Success Live count)"
+            if cond.type == ConditionType.HAS_LIVE_CARD:
+                cond_desc += " (Live card check)"
+                type_str = (
+                    "Heart comparison"
+                    if cond.params.get("type") == "heart"
+                    else "Cheer comparison"
+                    if cond.params.get("type") == "cheer_count"
+                    else "Score check"
+                )
+                cond_desc += f" ({type_str}{target_str})"
+            if cond.type == ConditionType.BATON:
+                cond_desc = "Condition: Baton Pass"
+                if "unit" in cond.params:
+                    cond_desc += f" ({cond.params['unit']})"
+            parts.append(cond_desc)
+
+        for eff in self.effects:
+            # Special handling for META_RULE which relies heavily on params
+            desc = None
+            if eff.effect_type == EffectType.META_RULE:
+                if eff.params.get("type") == "opponent_trigger_allowed":
+                    desc = "[Meta: Opponent effects trigger this]"
+                elif eff.params.get("type") == "shuffle":
+                    desc = "Shuffle Deck"
+                elif eff.params.get("type") == "heart_rule":
+                    src = eff.params.get("source", "")
+                    src_text = "ALL Blades" if src == "all_blade" else "Blade" if src == "blade" else ""
+                    desc = f"[Meta: Treat {src_text} as Heart]" if src_text else "[Meta: Treat as Heart]"
+                elif eff.params.get("type") == "live":
+                    desc = "[Meta: Live Rule]"
+                elif eff.params.get("type") == "lose_blade_heart":
+                    desc = "[Meta: Lose Blade Heart]"
+                elif eff.params.get("type") == "re_cheer":
+                    desc = "[Meta: Cheer Again]"
+                elif eff.params.get("type") == "cheer_mod":
+                    val = eff.value
+                    desc = f"[Meta: Cheer Reveal Count {'+' if val > 0 else ''}{val}]"
+                elif eff.effect_type == getattr(EffectType, "TAP_OPPONENT", -1):
+                    desc = "Tap Opponent Member(s)"
+
+            if desc is None:
+                # Custom overrides for standard effects with params
+                if eff.effect_type == EffectType.DRAW and eff.params.get("multiplier") == "energy":
+                    req = eff.params.get("req_per_unit", 1)
+                    desc = f"Draw {eff.value} card(s) per {req} Energy"
+                elif eff.effect_type == EffectType.REDUCE_HEART_REQ and eff.value < 0:
+                    # e.g. value -1 means reduce requirement. value +1 means increase requirement (opp).
+                    pass
+
+                if desc is None:
+                    template = e_desc_map.get(eff.effect_type, getattr(eff.effect_type, "name", str(eff.effect_type)))
+                    context = eff.params.copy()
+                    context["value"] = eff.value
+
+                    # Refine REDUCE_HEART_REQ
+                    if eff.effect_type == EffectType.REDUCE_HEART_REQ:
+                        if eff.params.get("mode") == "select_requirement":
+                            desc = "Choose Heart Requirement (hearts) (choice)" if not is_jp else "ハート条件選択"
+                        elif eff.value < 0:
+                            desc = (
+                                f"Reduce Heart Requirement by {abs(eff.value)} (Live)"
+                                if not is_jp
+                                else f"ハート条件-{abs(eff.value)}"
+                            )
+                        else:
+                            desc = (
+                                f"Increase Heart Requirement by {eff.value} (Live)"
+                                if not is_jp
+                                else f"ハート条件+{eff.value}"
+                            )
+                    elif eff.effect_type == EffectType.TRANSFORM_COLOR:
+                        target_s = eff.params.get("target", "Color")
+                        if target_s == "heart":
+                            target_s = "Heart"
+                        desc = f"Transform {target_s} Color" if not is_jp else f"{target_s}の色を変換"
+                    elif eff.effect_type == EffectType.PLACE_UNDER:
+                        type_s = f" {eff.params.get('type', '')}" if "type" in eff.params else ""
+                        desc = f"Place{type_s} card under member" if not is_jp else f"メンバーの下に{type_s}置く"
+                        if eff.params.get("type") == "energy":
+                            desc = "Place Energy under member" if not is_jp else "メンバーの下にエネルギーを置く"
+                    else:
+                        try:
+                            desc = template.format(**context)
+                        except KeyError:
+                            desc = template
+
+            # Clean up descriptions
+            if eff.params.get("live") and "live" not in desc.lower() and "meta" not in desc.lower():
+                desc = f"{desc} (Live Rule)"
+
+            # Contextual refinements without spamming "Interaction" tags
+            if eff.params.get("per_energy"):
+                desc += " per Energy"
+            if eff.params.get("per_member"):
+                desc += " per Member"
+            if eff.params.get("per_live"):
+                desc += " per Live"
+
+            # Target Context
+            if eff.target == TargetType.MEMBER_SELECT:
+                desc += " (Choose member)"
+            if eff.target == TargetType.OPPONENT or eff.target == TargetType.OPPONENT_HAND:
+                if "opponent" not in desc.lower():
+                    desc += " (Opponent)"
+
+            # Trigger Remote Context
+            if eff.effect_type == EffectType.TRIGGER_REMOTE:
+                zone = eff.params.get("from", "unknown")
+                desc += f" from {zone}"
+
+            # Reveal Context
+            if eff.effect_type == EffectType.REVEAL_CARDS:
+                if "from" in eff.params and eff.params["from"] == "deck":
+                    desc += " from Deck"
+            if eff.effect_type == EffectType.MOVE_TO_DECK:
+                if eff.params.get("to_energy_deck"):
+                    desc = "Return to Energy Deck"
+                elif eff.params.get("from") == "discard":
+                    desc += " from Discard"
+
+            if eff.params.get("rest") == "discard" or eff.params.get("on_fail") == "discard":
+                if "discard" not in desc.lower():
+                    desc += " (else Discard)"
+
+            if eff.params.get("both_players"):
+                desc += " (Both Players)" if not is_jp else " (両プレイヤー)"
+
+            if eff.params.get("filter") == "live" and "live" not in desc.lower() and "ライブ" not in desc:
+                desc += " (Live Card)" if not is_jp else " (ライブカード)"
+            if eff.params.get("filter") == "energy" and "energy" not in desc.lower() and "エネ" not in desc:
+                desc += " (Energy)" if not is_jp else " (エネルギー)"
+
+            parts.append(f"→ {desc}")
+
+            # Check for Effect-level modal options (e.g. from parser fix)
+            if eff.modal_options:
+                for i, option in enumerate(eff.modal_options):
+                    opt_descs = []
+                    for sub_eff in option:
+                        template = e_desc_map.get(sub_eff.effect_type, sub_eff.effect_type.name)
+                        context = sub_eff.params.copy()
+                        context["value"] = sub_eff.value
+                        try:
+                            opt_descs.append(template.format(**context))
+                        except KeyError:
+                            opt_descs.append(template)
+                    parts.append(
+                        f"[Option {i + 1}: {' + '.join(opt_descs)}]"
+                        if not is_jp
+                        else f"[選択肢 {i + 1}: {' + '.join(opt_descs)}]"
+                    )
+
+        # Include modal options (Ability level - legacy/bullet points)
+        if self.modal_options:
+            for i, option in enumerate(self.modal_options):
+                opt_descs = []
+                for eff in option:
+                    template = e_desc_map.get(eff.effect_type, eff.effect_type.name)
+                    context = eff.params.copy()
+                    context["value"] = eff.value
+                    try:
+                        opt_descs.append(template.format(**context))
+                    except KeyError:
+                        opt_descs.append(template)
+                parts.append(
+                    f"[Option {i + 1}: {' + '.join(opt_descs)}]"
+                    if not is_jp
+                    else f"[選択肢 {i + 1}: {' + '.join(opt_descs)}]"
+                )
+
+        return " ".join(parts)

engine/models/card.py

@@ -0,0 +1,104 @@
+from dataclasses import field
+from typing import Annotated, Any, Dict, List
+
+import numpy as np
+import pydantic
+from pydantic import BeforeValidator, ConfigDict, field_serializer
+
+from engine.models.ability import Ability
+from engine.models.enums import Group, Unit, ensure_group_list, ensure_unit_list
+
+
+def ensure_ndarray(v: Any) -> Any:
+    """Validator to convert list/dict to numpy array"""
+    if isinstance(v, list):
+        return np.array(v, dtype=np.int32)
+    return v
+
+
+@pydantic.dataclasses.dataclass(config=ConfigDict(arbitrary_types_allowed=True))
+class MemberCard:
+    """Represents a member card with all attributes"""
+
+    card_id: int
+    card_no: str
+    name: str
+    cost: int
+    hearts: Annotated[
+        np.ndarray, BeforeValidator(ensure_ndarray)
+    ]  # Shape (7,) for each color count (0-5: colors, 6: any/unassigned)
+    blade_hearts: Annotated[
+        np.ndarray, BeforeValidator(ensure_ndarray)
+    ]  # Shape (7,) blade hearts by color (Index 6 = ALL)
+    blades: int
+    groups: Annotated[List[Group], BeforeValidator(ensure_group_list)] = field(default_factory=list)
+    units: Annotated[List[Unit], BeforeValidator(ensure_unit_list)] = field(default_factory=list)
+    abilities: List[Ability] = field(default_factory=list)
+    img_path: str = ""
+    rare: str = "N"  # Default to Normal (updated from rarity to match tests)
+    # Rule 2.12: カードテキスト (Card Text)
+    ability_text: str = ""
+    original_text: str = ""
+    # Rule 2.7: ブレードハート (Blade Heart Icons)
+    volume_icons: int = 0
+    draw_icons: int = 0
+    faq: List[Dict[str, Any]] = field(default_factory=list)
+
+    @field_serializer("hearts", "blade_hearts")
+    def serialize_array(self, v: np.ndarray, _info):
+        return v.tolist()
+
+    def total_hearts(self) -> int:
+        return int(np.sum(self.hearts))
+
+    def total_blade_hearts(self) -> int:
+        return int(np.sum(self.blade_hearts))
+
+
+@pydantic.dataclasses.dataclass(config=ConfigDict(arbitrary_types_allowed=True))
+class LiveCard:
+    """Represents a live/song card"""
+
+    card_id: int
+    card_no: str
+    name: str
+    score: int
+    required_hearts: Annotated[
+        np.ndarray, BeforeValidator(ensure_ndarray)
+    ]  # Shape (7,) required hearts by color (6 colors + any)
+    abilities: List[Ability] = field(default_factory=list)
+    groups: Annotated[List[Group], BeforeValidator(ensure_group_list)] = field(default_factory=list)
+    units: Annotated[List[Unit], BeforeValidator(ensure_unit_list)] = field(default_factory=list)
+    img_path: str = ""
+    rare: str = "N"
+    ability_text: str = ""
+    original_text: str = ""
+    volume_icons: int = 0
+    draw_icons: int = 0
+    blade_hearts: Annotated[np.ndarray, BeforeValidator(ensure_ndarray)] = field(
+        default_factory=lambda: np.zeros(7, dtype=np.int32)
+    )
+    faq: List[Dict[str, Any]] = field(default_factory=list)
+
+    @field_serializer("required_hearts", "blade_hearts")
+    def serialize_array(self, v: np.ndarray, _info):
+        return v.tolist()
+
+    def total_required(self) -> int:
+        return int(np.sum(self.required_hearts[:6]))  # Exclude star/any
+
+    def total_blade_hearts(self) -> int:
+        return int(np.sum(self.blade_hearts))
+
+
+@pydantic.dataclasses.dataclass(config=ConfigDict(arbitrary_types_allowed=True))
+class EnergyCard:
+    """Represents an energy card with metadata"""
+
+    card_id: int
+    card_no: str = ""
+    name: str = "Energy"
+    img_path: str = ""
+    ability_text: str = ""
+    original_text: str = ""
+    rare: str = "N"

engine/models/choice_types.py

@@ -0,0 +1,21 @@
+from enum import IntEnum
+
+
+class ChoiceType(IntEnum):
+    NONE = 0
+    TARGET_HAND = 1
+    TARGET_MEMBER = 2
+    TARGET_MEMBER_SLOT = 3
+    DISCARD_SELECT = 4
+    MODAL = 5
+    SELECT_MODE = 6
+    CHOOSE_FORMATION = 7
+    COLOR_SELECT = 8
+    SELECT_FROM_LIST = 9
+    TARGET_OPPONENT_MEMBER = 10
+    SELECT_SWAP_SOURCE = 11
+    TARGET_SUCCESS_LIVES = 12
+    TARGET_DISCARD = 13
+    TARGET_REMOVED = 14
+    TARGET_DECK = 15
+    TARGET_LIVE = 16

engine/models/context_indices.py

@@ -0,0 +1,51 @@
+from enum import IntEnum
+
+
+class ContextIndex(IntEnum):
+    """
+    Indices for the fixed-size NumPy context array (int32).
+    Size should be enough to hold all standard context variables.
+    Standard Size: 64 integers.
+    """
+
+    # Header / Meta
+    TYPE = 0  # Context Type (Trigger, Effect, etc)
+    PLAYER_ID = 1  # Owner/Active Player
+    OPPONENT_ID = 2
+    PHASE = 3
+    TURN = 4
+
+    # Source Info
+    SOURCE_CARD_ID = 5
+    SOURCE_ZONE = 6  # Zone Enum
+    SOURCE_ZONE_IDX = 7
+    SOURCE_TYPE = 8  # Member/Live
+
+    # Target Info
+    TARGET_CARD_ID = 10
+    TARGET_ZONE = 11
+    TARGET_ZONE_IDX = 12
+    TARGET_PLAYER_ID = 13
+    TARGET_COUNT = 14  # How many targets
+
+    # Payload / Parameters
+    VALUE = 20  # Generic Value (Amount, Score, etc)
+    COST_PAID = 21  # Boolean/Chek
+    ATTRIBUTE = 22  # Color/Attribute
+    GROUP = 23  # Group Enum
+    SUB_TYPE = 24  # Trigger Subtype / Effect Subtype
+
+    # Mapped Params (Generic registers)
+    PARAM_1 = 30
+    PARAM_2 = 31
+    PARAM_3 = 32
+    PARAM_4 = 33
+
+    # Flags (Bitmask)
+    FLAGS = 50  # Optional, Negated, etc.
+
+    # Execution State
+    STEP_INDEX = 60
+    TOTAL_STEPS = 61
+
+    SIZE = 64

engine/models/enums.py

@@ -0,0 +1,161 @@
+from enum import IntEnum
+from typing import Any, List
+
+
+class CardType(IntEnum):
+    """Card types in the game"""
+
+    MEMBER = 0
+    LIVE = 1
+    ENERGY = 2
+
+
+class HeartColor(IntEnum):
+    """Heart/color types (6 colors + any + rainbow)"""
+
+    PINK = 0
+    RED = 1
+    YELLOW = 2
+    GREEN = 3
+    BLUE = 4
+    PURPLE = 5
+    ANY = 6  # Colorless requirement
+    RAINBOW = 7  # Can be any color
+
+
+class Area(IntEnum):
+    """Member areas on stage"""
+
+    LEFT = 0
+    CENTER = 1
+    RIGHT = 2
+
+
+class Group(IntEnum):
+    """Card Groups (Series/Schools)"""
+
+    MUSE = 0
+    AQOURS = 1
+    NIJIGASAKI = 2
+    LIELLA = 3
+    HASUNOSORA = 4
+    LIVE = 98
+    OTHER = 99
+
+    @classmethod
+    def from_japanese_name(cls, name: str) -> "Group":
+        name = name.strip()
+        name_lower = name.lower()
+        if "ラブライブ！" == name or "μ's" in name or "muse" in name_lower:
+            return cls.MUSE
+        if "サンシャイン" in name or "aqours" in name_lower:
+            return cls.AQOURS
+        if "虹ヶ咲" in name or "nijigasaki" in name_lower:
+            return cls.NIJIGASAKI
+        if "スーパースター" in name or "liella" in name_lower:
+            return cls.LIELLA
+        if "蓮ノ空" in name or "hasunosora" in name_lower:
+            return cls.HASUNOSORA
+        return cls.OTHER
+
+
+class Unit(IntEnum):
+    """Card Units"""
+
+    PRINTEMPS = 0
+    LILY_WHITE = 1
+    BIBI = 2
+    CYARON = 3
+    AZALEA = 4
+    GUILTY_KISS = 5
+    DIVER_DIVA = 6
+    A_ZU_NA = 7
+    QU4RTZ = 8
+    R3BIRTH = 9
+    CATCHU = 10
+    KALEIDOSCORE = 11
+    SYNCRISE = 12
+    CERISE_BOUQUET = 13
+    DOLLCHESTRA = 14
+    MIRA_CRA_PARK = 15
+    EDEL_NOTE = 16
+    OTHER = 99
+
+    @classmethod
+    def from_japanese_name(cls, name: str) -> "Unit":
+        name = name.strip()
+        name_lower = name.lower()
+        if "printemps" in name_lower:
+            return cls.PRINTEMPS
+        if "lily white" in name_lower or "lilywhite" in name_lower:
+            return cls.LILY_WHITE
+        if "bibi" in name_lower:
+            return cls.BIBI
+        if "cyaron" in name_lower or "cyaron！" in name_lower:
+            return cls.CYARON
+        if "azalea" in name_lower:
+            return cls.AZALEA
+        if "guilty kiss" in name_lower or "guiltykiss" in name_lower:
+            return cls.GUILTY_KISS
+        if "diverdiva" in name_lower:
+            return cls.DIVER_DIVA
+        if "azuna" in name_lower or "a・zu・na" in name_lower:
+            return cls.A_ZU_NA
+        if "qu4rtz" in name_lower:
+            return cls.QU4RTZ
+        if "r3birth" in name_lower:
+            return cls.R3BIRTH
+        if "catchu" in name_lower:
+            return cls.CATCHU
+        if "kaleidoscore" in name_lower:
+            return cls.KALEIDOSCORE
+        if "5yncri5e" in name_lower:
+            return cls.SYNCRISE
+        if "スリーズブーケ" in name or "cerise" in name_lower:
+            return cls.CERISE_BOUQUET
+        if "dollchestra" in name_lower:
+            return cls.DOLLCHESTRA
+        if "みらくらぱーく" in name or "mira-cra" in name_lower or "mirakura" in name_lower:
+            return cls.MIRA_CRA_PARK
+        if "edelnote" in name_lower:
+            return cls.EDEL_NOTE
+        if not name:
+            return cls.OTHER
+        return cls.OTHER
+
+
+def ensure_group_list(v: Any) -> List[Group]:
+    """Validator to convert string/single Group to List[Group]"""
+    if isinstance(v, list):
+        return [
+            g if isinstance(g, Group) else Group(g) if isinstance(g, int) else Group.from_japanese_name(str(g))
+            for g in v
+        ]
+    if isinstance(v, Group):
+        return [v]
+    if isinstance(v, int):
+        return [Group(v)]
+    if isinstance(v, str):
+        if not v:
+            return []
+        parts = [p.strip() for p in v.split("\n") if p.strip()]
+        return [Group.from_japanese_name(p) for p in parts]
+    return []
+
+
+def ensure_unit_list(v: Any) -> List[Unit]:
+    """Validator to convert string/single Unit to List[Unit]"""
+    if isinstance(v, list):
+        return [
+            u if isinstance(u, Unit) else Unit(u) if isinstance(u, int) else Unit.from_japanese_name(str(u)) for u in v
+        ]
+    if isinstance(v, Unit):
+        return [v]
+    if isinstance(v, int):
+        return [Unit(v)]
+    if isinstance(v, str):
+        if not v:
+            return []
+        parts = [p.strip() for p in v.split("\n") if p.strip()]
+        return [Unit.from_japanese_name(p) for p in parts]
+    return []

engine/models/opcodes.py

@@ -0,0 +1,129 @@
+from enum import IntEnum
+
+
+class Opcode(IntEnum):
+    # Core Flow
+    NOP = 0
+    RETURN = 1
+    JUMP = 2
+    JUMP_IF_FALSE = 3
+
+    # State Modification (10-99)
+    DRAW = 10
+    ADD_BLADES = 11
+    ADD_HEARTS = 12
+    REDUCE_COST = 13
+    LOOK_DECK = 14
+    RECOVER_LIVE = 15
+    BOOST_SCORE = 16
+    RECOVER_MEMBER = 17
+    BUFF_POWER = 18
+    IMMUNITY = 19
+    MOVE_MEMBER = 20
+    SWAP_CARDS = 21
+    SEARCH_DECK = 22
+    ENERGY_CHARGE = 23
+    SET_BLADES = 24
+    SET_HEARTS = 25
+    FORMATION_CHANGE = 26
+    NEGATE_EFFECT = 27
+    ORDER_DECK = 28  # Reorder cards in deck. Attr: 0=Discard, 1=DeckTop, 2=DeckBottom
+    META_RULE = 29
+    SELECT_MODE = 30
+    MOVE_TO_DECK = 31
+    TAP_OPPONENT = 32
+    PLACE_UNDER = 33
+    FLAVOR_ACTION = 34
+    RESTRICTION = 35
+    BATON_TOUCH_MOD = 36
+    SET_SCORE = 37
+    SWAP_ZONE = 38
+    TRANSFORM_COLOR = 39
+    REVEAL_CARDS = 40
+    LOOK_AND_CHOOSE = 41
+    CHEER_REVEAL = 42
+    ACTIVATE_MEMBER = 43
+    ADD_TO_HAND = 44
+    COLOR_SELECT = 45
+    REPLACE_EFFECT = 46
+    TRIGGER_REMOTE = 47
+    REDUCE_HEART_REQ = 48
+    MODIFY_SCORE_RULE = 49
+    ADD_STAGE_ENERGY = 50  # Internal
+    SET_TAPPED = 51  # Internal
+    ADD_CONTINUOUS = 52  # Internal
+    TAP_MEMBER = 53
+    PLAY_MEMBER_FROM_HAND = 57
+    MOVE_TO_DISCARD = 58
+
+    # --- Added to fix systemic parsing issues ---
+    GRANT_ABILITY = 60
+    INCREASE_HEART_COST = 61
+    REDUCE_YELL_COUNT = 62
+    PLAY_MEMBER_FROM_DISCARD = 63
+    PAY_ENERGY = 64
+    SELECT_MEMBER = 65
+    DRAW_UNTIL = 66
+    SELECT_PLAYER = 67
+    SELECT_LIVE = 68
+    REVEAL_UNTIL = 69
+    INCREASE_COST = 70
+    PREVENT_PLAY_TO_SLOT = 71
+    SWAP_AREA = 72
+    TRANSFORM_HEART = 73
+    SELECT_CARDS = 74
+    OPPONENT_CHOOSE = 75
+    PLAY_LIVE_FROM_DISCARD = 76
+    REDUCE_LIVE_SET_LIMIT = 77
+    PREVENT_ACTIVATE = 82
+    ACTIVATE_ENERGY = 81
+
+    # Target Specification (100-199)
+    SET_TARGET_SELF = 100
+    SET_TARGET_PLAYER = 101
+    SET_TARGET_OPPONENT = 102
+    SET_TARGET_ALL_PLAYERS = 103
+    SET_TARGET_MEMBER_SELF = 104
+    SET_TARGET_MEMBER_OTHER = 105
+    SET_TARGET_CARD_HAND = 106
+    SET_TARGET_CARD_DISCARD = 107
+    SET_TARGET_CARD_DECK_TOP = 108
+    SET_TARGET_OPPONENT_HAND = 109
+    SET_TARGET_MEMBER_SELECT = 110
+    SET_TARGET_MEMBER_NAMED = 111
+
+    # Condition Checks (200-299)
+    CHECK_TURN_1 = 200
+    CHECK_HAS_MEMBER = 201
+    CHECK_HAS_COLOR = 202
+    CHECK_COUNT_STAGE = 203
+    CHECK_COUNT_HAND = 204
+    CHECK_COUNT_DISCARD = 205
+    CHECK_IS_CENTER = 206
+    CHECK_LIFE_LEAD = 207
+    CHECK_COUNT_GROUP = 208
+    CHECK_GROUP_FILTER = 209
+    CHECK_OPPONENT_HAS = 210
+    CHECK_SELF_IS_GROUP = 211
+    CHECK_MODAL_ANSWER = 212
+    CHECK_COUNT_ENERGY = 213
+    CHECK_HAS_LIVE_CARD = 214
+    CHECK_COST_CHECK = 215
+    CHECK_RARITY_CHECK = 216
+    CHECK_HAND_HAS_NO_LIVE = 217
+    CHECK_COUNT_SUCCESS_LIVE = 218
+    CHECK_OPPONENT_HAND_DIFF = 219
+    CHECK_SCORE_COMPARE = 220
+    CHECK_HAS_CHOICE = 221
+    CHECK_OPPONENT_CHOICE = 222
+    CHECK_COUNT_HEARTS = 223
+    CHECK_COUNT_BLADES = 224
+    CHECK_OPPONENT_ENERGY_DIFF = 225
+    CHECK_HAS_KEYWORD = 226
+    CHECK_DECK_REFRESHED = 227
+    CHECK_HAS_MOVED = 228
+    CHECK_HAND_INCREASED = 229
+    CHECK_COUNT_LIVE_ZONE = 230
+    CHECK_BATON = 231
+    CHECK_TYPE_CHECK = 232
+    CHECK_IS_IN_DISCARD = 233