# McRogueFace API Reference

Generated on 2025-07-08 10:11:22

## Overview

McRogueFace Python API\n\nCore game engine interface for creating roguelike games with Python.\n\nThis module provides:\n- Scene management (createScene, setScene, currentScene)\n- UI components (Frame, Caption, Sprite, Grid)\n- Entity system for game objects\n- Audio playback (sound effects and music)\n- Timer system for scheduled events\n- Input handling\n- Performance metrics\n\nExample:\n import mcrfpy\n \n # Create a new scene\n mcrfpy.createScene('game')\n mcrfpy.setScene('game')\n \n # Add UI elements\n frame = mcrfpy.Frame(10, 10, 200, 100)\n caption = mcrfpy.Caption('Hello World', 50, 50)\n mcrfpy.sceneUI().extend([frame, caption])\n

## Table of Contents

- [Classes](#classes)
- [Functions](#functions)
- [Automation Module](#automation-module)

## Classes

### UI Components

### class `Caption`

Inherits from: Drawable

    Caption(text='', x=0, y=0, font=None, fill_color=None, outline_color=None, outline=0, click=None)

A text display UI element with customizable font and styling.

Args:

text (str): The text content to display. Default: ''

x (float): X position in pixels. Default: 0

y (float): Y position in pixels. Default: 0

font (Font): Font object for text rendering. Default: engine default font

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

click (callable): Click event handler. Default: None

Attributes:

text (str): The displayed text content

x, y (float): Position in pixels

font (Font): Font used for rendering

fill_color, outline_color (Color): Text appearance

outline (float): Outline thickness

click (callable): Click event handler

visible (bool): Visibility state

z_index (int): Rendering order

w, h (float): Read-only computed size based on text and font

#### Methods

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

Get bounding box as (x, y, width, height)

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

Move by relative offset (dx, dy)

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

Resize to new dimensions (width, height)

### class `Entity`

Inherits from: Drawable

UIEntity objects

#### Methods

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

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

Remove this entity from its grid

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

Get bounding box as (x, y, width, height)

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

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

Move by relative offset (dx, dy)

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

Resize to new dimensions (width, height)

### class `Frame`

Inherits from: Drawable

    Frame(x=0, y=0, w=0, h=0, fill_color=None, outline_color=None, outline=0, click=None, children=None)

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

Args:

x (float): X position in pixels. Default: 0

y (float): Y position in pixels. Default: 0

w (float): Width in pixels. Default: 0

h (float): Height in pixels. Default: 0

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

Attributes:

x, y (float): Position in pixels

w, h (float): Size in pixels

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

z_index (int): Rendering order

clip_children (bool): Whether to clip children to frame bounds

#### Methods

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

Get bounding box as (x, y, width, height)

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

Move by relative offset (dx, dy)

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

Resize to new dimensions (width, height)

### class `Grid`

Inherits from: Drawable

    Grid(x=0, y=0, grid_size=(20, 20), texture=None, tile_width=16, tile_height=16, scale=1.0, click=None)

A grid-based tilemap UI element for rendering tile-based levels and game worlds.

Args:

x (float): X position in pixels. Default: 0

y (float): Y position in pixels. Default: 0

grid_size (tuple): Grid dimensions as (width, height) in tiles. Default: (20, 20)

texture (Texture): Texture atlas containing tile sprites. Default: None

tile_width (int): Width of each tile in pixels. Default: 16

tile_height (int): Height of each tile in pixels. Default: 16

scale (float): Grid scaling factor. Default: 1.0

click (callable): Click event handler. Default: None

Attributes:

x, y (float): Position in pixels

grid_size (tuple): Grid dimensions (width, height) in tiles

tile_width, tile_height (int): Tile dimensions in pixels

texture (Texture): Tile texture atlas

scale (float): Scale multiplier

points (list): 2D array of GridPoint objects for tile data

entities (list): Collection of Entity objects in the grid

background_color (Color): Grid background color

click (callable): Click event handler

visible (bool): Visibility state

z_index (int): Rendering order

#### Methods

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

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

Get bounding box as (x, y, width, height)

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

Move by relative offset (dx, dy)

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

Resize to new dimensions (width, height)

### class `Sprite`

Inherits from: Drawable

    Sprite(x=0, y=0, texture=None, sprite_index=0, scale=1.0, click=None)

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

Args:

x (float): X position in pixels. Default: 0

y (float): Y position in pixels. Default: 0

texture (Texture): Texture object to display. Default: None

sprite_index (int): Index into texture atlas (if applicable). Default: 0

scale (float): Sprite scaling factor. Default: 1.0

click (callable): Click event handler. Default: None

Attributes:

x, y (float): Position in pixels

texture (Texture): The texture being displayed

sprite_index (int): Current sprite index in texture atlas

scale (float): Scale multiplier

click (callable): Click event handler

visible (bool): Visibility state

z_index (int): Rendering order

w, h (float): Read-only computed size based on texture and scale

#### Methods

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

Get bounding box as (x, y, width, height)

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

Move by relative offset (dx, dy)

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

Resize to new dimensions (width, height)

### Collections

### class `EntityCollection`

Iterable, indexable collection of Entities

#### Methods

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

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

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

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

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

### class `UICollection`

Iterable, indexable collection of UI objects

#### Methods

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

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

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

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

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

### class `UICollectionIter`

Iterator for a collection of UI objects

### class `UIEntityCollectionIter`

Iterator for a collection of UI objects

### System Types

### class `Color`

SFML Color Object

#### Methods

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

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

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

Linearly interpolate between this color and another

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

Convert Color to hex string

### class `Font`

SFML Font Object

### class `Texture`

SFML Texture Object

### class `Vector`

SFML Vector Object

#### Methods

##### `angle(...)`

##### `copy(...)`

##### `distance_to(...)`

Return the distance to another vector

##### `dot(...)`

##### `magnitude(...)`

Return the length of the vector

##### `magnitude_squared(...)`

Return the squared length of the vector

##### `normalize(...)`

Return a unit vector in the same direction

### Other Classes

### class `Animation`

Animation object for animating UI properties

#### Methods

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

Get the current interpolated value

##### `start(...)`

Start the animation on a target UIDrawable

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

Update the animation by deltaTime (returns True if still running)

### class `Drawable`

Base class for all drawable UI elements

#### Methods

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

Get bounding box as (x, y, width, height)

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

Move by relative offset (dx, dy)

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

Resize to new dimensions (width, height)

### class `GridPoint`

UIGridPoint object

### class `GridPointState`

UIGridPointState object

### class `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 a keyboard handler function (alternative to overriding on_keypress)`

Register a keyboard handler function (alternative to overriding on_keypress)

### class `Timer`

Timer object for scheduled callbacks

#### Methods

##### `cancel(...)`

Cancel the timer and remove it from the system

##### `pause(...)`

Pause the timer

##### `restart(...)`

Restart the timer from the current time

##### `resume(...)`

Resume a paused timer

### class `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(...)`

## Functions

### Scene Management

### `createScene(name: str)`

Create a new empty scene.

*Args:*

name: Unique name for the new scene

*Raises:*

ValueError: If a scene with this name already exists

*Note:*

The scene is created but not made active. Use setScene() to switch to it.

### `currentScene()`

Get the name of the currently active scene.

*Returns:*

str: Name of the current scene

### `keypressScene(handler: callable)`

Set the keyboard event handler for the current scene.

*Args:*

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)

### `sceneUI(scene: str = None)`

Get all UI elements for a scene.

*Args:*

scene: Scene name. If None, uses current scene

*Returns:*

list: All UI elements (Frame, Caption, Sprite, Grid) in the scene

*Raises:*

KeyError: If the specified scene doesn't exist

### `setScene(scene: str, transition: str = None, duration: float = 0.0)`

Switch to a different scene with optional transition effect.

*Args:*

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)

*Raises:*

KeyError: If the scene doesn't exist

ValueError: If the transition type is invalid

### Audio

### `createSoundBuffer(filename: str)`

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

*Args:*

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

*Returns:*

int: Buffer ID for use with playSound()

*Raises:*

RuntimeError: If the file cannot be loaded

### `getMusicVolume()`

Get the current music volume level.

*Returns:*

int: Current volume (0-100)

### `getSoundVolume()`

Get the current sound effects volume level.

*Returns:*

int: Current volume (0-100)

### `loadMusic(filename: str)`

Load and immediately play background music from a file.

*Args:*

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

*Note:*

Only one music track can play at a time. Loading new music stops the current track.

### `playSound(buffer_id: int)`

Play a sound effect using a previously loaded buffer.

*Args:*

buffer_id: Sound buffer ID returned by createSoundBuffer()

*Raises:*

RuntimeError: If the buffer ID is invalid

### `setMusicVolume(volume: int)`

Set the global music volume.

*Args:*

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

### `setSoundVolume(volume: int)`

Set the global sound effects volume.

*Args:*

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

### UI Utilities

### `find(name: str, scene: str = None)`

Find the first UI element with the specified name.

*Args:*

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

*Note:*

Searches scene UI elements and entities within grids.

### `findAll(pattern: str, scene: str = None)`

Find all UI elements matching a name pattern.

*Args:*

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'

### System

### `delTimer(name: str)`

Stop and remove a timer.

*Args:*

name: Timer identifier to remove

*Note:*

No error is raised if the timer doesn't exist.

### `exit()`

Cleanly shut down the game engine and exit the application.

*Note:*

This immediately closes the window and terminates the program.

### `getMetrics()`

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

### `setScale(multiplier: float)`

Scale the game window size.

*Args:*

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

*Note:*

The internal resolution remains 1024x768, but the window is scaled.

This is deprecated - use Window.resolution instead.

### `setTimer(name: str, handler: callable, interval: int)`

Create or update a recurring timer.

*Args:*

name: Unique identifier for the timer

handler: Function called with (runtime: float) parameter

interval: Time between calls in milliseconds

*Note:*

If a timer with this name exists, it will be replaced.

The handler receives the total runtime in seconds as its argument.

## Automation Module

The `mcrfpy.automation` module provides testing and automation capabilities.

### `automation.click(x=None, y=None, clicks=1, interval=0.0, button='left') - Click at position`

click(x=None, y=None, clicks=1, interval=0.0, button='left') - Click at position

### `automation.doubleClick(x=None, y=None) - Double click at position`

doubleClick(x=None, y=None) - Double click at position

### `automation.dragRel(xOffset, yOffset, duration=0.0, button='left') - Drag mouse relative to current position`

dragRel(xOffset, yOffset, duration=0.0, button='left') - Drag mouse relative to current position

### `automation.dragTo(x, y, duration=0.0, button='left') - Drag mouse to position`

dragTo(x, y, duration=0.0, button='left') - Drag mouse to position

### `automation.hotkey(*keys) - Press a hotkey combination (e.g., hotkey('ctrl', 'c'))`

hotkey(*keys) - Press a hotkey combination (e.g., hotkey('ctrl', 'c'))

### `automation.keyDown(key) - Press and hold a key`

keyDown(key) - Press and hold a key

### `automation.keyUp(key) - Release a key`

keyUp(key) - Release a key

### `automation.middleClick(x=None, y=None) - Middle click at position`

middleClick(x=None, y=None) - Middle click at position

### `automation.mouseDown(x=None, y=None, button='left') - Press mouse button`

mouseDown(x=None, y=None, button='left') - Press mouse button

### `automation.mouseUp(x=None, y=None, button='left') - Release mouse button`

mouseUp(x=None, y=None, button='left') - Release mouse button

### `automation.moveRel(xOffset, yOffset, duration=0.0) - Move mouse relative to current position`

moveRel(xOffset, yOffset, duration=0.0) - Move mouse relative to current position

### `automation.moveTo(x, y, duration=0.0) - Move mouse to absolute position`

moveTo(x, y, duration=0.0) - Move mouse to absolute position

### `automation.onScreen(x, y) - Check if coordinates are within screen bounds`

onScreen(x, y) - Check if coordinates are within screen bounds

### `automation.position() - Get current mouse position as (x, y) tuple`

position() - Get current mouse position as (x, y) tuple

### `automation.rightClick(x=None, y=None) - Right click at position`

rightClick(x=None, y=None) - Right click at position

### `automation.screenshot(filename) - Save a screenshot to the specified file`

screenshot(filename) - Save a screenshot to the specified file

### `automation.scroll(clicks, x=None, y=None) - Scroll wheel at position`

scroll(clicks, x=None, y=None) - Scroll wheel at position

### `automation.size() - Get screen size as (width, height) tuple`

size() - Get screen size as (width, height) tuple

### `automation.tripleClick(x=None, y=None) - Triple click at position`

tripleClick(x=None, y=None) - Triple click at position

### `automation.typewrite(message, interval=0.0) - Type text with optional interval between keystrokes`

typewrite(message, interval=0.0) - Type text with optional interval between keystrokes