McRogueFace API Reference

bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]]

Compute grid cells along a line using Bresenham's algorithm. Note:

Arguments:

• start: (x, y) tuple or Vector - starting point
• end: (x, y) tuple or Vector - ending point
• include_start: Include the starting point in results (default: True)
• include_end: Include the ending point in results (default: True)

Returns: list[tuple[int, int]]: List of (x, y) grid coordinates along the line Useful for line-of-sight checks, projectile paths, and drawing lines on grids. The algorithm ensures minimal grid traversal between two points.

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:

• name: Exact name to search for
• scene: Scene to search in (default: current scene)

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

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

Find all UI elements matching a name pattern. Note:

Arguments:

• pattern: Name pattern with optional wildcards (* matches any characters)
• scene: Scene to search in (default: current scene)

Returns: list: All matching UI elements and entities

get_metrics() -> 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)

lock() -> _LockContext

Get a context manager for thread-safe UI updates from background threads. Note:

Returns: _LockContext: A context manager that blocks until safe to modify UI Use with `with mcrfpy.lock():` to safely modify UI objects from a background thread. The context manager blocks until the render loop reaches a safe point between frames. Without this, modifying UI from threads may cause visual glitches or crashes.

log_benchmark(message: str) -> None

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

Arguments:

• message: Text to associate with the current frame

Returns: None

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

set_dev_console(enabled: bool) -> None

Enable or disable the developer console overlay. Note:

Arguments:

• enabled: True to enable the console (default), False to disable

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

set_scale(multiplier: float) -> None

Deprecated: use Window.resolution instead. Scale the game window size. Note:

Arguments:

• multiplier: Scale factor (e.g., 2.0 for double size)

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

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.

step(dt: float = None) -> float

Advance simulation time (headless mode only). Note:

Arguments:

• dt: Time to advance in seconds. If None, advances to the next scheduled event (timer/animation).

Returns: float: Actual time advanced in seconds. Returns 0.0 in windowed mode. In windowed mode, this is a no-op and returns 0.0. Use this for deterministic simulation control in headless/testing scenarios.

AStarPath

A computed A* path result, consumed step by step. Created by Grid.find_path(). Cannot be instantiated directly. Use walk() to get and consume each step, or iterate directly. Use peek() to see the next step without consuming it. Use bool(path) or len(path) to check if steps remain. Properties: origin (Vector): Starting position (read-only) destination (Vector): Ending position (read-only) remaining (int): Steps remaining (read-only) Example: path = grid.find_path(start, end) if path: while path: next_pos = path.walk() entity.pos = next_pos

Properties:

• destination (read-only): Ending position of the path (Vector, read-only).
• origin (read-only): Starting position of the path (Vector, read-only).
• remaining (read-only): Number of steps remaining in the path (int, read-only).

Methods:

Alignment

Inherits from: IntEnum

Alignment enum for positioning UI elements relative to parent bounds. Values: TOP_LEFT, TOP_CENTER, TOP_RIGHT CENTER_LEFT, CENTER, CENTER_RIGHT BOTTOM_LEFT, BOTTOM_CENTER, BOTTOM_RIGHT Margin Validation Rules: Margins define distance from parent edge when aligned. - CENTER: No margins allowed (raises ValueError if margin != 0) - TOP_CENTER, BOTTOM_CENTER: Only vert_margin applies (horiz_margin raises ValueError) - CENTER_LEFT, CENTER_RIGHT: Only horiz_margin applies (vert_margin raises ValueError) - Corner alignments (TOP_LEFT, etc.): All margins valid Properties: align: Alignment value or None to disable margin: General margin for all applicable edges horiz_margin: Override for horizontal edge (0 = use general margin) vert_margin: Override for vertical edge (0 = use general margin) Example: # Center a panel in the scene panel = Frame(size=(200, 100), align=Alignment.CENTER) scene.children.append(panel) # Place button in bottom-right with 10px margin button = Frame(size=(80, 30), align=Alignment.BOTTOM_RIGHT, margin=10) panel.children.append(button)

Properties:

• denominator: the denominator of a rational number in lowest terms
• imag: the imaginary part of a complex number
• numerator: the numerator of a rational number in lowest terms
• real: the real part of a complex number

Methods:

Animation

Animation(property: str, target: Any, duration: float, easing: str = 'linear', delta: bool = False, loop: bool = False, callback: Callable = None) Create an animation that interpolates a property value over time. Args: property: Property name to animate. Valid properties depend on target type: - Position/Size: 'x', 'y', 'w', 'h', 'pos', 'size' - Appearance: 'fill_color', 'outline_color', 'outline', 'opacity' - Sprite: 'sprite_index', 'scale' - Grid: 'center', 'zoom' - Caption: 'text' - Sub-properties: 'fill_color.r', 'fill_color.g', 'fill_color.b', 'fill_color.a' target: Target value for the animation. Type depends on property: - float: For numeric properties (x, y, w, h, scale, opacity, zoom) - int: For integer properties (sprite_index) - tuple (r, g, b[, a]): For color properties - tuple (x, y): For vector properties (pos, size, center) - list[int]: For sprite animation sequences - str: For text animation duration: Animation duration in seconds. easing: Easing function name. Options: - 'linear' (default) - 'easeIn', 'easeOut', 'easeInOut' - 'easeInQuad', 'easeOutQuad', 'easeInOutQuad' - 'easeInCubic', 'easeOutCubic', 'easeInOutCubic' - 'easeInQuart', 'easeOutQuart', 'easeInOutQuart' - 'easeInSine', 'easeOutSine', 'easeInOutSine' - 'easeInExpo', 'easeOutExpo', 'easeInOutExpo' - 'easeInCirc', 'easeOutCirc', 'easeInOutCirc' - 'easeInElastic', 'easeOutElastic', 'easeInOutElastic' - 'easeInBack', 'easeOutBack', 'easeInOutBack' - 'easeInBounce', 'easeOutBounce', 'easeInOutBounce' delta: If True, target is relative to start value (additive). Default False. loop: If True, animation repeats from start when it reaches the end. Default False. callback: Function(target, property, value) called when animation completes. Not called for looping animations (since they never complete). Example: # Move a frame from current position to x=500 over 2 seconds anim = mcrfpy.Animation('x', 500.0, 2.0, 'easeInOut') anim.start(my_frame) # Looping sprite animation walk = mcrfpy.Animation('sprite_index', [0,1,2,3,2,1], 0.6, loop=True) walk.start(my_sprite)

Properties:

• duration (read-only): Animation duration in seconds (float, read-only). Total time for the animation to complete.
• elapsed (read-only): Elapsed time in seconds (float, read-only). Time since the animation started.
• is_complete (read-only): Whether animation is complete (bool, read-only). True when elapsed >= duration or complete() was called.
• is_delta (read-only): Whether animation uses delta mode (bool, read-only). In delta mode, the target value is added to the starting value.
• is_looping (read-only): Whether animation loops (bool, read-only). Looping animations repeat from the start when they reach the end.
• property (read-only): Target property name (str, read-only). The property being animated (e.g., 'pos', 'opacity', 'sprite_index').

Methods:

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: on_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 align (Alignment): Alignment relative to parent. Default: None margin (float): Margin from parent edge when aligned. Default: 0 horiz_margin (float): Horizontal margin override. Default: 0 (use margin) vert_margin (float): Vertical margin override. Default: 0 (use margin) 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 align (Alignment): Alignment relative to parent (or None) margin (float): General margin for alignment horiz_margin (float): Horizontal margin override vert_margin (float): Vertical margin override

Properties:

• align: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
• bounds: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
• center: Center position of the arc
• color: Arc color
• end_angle: Ending angle in degrees
• global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
• global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
• grid_pos: Position in grid tile coordinates (only when parent is Grid)
• grid_size: Size in grid tile coordinates (only when parent is Grid)
• horiz_margin: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
• hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
• margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
• name: Name for finding this element.
• on_click: Callable executed when arc is clicked. Function receives (pos: Vector, button: str, action: str).
• on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
• on_exit: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
• on_move: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
• opacity: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
• origin: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
• parent: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
• pos: Position as a Vector (same as center).
• radius: Arc radius in pixels
• rotate_with_camera: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
• rotation: Rotation angle in degrees (clockwise around origin). Animatable property.
• start_angle: Starting angle in degrees
• thickness: Line thickness
• vert_margin: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
• visible: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
• z_index: Z-order for rendering (lower values rendered first).

Methods:

AutoRuleSet

AutoRuleSet - LDtk auto-tile rule set for pattern-based terrain rendering. AutoRuleSets are obtained from LdtkProject.ruleset(). They map IntGrid terrain values to sprite tiles using LDtk's pattern-matching auto-rule system. Properties: name (str, read-only): Rule set name (layer identifier). grid_size (int, read-only): Cell size in pixels. value_count (int, read-only): Number of IntGrid values. values (list, read-only): List of value dicts. rule_count (int, read-only): Total rules across all groups. group_count (int, read-only): Number of rule groups. Example: rs = project.ruleset('Walls') Terrain = rs.terrain_enum() rs.apply(discrete_map, tile_layer, seed=42)

Properties:

• grid_size (read-only): Cell size in pixels (int, read-only).
• group_count (read-only): Number of rule groups (int, read-only).
• name (read-only): Rule set name / layer identifier (str, read-only).
• rule_count (read-only): Total number of rules across all groups (int, read-only).
• value_count (read-only): Number of IntGrid terrain values (int, read-only).
• values (read-only): List of IntGrid value dicts with value and name (read-only).

Methods:

BSP

BSP(pos: tuple[int, int], size: tuple[int, int]) Binary Space Partitioning tree for procedural dungeon generation. BSP recursively divides a rectangular region into smaller sub-regions, creating a tree structure perfect for generating dungeon rooms and corridors. Args: pos: (x, y) - Top-left position of the root region. size: (w, h) - Width and height of the root region. Properties: pos (tuple[int, int]): Read-only. Top-left position (x, y). size (tuple[int, int]): Read-only. Dimensions (width, height). bounds ((pos), (size)): Read-only. Combined position and size. root (BSPNode): Read-only. Reference to the root node. Iteration: for leaf in bsp: # Iterates over leaf nodes (rooms) len(bsp) # Returns number of leaf nodes Example: bsp = mcrfpy.BSP(pos=(0, 0), size=(80, 50)) bsp.split_recursive(depth=4, min_size=(8, 8)) for leaf in bsp: print(f'Room at {leaf.pos}, size {leaf.size}')

Properties:

• adjacency (read-only): Leaf adjacency graph. adjacency[i] returns tuple of neighbor indices. Read-only.
• bounds (read-only): Root node bounds as ((x, y), (w, h)). Read-only.
• pos (read-only): Top-left position (x, y). Read-only.
• root (read-only): Reference to the root BSPNode. Read-only.
• size (read-only): Dimensions (width, height). Read-only.

Methods:

Behavior

Inherits from: IntEnum

Enum representing entity behavior types for grid.step() turn management. Values: IDLE: No action each turn CUSTOM: Calls step callback only, no built-in movement NOISE4: Random movement in 4 cardinal directions NOISE8: Random movement in 8 directions (incl. diagonals) PATH: Follow a precomputed path to completion WAYPOINT: Path through a sequence of waypoints in order PATROL: Patrol waypoints back and forth (reversing at ends) LOOP: Loop through waypoints cyclically SLEEP: Wait for N turns, then trigger DONE SEEK: Move toward target using Dijkstra map FLEE: Move away from target using Dijkstra map

Properties:

• denominator: the denominator of a rational number in lowest terms
• imag: the imaginary part of a complex number
• numerator: the numerator of a rational number in lowest terms
• real: the real part of a complex number

Methods:

Billboard

Billboard(texture=None, sprite_index=0, pos=(0,0,0), scale=1.0, facing='camera_y') A camera-facing 3D sprite for trees, items, particles, etc. Args: texture (Texture, optional): Sprite sheet texture. Default: None sprite_index (int): Index into sprite sheet. Default: 0 pos (tuple): World position (x, y, z). Default: (0, 0, 0) scale (float): Uniform scale factor. Default: 1.0 facing (str): Facing mode - 'camera', 'camera_y', or 'fixed'. Default: 'camera_y' Properties: texture (Texture): Sprite sheet texture sprite_index (int): Index into sprite sheet pos (tuple): World position (x, y, z) scale (float): Uniform scale factor facing (str): Facing mode - 'camera', 'camera_y', or 'fixed' theta (float): Horizontal rotation for 'fixed' mode (radians) phi (float): Vertical tilt for 'fixed' mode (radians) opacity (float): Opacity 0.0 (transparent) to 1.0 (opaque) visible (bool): Visibility state

Properties:

• facing: Facing mode: 'camera', 'camera_y', or 'fixed' (str)
• opacity: Opacity from 0.0 (transparent) to 1.0 (opaque) (float)
• phi: Vertical tilt for 'fixed' mode in radians (float)
• pos: World position as (x, y, z) tuple
• scale: Uniform scale factor (float)
• sprite_index: Index into sprite sheet (int)
• texture: Sprite sheet texture (Texture or None)
• theta: Horizontal rotation for 'fixed' mode in radians (float)
• visible: Visibility state (bool)

Methods:

CallableBinding

CallableBinding(callable: Callable[[], float]) A binding that calls a Python function to get its value. Args: callable: A function that takes no arguments and returns a float The callable is invoked every frame when the shader is rendered. Keep the callable lightweight to avoid performance issues. Example: player_health = 100 frame.uniforms['health_pct'] = mcrfpy.CallableBinding( lambda: player_health / 100.0 )

Properties:

• callable (read-only): The Python callable (read-only).
• is_valid (read-only): True if the callable is still valid (bool, read-only).
• value (read-only): Current value from calling the callable (float, read-only). Returns None on error.

Methods:

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 align (Alignment): Alignment relative to parent. Default: None margin (float): Margin from parent edge when aligned. Default: 0 horiz_margin (float): Horizontal margin override. Default: 0 (use margin) vert_margin (float): Vertical margin override. Default: 0 (use margin) 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 align (Alignment): Alignment relative to parent (or None) margin (float): General margin for alignment horiz_margin (float): Horizontal margin override vert_margin (float): Vertical margin override

Properties:

• align: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
• bounds: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
• fill_color: Fill color of the text. Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc.
• font_size: Font size (integer) in points
• global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
• global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
• grid_pos: Position in grid tile coordinates (only when parent is Grid)
• grid_size: Size in grid tile coordinates (only when parent is Grid)
• h (read-only): Text height in pixels (read-only)
• horiz_margin: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
• hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
• margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
• name: Name for finding elements
• on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
• on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
• on_exit: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
• on_move: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
• opacity: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
• origin: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
• outline: Thickness of the border
• outline_color: Outline color of the text. Returns a copy; modifying components requires reassignment. For animation, use 'outline_color.r', 'outline_color.g', etc.
• parent: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
• pos: (x, y) vector
• rotate_with_camera: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
• rotation: Rotation angle in degrees (clockwise around origin). Animatable property.
• shader: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
• size (read-only): Text dimensions as Vector (read-only)
• text: The text displayed
• uniforms (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
• vert_margin: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
• visible: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
• w (read-only): Text width in pixels (read-only)
• x: X coordinate of top-left corner
• y: Y coordinate of top-left corner
• z_index: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.

Methods:

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: on_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 align (Alignment): Alignment relative to parent. Default: None margin (float): Margin from parent edge when aligned. Default: 0 horiz_margin (float): Horizontal margin override. Default: 0 (use margin) vert_margin (float): Vertical margin override. Default: 0 (use margin) 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 align (Alignment): Alignment relative to parent (or None) margin (float): General margin for alignment horiz_margin (float): Horizontal margin override vert_margin (float): Vertical margin override

Properties:

• align: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
• bounds: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
• center: Center position of the circle
• fill_color: Fill color of the circle
• global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
• global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
• grid_pos: Position in grid tile coordinates (only when parent is Grid)
• grid_size: Size in grid tile coordinates (only when parent is Grid)
• horiz_margin: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
• hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
• margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
• name: Name for finding this element.
• on_click: Callable executed when circle is clicked. Function receives (pos: Vector, button: str, action: str).
• on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
• on_exit: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
• on_move: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
• opacity: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
• origin: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
• outline: Outline thickness (0 for no outline)
• outline_color: Outline color of the circle
• parent: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
• pos: Position as a Vector (same as center).
• radius: Circle radius in pixels
• rotate_with_camera: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
• rotation: Rotation angle in degrees (clockwise around origin). Animatable property.
• vert_margin: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
• visible: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
• z_index: Z-order for rendering (lower values rendered first).

Methods:

Color

Color(r: int = 0, g: int = 0, b: int = 0, a: int = 255) RGBA color representation. Args: r: Red component (0-255) g: Green component (0-255) b: Blue component (0-255) a: Alpha component (0-255, default 255 = opaque) Note: When accessing colors from UI elements (e.g., frame.fill_color), you receive a COPY of the color. Modifying it doesn't affect the original. To change a component: # This does NOT work: frame.fill_color.r = 255 # Modifies a temporary copy # Do this instead: c = frame.fill_color c.r = 255 frame.fill_color = c # Or use Animation for sub-properties: anim = mcrfpy.Animation('fill_color.r', 255, 0.5, 'linear') anim.start(frame)

Properties:

• a: Alpha component (0-255, where 0=transparent, 255=opaque). Automatically clamped to valid range.
• b: Blue component (0-255). Automatically clamped to valid range.
• g: Green component (0-255). Automatically clamped to valid range.
• r: Red component (0-255). Automatically clamped to valid range.

Methods:

ColorLayer

ColorLayer(z_index=-1, name=None, grid_size=None) A grid layer that stores RGBA colors per cell for background/overlay effects. ColorLayers can be created standalone and attached to a Grid via add_layer() or passed to the Grid constructor's layers parameter. Layers with size (0, 0) automatically resize to match the Grid when attached. Args: z_index (int): Render order relative to entities. Negative values render below entities (as backgrounds), positive values render above entities (as overlays). Default: -1 (background) name (str): Layer name for Grid.layer(name) lookup. Default: None grid_size (tuple): Dimensions as (width, height). If None or (0, 0), the layer will auto-resize when attached to a Grid. Default: None Attributes: z_index (int): Layer z-order relative to entities (read/write) name (str): Layer name for lookup (read-only) visible (bool): Whether layer is rendered (read/write) grid_size (tuple): Layer dimensions as (width, height) (read-only) grid (Grid): Parent Grid or None. Setting manages layer association. Methods: at(x, y) -> Color: Get the color at cell position (x, y) set(x, y, color): Set the color at cell position (x, y) fill(color): Fill the entire layer with a single color fill_rect(x, y, w, h, color): Fill a rectangular region with a color draw_fov(...): Draw FOV-based visibility colors apply_perspective(entity, ...): Bind layer to entity for automatic FOV updates Example: fog = mcrfpy.ColorLayer(z_index=-1, name='fog') grid = mcrfpy.Grid(grid_size=(20, 15), layers=[fog]) fog.fill(mcrfpy.Color(40, 40, 40)) # Dark gray background grid.layer('fog').set(5, 5, mcrfpy.Color(255, 0, 0, 128))

Properties:

• grid: Parent Grid or None. Setting manages layer association and handles lazy allocation.
• grid_size: Layer dimensions as (width, height) tuple.
• name (read-only): Layer name (str, read-only). Used for Grid.layer(name) lookup.
• visible: Whether the layer is rendered.
• z_index: Layer z-order. Negative values render below entities.

Methods:

DijkstraMap

A Dijkstra distance map from a fixed root position. Created by Grid.get_dijkstra_map(). Cannot be instantiated directly. Grid caches these maps - multiple requests for the same root return the same map. Call Grid.clear_dijkstra_maps() after changing grid walkability to invalidate the cache. Properties: root (Vector): Root position (read-only) Methods: distance(pos) -> float | None: Get distance to root path_from(pos) -> AStarPath: Get full path to root step_from(pos) -> Vector | None: Get single step toward root Example: dijkstra = grid.get_dijkstra_map(player.pos) for enemy in enemies: dist = dijkstra.distance(enemy.pos) if dist and dist < 10: step = dijkstra.step_from(enemy.pos) if step: enemy.pos = step

Properties:

• root (read-only): Root position that distances are measured from (Vector, read-only).

Methods:

DiscreteMap

DiscreteMap(size: tuple[int, int], fill: int = 0, enum: type[IntEnum] = None) A 2D grid of uint8 values (0-255) for discrete/categorical data. DiscreteMap provides memory-efficient storage for terrain types, region IDs, walkability masks, and other categorical data. Uses 4x less memory than HeightMap for the same dimensions. Args: size: (width, height) dimensions. Immutable after creation. fill: Initial value for all cells (0-255). Default 0. enum: Optional IntEnum class for value interpretation. Example: from enum import IntEnum class Terrain(IntEnum): WATER = 0 GRASS = 1 MOUNTAIN = 2 dmap = mcrfpy.DiscreteMap((100, 100), fill=0, enum=Terrain) dmap.fill(Terrain.GRASS, pos=(10, 10), size=(20, 20)) print(dmap[15, 15]) # Terrain.GRASS

Properties:

• enum_type: Optional IntEnum class for value interpretation.
• size (read-only): Dimensions (width, height) of the map. Read-only.

Methods:

Drawable

Base class for all drawable UI elements

Properties:

• on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
• opacity: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
• visible: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
• z_index: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.

Methods:

Easing

Inherits from: IntEnum

Properties:

• denominator: the denominator of a rational number in lowest terms
• imag: the imaginary part of a complex number
• numerator: the numerator of a rational number in lowest terms
• real: the real part of a complex number

Methods:

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 (tile coords). Default: 0 y (float): Y grid position override (tile coords). Default: 0 sprite_offset (tuple): Pixel offset for oversized sprites. Default: (0, 0) sprite_grid (list): Per-tile sprite indices for composite entities. Default: None Attributes: pos (Vector): Pixel position relative to grid (requires grid attachment) x, y (float): Pixel position components (requires grid attachment) grid_pos (Vector): Integer tile coordinates (logical game position) grid_x, grid_y (int): Integer tile coordinate components draw_pos (Vector): Fractional tile position for smooth animation perspective_map (DiscreteMap | None): 3-state per-entity FOV memory sprite_index (int): Current sprite index visible (bool): Visibility state opacity (float): Opacity value name (str): Element name sprite_offset (Vector): Pixel offset for oversized sprites sprite_offset_x (float): X component of sprite offset sprite_offset_y (float): Y component of sprite offset

Properties:

• behavior_type (read-only): Current behavior type (int, read-only). Use set_behavior() to change.
• cell_pos: Integer logical cell position (Vector). Decoupled from draw_pos. Determines which cell this entity logically occupies for collision, pathfinding, etc.
• cell_x: Integer X cell coordinate.
• cell_y: Integer Y cell coordinate.
• default_behavior: Default behavior type (int, maps to Behavior enum). Entity reverts to this after DONE trigger. Default: 0 (IDLE).
• draw_pos: Fractional tile position for rendering (Vector). Use for smooth animation between grid cells.
• grid: Grid this entity belongs to. Get: Returns the Grid or None. Set: Assign a Grid to move entity, or None to remove from grid.
• grid_pos: Grid position as integer cell coordinates (Vector). Alias for cell_pos.
• grid_x: Grid X position as integer cell coordinate. Alias for cell_x.
• grid_y: Grid Y position as integer cell coordinate. Alias for cell_y.
• labels: Set of string labels for collision/targeting (frozenset). Assign any iterable of strings to replace all labels.
• move_speed: Animation duration for behavior movement in seconds (float). 0 = instant. Default: 0.15.
• name: Name for finding elements
• opacity: Opacity (0.0 = transparent, 1.0 = opaque)
• perspective_map: Per-entity FOV memory (DiscreteMap, read-write). 3-state values per cell: 0 = unknown (never seen), 1 = discovered (seen before, not currently visible), 2 = visible (in current FOV). Use mcrfpy.Perspective enum for clarity. Lazy-allocated on first access once the entity has a grid; returns None otherwise. The returned DiscreteMap is a live reference -- mutations are visible to subsequent updateVisibility() calls. Assigning a DiscreteMap replaces the entity's memory; the new map's size must match the grid's size or ValueError is raised. Assign None to clear (will be lazy-reallocated on next access).
• pos: Pixel position relative to grid (Vector). Computed as draw_pos * tile_size. Requires entity to be attached to a grid.
• shader: Shader for GPU visual effects (Shader or None). When set, the entity is rendered through the shader program. Set to None to disable shader effects.
• sight_radius: FOV radius for TARGET trigger (int). Default: 10.
• sprite_grid: Per-tile sprite indices for composite multi-tile entities (list of lists or None). Row-major, dimensions must match tile_width x tile_height. Use -1 for empty tiles. When set, each tile renders its own sprite index instead of the single entity sprite.
• sprite_index: Sprite index on the texture on the display
• sprite_offset: Pixel offset for oversized sprites (Vector). Applied pre-zoom during grid rendering.
• sprite_offset_x: X component of sprite pixel offset.
• sprite_offset_y: Y component of sprite pixel offset.
• step: Step callback for grid.step() turn management. Called with (trigger, data) when behavior triggers fire. Set to None to clear.
• target_label: Label to search for with TARGET trigger (str or None). Default: None.
• tile_height: Entity height in tiles (int). Must be >= 1. Default 1.
• tile_size: Entity size in tiles as (width, height) Vector. Default (1, 1).
• tile_width: Entity width in tiles (int). Must be >= 1. Default 1.
• turn_order: Turn order for grid.step() (int). 0 = skip, higher values go later. Default: 1.
• uniforms (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: entity.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
• visible: Visibility flag
• x: Pixel X position relative to grid. Requires entity to be attached to a grid.
• y: Pixel Y position relative to grid. Requires entity to be attached to a grid.

Methods:

Entity3D

Entity3D(pos=None, **kwargs) A 3D game entity that exists on a Viewport3D's navigation grid. Args: pos (tuple, optional): Grid position as (x, z). Default: (0, 0) Keyword Args: viewport (Viewport3D): Viewport to attach entity to. Default: None rotation (float): Y-axis rotation in degrees. Default: 0 scale (float or tuple): Scale factor. Default: 1.0 visible (bool): Visibility state. Default: True color (Color): Entity color. Default: orange Attributes: pos (tuple): Grid position (x, z) - setting triggers movement grid_pos (tuple): Same as pos (read-only) world_pos (tuple): Current world coordinates (x, y, z) (read-only) rotation (float): Y-axis rotation in degrees scale (float): Uniform scale factor visible (bool): Visibility state color (Color): Entity render color viewport (Viewport3D): Owning viewport (read-only)

Properties:

• anim_clip: Current animation clip name. Set to play an animation.
• anim_frame (read-only): Current animation frame number (read-only, approximate at 30fps).
• anim_loop: Whether animation loops when it reaches the end.
• anim_paused: Whether animation playback is paused.
• anim_speed: Animation playback speed multiplier. 1.0 = normal speed.
• anim_time: Current time position in animation (seconds).
• auto_animate: Enable auto-play of walk/idle clips based on movement.
• color: Entity render color.
• grid_pos: Grid position (x, z). Same as pos.
• idle_clip: Animation clip to play when entity is stationary.
• is_moving (read-only): Whether entity is currently moving (read-only).
• model: 3D model (Model3D). If None, uses placeholder cube.
• name: Entity name (str). Used for find() lookup.
• on_anim_complete: Callback(entity, clip_name) when non-looping animation ends.
• pos: Grid position (x, z). Setting triggers smooth movement.
• rotation: Y-axis rotation in degrees.
• scale: Uniform scale factor. Can also set as (x, y, z) tuple.
• viewport (read-only): Owning Viewport3D (read-only).
• visible: Visibility state.
• walk_clip: Animation clip to play when entity is moving.
• world_pos (read-only): Current world position (x, y, z) (read-only). Includes animation interpolation.

Methods:

EntityCollection3D

Collection of Entity3D objects belonging to a Viewport3D. Supports list-like operations: indexing, iteration, append, remove. Example: viewport.entities.append(entity) for entity in viewport.entities: print(entity.pos)

Methods:

EntityCollection3DIter

Iterator for EntityCollection3D

Methods:

FOV

Inherits from: IntEnum

Properties:

• denominator: the denominator of a rational number in lowest terms
• imag: the imaginary part of a complex number
• numerator: the numerator of a rational number in lowest terms
• real: the real part of a complex number

Methods:

Font

Font(filename: str) A font resource for rendering text in Caption elements. Args: filename: Path to a TrueType (.ttf) or OpenType (.otf) font file. Properties: family (str, read-only): Font family name from metadata. source (str, read-only): File path used to load this font.

Properties:

• family (read-only): Font family name (str, read-only). Retrieved from font metadata.
• source (read-only): Source filename path (str, read-only). The path used to load this font.

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 align (Alignment): Alignment relative to parent. Default: None (manual positioning) margin (float): Margin from parent edge when aligned. Default: 0 horiz_margin (float): Horizontal margin override. Default: 0 (use margin) vert_margin (float): Vertical margin override. Default: 0 (use margin) 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 align (Alignment): Alignment relative to parent (or None) margin (float): General margin for alignment horiz_margin (float): Horizontal margin override vert_margin (float): Vertical margin override

Properties:

• align: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
• bounds: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
• cache_subtree: #144: Cache subtree rendering to texture for performance
• children: UICollection of objects on top of this one
• clip_children: Whether to clip children to frame bounds
• fill_color: Fill color of the rectangle. Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc.
• global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
• global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
• grid_pos: Position in grid tile coordinates (only when parent is Grid)
• grid_size: Size in grid tile coordinates (only when parent is Grid)
• h: height of the rectangle
• horiz_margin: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
• hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
• margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
• name: Name for finding elements
• on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
• on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
• on_exit: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
• on_move: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
• opacity: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
• origin: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
• outline: Thickness of the border
• outline_color: Outline color of the rectangle. Returns a copy; modifying components requires reassignment. For animation, use 'outline_color.r', 'outline_color.g', etc.
• parent: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
• pos: Position as a Vector
• rotate_with_camera: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
• rotation: Rotation angle in degrees (clockwise around origin). Animatable property.
• shader: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
• uniforms (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
• vert_margin: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
• visible: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
• w: width of the rectangle
• x: X coordinate of top-left corner
• y: Y coordinate of top-left corner
• z_index: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.

Methods:

Grid

Inherits from: Drawable

Grid(grid_size=None, pos=None, size=None, texture=None, **kwargs) A grid-based UI element for tile-based rendering and entity management. Creates and owns grid data (cells, entities, layers) with an integrated rendering view (camera, zoom, perspective). Can also be constructed as a view of existing grid data: Grid(grid=existing_grid, pos=..., size=...) Args: grid_size (tuple): Grid dimensions as (grid_w, grid_h). Default: (2, 2) pos (tuple): Position as (x, y). Default: (0, 0) size (tuple): Size as (w, h). Default: auto-calculated texture (Texture): Tile texture atlas. Default: default texture Keyword Args: grid (Grid): Existing Grid to view (creates view of shared data). fill_color (Color): Background fill color. on_click (callable): Click event handler. center_x, center_y (float): Camera center coordinates. zoom (float): Zoom level. Default: 1.0 visible (bool): Visibility. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. Default: 0 name (str): Element name. layers (list): List of ColorLayer/TileLayer objects.

Properties:

• align: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
• bounds: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
• camera_rotation: Rotation of grid contents around camera center (degrees).
• center: Camera center point in pixel coordinates.
• center_x: center of the view X-coordinate
• center_y: center of the view Y-coordinate
• fill_color: Background fill color.
• global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
• global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
• grid_data: The underlying grid data object (for multi-view scenarios).
• h: visible widget height
• horiz_margin: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
• hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
• margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
• name: Name for finding elements
• on_click: Callable executed when object is clicked.
• on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
• on_exit: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
• on_move: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
• opacity: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
• origin: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
• parent: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
• pos: Position of the grid as Vector
• rotate_with_camera: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
• rotation: Rotation angle in degrees (clockwise around origin). Animatable property.
• shader: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
• texture (read-only): Texture used for tile rendering (read-only).
• uniforms (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
• vert_margin: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
• visible: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
• w: visible widget width
• x: top-left corner X-coordinate
• y: top-left corner Y-coordinate
• z_index: Z-order for rendering (lower values rendered first).
• zoom: Zoom level for rendering.

Methods:

GridView

Inherits from: Drawable

Grid(grid_size=None, pos=None, size=None, texture=None, **kwargs) A grid-based UI element for tile-based rendering and entity management. Creates and owns grid data (cells, entities, layers) with an integrated rendering view (camera, zoom, perspective). Can also be constructed as a view of existing grid data: Grid(grid=existing_grid, pos=..., size=...) Args: grid_size (tuple): Grid dimensions as (grid_w, grid_h). Default: (2, 2) pos (tuple): Position as (x, y). Default: (0, 0) size (tuple): Size as (w, h). Default: auto-calculated texture (Texture): Tile texture atlas. Default: default texture Keyword Args: grid (Grid): Existing Grid to view (creates view of shared data). fill_color (Color): Background fill color. on_click (callable): Click event handler. center_x, center_y (float): Camera center coordinates. zoom (float): Zoom level. Default: 1.0 visible (bool): Visibility. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. Default: 0 name (str): Element name. layers (list): List of ColorLayer/TileLayer objects.

Properties:

• align: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
• bounds: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
• camera_rotation: Rotation of grid contents around camera center (degrees).
• center: Camera center point in pixel coordinates.
• center_x: center of the view X-coordinate
• center_y: center of the view Y-coordinate
• fill_color: Background fill color.
• global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
• global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
• grid_data: The underlying grid data object (for multi-view scenarios).
• h: visible widget height
• horiz_margin: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
• hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
• margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
• name: Name for finding elements
• on_click: Callable executed when object is clicked.
• on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
• on_exit: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
• on_move: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
• opacity: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
• origin: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
• parent: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
• pos: Position of the grid as Vector
• rotate_with_camera: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
• rotation: Rotation angle in degrees (clockwise around origin). Animatable property.
• shader: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
• texture (read-only): Texture used for tile rendering (read-only).
• uniforms (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
• vert_margin: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
• visible: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
• w: visible widget width
• x: top-left corner X-coordinate
• y: top-left corner Y-coordinate
• z_index: Z-order for rendering (lower values rendered first).
• zoom: Zoom level for rendering.

Methods:

HeightMap

HeightMap(size: tuple[int, int], fill: float = 0.0) A 2D grid of float values for procedural generation. HeightMap is the universal canvas for procedural generation. It stores float values that can be manipulated, combined, and applied to Grid and Layer objects. Args: size: (width, height) dimensions of the heightmap. Immutable after creation. fill: Initial value for all cells. Default 0.0. Example: hmap = mcrfpy.HeightMap((100, 100)) hmap.fill(0.5).scale(2.0).clamp(0.0, 1.0) value = hmap[5, 5] # Subscript shorthand for get()

Properties:

• size (read-only): Dimensions (width, height) of the heightmap. Read-only.

Methods:

InputState

Inherits from: IntEnum

Enum representing input event states (pressed/released). Values: PRESSED: Key or button was pressed RELEASED: Key or button was released

Properties:

• denominator: the denominator of a rational number in lowest terms
• imag: the imaginary part of a complex number
• numerator: the numerator of a rational number in lowest terms
• real: the real part of a complex number

Methods:

Key

Inherits from: IntEnum

Enum representing keyboard keys. Values map to SFML's sf::Keyboard::Key enum. Categories: Letters: A-Z Numbers: NUM_0 through NUM_9 (top row) Numpad: NUMPAD_0 through NUMPAD_9 Function: F1 through F15 Modifiers: LEFT_SHIFT, RIGHT_SHIFT, LEFT_CONTROL, etc. Navigation: LEFT, RIGHT, UP, DOWN, HOME, END, PAGE_UP, PAGE_DOWN Editing: ENTER, BACKSPACE, DELETE, INSERT, TAB, SPACE Symbols: COMMA, PERIOD, SLASH, SEMICOLON, etc.

Properties:

• denominator: the denominator of a rational number in lowest terms
• imag: the imaginary part of a complex number
• numerator: the numerator of a rational number in lowest terms
• real: the real part of a complex number

Methods:

Keyboard

Keyboard state singleton for checking modifier keys

Properties:

• alt (read-only): True if either Alt key is currently pressed (read-only).
• ctrl (read-only): True if either Control key is currently pressed (read-only).
• shift (read-only): True if either Shift key is currently pressed (read-only).
• system (read-only): True if either System key (Win/Cmd) is currently pressed (read-only).

Methods:

LdtkProject

LdtkProject(path: str) Load an LDtk project file (.ldtk). Parses the project and provides access to tilesets, auto-rule sets, levels, and enum definitions. Args: path: Path to the .ldtk project file. Properties: version (str, read-only): LDtk JSON format version. tileset_names (list[str], read-only): Names of all tilesets. ruleset_names (list[str], read-only): Names of all rule sets. level_names (list[str], read-only): Names of all levels. enums (dict, read-only): Enum definitions from the project. Example: proj = mcrfpy.LdtkProject('dungeon.ldtk') ts = proj.tileset('Dungeon_Tiles') rs = proj.ruleset('Walls') level = proj.level('Level_0')

Properties:

• enums (read-only): Enum definitions from the project as a list of dicts (read-only).
• level_names (read-only): List of level identifier names (list[str], read-only).
• ruleset_names (read-only): List of rule set / layer names (list[str], read-only).
• tileset_names (read-only): List of tileset identifier names (list[str], read-only).
• version (read-only): LDtk JSON format version string (str, read-only).

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: on_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 align (Alignment): Alignment relative to parent. Default: None margin (float): Margin from parent edge when aligned. Default: 0 horiz_margin (float): Horizontal margin override. Default: 0 (use margin) vert_margin (float): Vertical margin override. Default: 0 (use margin) 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 align (Alignment): Alignment relative to parent (or None) margin (float): General margin for alignment horiz_margin (float): Horizontal margin override vert_margin (float): Vertical margin override

Properties:

• align: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
• bounds: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
• color: Line color as a Color object.
• end: Ending point of the line as a Vector.
• global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
• global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
• grid_pos: Position in grid tile coordinates (only when parent is Grid)
• grid_size: Size in grid tile coordinates (only when parent is Grid)
• horiz_margin: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
• hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
• margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
• name: Name for finding this element.
• on_click: Callable executed when line is clicked. Function receives (pos: Vector, button: str, action: str).
• on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
• on_exit: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
• on_move: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
• opacity: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
• origin: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
• parent: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
• pos: Position as a Vector (midpoint of line).
• rotate_with_camera: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
• rotation: Rotation angle in degrees (clockwise around origin). Animatable property.
• start: Starting point of the line as a Vector.
• thickness: Line thickness in pixels.
• vert_margin: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
• visible: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
• z_index: Z-order for rendering (lower values rendered first).

Methods:

Model3D

Model3D(path=None) A 3D model resource that can be rendered by Entity3D. Args: path (str, optional): Path to .glb file to load. If None, creates empty model. Class Methods: cube(size=1.0) -> Model3D: Create a unit cube plane(width=1.0, depth=1.0, segments=1) -> Model3D: Create a flat plane sphere(radius=0.5, segments=16, rings=12) -> Model3D: Create a UV sphere Properties: name (str, read-only): Model name vertex_count (int, read-only): Total vertices across all meshes triangle_count (int, read-only): Total triangles across all meshes has_skeleton (bool, read-only): Whether model has skeletal animation data bounds (tuple, read-only): AABB as ((min_x, min_y, min_z), (max_x, max_y, max_z)) mesh_count (int, read-only): Number of submeshes bone_count (int, read-only): Number of bones in skeleton animation_clips (list, read-only): List of animation clip names

Properties:

• animation_clips (read-only): List of animation clip names (read-only)
• bone_count (read-only): Number of bones in skeleton (read-only)
• bounds (read-only): AABB as ((min_x, min_y, min_z), (max_x, max_y, max_z)) (read-only)
• has_skeleton (read-only): Whether model has skeletal animation data (read-only)
• mesh_count (read-only): Number of submeshes (read-only)
• name (read-only): Model name (read-only)
• triangle_count (read-only): Total triangle count across all meshes (read-only)
• vertex_count (read-only): Total vertex count across all meshes (read-only)

Methods:

Mouse

Mouse state singleton for reading button/position state and controlling cursor visibility

Properties:

• grabbed: Whether the mouse cursor is confined to the window (default: False).
• left (read-only): True if left mouse button is currently pressed (read-only).
• middle (read-only): True if middle mouse button is currently pressed (read-only).
• pos (read-only): Current mouse position as Vector (read-only).
• right (read-only): True if right mouse button is currently pressed (read-only).
• visible: Whether the mouse cursor is visible (default: True).
• x (read-only): Current mouse X position in window coordinates (read-only).
• y (read-only): Current mouse Y position in window coordinates (read-only).

Methods:

MouseButton

Inherits from: IntEnum

Enum representing mouse buttons and scroll wheel. Values: LEFT: Left mouse button RIGHT: Right mouse button MIDDLE: Middle mouse button / scroll wheel click X1: Extra mouse button 1 X2: Extra mouse button 2 SCROLL_UP: Scroll wheel up SCROLL_DOWN: Scroll wheel down

Properties:

• denominator: the denominator of a rational number in lowest terms
• imag: the imaginary part of a complex number
• numerator: the numerator of a rational number in lowest terms
• real: the real part of a complex number

Methods:

Music

Streaming music object for longer audio tracks

Properties:

• duration (read-only): Total duration of the music in seconds (read-only).
• loop: Whether the music loops when it reaches the end.
• playing (read-only): True if the music is currently playing (read-only).
• position: Current playback position in seconds. Can be set to seek.
• source (read-only): Filename path used to load this music (read-only).
• volume: Volume level from 0 (silent) to 100 (full volume).

Methods:

NoiseSource

NoiseSource(dimensions: int = 2, algorithm: str = 'simplex', hurst: float = 0.5, lacunarity: float = 2.0, seed: int = None) A configured noise generator for procedural generation. NoiseSource wraps libtcod's noise generator, providing coherent noise values that can be used for terrain generation, textures, and other procedural content. The same coordinates always produce the same value (deterministic). Args: dimensions: Number of input dimensions (1-4). Default: 2. algorithm: Noise algorithm - 'simplex', 'perlin', or 'wavelet'. Default: 'simplex'. hurst: Fractal Hurst exponent for fbm/turbulence (0.0-1.0). Default: 0.5. lacunarity: Frequency multiplier between octaves. Default: 2.0. seed: Random seed for reproducibility. None for random seed. Properties: dimensions (int): Read-only. Number of input dimensions. algorithm (str): Read-only. Noise algorithm name. hurst (float): Read-only. Hurst exponent. lacunarity (float): Read-only. Lacunarity value. seed (int): Read-only. Seed used (even if originally None). Example: noise = mcrfpy.NoiseSource(dimensions=2, algorithm='simplex', seed=42) value = noise.get((10.5, 20.3)) # Returns -1.0 to 1.0 fbm_val = noise.fbm((10.5, 20.3), octaves=6)

Properties:

• algorithm (read-only): Noise algorithm name ('simplex', 'perlin', or 'wavelet'). Read-only.
• dimensions (read-only): Number of input dimensions (1-4). Read-only.
• hurst (read-only): Hurst exponent for fbm/turbulence. Read-only.
• lacunarity (read-only): Frequency multiplier between octaves. Read-only.
• seed (read-only): Random seed used (even if originally None). Read-only.

Methods:

Perspective

Inherits from: IntEnum

Enum representing an entity's knowledge of a cell. Values: UNKNOWN: Never seen (perspective_map value 0) DISCOVERED: Seen before but not currently visible (value 1) VISIBLE: In current FOV (value 2)

Properties:

• denominator: the denominator of a rational number in lowest terms
• imag: the imaginary part of a complex number
• numerator: the numerator of a rational number in lowest terms
• real: the real part of a complex number

Methods:

PropertyBinding

PropertyBinding(target: UIDrawable, property: str) A binding that reads a property value from a UI drawable. Args: target: The drawable to read the property from property: Name of the property to read (e.g., 'x', 'opacity') Use this to create dynamic shader uniforms that follow a drawable's properties. The binding automatically handles cases where the target is destroyed. Example: other_frame = mcrfpy.Frame(pos=(100, 100)) frame.uniforms['offset_x'] = mcrfpy.PropertyBinding(other_frame, 'x')

Properties:

• is_valid (read-only): True if the binding target still exists and property is valid (bool, read-only).
• property (read-only): The property name being read (str, read-only).
• target (read-only): The drawable this binding reads from (read-only).
• value (read-only): Current value of the binding (float, read-only). Returns None if invalid.

Methods:

Scene

Scene(name: str) Object-oriented scene management with lifecycle callbacks. This is the recommended approach for scene management, replacing module-level functions like createScene(), setScene(), and sceneUI(). Key advantage: you can set on_key handlers on ANY scene, not just the currently active one. Args: name: Unique identifier for this scene. Used for scene transitions. Properties: name (str, read-only): Scene's unique identifier. active (bool, read-only): Whether this scene is currently displayed. children (UICollection, read-only): UI elements in this scene. Modify to add/remove elements. on_key (callable): Keyboard handler. Set on ANY scene, regardless of which is active! pos (Vector): Position offset for all UI elements. visible (bool): Whether the scene renders. opacity (float): Scene transparency (0.0-1.0). Lifecycle Callbacks (override in subclass): on_enter(): Called when scene becomes active via activate(). on_exit(): Called when scene is deactivated (another scene activates). on_key(key: str, action: str): Called for keyboard events (subclass method). update(dt: float): Called every frame with delta time in seconds. on_resize(new_size: Vector): Called when window is resized. Example: # Basic usage (replacing module functions): scene = mcrfpy.Scene('main_menu') scene.children.append(mcrfpy.Caption(text='Welcome', pos=(100, 100))) scene.on_key = lambda key, action: print(f'Key: {key}') scene.activate() # Switch to this scene # Subclassing for lifecycle: class GameScene(mcrfpy.Scene): def on_enter(self): print('Game started!') def update(self, dt): self.player.move(dt)

Properties:

• active (read-only): Whether this scene is currently active (bool, read-only). Only one scene can be active at a time.
• children (read-only): UI element collection for this scene (UICollection, read-only). Use to add, remove, or iterate over UI elements. Changes are reflected immediately.
• name (read-only): Scene name (str, read-only). Unique identifier for this scene.
• on_key: Keyboard event handler (callable or None). Function receives (key: Key, action: InputState) for keyboard events. Set to None to remove the handler.
• opacity: Scene opacity (0.0-1.0). Applied to all UI elements during rendering.
• pos: Scene position offset (Vector). Applied to all UI elements during rendering.
• registered (read-only): Whether this scene is registered with the game engine (bool, read-only). Unregistered scenes still exist but won't receive lifecycle callbacks.
• visible: Scene visibility (bool). If False, scene is not rendered.

Methods:

Shader

Shader(fragment_source: str, dynamic: bool = False) A GPU shader program for visual effects. Args: fragment_source: GLSL fragment shader source code dynamic: If True, shader uses time-varying effects and will invalidate parent caches each frame Shaders enable GPU-accelerated visual effects like glow, distortion, color manipulation, and more. Assign to drawable.shader to apply. Engine-provided uniforms (automatically available): - float time: Seconds since engine start - float delta_time: Seconds since last frame - vec2 resolution: Texture size in pixels - vec2 mouse: Mouse position in window coordinates Example: shader = mcrfpy.Shader(''' uniform sampler2D texture; uniform float time; void main() { vec2 uv = gl_TexCoord[0].xy; vec4 color = texture2D(texture, uv); color.rgb *= 0.5 + 0.5 * sin(time); gl_FragColor = color; } ''', dynamic=True) frame.shader = shader

Properties:

• dynamic: Whether this shader uses time-varying effects (bool). Dynamic shaders invalidate parent caches each frame.
• is_valid (read-only): True if the shader compiled successfully (bool, read-only).
• source (read-only): The GLSL fragment shader source code (str, read-only).

Methods:

Sound

Sound(source) Sound effect object for short audio clips. Args: source: Filename string or SoundBuffer object. Properties: volume (float): Volume 0-100. loop (bool): Whether to loop. playing (bool, read-only): True if playing. duration (float, read-only): Duration in seconds. source (str, read-only): Source filename. pitch (float): Playback pitch (1.0 = normal). buffer (SoundBuffer, read-only): The SoundBuffer, if created from one.

Properties:

• buffer (read-only): The SoundBuffer if created from one, else None (read-only).
• duration (read-only): Total duration of the sound in seconds (read-only).
• loop: Whether the sound loops when it reaches the end.
• pitch: Playback pitch multiplier (1.0 = normal, >1 = higher, <1 = lower).
• playing (read-only): True if the sound is currently playing (read-only).
• source (read-only): Filename path used to load this sound (read-only).
• volume: Volume level from 0 (silent) to 100 (full volume).

Methods:

SoundBuffer

SoundBuffer(filename: str) SoundBuffer.from_samples(data: bytes, channels: int, sample_rate: int) SoundBuffer.tone(frequency: float, duration: float, waveform: str = 'sine', ...) SoundBuffer.sfxr(preset: str, seed: int = None) Audio sample buffer for procedural audio generation and effects. Holds PCM sample data that can be created from files, raw samples, tone synthesis, or sfxr presets. Effect methods return new SoundBuffer instances (copy-modify pattern). Properties: duration (float, read-only): Duration in seconds. sample_count (int, read-only): Total number of samples. sample_rate (int, read-only): Samples per second (e.g. 44100). channels (int, read-only): Number of audio channels. sfxr_params (dict or None, read-only): sfxr parameters if sfxr-generated.

Properties:

• channels (read-only): Number of audio channels (read-only).
• duration (read-only): Total duration in seconds (read-only).
• sample_count (read-only): Total number of samples (read-only).
• sample_rate (read-only): Sample rate in Hz (read-only).
• sfxr_params (read-only): Dict of sfxr parameters if sfxr-generated, else None (read-only).

Methods:

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 align (Alignment): Alignment relative to parent. Default: None margin (float): Margin from parent edge when aligned. Default: 0 horiz_margin (float): Horizontal margin override. Default: 0 (use margin) vert_margin (float): Vertical margin override. Default: 0 (use margin) 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 align (Alignment): Alignment relative to parent (or None) margin (float): General margin for alignment horiz_margin (float): Horizontal margin override vert_margin (float): Vertical margin override

Properties:

• align: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
• bounds: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
• global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
• global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
• grid_pos: Position in grid tile coordinates (only when parent is Grid)
• grid_size: Size in grid tile coordinates (only when parent is Grid)
• horiz_margin: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
• hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
• margin: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
• name: Name for finding elements
• on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
• on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
• on_exit: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
• on_move: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
• opacity: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
• origin: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
• parent: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
• pos: Position as a Vector
• rotate_with_camera: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
• rotation: Rotation angle in degrees (clockwise around origin). Animatable property.
• scale: Uniform size factor
• scale_x: Horizontal scale factor
• scale_y: Vertical scale factor
• shader: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
• sprite_index: Which sprite on the texture is shown
• texture: Texture object
• uniforms (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
• vert_margin: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
• visible: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
• x: X coordinate of top-left corner
• y: Y coordinate of top-left corner
• z_index: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.

Methods:

Texture

Texture(filename: str, sprite_width: int = 0, sprite_height: int = 0, display_size: tuple = None, display_origin: tuple = None) A texture atlas for sprites and tiles. Args: filename: Path to an image file (PNG, BMP, etc.). sprite_width: Width of each sprite cell in pixels (0 = full image). sprite_height: Height of each sprite cell in pixels (0 = full image). display_size: Optional (w, h) actual content size within each cell. display_origin: Optional (x, y) content offset within each cell. Properties: sprite_width, sprite_height (int, read-only): Cell dimensions. sheet_width, sheet_height (int, read-only): Grid dimensions in cells. sprite_count (int, read-only): Total number of sprite cells. source (str, read-only): File path used to load this texture. display_width, display_height (int, read-only): Content size within cells. display_offset_x, display_offset_y (int, read-only): Content offset within cells.

Properties:

• display_height (read-only): Display height of sprite content within each cell (int, read-only). Defaults to sprite_height.
• display_offset_x (read-only): X offset of sprite content within each cell (int, read-only). Default 0.
• display_offset_y (read-only): Y offset of sprite content within each cell (int, read-only). Default 0.
• display_width (read-only): Display width of sprite content within each cell (int, read-only). Defaults to sprite_width.
• sheet_height (read-only): Number of sprite rows in the texture sheet (int, read-only). Calculated as texture_height / sprite_height.
• sheet_width (read-only): Number of sprite columns in the texture sheet (int, read-only). Calculated as texture_width / sprite_width.
• source (read-only): Source filename path (str, read-only). The path used to load this texture.
• sprite_count (read-only): Total number of sprites in the texture sheet (int, read-only). Equals sheet_width * sheet_height.
• sprite_height (read-only): Height of each sprite in pixels (int, read-only). Specified during texture initialization.
• sprite_width (read-only): Width of each sprite in pixels (int, read-only). Specified during texture initialization.

Methods:

TileLayer

TileLayer(z_index=-1, name=None, texture=None, grid_size=None) A grid layer that stores sprite indices per cell for tile-based rendering. TileLayers can be created standalone and attached to a Grid via add_layer() or passed to the Grid constructor's layers parameter. Layers with size (0, 0) automatically resize to match the Grid when attached. Args: z_index (int): Render order relative to entities. Negative values render below entities (as backgrounds), positive values render above entities (as overlays). Default: -1 (background) name (str): Layer name for Grid.layer(name) lookup. Default: None texture (Texture): Sprite atlas containing tile images. The texture's sprite_size determines individual tile dimensions. Required for rendering; can be set after creation. Default: None grid_size (tuple): Dimensions as (width, height). If None or (0, 0), the layer will auto-resize when attached to a Grid. Default: None Attributes: z_index (int): Layer z-order relative to entities (read/write) name (str): Layer name for lookup (read-only) visible (bool): Whether layer is rendered (read/write) texture (Texture): Sprite atlas for tile images (read/write) grid_size (tuple): Layer dimensions as (width, height) (read-only) grid (Grid): Parent Grid or None. Setting manages layer association. Methods: at(x, y) -> int: Get the tile index at cell position (x, y) set(x, y, index): Set the tile index at cell position (x, y) fill(index): Fill the entire layer with a single tile index fill_rect(x, y, w, h, index): Fill a rectangular region with a tile index Tile Index Values: -1: No tile (transparent/empty cell) 0+: Index into the texture's sprite atlas (row-major order) Example: terrain = mcrfpy.TileLayer(z_index=-2, name='terrain', texture=tileset) grid = mcrfpy.Grid(grid_size=(20, 15), layers=[terrain]) terrain.fill(0) # Fill with tile index 0 grid.layer('terrain').set(5, 5, 42) # Place tile 42 at (5, 5)

Properties:

• grid: Parent Grid or None. Setting manages layer association and handles lazy allocation.
• grid_size: Layer dimensions as (width, height) tuple.
• name (read-only): Layer name (str, read-only). Used for Grid.layer(name) lookup.
• texture: Texture atlas for tile sprites.
• visible: Whether the layer is rendered.
• z_index: Layer z-order. Negative values render below entities.

Methods:

TileMapFile

TileMapFile(path: str) Load a Tiled map file (.tmx or .tmj). Parses the map and its referenced tilesets, providing access to tile layers, object layers, and GID resolution. Args: path: Path to the .tmx or .tmj map file. Properties: width (int, read-only): Map width in tiles. height (int, read-only): Map height in tiles. tile_width (int, read-only): Tile width in pixels. tile_height (int, read-only): Tile height in pixels. orientation (str, read-only): Map orientation (e.g. 'orthogonal'). properties (dict, read-only): Custom map properties. tileset_count (int, read-only): Number of referenced tilesets. tile_layer_names (list, read-only): Names of tile layers. object_layer_names (list, read-only): Names of object layers. Example: tm = mcrfpy.TileMapFile('map.tmx') data = tm.tile_layer_data('Ground') tm.apply_to_tile_layer(my_tile_layer, 'Ground')

Properties:

• height (read-only): Map height in tiles (int, read-only).
• object_layer_names (read-only): List of object layer names (read-only).
• orientation (read-only): Map orientation, e.g. 'orthogonal' (str, read-only).
• properties (read-only): Custom map properties as a dict (read-only).
• tile_height (read-only): Tile height in pixels (int, read-only).
• tile_layer_names (read-only): List of tile layer names (read-only).
• tile_width (read-only): Tile width in pixels (int, read-only).
• tileset_count (read-only): Number of referenced tilesets (int, read-only).
• width (read-only): Map width in tiles (int, read-only).

Methods:

TileSetFile

TileSetFile(path: str) Load a Tiled tileset file (.tsx or .tsj). Parses the tileset and provides access to tile metadata, properties, Wang sets, and texture creation. Args: path: Path to the .tsx or .tsj tileset file. Properties: name (str, read-only): Tileset name. tile_width (int, read-only): Width of each tile in pixels. tile_height (int, read-only): Height of each tile in pixels. tile_count (int, read-only): Total number of tiles. columns (int, read-only): Number of columns in the tileset image. image_source (str, read-only): Resolved path to the tileset image. properties (dict, read-only): Custom properties from the tileset. wang_sets (list, read-only): List of WangSet objects. Example: ts = mcrfpy.TileSetFile('tileset.tsx') texture = ts.to_texture() print(f'{ts.name}: {ts.tile_count} tiles')

Properties:

• columns (read-only): Number of columns in tileset image (int, read-only).
• image_source (read-only): Resolved path to the tileset image file (str, read-only).
• margin (read-only): Margin around tiles in pixels (int, read-only).
• name (read-only): Tileset name (str, read-only).
• properties (read-only): Custom tileset properties as a dict (read-only).
• spacing (read-only): Spacing between tiles in pixels (int, read-only).
• tile_count (read-only): Total number of tiles (int, read-only).
• tile_height (read-only): Height of each tile in pixels (int, read-only).
• tile_width (read-only): Width of each tile in pixels (int, read-only).
• wang_sets (read-only): List of WangSet objects from this tileset (read-only).

Methods:

Timer

Timer(name, callback, interval, once=False, start=True) 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 start (bool): If True, timer starts immediately. Default: True 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) stopped (bool): Whether timer is stopped (read-only) active (bool): Running state (read-write). Set True to start, False to pause callback (callable): The callback function (preserved when stopped) once (bool): Whether timer stops after firing once Methods: start(): Start the timer, adding to engine tick loop stop(): Stop the timer (removes from engine, preserves callback) pause(): Pause the timer, preserving time remaining resume(): Resume a paused timer restart(): Reset timer and ensure it's running Example: def on_timer(timer, runtime): print(f'Timer {timer} fired at {runtime}ms') if runtime > 5000: timer.stop() # Stop but can restart later timer = mcrfpy.Timer('my_timer', on_timer, 1000) timer.pause() # Pause timer timer.resume() # Resume timer timer.stop() # Stop completely timer.start() # Restart from beginning

Properties:

• active: Running state (bool, read-write). True if running (not paused, not stopped). Set True to start/resume, False to pause.
• callback: The callback function (callable). Preserved when stopped, allowing timer restart.
• interval: Timer interval in milliseconds (int). Must be positive. Can be changed while timer is running.
• name (read-only): Timer name (str, read-only). Unique identifier for this timer.
• once: Whether the timer stops after firing once (bool). One-shot timers can be restarted.
• paused (read-only): Whether the timer is paused (bool, read-only). Paused timers preserve their remaining time.
• remaining (read-only): Time remaining until next trigger in milliseconds (int, read-only). Full interval when stopped.
• stopped (read-only): Whether the timer is stopped (bool, read-only). Stopped timers are not in the engine tick loop but preserve their callback.

Methods:

Transition

Inherits from: IntEnum

Properties:

• denominator: the denominator of a rational number in lowest terms
• imag: the imaginary part of a complex number
• numerator: the numerator of a rational number in lowest terms
• real: the real part of a complex number

Methods:

Traversal

Inherits from: IntEnum

Properties:

• denominator: the denominator of a rational number in lowest terms
• imag: the imaginary part of a complex number
• numerator: the numerator of a rational number in lowest terms
• real: the real part of a complex number

Methods:

Trigger

Inherits from: IntEnum

Enum representing trigger types passed to entity step() callbacks. Values: DONE: Behavior completed (path exhausted, sleep finished, etc.) BLOCKED: Movement blocked by wall or collision TARGET: Target entity spotted in FOV

Properties:

• denominator: the denominator of a rational number in lowest terms
• imag: the imaginary part of a complex number
• numerator: the numerator of a rational number in lowest terms
• real: the real part of a complex number

Methods:

Vector

Vector(x: float = 0, y: float = 0) 2D vector for positions, sizes, and directions. Args: x: X component. y: Y component. Supports arithmetic (+, -, *, /), abs(), len() == 2, indexing ([0] for x, [1] for y), hashing, and equality. Properties: x (float): X component. y (float): Y component. int (tuple[int, int], read-only): Integer floor of (x, y).

Properties:

• int (read-only): Integer tuple (floor of x and y) for use as dict keys. Read-only.
• x: X coordinate of the vector (float)
• y: Y coordinate of the vector (float)

Methods:

Viewport3D

Inherits from: Drawable

Viewport3D(pos=None, size=None, **kwargs) A 3D rendering viewport that displays a 3D scene as a UI element. Args: pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0) size (tuple, optional): Display size as (width, height). Default: (320, 240) Keyword Args: render_resolution (tuple): Internal render resolution (width, height). Default: (320, 240) fov (float): Camera field of view in degrees. Default: 60 camera_pos (tuple): Camera position (x, y, z). Default: (0, 0, 5) camera_target (tuple): Camera look-at point (x, y, z). Default: (0, 0, 0) bg_color (Color): Background clear color. Default: (25, 25, 50) enable_vertex_snap (bool): PS1-style vertex snapping. Default: True enable_affine (bool): PS1-style affine texture mapping. Default: True enable_dither (bool): PS1-style color dithering. Default: True enable_fog (bool): Distance fog. Default: True fog_color (Color): Fog color. Default: (128, 128, 153) fog_near (float): Fog start distance. Default: 10 fog_far (float): Fog end distance. Default: 100

Properties:

• bg_color: Background clear color.
• bounds: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
• camera_pos: Camera position as (x, y, z) tuple.
• camera_target: Camera look-at target as (x, y, z) tuple.
• cell_size: World units per navigation grid cell.
• enable_affine: Enable PS1-style affine texture mapping (warped textures).
• enable_dither: Enable PS1-style color dithering.
• enable_fog: Enable distance fog.
• enable_vertex_snap: Enable PS1-style vertex snapping (jittery vertices).
• entities (read-only): Collection of Entity3D objects (read-only). Use append/remove to modify.
• fog_color: Fog color.
• fog_far: Fog end distance.
• fog_near: Fog start distance.
• fov: Camera field of view in degrees.
• global_bounds: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).
• global_position (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.
• grid_size: Navigation grid dimensions as (width, depth) tuple.
• h: Display height in pixels.
• hovered (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
• on_click: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
• on_enter: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
• on_exit: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
• on_move: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
• opacity: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
• parent: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
• pos: Position as Vector (x, y).
• render_resolution: Internal render resolution (width, height). Lower values for PS1 effect.
• visible: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
• w: Display width in pixels.
• x: X position in pixels.
• y: Y position in pixels.
• z_index: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.

Methods:

VoxelGrid

VoxelGrid(size: tuple[int, int, int], cell_size: float = 1.0) A dense 3D grid of voxel material IDs with a material palette. VoxelGrids provide volumetric storage for 3D structures like buildings, caves, and dungeon walls. Each cell stores a uint8 material ID (0-255), where 0 is always air. Args: size: (width, height, depth) dimensions. Immutable after creation. cell_size: World units per voxel. Default 1.0. Properties: size (tuple, read-only): Grid dimensions as (width, height, depth) width, height, depth (int, read-only): Individual dimensions cell_size (float, read-only): World units per voxel offset (tuple): World-space position (x, y, z) rotation (float): Y-axis rotation in degrees material_count (int, read-only): Number of defined materials Example: voxels = mcrfpy.VoxelGrid(size=(16, 8, 16), cell_size=1.0) stone = voxels.add_material('stone', color=mcrfpy.Color(128, 128, 128)) voxels.set(5, 0, 5, stone) assert voxels.get(5, 0, 5) == stone print(f'Non-air voxels: {voxels.count_non_air()}')

Properties:

• cell_size (read-only): World units per voxel. Read-only.
• depth (read-only): Grid depth (Z dimension). Read-only.
• greedy_meshing: Enable greedy meshing optimization (reduces vertex count for uniform regions).
• height (read-only): Grid height (Y dimension). Read-only.
• material_count (read-only): Number of materials in the palette. Read-only.
• offset: World-space position (x, y, z) of the grid origin.
• rotation: Y-axis rotation in degrees.
• size (read-only): Dimensions (width, height, depth) of the grid. Read-only.
• vertex_count (read-only): Number of vertices after mesh generation. Read-only.
• visible: Show or hide this voxel grid in rendering.
• width (read-only): Grid width (X dimension). Read-only.

Methods:

VoxelRegion

VoxelRegion - Portable voxel data for copy/paste operations. Created by VoxelGrid.copy_region(), used with paste_region(). Cannot be instantiated directly. Properties: size (tuple, read-only): Dimensions as (width, height, depth) width, height, depth (int, read-only): Individual dimensions

Properties:

• depth (read-only): Region depth. Read-only.
• height (read-only): Region height. Read-only.
• size (read-only): Dimensions (width, height, depth) of the region. Read-only.
• width (read-only): Region width. Read-only.

Methods:

WangSet

WangSet - Wang terrain auto-tile set from a Tiled tileset. WangSets are obtained from TileSetFile.wang_sets or TileSetFile.wang_set(). They map abstract terrain types to concrete sprite indices using Tiled's Wang tile algorithm. Properties: name (str, read-only): Wang set name. type (str, read-only): 'corner', 'edge', or 'mixed'. color_count (int, read-only): Number of terrain colors. colors (list, read-only): List of color dicts. Example: ws = tileset.wang_set('overworld') Terrain = ws.terrain_enum() tiles = ws.resolve(discrete_map)

Properties:

• color_count (read-only): Number of terrain colors (int, read-only).
• colors (read-only): List of color dicts with name, index, tile_id, probability (read-only).
• name (read-only): Wang set name (str, read-only).
• type (read-only): Wang set type: 'corner', 'edge', or 'mixed' (str, read-only).

Methods:

Window

Window singleton for accessing and modifying the game window properties

Properties:

• framerate_limit: Frame rate limit in FPS (int, 0 for unlimited). Caps maximum frame rate.
• fullscreen: Window fullscreen state (bool). Setting this recreates the window.
• game_resolution: Fixed game resolution as (width, height) tuple. Enables resolution-independent rendering with scaling.
• resolution: Window resolution as (width, height) tuple. Setting this recreates the window.
• scaling_mode: Viewport scaling mode (str): 'center' (no scaling), 'stretch' (fill window), or 'fit' (maintain aspect ratio).
• title: Window title string (str). Displayed in the window title bar.
• visible: Window visibility state (bool). Hidden windows still process events.
• vsync: Vertical sync enabled state (bool). Prevents screen tearing but may limit framerate.

Methods: