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
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])
Inherits from: Drawable
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
get_bounds(...)Get bounding box as (x, y, width, height)
move(...)Move by relative offset (dx, dy)
resize(...)Resize to new dimensions (width, height)
Inherits from: Drawable
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
get_bounds(...)Get bounding box as (x, y, width, height)
move(...)Move by relative offset (dx, dy)
resize(...)Resize to new dimensions (width, height)
Inherits from: Drawable
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
get_bounds(...)Get bounding box as (x, y, width, height)
move(...)Move by relative offset (dx, dy)
resize(...)Resize to new dimensions (width, height)
Inherits from: Drawable
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
at(x, y)Get the GridPoint at the specified coordinates.
Arguments:
x (int)y (int)Returns: GridPoint: The tile at (x, y), or None if out of bounds
get_bounds(...)Get bounding box as (x, y, width, height)
move(...)Move by relative offset (dx, dy)
resize(...)Resize to new dimensions (width, height)
Entity(x=0, y=0, sprite_id=0)
Game entity that can be placed in a Grid.
x (int)y (int)sprite_id (int)at(x, y)Check if entity is at given grid coordinates.
Arguments:
x (int)y (int)Returns: bool: True if entity is at (x, y)
die()Remove this entity from its parent grid.
Note: The entity object remains valid but is no longer rendered.
get_bounds(...)Get bounding box as (x, y, width, height)
index(...)Return the index of this entity in its grid's entity collection
move(...)Move by relative offset (dx, dy)
resize(...)Resize to new dimensions (width, height)
entity = mcrfpy.Entity(5, 10, 42)
entity.move(1, 0) # Move right one tile
Container for Entity objects in a Grid. Supports iteration and indexing.
append(...)remove(...)extend(...)count(...)index(...)Container for UI drawable elements. Supports iteration and indexing.
append(...)remove(...)extend(...)count(...)index(...)Iterator for UICollection. Automatically created when iterating over a UICollection.
Iterator for EntityCollection. Automatically created when iterating over an EntityCollection.
Color(r=255, g=255, b=255, a=255)
RGBA color representation.
r (int)g (int)b (int)a (int)from_hex(...)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
red = mcrfpy.Color(255, 0, 0)
Vector(x=0.0, y=0.0)
2D vector for positions and directions.
x (float)y (float)angle(...)Return the angle in radians from the positive X axis
copy(...)Return a copy of this vector
distance_to(...)Return the distance to another vector
dot(...)Return the dot product with another vector
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
Texture(filename)
Load a texture from file.
filename (str)
Font(filename)
Load a font from file.
filename (str)
Animation(property_name, start_value, end_value, duration, transition="linear", loop=False)
Animate UI element properties over time.
property_name (str)start_value (float)end_value (float)duration (float)transition (str)loop (bool)current_valueelapsed_timeis_runningis_finishedget_current_value()Get the current interpolated value.
Returns: float: Current animation value
start(target)Start the animation on a target UI element.
Arguments:
target (UIDrawable): The element to animateupdate(...)Update the animation by deltaTime (returns True if still running)
Base class for all drawable UI elements
get_bounds(...)Get bounding box as (x, y, width, height)
move(...)Move by relative offset (dx, dy)
resize(...)Resize to new dimensions (width, height)
Represents a single tile in a Grid.
xytexture_indexsolidtransparentcolorState information for a GridPoint.
visiblediscoveredcustom_flagsBase class for object-oriented scenes
activate(...)Make this the active scene
get_ui(...)Get the UI element collection for this scene
register_keyboard(...)Register a keyboard handler function (alternative to overriding on_keypress)
Timer(name, callback, interval_ms)
Create a recurring timer.
name (str)callback (callable)interval_ms (int)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
Window singleton for accessing and modifying the game window properties
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.
The mcrfpy.automation module provides testing and automation capabilities for simulating user input and capturing screenshots.
automation.clickClick at position
automation.doubleClickDouble click at position
automation.dragRelDrag mouse relative to current position
automation.dragToDrag mouse to position
automation.hotkeyPress a hotkey combination (e.g., hotkey('ctrl', 'c'))
automation.keyDownPress and hold a key
automation.keyUpRelease a key
automation.middleClickMiddle click at position
automation.mouseDownPress mouse button
automation.mouseUpRelease mouse button
automation.moveRelMove mouse relative to current position
automation.moveToMove mouse to absolute position
automation.onScreenCheck if coordinates are within screen bounds
automation.positionGet current mouse position as (x, y) tuple
automation.rightClickRight click at position
automation.screenshotSave a screenshot to the specified file
automation.scrollScroll wheel at position
automation.sizeGet screen size as (width, height) tuple
automation.tripleClickTriple click at position
automation.typewriteType text with optional interval between keystrokes