McRogueFace/docs/API_REFERENCE_COMPLETE.md

McRogueFace API Reference

Generated on 2025-07-15 21:28:42

Overview

McRogueFace Python API

Core game engine interface for creating roguelike games with Python.

This module provides:

• Scene management (createScene, setScene, currentScene)
• UI components (Frame, Caption, Sprite, Grid)
• Entity system for game objects
• Audio playback (sound effects and music)
• Timer system for scheduled events
• Input handling
• Performance metrics

Example: import mcrfpy

# Create a new scene
mcrfpy.createScene('game')
mcrfpy.setScene('game')

# Add UI elements
frame = mcrfpy.Frame(10, 10, 200, 100)
caption = mcrfpy.Caption('Hello World', 50, 50)
mcrfpy.sceneUI().extend([frame, caption])

Table of Contents

• Functions
  • Scene Management
  • Audio
  • UI Utilities
  • System
• Classes
  • UI Components
  • Collections
  • System Types
  • Other Classes
• Automation Module

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

UI Components

class Frame

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

Methods

resize(width, height)

Resize the element to new dimensions.

Arguments:

• 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.

Arguments:

• 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.

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.

---

class Caption

A text display UI element with customizable font and styling.

Methods

resize(width, height)

Resize the element to new dimensions.

Arguments:

• 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.

Arguments:

• 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.

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.

---

class Sprite

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

Methods

resize(width, height)

Resize the element to new dimensions.

Arguments:

• 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.

Arguments:

• 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.

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.

---

class Grid

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

Methods

resize(width, height)

Resize the element to new dimensions.

Arguments:

• 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.

at(x, y)

Get the GridPoint at the specified grid coordinates.

Arguments:

• 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

move(dx, dy)

Move the element by a relative offset.

Arguments:

• 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.

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.

---

class Entity

Game entity that can be placed in a Grid.

Methods

move(dx, dy)

Move the element by a relative offset.

Arguments:

• 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.

Arguments:

• 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

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.

die()

Remove this entity from its parent grid.

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

resize(width, height)

Resize the element to new dimensions.

Arguments:

• 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

---

Collections

class EntityCollection

Container for Entity objects in a Grid. Supports iteration and indexing.

Methods

remove(entity)

Remove the first occurrence of an entity from the collection.

Arguments:

• entity (Entity): The entity to remove

Raises: ValueError: If entity is not in collection

extend(iterable)

Add all entities from an iterable to the collection.

Arguments:

• iterable (Iterable[Entity]): Entities to add

count(entity)

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

Arguments:

• entity (Entity): The entity to count

Returns: int: Number of times entity appears in collection

index(entity)

Find the index of the first occurrence of an entity.

Arguments:

• entity (Entity): The entity to find

Returns: int: Index of entity in collection

Raises: ValueError: If entity is not in collection

append(entity)

Add an entity to the end of the collection.

Arguments:

• entity (Entity): The entity to add

---

class UICollection

Container for UI drawable elements. Supports iteration and indexing.

Methods

remove(drawable)

Remove the first occurrence of a drawable from the collection.

Arguments:

• drawable (UIDrawable): The drawable to remove

Raises: ValueError: If drawable is not in collection

extend(iterable)

Add all drawables from an iterable to the collection.

Arguments:

• iterable (Iterable[UIDrawable]): Drawables to add

count(drawable)

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

Arguments:

• drawable (UIDrawable): The drawable to count

Returns: int: Number of times drawable appears in collection

index(drawable)

Find the index of the first occurrence of a drawable.

Arguments:

• drawable (UIDrawable): The drawable to find

Returns: int: Index of drawable in collection

Raises: ValueError: If drawable is not in collection

append(drawable)

Add a drawable element to the end of the collection.

Arguments:

• drawable (UIDrawable): The drawable element to add

---

class UICollectionIter

Iterator for UICollection. Automatically created when iterating over a UICollection.

---

class UIEntityCollectionIter

Iterator for EntityCollection. Automatically created when iterating over an EntityCollection.

---

System Types

class Color

RGBA color representation.

Methods

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.

Arguments:

• 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")

lerp(other, t)

Linearly interpolate between this color and another.

Arguments:

• 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

---

class Vector

2D vector for positions and directions.

Methods

magnitude()

Calculate the length/magnitude of this vector.

Returns: float: The magnitude of the vector

normalize()

Return a unit vector in the same direction.

Returns: Vector: New normalized vector with magnitude 1.0

Raises: ValueError: If vector has zero magnitude

dot(other)

Calculate the dot product with another vector.

Arguments:

• other (Vector): The other vector

Returns: float: Dot product of the two vectors

distance_to(other)

Calculate the distance to another vector.

Arguments:

• other (Vector): The other vector

Returns: float: Distance between the two vectors

copy()

Create a copy of this vector.

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

angle()

Get the angle of this vector in radians.

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

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.

---

class Texture

Texture object for image data.

---

class Font

Font object for text rendering.

---

Other Classes

class Animation

Animate UI element properties over time.

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.

Arguments:

• 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.

Arguments:

• target (UIDrawable): The UI element to animate

Note: The target must have the property specified in the animation constructor.

---

class Drawable

Base class for all drawable UI elements.

Methods

resize(width, height)

Resize the element to new dimensions.

Arguments:

• 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.

Arguments:

• 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.

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.

---

class GridPoint

Represents a single tile in a Grid.

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

---

class GridPointState

State information for a GridPoint.

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

---

class Scene

Base class for object-oriented scenes.

Methods

register_keyboard(callable)

Register a keyboard event handler function for the scene.

Arguments:

• 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}")
scene.register_keyboard(handle_keyboard)

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.

keypress(handler)

Register a keyboard handler function for this scene.

Arguments:

• handler (callable): Function that takes (key_name: str, is_pressed: bool)

Note: Alternative to overriding the on_keypress method.

---

class Timer

Timer object for scheduled callbacks.

Methods

pause()

Pause the timer, stopping its callback execution.

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

resume()

Resume a paused timer.

Note: Has no effect if timer is not paused.

restart()

Restart the timer from the beginning.

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

cancel()

Cancel the timer and remove it from the system.

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

---

class Window

Window singleton for accessing and modifying the game window properties.

Methods

screenshot(filename)

Take a screenshot and save it to a file.

Arguments:

• filename (str): Path where to save the screenshot

Note: Supports PNG, JPG, and BMP formats based on file extension.

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.

center()

Center the window on the screen.

Note: Only works if the window is not fullscreen.

---

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

---