633 lines
18 KiB
Python
633 lines
18 KiB
Python
"""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
|
|
|
|
# Type aliases
|
|
UIElement = Union['Frame', 'Caption', 'Sprite', 'Grid']
|
|
Transition = Union[str, None]
|
|
|
|
# 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) -> None:
|
|
"""Start the animation."""
|
|
...
|
|
|
|
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."""
|
|
...
|