john
/
McRogueFace
1
0
Fork 0
Code Issues 50 Pull Requests Projects 1 Releases Wiki Activity
McRogueFace/docs/API_REFERENCE_COMPLETE.md

23 KiB
Raw Blame History

McRogueFace API Reference

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

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

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.

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.

class Caption

A text display UI element with customizable font and styling.

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.

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.

class Sprite

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

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.

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.

class Grid

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

Methods

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

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.

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.

class Entity

Game entity that can be placed in a Grid.

Methods

die()

Remove this entity from its parent grid.

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

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.

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

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.

Collections

class EntityCollection

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

Methods

append(entity)

Add an entity to the end of the collection.

Arguments:

  • entity (Entity): The entity to add

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

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

extend(iterable)

Add all entities from an iterable to the collection.

Arguments:

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

class UICollection

Container for UI drawable elements. Supports iteration and indexing.

Methods

append(drawable)

Add a drawable element to the end of the collection.

Arguments:

  • drawable (UIDrawable): The drawable element to add

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

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

extend(iterable)

Add all drawables from an iterable to the collection.

Arguments:

  • iterable (Iterable[UIDrawable]): Drawables 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

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

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"

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

distance_to(other)

Calculate the distance to another vector.

Arguments:

  • other (Vector): The other vector

Returns: float: Distance between the two vectors

dot(other)

Calculate the dot product with another vector.

Arguments:

  • other (Vector): The other vector

Returns: float: Dot product of the two vectors

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.

copy()

Create a copy of this vector.

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

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

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

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.

get_current_value()

Get the current interpolated value of the animation.

Returns: float: Current animation value between start and end

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

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.

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)

activate()

Make this scene the active scene.

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

get_ui()

Get the UI element collection for this scene.

Returns: UICollection: Collection of all UI elements in this scene

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

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.

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.

class Window

Window singleton for accessing and modifying the game window properties.

Methods

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.

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.

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