gameboy_worlds.emulation.runes_of_virtue.parsers

  1"""
  2Runes of Virtue specific game state parser implementations.
  3
  4Visual screen-region matching is used (mirroring the Pokemon module's design) so that
  5adding additional Runes of Virtue variants only requires per-variant capture data and
  6optional region overrides, not a fork of the parser logic.
  7
  8CORE DESIGN PRINCIPLE: Never branch the parser subclasses for a given variant. The inheritance tree for a parser after the game variant parser should always be a tree with only one child per layer.
  9This is to ensure that we don't double effort, any capability added to a parser will always be valid for that game variant.
 10If this principle is followed, any state tracker can always use the STRONGEST (lowest level) parser for a given variant without concern for missing functionality.
 11"""
 12
 13import os
 14from abc import ABC, abstractmethod
 15from enum import Enum
 16from typing import Dict, List, Tuple
 17
 18import numpy as np
 19from pyboy import PyBoy
 20
 21from gameboy_worlds.emulation.parser import (
 22    NamedScreenRegion,
 23    StateParser,
 24    _get_proper_regions,
 25)
 26from gameboy_worlds.utils import log_error, verify_parameters
 27
 28
 29class AgentState(Enum):
 30    """
 31    0. FREE_ROAM: The agent is freely roaming the game world.
 32    1. IN_MENU: The agent is in the inventory/status menu.
 33    2. IN_DIALOGUE: The agent is in an NPC dialogue overlay.
 34    """
 35
 36    FREE_ROAM = 0
 37    IN_MENU = 1
 38    IN_DIALOGUE = 2
 39
 40
 41class RunesOfVirtueStateParser(StateParser, ABC):
 42    """
 43    Base class for Runes of Virtue game state parsers. Uses visual screen regions to parse game state.
 44    Defines common named screen regions and methods for determining game states such as being in a menu.
 45
 46    Can be used to determine the exact AgentState.
 47    """
 48
 49    COMMON_REGIONS: List[Tuple[str, int, int, int, int]] = []
 50    """ List of common named screen regions for Runes of Virtue games. Subclasses extend this with variant-specific regions via override_regions. """
 51
 52    COMMON_MULTI_TARGET_REGIONS: List[Tuple[str, int, int, int, int]] = []
 53    """ List of common multi-target named screen regions for Runes of Virtue games. """
 54
 55    COMMON_MULTI_TARGETS: Dict[str, List[str]] = {}
 56    """ Common multi-targets for the common multi-target named screen regions. """
 57
 58    def __init__(
 59        self,
 60        variant: str,
 61        pyboy: PyBoy,
 62        parameters: dict,
 63        additional_named_screen_region_details: List[
 64            Tuple[str, int, int, int, int]
 65        ] = [],
 66        additional_multi_target_named_screen_region_details: List[
 67            Tuple[str, int, int, int, int]
 68        ] = [],
 69        override_multi_targets: Dict[str, List[str]] = {},
 70    ):
 71        """
 72        Initializes the RunesOfVirtueStateParser.
 73        Args:
 74            variant (str): The variant of the Runes of Virtue game.
 75            pyboy (PyBoy): The PyBoy emulator instance.
 76            parameters (dict): Configuration parameters for the emulator.
 77            additional_named_screen_region_details: Additional named screen region tuples to register.
 78            additional_multi_target_named_screen_region_details: Additional multi-target named screen region tuples to register.
 79            override_multi_targets: Dictionary mapping region names to lists of target names for multi-target regions.
 80        """
 81        verify_parameters(parameters)
 82        regions = _get_proper_regions(
 83            override_regions=additional_named_screen_region_details,
 84            base_regions=self.COMMON_REGIONS,
 85        )
 86        self.variant = variant
 87        if f"{variant}_rom_data_path" not in parameters:
 88            log_error(
 89                f"ROM data path not found for variant: {variant}. Add {variant}_rom_data_path to the config files. See configs/rom_data_path_vars.yaml for an example",
 90                parameters,
 91            )
 92        self.rom_data_path = parameters[f"{variant}_rom_data_path"]
 93        """ Path to the ROM data directory for the specific Runes of Virtue variant."""
 94        captures_dir = os.path.join(self.rom_data_path, "captures")
 95        named_screen_regions = []
 96        for region_name, x, y, w, h in regions:
 97            region = NamedScreenRegion(
 98                region_name,
 99                x,
100                y,
101                w,
102                h,
103                parameters=parameters,
104                target_path=os.path.join(captures_dir, region_name),
105            )
106            named_screen_regions.append(region)
107        multi_target_regions = _get_proper_regions(
108            override_regions=additional_multi_target_named_screen_region_details,
109            base_regions=self.COMMON_MULTI_TARGET_REGIONS,
110        )
111        multi_target_region_names = [region[0] for region in multi_target_regions]
112        multi_targets = {k: list(v) for k, v in self.COMMON_MULTI_TARGETS.items()}
113        for key in override_multi_targets:
114            if key in multi_targets:
115                multi_targets[key].extend(override_multi_targets[key])
116            else:
117                multi_targets[key] = list(override_multi_targets[key])
118        if not set(multi_targets.keys()).issubset(set(multi_target_region_names)):
119            log_error(
120                f"Multi-target regions provided in multi_targets do not match the defined multi-target regions. Provided: {list(multi_targets.keys())}, Defined: {multi_target_region_names}",
121                parameters,
122            )
123        for region_name, x, y, w, h in multi_target_regions:
124            region_target_paths = {}
125            subdir = os.path.join(captures_dir, region_name)
126            for target_name in multi_targets.get(region_name, []):
127                region_target_paths[target_name] = os.path.join(subdir, target_name)
128            region = NamedScreenRegion(
129                region_name,
130                x,
131                y,
132                w,
133                h,
134                parameters=parameters,
135                multi_target_paths=region_target_paths,
136            )
137            named_screen_regions.append(region)
138        super().__init__(pyboy, parameters, named_screen_regions)
139
140    @abstractmethod
141    def is_in_menu(self, current_screen: np.ndarray) -> bool:
142        """
143        Determines if the inventory/status menu is currently open.
144
145        Args:
146            current_screen (np.ndarray): The current screen frame from the emulator.
147        Returns:
148            bool: True if the menu is open, False otherwise.
149        """
150        raise NotImplementedError
151
152    @abstractmethod
153    def is_in_dialogue(self, current_screen: np.ndarray) -> bool:
154        """
155        Determines if an NPC dialogue overlay is currently visible.
156
157        Args:
158            current_screen (np.ndarray): The current screen frame from the emulator.
159        Returns:
160            bool: True if any dialogue overlay is visible, False otherwise.
161        """
162        raise NotImplementedError
163
164    def get_agent_state(self, current_screen: np.ndarray) -> AgentState:
165        """
166        Determines the current agent state based on the screen.
167
168        Args:
169            current_screen (np.ndarray): The current screen frame from the emulator.
170
171        Returns:
172            AgentState: The current agent state.
173        """
174        if self.is_in_menu(current_screen):
175            return AgentState.IN_MENU
176        if self.is_in_dialogue(current_screen):
177            return AgentState.IN_DIALOGUE
178        return AgentState.FREE_ROAM
179
180    def dialogue_box_open(self, current_screen: np.ndarray) -> bool:
181        """
182        Determines if a dialogue box is currently open.
183        """
184        box = self.capture_named_region(
185            current_frame=current_screen, name=self.get_dialogue_ocr_region_name()
186        )
187        white_rows = np.mean(box == 255, axis=(1, 2))
188        return np.count_nonzero(white_rows > 0.98) >= 10
189
190    def dialogue_box_empty(self, current_screen: np.ndarray) -> bool:
191        """
192        Determines if the dialogue OCR region has no meaningful text content.
193        """
194        box = self.capture_named_region(
195            current_frame=current_screen, name=self.get_dialogue_ocr_region_name()
196        )
197        return np.mean(box < 255) < 0.05
198
199    def get_dialogue_ocr_region_name(self) -> str:
200        return "dialogue_ocr_region"
201
202    def __repr__(self) -> str:
203        return f"<RunesOfVirtueParser(variant={self.variant})>"
204
205
206class RunesOfVirtue1StateParser(RunesOfVirtueStateParser):
207    """
208    State parser for Ultima: Runes of Virtue (1991).
209
210    Screen regions:
211    - menu_indicator: A region (y=30-50, x=20-60) that is uniformly white when the
212      inventory/status menu is open (triggered by START), and contains game world
213      content during normal gameplay.
214    - dialog_indicator: A multi-target dialogue box region shared by NPC dialogue
215      targets with the same screen coordinates.
216    - dialogue_ocr_region: Dialogue text area captured for OCR.
217    """
218
219    REGIONS = [
220        ("menu_indicator", 20, 30, 40, 20),
221    ]
222    """ Additional named screen regions specific to Runes of Virtue 1.
223    - menu_indicator: A patch above the dialogue box that goes white when the inventory/status menu opens. Open the START menu to capture this.
224    """
225
226    MULTI_TARGET_REGIONS = [
227        ("king_dialog_indicator", 5, 100, 115, 40),
228        ("dialog_indicator", 5, 90, 115, 40),
229        ("cave_indicator", 0, 0, 100, 70),
230        ("playfield_indicator", 0, 0, 144, 144),
231        ("top_playfield_indicator", 0, 0, 144, 24),
232        ("telescope_view_indicator", 40, 40, 80, 60),
233        ("death_screen_indicator", 60, 100, 30, 30),
234        ("dialogue_ocr_region", 5, 90, 135, 54),
235    ]
236    """ Additional multi-target named screen regions specific to Runes of Virtue 1. """
237
238    MULTI_TARGETS = {
239        "king_dialog_indicator": ["king_dialog"],
240        "dialog_indicator": [
241            "chuckles_dialog",
242            "gnu_gnu_1_dialog",
243            "gnu_gnu_2_dialog",
244            "sherry_dialog",
245            "dr_cat_cats_lair_dialog",
246            "cavern_of_cowardice_sherry_floor_4_dialog",
247        ],
248        "cave_indicator": [
249            "cavern_of_hatred",
250            "cavern_of_deceit",
251            "cavern_of_cowardice",
252        ],
253        "playfield_indicator": [
254            "king_dialog",
255            "chuckles_dialog",
256            "gnu_gnu_1_dialog",
257            "gnu_gnu_2_dialog",
258            "sherry_dialog",
259            "dr_cat_cats_lair_dialog",
260            "cavern_of_cowardice_sherry_floor_4_dialog",
261            "cavern_of_hatred_chest_floor_1_opened",
262            "dr_cat_dialog",
263            "ship_ridden",
264            "basement_ladder_unlocked",
265            "basement_chest_opened",
266            "cavern_of_cowardice_enter_floor_2",
267            "cavern_of_cowardice_enter_floor_3",
268            "cavern_of_cowardice_floor_3_chest_opened",
269            "cavern_of_cowardice_take_stew_floor_4",
270            "cavern_of_cowardice_obtain_coin_floor_4",
271            "cavern_of_hatred_enter_floor_2",
272            "cavern_of_hatred_sherry_floor_2_dialog",
273            "cavern_of_hatred_choose_door_with_sherry",
274            "cavern_of_hatred_choose_right_door_melissa_dialog",
275            "cavern_of_hatred_enter_floor_3",
276        ],
277        "top_playfield_indicator": [
278            "cavern_of_hatred_enter_floor_4",
279            "cavern_of_cowardice_enter_floor_4",
280        ],
281        "telescope_view_indicator": ["telescope_view"],
282        "death_screen_indicator": ["death_screen"],
283    }
284    """ Multi-target names for Runes of Virtue 1 regions. """
285
286    def __init__(
287        self,
288        pyboy: PyBoy,
289        parameters: dict,
290        override_regions: List[Tuple[str, int, int, int, int]] = [],
291        override_multi_target_regions: List[Tuple[str, int, int, int, int]] = [],
292        override_multi_targets: Dict[str, List[str]] = {},
293    ):
294        regions = _get_proper_regions(
295            override_regions=override_regions, base_regions=self.REGIONS
296        )
297        multi_target_regions = _get_proper_regions(
298            override_regions=override_multi_target_regions,
299            base_regions=self.MULTI_TARGET_REGIONS,
300        )
301        multi_targets = {k: list(v) for k, v in self.MULTI_TARGETS.items()}
302        for key in override_multi_targets:
303            if key in multi_targets:
304                multi_targets[key].extend(override_multi_targets[key])
305            else:
306                multi_targets[key] = list(override_multi_targets[key])
307        super().__init__(
308            variant="runes_of_virtue_1",
309            pyboy=pyboy,
310            parameters=parameters,
311            additional_named_screen_region_details=regions,
312            additional_multi_target_named_screen_region_details=multi_target_regions,
313            override_multi_targets=multi_targets,
314        )
315
316    _DIALOG_TARGETS = (
317        ("king_dialog_indicator", "king_dialog"),
318        ("dialog_indicator", "chuckles_dialog"),
319        ("dialog_indicator", "gnu_gnu_1_dialog"),
320        ("dialog_indicator", "gnu_gnu_2_dialog"),
321        ("dialog_indicator", "sherry_dialog"),
322        ("dialog_indicator", "dr_cat_cats_lair_dialog"),
323        ("dialog_indicator", "cavern_of_cowardice_sherry_floor_4_dialog"),
324    )
325    """ Multi-target screen regions that indicate an NPC dialogue overlay is visible. """
326
327    def is_in_menu(self, current_screen: np.ndarray) -> bool:
328        return self.named_region_matches_target(current_screen, "menu_indicator")
329
330    def is_in_dialogue(self, current_screen: np.ndarray) -> bool:
331        return any(
332            self.named_region_matches_multi_target(current_screen, name, target_name)
333            for name, target_name in self._DIALOG_TARGETS
334        )
335
336
337class RunesOfVirtue2StateParser(RunesOfVirtueStateParser):
338    """
339    State parser for Ultima: Runes of Virtue II.
340
341    Screen regions:
342    - menu_indicator: A first-pass region matching the RoV1 menu detector. Recapture
343      this for RoV2 before relying on the task.
344    - playfield_indicator: Playfield multi-target for opened-book and location screens,
345      excluding the right HUD strip.
346    - dialog_indicator: The left multi-target dialogue panel used for NPC dialogue.
347    - death_screen_indicator: Small death/game-over screen indicator matching RoV1's
348      task region.
349    """
350
351    REGIONS: List[Tuple[str, int, int, int, int]] = [
352        ("menu_indicator", 20, 30, 40, 20),
353    ]
354    """ Additional named screen regions specific to Runes of Virtue 2. """
355
356    MULTI_TARGET_REGIONS: List[Tuple[str, int, int, int, int]] = [
357        ("playfield_indicator", 0, 0, 144, 144),
358        ("left_playfield_indicator", 0, 0, 56, 144),
359        ("dialog_indicator", 5, 5, 135, 136),
360        ("death_screen_indicator", 60, 100, 30, 30),
361    ]
362    """ Additional multi-target named screen regions specific to Runes of Virtue 2. """
363
364    MULTI_TARGETS = {
365        "playfield_indicator": [
366            "book_open",
367            "cave_of_dishonour",
368            "cavern_of_hatred",
369            "cave_of_dishonour_enter_floor_2",
370            "cave_of_dishonour_enter_floor_3",
371            "kitchen_cheese_grabbed",
372            "cheese_given_to_sherry",
373            "ladder_behind_locked_door_climbed",
374            "table_map_interacted",
375            "castle_ladder_back_found",
376            "cavern_of_hatred_gate_1_unlocked",
377            "blocked_room_entered",
378            "cavern_of_hatred_ladder_room_2",
379            "cavern_of_hatred_ladder_2",
380            "cavern_of_hatred_grab_key",
381            "cavern_of_hatred_enter_floor_4",
382            "cavern_of_hatred_enter_floor_5",
383            "cavern_of_hatred_enter_floor_6",
384            "cavern_of_hatred_enter_floor_7",
385        ],
386        "left_playfield_indicator": ["cavern_of_hatred_ladder_out_found"],
387        "dialog_indicator": [
388            "nystul_dialog",
389            "blacksmith_fail_buy_shield",
390            "sherry_mouse_dialog",
391            "sandy_cook_dialog",
392            "lord_whitsaber_dialog",
393            "tholden_saved",
394            "tholden_brought_back_to_king",
395            "castle_ceremony_attended",
396        ],
397        "death_screen_indicator": ["death_screen"],
398    }
399    """ Multi-target names for Runes of Virtue 2 regions. """
400
401    def __init__(
402        self,
403        pyboy: PyBoy,
404        parameters: dict,
405        override_regions: List[Tuple[str, int, int, int, int]] = [],
406        override_multi_target_regions: List[Tuple[str, int, int, int, int]] = [],
407        override_multi_targets: Dict[str, List[str]] = {},
408    ):
409        regions = _get_proper_regions(
410            override_regions=override_regions, base_regions=self.REGIONS
411        )
412        multi_target_regions = _get_proper_regions(
413            override_regions=override_multi_target_regions,
414            base_regions=self.MULTI_TARGET_REGIONS,
415        )
416        multi_targets = {k: list(v) for k, v in self.MULTI_TARGETS.items()}
417        for key in override_multi_targets:
418            if key in multi_targets:
419                multi_targets[key].extend(override_multi_targets[key])
420            else:
421                multi_targets[key] = list(override_multi_targets[key])
422        super().__init__(
423            variant="runes_of_virtue_2",
424            pyboy=pyboy,
425            parameters=parameters,
426            additional_named_screen_region_details=regions,
427            additional_multi_target_named_screen_region_details=multi_target_regions,
428            override_multi_targets=multi_targets,
429        )
430
431    _DIALOG_TARGETS = (
432        ("dialog_indicator", "nystul_dialog"),
433        ("dialog_indicator", "blacksmith_fail_buy_shield"),
434        ("dialog_indicator", "sherry_mouse_dialog"),
435        ("dialog_indicator", "sandy_cook_dialog"),
436        ("dialog_indicator", "lord_whitsaber_dialog"),
437        ("dialog_indicator", "tholden_saved"),
438        ("dialog_indicator", "tholden_brought_back_to_king"),
439        ("dialog_indicator", "castle_ceremony_attended"),
440    )
441    """ Multi-target screen regions that indicate an NPC dialogue overlay is visible. """
442
443    def is_in_menu(self, current_screen: np.ndarray) -> bool:
444        if "menu_indicator" not in self.named_screen_regions:
445            return False
446        return self.named_region_matches_target(current_screen, "menu_indicator")
447
448    def is_in_dialogue(self, current_screen: np.ndarray) -> bool:
449        return any(
450            self.named_region_matches_multi_target(current_screen, name, target_name)
451            for name, target_name in self._DIALOG_TARGETS
452        )
453
454    def get_dialogue_ocr_region_name(self) -> str:
455        return "dialog_indicator"