McRogueFace/stubs/mcrfpy.pyi

"""Type stubs for McRogueFace Python API.

Core game engine interface for creating roguelike games with Python.
"""

from typing import Any, List, Dict, Tuple, Optional, Callable, Union, overload, Literal

# Type aliases
UIElement = Union['Frame', 'Caption', 'Sprite', 'Grid']
Transition = Union[str, None]
ConflictMode = Literal['replace', 'queue', 'error']

# Classes

class Color:
    """SFML Color Object for RGBA colors."""
    
    r: int
    g: int
    b: int
    a: int
    
    @overload
    def __init__(self) -> None: ...
    @overload
    def __init__(self, r: int, g: int, b: int, a: int = 255) -> None: ...
    
    def from_hex(self, hex_string: str) -> 'Color':
        """Create color from hex string (e.g., '#FF0000' or 'FF0000')."""
        ...
    
    def to_hex(self) -> str:
        """Convert color to hex string format."""
        ...
    
    def lerp(self, other: 'Color', t: float) -> 'Color':
        """Linear interpolation between two colors."""
        ...

class Vector:
    """SFML Vector Object for 2D coordinates."""
    
    x: float
    y: float
    
    @overload
    def __init__(self) -> None: ...
    @overload
    def __init__(self, x: float, y: float) -> None: ...
    
    def add(self, other: 'Vector') -> 'Vector': ...
    def subtract(self, other: 'Vector') -> 'Vector': ...
    def multiply(self, scalar: float) -> 'Vector': ...
    def divide(self, scalar: float) -> 'Vector': ...
    def distance(self, other: 'Vector') -> float: ...
    def normalize(self) -> 'Vector': ...
    def dot(self, other: 'Vector') -> float: ...

class Texture:
    """SFML Texture Object for images."""
    
    def __init__(self, filename: str) -> None: ...
    
    filename: str
    width: int
    height: int
    sprite_count: int

class Font:
    """SFML Font Object for text rendering."""
    
    def __init__(self, filename: str) -> None: ...
    
    filename: str
    family: str

class Drawable:
    """Base class for all drawable UI elements."""
    
    x: float
    y: float
    visible: bool
    z_index: int
    name: str
    pos: Vector
    
    def get_bounds(self) -> Tuple[float, float, float, float]:
        """Get bounding box as (x, y, width, height)."""
        ...
    
    def move(self, dx: float, dy: float) -> None:
        """Move by relative offset (dx, dy)."""
        ...
    
    def resize(self, width: float, height: float) -> None:
        """Resize to new dimensions (width, height)."""
        ...

class Frame(Drawable):
    """Frame(x=0, y=0, w=0, h=0, fill_color=None, outline_color=None, outline=0, on_click=None, children=None)

    A rectangular frame UI element that can contain other drawable elements.
    """

    @overload
    def __init__(self) -> None: ...
    @overload
    def __init__(self, x: float = 0, y: float = 0, w: float = 0, h: float = 0,
                 fill_color: Optional[Color] = None, outline_color: Optional[Color] = None,
                 outline: float = 0, on_click: Optional[Callable] = None,
                 children: Optional[List[UIElement]] = None) -> None: ...

    w: float
    h: float
    fill_color: Color
    outline_color: Color
    outline: float
    on_click: Optional[Callable[[float, float, int], None]]
    on_enter: Optional[Callable[[], None]]
    on_exit: Optional[Callable[[], None]]
    on_move: Optional[Callable[[float, float], None]]
    children: 'UICollection'
    clip_children: bool

class Caption(Drawable):
    """Caption(text='', x=0, y=0, font=None, fill_color=None, outline_color=None, outline=0, on_click=None)

    A text display UI element with customizable font and styling.
    """

    @overload
    def __init__(self) -> None: ...
    @overload
    def __init__(self, text: str = '', x: float = 0, y: float = 0,
                 font: Optional[Font] = None, fill_color: Optional[Color] = None,
                 outline_color: Optional[Color] = None, outline: float = 0,
                 on_click: Optional[Callable] = None) -> None: ...

    text: str
    font: Font
    fill_color: Color
    outline_color: Color
    outline: float
    on_click: Optional[Callable[[float, float, int], None]]
    on_enter: Optional[Callable[[], None]]
    on_exit: Optional[Callable[[], None]]
    on_move: Optional[Callable[[float, float], None]]
    w: float  # Read-only, computed from text
    h: float  # Read-only, computed from text

class Sprite(Drawable):
    """Sprite(x=0, y=0, texture=None, sprite_index=0, scale=1.0, on_click=None)

    A sprite UI element that displays a texture or portion of a texture atlas.
    """

    @overload
    def __init__(self) -> None: ...
    @overload
    def __init__(self, x: float = 0, y: float = 0, texture: Optional[Texture] = None,
                 sprite_index: int = 0, scale: float = 1.0,
                 on_click: Optional[Callable] = None) -> None: ...

    texture: Texture
    sprite_index: int
    scale: float
    on_click: Optional[Callable[[float, float, int], None]]
    on_enter: Optional[Callable[[], None]]
    on_exit: Optional[Callable[[], None]]
    on_move: Optional[Callable[[float, float], None]]
    w: float  # Read-only, computed from texture
    h: float  # Read-only, computed from texture

class Grid(Drawable):
    """Grid(pos=None, size=None, grid_size=(20, 20), texture=None, on_click=None, layers=None)

    A grid-based tilemap UI element for rendering tile-based levels and game worlds.
    Supports multiple rendering layers (ColorLayer, TileLayer) and entity management.
    """

    @overload
    def __init__(self) -> None: ...
    @overload
    def __init__(self, pos: Optional[Tuple[float, float]] = None,
                 size: Optional[Tuple[float, float]] = None,
                 grid_size: Tuple[int, int] = (20, 20),
                 texture: Optional[Texture] = None,
                 on_click: Optional[Callable] = None,
                 layers: Optional[Dict[str, str]] = None) -> None: ...

    grid_size: Tuple[int, int]
    grid_x: int  # Read-only grid width
    grid_y: int  # Read-only grid height
    texture: Texture
    zoom: float
    center: Tuple[float, float]
    center_x: float
    center_y: float
    fill_color: Color
    entities: 'EntityCollection'
    children: 'UICollection'
    layers: List[Union['ColorLayer', 'TileLayer']]
    hovered_cell: Optional[Tuple[int, int]]

    # Mouse event handlers
    on_click: Optional[Callable[[float, float, int], None]]
    on_enter: Optional[Callable[[], None]]
    on_exit: Optional[Callable[[], None]]
    on_move: Optional[Callable[[float, float], None]]

    # Grid cell event handlers
    on_cell_click: Optional[Callable[[int, int], None]]
    on_cell_enter: Optional[Callable[[int, int], None]]
    on_cell_exit: Optional[Callable[[int, int], None]]

    def at(self, x: int, y: int) -> 'GridPoint':
        """Get grid point at tile coordinates."""
        ...

    def add_layer(self, type: str, z_index: int = -1,
                  texture: Optional[Texture] = None) -> Union['ColorLayer', 'TileLayer']:
        """Add a rendering layer. type='color' or 'tile'. z_index<0 = below entities."""
        ...

    def remove_layer(self, layer: Union['ColorLayer', 'TileLayer']) -> None:
        """Remove a layer from the grid."""
        ...

    def compute_fov(self, x: int, y: int, radius: int) -> None:
        """Compute field of view from a position."""
        ...

    def is_in_fov(self, x: int, y: int) -> bool:
        """Check if a cell is visible in the current FOV."""
        ...

    def compute_dijkstra(self, sources: List[Tuple[int, int]], max_cost: float = -1) -> None:
        """Compute Dijkstra distance map from source points."""
        ...

    def get_dijkstra_distance(self, x: int, y: int) -> float:
        """Get distance to nearest source for a cell."""
        ...

    def get_dijkstra_path(self, x: int, y: int) -> List[Tuple[int, int]]:
        """Get path from cell to nearest source."""
        ...

    def find_path(self, x1: int, y1: int, x2: int, y2: int) -> List[Tuple[int, int]]:
        """Find A* path between two cells."""
        ...

class GridPoint:
    """Grid point representing a single tile."""
    
    texture_index: int
    solid: bool
    color: Color

class GridPointState:
    """State information for a grid point."""

    texture_index: int
    color: Color

class ColorLayer:
    """Grid layer that renders solid colors per cell."""

    z_index: int
    visible: bool
    grid_size: Tuple[int, int]

    def fill(self, color: Color) -> None:
        """Fill all cells with a color."""
        ...

    def set(self, x: int, y: int, color: Color) -> None:
        """Set color at a specific cell."""
        ...

    def at(self, x: int, y: int) -> Color:
        """Get color at a specific cell."""
        ...

class TileLayer:
    """Grid layer that renders texture tiles per cell."""

    z_index: int
    visible: bool
    texture: Texture
    grid_size: Tuple[int, int]

    def fill(self, sprite_index: int) -> None:
        """Fill all cells with a sprite index."""
        ...

    def set(self, x: int, y: int, sprite_index: int) -> None:
        """Set tile sprite at a specific cell."""
        ...

    def at(self, x: int, y: int) -> int:
        """Get tile sprite index at a specific cell."""
        ...

class Entity(Drawable):
    """Entity(grid_x=0, grid_y=0, texture=None, sprite_index=0, name='')
    
    Game entity that lives within a Grid.
    """
    
    @overload
    def __init__(self) -> None: ...
    @overload
    def __init__(self, grid_x: float = 0, grid_y: float = 0, texture: Optional[Texture] = None,
                 sprite_index: int = 0, name: str = '') -> None: ...
    
    grid_x: float
    grid_y: float
    texture: Texture
    sprite_index: int
    grid: Optional[Grid]
    
    def at(self, grid_x: float, grid_y: float) -> None:
        """Move entity to grid position."""
        ...
    
    def die(self) -> None:
        """Remove entity from its grid."""
        ...
    
    def index(self) -> int:
        """Get index in parent grid's entity collection."""
        ...

class UICollection:
    """Collection of UI drawable elements (Frame, Caption, Sprite, Grid)."""
    
    def __len__(self) -> int: ...
    def __getitem__(self, index: int) -> UIElement: ...
    def __setitem__(self, index: int, value: UIElement) -> None: ...
    def __delitem__(self, index: int) -> None: ...
    def __contains__(self, item: UIElement) -> bool: ...
    def __iter__(self) -> Any: ...
    def __add__(self, other: 'UICollection') -> 'UICollection': ...
    def __iadd__(self, other: 'UICollection') -> 'UICollection': ...
    
    def append(self, item: UIElement) -> None: ...
    def extend(self, items: List[UIElement]) -> None: ...
    def remove(self, item: UIElement) -> None: ...
    def index(self, item: UIElement) -> int: ...
    def count(self, item: UIElement) -> int: ...

class EntityCollection:
    """Collection of Entity objects."""
    
    def __len__(self) -> int: ...
    def __getitem__(self, index: int) -> Entity: ...
    def __setitem__(self, index: int, value: Entity) -> None: ...
    def __delitem__(self, index: int) -> None: ...
    def __contains__(self, item: Entity) -> bool: ...
    def __iter__(self) -> Any: ...
    def __add__(self, other: 'EntityCollection') -> 'EntityCollection': ...
    def __iadd__(self, other: 'EntityCollection') -> 'EntityCollection': ...
    
    def append(self, item: Entity) -> None: ...
    def extend(self, items: List[Entity]) -> None: ...
    def remove(self, item: Entity) -> None: ...
    def index(self, item: Entity) -> int: ...
    def count(self, item: Entity) -> int: ...

class Scene:
    """Base class for object-oriented scenes."""
    
    name: str
    
    def __init__(self, name: str) -> None: ...
    
    def activate(self) -> None:
        """Called when scene becomes active."""
        ...
    
    def deactivate(self) -> None:
        """Called when scene becomes inactive."""
        ...
    
    def get_ui(self) -> UICollection:
        """Get UI elements collection."""
        ...
    
    def on_keypress(self, key: str, pressed: bool) -> None:
        """Handle keyboard events."""
        ...
    
    def on_click(self, x: float, y: float, button: int) -> None:
        """Handle mouse clicks."""
        ...
    
    def on_enter(self) -> None:
        """Called when entering the scene."""
        ...
    
    def on_exit(self) -> None:
        """Called when leaving the scene."""
        ...
    
    def on_resize(self, width: int, height: int) -> None:
        """Handle window resize events."""
        ...
    
    def update(self, dt: float) -> None:
        """Update scene logic."""
        ...

class Timer:
    """Timer object for scheduled callbacks."""
    
    name: str
    interval: int
    active: bool
    
    def __init__(self, name: str, callback: Callable[[float], None], interval: int) -> None: ...
    
    def pause(self) -> None:
        """Pause the timer."""
        ...
    
    def resume(self) -> None:
        """Resume the timer."""
        ...
    
    def cancel(self) -> None:
        """Cancel and remove the timer."""
        ...

class Window:
    """Window singleton for managing the game window."""
    
    resolution: Tuple[int, int]
    fullscreen: bool
    vsync: bool
    title: str
    fps_limit: int
    game_resolution: Tuple[int, int]
    scaling_mode: str
    
    @staticmethod
    def get() -> 'Window':
        """Get the window singleton instance."""
        ...

class Animation:
    """Animation object for animating UI properties."""
    
    target: Any
    property: str
    duration: float
    easing: str
    loop: bool
    on_complete: Optional[Callable]
    
    def __init__(self, target: Any, property: str, start_value: Any, end_value: Any,
                 duration: float, easing: str = 'linear', loop: bool = False,
                 on_complete: Optional[Callable] = None) -> None: ...
    
    def start(self, target: Any, conflict_mode: ConflictMode = 'replace') -> None:
        """Start the animation on a target UI element.

        Args:
            target: The UI element to animate (Frame, Caption, Sprite, Grid, or Entity)
            conflict_mode: How to handle conflicts if property is already animating:
                - 'replace' (default): Complete existing animation and start new one
                - 'queue': Wait for existing animation to complete
                - 'error': Raise RuntimeError if property is busy

        Raises:
            RuntimeError: When conflict_mode='error' and property is already animating
        """
        ...
    
    def update(self, dt: float) -> bool:
        """Update animation, returns True if still running."""
        ...
    
    def get_current_value(self) -> Any:
        """Get the current interpolated value."""
        ...

# Module functions

def createSoundBuffer(filename: str) -> int:
    """Load a sound effect from a file and return its buffer ID."""
    ...

def loadMusic(filename: str) -> None:
    """Load and immediately play background music from a file."""
    ...

def setMusicVolume(volume: int) -> None:
    """Set the global music volume (0-100)."""
    ...

def setSoundVolume(volume: int) -> None:
    """Set the global sound effects volume (0-100)."""
    ...

def playSound(buffer_id: int) -> None:
    """Play a sound effect using a previously loaded buffer."""
    ...

def getMusicVolume() -> int:
    """Get the current music volume level (0-100)."""
    ...

def getSoundVolume() -> int:
    """Get the current sound effects volume level (0-100)."""
    ...

def sceneUI(scene: Optional[str] = None) -> UICollection:
    """Get all UI elements for a scene."""
    ...

def currentScene() -> str:
    """Get the name of the currently active scene."""
    ...

def setScene(scene: str, transition: Optional[str] = None, duration: float = 0.0) -> None:
    """Switch to a different scene with optional transition effect."""
    ...

def createScene(name: str) -> None:
    """Create a new empty scene."""
    ...

def keypressScene(handler: Callable[[str, bool], None]) -> None:
    """Set the keyboard event handler for the current scene."""
    ...

def setTimer(name: str, handler: Callable[[float], None], interval: int) -> None:
    """Create or update a recurring timer."""
    ...

def delTimer(name: str) -> None:
    """Stop and remove a timer."""
    ...

def exit() -> None:
    """Cleanly shut down the game engine and exit the application."""
    ...

def setScale(multiplier: float) -> None:
    """Scale the game window size (deprecated - use Window.resolution)."""
    ...

def find(name: str, scene: Optional[str] = None) -> Optional[UIElement]:
    """Find the first UI element with the specified name."""
    ...

def findAll(pattern: str, scene: Optional[str] = None) -> List[UIElement]:
    """Find all UI elements matching a name pattern (supports * wildcards)."""
    ...

def getMetrics() -> Dict[str, Union[int, float]]:
    """Get current performance metrics."""
    ...

# Submodule
class automation:
    """Automation API for testing and scripting."""
    
    @staticmethod
    def screenshot(filename: str) -> bool:
        """Save a screenshot to the specified file."""
        ...
    
    @staticmethod
    def position() -> Tuple[int, int]:
        """Get current mouse position as (x, y) tuple."""
        ...
    
    @staticmethod
    def size() -> Tuple[int, int]:
        """Get screen size as (width, height) tuple."""
        ...
    
    @staticmethod
    def onScreen(x: int, y: int) -> bool:
        """Check if coordinates are within screen bounds."""
        ...
    
    @staticmethod
    def moveTo(x: int, y: int, duration: float = 0.0) -> None:
        """Move mouse to absolute position."""
        ...
    
    @staticmethod
    def moveRel(xOffset: int, yOffset: int, duration: float = 0.0) -> None:
        """Move mouse relative to current position."""
        ...
    
    @staticmethod
    def dragTo(x: int, y: int, duration: float = 0.0, button: str = 'left') -> None:
        """Drag mouse to position."""
        ...
    
    @staticmethod
    def dragRel(xOffset: int, yOffset: int, duration: float = 0.0, button: str = 'left') -> None:
        """Drag mouse relative to current position."""
        ...
    
    @staticmethod
    def click(x: Optional[int] = None, y: Optional[int] = None, clicks: int = 1,
              interval: float = 0.0, button: str = 'left') -> None:
        """Click mouse at position."""
        ...
    
    @staticmethod
    def mouseDown(x: Optional[int] = None, y: Optional[int] = None, button: str = 'left') -> None:
        """Press mouse button down."""
        ...
    
    @staticmethod
    def mouseUp(x: Optional[int] = None, y: Optional[int] = None, button: str = 'left') -> None:
        """Release mouse button."""
        ...
    
    @staticmethod
    def keyDown(key: str) -> None:
        """Press key down."""
        ...
    
    @staticmethod
    def keyUp(key: str) -> None:
        """Release key."""
        ...
    
    @staticmethod
    def press(key: str) -> None:
        """Press and release a key."""
        ...
    
    @staticmethod
    def typewrite(text: str, interval: float = 0.0) -> None:
        """Type text with optional interval between characters."""
        ...