# McRogueFace API Reference

Generated on 2025-10-30 11:47:05

This documentation was dynamically generated from the compiled module.

## Functions

### `createScenecreateScene(name: str) -> None`

Create a new empty scene. Note:

#### Arguments:

- name: Unique name for the new scene
- ValueError: If a scene with this name already exists

### `createSoundBuffercreateSoundBuffer(filename: str) -> int`

Load a sound effect from a file and return its buffer ID.

#### Arguments:

- filename: Path to the sound file (WAV, OGG, FLAC)

Returns: int: Buffer ID for use with playSound() RuntimeError: If the file cannot be loaded

### `currentScenecurrentScene() -> str`

Get the name of the currently active scene.

Returns: str: Name of the current scene

### `delTimerdelTimer(name: str) -> None`

Stop and remove a timer. Note:

#### Arguments:

- name: Timer identifier to remove

### `exitexit() -> None`

Cleanly shut down the game engine and exit the application. Note:

### `findfind(name: str, scene: str = None) -> UIDrawable | None`

Find the first UI element with the specified name. Note:

#### Arguments:

- name: Exact name to search for
- scene: Scene to search in (default: current scene)

Returns: Frame, Caption, Sprite, Grid, or Entity if found; None otherwise Searches scene UI elements and entities within grids.

### `findAllfindAll(pattern: str, scene: str = None) -> list`

Find all UI elements matching a name pattern.

#### Arguments:

- pattern: Name pattern with optional wildcards (* matches any characters)
- scene: Scene to search in (default: current scene)

Returns: list: All matching UI elements and entities

#### Example:

    findAll('enemy*')  # Find all elements starting with 'enemy'
        findAll('*_button')  # Find all elements ending with '_button'

### `getMetricsgetMetrics() -> dict`

Get current performance metrics.

Returns: dict: Performance data with keys: - frame_time: Last frame duration in seconds - avg_frame_time: Average frame time - fps: Frames per second - draw_calls: Number of draw calls - ui_elements: Total UI element count - visible_elements: Visible element count - current_frame: Frame counter - runtime: Total runtime in seconds

### `getMusicVolumegetMusicVolume() -> int`

Get the current music volume level.

Returns: int: Current volume (0-100)

### `getSoundVolumegetSoundVolume() -> int`

Get the current sound effects volume level.

Returns: int: Current volume (0-100)

### `keypressScenekeypressScene(handler: callable) -> None`

Set the keyboard event handler for the current scene.

#### Arguments:

- handler: Callable that receives (key_name: str, is_pressed: bool)

#### Example:

    def on_key(key, pressed):
            if key == 'A' and pressed:
                print('A key pressed')
        mcrfpy.keypressScene(on_key)

### `loadMusicloadMusic(filename: str) -> None`

Load and immediately play background music from a file. Note:

#### Arguments:

- filename: Path to the music file (WAV, OGG, FLAC)

### `playSoundplaySound(buffer_id: int) -> None`

Play a sound effect using a previously loaded buffer.

#### Arguments:

- buffer_id: Sound buffer ID returned by createSoundBuffer()
- RuntimeError: If the buffer ID is invalid

### `sceneUIsceneUI(scene: str = None) -> list`

Get all UI elements for a scene.

#### Arguments:

- scene: Scene name. If None, uses current scene

Returns: list: All UI elements (Frame, Caption, Sprite, Grid) in the scene KeyError: If the specified scene doesn't exist

### `setMusicVolumesetMusicVolume(volume: int) -> None`

Set the global music volume.

#### Arguments:

- volume: Volume level from 0 (silent) to 100 (full volume)

### `setScalesetScale(multiplier: float) -> None`

Scale the game window size. Note:

#### Arguments:

- multiplier: Scale factor (e.g., 2.0 for double size)

### `setScenesetScene(scene: str, transition: str = None, duration: float = 0.0) -> None`

Switch to a different scene with optional transition effect.

#### Arguments:

- scene: Name of the scene to switch to
- transition: Transition type ('fade', 'slide_left', 'slide_right', 'slide_up', 'slide_down')
- duration: Transition duration in seconds (default: 0.0 for instant)
- KeyError: If the scene doesn't exist
- ValueError: If the transition type is invalid

### `setSoundVolumesetSoundVolume(volume: int) -> None`

Set the global sound effects volume.

#### Arguments:

- volume: Volume level from 0 (silent) to 100 (full volume)

### `setTimersetTimer(name: str, handler: callable, interval: int) -> None`

Create or update a recurring timer. Note:

#### Arguments:

- name: Unique identifier for the timer
- handler: Function called with (runtime: float) parameter
- interval: Time between calls in milliseconds

## Classes

### Animation

Animation object for animating UI properties

#### Methods:

##### `completecomplete() -> None`

Complete the animation immediately by jumping to the final value.

##### `get_current_value(...)`

Get the current interpolated value

##### `hasValidTargethasValidTarget() -> bool`

Check if the animation still has a valid target.

Returns: True if the target still exists, False if it was destroyed.

##### `startstart(target) -> None`

Start the animation on a target UI element. Note:

target: The UI element to animate (Frame, Caption, Sprite, Grid, or Entity)

##### `updateUpdate the animation by deltaTime (returns True if still running)`

### Caption

Inherits from: Drawable

Caption(pos=None, font=None, text='', **kwargs) A text display UI element with customizable font and styling. Args: pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0) font (Font, optional): Font object for text rendering. Default: engine default font text (str, optional): The text content to display. Default: '' Keyword Args: fill_color (Color): Text fill color. Default: (255, 255, 255, 255) outline_color (Color): Text outline color. Default: (0, 0, 0, 255) outline (float): Text outline thickness. Default: 0 font_size (float): Font size in points. Default: 16 click (callable): Click event handler. Default: None visible (bool): Visibility state. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. Default: 0 name (str): Element name for finding. Default: None x (float): X position override. Default: 0 y (float): Y position override. Default: 0 Attributes: text (str): The displayed text content x, y (float): Position in pixels pos (Vector): Position as a Vector object font (Font): Font used for rendering font_size (float): Font size in points fill_color, outline_color (Color): Text appearance outline (float): Outline thickness click (callable): Click event handler visible (bool): Visibility state opacity (float): Opacity value z_index (int): Rendering order name (str): Element name w, h (float): Read-only computed size based on text and font

#### Methods:

##### `get_boundsGet bounding box as (x, y, width, height)`

##### `moveMove by relative offset (dx, dy)`

##### `resizeResize to new dimensions (width, height)`

### Color

SFML Color Object

#### Methods:

##### `from_hexCreate Color from hex string (e.g., '#FF0000' or 'FF0000')`

##### `lerp(...)`

Linearly interpolate between this color and another

##### `to_hex(...)`

Convert Color to hex string

### Drawable

Base class for all drawable UI elements

#### Methods:

##### `get_boundsGet bounding box as (x, y, width, height)`

##### `moveMove by relative offset (dx, dy)`

##### `resizeResize to new dimensions (width, height)`

### Entity

Entity(grid_pos=None, texture=None, sprite_index=0, **kwargs) A game entity that exists on a grid with sprite rendering. Args: grid_pos (tuple, optional): Grid position as (x, y) tuple. Default: (0, 0) texture (Texture, optional): Texture object for sprite. Default: default texture sprite_index (int, optional): Index into texture atlas. Default: 0 Keyword Args: grid (Grid): Grid to attach entity to. Default: None visible (bool): Visibility state. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 name (str): Element name for finding. Default: None x (float): X grid position override. Default: 0 y (float): Y grid position override. Default: 0 Attributes: pos (tuple): Grid position as (x, y) tuple x, y (float): Grid position coordinates draw_pos (tuple): Pixel position for rendering gridstate (GridPointState): Visibility state for grid points sprite_index (int): Current sprite index visible (bool): Visibility state opacity (float): Opacity value name (str): Element name

#### Methods:

##### `at(...)`

##### `die(...)`

Remove this entity from its grid

##### `get_boundsGet bounding box as (x, y, width, height)`

##### `index(...)`

Return the index of this entity in its grid's entity collection

##### `moveMove by relative offset (dx, dy)`

##### `path_topath_to(x: int, y: int) -> bool`

Find and follow path to target position using A* pathfinding.

x: Target X coordinate
y: Target Y coordinate

Returns: True if a path was found and the entity started moving, False otherwise

##### `resizeResize to new dimensions (width, height)`

##### `update_visibilityupdate_visibility() -> None`

Update entity's visibility state based on current FOV. Recomputes which cells are visible from the entity's position and updates the entity's gridstate to track explored areas. This is called automatically when the entity moves if it has a grid with perspective set.

### EntityCollection

Iterable, indexable collection of Entities

#### Methods:

##### `append(...)`

##### `count(...)`

##### `extend(...)`

##### `index(...)`

##### `remove(...)`

### Font

SFML Font Object

#### Methods:

### Frame

Inherits from: Drawable

Frame(pos=None, size=None, **kwargs) A rectangular frame UI element that can contain other drawable elements. Args: pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0) size (tuple, optional): Size as (width, height) tuple. Default: (0, 0) Keyword Args: fill_color (Color): Background fill color. Default: (0, 0, 0, 128) outline_color (Color): Border outline color. Default: (255, 255, 255, 255) outline (float): Border outline thickness. Default: 0 click (callable): Click event handler. Default: None children (list): Initial list of child drawable elements. Default: None visible (bool): Visibility state. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. Default: 0 name (str): Element name for finding. Default: None x (float): X position override. Default: 0 y (float): Y position override. Default: 0 w (float): Width override. Default: 0 h (float): Height override. Default: 0 clip_children (bool): Whether to clip children to frame bounds. Default: False Attributes: x, y (float): Position in pixels w, h (float): Size in pixels pos (Vector): Position as a Vector object fill_color, outline_color (Color): Visual appearance outline (float): Border thickness click (callable): Click event handler children (list): Collection of child drawable elements visible (bool): Visibility state opacity (float): Opacity value z_index (int): Rendering order name (str): Element name clip_children (bool): Whether to clip children to frame bounds

#### Methods:

##### `get_boundsGet bounding box as (x, y, width, height)`

##### `moveMove by relative offset (dx, dy)`

##### `resizeResize to new dimensions (width, height)`

### Grid

Inherits from: Drawable

Grid(pos=None, size=None, grid_size=None, texture=None, **kwargs) A grid-based UI element for tile-based rendering and entity management. Args: pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0) size (tuple, optional): Size as (width, height) tuple. Default: auto-calculated from grid_size grid_size (tuple, optional): Grid dimensions as (grid_x, grid_y) tuple. Default: (2, 2) texture (Texture, optional): Texture containing tile sprites. Default: default texture Keyword Args: fill_color (Color): Background fill color. Default: None click (callable): Click event handler. Default: None center_x (float): X coordinate of center point. Default: 0 center_y (float): Y coordinate of center point. Default: 0 zoom (float): Zoom level for rendering. Default: 1.0 perspective (int): Entity perspective index (-1 for omniscient). Default: -1 visible (bool): Visibility state. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. Default: 0 name (str): Element name for finding. Default: None x (float): X position override. Default: 0 y (float): Y position override. Default: 0 w (float): Width override. Default: auto-calculated h (float): Height override. Default: auto-calculated grid_x (int): Grid width override. Default: 2 grid_y (int): Grid height override. Default: 2 Attributes: x, y (float): Position in pixels w, h (float): Size in pixels pos (Vector): Position as a Vector object size (tuple): Size as (width, height) tuple center (tuple): Center point as (x, y) tuple center_x, center_y (float): Center point coordinates zoom (float): Zoom level for rendering grid_size (tuple): Grid dimensions (width, height) in tiles grid_x, grid_y (int): Grid dimensions texture (Texture): Tile texture atlas fill_color (Color): Background color entities (EntityCollection): Collection of entities in the grid perspective (int): Entity perspective index click (callable): Click event handler visible (bool): Visibility state opacity (float): Opacity value z_index (int): Rendering order name (str): Element name

#### Methods:

##### `at(...)`

##### `compute_astar_pathcompute_astar_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]`

Compute A* path between two points.

x1: Starting X coordinate
y1: Starting Y coordinate
x2: Target X coordinate
y2: Target Y coordinate
diagonal_cost: Cost of diagonal movement (default: 1.41)

Returns: List of (x, y) tuples representing the path, empty list if no path exists

##### `compute_dijkstracompute_dijkstra(root_x: int, root_y: int, diagonal_cost: float = 1.41) -> None`

Compute Dijkstra map from root position.

root_x: X coordinate of the root/target
root_y: Y coordinate of the root/target
diagonal_cost: Cost of diagonal movement (default: 1.41)

##### `compute_fovcompute_fov(x: int, y: int, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> List[Tuple[int, int, bool, bool]]`

Compute field of view from a position and return visible cells.

x: X coordinate of the viewer
y: Y coordinate of the viewer
radius: Maximum view distance (0 = unlimited)
light_walls: Whether walls are lit when visible
algorithm: FOV algorithm to use (FOV_BASIC, FOV_DIAMOND, FOV_SHADOW, FOV_PERMISSIVE_0-8)

Returns: List of tuples (x, y, visible, discovered) for all visible cells: - x, y: Grid coordinates - visible: True (all returned cells are visible) - discovered: True (FOV implies discovery)

##### `find_pathfind_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]`

Find A* path between two points.

x1: Starting X coordinate
y1: Starting Y coordinate
x2: Target X coordinate
y2: Target Y coordinate
diagonal_cost: Cost of diagonal movement (default: 1.41)

Returns: List of (x, y) tuples representing the path, empty list if no path exists

##### `get_boundsGet bounding box as (x, y, width, height)`

##### `get_dijkstra_distanceget_dijkstra_distance(x: int, y: int) -> Optional[float]`

Get distance from Dijkstra root to position.

x: X coordinate to query
y: Y coordinate to query

Returns: Distance as float, or None if position is unreachable or invalid

##### `get_dijkstra_pathget_dijkstra_path(x: int, y: int) -> List[Tuple[int, int]]`

Get path from position to Dijkstra root.

x: Starting X coordinate
y: Starting Y coordinate

Returns: List of (x, y) tuples representing path to root, empty if unreachable

##### `is_in_fovis_in_fov(x: int, y: int) -> bool`

Check if a cell is in the field of view.

x: X coordinate to check
y: Y coordinate to check

Returns: True if the cell is visible, False otherwise

##### `moveMove by relative offset (dx, dy)`

##### `resizeResize to new dimensions (width, height)`

### GridPoint

UIGridPoint object

#### Methods:

### GridPointState

UIGridPointState object

#### Methods:

### Scene

Base class for object-oriented scenes

#### Methods:

##### `activate(...)`

Make this the active scene

##### `get_ui(...)`

Get the UI element collection for this scene

##### `register_keyboardRegister a keyboard handler function (alternative to overriding on_keypress)`

### Sprite

Inherits from: Drawable

Sprite(pos=None, texture=None, sprite_index=0, **kwargs) A sprite UI element that displays a texture or portion of a texture atlas. Args: pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0) texture (Texture, optional): Texture object to display. Default: default texture sprite_index (int, optional): Index into texture atlas. Default: 0 Keyword Args: scale (float): Uniform scale factor. Default: 1.0 scale_x (float): Horizontal scale factor. Default: 1.0 scale_y (float): Vertical scale factor. Default: 1.0 click (callable): Click event handler. Default: None visible (bool): Visibility state. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. Default: 0 name (str): Element name for finding. Default: None x (float): X position override. Default: 0 y (float): Y position override. Default: 0 Attributes: x, y (float): Position in pixels pos (Vector): Position as a Vector object texture (Texture): The texture being displayed sprite_index (int): Current sprite index in texture atlas scale (float): Uniform scale factor scale_x, scale_y (float): Individual scale factors click (callable): Click event handler visible (bool): Visibility state opacity (float): Opacity value z_index (int): Rendering order name (str): Element name w, h (float): Read-only computed size based on texture and scale

#### Methods:

##### `get_boundsGet bounding box as (x, y, width, height)`

##### `moveMove by relative offset (dx, dy)`

##### `resizeResize to new dimensions (width, height)`

### Texture

SFML Texture Object

#### Methods:

### Timer

Timer(name, callback, interval, once=False) Create a timer that calls a function at regular intervals. Args: name (str): Unique identifier for the timer callback (callable): Function to call - receives (timer, runtime) args interval (int): Time between calls in milliseconds once (bool): If True, timer stops after first call. Default: False Attributes: interval (int): Time between calls in milliseconds remaining (int): Time until next call in milliseconds (read-only) paused (bool): Whether timer is paused (read-only) active (bool): Whether timer is active and not paused (read-only) callback (callable): The callback function once (bool): Whether timer stops after firing once Methods: pause(): Pause the timer, preserving time remaining resume(): Resume a paused timer cancel(): Stop and remove the timer restart(): Reset timer to start from beginning Example: def on_timer(timer, runtime): print(f'Timer {timer} fired at {runtime}ms') if runtime > 5000: timer.cancel() timer = mcrfpy.Timer('my_timer', on_timer, 1000) timer.pause() # Pause timer timer.resume() # Resume timer timer.once = True # Make it one-shot

#### Methods:

##### `cancelcancel() -> None`

Cancel the timer and remove it from the timer system. The timer will no longer fire and cannot be restarted.

##### `pausepause() -> None`

Pause the timer, preserving the time remaining until next trigger. The timer can be resumed later with resume().

##### `restartrestart() -> None`

Restart the timer from the beginning. Resets the timer to fire after a full interval from now.

##### `resumeresume() -> None`

Resume a paused timer from where it left off. Has no effect if the timer is not paused.

### UICollection

Iterable, indexable collection of UI objects

#### Methods:

##### `append(...)`

##### `count(...)`

##### `extend(...)`

##### `index(...)`

##### `remove(...)`

### UICollectionIter

Iterator for a collection of UI objects

#### Methods:

### UIEntityCollectionIter

Iterator for a collection of UI objects

#### Methods:

### Vector

SFML Vector Object

#### Methods:

##### `angleangle() -> float`

Get the angle of this vector in radians.

Returns: float: Angle in radians from positive x-axis

##### `copycopy() -> Vector`

Create a copy of this vector.

Returns: Vector: New Vector object with same x and y values

##### `distance_todistance_to(other: Vector) -> float`

Calculate the distance to another vector.

other: The other vector

Returns: float: Distance between the two vectors

##### `dotdot(other: Vector) -> float`

Calculate the dot product with another vector.

other: The other vector

Returns: float: Dot product of the two vectors

##### `magnitudemagnitude() -> float`

Calculate the length/magnitude of this vector.

Returns: float: The magnitude of the vector

##### `magnitude_squaredmagnitude_squared() -> float`

Calculate the squared magnitude of this vector. Note:

Returns: float: The squared magnitude (faster than magnitude()) Use this for comparisons to avoid expensive square root calculation.

##### `normalizenormalize() -> Vector`

Return a unit vector in the same direction. Note:

Returns: Vector: New normalized vector with magnitude 1.0 For zero vectors (magnitude 0.0), returns a zero vector rather than raising an exception

### Window

Window singleton for accessing and modifying the game window properties

#### Methods:

##### `center(...)`

Center the window on the screen

##### `get(...)`

Get the Window singleton instance

##### `screenshot(...)`

Take a screenshot. Pass filename to save to file, or get raw bytes if no filename.

## Constants

- `FOV_BASIC` (int): 0
- `FOV_DIAMOND` (int): 1
- `FOV_PERMISSIVE_0` (int): 3
- `FOV_PERMISSIVE_1` (int): 4
- `FOV_PERMISSIVE_2` (int): 5
- `FOV_PERMISSIVE_3` (int): 6
- `FOV_PERMISSIVE_4` (int): 7
- `FOV_PERMISSIVE_5` (int): 8
- `FOV_PERMISSIVE_6` (int): 9
- `FOV_PERMISSIVE_7` (int): 10
- `FOV_PERMISSIVE_8` (int): 11
- `FOV_RESTRICTIVE` (int): 12
- `FOV_SHADOW` (int): 2