McRogueFace/docs/mcrfpy.3

.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "MCRFPY" "3" "2026-06-10" "McRogueFace 0.2.7-prerelease-7drl2026-99-g16adc92" ""
.hy
.SH McRogueFace API Reference
.PP
\f[I]Generated on 2026-06-10 20:23:39\f[R]
.PP
\f[I]This documentation was dynamically generated from the compiled
module.\f[R]
.SS Table of Contents
.IP \[bu] 2
Functions
.IP \[bu] 2
Classes
.RS 2
.IP \[bu] 2
AStarPath
.IP \[bu] 2
Alignment
.IP \[bu] 2
Arc
.IP \[bu] 2
AutoRuleSet
.IP \[bu] 2
BSP
.IP \[bu] 2
Behavior
.IP \[bu] 2
Billboard
.IP \[bu] 2
CallableBinding
.IP \[bu] 2
Caption
.IP \[bu] 2
Circle
.IP \[bu] 2
Color
.IP \[bu] 2
ColorLayer
.IP \[bu] 2
DijkstraMap
.IP \[bu] 2
DiscreteMap
.IP \[bu] 2
Drawable
.IP \[bu] 2
Easing
.IP \[bu] 2
Entity
.IP \[bu] 2
Entity3D
.IP \[bu] 2
EntityCollection3D
.IP \[bu] 2
EntityCollection3DIter
.IP \[bu] 2
FOV
.IP \[bu] 2
Font
.IP \[bu] 2
Frame
.IP \[bu] 2
Grid
.IP \[bu] 2
GridView
.IP \[bu] 2
HeightMap
.IP \[bu] 2
Heuristic
.IP \[bu] 2
InputState
.IP \[bu] 2
Key
.IP \[bu] 2
Keyboard
.IP \[bu] 2
LdtkProject
.IP \[bu] 2
Line
.IP \[bu] 2
Model3D
.IP \[bu] 2
Mouse
.IP \[bu] 2
MouseButton
.IP \[bu] 2
Music
.IP \[bu] 2
NoiseSource
.IP \[bu] 2
Perspective
.IP \[bu] 2
PropertyBinding
.IP \[bu] 2
Scene
.IP \[bu] 2
Shader
.IP \[bu] 2
Sound
.IP \[bu] 2
SoundBuffer
.IP \[bu] 2
Sprite
.IP \[bu] 2
Texture
.IP \[bu] 2
TileLayer
.IP \[bu] 2
TileMapFile
.IP \[bu] 2
TileSetFile
.IP \[bu] 2
Timer
.IP \[bu] 2
Transition
.IP \[bu] 2
Traversal
.IP \[bu] 2
Trigger
.IP \[bu] 2
Vector
.IP \[bu] 2
Viewport3D
.IP \[bu] 2
VoxelGrid
.IP \[bu] 2
VoxelRegion
.IP \[bu] 2
WangSet
.IP \[bu] 2
Window
.RE
.IP \[bu] 2
Constants
.SS Functions
.SS \f[V]bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]]\f[R]
.PP
Compute grid cells along a line using Bresenham\[cq]s algorithm.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]start\f[R]: (x, y) tuple or Vector -
starting point - \f[V]end\f[R]: (x, y) tuple or Vector - ending point -
\f[V]include_start\f[R]: Include the starting point in results (default:
True) - \f[V]include_end\f[R]: Include the ending point in results
(default: True)
.PP
\f[B]Returns:\f[R] 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.
.SS \f[V]end_benchmark() -> str\f[R]
.PP
Stop benchmark capture and write data to JSON file.
.PP
Note:
.PP
\f[B]Returns:\f[R] str: The filename of the written benchmark data
.PP
\f[B]Raises:\f[R] RuntimeError: If no benchmark is currently running
Returns the auto-generated filename (e.g.,
`benchmark_12345_20250528_143022.json')
.SS \f[V]exit() -> None\f[R]
.PP
Cleanly shut down the game engine and exit the application.
.PP
Note:
.PP
\f[B]Returns:\f[R] None This immediately closes the window and
terminates the program.
.SS \f[V]find(name: str, scene: str = None) -> UIDrawable | None\f[R]
.PP
Find the first UI element with the specified name.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Exact name to search for -
\f[V]scene\f[R]: Scene to search in (default: current scene)
.PP
\f[B]Returns:\f[R] Frame, Caption, Sprite, Grid, or Entity if found;
None otherwise Searches scene UI elements and entities within grids.
.SS \f[V]find_all(pattern: str, scene: str = None) -> list\f[R]
.PP
Find all UI elements matching a name pattern.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]pattern\f[R]: Name pattern with optional
wildcards (* matches any characters) - \f[V]scene\f[R]: Scene to search
in (default: current scene)
.PP
\f[B]Returns:\f[R] list: All matching UI elements and entities
.SS \f[V]get_metrics() -> dict\f[R]
.PP
Get current performance metrics.
.PP
\f[B]Returns:\f[R] dict: Performance data with keys: frame_time (last
frame duration in seconds), avg_frame_time (average frame time), fps
(frames per second), draw_calls (number of draw calls), ui_elements
(total UI element count), visible_elements (visible element count),
current_frame (frame counter), runtime (total runtime in seconds)
.SS \f[V]lock() -> _LockContext\f[R]
.PP
Get a context manager for thread-safe UI updates from background
threads.
.PP
Note:
.PP
\f[B]Returns:\f[R] _LockContext: A context manager that blocks until
safe to modify UI Use with \f[V]with mcrfpy.lock():\f[R] 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.
.SS \f[V]log_benchmark(message: str) -> None\f[R]
.PP
Add a log message to the current benchmark frame.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]message\f[R]: Text to associate with the
current frame
.PP
\f[B]Returns:\f[R] None
.PP
\f[B]Raises:\f[R] RuntimeError: If no benchmark is currently running
Messages appear in the `logs' array of each frame in the output JSON.
.SS \f[V]set_dev_console(enabled: bool) -> None\f[R]
.PP
Enable or disable the developer console overlay.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]enabled\f[R]: True to enable the console
(default), False to disable
.PP
\f[B]Returns:\f[R] None When disabled, the grave/tilde key will not open
the console.
Use this to ship games without debug features.
.SS \f[V]set_scale(multiplier: float) -> None\f[R]
.PP
Deprecated: use Window.resolution instead.
Scale the game window size.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]multiplier\f[R]: Scale factor (e.g., 2.0 for
double size)
.PP
\f[B]Returns:\f[R] None The internal resolution remains 1024x768, but
the window is scaled.
This is deprecated - use Window.resolution instead.
.SS \f[V]start_benchmark() -> None\f[R]
.PP
Start capturing benchmark data to a file.
.PP
Note:
.PP
\f[B]Returns:\f[R] None
.PP
\f[B]Raises:\f[R] RuntimeError: If a benchmark is already running
Benchmark filename is auto-generated from PID and timestamp.
Use end_benchmark() to stop and get filename.
.SS \f[V]step(dt: float = None) -> float\f[R]
.PP
Advance simulation time (headless mode only).
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dt\f[R]: Time to advance in seconds.
If None, advances to the next scheduled event (timer/animation).
.PP
\f[B]Returns:\f[R] 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.
.SS Classes
.SS AStarPath
.PP
A computed A* path result, consumed step by step.
.PP
Created by Grid.find_path().
Cannot be instantiated directly.
.PP
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.
.PP
Properties: origin (Vector): Starting position (read-only) destination
(Vector): Ending position (read-only) remaining (int): Steps remaining
(read-only)
.PP
Example: path = grid.find_path(start, end) if path: while path: next_pos
= path.walk() entity.pos = next_pos
.PP
\f[B]Properties:\f[R] - \f[V]destination\f[R] \f[I](read-only)\f[R]:
Ending position of the path (Vector, read-only).
- \f[V]origin\f[R] \f[I](read-only)\f[R]: Starting position of the path
(Vector, read-only).
- \f[V]remaining\f[R] \f[I](read-only)\f[R]: Number of steps remaining
in the path (int, read-only).
.PP
\f[B]Methods:\f[R]
.SS \f[V]peek() -> Vector\f[R]
.PP
See next step without consuming it.
.PP
\f[B]Returns:\f[R] Next position as Vector.
.PP
\f[B]Raises:\f[R] IndexError: If path is exhausted.
.SS \f[V]walk() -> Vector\f[R]
.PP
Get and consume next step in the path.
.PP
\f[B]Returns:\f[R] Next position as Vector.
.PP
\f[B]Raises:\f[R] IndexError: If path is exhausted.
.SS Alignment
.PP
\f[I]Inherits from: IntEnum\f[R]
.PP
Alignment enum for positioning UI elements relative to parent bounds.
.PP
Values: TOP_LEFT, TOP_CENTER, TOP_RIGHT CENTER_LEFT, CENTER,
CENTER_RIGHT BOTTOM_LEFT, BOTTOM_CENTER, BOTTOM_RIGHT
.PP
Margin Validation Rules: Margins define distance from parent edge when
aligned.
.IP
.nf
\f[C]
- 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
\f[R]
.fi
.PP
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)
.PP
Example: # Center a panel in the scene panel = Frame(size=(200, 100),
align=Alignment.CENTER) scene.children.append(panel)
.IP
.nf
\f[C]
# Place button in bottom-right with 10px margin
button = Frame(size=(80, 30), align=Alignment.BOTTOM_RIGHT, margin=10)
panel.children.append(button)
\f[R]
.fi
.PP
\f[B]Properties:\f[R] - \f[V]denominator\f[R]: the denominator of a
rational number in lowest terms - \f[V]imag\f[R]: the imaginary part of
a complex number - \f[V]numerator\f[R]: the numerator of a rational
number in lowest terms - \f[V]real\f[R]: the real part of a complex
number
.PP
\f[B]Methods:\f[R]
.SS \f[V]as_integer_ratio(...)\f[R]
.PP
Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10,
1) >>> (0).as_integer_ratio() (0, 1)
.SS \f[V]bit_count(...)\f[R]
.PP
Number of ones in the binary representation of the absolute value of
self.
Also known as the population count.
>>> bin(13) `0b1101' >>> (13).bit_count() 3
.SS \f[V]bit_length(...)\f[R]
.PP
Number of bits necessary to represent self in binary.
>>> bin(37) `0b100101' >>> (37).bit_length() 6
.SS \f[V]conjugate(...)\f[R]
.PP
Returns self, the complex conjugate of any int.
.SS \f[V]from_bytes(...)\f[R]
.PP
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert.
The argument must either support the buffer protocol or be an iterable
object producing bytes.
Bytes and bytearray are examples of built-in objects that support the
buffer protocol.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Indicates whether two\[cq]s complement is used to represent the
integer.
.SS \f[V]is_integer(...)\f[R]
.PP
Returns True.
Exists for duck type compatibility with float.is_integer.
.SS \f[V]to_bytes(...)\f[R]
.PP
Return an array of bytes representing an integer.
length Length of bytes object to use.
An OverflowError is raised if the integer is not representable with the
given number of bytes.
Default is length 1.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Determines whether two\[cq]s complement is used to represent the
integer.
If signed is False and a negative integer is given, an OverflowError is
raised.
.SS Arc
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Arc(center=None, radius=0, start_angle=0, end_angle=90, color=None,
thickness=1, **kwargs)
.PP
An arc UI element for drawing curved line segments.
.PP
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
.PP
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)
.PP
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
.PP
\f[B]Properties:\f[R] - \f[V]align\f[R]: 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.
- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]center\f[R]: Center position of the arc - \f[V]color\f[R]: Arc
color - \f[V]end_angle\f[R]: Ending angle in degrees -
\f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors in
screen coordinates.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
position (read-only).
Calculates absolute position by walking up the parent chain.
- \f[V]grid_pos\f[R]: Position in grid tile coordinates (only when
parent is Grid) - \f[V]grid_size\f[R]: Size in grid tile coordinates
(only when parent is Grid) - \f[V]horiz_margin\f[R]: Horizontal margin
override (float, 0 = use general margin).
Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER,
CENTER).
- \f[V]hovered\f[R] \f[I](read-only)\f[R]: Whether mouse is currently
over this element (read-only).
Updated automatically by the engine during mouse movement.
- \f[V]margin\f[R]: General margin from edge when aligned (float).
Applied to both horizontal and vertical edges unless overridden.
Invalid for CENTER alignment (raises ValueError).
- \f[V]name\f[R]: Name for finding this element.
- \f[V]on_click\f[R]: Callable executed when arc is clicked.
Function receives (pos: Vector, button: str, action: str).
- \f[V]on_enter\f[R]: Callback for mouse enter events.
Called with (pos: Vector, button: str, action: str) when mouse enters
this element\[cq]s bounds.
- \f[V]on_exit\f[R]: Callback for mouse exit events.
Called with (pos: Vector, button: str, action: str) when mouse leaves
this element\[cq]s bounds.
- \f[V]on_move\f[R]: 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.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]parent\f[R]: 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.
- \f[V]pos\f[R]: Position as a Vector (same as center).
- \f[V]radius\f[R]: Arc radius in pixels - \f[V]rotate_with_camera\f[R]:
Whether to rotate visually with parent Grid\[cq]s camera_rotation
(bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]start_angle\f[R]: Starting angle in degrees -
\f[V]thickness\f[R]: Line thickness - \f[V]vert_margin\f[R]: Vertical
margin override (float, 0 = use general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
Invisible objects are not rendered or clickable.
- \f[V]z_index\f[R]: Z-order for rendering (lower values rendered
first).
.PP
\f[B]Methods:\f[R]
.SS \f[V]animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode=\[aq]replace\[aq]) -> Animation\f[R]
.PP
Create and start an animation on this drawable\[cq]s property.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]property\f[R]: Name of the property to
animate (e.g., `x', `fill_color', `opacity') - \f[V]target\f[R]: Target
value - type depends on property (float, tuple for color/vector, etc.)
- \f[V]duration\f[R]: Animation duration in seconds - \f[V]easing\f[R]:
Easing function: Easing enum value, string name, or None for linear -
\f[V]delta\f[R]: If True, target is relative to current value; if False,
target is absolute - \f[V]loop\f[R]: If True, animation repeats from
start when it reaches the end (default False) - \f[V]callback\f[R]:
Optional callable invoked when animation completes (not called for
looping animations) - \f[V]conflict_mode\f[R]: `replace' (default),
`queue', or `error' if property already animating
.PP
\f[B]Returns:\f[R] Animation object for monitoring progress
.PP
\f[B]Raises:\f[R] ValueError: If property name is not valid for this
drawable type This is a convenience method that creates an Animation,
starts it, and adds it to the AnimationManager.
.SS \f[V]move(dx, dy) or (delta) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels (or use
delta) - \f[V]dy\f[R]: Vertical offset in pixels (or use delta) -
\f[V]delta\f[R]: Offset as tuple, list, or Vector: (dx, dy)
.SS \f[V]realign() -> None\f[R]
.PP
Reapply alignment relative to parent, useful for responsive layouts.
.PP
Note: Call this to recalculate position after parent changes size.
For elements with align=None, this has no effect.
.SS \f[V]resize(width, height) or (size) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels (or use
size) - \f[V]height\f[R]: New height in pixels (or use size) -
\f[V]size\f[R]: Size as tuple, list, or Vector: (width, height)
.SS AutoRuleSet
.PP
AutoRuleSet - LDtk auto-tile rule set for pattern-based terrain
rendering.
.PP
AutoRuleSets are obtained from LdtkProject.ruleset().
They map IntGrid terrain values to sprite tiles using LDtk\[cq]s
pattern-matching auto-rule system.
.PP
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.
.PP
Example: rs = project.ruleset(`Walls') Terrain = rs.terrain_enum()
rs.apply(discrete_map, tile_layer, seed=42)
.PP
\f[B]Properties:\f[R] - \f[V]grid_size\f[R] \f[I](read-only)\f[R]: Cell
size in pixels (int, read-only).
- \f[V]group_count\f[R] \f[I](read-only)\f[R]: Number of rule groups
(int, read-only).
- \f[V]name\f[R] \f[I](read-only)\f[R]: Rule set name / layer identifier
(str, read-only).
- \f[V]rule_count\f[R] \f[I](read-only)\f[R]: Total number of rules
across all groups (int, read-only).
- \f[V]value_count\f[R] \f[I](read-only)\f[R]: Number of IntGrid terrain
values (int, read-only).
- \f[V]values\f[R] \f[I](read-only)\f[R]: List of IntGrid value dicts
with value and name (read-only).
.PP
\f[B]Methods:\f[R]
.SS \f[V]apply(discrete_map: DiscreteMap, tile_layer: TileLayer, seed: int = 0) -> None\f[R]
.PP
Resolve auto-rules and write tile indices directly into a TileLayer.
.PP
\f[B]Arguments:\f[R] - \f[V]discrete_map\f[R]: A DiscreteMap with
IntGrid values - \f[V]tile_layer\f[R]: Target TileLayer to write
resolved tiles into - \f[V]seed\f[R]: Random seed for deterministic
results (default: 0)
.SS \f[V]resolve(discrete_map: DiscreteMap, seed: int = 0) -> list[int]\f[R]
.PP
Resolve IntGrid data to tile indices using LDtk auto-rules.
.PP
\f[B]Arguments:\f[R] - \f[V]discrete_map\f[R]: A DiscreteMap with
IntGrid values matching this rule set - \f[V]seed\f[R]: Random seed for
deterministic tile selection and probability (default: 0)
.PP
\f[B]Returns:\f[R] List of tile IDs (one per cell).
-1 means no matching rule.
.SS \f[V]terrain_enum() -> IntEnum\f[R]
.PP
Generate a Python IntEnum from this rule set\[cq]s IntGrid values.
.PP
\f[B]Returns:\f[R] IntEnum class with NONE=0 and one member per IntGrid
value (UPPER_SNAKE_CASE).
.SS BSP
.PP
BSP(pos: tuple[int, int], size: tuple[int, int])
.PP
Binary Space Partitioning tree for procedural dungeon generation.
.PP
BSP recursively divides a rectangular region into smaller sub-regions,
creating a tree structure perfect for generating dungeon rooms and
corridors.
.PP
Args: pos: (x, y) - Top-left position of the root region.
size: (w, h) - Width and height of the root region.
.PP
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.
.PP
Iteration: for leaf in bsp: # Iterates over leaf nodes (rooms) len(bsp)
# Returns number of leaf nodes
.PP
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\[cq]Room at {leaf.pos}, size {leaf.size}\[cq])
.PP
\f[B]Properties:\f[R] - \f[V]adjacency\f[R] \f[I](read-only)\f[R]: Leaf
adjacency graph.
adjacency[i] returns tuple of neighbor indices.
Read-only.
- \f[V]bounds\f[R] \f[I](read-only)\f[R]: Root node bounds as ((x, y),
(w, h)).
Read-only.
- \f[V]pos\f[R] \f[I](read-only)\f[R]: Top-left position (x, y).
Read-only.
- \f[V]root\f[R] \f[I](read-only)\f[R]: Reference to the root BSPNode.
Read-only.
- \f[V]size\f[R] \f[I](read-only)\f[R]: Dimensions (width, height).
Read-only.
.PP
\f[B]Methods:\f[R]
.SS \f[V]clear() -> BSP\f[R]
.PP
Remove all children, keeping only the root node with original bounds.
WARNING: Invalidates all existing BSPNode references from this tree.
.PP
\f[B]Returns:\f[R] BSP: self, for method chaining
.SS \f[V]find(pos: tuple[int, int]) -> BSPNode | None\f[R]
.PP
Find the smallest (deepest) node containing the position.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Position as (x, y) tuple, list, or
Vector
.PP
\f[B]Returns:\f[R] BSPNode if found, None if position is outside bounds
.SS \f[V]get_leaf(index: int) -> BSPNode\f[R]
.PP
Get a leaf node by its index (0 to len(bsp)-1).
This is useful when working with adjacency data, which returns leaf
indices.
.PP
\f[B]Arguments:\f[R] - \f[V]index\f[R]: Leaf index (0 to len(bsp)-1).
Negative indices supported.
.PP
\f[B]Returns:\f[R] BSPNode at the specified index
.PP
\f[B]Raises:\f[R] IndexError: If index is out of range
.SS \f[V]leaves() -> Iterator[BSPNode]\f[R]
.PP
Iterate all leaf nodes (the actual rooms).
Same as iterating the BSP directly.
.PP
\f[B]Returns:\f[R] Iterator yielding BSPNode objects
.SS \f[V]split_once(horizontal: bool, position: int) -> BSP\f[R]
.PP
Split the root node once at the specified position.
horizontal=True creates a horizontal divider, producing top/bottom
rooms.
horizontal=False creates a vertical divider, producing left/right rooms.
.PP
\f[B]Arguments:\f[R] - \f[V]horizontal\f[R]: True for horizontal divider
(top/bottom), False for vertical (left/right) - \f[V]position\f[R]:
Split coordinate (y for horizontal, x for vertical)
.PP
\f[B]Returns:\f[R] BSP: self, for method chaining
.SS \f[V]split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP\f[R]
.PP
Recursively split to the specified depth.
WARNING: Invalidates all existing BSPNode references from this tree.
.PP
\f[B]Arguments:\f[R] - \f[V]depth\f[R]: Maximum recursion depth (1-16).
Creates up to 2\[ha]depth leaves.
- \f[V]min_size\f[R]: Minimum (width, height) for a node to be split.
- \f[V]max_ratio\f[R]: Maximum aspect ratio before forcing split
direction.
Default: 1.5.
- \f[V]seed\f[R]: Random seed.
None for random.
.PP
\f[B]Returns:\f[R] BSP: self, for method chaining
.SS \f[V]to_heightmap(size: tuple[int, int] = None, select: str = \[aq]leaves\[aq], shrink: int = 0, value: float = 1.0) -> HeightMap\f[R]
.PP
Convert BSP node selection to a HeightMap.
.PP
\f[B]Arguments:\f[R] - \f[V]size\f[R]: Output size (width, height).
Default: bounds size.
- \f[V]select\f[R]: `leaves', `all', or `internal'.
Default: `leaves'.
- \f[V]shrink\f[R]: Pixels to shrink from each node\[cq]s bounds.
Default: 0.
- \f[V]value\f[R]: Value inside selected regions.
Default: 1.0.
.PP
\f[B]Returns:\f[R] HeightMap with selected regions filled
.SS \f[V]traverse(order: Traversal = Traversal.LEVEL_ORDER) -> Iterator[BSPNode]\f[R]
.PP
Iterate all nodes in the specified order.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]order\f[R]: Traversal order from Traversal
enum.
Default: LEVEL_ORDER.
.PP
\f[B]Returns:\f[R] Iterator yielding BSPNode objects Orders: PRE_ORDER,
IN_ORDER, POST_ORDER, LEVEL_ORDER, INVERTED_LEVEL_ORDER
.SS Behavior
.PP
\f[I]Inherits from: IntEnum\f[R]
.PP
Enum representing entity behavior types for grid.step() turn management.
.PP
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
.PP
\f[B]Properties:\f[R] - \f[V]denominator\f[R]: the denominator of a
rational number in lowest terms - \f[V]imag\f[R]: the imaginary part of
a complex number - \f[V]numerator\f[R]: the numerator of a rational
number in lowest terms - \f[V]real\f[R]: the real part of a complex
number
.PP
\f[B]Methods:\f[R]
.SS \f[V]as_integer_ratio(...)\f[R]
.PP
Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10,
1) >>> (0).as_integer_ratio() (0, 1)
.SS \f[V]bit_count(...)\f[R]
.PP
Number of ones in the binary representation of the absolute value of
self.
Also known as the population count.
>>> bin(13) `0b1101' >>> (13).bit_count() 3
.SS \f[V]bit_length(...)\f[R]
.PP
Number of bits necessary to represent self in binary.
>>> bin(37) `0b100101' >>> (37).bit_length() 6
.SS \f[V]conjugate(...)\f[R]
.PP
Returns self, the complex conjugate of any int.
.SS \f[V]from_bytes(...)\f[R]
.PP
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert.
The argument must either support the buffer protocol or be an iterable
object producing bytes.
Bytes and bytearray are examples of built-in objects that support the
buffer protocol.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Indicates whether two\[cq]s complement is used to represent the
integer.
.SS \f[V]is_integer(...)\f[R]
.PP
Returns True.
Exists for duck type compatibility with float.is_integer.
.SS \f[V]to_bytes(...)\f[R]
.PP
Return an array of bytes representing an integer.
length Length of bytes object to use.
An OverflowError is raised if the integer is not representable with the
given number of bytes.
Default is length 1.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Determines whether two\[cq]s complement is used to represent the
integer.
If signed is False and a negative integer is given, an OverflowError is
raised.
.SS Billboard
.PP
Billboard(texture=None, sprite_index=0, pos=(0,0,0), scale=1.0,
facing=`camera_y')
.PP
A camera-facing 3D sprite for trees, items, particles, etc.
.PP
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'
.PP
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
.PP
\f[B]Properties:\f[R] - \f[V]facing\f[R]: Facing mode: `camera',
`camera_y', or `fixed' (str) - \f[V]opacity\f[R]: Opacity from 0.0
(transparent) to 1.0 (opaque) (float) - \f[V]phi\f[R]: Vertical tilt for
`fixed' mode in radians (float) - \f[V]pos\f[R]: World position as (x,
y, z) tuple - \f[V]scale\f[R]: Uniform scale factor (float) -
\f[V]sprite_index\f[R]: Index into sprite sheet (int) -
\f[V]texture\f[R]: Sprite sheet texture (Texture or None) -
\f[V]theta\f[R]: Horizontal rotation for `fixed' mode in radians (float)
- \f[V]visible\f[R]: Visibility state (bool)
.PP
\f[B]Methods:\f[R]
.SS CallableBinding
.PP
CallableBinding(callable: Callable[[], float])
.PP
A binding that calls a Python function to get its value.
.PP
Args: callable: A function that takes no arguments and returns a float
.PP
The callable is invoked every frame when the shader is rendered.
Keep the callable lightweight to avoid performance issues.
.PP
Example: player_health = 100 frame.uniforms[`health_pct'] =
mcrfpy.CallableBinding( lambda: player_health / 100.0 )
.PP
\f[B]Properties:\f[R] - \f[V]callable\f[R] \f[I](read-only)\f[R]: The
Python callable (read-only).
- \f[V]is_valid\f[R] \f[I](read-only)\f[R]: True if the callable is
still valid (bool, read-only).
- \f[V]value\f[R] \f[I](read-only)\f[R]: Current value from calling the
callable (float, read-only).
Returns None on error.
.PP
\f[B]Methods:\f[R]
.SS Caption
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Caption(pos=None, font=None, text=\[cq]\[cq], **kwargs)
.PP
A text display UI element with customizable font and styling.
.PP
Args: pos (tuple, optional): Position as (x, y) tuple.
Default: (0, 0) font (Font, optional): Font object for text rendering.
Default: engine default font text (str, optional): The text content to
display.
Default: \[cq]\[cq]
.PP
Keyword Args: fill_color (Color): Text fill color.
Default: (255, 255, 255, 255) outline_color (Color): Text outline color.
Default: (0, 0, 0, 255) outline (float): Text outline thickness.
Default: 0 font_size (float): Font size in points.
Default: 16 click (callable): Click event handler.
Default: None visible (bool): Visibility state.
Default: True opacity (float): Opacity (0.0-1.0).
Default: 1.0 z_index (int): Rendering order.
Default: 0 name (str): Element name for finding.
Default: None x (float): X position override.
Default: 0 y (float): Y position override.
Default: 0 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)
.PP
Attributes: text (str): The displayed text content x, y (float):
Position in pixels pos (Vector): Position as a Vector object font
(Font): Font used for rendering font_size (float): Font size in points
fill_color, outline_color (Color): Text appearance outline (float):
Outline thickness click (callable): Click event handler visible (bool):
Visibility state opacity (float): Opacity value z_index (int): Rendering
order name (str): Element name w, h (float): Read-only computed size
based on text and font 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
.PP
\f[B]Properties:\f[R] - \f[V]align\f[R]: 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.
- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]fill_color\f[R]: Fill color of the text.
Returns a copy; modifying components requires reassignment.
For animation, use `fill_color.r', `fill_color.g', etc.
- \f[V]font_size\f[R]: Font size (integer) in points -
\f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors in
screen coordinates.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
position (read-only).
Calculates absolute position by walking up the parent chain.
- \f[V]grid_pos\f[R]: Position in grid tile coordinates (only when
parent is Grid) - \f[V]grid_size\f[R]: Size in grid tile coordinates
(only when parent is Grid) - \f[V]h\f[R] \f[I](read-only)\f[R]: Text
height in pixels (read-only) - \f[V]horiz_margin\f[R]: Horizontal margin
override (float, 0 = use general margin).
Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER,
CENTER).
- \f[V]hovered\f[R] \f[I](read-only)\f[R]: Whether mouse is currently
over this element (read-only).
Updated automatically by the engine during mouse movement.
- \f[V]margin\f[R]: General margin from edge when aligned (float).
Applied to both horizontal and vertical edges unless overridden.
Invalid for CENTER alignment (raises ValueError).
- \f[V]name\f[R]: Name for finding elements - \f[V]on_click\f[R]:
Callable executed when object is clicked.
Function receives (pos: Vector, button: str, action: str).
- \f[V]on_enter\f[R]: Callback for mouse enter events.
Called with (pos: Vector, button: str, action: str) when mouse enters
this element\[cq]s bounds.
- \f[V]on_exit\f[R]: Callback for mouse exit events.
Called with (pos: Vector, button: str, action: str) when mouse leaves
this element\[cq]s bounds.
- \f[V]on_move\f[R]: 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.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]outline\f[R]: Thickness of the border - \f[V]outline_color\f[R]:
Outline color of the text.
Returns a copy; modifying components requires reassignment.
For animation, use `outline_color.r', `outline_color.g', etc.
- \f[V]parent\f[R]: 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.
- \f[V]pos\f[R]: (x, y) vector - \f[V]rotate_with_camera\f[R]: Whether
to rotate visually with parent Grid\[cq]s camera_rotation (bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]shader\f[R]: 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.
- \f[V]size\f[R] \f[I](read-only)\f[R]: Text dimensions as Vector
(read-only) - \f[V]text\f[R]: The text displayed - \f[V]uniforms\f[R]
\f[I](read-only)\f[R]: 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.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
Invisible objects are not rendered or clickable.
- \f[V]w\f[R] \f[I](read-only)\f[R]: Text width in pixels (read-only) -
\f[V]x\f[R]: X coordinate of top-left corner - \f[V]y\f[R]: Y coordinate
of top-left corner - \f[V]z_index\f[R]: Z-order for rendering (lower
values rendered first).
Automatically triggers scene resort when changed.
.PP
\f[B]Methods:\f[R]
.SS \f[V]animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode=\[aq]replace\[aq]) -> Animation\f[R]
.PP
Create and start an animation on this drawable\[cq]s property.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]property\f[R]: Name of the property to
animate (e.g., `x', `fill_color', `opacity') - \f[V]target\f[R]: Target
value - type depends on property (float, tuple for color/vector, etc.)
- \f[V]duration\f[R]: Animation duration in seconds - \f[V]easing\f[R]:
Easing function: Easing enum value, string name, or None for linear -
\f[V]delta\f[R]: If True, target is relative to current value; if False,
target is absolute - \f[V]loop\f[R]: If True, animation repeats from
start when it reaches the end (default False) - \f[V]callback\f[R]:
Optional callable invoked when animation completes (not called for
looping animations) - \f[V]conflict_mode\f[R]: `replace' (default),
`queue', or `error' if property already animating
.PP
\f[B]Returns:\f[R] Animation object for monitoring progress
.PP
\f[B]Raises:\f[R] ValueError: If property name is not valid for this
drawable type This is a convenience method that creates an Animation,
starts it, and adds it to the AnimationManager.
.SS \f[V]move(dx, dy) or (delta) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels (or use
delta) - \f[V]dy\f[R]: Vertical offset in pixels (or use delta) -
\f[V]delta\f[R]: Offset as tuple, list, or Vector: (dx, dy)
.SS \f[V]realign() -> None\f[R]
.PP
Reapply alignment relative to parent, useful for responsive layouts.
.PP
Note: Call this to recalculate position after parent changes size.
For elements with align=None, this has no effect.
.SS \f[V]resize(width, height) or (size) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels (or use
size) - \f[V]height\f[R]: New height in pixels (or use size) -
\f[V]size\f[R]: Size as tuple, list, or Vector: (width, height)
.SS Circle
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Circle(radius=0, center=None, fill_color=None, outline_color=None,
outline=0, **kwargs)
.PP
A circle UI element for drawing filled or outlined circles.
.PP
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)
.PP
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)
.PP
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
.PP
\f[B]Properties:\f[R] - \f[V]align\f[R]: 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.
- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]center\f[R]: Center position of the circle -
\f[V]fill_color\f[R]: Fill color of the circle -
\f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors in
screen coordinates.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
position (read-only).
Calculates absolute position by walking up the parent chain.
- \f[V]grid_pos\f[R]: Position in grid tile coordinates (only when
parent is Grid) - \f[V]grid_size\f[R]: Size in grid tile coordinates
(only when parent is Grid) - \f[V]horiz_margin\f[R]: Horizontal margin
override (float, 0 = use general margin).
Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER,
CENTER).
- \f[V]hovered\f[R] \f[I](read-only)\f[R]: Whether mouse is currently
over this element (read-only).
Updated automatically by the engine during mouse movement.
- \f[V]margin\f[R]: General margin from edge when aligned (float).
Applied to both horizontal and vertical edges unless overridden.
Invalid for CENTER alignment (raises ValueError).
- \f[V]name\f[R]: Name for finding this element.
- \f[V]on_click\f[R]: Callable executed when circle is clicked.
Function receives (pos: Vector, button: str, action: str).
- \f[V]on_enter\f[R]: Callback for mouse enter events.
Called with (pos: Vector, button: str, action: str) when mouse enters
this element\[cq]s bounds.
- \f[V]on_exit\f[R]: Callback for mouse exit events.
Called with (pos: Vector, button: str, action: str) when mouse leaves
this element\[cq]s bounds.
- \f[V]on_move\f[R]: 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.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]outline\f[R]: Outline thickness (0 for no outline) -
\f[V]outline_color\f[R]: Outline color of the circle - \f[V]parent\f[R]:
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.
- \f[V]pos\f[R]: Position as a Vector (same as center).
- \f[V]radius\f[R]: Circle radius in pixels -
\f[V]rotate_with_camera\f[R]: Whether to rotate visually with parent
Grid\[cq]s camera_rotation (bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
Invisible objects are not rendered or clickable.
- \f[V]z_index\f[R]: Z-order for rendering (lower values rendered
first).
.PP
\f[B]Methods:\f[R]
.SS \f[V]animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode=\[aq]replace\[aq]) -> Animation\f[R]
.PP
Create and start an animation on this drawable\[cq]s property.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]property\f[R]: Name of the property to
animate (e.g., `x', `fill_color', `opacity') - \f[V]target\f[R]: Target
value - type depends on property (float, tuple for color/vector, etc.)
- \f[V]duration\f[R]: Animation duration in seconds - \f[V]easing\f[R]:
Easing function: Easing enum value, string name, or None for linear -
\f[V]delta\f[R]: If True, target is relative to current value; if False,
target is absolute - \f[V]loop\f[R]: If True, animation repeats from
start when it reaches the end (default False) - \f[V]callback\f[R]:
Optional callable invoked when animation completes (not called for
looping animations) - \f[V]conflict_mode\f[R]: `replace' (default),
`queue', or `error' if property already animating
.PP
\f[B]Returns:\f[R] Animation object for monitoring progress
.PP
\f[B]Raises:\f[R] ValueError: If property name is not valid for this
drawable type This is a convenience method that creates an Animation,
starts it, and adds it to the AnimationManager.
.SS \f[V]move(dx, dy) or (delta) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels (or use
delta) - \f[V]dy\f[R]: Vertical offset in pixels (or use delta) -
\f[V]delta\f[R]: Offset as tuple, list, or Vector: (dx, dy)
.SS \f[V]realign() -> None\f[R]
.PP
Reapply alignment relative to parent, useful for responsive layouts.
.PP
Note: Call this to recalculate position after parent changes size.
For elements with align=None, this has no effect.
.SS \f[V]resize(width, height) or (size) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels (or use
size) - \f[V]height\f[R]: New height in pixels (or use size) -
\f[V]size\f[R]: Size as tuple, list, or Vector: (width, height)
.SS Color
.PP
Color(r: int = 0, g: int = 0, b: int = 0, a: int = 255)
.PP
RGBA color representation.
.PP
Args: r: Red component (0-255) g: Green component (0-255) b: Blue
component (0-255) a: Alpha component (0-255, default 255 = opaque)
.PP
Note: When accessing colors from UI elements (e.g., frame.fill_color),
you receive a COPY of the color.
Modifying it doesn\[cq]t affect the original.
To change a component:
.IP
.nf
\f[C]
    # 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(\[aq]fill_color.r\[aq], 255, 0.5, \[aq]linear\[aq])
    anim.start(frame)
\f[R]
.fi
.PP
\f[B]Properties:\f[R] - \f[V]a\f[R]: Alpha component (0-255, where
0=transparent, 255=opaque).
Automatically clamped to valid range.
- \f[V]b\f[R]: Blue component (0-255).
Automatically clamped to valid range.
- \f[V]g\f[R]: Green component (0-255).
Automatically clamped to valid range.
- \f[V]r\f[R]: Red component (0-255).
Automatically clamped to valid range.
.PP
\f[B]Methods:\f[R]
.SS \f[V]from_hex(hex_string: str) -> Color\f[R]
.PP
Create a Color from a hexadecimal string.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]hex_string\f[R]: Hex color string (e.g.,
`#FF0000', `FF0000', `#AABBCCDD' for RGBA)
.PP
\f[B]Returns:\f[R] Color: New Color object with values from hex string
.PP
\f[B]Raises:\f[R] ValueError: If hex string is not 6 or 8 characters
(RGB or RGBA) This is a class method.
Call as Color.from_hex(`#FF0000')
.SS \f[V]lerp(other: Color, t: float) -> Color\f[R]
.PP
Linearly interpolate between this color and another.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: The target Color to interpolate
towards - \f[V]t\f[R]: Interpolation factor (0.0 = this color, 1.0 =
other color).
Automatically clamped to [0.0, 1.0]
.PP
\f[B]Returns:\f[R] Color: New Color representing the interpolated value
All components (r, g, b, a) are interpolated independently
.SS \f[V]to_hex() -> str\f[R]
.PP
Convert this Color to a hexadecimal string.
.PP
Note:
.PP
\f[B]Returns:\f[R] str: Hex string in format `#RRGGBB' or `#RRGGBBAA'
(if alpha < 255) Alpha component is only included if not fully opaque (<
255)
.SS ColorLayer
.PP
ColorLayer(z_index=-1, name=None, grid_size=None)
.PP
A grid layer that stores RGBA colors per cell for background/overlay
effects.
.PP
ColorLayers can be created standalone and attached to a Grid via
add_layer() or passed to the Grid constructor\[cq]s layers parameter.
Layers with size (0, 0) automatically resize to match the Grid when
attached.
.PP
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
.PP
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.
.PP
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
.PP
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))
.PP
\f[B]Properties:\f[R] - \f[V]grid\f[R]: Parent Grid or None.
Setting manages layer association and handles lazy allocation.
- \f[V]grid_size\f[R]: Layer dimensions as (width, height) tuple.
- \f[V]name\f[R] \f[I](read-only)\f[R]: Layer name (str, read-only).
Used for Grid.layer(name) lookup.
- \f[V]visible\f[R]: Whether the layer is rendered.
- \f[V]z_index\f[R]: Layer z-order.
Negative values render below entities.
.PP
\f[B]Methods:\f[R]
.SS \f[V]apply_gradient(source, range, color_low, color_high) -> ColorLayer\f[R]
.PP
Interpolate between colors based on HeightMap value within range.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]color_low\f[R]: Color at range minimum -
\f[V]color_high\f[R]: Color at range maximum
.PP
\f[B]Returns:\f[R] self for method chaining Uses the original HeightMap
value for interpolation, not binary.
This allows smooth color transitions within a value range.
.SS \f[V]apply_perspective(entity, visible=None, discovered=None, unknown=None)\f[R]
.PP
Bind this layer to an entity for automatic FOV updates.
.SS \f[V]apply_ranges(source, ranges) -> ColorLayer\f[R]
.PP
Apply multiple color assignments in a single pass.
.PP
Note:
.PP
\f[B]Returns:\f[R] self for method chaining Later ranges override
earlier ones if overlapping.
Cells not matching any range are left unchanged.
.SS \f[V]apply_threshold(source, range, color) -> ColorLayer\f[R]
.PP
Set fixed color for cells where HeightMap value is within range.
.PP
\f[B]Arguments:\f[R] - \f[V]color\f[R]: Color or (r, g, b[, a]) tuple to
set for cells in range
.PP
\f[B]Returns:\f[R] self for method chaining
.SS \f[V]at(pos) -> Color\f[R]
.PP
at(x, y) -> Color Get the color at cell position.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Position as (x, y) tuple, list, or
Vector
.SS \f[V]clear_perspective()\f[R]
.PP
Remove the perspective binding from this layer.
.SS \f[V]draw_fov(source, radius=None, fov=None, visible=None, discovered=None, unknown=None)\f[R]
.PP
Paint cells based on field-of-view visibility from source position.
.PP
Note: Layer must be attached to a grid for FOV calculation.
.SS \f[V]fill(color)\f[R]
.PP
Fill the entire layer with the specified color.
.SS \f[V]fill_rect(pos, size, color)\f[R]
.PP
Fill a rectangular region with a color.
.PP
\f[B]Arguments:\f[R] - \f[V]color\f[R]: Color object or (r, g, b[, a])
tuple
.SS \f[V]set(pos, color)\f[R]
.PP
Set the color at cell position.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Position as (x, y) tuple, list, or
Vector - \f[V]color\f[R]: Color object or (r, g, b[, a]) tuple
.SS \f[V]update_perspective()\f[R]
.PP
Redraw FOV based on the bound entity\[cq]s current position.
Call this after the entity moves to update the visibility layer.
.SS DijkstraMap
.PP
A Dijkstra distance map from a fixed root position.
.PP
Created by Grid.get_dijkstra_map().
Cannot be instantiated directly.
.PP
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.
.PP
Properties: root (Vector): Root position (read-only)
.PP
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
.PP
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
.PP
\f[B]Properties:\f[R] - \f[V]root\f[R] \f[I](read-only)\f[R]: Root
position that distances are measured from (Vector, read-only).
.PP
\f[B]Methods:\f[R]
.SS \f[V]descent_step(pos) -> Vector | None\f[R]
.PP
Get the adjacent cell with the lowest distance (steepest descent).
Unlike step_from (which follows the path set by path_from), descent_step
always returns the best neighbor in a single hop.
Useful for AI that reacts to the current distance field rather than
following a fixed path.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Current position as Vector,
Entity, or (x, y) tuple.
.PP
\f[B]Returns:\f[R] Next position as Vector, or None if pos is a local
minimum or off-grid.
.SS \f[V]distance(pos) -> float | None\f[R]
.PP
Get distance from position to root.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Position as Vector, Entity, or (x,
y) tuple.
.PP
\f[B]Returns:\f[R] Float distance, or None if position is unreachable.
.SS \f[V]invert() -> DijkstraMap\f[R]
.PP
Return a NEW DijkstraMap whose distance field is the safety field.
Cells near a root become high values and cells far from any root become
low values.
Combined with step_from or descent_step, this gives flee behavior:
descend the inverted map to move away from the original roots.
The original DijkstraMap is unchanged.
.PP
\f[B]Returns:\f[R] New DijkstraMap with inverted distances.
.SS \f[V]path_from(pos) -> AStarPath\f[R]
.PP
Get full path from position to root.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Starting position as Vector,
Entity, or (x, y) tuple.
.PP
\f[B]Returns:\f[R] AStarPath from pos toward root.
.SS \f[V]step_from(pos) -> Vector | None\f[R]
.PP
Get single step from position toward root.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Current position as Vector,
Entity, or (x, y) tuple.
.PP
\f[B]Returns:\f[R] Next position as Vector, or None if at root or
unreachable.
.SS \f[V]to_heightmap(size=None, unreachable=-1.0) -> HeightMap\f[R]
.PP
Convert distance field to a HeightMap.
Each cell\[cq]s height equals its pathfinding distance from the root.
Useful for visualization, procedural terrain, or influence mapping.
.PP
\f[B]Arguments:\f[R] - \f[V]size\f[R]: Optional (width, height) tuple.
Defaults to dijkstra dimensions.
- \f[V]unreachable\f[R]: Value for cells that cannot reach root (default
-1.0).
.PP
\f[B]Returns:\f[R] HeightMap with distance values as heights.
.SS DiscreteMap
.PP
DiscreteMap(size: tuple[int, int], fill: int = 0, enum: type[IntEnum] =
None)
.PP
A 2D grid of uint8 values (0-255) for discrete/categorical data.
.PP
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.
.PP
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.
.PP
Example: from enum import IntEnum class Terrain(IntEnum): WATER = 0
GRASS = 1 MOUNTAIN = 2
.IP
.nf
\f[C]
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
\f[R]
.fi
.PP
\f[B]Properties:\f[R] - \f[V]enum_type\f[R]: Optional IntEnum class for
value interpretation.
- \f[V]size\f[R] \f[I](read-only)\f[R]: Dimensions (width, height) of
the map.
Read-only.
.PP
\f[B]Methods:\f[R]
.SS \f[V]add(other: DiscreteMap | int, *, pos=None, source_pos=None, size=None) -> DiscreteMap\f[R]
.PP
Add values from another map or a scalar, with saturation to 0-255.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: DiscreteMap to add, or int
scalar to add to all cells - \f[V]pos\f[R]: Destination start (x, y) in
self (default: (0, 0)) - \f[V]source_pos\f[R]: Source start (x, y) in
other (default: (0, 0)) - \f[V]size\f[R]: Region (width, height)
(default: max overlapping area)
.PP
\f[B]Returns:\f[R] DiscreteMap: self, for method chaining
.SS \f[V]bitwise_and(other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap\f[R]
.PP
Bitwise AND with another DiscreteMap.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: DiscreteMap for AND operation -
\f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0)) -
\f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] DiscreteMap: self, for method chaining
.SS \f[V]bitwise_or(other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap\f[R]
.PP
Bitwise OR with another DiscreteMap.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: DiscreteMap for OR operation -
\f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0)) -
\f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] DiscreteMap: self, for method chaining
.SS \f[V]bitwise_xor(other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap\f[R]
.PP
Bitwise XOR with another DiscreteMap.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: DiscreteMap for XOR operation -
\f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0)) -
\f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] DiscreteMap: self, for method chaining
.SS \f[V]bool(condition: int | set | callable) -> DiscreteMap\f[R]
.PP
Create binary mask from condition.
Returns NEW DiscreteMap.
.PP
\f[B]Arguments:\f[R] - \f[V]condition\f[R]: int: match that value; set:
match any in set; callable: predicate
.PP
\f[B]Returns:\f[R] DiscreteMap: new map with 1 where condition true, 0
elsewhere
.SS \f[V]clear() -> DiscreteMap\f[R]
.PP
Set all cells to 0.
Equivalent to fill(0).
.PP
\f[B]Returns:\f[R] DiscreteMap: self, for method chaining
.SS \f[V]copy_from(other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap\f[R]
.PP
Copy values from another DiscreteMap into the specified region.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: DiscreteMap to copy from -
\f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0)) -
\f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] DiscreteMap: self, for method chaining
.SS \f[V]count(value: int) -> int\f[R]
.PP
Count cells with the specified value.
.PP
\f[B]Arguments:\f[R] - \f[V]value\f[R]: Value to count (0-255)
.PP
\f[B]Returns:\f[R] int: Number of cells with that value
.SS \f[V]count_range(min_val: int, max_val: int) -> int\f[R]
.PP
Count cells with values in the specified range (inclusive).
.PP
\f[B]Arguments:\f[R] - \f[V]min_val\f[R]: Minimum value (inclusive) -
\f[V]max_val\f[R]: Maximum value (inclusive)
.PP
\f[B]Returns:\f[R] int: Number of cells in range
.SS \f[V]fill(value: int, *, pos=None, size=None) -> DiscreteMap\f[R]
.PP
Set cells in region to the specified value.
.PP
\f[B]Arguments:\f[R] - \f[V]value\f[R]: The value to set (0-255, or
IntEnum member) - \f[V]pos\f[R]: Region start (x, y) in destination
(default: (0, 0)) - \f[V]size\f[R]: Region (width, height) to fill
(default: remaining space)
.PP
\f[B]Returns:\f[R] DiscreteMap: self, for method chaining
.SS \f[V]from_bytes(data: bytes, size: tuple[int, int], *, enum: type = None) -> DiscreteMap\f[R]
.PP
Create a DiscreteMap from raw byte data.
.PP
\f[B]Arguments:\f[R] - \f[V]data\f[R]: Raw cell data (one byte per cell,
row-major) - \f[V]size\f[R]: (width, height) dimensions -
\f[V]enum\f[R]: Optional IntEnum class for value interpretation
.PP
\f[B]Returns:\f[R] DiscreteMap: new map initialized from data
.PP
\f[B]Raises:\f[R] ValueError: Data length does not match width * height
.SS \f[V]from_heightmap(hmap: HeightMap, mapping: list[tuple[tuple[float,float], int]], *, enum=None) -> DiscreteMap\f[R]
.PP
Create DiscreteMap from HeightMap using range-to-value mapping.
.PP
\f[B]Arguments:\f[R] - \f[V]hmap\f[R]: HeightMap to convert -
\f[V]mapping\f[R]: List of ((min, max), value) tuples - \f[V]enum\f[R]:
Optional IntEnum class for value interpretation
.PP
\f[B]Returns:\f[R] DiscreteMap: new map with mapped values
.SS \f[V]get(x, y) or (pos) -> int | Enum\f[R]
.PP
Get the value at integer coordinates.
.PP
\f[B]Returns:\f[R] int or enum member if enum_type is set
.PP
\f[B]Raises:\f[R] IndexError: Position is out of bounds
.SS \f[V]histogram() -> dict[int, int]\f[R]
.PP
Get a histogram of value counts.
.PP
\f[B]Returns:\f[R] dict: {value: count} for all values present in the
map
.SS \f[V]invert() -> DiscreteMap\f[R]
.PP
Return NEW DiscreteMap with (255 - value) for each cell.
.PP
\f[B]Returns:\f[R] DiscreteMap: new inverted map (original unchanged)
.SS \f[V]mask() -> memoryview\f[R]
.PP
Get raw uint8_t data as memoryview for libtcod compatibility.
.PP
\f[B]Returns:\f[R] memoryview: Direct access to internal buffer
(read/write)
.SS \f[V]max(other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap\f[R]
.PP
Set each cell to the maximum of this and another DiscreteMap.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: DiscreteMap to compare with -
\f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0)) -
\f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] DiscreteMap: self, for method chaining
.SS \f[V]min(other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap\f[R]
.PP
Set each cell to the minimum of this and another DiscreteMap.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: DiscreteMap to compare with -
\f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0)) -
\f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] DiscreteMap: self, for method chaining
.SS \f[V]min_max() -> tuple[int, int]\f[R]
.PP
Get the minimum and maximum values in the map.
.PP
\f[B]Returns:\f[R] tuple[int, int]: (min_value, max_value)
.SS \f[V]multiply(factor: float, *, pos=None, size=None) -> DiscreteMap\f[R]
.PP
Multiply values by a scalar factor, with saturation to 0-255.
.PP
\f[B]Arguments:\f[R] - \f[V]factor\f[R]: Multiplier for each cell -
\f[V]pos\f[R]: Region start (x, y) (default: (0, 0)) - \f[V]size\f[R]:
Region (width, height) (default: entire map)
.PP
\f[B]Returns:\f[R] DiscreteMap: self, for method chaining
.SS \f[V]set(x: int, y: int, value: int) -> None\f[R]
.PP
Set the value at integer coordinates.
.PP
\f[B]Arguments:\f[R] - \f[V]x\f[R]: X coordinate - \f[V]y\f[R]: Y
coordinate - \f[V]value\f[R]: Value to set (0-255, or IntEnum member)
.PP
\f[B]Raises:\f[R] IndexError: Position is out of bounds ValueError:
Value out of range 0-255
.SS \f[V]subtract(other: DiscreteMap | int, *, pos=None, source_pos=None, size=None) -> DiscreteMap\f[R]
.PP
Subtract values from another map or a scalar, with saturation to 0-255.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: DiscreteMap to subtract, or int
scalar - \f[V]pos\f[R]: Destination start (x, y) in self (default: (0,
0)) - \f[V]source_pos\f[R]: Source start (x, y) in other (default: (0,
0)) - \f[V]size\f[R]: Region (width, height) (default: max overlapping
area)
.PP
\f[B]Returns:\f[R] DiscreteMap: self, for method chaining
.SS \f[V]to_bytes() -> bytes\f[R]
.PP
Serialize map data to bytes (row-major, one byte per cell).
.PP
\f[B]Returns:\f[R] bytes: Raw cell data, length = width * height
.SS \f[V]to_heightmap(mapping: dict[int, float] = None) -> HeightMap\f[R]
.PP
Convert to HeightMap, optionally mapping values to floats.
.PP
\f[B]Arguments:\f[R] - \f[V]mapping\f[R]: Optional {int: float} mapping
(default: direct cast)
.PP
\f[B]Returns:\f[R] HeightMap: new heightmap with converted values
.SS Drawable
.PP
Base class for all drawable UI elements
.PP
\f[B]Properties:\f[R] - \f[V]on_click\f[R]: Callable executed when
object is clicked.
Function receives (pos: Vector, button: str, action: str).
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]visible\f[R]: Whether the object is visible (bool).
Invisible objects are not rendered or clickable.
- \f[V]z_index\f[R]: Z-order for rendering (lower values rendered
first).
Automatically triggers scene resort when changed.
.PP
\f[B]Methods:\f[R]
.SS \f[V]move(dx, dy) or (delta) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels (or use
delta) - \f[V]dy\f[R]: Vertical offset in pixels (or use delta) -
\f[V]delta\f[R]: Offset as tuple, list, or Vector: (dx, dy)
.SS \f[V]resize(width, height) or (size) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels (or use
size) - \f[V]height\f[R]: New height in pixels (or use size) -
\f[V]size\f[R]: Size as tuple, list, or Vector: (width, height)
.SS Easing
.PP
\f[I]Inherits from: IntEnum\f[R]
.PP
\f[B]Properties:\f[R] - \f[V]denominator\f[R]: the denominator of a
rational number in lowest terms - \f[V]imag\f[R]: the imaginary part of
a complex number - \f[V]numerator\f[R]: the numerator of a rational
number in lowest terms - \f[V]real\f[R]: the real part of a complex
number
.PP
\f[B]Methods:\f[R]
.SS \f[V]as_integer_ratio(...)\f[R]
.PP
Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10,
1) >>> (0).as_integer_ratio() (0, 1)
.SS \f[V]bit_count(...)\f[R]
.PP
Number of ones in the binary representation of the absolute value of
self.
Also known as the population count.
>>> bin(13) `0b1101' >>> (13).bit_count() 3
.SS \f[V]bit_length(...)\f[R]
.PP
Number of bits necessary to represent self in binary.
>>> bin(37) `0b100101' >>> (37).bit_length() 6
.SS \f[V]conjugate(...)\f[R]
.PP
Returns self, the complex conjugate of any int.
.SS \f[V]from_bytes(...)\f[R]
.PP
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert.
The argument must either support the buffer protocol or be an iterable
object producing bytes.
Bytes and bytearray are examples of built-in objects that support the
buffer protocol.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Indicates whether two\[cq]s complement is used to represent the
integer.
.SS \f[V]is_integer(...)\f[R]
.PP
Returns True.
Exists for duck type compatibility with float.is_integer.
.SS \f[V]to_bytes(...)\f[R]
.PP
Return an array of bytes representing an integer.
length Length of bytes object to use.
An OverflowError is raised if the integer is not representable with the
given number of bytes.
Default is length 1.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Determines whether two\[cq]s complement is used to represent the
integer.
If signed is False and a negative integer is given, an OverflowError is
raised.
.SS Entity
.PP
Entity(grid_pos=None, texture=None, sprite_index=0, **kwargs)
.PP
A game entity that exists on a grid with sprite rendering.
.PP
Args: grid_pos (tuple, optional): Grid position as (x, y) tuple.
Default: (0, 0) texture (Texture, optional): Texture object for sprite.
Default: default texture sprite_index (int, optional): Index into
texture atlas.
Default: 0
.PP
Keyword Args: grid (Grid): Grid to attach entity to.
Default: None visible (bool): Visibility state.
Default: True opacity (float): Opacity (0.0-1.0).
Default: 1.0 name (str): Element name for finding.
Default: None x (float): X grid position override (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
.PP
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
texture (Texture): Texture atlas used by the entity\[cq]s sprite
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
.PP
\f[B]Properties:\f[R] - \f[V]behavior_type\f[R] \f[I](read-only)\f[R]:
Current behavior type (int, read-only).
Use set_behavior() to change.
- \f[V]cell_pos\f[R]: Integer logical cell position (Vector).
Alias for grid_pos (the canonical name).
- \f[V]cell_x\f[R]: Integer X cell coordinate.
Alias for grid_x.
- \f[V]cell_y\f[R]: Integer Y cell coordinate.
Alias for grid_y.
- \f[V]default_behavior\f[R]: Default behavior type (int, maps to
Behavior enum).
Entity reverts to this after DONE trigger.
Default: 0 (IDLE).
- \f[V]draw_pos\f[R]: Fractional tile position for rendering (Vector).
Use for smooth animation between grid cells.
- \f[V]grid\f[R]: Grid this entity belongs to.
Get: Returns the Grid or None.
Set: Assign a Grid to move entity, or None to remove from grid.
- \f[V]grid_pos\f[R]: Integer logical cell position (Vector).
Canonical cell-position property; matches the `grid_pos' constructor
argument.
Decoupled from draw_pos.
Determines which cell this entity logically occupies for collision,
pathfinding, etc.
- \f[V]grid_x\f[R]: Integer X cell coordinate.
Canonical; matches grid_pos.
- \f[V]grid_y\f[R]: Integer Y cell coordinate.
Canonical; matches grid_pos.
- \f[V]labels\f[R]: Set of string labels for collision/targeting
(frozenset).
Assign any iterable of strings to replace all labels.
- \f[V]move_speed\f[R]: Animation duration for behavior movement in
seconds (float).
0 = instant.
Default: 0.15.
- \f[V]name\f[R]: Name for finding elements - \f[V]opacity\f[R]: Opacity
(0.0 = transparent, 1.0 = opaque) - \f[V]perspective_map\f[R]:
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 \[en] mutations are visible
to subsequent updateVisibility() calls.
Assigning a DiscreteMap replaces the entity\[cq]s memory; the new
map\[cq]s size must match the grid\[cq]s size or ValueError is raised.
Assign None to clear (will be lazy-reallocated on next access).
- \f[V]pos\f[R]: Pixel position relative to grid (Vector).
Computed as draw_pos * tile_size.
Requires entity to be attached to a grid.
- \f[V]shader\f[R]: 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.
- \f[V]sight_radius\f[R]: FOV radius for TARGET trigger (int).
Default: 10.
- \f[V]sprite_grid\f[R]: 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.
- \f[V]sprite_index\f[R]: Sprite index on the texture on the display -
\f[V]sprite_offset\f[R]: Pixel offset for oversized sprites (Vector).
Applied pre-zoom during grid rendering.
- \f[V]sprite_offset_x\f[R]: X component of sprite pixel offset.
- \f[V]sprite_offset_y\f[R]: Y component of sprite pixel offset.
- \f[V]step\f[R]: Step callback for grid.step() turn management.
Called with (trigger, data) when behavior triggers fire.
Set to None to clear.
- \f[V]target_label\f[R]: Label to search for with TARGET trigger (str
or None).
Default: None.
- \f[V]texture\f[R]: Sprite texture atlas (Texture).
Defaults to mcrfpy.default_texture when the entity is constructed
without one.
Setting preserves sprite_index (the index is not re-validated against
the new atlas).
The grid\[cq]s texture only determines cell size; entities draw with
their own.
- \f[V]tile_height\f[R]: Entity height in tiles (int).
Must be >= 1.
Default 1.
- \f[V]tile_size\f[R]: Entity size in tiles as (width, height) Vector.
Default (1, 1).
- \f[V]tile_width\f[R]: Entity width in tiles (int).
Must be >= 1.
Default 1.
- \f[V]turn_order\f[R]: Turn order for grid.step() (int).
0 = skip, higher values go later.
Default: 1.
- \f[V]uniforms\f[R] \f[I](read-only)\f[R]: 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.
- \f[V]visible\f[R]: Visibility flag - \f[V]x\f[R]: Pixel X position
relative to grid.
Requires entity to be attached to a grid.
- \f[V]y\f[R]: Pixel Y position relative to grid.
Requires entity to be attached to a grid.
.PP
\f[B]Methods:\f[R]
.SS \f[V]add_label(label: str) -> None\f[R]
.PP
Add a label to this entity.
Idempotent (adding same label twice is safe).
.SS \f[V]animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode=\[aq]replace\[aq]) -> Animation\f[R]
.PP
Create and start an animation on this entity\[cq]s property.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]property\f[R]: Name of the property to
animate: `draw_x', `draw_y' (tile coords), `sprite_scale',
`sprite_index' - \f[V]target\f[R]: Target value - float, int, or list of
int (for sprite frame sequences) - \f[V]duration\f[R]: Animation
duration in seconds - \f[V]easing\f[R]: Easing function: Easing enum
value, string name, or None for linear - \f[V]delta\f[R]: If True,
target is relative to current value; if False, target is absolute -
\f[V]loop\f[R]: If True, animation repeats from start when it reaches
the end (default False) - \f[V]callback\f[R]: Optional callable invoked
when animation completes (not called for looping animations) -
\f[V]conflict_mode\f[R]: `replace' (default), `queue', or `error' if
property already animating
.PP
\f[B]Returns:\f[R] Animation object for monitoring progress
.PP
\f[B]Raises:\f[R] ValueError: If property name is not valid for Entity
(draw_x, draw_y, sprite_scale, sprite_index) Use `draw_x'/`draw_y' to
animate tile coordinates for smooth movement between grid cells.
Use list target with loop=True for repeating sprite frame animations.
.SS \f[V]at(x, y) or at(pos) -> GridPoint | None\f[R]
.PP
Return the GridPoint at (x, y) if currently VISIBLE to this entity\[cq]s
perspective_map, otherwise None.
Equivalent to: grid.at(x, y) if perspective_map[x, y] ==
Perspective.VISIBLE else None To inspect discovered-but-not-visible
cells, read entity.perspective_map[x, y] directly and use grid.at(x, y)
for cell data.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Grid coordinates as tuple, list,
or Vector
.SS \f[V]die(...)\f[R]
.PP
Remove this entity from its grid.
Warning: Do not call during iteration over grid.entities.
Modifying the collection during iteration raises RuntimeError.
.SS \f[V]find_path(target, diagonal_cost=1.41, collide=None) -> AStarPath | None\f[R]
.PP
Find a path from this entity to the target position.
.PP
\f[B]Arguments:\f[R] - \f[V]target\f[R]: Target as Vector, Entity, or
(x, y) tuple.
- \f[V]diagonal_cost\f[R]: Cost of diagonal movement (default 1.41).
- \f[V]collide\f[R]: Label string.
Entities with this label block pathfinding.
.PP
\f[B]Returns:\f[R] AStarPath object, or None if no path exists.
.SS \f[V]has_label(label: str) -> bool\f[R]
.PP
Check if this entity has the given label.
.SS \f[V]index(...)\f[R]
.PP
Return the index of this entity in its grid\[cq]s entity collection
.SS \f[V]move(dx, dy) or (delta) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels (or use
delta) - \f[V]dy\f[R]: Vertical offset in pixels (or use delta) -
\f[V]delta\f[R]: Offset as tuple, list, or Vector: (dx, dy)
.SS \f[V]path_to(x, y) or path_to(target) -> list\f[R]
.PP
Find a path to the target position using Dijkstra pathfinding.
.PP
\f[B]Arguments:\f[R] - \f[V]target\f[R]: Target coordinates as tuple,
list, or Vector
.PP
\f[B]Returns:\f[R] List of (x, y) tuples representing the path.
.SS \f[V]remove_label(label: str) -> None\f[R]
.PP
Remove a label from this entity.
No-op if label not present.
.SS \f[V]resize(width, height) or (size) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels (or use
size) - \f[V]height\f[R]: New height in pixels (or use size) -
\f[V]size\f[R]: Size as tuple, list, or Vector: (width, height)
.SS \f[V]set_behavior(type, waypoints=None, turns=0, path=None) -> None\f[R]
.PP
Configure this entity\[cq]s behavior for grid.step() turn management.
.SS \f[V]update_visibility() -> None\f[R]
.PP
Update entity\[cq]s visibility state based on current FOV.
Recomputes which cells are visible from the entity\[cq]s position and
updates the entity\[cq]s perspective_map (see entity.perspective_map and
mcrfpy.Perspective).
This is called automatically when the entity moves if it has a grid with
perspective set.
.SS \f[V]visible_entities(fov=None, radius=None) -> list[Entity]\f[R]
.PP
Get list of other entities visible from this entity\[cq]s position.
.PP
\f[B]Returns:\f[R] List of Entity objects that are within field of view.
Computes FOV from this entity\[cq]s position and returns all other
entities whose positions fall within the visible area.
.SS Entity3D
.PP
Entity3D(pos=None, **kwargs)
.PP
A 3D game entity that exists on a Viewport3D\[cq]s navigation grid.
.PP
Args: pos (tuple, optional): Grid position as (x, z).
Default: (0, 0)
.PP
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
.PP
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)
.PP
\f[B]Properties:\f[R] - \f[V]anim_clip\f[R]: Current animation clip
name.
Set to play an animation.
- \f[V]anim_frame\f[R] \f[I](read-only)\f[R]: Current animation frame
number (read-only, approximate at 30fps).
- \f[V]anim_loop\f[R]: Whether animation loops when it reaches the end.
- \f[V]anim_paused\f[R]: Whether animation playback is paused.
- \f[V]anim_speed\f[R]: Animation playback speed multiplier.
1.0 = normal speed.
- \f[V]anim_time\f[R]: Current time position in animation (seconds).
- \f[V]auto_animate\f[R]: Enable auto-play of walk/idle clips based on
movement.
- \f[V]color\f[R]: Entity render color.
- \f[V]grid_pos\f[R]: Grid position (x, z).
Same as pos.
- \f[V]idle_clip\f[R]: Animation clip to play when entity is stationary.
- \f[V]is_moving\f[R] \f[I](read-only)\f[R]: Whether entity is currently
moving (read-only).
- \f[V]model\f[R]: 3D model (Model3D).
If None, uses placeholder cube.
- \f[V]name\f[R]: Entity name (str).
Used for find() lookup.
- \f[V]on_anim_complete\f[R]: Callback(entity, clip_name) when
non-looping animation ends.
- \f[V]pos\f[R]: Grid position (x, z).
Setting triggers smooth movement.
- \f[V]rotation\f[R]: Y-axis rotation in degrees.
- \f[V]scale\f[R]: Uniform scale factor.
Can also set as (x, y, z) tuple.
- \f[V]viewport\f[R] \f[I](read-only)\f[R]: Owning Viewport3D
(read-only).
- \f[V]visible\f[R]: Visibility state.
- \f[V]walk_clip\f[R]: Animation clip to play when entity is moving.
- \f[V]world_pos\f[R] \f[I](read-only)\f[R]: Current world position (x,
y, z) (read-only).
Includes animation interpolation.
.PP
\f[B]Methods:\f[R]
.SS \f[V]animate(property, target, duration, easing=None, delta=False, callback=None, conflict_mode=None)\f[R]
.PP
Animate a property over time.
.PP
\f[B]Arguments:\f[R] - \f[V]property\f[R]: Property name (x, y, z,
rotation, scale, etc.)
- \f[V]target\f[R]: Target value (float or int) - \f[V]duration\f[R]:
Animation duration in seconds - \f[V]easing\f[R]: Easing function
(Easing enum or None for linear) - \f[V]delta\f[R]: If True, target is
relative to current value - \f[V]callback\f[R]: Called with (target,
property, value) when complete - \f[V]conflict_mode\f[R]: `replace',
`queue', or `error'
.SS \f[V]at(x, z) -> dict\f[R]
.PP
Get visibility state for a cell from this entity\[cq]s perspective.
Returns dict with `visible' and `discovered' boolean keys.
.SS \f[V]clear_path()\f[R]
.PP
Clear the movement queue and stop at current position.
.SS \f[V]follow_path(path)\f[R]
.PP
Queue path positions for smooth movement.
.PP
\f[B]Arguments:\f[R] - \f[V]path\f[R]: List of (x, z) tuples (as
returned by path_to())
.SS \f[V]path_to(x, z) or path_to(pos=(x, z)) -> list\f[R]
.PP
Compute A* path to target position.
Returns list of (x, z) tuples, or empty list if no path exists.
.SS \f[V]teleport(x, z) or teleport(pos=(x, z))\f[R]
.PP
Instantly move to target position without animation.
.SS \f[V]update_visibility()\f[R]
.PP
Recompute field of view from current position.
.SS EntityCollection3D
.PP
Collection of Entity3D objects belonging to a Viewport3D.
.PP
Supports list-like operations: indexing, iteration, append, remove.
.PP
Example: viewport.entities.append(entity) for entity in
viewport.entities: print(entity.pos)
.PP
\f[B]Methods:\f[R]
.SS \f[V]append(entity)\f[R]
.PP
Add an Entity3D to the collection.
.SS \f[V]clear()\f[R]
.PP
Remove all entities from the collection.
.SS \f[V]extend(iterable)\f[R]
.PP
Add all Entity3D objects from iterable to the collection.
.SS \f[V]find(name) -> Entity3D or None\f[R]
.PP
Find an Entity3D by name.
Returns None if not found.
.SS \f[V]pop(index=-1) -> Entity3D\f[R]
.PP
Remove and return Entity3D at index (default: last).
.SS \f[V]remove(entity)\f[R]
.PP
Remove an Entity3D from the collection.
.SS EntityCollection3DIter
.PP
Iterator for EntityCollection3D
.PP
\f[B]Methods:\f[R]
.SS FOV
.PP
\f[I]Inherits from: IntEnum\f[R]
.PP
\f[B]Properties:\f[R] - \f[V]denominator\f[R]: the denominator of a
rational number in lowest terms - \f[V]imag\f[R]: the imaginary part of
a complex number - \f[V]numerator\f[R]: the numerator of a rational
number in lowest terms - \f[V]real\f[R]: the real part of a complex
number
.PP
\f[B]Methods:\f[R]
.SS \f[V]as_integer_ratio(...)\f[R]
.PP
Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10,
1) >>> (0).as_integer_ratio() (0, 1)
.SS \f[V]bit_count(...)\f[R]
.PP
Number of ones in the binary representation of the absolute value of
self.
Also known as the population count.
>>> bin(13) `0b1101' >>> (13).bit_count() 3
.SS \f[V]bit_length(...)\f[R]
.PP
Number of bits necessary to represent self in binary.
>>> bin(37) `0b100101' >>> (37).bit_length() 6
.SS \f[V]conjugate(...)\f[R]
.PP
Returns self, the complex conjugate of any int.
.SS \f[V]from_bytes(...)\f[R]
.PP
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert.
The argument must either support the buffer protocol or be an iterable
object producing bytes.
Bytes and bytearray are examples of built-in objects that support the
buffer protocol.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Indicates whether two\[cq]s complement is used to represent the
integer.
.SS \f[V]is_integer(...)\f[R]
.PP
Returns True.
Exists for duck type compatibility with float.is_integer.
.SS \f[V]to_bytes(...)\f[R]
.PP
Return an array of bytes representing an integer.
length Length of bytes object to use.
An OverflowError is raised if the integer is not representable with the
given number of bytes.
Default is length 1.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Determines whether two\[cq]s complement is used to represent the
integer.
If signed is False and a negative integer is given, an OverflowError is
raised.
.SS Font
.PP
Font(filename: str)
.PP
A font resource for rendering text in Caption elements.
.PP
Args: filename: Path to a TrueType (.ttf) or OpenType (.otf) font file.
.PP
Properties: family (str, read-only): Font family name from metadata.
source (str, read-only): File path used to load this font.
.PP
\f[B]Properties:\f[R] - \f[V]family\f[R] \f[I](read-only)\f[R]: Font
family name (str, read-only).
Retrieved from font metadata.
- \f[V]source\f[R] \f[I](read-only)\f[R]: Source filename path (str,
read-only).
The path used to load this font.
.PP
\f[B]Methods:\f[R]
.SS Frame
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Frame(pos=None, size=None, **kwargs)
.PP
A rectangular frame UI element that can contain other drawable elements.
.PP
Args: pos (tuple, optional): Position as (x, y) tuple.
Default: (0, 0) size (tuple, optional): Size as (width, height) tuple.
Default: (0, 0)
.PP
Keyword Args: fill_color (Color): Background fill color.
Default: (0, 0, 0, 128) outline_color (Color): Border outline color.
Default: (255, 255, 255, 255) outline (float): Border outline thickness.
Default: 0 click (callable): Click event handler.
Default: None children (list): Initial list of child drawable elements.
Default: None visible (bool): Visibility state.
Default: True opacity (float): Opacity (0.0-1.0).
Default: 1.0 z_index (int): Rendering order.
Default: 0 name (str): Element name for finding.
Default: None x (float): X position override.
Default: 0 y (float): Y position override.
Default: 0 w (float): Width override.
Default: 0 h (float): Height override.
Default: 0 clip_children (bool): Whether to clip children to frame
bounds.
Default: False 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)
.PP
Attributes: x, y (float): Position in pixels w, h (float): Size in
pixels pos (Vector): Position as a Vector object fill_color,
outline_color (Color): Visual appearance outline (float): Border
thickness click (callable): Click event handler children (list):
Collection of child drawable elements visible (bool): Visibility state
opacity (float): Opacity value z_index (int): Rendering order name
(str): Element name clip_children (bool): Whether to clip children to
frame bounds 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
.PP
\f[B]Properties:\f[R] - \f[V]align\f[R]: 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.
- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]cache_subtree\f[R]: #144: Cache subtree rendering to texture for
performance - \f[V]children\f[R]: UICollection of objects on top of this
one - \f[V]clip_children\f[R]: Whether to clip children to frame bounds
- \f[V]fill_color\f[R]: Fill color of the rectangle.
Returns a copy; modifying components requires reassignment.
For animation, use `fill_color.r', `fill_color.g', etc.
- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
in screen coordinates.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
position (read-only).
Calculates absolute position by walking up the parent chain.
- \f[V]grid_pos\f[R]: Position in grid tile coordinates (only when
parent is Grid) - \f[V]grid_size\f[R]: Size in grid tile coordinates
(only when parent is Grid) - \f[V]h\f[R]: height of the rectangle -
\f[V]horiz_margin\f[R]: Horizontal margin override (float, 0 = use
general margin).
Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER,
CENTER).
- \f[V]hovered\f[R] \f[I](read-only)\f[R]: Whether mouse is currently
over this element (read-only).
Updated automatically by the engine during mouse movement.
- \f[V]margin\f[R]: General margin from edge when aligned (float).
Applied to both horizontal and vertical edges unless overridden.
Invalid for CENTER alignment (raises ValueError).
- \f[V]name\f[R]: Name for finding elements - \f[V]on_click\f[R]:
Callable executed when object is clicked.
Function receives (pos: Vector, button: str, action: str).
- \f[V]on_enter\f[R]: Callback for mouse enter events.
Called with (pos: Vector, button: str, action: str) when mouse enters
this element\[cq]s bounds.
- \f[V]on_exit\f[R]: Callback for mouse exit events.
Called with (pos: Vector, button: str, action: str) when mouse leaves
this element\[cq]s bounds.
- \f[V]on_move\f[R]: 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.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]outline\f[R]: Thickness of the border - \f[V]outline_color\f[R]:
Outline color of the rectangle.
Returns a copy; modifying components requires reassignment.
For animation, use `outline_color.r', `outline_color.g', etc.
- \f[V]parent\f[R]: 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.
- \f[V]pos\f[R]: Position as a Vector - \f[V]rotate_with_camera\f[R]:
Whether to rotate visually with parent Grid\[cq]s camera_rotation
(bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]shader\f[R]: 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.
- \f[V]uniforms\f[R] \f[I](read-only)\f[R]: 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.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
Invisible objects are not rendered or clickable.
- \f[V]w\f[R]: width of the rectangle - \f[V]x\f[R]: X coordinate of
top-left corner - \f[V]y\f[R]: Y coordinate of top-left corner -
\f[V]z_index\f[R]: Z-order for rendering (lower values rendered first).
Automatically triggers scene resort when changed.
.PP
\f[B]Methods:\f[R]
.SS \f[V]animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode=\[aq]replace\[aq]) -> Animation\f[R]
.PP
Create and start an animation on this drawable\[cq]s property.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]property\f[R]: Name of the property to
animate (e.g., `x', `fill_color', `opacity') - \f[V]target\f[R]: Target
value - type depends on property (float, tuple for color/vector, etc.)
- \f[V]duration\f[R]: Animation duration in seconds - \f[V]easing\f[R]:
Easing function: Easing enum value, string name, or None for linear -
\f[V]delta\f[R]: If True, target is relative to current value; if False,
target is absolute - \f[V]loop\f[R]: If True, animation repeats from
start when it reaches the end (default False) - \f[V]callback\f[R]:
Optional callable invoked when animation completes (not called for
looping animations) - \f[V]conflict_mode\f[R]: `replace' (default),
`queue', or `error' if property already animating
.PP
\f[B]Returns:\f[R] Animation object for monitoring progress
.PP
\f[B]Raises:\f[R] ValueError: If property name is not valid for this
drawable type This is a convenience method that creates an Animation,
starts it, and adds it to the AnimationManager.
.SS \f[V]move(dx, dy) or (delta) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels (or use
delta) - \f[V]dy\f[R]: Vertical offset in pixels (or use delta) -
\f[V]delta\f[R]: Offset as tuple, list, or Vector: (dx, dy)
.SS \f[V]realign() -> None\f[R]
.PP
Reapply alignment relative to parent, useful for responsive layouts.
.PP
Note: Call this to recalculate position after parent changes size.
For elements with align=None, this has no effect.
.SS \f[V]resize(width, height) or (size) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels (or use
size) - \f[V]height\f[R]: New height in pixels (or use size) -
\f[V]size\f[R]: Size as tuple, list, or Vector: (width, height)
.SS Grid
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Grid(grid_size=None, pos=None, size=None, texture=None, **kwargs)
.PP
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).
.PP
Can also be constructed as a view of existing grid data:
Grid(grid=existing_grid, pos=\&..., size=\&...)
.PP
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
.PP
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.
.PP
\f[B]Properties:\f[R] - \f[V]align\f[R]: 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.
- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]camera_rotation\f[R]: Rotation of grid contents around camera
center (degrees).
- \f[V]center\f[R]: Camera center point in pixel coordinates.
- \f[V]center_x\f[R]: center of the view X-coordinate -
\f[V]center_y\f[R]: center of the view Y-coordinate -
\f[V]fill_color\f[R]: Background fill color.
- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
in screen coordinates.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
position (read-only).
Calculates absolute position by walking up the parent chain.
- \f[V]grid_data\f[R]: The underlying grid data object (for multi-view
scenarios).
- \f[V]h\f[R]: visible widget height - \f[V]horiz_margin\f[R]:
Horizontal margin override (float, 0 = use general margin).
Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER,
CENTER).
- \f[V]hovered\f[R] \f[I](read-only)\f[R]: Whether mouse is currently
over this element (read-only).
Updated automatically by the engine during mouse movement.
- \f[V]margin\f[R]: General margin from edge when aligned (float).
Applied to both horizontal and vertical edges unless overridden.
Invalid for CENTER alignment (raises ValueError).
- \f[V]name\f[R]: Name for finding elements - \f[V]on_click\f[R]:
Callable executed when object is clicked.
- \f[V]on_enter\f[R]: Callback for mouse enter events.
Called with (pos: Vector, button: str, action: str) when mouse enters
this element\[cq]s bounds.
- \f[V]on_exit\f[R]: Callback for mouse exit events.
Called with (pos: Vector, button: str, action: str) when mouse leaves
this element\[cq]s bounds.
- \f[V]on_move\f[R]: 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.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]parent\f[R]: 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.
- \f[V]pos\f[R]: Position of the grid as Vector -
\f[V]rotate_with_camera\f[R]: Whether to rotate visually with parent
Grid\[cq]s camera_rotation (bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]shader\f[R]: 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.
- \f[V]texture\f[R] \f[I](read-only)\f[R]: Texture used for tile
rendering (read-only).
- \f[V]uniforms\f[R] \f[I](read-only)\f[R]: 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.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
Invisible objects are not rendered or clickable.
- \f[V]w\f[R]: visible widget width - \f[V]x\f[R]: top-left corner
X-coordinate - \f[V]y\f[R]: top-left corner Y-coordinate -
\f[V]z_index\f[R]: Z-order for rendering (lower values rendered first).
- \f[V]zoom\f[R]: Zoom level for rendering.
.PP
\f[B]Methods:\f[R]
.SS \f[V]animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode=\[aq]replace\[aq]) -> Animation\f[R]
.PP
Create and start an animation on this drawable\[cq]s property.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]property\f[R]: Name of the property to
animate (e.g., `x', `fill_color', `opacity') - \f[V]target\f[R]: Target
value - type depends on property (float, tuple for color/vector, etc.)
- \f[V]duration\f[R]: Animation duration in seconds - \f[V]easing\f[R]:
Easing function: Easing enum value, string name, or None for linear -
\f[V]delta\f[R]: If True, target is relative to current value; if False,
target is absolute - \f[V]loop\f[R]: If True, animation repeats from
start when it reaches the end (default False) - \f[V]callback\f[R]:
Optional callable invoked when animation completes (not called for
looping animations) - \f[V]conflict_mode\f[R]: `replace' (default),
`queue', or `error' if property already animating
.PP
\f[B]Returns:\f[R] Animation object for monitoring progress
.PP
\f[B]Raises:\f[R] ValueError: If property name is not valid for this
drawable type This is a convenience method that creates an Animation,
starts it, and adds it to the AnimationManager.
.SS \f[V]move(dx, dy) or (delta) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels (or use
delta) - \f[V]dy\f[R]: Vertical offset in pixels (or use delta) -
\f[V]delta\f[R]: Offset as tuple, list, or Vector: (dx, dy)
.SS \f[V]realign() -> None\f[R]
.PP
Reapply alignment relative to parent, useful for responsive layouts.
.PP
Note: Call this to recalculate position after parent changes size.
For elements with align=None, this has no effect.
.SS \f[V]resize(width, height) or (size) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels (or use
size) - \f[V]height\f[R]: New height in pixels (or use size) -
\f[V]size\f[R]: Size as tuple, list, or Vector: (width, height)
.SS GridView
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Grid(grid_size=None, pos=None, size=None, texture=None, **kwargs)
.PP
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).
.PP
Can also be constructed as a view of existing grid data:
Grid(grid=existing_grid, pos=\&..., size=\&...)
.PP
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
.PP
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.
.PP
\f[B]Properties:\f[R] - \f[V]align\f[R]: 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.
- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]camera_rotation\f[R]: Rotation of grid contents around camera
center (degrees).
- \f[V]center\f[R]: Camera center point in pixel coordinates.
- \f[V]center_x\f[R]: center of the view X-coordinate -
\f[V]center_y\f[R]: center of the view Y-coordinate -
\f[V]fill_color\f[R]: Background fill color.
- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
in screen coordinates.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
position (read-only).
Calculates absolute position by walking up the parent chain.
- \f[V]grid_data\f[R]: The underlying grid data object (for multi-view
scenarios).
- \f[V]h\f[R]: visible widget height - \f[V]horiz_margin\f[R]:
Horizontal margin override (float, 0 = use general margin).
Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER,
CENTER).
- \f[V]hovered\f[R] \f[I](read-only)\f[R]: Whether mouse is currently
over this element (read-only).
Updated automatically by the engine during mouse movement.
- \f[V]margin\f[R]: General margin from edge when aligned (float).
Applied to both horizontal and vertical edges unless overridden.
Invalid for CENTER alignment (raises ValueError).
- \f[V]name\f[R]: Name for finding elements - \f[V]on_click\f[R]:
Callable executed when object is clicked.
- \f[V]on_enter\f[R]: Callback for mouse enter events.
Called with (pos: Vector, button: str, action: str) when mouse enters
this element\[cq]s bounds.
- \f[V]on_exit\f[R]: Callback for mouse exit events.
Called with (pos: Vector, button: str, action: str) when mouse leaves
this element\[cq]s bounds.
- \f[V]on_move\f[R]: 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.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]parent\f[R]: 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.
- \f[V]pos\f[R]: Position of the grid as Vector -
\f[V]rotate_with_camera\f[R]: Whether to rotate visually with parent
Grid\[cq]s camera_rotation (bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]shader\f[R]: 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.
- \f[V]texture\f[R] \f[I](read-only)\f[R]: Texture used for tile
rendering (read-only).
- \f[V]uniforms\f[R] \f[I](read-only)\f[R]: 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.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
Invisible objects are not rendered or clickable.
- \f[V]w\f[R]: visible widget width - \f[V]x\f[R]: top-left corner
X-coordinate - \f[V]y\f[R]: top-left corner Y-coordinate -
\f[V]z_index\f[R]: Z-order for rendering (lower values rendered first).
- \f[V]zoom\f[R]: Zoom level for rendering.
.PP
\f[B]Methods:\f[R]
.SS \f[V]animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode=\[aq]replace\[aq]) -> Animation\f[R]
.PP
Create and start an animation on this drawable\[cq]s property.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]property\f[R]: Name of the property to
animate (e.g., `x', `fill_color', `opacity') - \f[V]target\f[R]: Target
value - type depends on property (float, tuple for color/vector, etc.)
- \f[V]duration\f[R]: Animation duration in seconds - \f[V]easing\f[R]:
Easing function: Easing enum value, string name, or None for linear -
\f[V]delta\f[R]: If True, target is relative to current value; if False,
target is absolute - \f[V]loop\f[R]: If True, animation repeats from
start when it reaches the end (default False) - \f[V]callback\f[R]:
Optional callable invoked when animation completes (not called for
looping animations) - \f[V]conflict_mode\f[R]: `replace' (default),
`queue', or `error' if property already animating
.PP
\f[B]Returns:\f[R] Animation object for monitoring progress
.PP
\f[B]Raises:\f[R] ValueError: If property name is not valid for this
drawable type This is a convenience method that creates an Animation,
starts it, and adds it to the AnimationManager.
.SS \f[V]move(dx, dy) or (delta) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels (or use
delta) - \f[V]dy\f[R]: Vertical offset in pixels (or use delta) -
\f[V]delta\f[R]: Offset as tuple, list, or Vector: (dx, dy)
.SS \f[V]realign() -> None\f[R]
.PP
Reapply alignment relative to parent, useful for responsive layouts.
.PP
Note: Call this to recalculate position after parent changes size.
For elements with align=None, this has no effect.
.SS \f[V]resize(width, height) or (size) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels (or use
size) - \f[V]height\f[R]: New height in pixels (or use size) -
\f[V]size\f[R]: Size as tuple, list, or Vector: (width, height)
.SS HeightMap
.PP
HeightMap(size: tuple[int, int], fill: float = 0.0)
.PP
A 2D grid of float values for procedural generation.
.PP
HeightMap is the universal canvas for procedural generation.
It stores float values that can be manipulated, combined, and applied to
Grid and Layer objects.
.PP
Args: size: (width, height) dimensions of the heightmap.
Immutable after creation.
fill: Initial value for all cells.
Default 0.0.
.PP
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()
.PP
\f[B]Properties:\f[R] - \f[V]size\f[R] \f[I](read-only)\f[R]: Dimensions
(width, height) of the heightmap.
Read-only.
.PP
\f[B]Methods:\f[R]
.SS \f[V]add(other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap\f[R]
.PP
Add another heightmap\[cq]s values to this one in the specified region.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: HeightMap to add values from -
\f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0)) -
\f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]add_bsp(bsp: BSP, *, pos=None, select: str = \[aq]leaves\[aq], nodes: list = None, shrink: int = 0, value: float = 1.0) -> HeightMap\f[R]
.PP
Add BSP node regions to heightmap.
More efficient than creating intermediate HeightMap.
.PP
\f[B]Arguments:\f[R] - \f[V]bsp\f[R]: BSP tree to sample from -
\f[V]pos\f[R]: Where BSP origin maps to in HeightMap (default:
origin-relative like to_heightmap) - \f[V]select\f[R]: `leaves', `all',
or `internal' (default: `leaves') - \f[V]nodes\f[R]: Override: specific
BSPNodes only (default: None) - \f[V]shrink\f[R]: Pixels to shrink from
node bounds (default: 0) - \f[V]value\f[R]: Value to add inside regions
(default: 1.0)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]add_constant(value: float, *, pos=None, size=None) -> HeightMap\f[R]
.PP
Add a constant value to cells in region.
.PP
\f[B]Arguments:\f[R] - \f[V]value\f[R]: The value to add to each cell -
\f[V]pos\f[R]: Region start (x, y) in destination (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: remaining space)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]add_hill(center, radius: float, height: float) -> HeightMap\f[R]
.PP
Add a smooth hill at the specified position.
.PP
\f[B]Arguments:\f[R] - \f[V]center\f[R]: Center position as (x, y)
tuple, list, or Vector - \f[V]radius\f[R]: Radius of the hill in cells -
\f[V]height\f[R]: Height of the hill peak
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]add_noise(source: NoiseSource, world_origin: tuple = (0.0, 0.0), world_size: tuple = None, mode: str = \[aq]fbm\[aq], octaves: int = 4, scale: float = 1.0) -> HeightMap\f[R]
.PP
Sample noise and add to current values.
More efficient than creating intermediate HeightMap.
.PP
\f[B]Arguments:\f[R] - \f[V]source\f[R]: 2D NoiseSource to sample from -
\f[V]world_origin\f[R]: World coordinates of top-left (default: (0, 0))
- \f[V]world_size\f[R]: World area to sample (default: HeightMap size) -
\f[V]mode\f[R]: `flat', `fbm', or `turbulence' (default: `fbm') -
\f[V]octaves\f[R]: Octaves for fbm/turbulence (default: 4) -
\f[V]scale\f[R]: Multiplier for sampled values (default: 1.0)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]add_voronoi(num_points: int, coefficients: tuple = (1.0, -0.5), seed: int = None) -> HeightMap\f[R]
.PP
Add Voronoi-based terrain features.
.PP
\f[B]Arguments:\f[R] - \f[V]num_points\f[R]: Number of Voronoi seed
points - \f[V]coefficients\f[R]: Coefficients for distance calculations
(default: (1.0, -0.5)) - \f[V]seed\f[R]: Random seed (None for random)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]clamp(min: float = 0.0, max: float = 1.0, *, pos=None, size=None) -> HeightMap\f[R]
.PP
Clamp values in region to the specified range.
.PP
\f[B]Arguments:\f[R] - \f[V]min\f[R]: Minimum value (default 0.0) -
\f[V]max\f[R]: Maximum value (default 1.0) - \f[V]pos\f[R]: Region start
(x, y) in destination (default: (0, 0)) - \f[V]size\f[R]: Region (width,
height) (default: remaining space)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]clear() -> HeightMap\f[R]
.PP
Set all cells to 0.0.
Equivalent to fill(0.0).
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]copy_from(other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap\f[R]
.PP
Copy values from another heightmap into the specified region.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: HeightMap to copy from -
\f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0)) -
\f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]count_in_range(range: tuple[float, float]) -> int\f[R]
.PP
Count cells with values in the specified range (inclusive).
.PP
\f[B]Arguments:\f[R] - \f[V]range\f[R]: Value range as (min, max) tuple
or list
.PP
\f[B]Returns:\f[R] int: Number of cells with values in range
.PP
\f[B]Raises:\f[R] ValueError: min > max
.SS \f[V]dig_bezier(points: tuple, start_radius: float, end_radius: float, start_height: float, end_height: float) -> HeightMap\f[R]
.PP
Construct a canal along a cubic Bezier curve with specified heights.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]points\f[R]: Four control points as
((x0,y0), (x1,y1), (x2,y2), (x3,y3)) - \f[V]start_radius\f[R]: Radius at
start of path - \f[V]end_radius\f[R]: Radius at end of path -
\f[V]start_height\f[R]: Target height at start of path -
\f[V]end_height\f[R]: Target height at end of path
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining Only lowers
cells; cells below target height are unchanged
.SS \f[V]dig_hill(center, radius: float, target_height: float) -> HeightMap\f[R]
.PP
Construct a pit or crater with the specified center height.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]center\f[R]: Center position as (x, y)
tuple, list, or Vector - \f[V]radius\f[R]: Radius of the crater in cells
- \f[V]target_height\f[R]: Height at the center of the pit
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining Only lowers
cells; cells below target_height are unchanged
.SS \f[V]fill(value: float, *, pos=None, size=None) -> HeightMap\f[R]
.PP
Set cells in region to the specified value.
.PP
\f[B]Arguments:\f[R] - \f[V]value\f[R]: The value to set -
\f[V]pos\f[R]: Region start (x, y) in destination (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) to fill (default: remaining
space)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]get(x, y) or (pos) -> float\f[R]
.PP
Get the height value at integer coordinates.
.PP
\f[B]Returns:\f[R] float: Height value at that position
.PP
\f[B]Raises:\f[R] IndexError: Position is out of bounds
.SS \f[V]get_interpolated(x, y) or (pos) -> float\f[R]
.PP
Get interpolated height value at non-integer coordinates.
.PP
\f[B]Returns:\f[R] float: Bilinearly interpolated height value
.SS \f[V]get_normal(x, y, water_level=0.0) or (pos, water_level=0.0) -> tuple[float, float, float]\f[R]
.PP
Get the normal vector at given coordinates for lighting calculations.
.PP
\f[B]Arguments:\f[R] - \f[V]water_level\f[R]: Water level below which
terrain is considered flat (default 0.0)
.PP
\f[B]Returns:\f[R] tuple[float, float, float]: Normal vector (nx, ny,
nz)
.SS \f[V]get_slope(x, y) or (pos) -> float\f[R]
.PP
Get the slope at integer coordinates, from 0 (flat) to pi/2 (vertical).
.PP
\f[B]Returns:\f[R] float: Slope angle in radians (0 to pi/2)
.PP
\f[B]Raises:\f[R] IndexError: Position is out of bounds
.SS \f[V]inverse() -> HeightMap\f[R]
.PP
Return NEW HeightMap with (1.0 - value) for each cell.
.PP
\f[B]Returns:\f[R] HeightMap: New inverted HeightMap (original is
unchanged)
.SS \f[V]lerp(other: HeightMap, t: float, *, pos=None, source_pos=None, size=None) -> HeightMap\f[R]
.PP
Linear interpolation between this and another heightmap in the specified
region.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: HeightMap to interpolate towards
- \f[V]t\f[R]: Interpolation factor (0.0 = this, 1.0 = other) -
\f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0)) -
\f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]max(other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap\f[R]
.PP
Set each cell in region to the maximum of this and another heightmap.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: HeightMap to compare with -
\f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0)) -
\f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]mid_point_displacement(roughness: float = 0.5, seed: int = None) -> HeightMap\f[R]
.PP
Generate terrain using midpoint displacement algorithm (diamond-square).
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]roughness\f[R]: Controls terrain roughness
(0.0-1.0, default 0.5) - \f[V]seed\f[R]: Random seed (None for random)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining Works best with
power-of-2+1 dimensions (e.g., 65x65, 129x129)
.SS \f[V]min(other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap\f[R]
.PP
Set each cell in region to the minimum of this and another heightmap.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: HeightMap to compare with -
\f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0)) -
\f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]min_max() -> tuple[float, float]\f[R]
.PP
Get the minimum and maximum height values in the map.
.PP
\f[B]Returns:\f[R] tuple[float, float]: (min_value, max_value)
.SS \f[V]multiply(other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap\f[R]
.PP
Multiply this heightmap by another in the specified region (useful for
masking).
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: HeightMap to multiply by -
\f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0)) -
\f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]multiply_bsp(bsp: BSP, *, pos=None, select: str = \[aq]leaves\[aq], nodes: list = None, shrink: int = 0, value: float = 1.0) -> HeightMap\f[R]
.PP
Multiply by BSP regions.
Effectively masks the heightmap to node interiors.
.PP
\f[B]Arguments:\f[R] - \f[V]bsp\f[R]: BSP tree to sample from -
\f[V]pos\f[R]: Where BSP origin maps to in HeightMap (default:
origin-relative like to_heightmap) - \f[V]select\f[R]: `leaves', `all',
or `internal' (default: `leaves') - \f[V]nodes\f[R]: Override: specific
BSPNodes only (default: None) - \f[V]shrink\f[R]: Pixels to shrink from
node bounds (default: 0) - \f[V]value\f[R]: Value to multiply inside
regions (default: 1.0)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]multiply_noise(source: NoiseSource, world_origin: tuple = (0.0, 0.0), world_size: tuple = None, mode: str = \[aq]fbm\[aq], octaves: int = 4, scale: float = 1.0) -> HeightMap\f[R]
.PP
Sample noise and multiply with current values.
Useful for applying noise-based masks.
.PP
\f[B]Arguments:\f[R] - \f[V]source\f[R]: 2D NoiseSource to sample from -
\f[V]world_origin\f[R]: World coordinates of top-left (default: (0, 0))
- \f[V]world_size\f[R]: World area to sample (default: HeightMap size) -
\f[V]mode\f[R]: `flat', `fbm', or `turbulence' (default: `fbm') -
\f[V]octaves\f[R]: Octaves for fbm/turbulence (default: 4) -
\f[V]scale\f[R]: Multiplier for sampled values (default: 1.0)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]normalize(min: float = 0.0, max: float = 1.0, *, pos=None, size=None) -> HeightMap\f[R]
.PP
Linearly rescale values in region.
Current min becomes new min, current max becomes new max.
.PP
\f[B]Arguments:\f[R] - \f[V]min\f[R]: Target minimum value (default 0.0)
- \f[V]max\f[R]: Target maximum value (default 1.0) - \f[V]pos\f[R]:
Region start (x, y) in destination (default: (0, 0)) - \f[V]size\f[R]:
Region (width, height) (default: remaining space)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]rain_erosion(drops: int, erosion: float = 0.1, sedimentation: float = 0.05, seed: int = None) -> HeightMap\f[R]
.PP
Simulate rain erosion on the terrain.
.PP
\f[B]Arguments:\f[R] - \f[V]drops\f[R]: Number of rain drops to simulate
- \f[V]erosion\f[R]: Erosion coefficient (default 0.1) -
\f[V]sedimentation\f[R]: Sedimentation coefficient (default 0.05) -
\f[V]seed\f[R]: Random seed (None for random)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]scale(factor: float, *, pos=None, size=None) -> HeightMap\f[R]
.PP
Multiply cells in region by a factor.
.PP
\f[B]Arguments:\f[R] - \f[V]factor\f[R]: The multiplier for each cell -
\f[V]pos\f[R]: Region start (x, y) in destination (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: remaining space)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]smooth(iterations: int = 1) -> HeightMap\f[R]
.PP
Smooth the heightmap by averaging neighboring cells.
.PP
\f[B]Arguments:\f[R] - \f[V]iterations\f[R]: Number of smoothing passes
(default 1)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]sparse_kernel(weights: dict[tuple[int, int], float]) -> HeightMap\f[R]
.PP
Apply sparse convolution kernel, returning a NEW HeightMap with results.
.PP
\f[B]Arguments:\f[R] - \f[V]weights\f[R]: Dict mapping (dx, dy) offsets
to weight values
.PP
\f[B]Returns:\f[R] HeightMap: new heightmap with convolution result
.SS \f[V]sparse_kernel_from(source: HeightMap, weights: dict[tuple[int, int], float]) -> None\f[R]
.PP
Apply sparse convolution from source heightmap into self (for reusing
destination buffers).
.PP
\f[B]Arguments:\f[R] - \f[V]source\f[R]: Source HeightMap to convolve
from - \f[V]weights\f[R]: Dict mapping (dx, dy) offsets to weight values
.PP
\f[B]Returns:\f[R] None
.SS \f[V]subtract(other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap\f[R]
.PP
Subtract another heightmap\[cq]s values from this one in the specified
region.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: HeightMap to subtract values
from - \f[V]pos\f[R]: Destination start (x, y) in self (default: (0, 0))
- \f[V]source_pos\f[R]: Source start (x, y) in other (default: (0, 0)) -
\f[V]size\f[R]: Region (width, height) (default: max overlapping area)
.PP
\f[B]Returns:\f[R] HeightMap: self, for method chaining
.SS \f[V]threshold(range: tuple[float, float]) -> HeightMap\f[R]
.PP
Return NEW HeightMap with original values where in range, 0.0 elsewhere.
.PP
\f[B]Arguments:\f[R] - \f[V]range\f[R]: Value range as (min, max) tuple
or list, inclusive
.PP
\f[B]Returns:\f[R] HeightMap: New HeightMap (original is unchanged)
.PP
\f[B]Raises:\f[R] ValueError: min > max
.SS \f[V]threshold_binary(range: tuple[float, float], value: float = 1.0) -> HeightMap\f[R]
.PP
Return NEW HeightMap with uniform value where in range, 0.0 elsewhere.
.PP
\f[B]Arguments:\f[R] - \f[V]range\f[R]: Value range as (min, max) tuple
or list, inclusive - \f[V]value\f[R]: Value to set for cells in range
(default 1.0)
.PP
\f[B]Returns:\f[R] HeightMap: New HeightMap (original is unchanged)
.PP
\f[B]Raises:\f[R] ValueError: min > max
.SS Heuristic
.PP
\f[I]Inherits from: IntEnum\f[R]
.PP
Built-in A* heuristic function selector.
.PP
Values: EUCLIDEAN: sqrt((dx)\[ha]2 + (dy)\[ha]2).
Admissible, default.
MANHATTAN: |dx| + |dy|.
Admissible on 4-connected grids.
CHEBYSHEV: max(|dx|, |dy|).
Admissible on 8-connected (diag=1).
DIAGONAL: Octile distance.
Admissible on 8-connected (diag=sqrt(2)).
ZERO: Always returns 0.
A* degenerates to Dijkstra.
.PP
\f[B]Properties:\f[R] - \f[V]denominator\f[R]: the denominator of a
rational number in lowest terms - \f[V]imag\f[R]: the imaginary part of
a complex number - \f[V]numerator\f[R]: the numerator of a rational
number in lowest terms - \f[V]real\f[R]: the real part of a complex
number
.PP
\f[B]Methods:\f[R]
.SS \f[V]as_integer_ratio(...)\f[R]
.PP
Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10,
1) >>> (0).as_integer_ratio() (0, 1)
.SS \f[V]bit_count(...)\f[R]
.PP
Number of ones in the binary representation of the absolute value of
self.
Also known as the population count.
>>> bin(13) `0b1101' >>> (13).bit_count() 3
.SS \f[V]bit_length(...)\f[R]
.PP
Number of bits necessary to represent self in binary.
>>> bin(37) `0b100101' >>> (37).bit_length() 6
.SS \f[V]conjugate(...)\f[R]
.PP
Returns self, the complex conjugate of any int.
.SS \f[V]from_bytes(...)\f[R]
.PP
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert.
The argument must either support the buffer protocol or be an iterable
object producing bytes.
Bytes and bytearray are examples of built-in objects that support the
buffer protocol.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Indicates whether two\[cq]s complement is used to represent the
integer.
.SS \f[V]is_integer(...)\f[R]
.PP
Returns True.
Exists for duck type compatibility with float.is_integer.
.SS \f[V]to_bytes(...)\f[R]
.PP
Return an array of bytes representing an integer.
length Length of bytes object to use.
An OverflowError is raised if the integer is not representable with the
given number of bytes.
Default is length 1.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Determines whether two\[cq]s complement is used to represent the
integer.
If signed is False and a negative integer is given, an OverflowError is
raised.
.SS InputState
.PP
\f[I]Inherits from: IntEnum\f[R]
.PP
Enum representing input event states (pressed/released).
.PP
Values: PRESSED: Key or button was pressed RELEASED: Key or button was
released
.PP
\f[B]Properties:\f[R] - \f[V]denominator\f[R]: the denominator of a
rational number in lowest terms - \f[V]imag\f[R]: the imaginary part of
a complex number - \f[V]numerator\f[R]: the numerator of a rational
number in lowest terms - \f[V]real\f[R]: the real part of a complex
number
.PP
\f[B]Methods:\f[R]
.SS \f[V]as_integer_ratio(...)\f[R]
.PP
Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10,
1) >>> (0).as_integer_ratio() (0, 1)
.SS \f[V]bit_count(...)\f[R]
.PP
Number of ones in the binary representation of the absolute value of
self.
Also known as the population count.
>>> bin(13) `0b1101' >>> (13).bit_count() 3
.SS \f[V]bit_length(...)\f[R]
.PP
Number of bits necessary to represent self in binary.
>>> bin(37) `0b100101' >>> (37).bit_length() 6
.SS \f[V]conjugate(...)\f[R]
.PP
Returns self, the complex conjugate of any int.
.SS \f[V]from_bytes(...)\f[R]
.PP
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert.
The argument must either support the buffer protocol or be an iterable
object producing bytes.
Bytes and bytearray are examples of built-in objects that support the
buffer protocol.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Indicates whether two\[cq]s complement is used to represent the
integer.
.SS \f[V]is_integer(...)\f[R]
.PP
Returns True.
Exists for duck type compatibility with float.is_integer.
.SS \f[V]to_bytes(...)\f[R]
.PP
Return an array of bytes representing an integer.
length Length of bytes object to use.
An OverflowError is raised if the integer is not representable with the
given number of bytes.
Default is length 1.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Determines whether two\[cq]s complement is used to represent the
integer.
If signed is False and a negative integer is given, an OverflowError is
raised.
.SS Key
.PP
\f[I]Inherits from: IntEnum\f[R]
.PP
Enum representing keyboard keys.
.PP
Values map to SFML\[cq]s sf::Keyboard::Key enum.
.PP
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.
.PP
\f[B]Properties:\f[R] - \f[V]denominator\f[R]: the denominator of a
rational number in lowest terms - \f[V]imag\f[R]: the imaginary part of
a complex number - \f[V]numerator\f[R]: the numerator of a rational
number in lowest terms - \f[V]real\f[R]: the real part of a complex
number
.PP
\f[B]Methods:\f[R]
.SS \f[V]as_integer_ratio(...)\f[R]
.PP
Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10,
1) >>> (0).as_integer_ratio() (0, 1)
.SS \f[V]bit_count(...)\f[R]
.PP
Number of ones in the binary representation of the absolute value of
self.
Also known as the population count.
>>> bin(13) `0b1101' >>> (13).bit_count() 3
.SS \f[V]bit_length(...)\f[R]
.PP
Number of bits necessary to represent self in binary.
>>> bin(37) `0b100101' >>> (37).bit_length() 6
.SS \f[V]conjugate(...)\f[R]
.PP
Returns self, the complex conjugate of any int.
.SS \f[V]from_bytes(...)\f[R]
.PP
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert.
The argument must either support the buffer protocol or be an iterable
object producing bytes.
Bytes and bytearray are examples of built-in objects that support the
buffer protocol.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Indicates whether two\[cq]s complement is used to represent the
integer.
.SS \f[V]is_integer(...)\f[R]
.PP
Returns True.
Exists for duck type compatibility with float.is_integer.
.SS \f[V]to_bytes(...)\f[R]
.PP
Return an array of bytes representing an integer.
length Length of bytes object to use.
An OverflowError is raised if the integer is not representable with the
given number of bytes.
Default is length 1.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Determines whether two\[cq]s complement is used to represent the
integer.
If signed is False and a negative integer is given, an OverflowError is
raised.
.SS Keyboard
.PP
Keyboard state singleton for checking modifier keys
.PP
\f[B]Properties:\f[R] - \f[V]alt\f[R] \f[I](read-only)\f[R]: True if
either Alt key is currently pressed (read-only).
- \f[V]ctrl\f[R] \f[I](read-only)\f[R]: True if either Control key is
currently pressed (read-only).
- \f[V]shift\f[R] \f[I](read-only)\f[R]: True if either Shift key is
currently pressed (read-only).
- \f[V]system\f[R] \f[I](read-only)\f[R]: True if either System key
(Win/Cmd) is currently pressed (read-only).
.PP
\f[B]Methods:\f[R]
.SS LdtkProject
.PP
LdtkProject(path: str)
.PP
Load an LDtk project file (.ldtk).
.PP
Parses the project and provides access to tilesets, auto-rule sets,
levels, and enum definitions.
.PP
Args: path: Path to the .ldtk project file.
.PP
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.
.PP
Example: proj = mcrfpy.LdtkProject(`dungeon.ldtk') ts =
proj.tileset(`Dungeon_Tiles') rs = proj.ruleset(`Walls') level =
proj.level(`Level_0')
.PP
\f[B]Properties:\f[R] - \f[V]enums\f[R] \f[I](read-only)\f[R]: Enum
definitions from the project as a list of dicts (read-only).
- \f[V]level_names\f[R] \f[I](read-only)\f[R]: List of level identifier
names (list[str], read-only).
- \f[V]ruleset_names\f[R] \f[I](read-only)\f[R]: List of rule set /
layer names (list[str], read-only).
- \f[V]tileset_names\f[R] \f[I](read-only)\f[R]: List of tileset
identifier names (list[str], read-only).
- \f[V]version\f[R] \f[I](read-only)\f[R]: LDtk JSON format version
string (str, read-only).
.PP
\f[B]Methods:\f[R]
.SS \f[V]level(name: str) -> dict\f[R]
.PP
Get level data by name.
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Level identifier from the LDtk
project
.PP
\f[B]Returns:\f[R] Dict with name, dimensions, world position, and layer
data.
.PP
\f[B]Raises:\f[R] KeyError: If no level with the given name exists
.SS \f[V]ruleset(name: str) -> AutoRuleSet\f[R]
.PP
Get an auto-rule set by layer name.
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Layer identifier from the LDtk
project
.PP
\f[B]Returns:\f[R] An AutoRuleSet for resolving IntGrid data to sprite
tiles.
.PP
\f[B]Raises:\f[R] KeyError: If no ruleset with the given name exists
.SS \f[V]tileset(name: str) -> TileSetFile\f[R]
.PP
Get a tileset by name.
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Tileset identifier from the LDtk
project
.PP
\f[B]Returns:\f[R] A TileSetFile object for texture creation and tile
metadata.
.PP
\f[B]Raises:\f[R] KeyError: If no tileset with the given name exists
.SS Line
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Line(start=None, end=None, thickness=1.0, color=None, **kwargs)
.PP
A line UI element for drawing straight lines between two points.
.PP
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
.PP
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)
.PP
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
.PP
\f[B]Properties:\f[R] - \f[V]align\f[R]: 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.
- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]color\f[R]: Line color as a Color object.
- \f[V]end\f[R]: Ending point of the line as a Vector.
- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
in screen coordinates.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
position (read-only).
Calculates absolute position by walking up the parent chain.
- \f[V]grid_pos\f[R]: Position in grid tile coordinates (only when
parent is Grid) - \f[V]grid_size\f[R]: Size in grid tile coordinates
(only when parent is Grid) - \f[V]horiz_margin\f[R]: Horizontal margin
override (float, 0 = use general margin).
Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER,
CENTER).
- \f[V]hovered\f[R] \f[I](read-only)\f[R]: Whether mouse is currently
over this element (read-only).
Updated automatically by the engine during mouse movement.
- \f[V]margin\f[R]: General margin from edge when aligned (float).
Applied to both horizontal and vertical edges unless overridden.
Invalid for CENTER alignment (raises ValueError).
- \f[V]name\f[R]: Name for finding this element.
- \f[V]on_click\f[R]: Callable executed when line is clicked.
Function receives (pos: Vector, button: str, action: str).
- \f[V]on_enter\f[R]: Callback for mouse enter events.
Called with (pos: Vector, button: str, action: str) when mouse enters
this element\[cq]s bounds.
- \f[V]on_exit\f[R]: Callback for mouse exit events.
Called with (pos: Vector, button: str, action: str) when mouse leaves
this element\[cq]s bounds.
- \f[V]on_move\f[R]: 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.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]parent\f[R]: 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.
- \f[V]pos\f[R]: Position as a Vector (midpoint of line).
- \f[V]rotate_with_camera\f[R]: Whether to rotate visually with parent
Grid\[cq]s camera_rotation (bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]start\f[R]: Starting point of the line as a Vector.
- \f[V]thickness\f[R]: Line thickness in pixels.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
Invisible objects are not rendered or clickable.
- \f[V]z_index\f[R]: Z-order for rendering (lower values rendered
first).
.PP
\f[B]Methods:\f[R]
.SS \f[V]animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode=\[aq]replace\[aq]) -> Animation\f[R]
.PP
Create and start an animation on this drawable\[cq]s property.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]property\f[R]: Name of the property to
animate (e.g., `x', `fill_color', `opacity') - \f[V]target\f[R]: Target
value - type depends on property (float, tuple for color/vector, etc.)
- \f[V]duration\f[R]: Animation duration in seconds - \f[V]easing\f[R]:
Easing function: Easing enum value, string name, or None for linear -
\f[V]delta\f[R]: If True, target is relative to current value; if False,
target is absolute - \f[V]loop\f[R]: If True, animation repeats from
start when it reaches the end (default False) - \f[V]callback\f[R]:
Optional callable invoked when animation completes (not called for
looping animations) - \f[V]conflict_mode\f[R]: `replace' (default),
`queue', or `error' if property already animating
.PP
\f[B]Returns:\f[R] Animation object for monitoring progress
.PP
\f[B]Raises:\f[R] ValueError: If property name is not valid for this
drawable type This is a convenience method that creates an Animation,
starts it, and adds it to the AnimationManager.
.SS \f[V]move(dx, dy) or (delta) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels (or use
delta) - \f[V]dy\f[R]: Vertical offset in pixels (or use delta) -
\f[V]delta\f[R]: Offset as tuple, list, or Vector: (dx, dy)
.SS \f[V]realign() -> None\f[R]
.PP
Reapply alignment relative to parent, useful for responsive layouts.
.PP
Note: Call this to recalculate position after parent changes size.
For elements with align=None, this has no effect.
.SS \f[V]resize(width, height) or (size) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels (or use
size) - \f[V]height\f[R]: New height in pixels (or use size) -
\f[V]size\f[R]: Size as tuple, list, or Vector: (width, height)
.SS Model3D
.PP
Model3D(path=None)
.PP
A 3D model resource that can be rendered by Entity3D.
.PP
Args: path (str, optional): Path to .glb file to load.
If None, creates empty model.
.PP
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
.PP
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
.PP
\f[B]Properties:\f[R] - \f[V]animation_clips\f[R] \f[I](read-only)\f[R]:
List of animation clip names (read-only) - \f[V]bone_count\f[R]
\f[I](read-only)\f[R]: Number of bones in skeleton (read-only) -
\f[V]bounds\f[R] \f[I](read-only)\f[R]: AABB as ((min_x, min_y, min_z),
(max_x, max_y, max_z)) (read-only) - \f[V]has_skeleton\f[R]
\f[I](read-only)\f[R]: Whether model has skeletal animation data
(read-only) - \f[V]mesh_count\f[R] \f[I](read-only)\f[R]: Number of
submeshes (read-only) - \f[V]name\f[R] \f[I](read-only)\f[R]: Model name
(read-only) - \f[V]triangle_count\f[R] \f[I](read-only)\f[R]: Total
triangle count across all meshes (read-only) - \f[V]vertex_count\f[R]
\f[I](read-only)\f[R]: Total vertex count across all meshes (read-only)
.PP
\f[B]Methods:\f[R]
.SS \f[V]cube(size=1.0) -> Model3D\f[R]
.PP
Create a unit cube centered at origin.
.SS \f[V]plane(width=1.0, depth=1.0, segments=1) -> Model3D\f[R]
.PP
Create a flat plane.
.SS \f[V]sphere(radius=0.5, segments=16, rings=12) -> Model3D\f[R]
.PP
Create a UV sphere.
.SS Mouse
.PP
Mouse state singleton for reading button/position state and controlling
cursor visibility
.PP
\f[B]Properties:\f[R] - \f[V]grabbed\f[R]: Whether the mouse cursor is
confined to the window (default: False).
- \f[V]left\f[R] \f[I](read-only)\f[R]: True if left mouse button is
currently pressed (read-only).
- \f[V]middle\f[R] \f[I](read-only)\f[R]: True if middle mouse button is
currently pressed (read-only).
- \f[V]pos\f[R] \f[I](read-only)\f[R]: Current mouse position as Vector
(read-only).
- \f[V]right\f[R] \f[I](read-only)\f[R]: True if right mouse button is
currently pressed (read-only).
- \f[V]visible\f[R]: Whether the mouse cursor is visible (default:
True).
- \f[V]x\f[R] \f[I](read-only)\f[R]: Current mouse X position in window
coordinates (read-only).
- \f[V]y\f[R] \f[I](read-only)\f[R]: Current mouse Y position in window
coordinates (read-only).
.PP
\f[B]Methods:\f[R]
.SS MouseButton
.PP
\f[I]Inherits from: IntEnum\f[R]
.PP
Enum representing mouse buttons and scroll wheel.
.PP
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
.PP
\f[B]Properties:\f[R] - \f[V]denominator\f[R]: the denominator of a
rational number in lowest terms - \f[V]imag\f[R]: the imaginary part of
a complex number - \f[V]numerator\f[R]: the numerator of a rational
number in lowest terms - \f[V]real\f[R]: the real part of a complex
number
.PP
\f[B]Methods:\f[R]
.SS \f[V]as_integer_ratio(...)\f[R]
.PP
Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10,
1) >>> (0).as_integer_ratio() (0, 1)
.SS \f[V]bit_count(...)\f[R]
.PP
Number of ones in the binary representation of the absolute value of
self.
Also known as the population count.
>>> bin(13) `0b1101' >>> (13).bit_count() 3
.SS \f[V]bit_length(...)\f[R]
.PP
Number of bits necessary to represent self in binary.
>>> bin(37) `0b100101' >>> (37).bit_length() 6
.SS \f[V]conjugate(...)\f[R]
.PP
Returns self, the complex conjugate of any int.
.SS \f[V]from_bytes(...)\f[R]
.PP
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert.
The argument must either support the buffer protocol or be an iterable
object producing bytes.
Bytes and bytearray are examples of built-in objects that support the
buffer protocol.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Indicates whether two\[cq]s complement is used to represent the
integer.
.SS \f[V]is_integer(...)\f[R]
.PP
Returns True.
Exists for duck type compatibility with float.is_integer.
.SS \f[V]to_bytes(...)\f[R]
.PP
Return an array of bytes representing an integer.
length Length of bytes object to use.
An OverflowError is raised if the integer is not representable with the
given number of bytes.
Default is length 1.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Determines whether two\[cq]s complement is used to represent the
integer.
If signed is False and a negative integer is given, an OverflowError is
raised.
.SS Music
.PP
Streaming music object for longer audio tracks
.PP
\f[B]Properties:\f[R] - \f[V]duration\f[R] \f[I](read-only)\f[R]: Total
duration of the music in seconds (read-only).
- \f[V]loop\f[R]: Whether the music loops when it reaches the end.
- \f[V]playing\f[R] \f[I](read-only)\f[R]: True if the music is
currently playing (read-only).
- \f[V]position\f[R]: Current playback position in seconds.
Can be set to seek.
- \f[V]source\f[R] \f[I](read-only)\f[R]: Filename path used to load
this music (read-only).
- \f[V]volume\f[R]: Volume level from 0 (silent) to 100 (full volume).
.PP
\f[B]Methods:\f[R]
.SS \f[V]pause() -> None\f[R]
.PP
Pause the music.
Use play() to resume from the paused position.
.SS \f[V]play() -> None\f[R]
.PP
Start or resume playing the music.
.SS \f[V]stop() -> None\f[R]
.PP
Stop playing and reset to the beginning.
.SS NoiseSource
.PP
NoiseSource(dimensions: int = 2, algorithm: str = `simplex', hurst:
float = 0.5, lacunarity: float = 2.0, seed: int = None)
.PP
A configured noise generator for procedural generation.
.PP
NoiseSource wraps libtcod\[cq]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).
.PP
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.
.PP
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).
.PP
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)
.PP
\f[B]Properties:\f[R] - \f[V]algorithm\f[R] \f[I](read-only)\f[R]: Noise
algorithm name (`simplex', `perlin', or `wavelet').
Read-only.
- \f[V]dimensions\f[R] \f[I](read-only)\f[R]: Number of input dimensions
(1-4).
Read-only.
- \f[V]hurst\f[R] \f[I](read-only)\f[R]: Hurst exponent for
fbm/turbulence.
Read-only.
- \f[V]lacunarity\f[R] \f[I](read-only)\f[R]: Frequency multiplier
between octaves.
Read-only.
- \f[V]seed\f[R] \f[I](read-only)\f[R]: Random seed used (even if
originally None).
Read-only.
.PP
\f[B]Methods:\f[R]
.SS \f[V]fbm(pos: tuple[float, ...], octaves: int = 4) -> float\f[R]
.PP
Get fractal brownian motion value at coordinates.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Position tuple with length
matching dimensions - \f[V]octaves\f[R]: Number of noise octaves to
combine (default: 4)
.PP
\f[B]Returns:\f[R] float: FBM noise value in range [-1.0, 1.0]
.PP
\f[B]Raises:\f[R] ValueError: Position tuple length doesn\[cq]t match
dimensions
.SS \f[V]get(pos: tuple[float, ...]) -> float\f[R]
.PP
Get flat noise value at coordinates.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Position tuple with length
matching dimensions
.PP
\f[B]Returns:\f[R] float: Noise value in range [-1.0, 1.0]
.PP
\f[B]Raises:\f[R] ValueError: Position tuple length doesn\[cq]t match
dimensions
.SS \f[V]sample(size: tuple[int, int], world_origin: tuple[float, float] = (0.0, 0.0), world_size: tuple[float, float] = None, mode: str = \[aq]fbm\[aq], octaves: int = 4) -> HeightMap\f[R]
.PP
Sample noise into a HeightMap for batch processing.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]size\f[R]: Output dimensions in cells as
(width, height) - \f[V]world_origin\f[R]: World coordinates of top-left
corner (default: (0, 0)) - \f[V]world_size\f[R]: World area to sample
(default: same as size) - \f[V]mode\f[R]: Sampling mode: `flat', `fbm',
or `turbulence' (default: `fbm') - \f[V]octaves\f[R]: Octaves for
fbm/turbulence modes (default: 4)
.PP
\f[B]Returns:\f[R] HeightMap: New HeightMap filled with sampled noise
values Requires dimensions=2.
Values are in range [-1.0, 1.0].
.SS \f[V]turbulence(pos: tuple[float, ...], octaves: int = 4) -> float\f[R]
.PP
Get turbulence (absolute fbm) value at coordinates.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Position tuple with length
matching dimensions - \f[V]octaves\f[R]: Number of noise octaves to
combine (default: 4)
.PP
\f[B]Returns:\f[R] float: Turbulence noise value in range [-1.0, 1.0]
.PP
\f[B]Raises:\f[R] ValueError: Position tuple length doesn\[cq]t match
dimensions
.SS Perspective
.PP
\f[I]Inherits from: IntEnum\f[R]
.PP
Enum representing an entity\[cq]s knowledge of a cell.
.PP
Values: UNKNOWN: Never seen (perspective_map value 0) DISCOVERED: Seen
before but not currently visible (value 1) VISIBLE: In current FOV
(value 2)
.PP
\f[B]Properties:\f[R] - \f[V]denominator\f[R]: the denominator of a
rational number in lowest terms - \f[V]imag\f[R]: the imaginary part of
a complex number - \f[V]numerator\f[R]: the numerator of a rational
number in lowest terms - \f[V]real\f[R]: the real part of a complex
number
.PP
\f[B]Methods:\f[R]
.SS \f[V]as_integer_ratio(...)\f[R]
.PP
Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10,
1) >>> (0).as_integer_ratio() (0, 1)
.SS \f[V]bit_count(...)\f[R]
.PP
Number of ones in the binary representation of the absolute value of
self.
Also known as the population count.
>>> bin(13) `0b1101' >>> (13).bit_count() 3
.SS \f[V]bit_length(...)\f[R]
.PP
Number of bits necessary to represent self in binary.
>>> bin(37) `0b100101' >>> (37).bit_length() 6
.SS \f[V]conjugate(...)\f[R]
.PP
Returns self, the complex conjugate of any int.
.SS \f[V]from_bytes(...)\f[R]
.PP
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert.
The argument must either support the buffer protocol or be an iterable
object producing bytes.
Bytes and bytearray are examples of built-in objects that support the
buffer protocol.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Indicates whether two\[cq]s complement is used to represent the
integer.
.SS \f[V]is_integer(...)\f[R]
.PP
Returns True.
Exists for duck type compatibility with float.is_integer.
.SS \f[V]to_bytes(...)\f[R]
.PP
Return an array of bytes representing an integer.
length Length of bytes object to use.
An OverflowError is raised if the integer is not representable with the
given number of bytes.
Default is length 1.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Determines whether two\[cq]s complement is used to represent the
integer.
If signed is False and a negative integer is given, an OverflowError is
raised.
.SS PropertyBinding
.PP
PropertyBinding(target: UIDrawable, property: str)
.PP
A binding that reads a property value from a UI drawable.
.PP
Args: target: The drawable to read the property from property: Name of
the property to read (e.g., `x', `opacity')
.PP
Use this to create dynamic shader uniforms that follow a drawable\[cq]s
properties.
The binding automatically handles cases where the target is destroyed.
.PP
Example: other_frame = mcrfpy.Frame(pos=(100, 100))
frame.uniforms[`offset_x'] = mcrfpy.PropertyBinding(other_frame, `x')
.PP
\f[B]Properties:\f[R] - \f[V]is_valid\f[R] \f[I](read-only)\f[R]: True
if the binding target still exists and property is valid (bool,
read-only).
- \f[V]property\f[R] \f[I](read-only)\f[R]: The property name being read
(str, read-only).
- \f[V]target\f[R] \f[I](read-only)\f[R]: The drawable this binding
reads from (read-only).
- \f[V]value\f[R] \f[I](read-only)\f[R]: Current value of the binding
(float, read-only).
Returns None if invalid.
.PP
\f[B]Methods:\f[R]
.SS Scene
.PP
Scene(name: str)
.PP
Object-oriented scene management with lifecycle callbacks.
.PP
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.
.PP
Args: name: Unique identifier for this scene.
Used for scene transitions.
.PP
Properties: name (str, read-only): Scene\[cq]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).
.PP
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.
.PP
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\[cq]Key: {key}\[cq])
scene.activate() # Switch to this scene
.IP
.nf
\f[C]
# Subclassing for lifecycle:
class GameScene(mcrfpy.Scene):
    def on_enter(self):
        print(\[aq]Game started!\[aq])
    def update(self, dt):
        self.player.move(dt)
\f[R]
.fi
.PP
\f[B]Properties:\f[R] - \f[V]active\f[R] \f[I](read-only)\f[R]: Whether
this scene is currently active (bool, read-only).
Only one scene can be active at a time.
- \f[V]children\f[R] \f[I](read-only)\f[R]: UI element collection for
this scene (UICollection, read-only).
Use to add, remove, or iterate over UI elements.
Changes are reflected immediately.
- \f[V]name\f[R] \f[I](read-only)\f[R]: Scene name (str, read-only).
Unique identifier for this scene.
- \f[V]on_key\f[R]: Keyboard event handler (callable or None).
Function receives (key: Key, action: InputState) for keyboard events.
Set to None to remove the handler.
- \f[V]opacity\f[R]: Scene opacity (0.0-1.0).
Applied to all UI elements during rendering.
- \f[V]pos\f[R]: Scene position offset (Vector).
Applied to all UI elements during rendering.
- \f[V]registered\f[R] \f[I](read-only)\f[R]: Whether this scene is
registered with the game engine (bool, read-only).
Unregistered scenes still exist but won\[cq]t receive lifecycle
callbacks.
- \f[V]visible\f[R]: Scene visibility (bool).
If False, scene is not rendered.
.PP
\f[B]Methods:\f[R]
.SS \f[V]activate(transition: Transition = None, duration: float = None) -> None\f[R]
.PP
Make this the active scene with optional transition effect.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]transition\f[R]: Transition type
(mcrfpy.Transition enum).
Defaults to mcrfpy.default_transition - \f[V]duration\f[R]: Transition
duration in seconds.
Defaults to mcrfpy.default_transition_duration
.PP
\f[B]Returns:\f[R] None Deactivates the current scene and activates this
one.
Lifecycle callbacks (on_exit, on_enter) are triggered.
.SS \f[V]realign() -> None\f[R]
.PP
Recalculate alignment for all children with alignment set.
.PP
Note: Call this after window resize or when game_resolution changes.
For responsive layouts, connect this to on_resize callback.
.SS \f[V]register() -> None\f[R]
.PP
Register this scene with the game engine.
.PP
Note: Makes the scene available for activation and receives lifecycle
callbacks.
If another scene with the same name exists, it will be unregistered
first.
Called automatically by activate() if needed.
.SS \f[V]unregister() -> None\f[R]
.PP
Unregister this scene from the game engine.
.PP
Note: Removes the scene from the engine\[cq]s registry but keeps the
Python object alive.
The scene\[cq]s UI elements and state are preserved.
Call register() to re-add it.
Useful for temporary scenes or scene pooling.
.SS Shader
.PP
Shader(fragment_source: str, dynamic: bool = False)
.PP
A GPU shader program for visual effects.
.PP
Args: fragment_source: GLSL fragment shader source code dynamic: If
True, shader uses time-varying effects and will invalidate parent caches
each frame
.PP
Shaders enable GPU-accelerated visual effects like glow, distortion,
color manipulation, and more.
Assign to drawable.shader to apply.
.PP
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
.PP
Example: shader = mcrfpy.Shader(\[cq]\[cq]\[cq] uniform sampler2D
texture; uniform float time; void main() { vec2 uv = gl_TexCoord[0].xy;
vec4 color = texture2D(texture, uv); color.rgb \f[I]= 0.5 + 0.5 \f[R]
sin(time); gl_FragColor = color; } \[cq]\[cq]\[cq], dynamic=True)
frame.shader = shader
.PP
\f[B]Properties:\f[R] - \f[V]dynamic\f[R]: Whether this shader uses
time-varying effects (bool).
Dynamic shaders invalidate parent caches each frame.
- \f[V]is_valid\f[R] \f[I](read-only)\f[R]: True if the shader compiled
successfully (bool, read-only).
- \f[V]source\f[R] \f[I](read-only)\f[R]: The GLSL fragment shader
source code (str, read-only).
.PP
\f[B]Methods:\f[R]
.SS \f[V]set_uniform(name: str, value: float|tuple) -> None\f[R]
.PP
Set a custom uniform value on this shader.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Uniform variable name in the
shader - \f[V]value\f[R]: Float, vec2 (2-tuple), vec3 (3-tuple), or vec4
(4-tuple)
.PP
\f[B]Raises:\f[R] ValueError: If uniform type cannot be determined
Engine uniforms (time, resolution, etc.)
are set automatically
.SS Sound
.PP
Sound(source)
.PP
Sound effect object for short audio clips.
.PP
Args: source: Filename string or SoundBuffer object.
.PP
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.
.PP
\f[B]Properties:\f[R] - \f[V]buffer\f[R] \f[I](read-only)\f[R]: The
SoundBuffer if created from one, else None (read-only).
- \f[V]duration\f[R] \f[I](read-only)\f[R]: Total duration of the sound
in seconds (read-only).
- \f[V]loop\f[R]: Whether the sound loops when it reaches the end.
- \f[V]pitch\f[R]: Playback pitch multiplier (1.0 = normal, >1 = higher,
<1 = lower).
- \f[V]playing\f[R] \f[I](read-only)\f[R]: True if the sound is
currently playing (read-only).
- \f[V]source\f[R] \f[I](read-only)\f[R]: Filename path used to load
this sound (read-only).
- \f[V]volume\f[R]: Volume level from 0 (silent) to 100 (full volume).
.PP
\f[B]Methods:\f[R]
.SS \f[V]pause() -> None\f[R]
.PP
Pause the sound.
Use play() to resume from the paused position.
.SS \f[V]play() -> None\f[R]
.PP
Start or resume playing the sound.
.SS \f[V]play_varied(pitch_range: float = 0.1, volume_range: float = 3.0) -> None\f[R]
.PP
Play with randomized pitch and volume for natural variation.
.PP
\f[B]Arguments:\f[R] - \f[V]pitch_range\f[R]: Random pitch offset range
(default 0.1) - \f[V]volume_range\f[R]: Random volume offset range
(default 3.0)
.SS \f[V]stop() -> None\f[R]
.PP
Stop playing and reset to the beginning.
.SS SoundBuffer
.PP
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)
.PP
Audio sample buffer for procedural audio generation and effects.
.PP
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).
.PP
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.
.PP
\f[B]Properties:\f[R] - \f[V]channels\f[R] \f[I](read-only)\f[R]: Number
of audio channels (read-only).
- \f[V]duration\f[R] \f[I](read-only)\f[R]: Total duration in seconds
(read-only).
- \f[V]sample_count\f[R] \f[I](read-only)\f[R]: Total number of samples
(read-only).
- \f[V]sample_rate\f[R] \f[I](read-only)\f[R]: Sample rate in Hz
(read-only).
- \f[V]sfxr_params\f[R] \f[I](read-only)\f[R]: Dict of sfxr parameters
if sfxr-generated, else None (read-only).
.PP
\f[B]Methods:\f[R]
.SS \f[V]bit_crush(bits: int, rate_divisor: int) -> SoundBuffer\f[R]
.PP
Reduce bit depth and sample rate for lo-fi effect.
.SS \f[V]concat(buffers: list[SoundBuffer], overlap: float = 0.0) -> SoundBuffer\f[R]
.PP
Concatenate multiple SoundBuffers with optional crossfade overlap.
.PP
\f[B]Arguments:\f[R] - \f[V]buffers\f[R]: List of SoundBuffer objects to
concatenate - \f[V]overlap\f[R]: Crossfade overlap duration in seconds
.SS \f[V]distortion(drive: float) -> SoundBuffer\f[R]
.PP
Apply tanh soft clipping distortion.
.SS \f[V]echo(delay_ms: float, feedback: float, wet: float) -> SoundBuffer\f[R]
.PP
Apply echo effect with delay, feedback, and wet/dry mix.
.SS \f[V]from_samples(data: bytes, channels: int, sample_rate: int) -> SoundBuffer\f[R]
.PP
Create a SoundBuffer from raw int16 PCM sample data.
.PP
\f[B]Arguments:\f[R] - \f[V]data\f[R]: Raw PCM data as bytes (int16
little-endian) - \f[V]channels\f[R]: Number of audio channels (1=mono,
2=stereo) - \f[V]sample_rate\f[R]: Sample rate in Hz (e.g.\ 44100)
.SS \f[V]gain(factor: float) -> SoundBuffer\f[R]
.PP
Multiply all samples by a scalar factor.
Use for volume/amplitude control before mixing.
.PP
\f[B]Arguments:\f[R] - \f[V]factor\f[R]: Amplitude multiplier (0.5 =
half volume, 2.0 = double).
Clamps to int16 range.
.SS \f[V]high_pass(cutoff_hz: float) -> SoundBuffer\f[R]
.PP
Apply single-pole IIR high-pass filter.
.SS \f[V]low_pass(cutoff_hz: float) -> SoundBuffer\f[R]
.PP
Apply single-pole IIR low-pass filter.
.SS \f[V]mix(buffers: list[SoundBuffer]) -> SoundBuffer\f[R]
.PP
Mix multiple SoundBuffers together (additive, clamped).
.PP
\f[B]Arguments:\f[R] - \f[V]buffers\f[R]: List of SoundBuffer objects to
mix
.SS \f[V]normalize() -> SoundBuffer\f[R]
.PP
Scale samples to 95%% of int16 max.
.SS \f[V]pitch_shift(factor: float) -> SoundBuffer\f[R]
.PP
Resample to shift pitch.
factor>1 = higher+shorter.
.SS \f[V]reverb(room_size: float, damping: float, wet: float) -> SoundBuffer\f[R]
.PP
Apply simplified Freeverb-style reverb.
.SS \f[V]reverse() -> SoundBuffer\f[R]
.PP
Reverse the sample order.
.SS \f[V]sfxr(preset: str = None, seed: int = None, **params) -> SoundBuffer\f[R]
.PP
Generate retro sound effects using sfxr synthesis.
.PP
\f[B]Arguments:\f[R] - \f[V]preset\f[R]: One of: coin, laser, explosion,
powerup, hurt, jump, blip - \f[V]seed\f[R]: Random seed for
deterministic generation
.PP
\f[B]Returns:\f[R] SoundBuffer with sfxr_params set for later mutation
.SS \f[V]sfxr_mutate(amount: float = 0.05, seed: int = None) -> SoundBuffer\f[R]
.PP
Jitter sfxr params and re-synthesize.
Only works on sfxr-generated buffers.
.SS \f[V]slice(start: float, end: float) -> SoundBuffer\f[R]
.PP
Extract a time range in seconds.
.SS \f[V]tone(frequency: float, duration: float, waveform: str = \[aq]sine\[aq], ...) -> SoundBuffer\f[R]
.PP
Generate a tone with optional ADSR envelope.
.PP
\f[B]Arguments:\f[R] - \f[V]frequency\f[R]: Frequency in Hz -
\f[V]duration\f[R]: Duration in seconds - \f[V]waveform\f[R]: One of:
sine, square, saw, triangle, noise - \f[V]attack\f[R]: ADSR attack time
in seconds (default 0.01) - \f[V]decay\f[R]: ADSR decay time in seconds
(default 0.0) - \f[V]sustain\f[R]: ADSR sustain level 0.0-1.0 (default
1.0) - \f[V]release\f[R]: ADSR release time in seconds (default 0.01)
.SS Sprite
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Sprite(pos=None, texture=None, sprite_index=0, **kwargs)
.PP
A sprite UI element that displays a texture or portion of a texture
atlas.
.PP
Args: pos (tuple, optional): Position as (x, y) tuple.
Default: (0, 0) texture (Texture, optional): Texture object to display.
Default: default texture sprite_index (int, optional): Index into
texture atlas.
Default: 0
.PP
Keyword Args: scale (float): Uniform scale factor.
Default: 1.0 scale_x (float): Horizontal scale factor.
Default: 1.0 scale_y (float): Vertical scale factor.
Default: 1.0 click (callable): Click event handler.
Default: None visible (bool): Visibility state.
Default: True opacity (float): Opacity (0.0-1.0).
Default: 1.0 z_index (int): Rendering order.
Default: 0 name (str): Element name for finding.
Default: None x (float): X position override.
Default: 0 y (float): Y position override.
Default: 0 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)
.PP
Attributes: x, y (float): Position in pixels pos (Vector): Position as a
Vector object texture (Texture): The texture being displayed
sprite_index (int): Current sprite index in texture atlas scale (float):
Uniform scale factor scale_x, scale_y (float): Individual scale factors
click (callable): Click event handler visible (bool): Visibility state
opacity (float): Opacity value z_index (int): Rendering order name
(str): Element name w, h (float): Read-only computed size based on
texture and scale 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
.PP
\f[B]Properties:\f[R] - \f[V]align\f[R]: 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.
- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
in screen coordinates.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
position (read-only).
Calculates absolute position by walking up the parent chain.
- \f[V]grid_pos\f[R]: Position in grid tile coordinates (only when
parent is Grid) - \f[V]grid_size\f[R]: Size in grid tile coordinates
(only when parent is Grid) - \f[V]horiz_margin\f[R]: Horizontal margin
override (float, 0 = use general margin).
Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER,
CENTER).
- \f[V]hovered\f[R] \f[I](read-only)\f[R]: Whether mouse is currently
over this element (read-only).
Updated automatically by the engine during mouse movement.
- \f[V]margin\f[R]: General margin from edge when aligned (float).
Applied to both horizontal and vertical edges unless overridden.
Invalid for CENTER alignment (raises ValueError).
- \f[V]name\f[R]: Name for finding elements - \f[V]on_click\f[R]:
Callable executed when object is clicked.
Function receives (pos: Vector, button: str, action: str).
- \f[V]on_enter\f[R]: Callback for mouse enter events.
Called with (pos: Vector, button: str, action: str) when mouse enters
this element\[cq]s bounds.
- \f[V]on_exit\f[R]: Callback for mouse exit events.
Called with (pos: Vector, button: str, action: str) when mouse leaves
this element\[cq]s bounds.
- \f[V]on_move\f[R]: 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.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]parent\f[R]: 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.
- \f[V]pos\f[R]: Position as a Vector - \f[V]rotate_with_camera\f[R]:
Whether to rotate visually with parent Grid\[cq]s camera_rotation
(bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]scale\f[R]: Uniform size factor - \f[V]scale_x\f[R]: Horizontal
scale factor - \f[V]scale_y\f[R]: Vertical scale factor -
\f[V]shader\f[R]: 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.
- \f[V]sprite_index\f[R]: Which sprite on the texture is shown -
\f[V]texture\f[R]: Texture object - \f[V]uniforms\f[R]
\f[I](read-only)\f[R]: 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.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
Invisible objects are not rendered or clickable.
- \f[V]x\f[R]: X coordinate of top-left corner - \f[V]y\f[R]: Y
coordinate of top-left corner - \f[V]z_index\f[R]: Z-order for rendering
(lower values rendered first).
Automatically triggers scene resort when changed.
.PP
\f[B]Methods:\f[R]
.SS \f[V]animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode=\[aq]replace\[aq]) -> Animation\f[R]
.PP
Create and start an animation on this drawable\[cq]s property.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]property\f[R]: Name of the property to
animate (e.g., `x', `fill_color', `opacity') - \f[V]target\f[R]: Target
value - type depends on property (float, tuple for color/vector, etc.)
- \f[V]duration\f[R]: Animation duration in seconds - \f[V]easing\f[R]:
Easing function: Easing enum value, string name, or None for linear -
\f[V]delta\f[R]: If True, target is relative to current value; if False,
target is absolute - \f[V]loop\f[R]: If True, animation repeats from
start when it reaches the end (default False) - \f[V]callback\f[R]:
Optional callable invoked when animation completes (not called for
looping animations) - \f[V]conflict_mode\f[R]: `replace' (default),
`queue', or `error' if property already animating
.PP
\f[B]Returns:\f[R] Animation object for monitoring progress
.PP
\f[B]Raises:\f[R] ValueError: If property name is not valid for this
drawable type This is a convenience method that creates an Animation,
starts it, and adds it to the AnimationManager.
.SS \f[V]move(dx, dy) or (delta) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels (or use
delta) - \f[V]dy\f[R]: Vertical offset in pixels (or use delta) -
\f[V]delta\f[R]: Offset as tuple, list, or Vector: (dx, dy)
.SS \f[V]realign() -> None\f[R]
.PP
Reapply alignment relative to parent, useful for responsive layouts.
.PP
Note: Call this to recalculate position after parent changes size.
For elements with align=None, this has no effect.
.SS \f[V]resize(width, height) or (size) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels (or use
size) - \f[V]height\f[R]: New height in pixels (or use size) -
\f[V]size\f[R]: Size as tuple, list, or Vector: (width, height)
.SS Texture
.PP
Texture(filename: str, sprite_width: int = 0, sprite_height: int = 0,
display_size: tuple = None, display_origin: tuple = None)
.PP
A texture atlas for sprites and tiles.
.PP
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.
.PP
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.
.PP
\f[B]Properties:\f[R] - \f[V]display_height\f[R] \f[I](read-only)\f[R]:
Display height of sprite content within each cell (int, read-only).
Defaults to sprite_height.
- \f[V]display_offset_x\f[R] \f[I](read-only)\f[R]: X offset of sprite
content within each cell (int, read-only).
Default 0.
- \f[V]display_offset_y\f[R] \f[I](read-only)\f[R]: Y offset of sprite
content within each cell (int, read-only).
Default 0.
- \f[V]display_width\f[R] \f[I](read-only)\f[R]: Display width of sprite
content within each cell (int, read-only).
Defaults to sprite_width.
- \f[V]sheet_height\f[R] \f[I](read-only)\f[R]: Number of sprite rows in
the texture sheet (int, read-only).
Calculated as texture_height / sprite_height.
- \f[V]sheet_width\f[R] \f[I](read-only)\f[R]: Number of sprite columns
in the texture sheet (int, read-only).
Calculated as texture_width / sprite_width.
- \f[V]source\f[R] \f[I](read-only)\f[R]: Source filename path (str,
read-only).
The path used to load this texture.
- \f[V]sprite_count\f[R] \f[I](read-only)\f[R]: Total number of sprites
in the texture sheet (int, read-only).
Equals sheet_width * sheet_height.
- \f[V]sprite_height\f[R] \f[I](read-only)\f[R]: Height of each sprite
in pixels (int, read-only).
Specified during texture initialization.
- \f[V]sprite_width\f[R] \f[I](read-only)\f[R]: Width of each sprite in
pixels (int, read-only).
Specified during texture initialization.
.PP
\f[B]Methods:\f[R]
.SS \f[V]composite(layers: list[Texture], sprite_width: int, sprite_height: int, name: str = \[aq]<composite>\[aq]) -> Texture\f[R]
.PP
Alpha-composite multiple texture layers into a single texture.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]layers\f[R]: List of Texture objects,
composited bottom-to-top - \f[V]sprite_width\f[R]: Width of each sprite
cell in the result - \f[V]sprite_height\f[R]: Height of each sprite cell
in the result - \f[V]name\f[R]: Optional name for the composite texture
.PP
\f[B]Returns:\f[R] Texture: New texture with all layers composited
.PP
\f[B]Raises:\f[R] ValueError: If layers have different dimensions or
list is empty This is a class method.
Uses Porter-Duff `over' alpha compositing.
.SS \f[V]from_bytes(data: bytes, width: int, height: int, sprite_width: int, sprite_height: int, name: str = \[aq]<generated>\[aq]) -> Texture\f[R]
.PP
Create a Texture from raw RGBA pixel data.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]data\f[R]: Raw RGBA bytes (length must equal
width * height * 4) - \f[V]width\f[R]: Image width in pixels -
\f[V]height\f[R]: Image height in pixels - \f[V]sprite_width\f[R]: Width
of each sprite cell - \f[V]sprite_height\f[R]: Height of each sprite
cell - \f[V]name\f[R]: Optional name for the texture (default: `')
.PP
\f[B]Returns:\f[R] Texture: New texture containing the pixel data
.PP
\f[B]Raises:\f[R] ValueError: If data length does not match width *
height * 4 This is a class method.
Useful for procedurally generated textures.
.SS \f[V]hsl_shift(hue_shift: float, sat_shift: float = 0.0, lit_shift: float = 0.0) -> Texture\f[R]
.PP
Create a new texture with HSL color adjustments applied.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]hue_shift\f[R]: Hue rotation in degrees
[0.0, 360.0) - \f[V]sat_shift\f[R]: Saturation adjustment [-1.0, 1.0]
(default 0.0) - \f[V]lit_shift\f[R]: Lightness adjustment [-1.0, 1.0]
(default 0.0)
.PP
\f[B]Returns:\f[R] Texture: New texture with color-shifted pixels
Preserves alpha channel.
Skips fully transparent pixels.
.SS TileLayer
.PP
TileLayer(z_index=-1, name=None, texture=None, grid_size=None)
.PP
A grid layer that stores sprite indices per cell for tile-based
rendering.
.PP
TileLayers can be created standalone and attached to a Grid via
add_layer() or passed to the Grid constructor\[cq]s layers parameter.
Layers with size (0, 0) automatically resize to match the Grid when
attached.
.PP
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\[cq]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
.PP
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.
.PP
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
.PP
Tile Index Values: -1: No tile (transparent/empty cell) 0+: Index into
the texture\[cq]s sprite atlas (row-major order)
.PP
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)
.PP
\f[B]Properties:\f[R] - \f[V]grid\f[R]: Parent Grid or None.
Setting manages layer association and handles lazy allocation.
- \f[V]grid_size\f[R]: Layer dimensions as (width, height) tuple.
- \f[V]name\f[R] \f[I](read-only)\f[R]: Layer name (str, read-only).
Used for Grid.layer(name) lookup.
- \f[V]texture\f[R]: Texture atlas for tile sprites.
- \f[V]visible\f[R]: Whether the layer is rendered.
- \f[V]z_index\f[R]: Layer z-order.
Negative values render below entities.
.PP
\f[B]Methods:\f[R]
.SS \f[V]apply_ranges(source, ranges) -> TileLayer\f[R]
.PP
Apply multiple tile assignments in a single pass.
.PP
Note:
.PP
\f[B]Returns:\f[R] self for method chaining Later ranges override
earlier ones if overlapping.
Cells not matching any range are left unchanged.
.SS \f[V]apply_threshold(source, range, tile) -> TileLayer\f[R]
.PP
Set tile index for cells where HeightMap value is within range.
.PP
\f[B]Returns:\f[R] self for method chaining
.SS \f[V]at(pos) -> int\f[R]
.PP
at(x, y) -> int Get the tile index at cell position.
Returns -1 if no tile.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Position as (x, y) tuple, list, or
Vector
.SS \f[V]fill(index)\f[R]
.PP
Fill the entire layer with the specified tile index.
.SS \f[V]fill_rect(pos, size, index)\f[R]
.PP
Fill a rectangular region with a tile index.
.SS \f[V]set(pos, index)\f[R]
.PP
Set the tile index at cell position.
Use -1 for no tile.
.PP
\f[B]Arguments:\f[R] - \f[V]pos\f[R]: Position as (x, y) tuple, list, or
Vector - \f[V]index\f[R]: Tile index (-1 for no tile)
.SS TileMapFile
.PP
TileMapFile(path: str)
.PP
Load a Tiled map file (.tmx or .tmj).
.PP
Parses the map and its referenced tilesets, providing access to tile
layers, object layers, and GID resolution.
.PP
Args: path: Path to the .tmx or .tmj map file.
.PP
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.
.PP
Example: tm = mcrfpy.TileMapFile(`map.tmx') data =
tm.tile_layer_data(`Ground') tm.apply_to_tile_layer(my_tile_layer,
`Ground')
.PP
\f[B]Properties:\f[R] - \f[V]height\f[R] \f[I](read-only)\f[R]: Map
height in tiles (int, read-only).
- \f[V]object_layer_names\f[R] \f[I](read-only)\f[R]: List of object
layer names (read-only).
- \f[V]orientation\f[R] \f[I](read-only)\f[R]: Map orientation,
e.g.\ `orthogonal' (str, read-only).
- \f[V]properties\f[R] \f[I](read-only)\f[R]: Custom map properties as a
dict (read-only).
- \f[V]tile_height\f[R] \f[I](read-only)\f[R]: Tile height in pixels
(int, read-only).
- \f[V]tile_layer_names\f[R] \f[I](read-only)\f[R]: List of tile layer
names (read-only).
- \f[V]tile_width\f[R] \f[I](read-only)\f[R]: Tile width in pixels (int,
read-only).
- \f[V]tileset_count\f[R] \f[I](read-only)\f[R]: Number of referenced
tilesets (int, read-only).
- \f[V]width\f[R] \f[I](read-only)\f[R]: Map width in tiles (int,
read-only).
.PP
\f[B]Methods:\f[R]
.SS \f[V]apply_to_tile_layer(tile_layer: TileLayer, layer_name: str, tileset_index: int = 0) -> None\f[R]
.PP
Resolve GIDs and write sprite indices into a TileLayer.
.PP
\f[B]Arguments:\f[R] - \f[V]tile_layer\f[R]: Target TileLayer to write
into - \f[V]layer_name\f[R]: Name of the tile layer in this map -
\f[V]tileset_index\f[R]: Which tileset to resolve GIDs against (default
0)
.SS \f[V]object_layer(name: str) -> list[dict]\f[R]
.PP
Get objects from an object layer as Python dicts.
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Name of the object layer
.PP
\f[B]Returns:\f[R] List of dicts with object properties (id, name, x, y,
width, height, etc.).
.PP
\f[B]Raises:\f[R] KeyError: If no object layer with that name exists
.SS \f[V]resolve_gid(gid: int) -> tuple[int, int]\f[R]
.PP
Resolve a global tile ID to tileset index and local tile ID.
.PP
\f[B]Arguments:\f[R] - \f[V]gid\f[R]: Global tile ID from
tile_layer_data()
.PP
\f[B]Returns:\f[R] Tuple of (tileset_index, local_tile_id).
(-1, -1) for empty/invalid.
.SS \f[V]tile_layer_data(name: str) -> list[int]\f[R]
.PP
Get raw global GID data for a tile layer.
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Name of the tile layer
.PP
\f[B]Returns:\f[R] Flat list of global GIDs (0 = empty tile).
.PP
\f[B]Raises:\f[R] KeyError: If no tile layer with that name exists
.SS \f[V]tileset(index: int) -> tuple[int, TileSetFile]\f[R]
.PP
Get a referenced tileset by index.
.PP
\f[B]Arguments:\f[R] - \f[V]index\f[R]: Tileset index (0-based)
.PP
\f[B]Returns:\f[R] Tuple of (firstgid, TileSetFile).
.SS TileSetFile
.PP
TileSetFile(path: str)
.PP
Load a Tiled tileset file (.tsx or .tsj).
.PP
Parses the tileset and provides access to tile metadata, properties,
Wang sets, and texture creation.
.PP
Args: path: Path to the .tsx or .tsj tileset file.
.PP
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.
.PP
Example: ts = mcrfpy.TileSetFile(`tileset.tsx') texture =
ts.to_texture() print(f\[cq]{ts.name}: {ts.tile_count} tiles\[cq])
.PP
\f[B]Properties:\f[R] - \f[V]columns\f[R] \f[I](read-only)\f[R]: Number
of columns in tileset image (int, read-only).
- \f[V]image_source\f[R] \f[I](read-only)\f[R]: Resolved path to the
tileset image file (str, read-only).
- \f[V]margin\f[R] \f[I](read-only)\f[R]: Margin around tiles in pixels
(int, read-only).
- \f[V]name\f[R] \f[I](read-only)\f[R]: Tileset name (str, read-only).
- \f[V]properties\f[R] \f[I](read-only)\f[R]: Custom tileset properties
as a dict (read-only).
- \f[V]spacing\f[R] \f[I](read-only)\f[R]: Spacing between tiles in
pixels (int, read-only).
- \f[V]tile_count\f[R] \f[I](read-only)\f[R]: Total number of tiles
(int, read-only).
- \f[V]tile_height\f[R] \f[I](read-only)\f[R]: Height of each tile in
pixels (int, read-only).
- \f[V]tile_width\f[R] \f[I](read-only)\f[R]: Width of each tile in
pixels (int, read-only).
- \f[V]wang_sets\f[R] \f[I](read-only)\f[R]: List of WangSet objects
from this tileset (read-only).
.PP
\f[B]Methods:\f[R]
.SS \f[V]tile_info(tile_id: int) -> dict | None\f[R]
.PP
Get metadata for a specific tile.
.PP
\f[B]Arguments:\f[R] - \f[V]tile_id\f[R]: Local tile ID (0-based)
.PP
\f[B]Returns:\f[R] Dict with `properties' and `animation' keys, or None
if no metadata.
.SS \f[V]to_texture() -> Texture\f[R]
.PP
Create a Texture from the tileset image.
.PP
\f[B]Returns:\f[R] A Texture object for use with TileLayer.
.SS \f[V]wang_set(name: str) -> WangSet\f[R]
.PP
Look up a WangSet by name.
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Name of the Wang set
.PP
\f[B]Returns:\f[R] The WangSet object.
.PP
\f[B]Raises:\f[R] KeyError: If no WangSet with that name exists
.SS Timer
.PP
Timer(name, callback, interval, once=False, start=True)
.PP
Create a timer that calls a function at regular intervals.
.PP
Args: name (str): Unique identifier for the timer callback (callable):
Function to call - receives (timer, runtime) args interval (int): Time
between calls in milliseconds once (bool): If True, timer stops after
first call.
Default: False start (bool): If True, timer starts immediately.
Default: True
.PP
Attributes: interval (int): Time between calls in milliseconds remaining
(int): Time until next call in milliseconds (read-only) paused (bool):
Whether timer is paused (read-only) 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
.PP
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\[cq]s running
.PP
Example: def on_timer(timer, runtime): print(f\[cq]Timer {timer} fired
at {runtime}ms\[cq]) if runtime > 5000: timer.stop() # Stop but can
restart later
.IP
.nf
\f[C]
timer = mcrfpy.Timer(\[aq]my_timer\[aq], on_timer, 1000)
timer.pause()  # Pause timer
timer.resume() # Resume timer
timer.stop()   # Stop completely
timer.start()  # Restart from beginning
\f[R]
.fi
.PP
\f[B]Properties:\f[R] - \f[V]active\f[R]: Running state (bool,
read-write).
True if running (not paused, not stopped).
Set True to start/resume, False to pause.
- \f[V]callback\f[R]: The callback function (callable).
Preserved when stopped, allowing timer restart.
- \f[V]interval\f[R]: Timer interval in milliseconds (int).
Must be positive.
Can be changed while timer is running.
- \f[V]name\f[R] \f[I](read-only)\f[R]: Timer name (str, read-only).
Unique identifier for this timer.
- \f[V]once\f[R]: Whether the timer stops after firing once (bool).
One-shot timers can be restarted.
- \f[V]paused\f[R] \f[I](read-only)\f[R]: Whether the timer is paused
(bool, read-only).
Paused timers preserve their remaining time.
- \f[V]remaining\f[R] \f[I](read-only)\f[R]: Time remaining until next
trigger in milliseconds (int, read-only).
Full interval when stopped.
- \f[V]stopped\f[R] \f[I](read-only)\f[R]: Whether the timer is stopped
(bool, read-only).
Stopped timers are not in the engine tick loop but preserve their
callback.
.PP
\f[B]Methods:\f[R]
.SS \f[V]pause() -> None\f[R]
.PP
Pause the timer, preserving the time remaining until next trigger.
.PP
Note:
.PP
\f[B]Returns:\f[R] None The timer can be resumed later with resume().
Time spent paused does not count toward the interval.
.SS \f[V]restart() -> None\f[R]
.PP
Restart the timer from the beginning and ensure it\[cq]s running.
.PP
Note:
.PP
\f[B]Returns:\f[R] None Resets progress and adds timer to engine if
stopped.
Equivalent to stop() followed by start().
.SS \f[V]resume() -> None\f[R]
.PP
Resume a paused timer from where it left off.
.PP
Note:
.PP
\f[B]Returns:\f[R] None Has no effect if the timer is not paused.
Timer will fire after the remaining time elapses.
.SS \f[V]start() -> None\f[R]
.PP
Start the timer, adding it to the engine tick loop.
.PP
Note:
.PP
\f[B]Returns:\f[R] None Resets progress and begins counting toward the
next fire.
If another timer has this name, it will be stopped.
.SS \f[V]stop() -> None\f[R]
.PP
Stop the timer and remove it from the engine tick loop.
.PP
Note:
.PP
\f[B]Returns:\f[R] None The callback is preserved, so the timer can be
restarted with start() or restart().
.SS Transition
.PP
\f[I]Inherits from: IntEnum\f[R]
.PP
\f[B]Properties:\f[R] - \f[V]denominator\f[R]: the denominator of a
rational number in lowest terms - \f[V]imag\f[R]: the imaginary part of
a complex number - \f[V]numerator\f[R]: the numerator of a rational
number in lowest terms - \f[V]real\f[R]: the real part of a complex
number
.PP
\f[B]Methods:\f[R]
.SS \f[V]as_integer_ratio(...)\f[R]
.PP
Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10,
1) >>> (0).as_integer_ratio() (0, 1)
.SS \f[V]bit_count(...)\f[R]
.PP
Number of ones in the binary representation of the absolute value of
self.
Also known as the population count.
>>> bin(13) `0b1101' >>> (13).bit_count() 3
.SS \f[V]bit_length(...)\f[R]
.PP
Number of bits necessary to represent self in binary.
>>> bin(37) `0b100101' >>> (37).bit_length() 6
.SS \f[V]conjugate(...)\f[R]
.PP
Returns self, the complex conjugate of any int.
.SS \f[V]from_bytes(...)\f[R]
.PP
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert.
The argument must either support the buffer protocol or be an iterable
object producing bytes.
Bytes and bytearray are examples of built-in objects that support the
buffer protocol.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Indicates whether two\[cq]s complement is used to represent the
integer.
.SS \f[V]is_integer(...)\f[R]
.PP
Returns True.
Exists for duck type compatibility with float.is_integer.
.SS \f[V]to_bytes(...)\f[R]
.PP
Return an array of bytes representing an integer.
length Length of bytes object to use.
An OverflowError is raised if the integer is not representable with the
given number of bytes.
Default is length 1.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Determines whether two\[cq]s complement is used to represent the
integer.
If signed is False and a negative integer is given, an OverflowError is
raised.
.SS Traversal
.PP
\f[I]Inherits from: IntEnum\f[R]
.PP
\f[B]Properties:\f[R] - \f[V]denominator\f[R]: the denominator of a
rational number in lowest terms - \f[V]imag\f[R]: the imaginary part of
a complex number - \f[V]numerator\f[R]: the numerator of a rational
number in lowest terms - \f[V]real\f[R]: the real part of a complex
number
.PP
\f[B]Methods:\f[R]
.SS \f[V]as_integer_ratio(...)\f[R]
.PP
Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10,
1) >>> (0).as_integer_ratio() (0, 1)
.SS \f[V]bit_count(...)\f[R]
.PP
Number of ones in the binary representation of the absolute value of
self.
Also known as the population count.
>>> bin(13) `0b1101' >>> (13).bit_count() 3
.SS \f[V]bit_length(...)\f[R]
.PP
Number of bits necessary to represent self in binary.
>>> bin(37) `0b100101' >>> (37).bit_length() 6
.SS \f[V]conjugate(...)\f[R]
.PP
Returns self, the complex conjugate of any int.
.SS \f[V]from_bytes(...)\f[R]
.PP
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert.
The argument must either support the buffer protocol or be an iterable
object producing bytes.
Bytes and bytearray are examples of built-in objects that support the
buffer protocol.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Indicates whether two\[cq]s complement is used to represent the
integer.
.SS \f[V]is_integer(...)\f[R]
.PP
Returns True.
Exists for duck type compatibility with float.is_integer.
.SS \f[V]to_bytes(...)\f[R]
.PP
Return an array of bytes representing an integer.
length Length of bytes object to use.
An OverflowError is raised if the integer is not representable with the
given number of bytes.
Default is length 1.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Determines whether two\[cq]s complement is used to represent the
integer.
If signed is False and a negative integer is given, an OverflowError is
raised.
.SS Trigger
.PP
\f[I]Inherits from: IntEnum\f[R]
.PP
Enum representing trigger types passed to entity step() callbacks.
.PP
Values: DONE: Behavior completed (path exhausted, sleep finished, etc.)
BLOCKED: Movement blocked by wall or collision TARGET: Target entity
spotted in FOV
.PP
\f[B]Properties:\f[R] - \f[V]denominator\f[R]: the denominator of a
rational number in lowest terms - \f[V]imag\f[R]: the imaginary part of
a complex number - \f[V]numerator\f[R]: the numerator of a rational
number in lowest terms - \f[V]real\f[R]: the real part of a complex
number
.PP
\f[B]Methods:\f[R]
.SS \f[V]as_integer_ratio(...)\f[R]
.PP
Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
>>> (10).as_integer_ratio() (10, 1) >>> (-10).as_integer_ratio() (-10,
1) >>> (0).as_integer_ratio() (0, 1)
.SS \f[V]bit_count(...)\f[R]
.PP
Number of ones in the binary representation of the absolute value of
self.
Also known as the population count.
>>> bin(13) `0b1101' >>> (13).bit_count() 3
.SS \f[V]bit_length(...)\f[R]
.PP
Number of bits necessary to represent self in binary.
>>> bin(37) `0b100101' >>> (37).bit_length() 6
.SS \f[V]conjugate(...)\f[R]
.PP
Returns self, the complex conjugate of any int.
.SS \f[V]from_bytes(...)\f[R]
.PP
Return the integer represented by the given array of bytes.
bytes Holds the array of bytes to convert.
The argument must either support the buffer protocol or be an iterable
object producing bytes.
Bytes and bytearray are examples of built-in objects that support the
buffer protocol.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Indicates whether two\[cq]s complement is used to represent the
integer.
.SS \f[V]is_integer(...)\f[R]
.PP
Returns True.
Exists for duck type compatibility with float.is_integer.
.SS \f[V]to_bytes(...)\f[R]
.PP
Return an array of bytes representing an integer.
length Length of bytes object to use.
An OverflowError is raised if the integer is not representable with the
given number of bytes.
Default is length 1.
byteorder The byte order used to represent the integer.
If byteorder is `big', the most significant byte is at the beginning of
the byte array.
If byteorder is `little', the most significant byte is at the end of the
byte array.
To request the native byte order of the host system, use sys.byteorder
as the byte order value.
Default is to use `big'.
signed Determines whether two\[cq]s complement is used to represent the
integer.
If signed is False and a negative integer is given, an OverflowError is
raised.
.SS Vector
.PP
Vector(x: float = 0, y: float = 0)
.PP
2D vector for positions, sizes, and directions.
.PP
Args: x: X component.
y: Y component.
.PP
Supports arithmetic (+, -, *, /), abs(), len() == 2, indexing ([0] for
x, [1] for y), hashing, and equality.
.PP
Properties: x (float): X component.
y (float): Y component.
int (tuple[int, int], read-only): Integer floor of (x, y).
.PP
\f[B]Properties:\f[R] - \f[V]int\f[R] \f[I](read-only)\f[R]: Integer
tuple (floor of x and y) for use as dict keys.
Read-only.
- \f[V]x\f[R]: X coordinate of the vector (float) - \f[V]y\f[R]: Y
coordinate of the vector (float)
.PP
\f[B]Methods:\f[R]
.SS \f[V]angle() -> float\f[R]
.PP
Get the angle of this vector in radians.
.PP
\f[B]Returns:\f[R] float: Angle in radians from positive x-axis
.SS \f[V]copy() -> Vector\f[R]
.PP
Create a copy of this vector.
.PP
\f[B]Returns:\f[R] Vector: New Vector object with same x and y values
.SS \f[V]distance_to(other: Vector) -> float\f[R]
.PP
Calculate the distance to another vector.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: The other vector
.PP
\f[B]Returns:\f[R] float: Distance between the two vectors
.SS \f[V]dot(other: Vector) -> float\f[R]
.PP
Calculate the dot product with another vector.
.PP
\f[B]Arguments:\f[R] - \f[V]other\f[R]: The other vector
.PP
\f[B]Returns:\f[R] float: Dot product of the two vectors
.SS \f[V]floor() -> Vector\f[R]
.PP
Return a new vector with floored (integer) coordinates.
.PP
Note:
.PP
\f[B]Returns:\f[R] Vector: New Vector with floor(x) and floor(y) Useful
for grid-based positioning.
For a hashable tuple, use the .int property instead.
.SS \f[V]magnitude() -> float\f[R]
.PP
Calculate the length/magnitude of this vector.
.PP
\f[B]Returns:\f[R] float: The magnitude of the vector
.SS \f[V]magnitude_squared() -> float\f[R]
.PP
Calculate the squared magnitude of this vector.
.PP
Note:
.PP
\f[B]Returns:\f[R] float: The squared magnitude (faster than
magnitude()) Use this for comparisons to avoid expensive square root
calculation.
.SS \f[V]normalize() -> Vector\f[R]
.PP
Return a unit vector in the same direction.
.PP
Note:
.PP
\f[B]Returns:\f[R] Vector: New normalized vector with magnitude 1.0 For
zero vectors (magnitude 0.0), returns a zero vector rather than raising
an exception
.SS Viewport3D
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Viewport3D(pos=None, size=None, **kwargs)
.PP
A 3D rendering viewport that displays a 3D scene as a UI element.
.PP
Args: pos (tuple, optional): Position as (x, y) tuple.
Default: (0, 0) size (tuple, optional): Display size as (width, height).
Default: (320, 240)
.PP
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
.PP
\f[B]Properties:\f[R] - \f[V]bg_color\f[R]: Background clear color.
- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]camera_pos\f[R]: Camera position as (x, y, z) tuple.
- \f[V]camera_target\f[R]: Camera look-at target as (x, y, z) tuple.
- \f[V]cell_size\f[R]: World units per navigation grid cell.
- \f[V]enable_affine\f[R]: Enable PS1-style affine texture mapping
(warped textures).
- \f[V]enable_dither\f[R]: Enable PS1-style color dithering.
- \f[V]enable_fog\f[R]: Enable distance fog.
- \f[V]enable_vertex_snap\f[R]: Enable PS1-style vertex snapping
(jittery vertices).
- \f[V]entities\f[R] \f[I](read-only)\f[R]: Collection of Entity3D
objects (read-only).
Use append/remove to modify.
- \f[V]fog_color\f[R]: Fog color.
- \f[V]fog_far\f[R]: Fog end distance.
- \f[V]fog_near\f[R]: Fog start distance.
- \f[V]fov\f[R]: Camera field of view in degrees.
- \f[V]global_bounds\f[R]: Bounding box as (pos, size) tuple of Vectors
in screen coordinates.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]global_position\f[R] \f[I](read-only)\f[R]: Global screen
position (read-only).
Calculates absolute position by walking up the parent chain.
- \f[V]grid_size\f[R]: Navigation grid dimensions as (width, depth)
tuple.
- \f[V]h\f[R]: Display height in pixels.
- \f[V]hovered\f[R] \f[I](read-only)\f[R]: Whether mouse is currently
over this element (read-only).
Updated automatically by the engine during mouse movement.
- \f[V]on_click\f[R]: Callable executed when object is clicked.
Function receives (pos: Vector, button: str, action: str).
- \f[V]on_enter\f[R]: Callback for mouse enter events.
Called with (pos: Vector, button: str, action: str) when mouse enters
this element\[cq]s bounds.
- \f[V]on_exit\f[R]: Callback for mouse exit events.
Called with (pos: Vector, button: str, action: str) when mouse leaves
this element\[cq]s bounds.
- \f[V]on_move\f[R]: 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.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]parent\f[R]: 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.
- \f[V]pos\f[R]: Position as Vector (x, y).
- \f[V]render_resolution\f[R]: Internal render resolution (width,
height).
Lower values for PS1 effect.
- \f[V]visible\f[R]: Whether the object is visible (bool).
Invisible objects are not rendered or clickable.
- \f[V]w\f[R]: Display width in pixels.
- \f[V]x\f[R]: X position in pixels.
- \f[V]y\f[R]: Y position in pixels.
- \f[V]z_index\f[R]: Z-order for rendering (lower values rendered
first).
Automatically triggers scene resort when changed.
.PP
\f[B]Methods:\f[R]
.SS \f[V]add_billboard(billboard)\f[R]
.PP
Add a Billboard to the viewport.
.PP
\f[B]Arguments:\f[R] - \f[V]billboard\f[R]: Billboard object to add
.SS \f[V]add_layer(name, z_index=0) -> dict\f[R]
.PP
Add a new mesh layer to the viewport.
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Unique identifier for the layer -
\f[V]z_index\f[R]: Render order (lower = rendered first)
.SS \f[V]add_mesh(layer_name, model, pos, rotation=0, scale=1.0) -> int\f[R]
.PP
Add a Model3D instance to a layer at the specified position.
.PP
\f[B]Arguments:\f[R] - \f[V]layer_name\f[R]: Name of layer to add mesh
to (created if needed) - \f[V]model\f[R]: Model3D object to place -
\f[V]pos\f[R]: World position as (x, y, z) tuple - \f[V]rotation\f[R]:
Y-axis rotation in degrees - \f[V]scale\f[R]: Uniform scale factor
.PP
\f[B]Returns:\f[R] Index of the mesh instance
.SS \f[V]add_voxel_layer(voxel_grid, z_index=0)\f[R]
.PP
Add a VoxelGrid as a renderable layer.
.PP
\f[B]Arguments:\f[R] - \f[V]voxel_grid\f[R]: VoxelGrid object to render
- \f[V]z_index\f[R]: Render order (lower = rendered first)
.SS \f[V]animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode=\[aq]replace\[aq]) -> Animation\f[R]
.PP
Create and start an animation on this drawable\[cq]s property.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]property\f[R]: Name of the property to
animate (e.g., `x', `fill_color', `opacity') - \f[V]target\f[R]: Target
value - type depends on property (float, tuple for color/vector, etc.)
- \f[V]duration\f[R]: Animation duration in seconds - \f[V]easing\f[R]:
Easing function: Easing enum value, string name, or None for linear -
\f[V]delta\f[R]: If True, target is relative to current value; if False,
target is absolute - \f[V]loop\f[R]: If True, animation repeats from
start when it reaches the end (default False) - \f[V]callback\f[R]:
Optional callable invoked when animation completes (not called for
looping animations) - \f[V]conflict_mode\f[R]: `replace' (default),
`queue', or `error' if property already animating
.PP
\f[B]Returns:\f[R] Animation object for monitoring progress
.PP
\f[B]Raises:\f[R] ValueError: If property name is not valid for this
drawable type This is a convenience method that creates an Animation,
starts it, and adds it to the AnimationManager.
.SS \f[V]apply_heightmap(heightmap, y_scale=1.0)\f[R]
.PP
Set cell heights from HeightMap.
.PP
\f[B]Arguments:\f[R] - \f[V]heightmap\f[R]: HeightMap object -
\f[V]y_scale\f[R]: Vertical scale factor
.SS \f[V]apply_terrain_colors(layer_name, r_map, g_map, b_map)\f[R]
.PP
Apply per-vertex colors to terrain from RGB HeightMaps.
.PP
\f[B]Arguments:\f[R] - \f[V]layer_name\f[R]: Name of terrain layer to
colorize - \f[V]r_map\f[R]: HeightMap for red channel (0-1 values) -
\f[V]g_map\f[R]: HeightMap for green channel (0-1 values) -
\f[V]b_map\f[R]: HeightMap for blue channel (0-1 values)
.SS \f[V]apply_threshold(heightmap, min_height, max_height, walkable=True)\f[R]
.PP
Set cell walkability based on height thresholds.
.PP
\f[B]Arguments:\f[R] - \f[V]heightmap\f[R]: HeightMap object -
\f[V]min_height\f[R]: Minimum height (0-1) - \f[V]max_height\f[R]:
Maximum height (0-1) - \f[V]walkable\f[R]: Walkability value for cells
in range
.SS \f[V]at(x, z) -> VoxelPoint\f[R]
.PP
Get VoxelPoint at grid coordinates.
.PP
\f[B]Arguments:\f[R] - \f[V]x\f[R]: X coordinate in grid - \f[V]z\f[R]:
Z coordinate in grid
.PP
\f[B]Returns:\f[R] VoxelPoint object for the cell
.SS \f[V]billboard_count() -> int\f[R]
.PP
Get the number of billboards.
.PP
\f[B]Returns:\f[R] Number of billboards in the viewport
.SS \f[V]build_terrain(layer_name, heightmap, y_scale=1.0, cell_size=1.0) -> int\f[R]
.PP
Build terrain mesh from HeightMap on specified layer.
.PP
\f[B]Arguments:\f[R] - \f[V]layer_name\f[R]: Name of layer to build
terrain on (created if doesn\[cq]t exist) - \f[V]heightmap\f[R]:
HeightMap object with height data - \f[V]y_scale\f[R]: Vertical
exaggeration factor - \f[V]cell_size\f[R]: World-space size of each grid
cell
.PP
\f[B]Returns:\f[R] Number of vertices in the generated mesh
.SS \f[V]clear_billboards()\f[R]
.PP
Remove all billboards from the viewport.
.SS \f[V]clear_meshes(layer_name)\f[R]
.PP
Clear all mesh instances from a layer.
.PP
\f[B]Arguments:\f[R] - \f[V]layer_name\f[R]: Name of layer to clear
.SS \f[V]clear_voxel_nav_region(voxel_grid)\f[R]
.PP
Clear navigation cells in a voxel grid\[cq]s footprint.
Resets walkability, transparency, height, and cost to defaults for all
nav cells corresponding to the voxel grid\[cq]s XZ extent.
.PP
\f[B]Arguments:\f[R] - \f[V]voxel_grid\f[R]: VoxelGrid whose nav region
to clear
.SS \f[V]compute_fov(origin, radius=10) -> list\f[R]
.PP
Compute field of view from a position.
.PP
\f[B]Arguments:\f[R] - \f[V]origin\f[R]: Origin point as (x, z) tuple -
\f[V]radius\f[R]: FOV radius
.PP
\f[B]Returns:\f[R] List of visible (x, z) positions
.SS \f[V]find_path(start, end) -> list\f[R]
.PP
Find A* path between two points.
.PP
\f[B]Arguments:\f[R] - \f[V]start\f[R]: Starting point as (x, z) tuple -
\f[V]end\f[R]: End point as (x, z) tuple
.PP
\f[B]Returns:\f[R] List of (x, z) tuples forming the path, or empty list
if no path
.SS \f[V]follow(entity, distance=10, height=5, smoothing=1.0)\f[R]
.PP
Position camera to follow an entity.
.PP
\f[B]Arguments:\f[R] - \f[V]entity\f[R]: Entity3D to follow -
\f[V]distance\f[R]: Distance behind entity - \f[V]height\f[R]: Camera
height above entity - \f[V]smoothing\f[R]: Interpolation factor (0-1).
1 = instant, lower = smoother
.SS \f[V]get_billboard(index) -> Billboard\f[R]
.PP
Get a Billboard by index.
.PP
\f[B]Arguments:\f[R] - \f[V]index\f[R]: Index of the billboard
.PP
\f[B]Returns:\f[R] Billboard object
.SS \f[V]get_layer(name) -> dict or None\f[R]
.PP
Get a layer by name.
.SS \f[V]is_in_fov(x, z) -> bool\f[R]
.PP
Check if a cell is in the current FOV (after compute_fov).
.PP
\f[B]Arguments:\f[R] - \f[V]x\f[R]: X coordinate - \f[V]z\f[R]: Z
coordinate
.PP
\f[B]Returns:\f[R] True if the cell is visible
.SS \f[V]layer_count() -> int\f[R]
.PP
Get the number of mesh layers.
.SS \f[V]move(dx, dy) or (delta) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels (or use
delta) - \f[V]dy\f[R]: Vertical offset in pixels (or use delta) -
\f[V]delta\f[R]: Offset as tuple, list, or Vector: (dx, dy)
.SS \f[V]orbit_camera(angle=0, distance=10, height=5)\f[R]
.PP
Position camera to orbit around origin.
.PP
\f[B]Arguments:\f[R] - \f[V]angle\f[R]: Orbit angle in radians -
\f[V]distance\f[R]: Distance from origin - \f[V]height\f[R]: Camera
height above XZ plane
.SS \f[V]place_blocking(grid_pos, footprint, walkable=False, transparent=False)\f[R]
.PP
Mark grid cells as blocking for pathfinding and FOV.
.PP
\f[B]Arguments:\f[R] - \f[V]grid_pos\f[R]: Top-left grid position as (x,
z) tuple - \f[V]footprint\f[R]: Size in cells as (width, depth) tuple -
\f[V]walkable\f[R]: Whether cells should be walkable (default: False) -
\f[V]transparent\f[R]: Whether cells should be transparent (default:
False)
.SS \f[V]project_all_voxels_to_nav(headroom=2)\f[R]
.PP
Project all voxel layers to the navigation grid.
Resets navigation grid and projects each voxel layer in z_index order.
Later layers (higher z_index) overwrite earlier ones.
.PP
\f[B]Arguments:\f[R] - \f[V]headroom\f[R]: Required air voxels above
floor for walkability (default: 2)
.SS \f[V]project_voxel_to_nav(voxel_grid, headroom=2)\f[R]
.PP
Project a VoxelGrid to the navigation grid.
Scans each column of the voxel grid and updates corresponding navigation
cells with walkability, transparency, height, and cost.
.PP
\f[B]Arguments:\f[R] - \f[V]voxel_grid\f[R]: VoxelGrid to project -
\f[V]headroom\f[R]: Required air voxels above floor for walkability
(default: 2)
.SS \f[V]realign() -> None\f[R]
.PP
Reapply alignment relative to parent, useful for responsive layouts.
.PP
Note: Call this to recalculate position after parent changes size.
For elements with align=None, this has no effect.
.SS \f[V]remove_billboard(billboard)\f[R]
.PP
Remove a Billboard from the viewport.
.PP
\f[B]Arguments:\f[R] - \f[V]billboard\f[R]: Billboard object to remove
.SS \f[V]remove_layer(name) -> bool\f[R]
.PP
Remove a layer by name.
Returns True if found and removed.
.SS \f[V]remove_voxel_layer(voxel_grid) -> bool\f[R]
.PP
Remove a VoxelGrid layer from the viewport.
.PP
\f[B]Arguments:\f[R] - \f[V]voxel_grid\f[R]: VoxelGrid object to remove
.PP
\f[B]Returns:\f[R] True if the layer was found and removed
.SS \f[V]resize(width, height) or (size) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels (or use
size) - \f[V]height\f[R]: New height in pixels (or use size) -
\f[V]size\f[R]: Size as tuple, list, or Vector: (width, height)
.SS \f[V]screen_to_world(x, y, y_plane=0.0) -> tuple or None\f[R]
.PP
Convert screen coordinates to world position via ray casting.
.PP
\f[B]Arguments:\f[R] - \f[V]x\f[R]: Screen X coordinate relative to
viewport - \f[V]y\f[R]: Screen Y coordinate relative to viewport -
\f[V]y_plane\f[R]: Y value of horizontal plane to intersect (default:
0.0)
.PP
\f[B]Returns:\f[R] (x, y, z) world position tuple, or None if no
intersection with the plane
.SS \f[V]set_grid_size(width, depth)\f[R]
.PP
Initialize navigation grid with specified dimensions.
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: Grid width (X axis) -
\f[V]depth\f[R]: Grid depth (Z axis)
.SS \f[V]set_slope_cost(max_slope=0.5, cost_multiplier=1.0)\f[R]
.PP
Calculate slope costs and mark steep cells unwalkable.
.PP
\f[B]Arguments:\f[R] - \f[V]max_slope\f[R]: Maximum height difference
before marking unwalkable - \f[V]cost_multiplier\f[R]: Cost increase per
unit slope
.SS \f[V]voxel_layer_count() -> int\f[R]
.PP
Get the number of voxel layers.
.PP
\f[B]Returns:\f[R] Number of voxel layers in the viewport
.SS VoxelGrid
.PP
VoxelGrid(size: tuple[int, int, int], cell_size: float = 1.0)
.PP
A dense 3D grid of voxel material IDs with a material palette.
.PP
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.
.PP
Args: size: (width, height, depth) dimensions.
Immutable after creation.
cell_size: World units per voxel.
Default 1.0.
.PP
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
.PP
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\[cq]Non-air voxels: {voxels.count_non_air()}\[cq])
.PP
\f[B]Properties:\f[R] - \f[V]cell_size\f[R] \f[I](read-only)\f[R]: World
units per voxel.
Read-only.
- \f[V]depth\f[R] \f[I](read-only)\f[R]: Grid depth (Z dimension).
Read-only.
- \f[V]greedy_meshing\f[R]: Enable greedy meshing optimization (reduces
vertex count for uniform regions).
- \f[V]height\f[R] \f[I](read-only)\f[R]: Grid height (Y dimension).
Read-only.
- \f[V]material_count\f[R] \f[I](read-only)\f[R]: Number of materials in
the palette.
Read-only.
- \f[V]offset\f[R]: World-space position (x, y, z) of the grid origin.
- \f[V]rotation\f[R]: Y-axis rotation in degrees.
- \f[V]size\f[R] \f[I](read-only)\f[R]: Dimensions (width, height,
depth) of the grid.
Read-only.
- \f[V]vertex_count\f[R] \f[I](read-only)\f[R]: Number of vertices after
mesh generation.
Read-only.
- \f[V]visible\f[R]: Show or hide this voxel grid in rendering.
- \f[V]width\f[R] \f[I](read-only)\f[R]: Grid width (X dimension).
Read-only.
.PP
\f[B]Methods:\f[R]
.SS \f[V]add_material(name, color=Color(255,255,255), sprite_index=-1, transparent=False, path_cost=1.0) -> int\f[R]
.PP
Add a new material to the palette.
Returns the material ID (1-indexed).
Material 0 is always air (implicit, never stored in palette).
Maximum 255 materials can be added.
.SS \f[V]clear() -> None\f[R]
.PP
Clear the grid (fill with air, material 0).
.SS \f[V]copy_region(min_coord, max_coord) -> VoxelRegion\f[R]
.PP
Copy a rectangular region to a VoxelRegion prefab.
.PP
\f[B]Arguments:\f[R] - \f[V]min_coord\f[R]: (x0, y0, z0) - minimum
corner (inclusive) - \f[V]max_coord\f[R]: (x1, y1, z1) - maximum corner
(inclusive)
.PP
\f[B]Returns:\f[R] VoxelRegion object that can be pasted elsewhere.
.SS \f[V]count_material(material) -> int\f[R]
.PP
Count the number of voxels with the specified material ID.
.SS \f[V]count_non_air() -> int\f[R]
.PP
Count the number of non-air voxels in the grid.
.SS \f[V]fill(material) -> None\f[R]
.PP
Fill the entire grid with the specified material ID.
.SS \f[V]fill_box(min_coord, max_coord, material) -> None\f[R]
.PP
Fill a rectangular region with the specified material.
.PP
\f[B]Arguments:\f[R] - \f[V]min_coord\f[R]: (x0, y0, z0) - minimum
corner (inclusive) - \f[V]max_coord\f[R]: (x1, y1, z1) - maximum corner
(inclusive) - \f[V]material\f[R]: material ID (0-255)
.SS \f[V]fill_box_hollow(min_coord, max_coord, material, thickness=1) -> None\f[R]
.PP
Create a hollow rectangular room (walls only, hollow inside).
.PP
\f[B]Arguments:\f[R] - \f[V]min_coord\f[R]: (x0, y0, z0) - minimum
corner (inclusive) - \f[V]max_coord\f[R]: (x1, y1, z1) - maximum corner
(inclusive) - \f[V]material\f[R]: material ID for walls (0-255) -
\f[V]thickness\f[R]: wall thickness in voxels (default 1)
.SS \f[V]fill_cylinder(base_pos, radius, height, material) -> None\f[R]
.PP
Fill a vertical cylinder (Y-axis aligned).
.PP
\f[B]Arguments:\f[R] - \f[V]base_pos\f[R]: (cx, cy, cz) - base center
position - \f[V]radius\f[R]: cylinder radius in voxels -
\f[V]height\f[R]: cylinder height in voxels - \f[V]material\f[R]:
material ID (0-255)
.SS \f[V]fill_noise(min_coord, max_coord, material, threshold=0.5, scale=0.1, seed=0) -> None\f[R]
.PP
Fill region with 3D noise-based pattern (caves, clouds).
.PP
\f[B]Arguments:\f[R] - \f[V]min_coord\f[R]: (x0, y0, z0) - minimum
corner - \f[V]max_coord\f[R]: (x1, y1, z1) - maximum corner -
\f[V]material\f[R]: material ID for solid areas - \f[V]threshold\f[R]:
noise threshold (0-1, higher = more solid) - \f[V]scale\f[R]: noise
scale (smaller = larger features) - \f[V]seed\f[R]: random seed (0 for
default)
.SS \f[V]fill_sphere(center, radius, material) -> None\f[R]
.PP
Fill a spherical region.
.PP
\f[B]Arguments:\f[R] - \f[V]center\f[R]: (cx, cy, cz) - sphere center
coordinates - \f[V]radius\f[R]: sphere radius in voxels -
\f[V]material\f[R]: material ID (0-255, use 0 to carve)
.SS \f[V]from_bytes(data) -> bool\f[R]
.PP
Load voxel data from a bytes object.
.PP
Note: This replaces the current grid data entirely.
.PP
\f[B]Arguments:\f[R] - \f[V]data\f[R]: bytes object containing
serialized grid data
.PP
\f[B]Returns:\f[R] True on success, False on failure.
.SS \f[V]get(x, y, z) -> int\f[R]
.PP
Get the material ID at integer coordinates.
Returns 0 (air) for out-of-bounds coordinates.
.SS \f[V]get_material(id) -> dict\f[R]
.PP
Get material properties by ID.
Returns dict with keys: name, color, sprite_index, transparent,
path_cost.
ID 0 returns the implicit air material.
.SS \f[V]load(path) -> bool\f[R]
.PP
Load voxel data from a binary file.
.PP
Note: This replaces the current grid data entirely, including
.PP
\f[B]Arguments:\f[R] - \f[V]path\f[R]: File path to load from
.PP
\f[B]Returns:\f[R] True on success, False on failure.
dimensions and material palette.
.SS \f[V]paste_region(region, position, skip_air=True) -> None\f[R]
.PP
Paste a VoxelRegion prefab at the specified position.
.PP
\f[B]Arguments:\f[R] - \f[V]region\f[R]: VoxelRegion from copy_region()
- \f[V]position\f[R]: (x, y, z) - paste destination -
\f[V]skip_air\f[R]: if True, air voxels don\[cq]t overwrite (default
True)
.SS \f[V]project_column(x, z, headroom=2) -> dict\f[R]
.PP
Project a single column to navigation info.
Scans the column from top to bottom, finding the topmost floor (solid
voxel with air above) and checking for adequate headroom.
.PP
\f[B]Arguments:\f[R] - \f[V]x\f[R]: X coordinate in voxel grid -
\f[V]z\f[R]: Z coordinate in voxel grid - \f[V]headroom\f[R]: Required
air voxels above floor (default 2)
.PP
\f[B]Returns:\f[R] dict with keys: height (float): World Y of floor
surface walkable (bool): True if floor found with adequate headroom
transparent (bool): True if no opaque voxels in column path_cost
(float): Floor material\[cq]s path cost
.SS \f[V]rebuild_mesh() -> None\f[R]
.PP
Force immediate mesh rebuild for rendering.
.SS \f[V]save(path) -> bool\f[R]
.PP
Save the voxel grid to a binary file.
.PP
\f[B]Arguments:\f[R] - \f[V]path\f[R]: File path to save to (.mcvg
extension recommended)
.PP
\f[B]Returns:\f[R] True on success, False on failure.
The file format includes grid dimensions, cell size, material palette,
and RLE-compressed voxel data.
.SS \f[V]set(x, y, z, material) -> None\f[R]
.PP
Set the material ID at integer coordinates.
Out-of-bounds coordinates are silently ignored.
.SS \f[V]to_bytes() -> bytes\f[R]
.PP
Serialize the voxel grid to a bytes object.
.PP
\f[B]Returns:\f[R] bytes object containing the serialized grid data.
Useful for network transmission or custom storage.
.SS VoxelRegion
.PP
VoxelRegion - Portable voxel data for copy/paste operations.
.PP
Created by VoxelGrid.copy_region(), used with paste_region().
Cannot be instantiated directly.
.PP
Properties: size (tuple, read-only): Dimensions as (width, height,
depth) width, height, depth (int, read-only): Individual dimensions
.PP
\f[B]Properties:\f[R] - \f[V]depth\f[R] \f[I](read-only)\f[R]: Region
depth.
Read-only.
- \f[V]height\f[R] \f[I](read-only)\f[R]: Region height.
Read-only.
- \f[V]size\f[R] \f[I](read-only)\f[R]: Dimensions (width, height,
depth) of the region.
Read-only.
- \f[V]width\f[R] \f[I](read-only)\f[R]: Region width.
Read-only.
.PP
\f[B]Methods:\f[R]
.SS WangSet
.PP
WangSet - Wang terrain auto-tile set from a Tiled tileset.
.PP
WangSets are obtained from TileSetFile.wang_sets or
TileSetFile.wang_set().
They map abstract terrain types to concrete sprite indices using
Tiled\[cq]s Wang tile algorithm.
.PP
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.
.PP
Example: ws = tileset.wang_set(`overworld') Terrain = ws.terrain_enum()
tiles = ws.resolve(discrete_map)
.PP
\f[B]Properties:\f[R] - \f[V]color_count\f[R] \f[I](read-only)\f[R]:
Number of terrain colors (int, read-only).
- \f[V]colors\f[R] \f[I](read-only)\f[R]: List of color dicts with name,
index, tile_id, probability (read-only).
- \f[V]name\f[R] \f[I](read-only)\f[R]: Wang set name (str, read-only).
- \f[V]type\f[R] \f[I](read-only)\f[R]: Wang set type: `corner', `edge',
or `mixed' (str, read-only).
.PP
\f[B]Methods:\f[R]
.SS \f[V]apply(discrete_map: DiscreteMap, tile_layer: TileLayer) -> None\f[R]
.PP
Resolve terrain and write tile indices directly into a TileLayer.
.PP
\f[B]Arguments:\f[R] - \f[V]discrete_map\f[R]: A DiscreteMap with
terrain IDs - \f[V]tile_layer\f[R]: Target TileLayer to write resolved
tiles into
.SS \f[V]resolve(discrete_map: DiscreteMap) -> list[int]\f[R]
.PP
Resolve terrain data to tile indices using Wang tile rules.
.PP
\f[B]Arguments:\f[R] - \f[V]discrete_map\f[R]: A DiscreteMap with
terrain IDs matching this WangSet\[cq]s colors
.PP
\f[B]Returns:\f[R] List of tile IDs (one per cell).
-1 means no matching Wang tile.
.SS \f[V]terrain_enum() -> IntEnum\f[R]
.PP
Generate a Python IntEnum from this WangSet\[cq]s terrain colors.
.PP
\f[B]Returns:\f[R] IntEnum class with NONE=0 and one member per color
(UPPER_SNAKE_CASE).
.SS Window
.PP
Window singleton for accessing and modifying the game window properties
.PP
\f[B]Properties:\f[R] - \f[V]framerate_limit\f[R]: Frame rate limit in
FPS (int, 0 for unlimited).
Caps maximum frame rate.
- \f[V]fullscreen\f[R]: Window fullscreen state (bool).
Setting this recreates the window.
- \f[V]game_resolution\f[R]: Fixed game resolution as (width, height)
tuple.
Enables resolution-independent rendering with scaling.
- \f[V]resolution\f[R]: Window resolution as (width, height) tuple.
Setting this recreates the window.
- \f[V]scaling_mode\f[R]: Viewport scaling mode (str): `center' (no
scaling), `stretch' (fill window), or `fit' (maintain aspect ratio).
- \f[V]title\f[R]: Window title string (str).
Displayed in the window title bar.
- \f[V]visible\f[R]: Window visibility state (bool).
Hidden windows still process events.
- \f[V]vsync\f[R]: Vertical sync enabled state (bool).
Prevents screen tearing but may limit framerate.
.PP
\f[B]Methods:\f[R]
.SS \f[V]center() -> None\f[R]
.PP
Center the window on the screen.
.PP
Note:
.PP
\f[B]Returns:\f[R] None Only works in windowed mode.
Has no effect when fullscreen or in headless mode.
.SS \f[V]get() -> Window\f[R]
.PP
Get the Window singleton instance.
.PP
Note:
.PP
\f[B]Returns:\f[R] Window: The global window object This is a class
method.
Call as Window.get().
There is only one window instance per application.
.SS \f[V]screenshot(filename: str = None) -> bytes | None\f[R]
.PP
Take a screenshot of the current window contents.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]filename\f[R]: Optional path to save
screenshot.
If omitted, returns raw RGBA bytes.
.PP
\f[B]Returns:\f[R] bytes | None: Raw RGBA pixel data if no filename
given, otherwise None after saving Screenshot is taken at the actual
window resolution.
Use after render loop update for current frame.
.SS Constants