McRogueFace API Reference

Generated on 2025-11-29 10:12:05

This documentation was dynamically generated from the compiled module.

Table of Contents

Functions

createScene(name: str) -> None

Create a new empty scene. Note:

Arguments:

Returns: None

Raises: ValueError: If a scene with this name already exists The scene is created but not made active. Use setScene() to switch to it.

createSoundBuffer(filename: str) -> int

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

Arguments:

Returns: int: Buffer ID for use with playSound()

Raises: RuntimeError: If the file cannot be loaded

currentScene() -> str

Get the name of the currently active scene.

Returns: str: Name of the current scene

delTimer(name: str) -> None

Stop and remove a timer. Note:

Arguments:

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

end_benchmark() -> str

Stop benchmark capture and write data to JSON file. Note:

Returns: str: The filename of the written benchmark data

Raises: RuntimeError: If no benchmark is currently running Returns the auto-generated filename (e.g., 'benchmark_12345_20250528_143022.json')

exit() -> None

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

Returns: None This immediately closes the window and terminates the program.

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

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

Arguments:

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

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

Find all UI elements matching a name pattern. Note:

Arguments:

Returns: list: All matching UI elements and entities

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)

getMusicVolume() -> int

Get the current music volume level.

Returns: int: Current volume (0-100)

getSoundVolume() -> int

Get the current sound effects volume level.

Returns: int: Current volume (0-100)

keypressScene(handler: callable) -> None

Set the keyboard event handler for the current scene. Note:

Arguments:

Returns: None

loadMusic(filename: str) -> None

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

Arguments:

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

log_benchmark(message: str) -> None

Add a log message to the current benchmark frame. Note:

Arguments:

Returns: None

Raises: RuntimeError: If no benchmark is currently running Messages appear in the 'logs' array of each frame in the output JSON.

playSound(buffer_id: int) -> None

Play a sound effect using a previously loaded buffer.

Arguments:

Returns: None

Raises: RuntimeError: If the buffer ID is invalid

sceneUI(scene: str = None) -> list

Get all UI elements for a scene.

Arguments:

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

Raises: KeyError: If the specified scene doesn't exist

setDevConsole(enabled: bool) -> None

Enable or disable the developer console overlay. Note:

Arguments:

Returns: None When disabled, the grave/tilde key will not open the console. Use this to ship games without debug features.

setMusicVolume(volume: int) -> None

Set the global music volume.

Arguments:

Returns: None

setScale(multiplier: float) -> None

Scale the game window size. Note:

Arguments:

Returns: None The internal resolution remains 1024x768, but the window is scaled. This is deprecated - use Window.resolution instead.

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

Switch to a different scene with optional transition effect.

Arguments:

Returns: None

Raises: KeyError: If the scene doesn't exist ValueError: If the transition type is invalid

setSoundVolume(volume: int) -> None

Set the global sound effects volume.

Arguments:

Returns: None

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

Create or update a recurring timer. Note:

Arguments:

Returns: None If a timer with this name exists, it will be replaced. The handler receives the total runtime in seconds as its argument.

start_benchmark() -> None

Start capturing benchmark data to a file. Note:

Returns: None

Raises: RuntimeError: If a benchmark is already running Benchmark filename is auto-generated from PID and timestamp. Use end_benchmark() to stop and get filename.

Classes

Animation

Animation object for animating UI properties

Methods:

complete() -> None

Complete the animation immediately by jumping to the final value. Note:

Returns: None Sets elapsed = duration and applies target value immediately. Completion callback will be called if set.

get_current_value() -> Any

Get the current interpolated value of the animation. Note:

Returns: Any: Current value (type depends on property: float, int, Color tuple, Vector tuple, or str) Return type matches the target property type. For sprite_index returns int, for pos returns (x, y), for fill_color returns (r, g, b, a).

hasValidTarget() -> bool

Check if the animation still has a valid target. Note:

Returns: bool: True if the target still exists, False if it was destroyed Animations automatically clean up when targets are destroyed. Use this to check if manual cleanup is needed.

start(target: UIDrawable) -> None

Start the animation on a target UI element. Note:

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

Returns: None The animation will automatically stop if the target is destroyed. Call AnimationManager.update(delta_time) each frame to progress animations.

update(delta_time: float) -> bool

Update the animation by the given time delta. Note:

delta_time: Time elapsed since last update in seconds

Returns: bool: True if animation is still running, False if complete Typically called by AnimationManager automatically. Manual calls only needed for custom animation control.

Arc

Inherits from: Drawable

Arc(center=None, radius=0, start_angle=0, end_angle=90, color=None, thickness=1, **kwargs) An arc UI element for drawing curved line segments. Args: center (tuple, optional): Center position as (x, y). Default: (0, 0) radius (float, optional): Arc radius in pixels. Default: 0 start_angle (float, optional): Starting angle in degrees. Default: 0 end_angle (float, optional): Ending angle in degrees. Default: 90 color (Color, optional): Arc color. Default: White thickness (float, optional): Line thickness. Default: 1.0 Keyword Args: click (callable): Click 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 Attributes: center (Vector): Center position radius (float): Arc radius start_angle (float): Starting angle in degrees end_angle (float): Ending angle in degrees color (Color): Arc color thickness (float): Line thickness visible (bool): Visibility state opacity (float): Opacity value z_index (int): Rendering order name (str): Element name

Methods:

get_bounds() -> tuple

Get the bounding rectangle of this drawable element. Note:

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

move(dx: float, dy: float) -> None

Move the element by a relative offset. Note:

dx: Horizontal offset in pixels
dy: Vertical offset in pixels
resize(width: float, height: float) -> None

Resize the element to new dimensions. Note:

width: New width in pixels
height: New height in pixels

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

Get the bounding rectangle of this drawable element. Note:

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

move(dx: float, dy: float) -> None

Move the element by a relative offset. Note:

dx: Horizontal offset in pixels
dy: Vertical offset in pixels
resize(width: float, height: float) -> None

Resize the element to new dimensions. Note:

width: New width in pixels
height: New height in pixels

Circle

Inherits from: Drawable

Circle(radius=0, center=None, fill_color=None, outline_color=None, outline=0, **kwargs) A circle UI element for drawing filled or outlined circles. Args: radius (float, optional): Circle radius in pixels. Default: 0 center (tuple, optional): Center position as (x, y). Default: (0, 0) fill_color (Color, optional): Fill color. Default: White outline_color (Color, optional): Outline color. Default: Transparent outline (float, optional): Outline thickness. Default: 0 (no outline) Keyword Args: click (callable): Click 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 Attributes: radius (float): Circle radius center (Vector): Center position fill_color (Color): Fill color outline_color (Color): Outline color outline (float): Outline thickness visible (bool): Visibility state opacity (float): Opacity value z_index (int): Rendering order name (str): Element name

Methods:

get_bounds() -> tuple

Get the bounding rectangle of this drawable element. Note:

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

move(dx: float, dy: float) -> None

Move the element by a relative offset. Note:

dx: Horizontal offset in pixels
dy: Vertical offset in pixels
resize(width: float, height: float) -> None

Resize the element to new dimensions. Note:

width: New width in pixels
height: New height in pixels

Color

SFML Color Object

Methods:

from_hex(hex_string: str) -> Color

Create a Color from a hexadecimal string. Note:

hex_string: Hex color string (e.g., '#FF0000', 'FF0000', '#AABBCCDD' for RGBA)

Returns: Color: New Color object with values from hex string

Raises: ValueError: If hex string is not 6 or 8 characters (RGB or RGBA) This is a class method. Call as Color.from_hex('#FF0000')

lerp(other: Color, t: float) -> Color

Linearly interpolate between this color and another. Note:

other: The target Color to interpolate towards
t: Interpolation factor (0.0 = this color, 1.0 = other color). Automatically clamped to [0.0, 1.0]

Returns: Color: New Color representing the interpolated value All components (r, g, b, a) are interpolated independently

to_hex() -> str

Convert this Color to a hexadecimal string. Note:

Returns: str: Hex string in format '#RRGGBB' or '#RRGGBBAA' (if alpha < 255) Alpha component is only included if not fully opaque (< 255)

ColorLayer

ColorLayer(z_index=-1, grid_size=None) A grid layer that stores RGBA colors per cell. Args: z_index (int): Render order. Negative = below entities. Default: -1 grid_size (tuple): Dimensions as (width, height). Default: parent grid size Attributes: z_index (int): Layer z-order relative to entities visible (bool): Whether layer is rendered grid_size (tuple): Layer dimensions (read-only) Methods: at(x, y): Get color at cell position set(x, y, color): Set color at cell position fill(color): Fill entire layer with color

Methods:

at(x, y) -> Color

Get the color at cell position (x, y).

fill(color)

Fill the entire layer with the specified color.

set(x, y, color)

Set the color at cell position (x, y).

Drawable

Base class for all drawable UI elements

Methods:

get_bounds() -> tuple

Get the bounding rectangle of this drawable element. Note:

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

move(dx: float, dy: float) -> None

Move the element by a relative offset. Note:

dx: Horizontal offset in pixels
dy: Vertical offset in pixels
resize(width: float, height: float) -> None

Resize the element to new dimensions. Note:

width: New width in pixels
height: New height in pixels

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

Get the bounding rectangle of this drawable element. Note:

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

index(...)

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

move(dx: float, dy: float) -> None

Move the element by a relative offset. Note:

dx: Horizontal offset in pixels
dy: Vertical offset in pixels
path_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 The entity will automatically move along the path over multiple frames. Call this again to change the target or repath.

resize(width: float, height: float) -> None

Resize the element to new dimensions. Note:

width: New width in pixels
height: New height in pixels
update_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(entity)

Add an entity to the end of the collection.

count(entity) -> int

Count occurrences of entity in the collection.

extend(iterable)

Add all entities from an iterable to the collection.

find(name) -> entity or list

Find entities by name.

Returns: Single entity if exact match, list if wildcard, None if not found.

index(entity) -> int

Return index of first occurrence of entity. Raises ValueError if not found.

insert(index, entity)

Insert entity at index. Like list.insert(), indices past the end append.

pop([index]) -> entity

Remove and return entity at index (default: last entity).

remove(entity)

Remove first occurrence of entity. Raises ValueError if not found.

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 cache_subtree (bool): Cache rendering to texture for performance. 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 cache_subtree (bool): Cache subtree rendering to texture

Methods:

get_bounds() -> tuple

Get the bounding rectangle of this drawable element. Note:

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

move(dx: float, dy: float) -> None

Move the element by a relative offset. Note:

dx: Horizontal offset in pixels
dy: Vertical offset in pixels
resize(width: float, height: float) -> None

Resize the element to new dimensions. Note:

width: New width in pixels
height: New height in pixels

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:

add_layer(type: str, z_index: int = -1, texture: Texture = None) -> ColorLayer | TileLayer

Add a new layer to the grid.

type: Layer type ('color' or 'tile')
z_index: Render order. Negative = below entities, >= 0 = above entities. Default: -1
texture: Texture for tile layers. Required for 'tile' type.

Returns: The created ColorLayer or TileLayer object.

at(...)
compute_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 Alternative A* implementation. Prefer find_path() for consistency.

compute_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_fov(x: int, y: int, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None

Compute field of view from a position.

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)
find_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 Uses A* algorithm with walkability from grid cells.

get_bounds() -> tuple

Get the bounding rectangle of this drawable element. Note:

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

get_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 Must call compute_dijkstra() first.

get_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 Must call compute_dijkstra() first. Path includes start but not root position.

is_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 Must call compute_fov() first to calculate visibility.

layer(z_index: int) -> ColorLayer | TileLayer | None

Get a layer by its z_index.

z_index: The z_index of the layer to find.

Returns: The layer with the specified z_index, or None if not found.

move(dx: float, dy: float) -> None

Move the element by a relative offset. Note:

dx: Horizontal offset in pixels
dy: Vertical offset in pixels
remove_layer(layer: ColorLayer | TileLayer) -> None

Remove a layer from the grid.

layer: The layer to remove.
resize(width: float, height: float) -> None

Resize the element to new dimensions. Note:

width: New width in pixels
height: New height in pixels

GridPoint

UIGridPoint object

Methods:

GridPointState

UIGridPointState object

Methods:

Line

Inherits from: Drawable

Line(start=None, end=None, thickness=1.0, color=None, **kwargs) A line UI element for drawing straight lines between two points. Args: start (tuple, optional): Starting point as (x, y). Default: (0, 0) end (tuple, optional): Ending point as (x, y). Default: (0, 0) thickness (float, optional): Line thickness in pixels. Default: 1.0 color (Color, optional): Line color. Default: White Keyword Args: click (callable): Click 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 Attributes: start (Vector): Starting point end (Vector): Ending point thickness (float): Line thickness color (Color): Line color visible (bool): Visibility state opacity (float): Opacity value z_index (int): Rendering order name (str): Element name

Methods:

get_bounds() -> tuple

Get the bounding rectangle of this drawable element. Note:

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

move(dx: float, dy: float) -> None

Move the element by a relative offset. Note:

dx: Horizontal offset in pixels
dy: Vertical offset in pixels
resize(width: float, height: float) -> None

Resize the element to new dimensions. Note:

width: New width in pixels
height: New height in pixels

Scene

Base class for object-oriented scenes

Methods:

activate() -> None

Make this the active scene. Note:

Returns: None Deactivates the current scene and activates this one. Scene transitions and lifecycle callbacks are triggered.

get_ui() -> UICollection

Get the UI element collection for this scene. Note:

Returns: UICollection: Collection of UI elements (Frames, Captions, Sprites, Grids) in this scene Use to add, remove, or iterate over UI elements. Changes are reflected immediately.

register_keyboard(callback: callable) -> None

Register a keyboard event handler function. Note:

callback: Function that receives (key: str, pressed: bool) when keyboard events occur

Returns: None Alternative to overriding on_keypress() method. Handler is called for both key press and release events.

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

Get the bounding rectangle of this drawable element. Note:

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

move(dx: float, dy: float) -> None

Move the element by a relative offset. Note:

dx: Horizontal offset in pixels
dy: Vertical offset in pixels
resize(width: float, height: float) -> None

Resize the element to new dimensions. Note:

width: New width in pixels
height: New height in pixels

Texture

SFML Texture Object

Methods:

TileLayer

TileLayer(z_index=-1, texture=None, grid_size=None) A grid layer that stores sprite indices per cell. Args: z_index (int): Render order. Negative = below entities. Default: -1 texture (Texture): Sprite atlas for tile rendering. Default: None grid_size (tuple): Dimensions as (width, height). Default: parent grid size Attributes: z_index (int): Layer z-order relative to entities visible (bool): Whether layer is rendered texture (Texture): Tile sprite atlas grid_size (tuple): Layer dimensions (read-only) Methods: at(x, y): Get tile index at cell position set(x, y, index): Set tile index at cell position fill(index): Fill entire layer with tile index

Methods:

at(x, y) -> int

Get the tile index at cell position (x, y). Returns -1 if no tile.

fill(index)

Fill the entire layer with the specified tile index.

set(x, y, index)

Set the tile index at cell position (x, y). Use -1 for no tile.

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:

cancel() -> None

Cancel the timer and remove it from the timer system. Note:

Returns: None The timer will no longer fire and cannot be restarted. The callback will not be called again.

pause() -> None

Pause the timer, preserving the time remaining until next trigger. Note:

Returns: None The timer can be resumed later with resume(). Time spent paused does not count toward the interval.

restart() -> None

Restart the timer from the beginning. Note:

Returns: None Resets the timer to fire after a full interval from now, regardless of remaining time.

resume() -> None

Resume a paused timer from where it left off. Note:

Returns: None Has no effect if the timer is not paused. Timer will fire after the remaining time elapses.

UICollection

Iterable, indexable collection of UI objects

Methods:

append(element)

Add an element to the end of the collection.

count(element) -> int

Count occurrences of element in the collection.

extend(iterable)

Add all elements from an iterable to the collection.

find(name, recursive=False) -> element or list

Find elements by name.

Returns: Single element if exact match, list if wildcard, None if not found.

index(element) -> int

Return index of first occurrence of element. Raises ValueError if not found.

insert(index, element)

Insert element at index. Like list.insert(), indices past the end append. Note: If using z_index for sorting, insertion order may not persist after the next render. Use name-based .find() for stable element access.

pop([index]) -> element

Remove and return element at index (default: last element). Note: If using z_index for sorting, indices may shift after render. Use name-based .find() for stable element access.

remove(element)

Remove first occurrence of element. Raises ValueError if not found.

UICollectionIter

Iterator for a collection of UI objects

Methods:

UIEntityCollectionIter

Iterator for a collection of UI objects

Methods:

Vector

SFML Vector Object

Methods:

angle() -> float

Get the angle of this vector in radians.

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

copy() -> Vector

Create a copy of this vector.

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

distance_to(other: Vector) -> float

Calculate the distance to another vector.

other: The other vector

Returns: float: Distance between the two vectors

dot(other: Vector) -> float

Calculate the dot product with another vector.

other: The other vector

Returns: float: Dot product of the two vectors

floor() -> Vector

Return a new vector with floored (integer) coordinates. Note:

Returns: Vector: New Vector with floor(x) and floor(y) Useful for grid-based positioning. For a hashable tuple, use the .int property instead.

magnitude() -> float

Calculate the length/magnitude of this vector.

Returns: float: The magnitude of the vector

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

normalize() -> 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() -> None

Center the window on the screen. Note:

Returns: None Only works in windowed mode. Has no effect when fullscreen or in headless mode.

get() -> Window

Get the Window singleton instance. Note:

Returns: Window: The global window object This is a class method. Call as Window.get(). There is only one window instance per application.

screenshot(filename: str = None) -> bytes | None

Take a screenshot of the current window contents. Note:

filename: Optional path to save screenshot. If omitted, returns raw RGBA bytes.

Returns: bytes | None: Raw RGBA pixel data if no filename given, otherwise None after saving Screenshot is taken at the actual window resolution. Use after render loop update for current frame.

Constants