McRogueFace API Reference - Complete Documentation

Generated on 2025-07-08 11:53:54

Table of Contents

Functions

Scene Management

createScene(name: str) -> None

Create a new empty scene with the given name.

Arguments:
name (str): 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.
Example:

mcrfpy.createScene("game_over")

setScene(scene: str, transition: str = None, duration: float = 0.0) -> None

Switch to a different scene with optional transition effect.

Arguments:
scene (str): Name of the scene to switch to
transition (str): Transition type: "fade", "slide_left", "slide_right", "slide_up", "slide_down"
duration (float): Transition duration in seconds (default: 0.0 for instant)
Raises: KeyError: If the scene doesn't exist
Example:

mcrfpy.setScene("game", "fade", 0.5)

currentScene() -> str

Get the name of the currently active scene.

Returns: str: Name of the current scene
Example:

scene_name = mcrfpy.currentScene()

sceneUI(scene: str = None) -> UICollection

Get all UI elements for a scene.

Arguments:
scene (str): Scene name. If None, uses current scene
Returns: UICollection: All UI elements in the scene
Raises: KeyError: If the specified scene doesn't exist
Example:

ui_elements = mcrfpy.sceneUI("game")

keypressScene(handler: callable) -> None

Set the keyboard event handler for the current scene.

Arguments:
handler (callable): Function that receives (key_name: str, is_pressed: bool)
Example:

def on_key(key, pressed):
    if key == "SPACE" and pressed:
        player.jump()
mcrfpy.keypressScene(on_key)

Audio

createSoundBuffer(filename: str) -> int

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

Arguments:
filename (str): Path to the sound file (WAV, OGG, FLAC)
Returns: int: Buffer ID for use with playSound()
Raises: RuntimeError: If the file cannot be loaded
Example:

jump_sound = mcrfpy.createSoundBuffer("assets/jump.wav")

loadMusic(filename: str, loop: bool = True) -> None

Load and immediately play background music from a file.

Arguments:
filename (str): Path to the music file (WAV, OGG, FLAC)
loop (bool): Whether to loop the music (default: True)
Note: Only one music track can play at a time. Loading new music stops the current track.
Example:

mcrfpy.loadMusic("assets/background.ogg", True)

playSound(buffer_id: int) -> None

Play a sound effect using a previously loaded buffer.

Arguments:
buffer_id (int): Sound buffer ID returned by createSoundBuffer()
Raises: RuntimeError: If the buffer ID is invalid
Example:

mcrfpy.playSound(jump_sound)

getMusicVolume() -> int

Get the current music volume level.

Returns: int: Current volume (0-100)
Example:

current_volume = mcrfpy.getMusicVolume()

getSoundVolume() -> int

Get the current sound effects volume level.

Returns: int: Current volume (0-100)
Example:

current_volume = mcrfpy.getSoundVolume()

setMusicVolume(volume: int) -> None

Set the global music volume.

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

mcrfpy.setMusicVolume(50)  # Set to 50% volume

setSoundVolume(volume: int) -> None

Set the global sound effects volume.

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

mcrfpy.setSoundVolume(75)  # Set to 75% volume

UI Utilities

find(name: str, scene: str = None) -> UIDrawable | None

Find the first UI element with the specified name.

Arguments:
name (str): Exact name to search for
scene (str): Scene to search in (default: current scene)
Returns: UIDrawable or None: The found element, or None if not found
Note: Searches scene UI elements and entities within grids.
Example:

button = mcrfpy.find("start_button")

findAll(pattern: str, scene: str = None) -> list

Find all UI elements matching a name pattern.

Arguments:
pattern (str): Name pattern with optional wildcards (* matches any characters)
scene (str): Scene to search in (default: current scene)
Returns: list: All matching UI elements and entities
Example:

enemies = mcrfpy.findAll("enemy_*")

System

exit() -> None

Cleanly shut down the game engine and exit the application.

Note: This immediately closes the window and terminates the program.
Example:

mcrfpy.exit()

getMetrics() -> 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
Example:

metrics = mcrfpy.getMetrics()

setTimer(name: str, handler: callable, interval: int) -> None

Create or update a recurring timer.

Arguments:
name (str): Unique identifier for the timer
handler (callable): Function called with (runtime: float) parameter
interval (int): Time between calls in milliseconds
Note: If a timer with this name exists, it will be replaced.
Example:

def update_score(runtime):
    score += 1
mcrfpy.setTimer("score_update", update_score, 1000)

delTimer(name: str) -> None

Stop and remove a timer.

Arguments:
name (str): Timer identifier to remove
Note: No error is raised if the timer doesn't exist.
Example:

mcrfpy.delTimer("score_update")

setScale(multiplier: float) -> None

Scale the game window size.

Arguments:
multiplier (float): Scale factor (e.g., 2.0 for double size)
Note: The internal resolution remains 1024x768, but the window is scaled.
Example:

mcrfpy.setScale(2.0)  # Double the window size

Classes

Animation

Animation object for animating UI properties

Properties:

property: str: Name of the property being animated (e.g., "x", "y", "scale")
duration: float: Total duration of the animation in seconds
elapsed_time: float: Time elapsed since animation started (read-only)
current_value: float: Current interpolated value of the animation (read-only)
is_running: bool: True if animation is currently running (read-only)
is_finished: bool: True if animation has completed (read-only)

Methods:

get_current_value()

Get the current interpolated value of the animation.

Returns: float: Current animation value between start and end
update(delta_time)

Update the animation by the given time delta.

delta_time (float): Time elapsed since last update in seconds
Returns: bool: True if animation is still running, False if finished
start(target)

Start the animation on a target UI element.

target (UIDrawable): The UI element to animate
Note: The target must have the property specified in the animation constructor.

Caption

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_bounds()

Get the bounding rectangle of this drawable element.

Returns: tuple: (x, y, width, height) representing the element's bounds
Note: The bounds are in screen coordinates and account for current position and size.
resize(width, height)

Resize the element to new dimensions.

width (float): New width in pixels
height (float): New height in pixels
Note: For Caption and Sprite, this may not change actual size if determined by content.
move(dx, dy)

Move the element by a relative offset.

dx (float): Horizontal offset in pixels
dy (float): Vertical offset in pixels
Note: This modifies the x and y position properties by the given amounts.

Color

SFML Color Object

Methods:

lerp(other, t)

Linearly interpolate between this color and another.

other (Color): The color to interpolate towards
t (float): Interpolation factor from 0.0 to 1.0
Returns: Color: New interpolated Color object
Example: 

mixed = red.lerp(blue, 0.5)  # 50% between red and blue
to_hex()

Convert this Color to a hexadecimal string.

Returns: str: Hex color string in format "#RRGGBB"
Example: 

hex_str = color.to_hex()  # Returns "#FF0000"
from_hex(hex_string)

Create a Color from a hexadecimal color string.

hex_string (str): Hex color string (e.g., "#FF0000" or "FF0000")
Returns: Color: New Color object from hex string
Example: 

red = Color.from_hex("#FF0000")

Drawable

Base class for all drawable UI elements

Methods:

get_bounds()

Get the bounding rectangle of this drawable element.

Returns: tuple: (x, y, width, height) representing the element's bounds
Note: The bounds are in screen coordinates and account for current position and size.
resize(width, height)

Resize the element to new dimensions.

width (float): New width in pixels
height (float): New height in pixels
Note: For Caption and Sprite, this may not change actual size if determined by content.
move(dx, dy)

Move the element by a relative offset.

dx (float): Horizontal offset in pixels
dy (float): Vertical offset in pixels
Note: This modifies the x and y position properties by the given amounts.

Entity

UIEntity objects

Methods:

get_bounds()

Get the bounding rectangle of this drawable element.

Returns: tuple: (x, y, width, height) representing the element's bounds
Note: The bounds are in screen coordinates and account for current position and size.
move(dx, dy)

Move the element by a relative offset.

dx (float): Horizontal offset in pixels
dy (float): Vertical offset in pixels
Note: This modifies the x and y position properties by the given amounts.
at(x, y)

Check if this entity is at the specified grid coordinates.

x (int): Grid x coordinate to check
y (int): Grid y coordinate to check
Returns: bool: True if entity is at position (x, y), False otherwise
resize(width, height)

Resize the element to new dimensions.

width (float): New width in pixels
height (float): New height in pixels
Note: For Caption and Sprite, this may not change actual size if determined by content.
index()

Get the index of this entity in its parent grid's entity list.

Returns: int: Index position, or -1 if not in a grid
die()

Remove this entity from its parent grid.

Note: The entity object remains valid but is no longer rendered or updated.

EntityCollection

Iterable, indexable collection of Entities

Methods:

remove(entity)

Remove the first occurrence of an entity from the collection.

entity (Entity): The entity to remove
extend(iterable)

Add all entities from an iterable to the collection.

iterable (Iterable[Entity]): Entities to add
append(entity)

Add an entity to the end of the collection.

entity (Entity): The entity to add
index(entity)

Find the index of the first occurrence of an entity.

entity (Entity): The entity to find
Returns: int: Index of entity in collection
count(entity)

Count the number of occurrences of an entity in the collection.

entity (Entity): The entity to count
Returns: int: Number of times entity appears in collection

Font

SFML Font Object

Frame

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_bounds()

Get the bounding rectangle of this drawable element.

Returns: tuple: (x, y, width, height) representing the element's bounds
Note: The bounds are in screen coordinates and account for current position and size.
resize(width, height)

Resize the element to new dimensions.

width (float): New width in pixels
height (float): New height in pixels
Note: For Caption and Sprite, this may not change actual size if determined by content.
move(dx, dy)

Move the element by a relative offset.

dx (float): Horizontal offset in pixels
dy (float): Vertical offset in pixels
Note: This modifies the x and y position properties by the given amounts.

Grid

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:

get_bounds()

Get the bounding rectangle of this drawable element.

Returns: tuple: (x, y, width, height) representing the element's bounds
Note: The bounds are in screen coordinates and account for current position and size.
at(x, y)

Get the GridPoint at the specified grid coordinates.

x (int): Grid x coordinate
y (int): Grid y coordinate
Returns: GridPoint or None: The grid point at (x, y), or None if out of bounds
resize(width, height)

Resize the element to new dimensions.

width (float): New width in pixels
height (float): New height in pixels
Note: For Caption and Sprite, this may not change actual size if determined by content.
move(dx, dy)

Move the element by a relative offset.

dx (float): Horizontal offset in pixels
dy (float): Vertical offset in pixels
Note: This modifies the x and y position properties by the given amounts.

GridPoint

UIGridPoint object

Properties:

x: int: Grid x coordinate of this point
y: int: Grid y coordinate of this point
texture_index: int: Index of the texture/sprite to display at this point
solid: bool: Whether this point blocks movement
transparent: bool: Whether this point allows light/vision through
color: Color: Color tint applied to the texture at this point

GridPointState

UIGridPointState object

Properties:

visible: bool: Whether this point is currently visible to the player
discovered: bool: Whether this point has been discovered/explored
custom_flags: int: Bitfield for custom game-specific flags

Scene

Base class for object-oriented scenes

Methods:

keypress(handler)

Register a keyboard handler function for this scene.

handler (callable): Function that takes (key_name: str, is_pressed: bool)
Note: Alternative to overriding the on_keypress method.
get_ui()

Get the UI element collection for this scene.

Returns: UICollection: Collection of all UI elements in this scene
activate()

Make this scene the active scene.

Note: Equivalent to calling setScene() with this scene's name.
register_keyboard(callable)

Register a keyboard event handler function for the scene.

callable (callable): Function that takes (key: str, action: str) parameters
Note: Alternative to overriding the on_keypress method when subclassing Scene objects.
Example: 

def handle_keyboard(key, action):
    print(f"Key '{key}' was {action}")
    if key == "q" and action == "press":
        # Handle quit
        pass
scene.register_keyboard(handle_keyboard)

Sprite

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_bounds()

Get the bounding rectangle of this drawable element.

Returns: tuple: (x, y, width, height) representing the element's bounds
Note: The bounds are in screen coordinates and account for current position and size.
resize(width, height)

Resize the element to new dimensions.

width (float): New width in pixels
height (float): New height in pixels
Note: For Caption and Sprite, this may not change actual size if determined by content.
move(dx, dy)

Move the element by a relative offset.

dx (float): Horizontal offset in pixels
dy (float): Vertical offset in pixels
Note: This modifies the x and y position properties by the given amounts.

Texture

SFML Texture Object

Timer

Timer object for scheduled callbacks

Methods:

resume()

Resume a paused timer.

Note: Has no effect if timer is not paused.
pause()

Pause the timer, stopping its callback execution.

Note: Use resume() to continue the timer from where it was paused.
cancel()

Cancel the timer and remove it from the system.

Note: After cancelling, the timer object cannot be reused.
restart()

Restart the timer from the beginning.

Note: Resets the timer's internal clock to zero.

UICollection

Iterable, indexable collection of UI objects

Methods:

remove(drawable)

Remove the first occurrence of a drawable from the collection.

drawable (UIDrawable): The drawable to remove
extend(iterable)

Add all drawables from an iterable to the collection.

iterable (Iterable[UIDrawable]): Drawables to add
append(drawable)

Add a drawable element to the end of the collection.

drawable (UIDrawable): The drawable element to add
index(drawable)

Find the index of the first occurrence of a drawable.

drawable (UIDrawable): The drawable to find
Returns: int: Index of drawable in collection
count(drawable)

Count the number of occurrences of a drawable in the collection.

drawable (UIDrawable): The drawable to count
Returns: int: Number of times drawable appears in collection

UICollectionIter

Iterator for a collection of UI objects

UIEntityCollectionIter

Iterator for a collection of UI objects

Vector

SFML Vector Object

Methods:

magnitude()

Calculate the length/magnitude of this vector.

Returns: float: The magnitude of the vector
Example: 

length = vector.magnitude()
distance_to(other)

Calculate the distance to another vector.

other (Vector): The other vector
Returns: float: Distance between the two vectors
angle()

Get the angle of this vector in radians.

Returns: float: Angle in radians from positive x-axis
dot(other)

Calculate the dot product with another vector.

other (Vector): The other vector
Returns: float: Dot product of the two vectors
normalize()

Return a unit vector in the same direction.

Returns: Vector: New normalized vector with magnitude 1.0
magnitude_squared()

Calculate the squared magnitude of this vector.

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

Create a copy of this vector.

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

Window

Window singleton for accessing and modifying the game window properties

Methods:

screenshot(filename)

Take a screenshot and save it to a file.

filename (str): Path where to save the screenshot
Note: Supports PNG, JPG, and BMP formats based on file extension.
center()

Center the window on the screen.

Note: Only works if the window is not fullscreen.
get()

Get the Window singleton instance.

Returns: Window: The singleton window object
Note: This is a static method that returns the same instance every time.

Automation Module

The mcrfpy.automation module provides testing and automation capabilities.

automation.click

Click at position

automation.doubleClick

Double click at position

automation.dragRel

Drag mouse relative to current position

automation.dragTo

Drag mouse to position

automation.hotkey

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

automation.keyDown

Press and hold a key

automation.keyUp

Release a key

automation.middleClick

Middle click at position

automation.mouseDown

Press mouse button

automation.mouseUp

Release mouse button

automation.moveRel

Move mouse relative to current position

automation.moveTo

Move mouse to absolute position

automation.onScreen

Check if coordinates are within screen bounds

automation.position

Get current mouse position as (x, y) tuple

automation.rightClick

Right click at position

automation.screenshot

Save a screenshot to the specified file

automation.scroll

Scroll wheel at position

automation.size

Get screen size as (width, height) tuple

automation.tripleClick

Triple click at position

automation.typewrite

Type text with optional interval between keystrokes