1071 lines
32 KiB
Groff
1071 lines
32 KiB
Groff
.\" 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
|