.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "MCRFPY" "3" "2025-10-30" "McRogueFace dev" ""
.hy
.SH McRogueFace API Reference
.PP
\f[I]Generated on 2025-10-30 20:49:34\f[R]
.PP
\f[I]This documentation was dynamically generated from the compiled
module.\f[R]
.SS Table of Contents
.IP \[bu] 2
Functions
.IP \[bu] 2
Classes
.RS 2
.IP \[bu] 2
Animation
.IP \[bu] 2
Caption
.IP \[bu] 2
Color
.IP \[bu] 2
Drawable
.IP \[bu] 2
Entity
.IP \[bu] 2
EntityCollection
.IP \[bu] 2
Font
.IP \[bu] 2
Frame
.IP \[bu] 2
Grid
.IP \[bu] 2
GridPoint
.IP \[bu] 2
GridPointState
.IP \[bu] 2
Scene
.IP \[bu] 2
Sprite
.IP \[bu] 2
Texture
.IP \[bu] 2
Timer
.IP \[bu] 2
UICollection
.IP \[bu] 2
UICollectionIter
.IP \[bu] 2
UIEntityCollectionIter
.IP \[bu] 2
Vector
.IP \[bu] 2
Window
.RE
.IP \[bu] 2
Constants
.SS Functions
.SS \f[V]createScene(name: str) -> None\f[R]
.PP
Create a new empty scene.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Unique name for the new scene
.PP
\f[B]Returns:\f[R] None
.PP
\f[B]Raises:\f[R] ValueError: If a scene with this name already exists
The scene is created but not made active.
Use setScene() to switch to it.
.SS \f[V]createSoundBuffer(filename: str) -> int\f[R]
.PP
Load a sound effect from a file and return its buffer ID.
.PP
\f[B]Arguments:\f[R] - \f[V]filename\f[R]: Path to the sound file (WAV,
OGG, FLAC)
.PP
\f[B]Returns:\f[R] int: Buffer ID for use with playSound()
.PP
\f[B]Raises:\f[R] RuntimeError: If the file cannot be loaded
.SS \f[V]currentScene() -> str\f[R]
.PP
Get the name of the currently active scene.
.PP
\f[B]Returns:\f[R] str: Name of the current scene
.SS \f[V]delTimer(name: str) -> None\f[R]
.PP
Stop and remove a timer.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Timer identifier to remove
.PP
\f[B]Returns:\f[R] None No error is raised if the timer doesn\[cq]t
exist.
.SS \f[V]exit() -> None\f[R]
.PP
Cleanly shut down the game engine and exit the application.
.PP
Note:
.PP
\f[B]Returns:\f[R] None This immediately closes the window and
terminates the program.
.SS \f[V]find(name: str, scene: str = None) -> UIDrawable | None\f[R]
.PP
Find the first UI element with the specified name.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Exact name to search for -
\f[V]scene\f[R]: Scene to search in (default: current scene)
.PP
\f[B]Returns:\f[R] Frame, Caption, Sprite, Grid, or Entity if found;
None otherwise Searches scene UI elements and entities within grids.
.SS \f[V]findAll(pattern: str, scene: str = None) -> list\f[R]
.PP
Find all UI elements matching a name pattern.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]pattern\f[R]: Name pattern with optional
wildcards (* matches any characters) - \f[V]scene\f[R]: Scene to search
in (default: current scene)
.PP
\f[B]Returns:\f[R] list: All matching UI elements and entities
.SS \f[V]getMetrics() -> dict\f[R]
.PP
Get current performance metrics.
.PP
\f[B]Returns:\f[R] 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)
.SS \f[V]getMusicVolume() -> int\f[R]
.PP
Get the current music volume level.
.PP
\f[B]Returns:\f[R] int: Current volume (0-100)
.SS \f[V]getSoundVolume() -> int\f[R]
.PP
Get the current sound effects volume level.
.PP
\f[B]Returns:\f[R] int: Current volume (0-100)
.SS \f[V]keypressScene(handler: callable) -> None\f[R]
.PP
Set the keyboard event handler for the current scene.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]handler\f[R]: Callable that receives
(key_name: str, is_pressed: bool)
.PP
\f[B]Returns:\f[R] None
.SS \f[V]loadMusic(filename: str) -> None\f[R]
.PP
Load and immediately play background music from a file.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]filename\f[R]: Path to the music file (WAV,
OGG, FLAC)
.PP
\f[B]Returns:\f[R] None Only one music track can play at a time.
Loading new music stops the current track.
.SS \f[V]playSound(buffer_id: int) -> None\f[R]
.PP
Play a sound effect using a previously loaded buffer.
.PP
\f[B]Arguments:\f[R] - \f[V]buffer_id\f[R]: Sound buffer ID returned by
createSoundBuffer()
.PP
\f[B]Returns:\f[R] None
.PP
\f[B]Raises:\f[R] RuntimeError: If the buffer ID is invalid
.SS \f[V]sceneUI(scene: str = None) -> list\f[R]
.PP
Get all UI elements for a scene.
.PP
\f[B]Arguments:\f[R] - \f[V]scene\f[R]: Scene name.
If None, uses current scene
.PP
\f[B]Returns:\f[R] list: All UI elements (Frame, Caption, Sprite, Grid)
in the scene
.PP
\f[B]Raises:\f[R] KeyError: If the specified scene doesn\[cq]t exist
.SS \f[V]setMusicVolume(volume: int) -> None\f[R]
.PP
Set the global music volume.
.PP
\f[B]Arguments:\f[R] - \f[V]volume\f[R]: Volume level from 0 (silent) to
100 (full volume)
.PP
\f[B]Returns:\f[R] None
.SS \f[V]setScale(multiplier: float) -> None\f[R]
.PP
Scale the game window size.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]multiplier\f[R]: Scale factor (e.g., 2.0 for
double size)
.PP
\f[B]Returns:\f[R] None The internal resolution remains 1024x768, but
the window is scaled.
This is deprecated - use Window.resolution instead.
.SS \f[V]setScene(scene: str, transition: str = None, duration: float = 0.0) -> None\f[R]
.PP
Switch to a different scene with optional transition effect.
.PP
\f[B]Arguments:\f[R] - \f[V]scene\f[R]: Name of the scene to switch to -
\f[V]transition\f[R]: Transition type (`fade', `slide_left',
`slide_right', `slide_up', `slide_down') - \f[V]duration\f[R]:
Transition duration in seconds (default: 0.0 for instant)
.PP
\f[B]Returns:\f[R] None
.PP
\f[B]Raises:\f[R] KeyError: If the scene doesn\[cq]t exist ValueError:
If the transition type is invalid
.SS \f[V]setSoundVolume(volume: int) -> None\f[R]
.PP
Set the global sound effects volume.
.PP
\f[B]Arguments:\f[R] - \f[V]volume\f[R]: Volume level from 0 (silent) to
100 (full volume)
.PP
\f[B]Returns:\f[R] None
.SS \f[V]setTimer(name: str, handler: callable, interval: int) -> None\f[R]
.PP
Create or update a recurring timer.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Unique identifier for the timer -
\f[V]handler\f[R]: Function called with (runtime: float) parameter -
\f[V]interval\f[R]: Time between calls in milliseconds
.PP
\f[B]Returns:\f[R] None If a timer with this name exists, it will be
replaced.
The handler receives the total runtime in seconds as its argument.
.SS Classes
.SS Animation
.PP
Animation object for animating UI properties
.PP
\f[B]Methods:\f[R]
.SS \f[V]complete() -> None\f[R]
.PP
Complete the animation immediately by jumping to the final value.
.PP
Note:
.PP
\f[B]Returns:\f[R] None Sets elapsed = duration and applies target value
immediately.
Completion callback will be called if set.
.SS \f[V]get_current_value() -> Any\f[R]
.PP
Get the current interpolated value of the animation.
.PP
Note:
.PP
\f[B]Returns:\f[R] 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).
.SS \f[V]hasValidTarget() -> bool\f[R]
.PP
Check if the animation still has a valid target.
.PP
Note:
.PP
\f[B]Returns:\f[R] 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.
.SS \f[V]start(target: UIDrawable) -> None\f[R]
.PP
Start the animation on a target UI element.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]target\f[R]: The UI element to animate
(Frame, Caption, Sprite, Grid, or Entity)
.PP
\f[B]Returns:\f[R] None The animation will automatically stop if the
target is destroyed.
Call AnimationManager.update(delta_time) each frame to progress
animations.
.SS \f[V]update(delta_time: float) -> bool\f[R]
.PP
Update the animation by the given time delta.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]delta_time\f[R]: Time elapsed since last
update in seconds
.PP
\f[B]Returns:\f[R] bool: True if animation is still running, False if
complete Typically called by AnimationManager automatically.
Manual calls only needed for custom animation control.
.SS Caption
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Caption(pos=None, font=None, text=\[cq]\[cq], **kwargs)
.PP
A text display UI element with customizable font and styling.
.PP
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: \[cq]\[cq]
.PP
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
.PP
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
.PP
\f[B]Methods:\f[R]
.SS \f[V]get_bounds() -> tuple\f[R]
.PP
Get the bounding rectangle of this drawable element.
.PP
Note:
.PP
\f[B]Returns:\f[R] tuple: (x, y, width, height) representing the
element\[cq]s bounds The bounds are in screen coordinates and account
for current position and size.
.SS \f[V]move(dx: float, dy: float) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels -
\f[V]dy\f[R]: Vertical offset in pixels
.SS \f[V]resize(width: float, height: float) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels -
\f[V]height\f[R]: New height in pixels
.SS Color
.PP
SFML Color Object
.PP
\f[B]Methods:\f[R]
.SS \f[V]from_hex(hex_string: str) -> Color\f[R]
.PP
Create a Color from a hexadecimal string.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]hex_string\f[R]: Hex color string (e.g.,
`#FF0000', `FF0000', `#AABBCCDD' for RGBA)
.PP
\f[B]Returns:\f[R] Color: New Color object with values from hex string
.PP
\f[B]Raises:\f[R] ValueError: If hex string is not 6 or 8 characters
(RGB or RGBA) This is a class method.
Call as Color.from_hex(`#FF0000')
.SS \f[V]lerp(other: Color, t: float) -> Color\f[R]
.PP
Linearly interpolate between this color and another.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: The target Color to interpolate
towards - \f[V]t\f[R]: Interpolation factor (0.0 = this color, 1.0 =
other color).
Automatically clamped to [0.0, 1.0]
.PP
\f[B]Returns:\f[R] Color: New Color representing the interpolated value
All components (r, g, b, a) are interpolated independently
.SS \f[V]to_hex() -> str\f[R]
.PP
Convert this Color to a hexadecimal string.
.PP
Note:
.PP
\f[B]Returns:\f[R] str: Hex string in format `#RRGGBB' or `#RRGGBBAA'
(if alpha < 255) Alpha component is only included if not fully opaque (<
255)
.SS Drawable
.PP
Base class for all drawable UI elements
.PP
\f[B]Methods:\f[R]
.SS \f[V]get_bounds() -> tuple\f[R]
.PP
Get the bounding rectangle of this drawable element.
.PP
Note:
.PP
\f[B]Returns:\f[R] tuple: (x, y, width, height) representing the
element\[cq]s bounds The bounds are in screen coordinates and account
for current position and size.
.SS \f[V]move(dx: float, dy: float) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels -
\f[V]dy\f[R]: Vertical offset in pixels
.SS \f[V]resize(width: float, height: float) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels -
\f[V]height\f[R]: New height in pixels
.SS Entity
.PP
Entity(grid_pos=None, texture=None, sprite_index=0, **kwargs)
.PP
A game entity that exists on a grid with sprite rendering.
.PP
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
.PP
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
.PP
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
.PP
\f[B]Methods:\f[R]
.SS \f[V]at(...)\f[R]
.SS \f[V]die(...)\f[R]
.PP
Remove this entity from its grid
.SS \f[V]get_bounds() -> tuple\f[R]
.PP
Get the bounding rectangle of this drawable element.
.PP
Note:
.PP
\f[B]Returns:\f[R] tuple: (x, y, width, height) representing the
element\[cq]s bounds The bounds are in screen coordinates and account
for current position and size.
.SS \f[V]index(...)\f[R]
.PP
Return the index of this entity in its grid\[cq]s entity collection
.SS \f[V]move(dx: float, dy: float) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels -
\f[V]dy\f[R]: Vertical offset in pixels
.SS \f[V]path_to(x: int, y: int) -> bool\f[R]
.PP
Find and follow path to target position using A* pathfinding.
.PP
\f[B]Arguments:\f[R] - \f[V]x\f[R]: Target X coordinate - \f[V]y\f[R]:
Target Y coordinate
.PP
\f[B]Returns:\f[R] 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.
.SS \f[V]resize(width: float, height: float) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels -
\f[V]height\f[R]: New height in pixels
.SS \f[V]update_visibility() -> None\f[R]
.PP
Update entity\[cq]s visibility state based on current FOV.
Recomputes which cells are visible from the entity\[cq]s position and
updates the entity\[cq]s gridstate to track explored areas.
This is called automatically when the entity moves if it has a grid with
perspective set.
.SS EntityCollection
.PP
Iterable, indexable collection of Entities
.PP
\f[B]Methods:\f[R]
.SS \f[V]append(...)\f[R]
.SS \f[V]count(...)\f[R]
.SS \f[V]extend(...)\f[R]
.SS \f[V]index(...)\f[R]
.SS \f[V]remove(...)\f[R]
.SS Font
.PP
SFML Font Object
.PP
\f[B]Methods:\f[R]
.SS Frame
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Frame(pos=None, size=None, **kwargs)
.PP
A rectangular frame UI element that can contain other drawable elements.
.PP
Args: pos (tuple, optional): Position as (x, y) tuple.
Default: (0, 0) size (tuple, optional): Size as (width, height) tuple.
Default: (0, 0)
.PP
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
.PP
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
.PP
\f[B]Methods:\f[R]
.SS \f[V]get_bounds() -> tuple\f[R]
.PP
Get the bounding rectangle of this drawable element.
.PP
Note:
.PP
\f[B]Returns:\f[R] tuple: (x, y, width, height) representing the
element\[cq]s bounds The bounds are in screen coordinates and account
for current position and size.
.SS \f[V]move(dx: float, dy: float) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels -
\f[V]dy\f[R]: Vertical offset in pixels
.SS \f[V]resize(width: float, height: float) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels -
\f[V]height\f[R]: New height in pixels
.SS Grid
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Grid(pos=None, size=None, grid_size=None, texture=None, **kwargs)
.PP
A grid-based UI element for tile-based rendering and entity management.
.PP
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
.PP
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
.PP
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
.PP
\f[B]Methods:\f[R]
.SS \f[V]at(...)\f[R]
.SS \f[V]compute_astar_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]\f[R]
.PP
Compute A* path between two points.
.PP
\f[B]Arguments:\f[R] - \f[V]x1\f[R]: Starting X coordinate -
\f[V]y1\f[R]: Starting Y coordinate - \f[V]x2\f[R]: Target X coordinate
- \f[V]y2\f[R]: Target Y coordinate - \f[V]diagonal_cost\f[R]: Cost of
diagonal movement (default: 1.41)
.PP
\f[B]Returns:\f[R] List of (x, y) tuples representing the path, empty
list if no path exists Alternative A* implementation.
Prefer find_path() for consistency.
.SS \f[V]compute_dijkstra(root_x: int, root_y: int, diagonal_cost: float = 1.41) -> None\f[R]
.PP
Compute Dijkstra map from root position.
.PP
\f[B]Arguments:\f[R] - \f[V]root_x\f[R]: X coordinate of the root/target
- \f[V]root_y\f[R]: Y coordinate of the root/target -
\f[V]diagonal_cost\f[R]: Cost of diagonal movement (default: 1.41)
.SS \f[V]compute_fov(x: int, y: int, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> List[Tuple[int, int, bool, bool]]\f[R]
.PP
Compute field of view from a position and return visible cells.
.PP
\f[B]Arguments:\f[R] - \f[V]x\f[R]: X coordinate of the viewer -
\f[V]y\f[R]: Y coordinate of the viewer - \f[V]radius\f[R]: Maximum view
distance (0 = unlimited) - \f[V]light_walls\f[R]: Whether walls are lit
when visible - \f[V]algorithm\f[R]: FOV algorithm to use (FOV_BASIC,
FOV_DIAMOND, FOV_SHADOW, FOV_PERMISSIVE_0-8)
.PP
\f[B]Returns:\f[R] List of tuples (x, y, visible, discovered) for all
visible cells: - x, y: Grid coordinates - visible: True (all returned
cells are visible) - discovered: True (FOV implies discovery) Also
updates the internal FOV state for use with is_in_fov().
.SS \f[V]find_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]\f[R]
.PP
Find A* path between two points.
.PP
\f[B]Arguments:\f[R] - \f[V]x1\f[R]: Starting X coordinate -
\f[V]y1\f[R]: Starting Y coordinate - \f[V]x2\f[R]: Target X coordinate
- \f[V]y2\f[R]: Target Y coordinate - \f[V]diagonal_cost\f[R]: Cost of
diagonal movement (default: 1.41)
.PP
\f[B]Returns:\f[R] List of (x, y) tuples representing the path, empty
list if no path exists Uses A* algorithm with walkability from grid
cells.
.SS \f[V]get_bounds() -> tuple\f[R]
.PP
Get the bounding rectangle of this drawable element.
.PP
Note:
.PP
\f[B]Returns:\f[R] tuple: (x, y, width, height) representing the
element\[cq]s bounds The bounds are in screen coordinates and account
for current position and size.
.SS \f[V]get_dijkstra_distance(x: int, y: int) -> Optional[float]\f[R]
.PP
Get distance from Dijkstra root to position.
.PP
\f[B]Arguments:\f[R] - \f[V]x\f[R]: X coordinate to query - \f[V]y\f[R]:
Y coordinate to query
.PP
\f[B]Returns:\f[R] Distance as float, or None if position is unreachable
or invalid Must call compute_dijkstra() first.
.SS \f[V]get_dijkstra_path(x: int, y: int) -> List[Tuple[int, int]]\f[R]
.PP
Get path from position to Dijkstra root.
.PP
\f[B]Arguments:\f[R] - \f[V]x\f[R]: Starting X coordinate - \f[V]y\f[R]:
Starting Y coordinate
.PP
\f[B]Returns:\f[R] List of (x, y) tuples representing path to root,
empty if unreachable Must call compute_dijkstra() first.
Path includes start but not root position.
.SS \f[V]is_in_fov(x: int, y: int) -> bool\f[R]
.PP
Check if a cell is in the field of view.
.PP
\f[B]Arguments:\f[R] - \f[V]x\f[R]: X coordinate to check - \f[V]y\f[R]:
Y coordinate to check
.PP
\f[B]Returns:\f[R] True if the cell is visible, False otherwise Must
call compute_fov() first to calculate visibility.
.SS \f[V]move(dx: float, dy: float) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels -
\f[V]dy\f[R]: Vertical offset in pixels
.SS \f[V]resize(width: float, height: float) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels -
\f[V]height\f[R]: New height in pixels
.SS GridPoint
.PP
UIGridPoint object
.PP
\f[B]Methods:\f[R]
.SS GridPointState
.PP
UIGridPointState object
.PP
\f[B]Methods:\f[R]
.SS Scene
.PP
Base class for object-oriented scenes
.PP
\f[B]Methods:\f[R]
.SS \f[V]activate() -> None\f[R]
.PP
Make this the active scene.
.PP
Note:
.PP
\f[B]Returns:\f[R] None Deactivates the current scene and activates this
one.
Scene transitions and lifecycle callbacks are triggered.
.SS \f[V]get_ui() -> UICollection\f[R]
.PP
Get the UI element collection for this scene.
.PP
Note:
.PP
\f[B]Returns:\f[R] 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.
.SS \f[V]register_keyboard(callback: callable) -> None\f[R]
.PP
Register a keyboard event handler function.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]callback\f[R]: Function that receives (key:
str, pressed: bool) when keyboard events occur
.PP
\f[B]Returns:\f[R] None Alternative to overriding on_keypress() method.
Handler is called for both key press and release events.
.SS Sprite
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Sprite(pos=None, texture=None, sprite_index=0, **kwargs)
.PP
A sprite UI element that displays a texture or portion of a texture
atlas.
.PP
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
.PP
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
.PP
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
.PP
\f[B]Methods:\f[R]
.SS \f[V]get_bounds() -> tuple\f[R]
.PP
Get the bounding rectangle of this drawable element.
.PP
Note:
.PP
\f[B]Returns:\f[R] tuple: (x, y, width, height) representing the
element\[cq]s bounds The bounds are in screen coordinates and account
for current position and size.
.SS \f[V]move(dx: float, dy: float) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels -
\f[V]dy\f[R]: Vertical offset in pixels
.SS \f[V]resize(width: float, height: float) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels -
\f[V]height\f[R]: New height in pixels
.SS Texture
.PP
SFML Texture Object
.PP
\f[B]Methods:\f[R]
.SS Timer
.PP
Timer(name, callback, interval, once=False)
.PP
Create a timer that calls a function at regular intervals.
.PP
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
.PP
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
.PP
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
.PP
Example: def on_timer(timer, runtime): print(f\[cq]Timer {timer} fired
at {runtime}ms\[cq]) if runtime > 5000: timer.cancel()
.IP
.nf
\f[C]
timer = mcrfpy.Timer(\[aq]my_timer\[aq], on_timer, 1000)
timer.pause()  # Pause timer
timer.resume() # Resume timer
timer.once = True  # Make it one-shot
\f[R]
.fi
.PP
\f[B]Methods:\f[R]
.SS \f[V]cancel() -> None\f[R]
.PP
Cancel the timer and remove it from the timer system.
.PP
Note:
.PP
\f[B]Returns:\f[R] None The timer will no longer fire and cannot be
restarted.
The callback will not be called again.
.SS \f[V]pause() -> None\f[R]
.PP
Pause the timer, preserving the time remaining until next trigger.
.PP
Note:
.PP
\f[B]Returns:\f[R] None The timer can be resumed later with resume().
Time spent paused does not count toward the interval.
.SS \f[V]restart() -> None\f[R]
.PP
Restart the timer from the beginning.
.PP
Note:
.PP
\f[B]Returns:\f[R] None Resets the timer to fire after a full interval
from now, regardless of remaining time.
.SS \f[V]resume() -> None\f[R]
.PP
Resume a paused timer from where it left off.
.PP
Note:
.PP
\f[B]Returns:\f[R] None Has no effect if the timer is not paused.
Timer will fire after the remaining time elapses.
.SS UICollection
.PP
Iterable, indexable collection of UI objects
.PP
\f[B]Methods:\f[R]
.SS \f[V]append(...)\f[R]
.SS \f[V]count(...)\f[R]
.SS \f[V]extend(...)\f[R]
.SS \f[V]index(...)\f[R]
.SS \f[V]remove(...)\f[R]
.SS UICollectionIter
.PP
Iterator for a collection of UI objects
.PP
\f[B]Methods:\f[R]
.SS UIEntityCollectionIter
.PP
Iterator for a collection of UI objects
.PP
\f[B]Methods:\f[R]
.SS Vector
.PP
SFML Vector Object
.PP
\f[B]Methods:\f[R]
.SS \f[V]angle() -> float\f[R]
.PP
Get the angle of this vector in radians.
.PP
\f[B]Returns:\f[R] float: Angle in radians from positive x-axis
.SS \f[V]copy() -> Vector\f[R]
.PP
Create a copy of this vector.
.PP
\f[B]Returns:\f[R] Vector: New Vector object with same x and y values
.SS \f[V]distance_to(other: Vector) -> float\f[R]
.PP
Calculate the distance to another vector.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: The other vector
.PP
\f[B]Returns:\f[R] float: Distance between the two vectors
.SS \f[V]dot(other: Vector) -> float\f[R]
.PP
Calculate the dot product with another vector.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: The other vector
.PP
\f[B]Returns:\f[R] float: Dot product of the two vectors
.SS \f[V]magnitude() -> float\f[R]
.PP
Calculate the length/magnitude of this vector.
.PP
\f[B]Returns:\f[R] float: The magnitude of the vector
.SS \f[V]magnitude_squared() -> float\f[R]
.PP
Calculate the squared magnitude of this vector.
.PP
Note:
.PP
\f[B]Returns:\f[R] float: The squared magnitude (faster than
magnitude()) Use this for comparisons to avoid expensive square root
calculation.
.SS \f[V]normalize() -> Vector\f[R]
.PP
Return a unit vector in the same direction.
.PP
Note:
.PP
\f[B]Returns:\f[R] Vector: New normalized vector with magnitude 1.0 For
zero vectors (magnitude 0.0), returns a zero vector rather than raising
an exception
.SS Window
.PP
Window singleton for accessing and modifying the game window properties
.PP
\f[B]Methods:\f[R]
.SS \f[V]center() -> None\f[R]
.PP
Center the window on the screen.
.PP
Note:
.PP
\f[B]Returns:\f[R] None Only works in windowed mode.
Has no effect when fullscreen or in headless mode.
.SS \f[V]get() -> Window\f[R]
.PP
Get the Window singleton instance.
.PP
Note:
.PP
\f[B]Returns:\f[R] Window: The global window object This is a class
method.
Call as Window.get().
There is only one window instance per application.
.SS \f[V]screenshot(filename: str = None) -> bytes | None\f[R]
.PP
Take a screenshot of the current window contents.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]filename\f[R]: Optional path to save
screenshot.
If omitted, returns raw RGBA bytes.
.PP
\f[B]Returns:\f[R] 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.
.SS Constants
.IP \[bu] 2
\f[V]FOV_BASIC\f[R] (int): 0
.IP \[bu] 2
\f[V]FOV_DIAMOND\f[R] (int): 1
.IP \[bu] 2
\f[V]FOV_PERMISSIVE_0\f[R] (int): 3
.IP \[bu] 2
\f[V]FOV_PERMISSIVE_1\f[R] (int): 4
.IP \[bu] 2
\f[V]FOV_PERMISSIVE_2\f[R] (int): 5
.IP \[bu] 2
\f[V]FOV_PERMISSIVE_3\f[R] (int): 6
.IP \[bu] 2
\f[V]FOV_PERMISSIVE_4\f[R] (int): 7
.IP \[bu] 2
\f[V]FOV_PERMISSIVE_5\f[R] (int): 8
.IP \[bu] 2
\f[V]FOV_PERMISSIVE_6\f[R] (int): 9
.IP \[bu] 2
\f[V]FOV_PERMISSIVE_7\f[R] (int): 10
.IP \[bu] 2
\f[V]FOV_PERMISSIVE_8\f[R] (int): 11
.IP \[bu] 2
\f[V]FOV_RESTRICTIVE\f[R] (int): 12
.IP \[bu] 2
\f[V]FOV_SHADOW\f[R] (int): 2