john/McRogueFace
1
0
Fork 0
Code Issues 25 Pull requests Projects Releases Wiki Activity
McRogueFace/docs/api_reference_dynamic.html
John McCardle 98d2b36739 Regenerate docs and stubs after API freeze pass 
Picks up the five 1.0 freeze commits (groups A-D + Grid follow-up):
  * mcrfpy.Animation removed from module exports
  * parent= kwarg on Frame/Caption/Sprite/Line/Circle/Arc/Grid
  * grid= kwarg on ColorLayer/TileLayer
  * Constructor positional reorders (Circle, Caption, Layers)
  * __getitem__/__setitem__ on ColorLayer/TileLayer/Grid

PyMethodDef/PyGetSetDef compliance baseline (per tools/audit_pymethoddef.py):
  PyGetSetDef: 190/410 MACRO (46.3%)
  PyMethodDef: 150/345 MACRO (43.5%)
413 raw-string docstring entries remain to migrate to MCRF_METHOD/
MCRF_PROPERTY in a separate sweep.
2026-04-18 13:35:26 -04:00

6090 lines
376 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>McRogueFace API Reference</title>
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
line-height: 1.6;
color: #333;
max-width: 1200px;
margin: 0 auto;
padding: 20px;
background-color: #f5f5f5;
}
.container {
background-color: white;
padding: 30px;
border-radius: 8px;
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
h1, h2, h3, h4, h5 {
color: #2c3e50;
}
.toc {
background-color: #f8f9fa;
padding: 20px;
border-radius: 4px;
margin-bottom: 30px;
}
.toc ul {
list-style-type: none;
padding-left: 20px;
}
.toc > ul {
padding-left: 0;
}
.toc a {
text-decoration: none;
color: #3498db;
}
.toc a:hover {
text-decoration: underline;
}
.method-section {
margin-bottom: 30px;
padding: 20px;
background-color: #f8f9fa;
border-radius: 4px;
border-left: 4px solid #3498db;
}
.function-signature {
font-family: 'Consolas', 'Monaco', monospace;
background-color: #e9ecef;
padding: 10px;
border-radius: 4px;
margin: 10px 0;
}
.class-name {
color: #e74c3c;
font-weight: bold;
}
.method-name {
color: #3498db;
font-family: 'Consolas', 'Monaco', monospace;
}
.property-name {
color: #27ae60;
font-family: 'Consolas', 'Monaco', monospace;
}
.arg-name {
color: #8b4513;
font-weight: bold;
}
.arg-type {
color: #666;
font-style: italic;
}
code {
background-color: #f4f4f4;
padding: 2px 5px;
border-radius: 3px;
font-family: 'Consolas', 'Monaco', monospace;
}
pre {
background-color: #f4f4f4;
padding: 15px;
border-radius: 5px;
overflow-x: auto;
}
.deprecated {
text-decoration: line-through;
opacity: 0.6;
}
.note {
background-color: #fff3cd;
border-left: 4px solid #ffc107;
padding: 10px;
margin: 10px 0;
}
.returns {
color: #28a745;
font-weight: bold;
}
</style>
</head>
<body>
<div class="container">
<h1>McRogueFace API Reference</h1>
<p><em>Generated on 2026-04-18 13:35:02</em></p>
<p><em>This documentation was dynamically generated from the compiled module.</em></p>
<div class="toc">
<h2>Table of Contents</h2>
<ul>
<li><a href="#functions">Functions</a></li>
<li><a href="#classes">Classes</a>
<ul>
<li><a href="#AStarPath">AStarPath</a></li>
<li><a href="#Alignment">Alignment</a></li>
<li><a href="#Arc">Arc</a></li>
<li><a href="#AutoRuleSet">AutoRuleSet</a></li>
<li><a href="#BSP">BSP</a></li>
<li><a href="#Behavior">Behavior</a></li>
<li><a href="#Billboard">Billboard</a></li>
<li><a href="#CallableBinding">CallableBinding</a></li>
<li><a href="#Caption">Caption</a></li>
<li><a href="#Circle">Circle</a></li>
<li><a href="#Color">Color</a></li>
<li><a href="#ColorLayer">ColorLayer</a></li>
<li><a href="#DijkstraMap">DijkstraMap</a></li>
<li><a href="#DiscreteMap">DiscreteMap</a></li>
<li><a href="#Drawable">Drawable</a></li>
<li><a href="#Easing">Easing</a></li>
<li><a href="#Entity">Entity</a></li>
<li><a href="#Entity3D">Entity3D</a></li>
<li><a href="#EntityCollection3D">EntityCollection3D</a></li>
<li><a href="#EntityCollection3DIter">EntityCollection3DIter</a></li>
<li><a href="#FOV">FOV</a></li>
<li><a href="#Font">Font</a></li>
<li><a href="#Frame">Frame</a></li>
<li><a href="#Grid">Grid</a></li>
<li><a href="#GridView">GridView</a></li>
<li><a href="#HeightMap">HeightMap</a></li>
<li><a href="#Heuristic">Heuristic</a></li>
<li><a href="#InputState">InputState</a></li>
<li><a href="#Key">Key</a></li>
<li><a href="#Keyboard">Keyboard</a></li>
<li><a href="#LdtkProject">LdtkProject</a></li>
<li><a href="#Line">Line</a></li>
<li><a href="#Model3D">Model3D</a></li>
<li><a href="#Mouse">Mouse</a></li>
<li><a href="#MouseButton">MouseButton</a></li>
<li><a href="#Music">Music</a></li>
<li><a href="#NoiseSource">NoiseSource</a></li>
<li><a href="#Perspective">Perspective</a></li>
<li><a href="#PropertyBinding">PropertyBinding</a></li>
<li><a href="#Scene">Scene</a></li>
<li><a href="#Shader">Shader</a></li>
<li><a href="#Sound">Sound</a></li>
<li><a href="#SoundBuffer">SoundBuffer</a></li>
<li><a href="#Sprite">Sprite</a></li>
<li><a href="#Texture">Texture</a></li>
<li><a href="#TileLayer">TileLayer</a></li>
<li><a href="#TileMapFile">TileMapFile</a></li>
<li><a href="#TileSetFile">TileSetFile</a></li>
<li><a href="#Timer">Timer</a></li>
<li><a href="#Transition">Transition</a></li>
<li><a href="#Traversal">Traversal</a></li>
<li><a href="#Trigger">Trigger</a></li>
<li><a href="#Vector">Vector</a></li>
<li><a href="#Viewport3D">Viewport3D</a></li>
<li><a href="#VoxelGrid">VoxelGrid</a></li>
<li><a href="#VoxelRegion">VoxelRegion</a></li>
<li><a href="#WangSet">WangSet</a></li>
<li><a href="#Window">Window</a></li>
</ul>
</li>
<li><a href="#constants">Constants</a></li>
</ul>
</div>
<h2 id="functions">Functions</h2>
<div class="method-section">
<h3><code class="function-signature">bresenham(start, end, *, include_start=True, include_end=True) -> list[tuple[int, int]]</code></h3>
<p>Compute grid cells along a line using Bresenham&#x27;s algorithm.
Note:</p>
<h4>Arguments:</h4>
<ul>
<li><span class='arg-name'>start</span>: (x, y) tuple or Vector - starting point</li>
<li><span class='arg-name'>end</span>: (x, y) tuple or Vector - ending point</li>
<li><span class='arg-name'>include_start</span>: Include the starting point in results (default: True)</li>
<li><span class='arg-name'>include_end</span>: Include the ending point in results (default: True)</li>
</ul>
<p><span class='returns'>Returns:</span> 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.</p>
</div>
<div class="method-section">
<h3><code class="function-signature">end_benchmark() -> str</code></h3>
<p>Stop benchmark capture and write data to JSON file.
Note:</p>
<p><span class='returns'>Returns:</span> str: The filename of the written benchmark data</p>
<p><span class='raises'>Raises:</span> RuntimeError: If no benchmark is currently running Returns the auto-generated filename (e.g., &#x27;benchmark_12345_20250528_143022.json&#x27;)</p>
</div>
<div class="method-section">
<h3><code class="function-signature">exit() -> None</code></h3>
<p>Cleanly shut down the game engine and exit the application.
Note:</p>
<p><span class='returns'>Returns:</span> None This immediately closes the window and terminates the program.</p>
</div>
<div class="method-section">
<h3><code class="function-signature">find(name: str, scene: str = None) -> UIDrawable | None</code></h3>
<p>Find the first UI element with the specified name.
Note:</p>
<h4>Arguments:</h4>
<ul>
<li><span class='arg-name'>name</span>: Exact name to search for</li>
<li><span class='arg-name'>scene</span>: Scene to search in (default: current scene)</li>
</ul>
<p><span class='returns'>Returns:</span> Frame, Caption, Sprite, Grid, or Entity if found; None otherwise Searches scene UI elements and entities within grids.</p>
</div>
<div class="method-section">
<h3><code class="function-signature">find_all(pattern: str, scene: str = None) -> list</code></h3>
<p>Find all UI elements matching a name pattern.
Note:</p>
<h4>Arguments:</h4>
<ul>
<li><span class='arg-name'>pattern</span>: Name pattern with optional wildcards (* matches any characters)</li>
<li><span class='arg-name'>scene</span>: Scene to search in (default: current scene)</li>
</ul>
<p><span class='returns'>Returns:</span> list: All matching UI elements and entities</p>
</div>
<div class="method-section">
<h3><code class="function-signature">get_metrics() -> dict</code></h3>
<p>Get current performance metrics.</p>
<p><span class='returns'>Returns:</span> 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)</p>
</div>
<div class="method-section">
<h3><code class="function-signature">lock() -> _LockContext</code></h3>
<p>Get a context manager for thread-safe UI updates from background threads.
Note:</p>
<p><span class='returns'>Returns:</span> _LockContext: A context manager that blocks until safe to modify UI Use with `with mcrfpy.lock():` to safely modify UI objects from a background thread. The context manager blocks until the render loop reaches a safe point between frames. Without this, modifying UI from threads may cause visual glitches or crashes.</p>
</div>
<div class="method-section">
<h3><code class="function-signature">log_benchmark(message: str) -> None</code></h3>
<p>Add a log message to the current benchmark frame.
Note:</p>
<h4>Arguments:</h4>
<ul>
<li><span class='arg-name'>message</span>: Text to associate with the current frame</li>
</ul>
<p><span class='returns'>Returns:</span> None</p>
<p><span class='raises'>Raises:</span> RuntimeError: If no benchmark is currently running Messages appear in the &#x27;logs&#x27; array of each frame in the output JSON.</p>
</div>
<div class="method-section">
<h3><code class="function-signature">set_dev_console(enabled: bool) -> None</code></h3>
<p>Enable or disable the developer console overlay.
Note:</p>
<h4>Arguments:</h4>
<ul>
<li><span class='arg-name'>enabled</span>: True to enable the console (default), False to disable</li>
</ul>
<p><span class='returns'>Returns:</span> None When disabled, the grave/tilde key will not open the console. Use this to ship games without debug features.</p>
</div>
<div class="method-section">
<h3><code class="function-signature">set_scale(multiplier: float) -> None</code></h3>
<p>Deprecated: use Window.resolution instead. Scale the game window size.
Note:</p>
<h4>Arguments:</h4>
<ul>
<li><span class='arg-name'>multiplier</span>: Scale factor (e.g., 2.0 for double size)</li>
</ul>
<p><span class='returns'>Returns:</span> None The internal resolution remains 1024x768, but the window is scaled. This is deprecated - use Window.resolution instead.</p>
</div>
<div class="method-section">
<h3><code class="function-signature">start_benchmark() -> None</code></h3>
<p>Start capturing benchmark data to a file.
Note:</p>
<p><span class='returns'>Returns:</span> None</p>
<p><span class='raises'>Raises:</span> RuntimeError: If a benchmark is already running Benchmark filename is auto-generated from PID and timestamp. Use end_benchmark() to stop and get filename.</p>
</div>
<div class="method-section">
<h3><code class="function-signature">step(dt: float = None) -> float</code></h3>
<p>Advance simulation time (headless mode only).
Note:</p>
<h4>Arguments:</h4>
<ul>
<li><span class='arg-name'>dt</span>: Time to advance in seconds. If None, advances to the next scheduled event (timer/animation).</li>
</ul>
<p><span class='returns'>Returns:</span> 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.</p>
</div>
<h2 id='classes'>Classes</h2>
<div class="method-section">
<h3 id="AStarPath"><span class="class-name">AStarPath</span></h3>
<p>A computed A* path result, consumed step by step.
Created by Grid.find_path(). Cannot be instantiated directly.
Use walk() to get and consume each step, or iterate directly.
Use peek() to see the next step without consuming it.
Use bool(path) or len(path) to check if steps remain.
Properties:
origin (Vector): Starting position (read-only)
destination (Vector): Ending position (read-only)
remaining (int): Steps remaining (read-only)
Example:
path = grid.find_path(start, end)
if path:
while path:
next_pos = path.walk()
entity.pos = next_pos</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>destination</span> (read-only): Ending position of the path (Vector, read-only).</li>
<li><span class='property-name'>origin</span> (read-only): Starting position of the path (Vector, read-only).</li>
<li><span class='property-name'>remaining</span> (read-only): Number of steps remaining in the path (int, read-only).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">peek() -> Vector</code></h5>
<p>See next step without consuming it.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Next position as Vector.</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> IndexError: If path is exhausted.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">walk() -> Vector</code></h5>
<p>Get and consume next step in the path.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Next position as Vector.</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> IndexError: If path is exhausted.</p>
</div>
</div>
<div class="method-section">
<h3 id="Alignment"><span class="class-name">Alignment</span></h3>
<p><em>Inherits from: IntEnum</em></p>
<p>Alignment enum for positioning UI elements relative to parent bounds.
Values:
TOP_LEFT, TOP_CENTER, TOP_RIGHT
CENTER_LEFT, CENTER, CENTER_RIGHT
BOTTOM_LEFT, BOTTOM_CENTER, BOTTOM_RIGHT
Margin Validation Rules:
Margins define distance from parent edge when aligned.
- CENTER: No margins allowed (raises ValueError if margin != 0)
- TOP_CENTER, BOTTOM_CENTER: Only vert_margin applies (horiz_margin raises ValueError)
- CENTER_LEFT, CENTER_RIGHT: Only horiz_margin applies (vert_margin raises ValueError)
- Corner alignments (TOP_LEFT, etc.): All margins valid
Properties:
align: Alignment value or None to disable
margin: General margin for all applicable edges
horiz_margin: Override for horizontal edge (0 = use general margin)
vert_margin: Override for vertical edge (0 = use general margin)
Example:
# Center a panel in the scene
panel = Frame(size=(200, 100), align=Alignment.CENTER)
scene.children.append(panel)
# Place button in bottom-right with 10px margin
button = Frame(size=(80, 30), align=Alignment.BOTTOM_RIGHT, margin=10)
panel.children.append(button)</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">as_integer_ratio(...)</code></h5>
<p>Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
&gt;&gt;&gt; (10).as_integer_ratio()
(10, 1)
&gt;&gt;&gt; (-10).as_integer_ratio()
(-10, 1)
&gt;&gt;&gt; (0).as_integer_ratio()
(0, 1)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_count(...)</code></h5>
<p>Number of ones in the binary representation of the absolute value of self.
Also known as the population count.
&gt;&gt;&gt; bin(13)
&#x27;0b1101&#x27;
&gt;&gt;&gt; (13).bit_count()
3</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_length(...)</code></h5>
<p>Number of bits necessary to represent self in binary.
&gt;&gt;&gt; bin(37)
&#x27;0b100101&#x27;
&gt;&gt;&gt; (37).bit_length()
6</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">conjugate(...)</code></h5>
<p>Returns self, the complex conjugate of any int.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Indicates whether two&#x27;s complement is used to represent the integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_integer(...)</code></h5>
<p>Returns True. Exists for duck type compatibility with float.is_integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Determines whether two&#x27;s complement is used to represent the integer.
If signed is False and a negative integer is given, an OverflowError
is raised.</p>
</div>
</div>
<div class="method-section">
<h3 id="Arc"><span class="class-name">Arc</span></h3>
<p><em>Inherits from: Drawable</em></p>
<p>Arc(center=None, radius=0, start_angle=0, end_angle=90, color=None, thickness=1, **kwargs)
An arc UI element for drawing curved line segments.
Args:
center (tuple, optional): Center position as (x, y). Default: (0, 0)
radius (float, optional): Arc radius in pixels. Default: 0
start_angle (float, optional): Starting angle in degrees. Default: 0
end_angle (float, optional): Ending angle in degrees. Default: 90
color (Color, optional): Arc color. Default: White
thickness (float, optional): Line thickness. Default: 1.0
Keyword Args:
on_click (callable): Click handler. Default: None
visible (bool): Visibility state. Default: True
opacity (float): Opacity (0.0-1.0). Default: 1.0
z_index (int): Rendering order. Default: 0
name (str): Element name for finding. Default: None
align (Alignment): Alignment relative to parent. Default: None
margin (float): Margin from parent edge when aligned. Default: 0
horiz_margin (float): Horizontal margin override. Default: 0 (use margin)
vert_margin (float): Vertical margin override. Default: 0 (use margin)
Attributes:
center (Vector): Center position
radius (float): Arc radius
start_angle (float): Starting angle in degrees
end_angle (float): Ending angle in degrees
color (Color): Arc color
thickness (float): Line thickness
visible (bool): Visibility state
opacity (float): Opacity value
z_index (int): Rendering order
name (str): Element name
align (Alignment): Alignment relative to parent (or None)
margin (float): General margin for alignment
horiz_margin (float): Horizontal margin override
vert_margin (float): Vertical margin override
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>align</span>: 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.</li>
<li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>center</span>: Center position of the arc</li>
<li><span class='property-name'>color</span>: Arc color</li>
<li><span class='property-name'>end_angle</span>: Ending angle in degrees</li>
<li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>grid_pos</span>: Position in grid tile coordinates (only when parent is Grid)</li>
<li><span class='property-name'>grid_size</span>: Size in grid tile coordinates (only when parent is Grid)</li>
<li><span class='property-name'>horiz_margin</span>: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
<li><span class='property-name'>name</span>: Name for finding this element.</li>
<li><span class='property-name'>on_click</span>: Callable executed when arc is clicked. Function receives (pos: Vector, button: str, action: str).</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: 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.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position as a Vector (same as center).</li>
<li><span class='property-name'>radius</span>: Arc radius in pixels</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>start_angle</span>: Starting angle in degrees</li>
<li><span class='property-name'>thickness</span>: Line thickness</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation</code></h5>
<p>Create and start an animation on this drawable&#x27;s property.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>property</span>: Name of the property to animate (e.g., &#x27;x&#x27;, &#x27;fill_color&#x27;, &#x27;opacity&#x27;)</div>
<div><span class='arg-name'>target</span>: Target value - type depends on property (float, tuple for color/vector, etc.)</div>
<div><span class='arg-name'>duration</span>: Animation duration in seconds</div>
<div><span class='arg-name'>easing</span>: Easing function: Easing enum value, string name, or None for linear</div>
<div><span class='arg-name'>delta</span>: If True, target is relative to current value; if False, target is absolute</div>
<div><span class='arg-name'>loop</span>: If True, animation repeats from start when it reaches the end (default False)</div>
<div><span class='arg-name'>callback</span>: Optional callable invoked when animation completes (not called for looping animations)</div>
<div><span class='arg-name'>conflict_mode</span>: &#x27;replace&#x27; (default), &#x27;queue&#x27;, or &#x27;error&#x27; if property already animating</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Animation object for monitoring progress</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> 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.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx, dy) or (delta) -> None</code></h5>
<p>Move the element by a relative offset.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>dx</span>: Horizontal offset in pixels (or use delta)</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels (or use delta)</div>
<div><span class='arg-name'>delta</span>: Offset as tuple, list, or Vector: (dx, dy)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">realign() -> None</code></h5>
<p>Reapply alignment relative to parent, useful for responsive layouts.
Note:
Call this to recalculate position after parent changes size. For elements with align=None, this has no effect.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width, height) or (size) -> None</code></h5>
<p>Resize the element to new dimensions.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>width</span>: New width in pixels (or use size)</div>
<div><span class='arg-name'>height</span>: New height in pixels (or use size)</div>
<div><span class='arg-name'>size</span>: Size as tuple, list, or Vector: (width, height)</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="AutoRuleSet"><span class="class-name">AutoRuleSet</span></h3>
<p>AutoRuleSet - LDtk auto-tile rule set for pattern-based terrain rendering.
AutoRuleSets are obtained from LdtkProject.ruleset().
They map IntGrid terrain values to sprite tiles using LDtk&#x27;s
pattern-matching auto-rule system.
Properties:
name (str, read-only): Rule set name (layer identifier).
grid_size (int, read-only): Cell size in pixels.
value_count (int, read-only): Number of IntGrid values.
values (list, read-only): List of value dicts.
rule_count (int, read-only): Total rules across all groups.
group_count (int, read-only): Number of rule groups.
Example:
rs = project.ruleset(&#x27;Walls&#x27;)
Terrain = rs.terrain_enum()
rs.apply(discrete_map, tile_layer, seed=42)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>grid_size</span> (read-only): Cell size in pixels (int, read-only).</li>
<li><span class='property-name'>group_count</span> (read-only): Number of rule groups (int, read-only).</li>
<li><span class='property-name'>name</span> (read-only): Rule set name / layer identifier (str, read-only).</li>
<li><span class='property-name'>rule_count</span> (read-only): Total number of rules across all groups (int, read-only).</li>
<li><span class='property-name'>value_count</span> (read-only): Number of IntGrid terrain values (int, read-only).</li>
<li><span class='property-name'>values</span> (read-only): List of IntGrid value dicts with value and name (read-only).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">apply(discrete_map: DiscreteMap, tile_layer: TileLayer, seed: int = 0) -> None</code></h5>
<p>Resolve auto-rules and write tile indices directly into a TileLayer.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>discrete_map</span>: A DiscreteMap with IntGrid values</div>
<div><span class='arg-name'>tile_layer</span>: Target TileLayer to write resolved tiles into</div>
<div><span class='arg-name'>seed</span>: Random seed for deterministic results (default: 0)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resolve(discrete_map: DiscreteMap, seed: int = 0) -> list[int]</code></h5>
<p>Resolve IntGrid data to tile indices using LDtk auto-rules.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>discrete_map</span>: A DiscreteMap with IntGrid values matching this rule set</div>
<div><span class='arg-name'>seed</span>: Random seed for deterministic tile selection and probability (default: 0)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of tile IDs (one per cell). -1 means no matching rule.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">terrain_enum() -> IntEnum</code></h5>
<p>Generate a Python IntEnum from this rule set&#x27;s IntGrid values.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> IntEnum class with NONE=0 and one member per IntGrid value (UPPER_SNAKE_CASE).</p>
</div>
</div>
<div class="method-section">
<h3 id="BSP"><span class="class-name">BSP</span></h3>
<p>BSP(pos: tuple[int, int], size: tuple[int, int])
Binary Space Partitioning tree for procedural dungeon generation.
BSP recursively divides a rectangular region into smaller sub-regions, creating a tree structure perfect for generating dungeon rooms and corridors.
Args:
pos: (x, y) - Top-left position of the root region.
size: (w, h) - Width and height of the root region.
Properties:
pos (tuple[int, int]): Read-only. Top-left position (x, y).
size (tuple[int, int]): Read-only. Dimensions (width, height).
bounds ((pos), (size)): Read-only. Combined position and size.
root (BSPNode): Read-only. Reference to the root node.
Iteration:
for leaf in bsp: # Iterates over leaf nodes (rooms)
len(bsp) # Returns number of leaf nodes
Example:
bsp = mcrfpy.BSP(pos=(0, 0), size=(80, 50))
bsp.split_recursive(depth=4, min_size=(8, 8))
for leaf in bsp:
print(f&#x27;Room at {leaf.pos}, size {leaf.size}&#x27;)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>adjacency</span> (read-only): Leaf adjacency graph. adjacency[i] returns tuple of neighbor indices. Read-only.</li>
<li><span class='property-name'>bounds</span> (read-only): Root node bounds as ((x, y), (w, h)). Read-only.</li>
<li><span class='property-name'>pos</span> (read-only): Top-left position (x, y). Read-only.</li>
<li><span class='property-name'>root</span> (read-only): Reference to the root BSPNode. Read-only.</li>
<li><span class='property-name'>size</span> (read-only): Dimensions (width, height). Read-only.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">clear() -> BSP</code></h5>
<p>Remove all children, keeping only the root node with original bounds. WARNING: Invalidates all existing BSPNode references from this tree.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> BSP: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">find(pos: tuple[int, int]) -> BSPNode | None</code></h5>
<p>Find the smallest (deepest) node containing the position.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Position as (x, y) tuple, list, or Vector</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> BSPNode if found, None if position is outside bounds</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get_leaf(index: int) -> BSPNode</code></h5>
<p>Get a leaf node by its index (0 to len(bsp)-1). This is useful when working with adjacency data, which returns leaf indices.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>index</span>: Leaf index (0 to len(bsp)-1). Negative indices supported.</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> BSPNode at the specified index</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> IndexError: If index is out of range</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">leaves() -> Iterator[BSPNode]</code></h5>
<p>Iterate all leaf nodes (the actual rooms). Same as iterating the BSP directly.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Iterator yielding BSPNode objects</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">split_once(horizontal: bool, position: int) -> BSP</code></h5>
<p>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.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>horizontal</span>: True for horizontal divider (top/bottom), False for vertical (left/right)</div>
<div><span class='arg-name'>position</span>: Split coordinate (y for horizontal, x for vertical)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> BSP: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">split_recursive(depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int = None) -> BSP</code></h5>
<p>Recursively split to the specified depth. WARNING: Invalidates all existing BSPNode references from this tree.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>depth</span>: Maximum recursion depth (1-16). Creates up to 2^depth leaves.</div>
<div><span class='arg-name'>min_size</span>: Minimum (width, height) for a node to be split.</div>
<div><span class='arg-name'>max_ratio</span>: Maximum aspect ratio before forcing split direction. Default: 1.5.</div>
<div><span class='arg-name'>seed</span>: Random seed. None for random.</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> BSP: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_heightmap(size: tuple[int, int] = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap</code></h5>
<p>Convert BSP node selection to a HeightMap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>size</span>: Output size (width, height). Default: bounds size.</div>
<div><span class='arg-name'>select</span>: &#x27;leaves&#x27;, &#x27;all&#x27;, or &#x27;internal&#x27;. Default: &#x27;leaves&#x27;.</div>
<div><span class='arg-name'>shrink</span>: Pixels to shrink from each node&#x27;s bounds. Default: 0.</div>
<div><span class='arg-name'>value</span>: Value inside selected regions. Default: 1.0.</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap with selected regions filled</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">traverse(order: Traversal = Traversal.LEVEL_ORDER) -> Iterator[BSPNode]</code></h5>
<p>Iterate all nodes in the specified order.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>order</span>: Traversal order from Traversal enum. Default: LEVEL_ORDER.</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Iterator yielding BSPNode objects Orders: PRE_ORDER, IN_ORDER, POST_ORDER, LEVEL_ORDER, INVERTED_LEVEL_ORDER</p>
</div>
</div>
<div class="method-section">
<h3 id="Behavior"><span class="class-name">Behavior</span></h3>
<p><em>Inherits from: IntEnum</em></p>
<p>Enum representing entity behavior types for grid.step() turn management.
Values:
IDLE: No action each turn
CUSTOM: Calls step callback only, no built-in movement
NOISE4: Random movement in 4 cardinal directions
NOISE8: Random movement in 8 directions (incl. diagonals)
PATH: Follow a precomputed path to completion
WAYPOINT: Path through a sequence of waypoints in order
PATROL: Patrol waypoints back and forth (reversing at ends)
LOOP: Loop through waypoints cyclically
SLEEP: Wait for N turns, then trigger DONE
SEEK: Move toward target using Dijkstra map
FLEE: Move away from target using Dijkstra map
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">as_integer_ratio(...)</code></h5>
<p>Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
&gt;&gt;&gt; (10).as_integer_ratio()
(10, 1)
&gt;&gt;&gt; (-10).as_integer_ratio()
(-10, 1)
&gt;&gt;&gt; (0).as_integer_ratio()
(0, 1)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_count(...)</code></h5>
<p>Number of ones in the binary representation of the absolute value of self.
Also known as the population count.
&gt;&gt;&gt; bin(13)
&#x27;0b1101&#x27;
&gt;&gt;&gt; (13).bit_count()
3</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_length(...)</code></h5>
<p>Number of bits necessary to represent self in binary.
&gt;&gt;&gt; bin(37)
&#x27;0b100101&#x27;
&gt;&gt;&gt; (37).bit_length()
6</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">conjugate(...)</code></h5>
<p>Returns self, the complex conjugate of any int.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Indicates whether two&#x27;s complement is used to represent the integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_integer(...)</code></h5>
<p>Returns True. Exists for duck type compatibility with float.is_integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Determines whether two&#x27;s complement is used to represent the integer.
If signed is False and a negative integer is given, an OverflowError
is raised.</p>
</div>
</div>
<div class="method-section">
<h3 id="Billboard"><span class="class-name">Billboard</span></h3>
<p>Billboard(texture=None, sprite_index=0, pos=(0,0,0), scale=1.0, facing=&#x27;camera_y&#x27;)
A camera-facing 3D sprite for trees, items, particles, etc.
Args:
texture (Texture, optional): Sprite sheet texture. Default: None
sprite_index (int): Index into sprite sheet. Default: 0
pos (tuple): World position (x, y, z). Default: (0, 0, 0)
scale (float): Uniform scale factor. Default: 1.0
facing (str): Facing mode - &#x27;camera&#x27;, &#x27;camera_y&#x27;, or &#x27;fixed&#x27;. Default: &#x27;camera_y&#x27;
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 - &#x27;camera&#x27;, &#x27;camera_y&#x27;, or &#x27;fixed&#x27;
theta (float): Horizontal rotation for &#x27;fixed&#x27; mode (radians)
phi (float): Vertical tilt for &#x27;fixed&#x27; mode (radians)
opacity (float): Opacity 0.0 (transparent) to 1.0 (opaque)
visible (bool): Visibility state</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>facing</span>: Facing mode: &#x27;camera&#x27;, &#x27;camera_y&#x27;, or &#x27;fixed&#x27; (str)</li>
<li><span class='property-name'>opacity</span>: Opacity from 0.0 (transparent) to 1.0 (opaque) (float)</li>
<li><span class='property-name'>phi</span>: Vertical tilt for &#x27;fixed&#x27; mode in radians (float)</li>
<li><span class='property-name'>pos</span>: World position as (x, y, z) tuple</li>
<li><span class='property-name'>scale</span>: Uniform scale factor (float)</li>
<li><span class='property-name'>sprite_index</span>: Index into sprite sheet (int)</li>
<li><span class='property-name'>texture</span>: Sprite sheet texture (Texture or None)</li>
<li><span class='property-name'>theta</span>: Horizontal rotation for &#x27;fixed&#x27; mode in radians (float)</li>
<li><span class='property-name'>visible</span>: Visibility state (bool)</li>
</ul>
<h4>Methods:</h4>
</div>
<div class="method-section">
<h3 id="CallableBinding"><span class="class-name">CallableBinding</span></h3>
<p>CallableBinding(callable: Callable[[], float])
A binding that calls a Python function to get its value.
Args:
callable: A function that takes no arguments and returns a float
The callable is invoked every frame when the shader is rendered.
Keep the callable lightweight to avoid performance issues.
Example:
player_health = 100
frame.uniforms[&#x27;health_pct&#x27;] = mcrfpy.CallableBinding(
lambda: player_health / 100.0
)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>callable</span> (read-only): The Python callable (read-only).</li>
<li><span class='property-name'>is_valid</span> (read-only): True if the callable is still valid (bool, read-only).</li>
<li><span class='property-name'>value</span> (read-only): Current value from calling the callable (float, read-only). Returns None on error.</li>
</ul>
<h4>Methods:</h4>
</div>
<div class="method-section">
<h3 id="Caption"><span class="class-name">Caption</span></h3>
<p><em>Inherits from: Drawable</em></p>
<p>Caption(pos=None, font=None, text=&#x27;&#x27;, **kwargs)
A text display UI element with customizable font and styling.
Args:
pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0)
font (Font, optional): Font object for text rendering. Default: engine default font
text (str, optional): The text content to display. Default: &#x27;&#x27;
Keyword Args:
fill_color (Color): Text fill color. Default: (255, 255, 255, 255)
outline_color (Color): Text outline color. Default: (0, 0, 0, 255)
outline (float): Text outline thickness. Default: 0
font_size (float): Font size in points. Default: 16
click (callable): Click event handler. Default: None
visible (bool): Visibility state. Default: True
opacity (float): Opacity (0.0-1.0). Default: 1.0
z_index (int): Rendering order. Default: 0
name (str): Element name for finding. Default: None
x (float): X position override. Default: 0
y (float): Y position override. Default: 0
align (Alignment): Alignment relative to parent. Default: None
margin (float): Margin from parent edge when aligned. Default: 0
horiz_margin (float): Horizontal margin override. Default: 0 (use margin)
vert_margin (float): Vertical margin override. Default: 0 (use margin)
Attributes:
text (str): The displayed text content
x, y (float): Position in pixels
pos (Vector): Position as a Vector object
font (Font): Font used for rendering
font_size (float): Font size in points
fill_color, outline_color (Color): Text appearance
outline (float): Outline thickness
click (callable): Click event handler
visible (bool): Visibility state
opacity (float): Opacity value
z_index (int): Rendering order
name (str): Element name
w, h (float): Read-only computed size based on text and font
align (Alignment): Alignment relative to parent (or None)
margin (float): General margin for alignment
horiz_margin (float): Horizontal margin override
vert_margin (float): Vertical margin override</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>align</span>: 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.</li>
<li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>fill_color</span>: Fill color of the text. Returns a copy; modifying components requires reassignment. For animation, use &#x27;fill_color.r&#x27;, &#x27;fill_color.g&#x27;, etc.</li>
<li><span class='property-name'>font_size</span>: Font size (integer) in points</li>
<li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>grid_pos</span>: Position in grid tile coordinates (only when parent is Grid)</li>
<li><span class='property-name'>grid_size</span>: Size in grid tile coordinates (only when parent is Grid)</li>
<li><span class='property-name'>h</span> (read-only): Text height in pixels (read-only)</li>
<li><span class='property-name'>horiz_margin</span>: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
<li><span class='property-name'>name</span>: Name for finding elements</li>
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: 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.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>outline</span>: Thickness of the border</li>
<li><span class='property-name'>outline_color</span>: Outline color of the text. Returns a copy; modifying components requires reassignment. For animation, use &#x27;outline_color.r&#x27;, &#x27;outline_color.g&#x27;, etc.</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: (x, y) vector</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>shader</span>: 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.</li>
<li><span class='property-name'>size</span> (read-only): Text dimensions as Vector (read-only)</li>
<li><span class='property-name'>text</span>: The text displayed</li>
<li><span class='property-name'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>w</span> (read-only): Text width in pixels (read-only)</li>
<li><span class='property-name'>x</span>: X coordinate of top-left corner</li>
<li><span class='property-name'>y</span>: Y coordinate of top-left corner</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation</code></h5>
<p>Create and start an animation on this drawable&#x27;s property.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>property</span>: Name of the property to animate (e.g., &#x27;x&#x27;, &#x27;fill_color&#x27;, &#x27;opacity&#x27;)</div>
<div><span class='arg-name'>target</span>: Target value - type depends on property (float, tuple for color/vector, etc.)</div>
<div><span class='arg-name'>duration</span>: Animation duration in seconds</div>
<div><span class='arg-name'>easing</span>: Easing function: Easing enum value, string name, or None for linear</div>
<div><span class='arg-name'>delta</span>: If True, target is relative to current value; if False, target is absolute</div>
<div><span class='arg-name'>loop</span>: If True, animation repeats from start when it reaches the end (default False)</div>
<div><span class='arg-name'>callback</span>: Optional callable invoked when animation completes (not called for looping animations)</div>
<div><span class='arg-name'>conflict_mode</span>: &#x27;replace&#x27; (default), &#x27;queue&#x27;, or &#x27;error&#x27; if property already animating</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Animation object for monitoring progress</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> 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.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx, dy) or (delta) -> None</code></h5>
<p>Move the element by a relative offset.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>dx</span>: Horizontal offset in pixels (or use delta)</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels (or use delta)</div>
<div><span class='arg-name'>delta</span>: Offset as tuple, list, or Vector: (dx, dy)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">realign() -> None</code></h5>
<p>Reapply alignment relative to parent, useful for responsive layouts.
Note:
Call this to recalculate position after parent changes size. For elements with align=None, this has no effect.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width, height) or (size) -> None</code></h5>
<p>Resize the element to new dimensions.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>width</span>: New width in pixels (or use size)</div>
<div><span class='arg-name'>height</span>: New height in pixels (or use size)</div>
<div><span class='arg-name'>size</span>: Size as tuple, list, or Vector: (width, height)</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="Circle"><span class="class-name">Circle</span></h3>
<p><em>Inherits from: Drawable</em></p>
<p>Circle(radius=0, center=None, fill_color=None, outline_color=None, outline=0, **kwargs)
A circle UI element for drawing filled or outlined circles.
Args:
radius (float, optional): Circle radius in pixels. Default: 0
center (tuple, optional): Center position as (x, y). Default: (0, 0)
fill_color (Color, optional): Fill color. Default: White
outline_color (Color, optional): Outline color. Default: Transparent
outline (float, optional): Outline thickness. Default: 0 (no outline)
Keyword Args:
on_click (callable): Click handler. Default: None
visible (bool): Visibility state. Default: True
opacity (float): Opacity (0.0-1.0). Default: 1.0
z_index (int): Rendering order. Default: 0
name (str): Element name for finding. Default: None
align (Alignment): Alignment relative to parent. Default: None
margin (float): Margin from parent edge when aligned. Default: 0
horiz_margin (float): Horizontal margin override. Default: 0 (use margin)
vert_margin (float): Vertical margin override. Default: 0 (use margin)
Attributes:
radius (float): Circle radius
center (Vector): Center position
fill_color (Color): Fill color
outline_color (Color): Outline color
outline (float): Outline thickness
visible (bool): Visibility state
opacity (float): Opacity value
z_index (int): Rendering order
name (str): Element name
align (Alignment): Alignment relative to parent (or None)
margin (float): General margin for alignment
horiz_margin (float): Horizontal margin override
vert_margin (float): Vertical margin override
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>align</span>: 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.</li>
<li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>center</span>: Center position of the circle</li>
<li><span class='property-name'>fill_color</span>: Fill color of the circle</li>
<li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>grid_pos</span>: Position in grid tile coordinates (only when parent is Grid)</li>
<li><span class='property-name'>grid_size</span>: Size in grid tile coordinates (only when parent is Grid)</li>
<li><span class='property-name'>horiz_margin</span>: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
<li><span class='property-name'>name</span>: Name for finding this element.</li>
<li><span class='property-name'>on_click</span>: Callable executed when circle is clicked. Function receives (pos: Vector, button: str, action: str).</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: 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.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>outline</span>: Outline thickness (0 for no outline)</li>
<li><span class='property-name'>outline_color</span>: Outline color of the circle</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position as a Vector (same as center).</li>
<li><span class='property-name'>radius</span>: Circle radius in pixels</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation</code></h5>
<p>Create and start an animation on this drawable&#x27;s property.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>property</span>: Name of the property to animate (e.g., &#x27;x&#x27;, &#x27;fill_color&#x27;, &#x27;opacity&#x27;)</div>
<div><span class='arg-name'>target</span>: Target value - type depends on property (float, tuple for color/vector, etc.)</div>
<div><span class='arg-name'>duration</span>: Animation duration in seconds</div>
<div><span class='arg-name'>easing</span>: Easing function: Easing enum value, string name, or None for linear</div>
<div><span class='arg-name'>delta</span>: If True, target is relative to current value; if False, target is absolute</div>
<div><span class='arg-name'>loop</span>: If True, animation repeats from start when it reaches the end (default False)</div>
<div><span class='arg-name'>callback</span>: Optional callable invoked when animation completes (not called for looping animations)</div>
<div><span class='arg-name'>conflict_mode</span>: &#x27;replace&#x27; (default), &#x27;queue&#x27;, or &#x27;error&#x27; if property already animating</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Animation object for monitoring progress</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> 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.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx, dy) or (delta) -> None</code></h5>
<p>Move the element by a relative offset.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>dx</span>: Horizontal offset in pixels (or use delta)</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels (or use delta)</div>
<div><span class='arg-name'>delta</span>: Offset as tuple, list, or Vector: (dx, dy)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">realign() -> None</code></h5>
<p>Reapply alignment relative to parent, useful for responsive layouts.
Note:
Call this to recalculate position after parent changes size. For elements with align=None, this has no effect.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width, height) or (size) -> None</code></h5>
<p>Resize the element to new dimensions.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>width</span>: New width in pixels (or use size)</div>
<div><span class='arg-name'>height</span>: New height in pixels (or use size)</div>
<div><span class='arg-name'>size</span>: Size as tuple, list, or Vector: (width, height)</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="Color"><span class="class-name">Color</span></h3>
<p>Color(r: int = 0, g: int = 0, b: int = 0, a: int = 255)
RGBA color representation.
Args:
r: Red component (0-255)
g: Green component (0-255)
b: Blue component (0-255)
a: Alpha component (0-255, default 255 = opaque)
Note:
When accessing colors from UI elements (e.g., frame.fill_color),
you receive a COPY of the color. Modifying it doesn&#x27;t affect the
original. To change a component:
# This does NOT work:
frame.fill_color.r = 255 # Modifies a temporary copy
# Do this instead:
c = frame.fill_color
c.r = 255
frame.fill_color = c
# Or use Animation for sub-properties:
anim = mcrfpy.Animation(&#x27;fill_color.r&#x27;, 255, 0.5, &#x27;linear&#x27;)
anim.start(frame)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>a</span>: Alpha component (0-255, where 0=transparent, 255=opaque). Automatically clamped to valid range.</li>
<li><span class='property-name'>b</span>: Blue component (0-255). Automatically clamped to valid range.</li>
<li><span class='property-name'>g</span>: Green component (0-255). Automatically clamped to valid range.</li>
<li><span class='property-name'>r</span>: Red component (0-255). Automatically clamped to valid range.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_hex(hex_string: str) -> Color</code></h5>
<p>Create a Color from a hexadecimal string.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>hex_string</span>: Hex color string (e.g., &#x27;#FF0000&#x27;, &#x27;FF0000&#x27;, &#x27;#AABBCCDD&#x27; for RGBA)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Color: New Color object with values from hex string</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: If hex string is not 6 or 8 characters (RGB or RGBA) This is a class method. Call as Color.from_hex(&#x27;#FF0000&#x27;)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">lerp(other: Color, t: float) -> Color</code></h5>
<p>Linearly interpolate between this color and another.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: The target Color to interpolate towards</div>
<div><span class='arg-name'>t</span>: Interpolation factor (0.0 = this color, 1.0 = other color). Automatically clamped to [0.0, 1.0]</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Color: New Color representing the interpolated value All components (r, g, b, a) are interpolated independently</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_hex() -> str</code></h5>
<p>Convert this Color to a hexadecimal string.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> str: Hex string in format &#x27;#RRGGBB&#x27; or &#x27;#RRGGBBAA&#x27; (if alpha &lt; 255) Alpha component is only included if not fully opaque (&lt; 255)</p>
</div>
</div>
<div class="method-section">
<h3 id="ColorLayer"><span class="class-name">ColorLayer</span></h3>
<p>ColorLayer(z_index=-1, name=None, grid_size=None)
A grid layer that stores RGBA colors per cell for background/overlay effects.
ColorLayers can be created standalone and attached to a Grid via add_layer()
or passed to the Grid constructor&#x27;s layers parameter. Layers with size (0, 0)
automatically resize to match the Grid when attached.
Args:
z_index (int): Render order relative to entities. Negative values render
below entities (as backgrounds), positive values render above entities
(as overlays). Default: -1 (background)
name (str): Layer name for Grid.layer(name) lookup. Default: None
grid_size (tuple): Dimensions as (width, height). If None or (0, 0), the
layer will auto-resize when attached to a Grid. Default: None
Attributes:
z_index (int): Layer z-order relative to entities (read/write)
name (str): Layer name for lookup (read-only)
visible (bool): Whether layer is rendered (read/write)
grid_size (tuple): Layer dimensions as (width, height) (read-only)
grid (Grid): Parent Grid or None. Setting manages layer association.
Methods:
at(x, y) -&gt; Color: Get the color at cell position (x, y)
set(x, y, color): Set the color at cell position (x, y)
fill(color): Fill the entire layer with a single color
fill_rect(x, y, w, h, color): Fill a rectangular region with a color
draw_fov(...): Draw FOV-based visibility colors
apply_perspective(entity, ...): Bind layer to entity for automatic FOV updates
Example:
fog = mcrfpy.ColorLayer(z_index=-1, name=&#x27;fog&#x27;)
grid = mcrfpy.Grid(grid_size=(20, 15), layers=[fog])
fog.fill(mcrfpy.Color(40, 40, 40)) # Dark gray background
grid.layer(&#x27;fog&#x27;).set(5, 5, mcrfpy.Color(255, 0, 0, 128))</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>grid</span>: Parent Grid or None. Setting manages layer association and handles lazy allocation.</li>
<li><span class='property-name'>grid_size</span>: Layer dimensions as (width, height) tuple.</li>
<li><span class='property-name'>name</span> (read-only): Layer name (str, read-only). Used for Grid.layer(name) lookup.</li>
<li><span class='property-name'>visible</span>: Whether the layer is rendered.</li>
<li><span class='property-name'>z_index</span>: Layer z-order. Negative values render below entities.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">apply_gradient(source, range, color_low, color_high) -> ColorLayer</code></h5>
<p>Interpolate between colors based on HeightMap value within range.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>color_low</span>: Color at range minimum</div>
<div><span class='arg-name'>color_high</span>: Color at range maximum</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> self for method chaining Uses the original HeightMap value for interpolation, not binary. This allows smooth color transitions within a value range.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">apply_perspective(entity, visible=None, discovered=None, unknown=None)</code></h5>
<p>Bind this layer to an entity for automatic FOV updates.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">apply_ranges(source, ranges) -> ColorLayer</code></h5>
<p>Apply multiple color assignments in a single pass.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> self for method chaining Later ranges override earlier ones if overlapping. Cells not matching any range are left unchanged.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">apply_threshold(source, range, color) -> ColorLayer</code></h5>
<p>Set fixed color for cells where HeightMap value is within range.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>color</span>: Color or (r, g, b[, a]) tuple to set for cells in range</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> self for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">at(pos) -> Color</code></h5>
<p>at(x, y) -&gt; Color
Get the color at cell position.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Position as (x, y) tuple, list, or Vector</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">clear_perspective()</code></h5>
<p>Remove the perspective binding from this layer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">draw_fov(source, radius=None, fov=None, visible=None, discovered=None, unknown=None)</code></h5>
<p>Paint cells based on field-of-view visibility from source position.
Note: Layer must be attached to a grid for FOV calculation.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill(color)</code></h5>
<p>Fill the entire layer with the specified color.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill_rect(pos, size, color)</code></h5>
<p>Fill a rectangular region with a color.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>color</span>: Color object or (r, g, b[, a]) tuple</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">set(pos, color)</code></h5>
<p>Set the color at cell position.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Position as (x, y) tuple, list, or Vector</div>
<div><span class='arg-name'>color</span>: Color object or (r, g, b[, a]) tuple</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">update_perspective()</code></h5>
<p>Redraw FOV based on the bound entity&#x27;s current position.
Call this after the entity moves to update the visibility layer.</p>
</div>
</div>
<div class="method-section">
<h3 id="DijkstraMap"><span class="class-name">DijkstraMap</span></h3>
<p>A Dijkstra distance map from a fixed root position.
Created by Grid.get_dijkstra_map(). Cannot be instantiated directly.
Grid caches these maps - multiple requests for the same root return
the same map. Call Grid.clear_dijkstra_maps() after changing grid
walkability to invalidate the cache.
Properties:
root (Vector): Root position (read-only)
Methods:
distance(pos) -&gt; float | None: Get distance to root
path_from(pos) -&gt; AStarPath: Get full path to root
step_from(pos) -&gt; Vector | None: Get single step toward root
Example:
dijkstra = grid.get_dijkstra_map(player.pos)
for enemy in enemies:
dist = dijkstra.distance(enemy.pos)
if dist and dist &lt; 10:
step = dijkstra.step_from(enemy.pos)
if step:
enemy.pos = step</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>root</span> (read-only): Root position that distances are measured from (Vector, read-only).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">descent_step(pos) -> Vector | None</code></h5>
<p>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.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Current position as Vector, Entity, or (x, y) tuple.</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Next position as Vector, or None if pos is a local minimum or off-grid.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">distance(pos) -> float | None</code></h5>
<p>Get distance from position to root.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Position as Vector, Entity, or (x, y) tuple.</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Float distance, or None if position is unreachable.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">invert() -> DijkstraMap</code></h5>
<p>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.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> New DijkstraMap with inverted distances.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">path_from(pos) -> AStarPath</code></h5>
<p>Get full path from position to root.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Starting position as Vector, Entity, or (x, y) tuple.</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> AStarPath from pos toward root.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">step_from(pos) -> Vector | None</code></h5>
<p>Get single step from position toward root.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Current position as Vector, Entity, or (x, y) tuple.</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Next position as Vector, or None if at root or unreachable.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_heightmap(size=None, unreachable=-1.0) -> HeightMap</code></h5>
<p>Convert distance field to a HeightMap.
Each cell&#x27;s height equals its pathfinding distance from the root.
Useful for visualization, procedural terrain, or influence mapping.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>size</span>: Optional (width, height) tuple. Defaults to dijkstra dimensions.</div>
<div><span class='arg-name'>unreachable</span>: Value for cells that cannot reach root (default -1.0).</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap with distance values as heights.</p>
</div>
</div>
<div class="method-section">
<h3 id="DiscreteMap"><span class="class-name">DiscreteMap</span></h3>
<p>DiscreteMap(size: tuple[int, int], fill: int = 0, enum: type[IntEnum] = None)
A 2D grid of uint8 values (0-255) for discrete/categorical data.
DiscreteMap provides memory-efficient storage for terrain types, region IDs,
walkability masks, and other categorical data. Uses 4x less memory than HeightMap
for the same dimensions.
Args:
size: (width, height) dimensions. Immutable after creation.
fill: Initial value for all cells (0-255). Default 0.
enum: Optional IntEnum class for value interpretation.
Example:
from enum import IntEnum
class Terrain(IntEnum):
WATER = 0
GRASS = 1
MOUNTAIN = 2
dmap = mcrfpy.DiscreteMap((100, 100), fill=0, enum=Terrain)
dmap.fill(Terrain.GRASS, pos=(10, 10), size=(20, 20))
print(dmap[15, 15]) # Terrain.GRASS
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>enum_type</span>: Optional IntEnum class for value interpretation.</li>
<li><span class='property-name'>size</span> (read-only): Dimensions (width, height) of the map. Read-only.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add(other: DiscreteMap | int, *, pos=None, source_pos=None, size=None) -> DiscreteMap</code></h5>
<p>Add values from another map or a scalar, with saturation to 0-255.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: DiscreteMap to add, or int scalar to add to all cells</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bitwise_and(other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap</code></h5>
<p>Bitwise AND with another DiscreteMap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: DiscreteMap for AND operation</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bitwise_or(other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap</code></h5>
<p>Bitwise OR with another DiscreteMap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: DiscreteMap for OR operation</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bitwise_xor(other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap</code></h5>
<p>Bitwise XOR with another DiscreteMap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: DiscreteMap for XOR operation</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bool(condition: int | set | callable) -> DiscreteMap</code></h5>
<p>Create binary mask from condition. Returns NEW DiscreteMap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>condition</span>: int: match that value; set: match any in set; callable: predicate</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: new map with 1 where condition true, 0 elsewhere</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">clear() -> DiscreteMap</code></h5>
<p>Set all cells to 0. Equivalent to fill(0).</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">copy_from(other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap</code></h5>
<p>Copy values from another DiscreteMap into the specified region.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: DiscreteMap to copy from</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">count(value: int) -> int</code></h5>
<p>Count cells with the specified value.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>value</span>: Value to count (0-255)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> int: Number of cells with that value</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">count_range(min_val: int, max_val: int) -> int</code></h5>
<p>Count cells with values in the specified range (inclusive).</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>min_val</span>: Minimum value (inclusive)</div>
<div><span class='arg-name'>max_val</span>: Maximum value (inclusive)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> int: Number of cells in range</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill(value: int, *, pos=None, size=None) -> DiscreteMap</code></h5>
<p>Set cells in region to the specified value.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>value</span>: The value to set (0-255, or IntEnum member)</div>
<div><span class='arg-name'>pos</span>: Region start (x, y) in destination (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) to fill (default: remaining space)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(data: bytes, size: tuple[int, int], *, enum: type = None) -> DiscreteMap</code></h5>
<p>Create a DiscreteMap from raw byte data.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>data</span>: Raw cell data (one byte per cell, row-major)</div>
<div><span class='arg-name'>size</span>: (width, height) dimensions</div>
<div><span class='arg-name'>enum</span>: Optional IntEnum class for value interpretation</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: new map initialized from data</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: Data length does not match width * height</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_heightmap(hmap: HeightMap, mapping: list[tuple[tuple[float,float], int]], *, enum=None) -> DiscreteMap</code></h5>
<p>Create DiscreteMap from HeightMap using range-to-value mapping.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>hmap</span>: HeightMap to convert</div>
<div><span class='arg-name'>mapping</span>: List of ((min, max), value) tuples</div>
<div><span class='arg-name'>enum</span>: Optional IntEnum class for value interpretation</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: new map with mapped values</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get(x, y) or (pos) -> int | Enum</code></h5>
<p>Get the value at integer coordinates.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> int or enum member if enum_type is set</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> IndexError: Position is out of bounds</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">histogram() -> dict[int, int]</code></h5>
<p>Get a histogram of value counts.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> dict: {value: count} for all values present in the map</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">invert() -> DiscreteMap</code></h5>
<p>Return NEW DiscreteMap with (255 - value) for each cell.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: new inverted map (original unchanged)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">mask() -> memoryview</code></h5>
<p>Get raw uint8_t data as memoryview for libtcod compatibility.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> memoryview: Direct access to internal buffer (read/write)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">max(other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap</code></h5>
<p>Set each cell to the maximum of this and another DiscreteMap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: DiscreteMap to compare with</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">min(other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap</code></h5>
<p>Set each cell to the minimum of this and another DiscreteMap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: DiscreteMap to compare with</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">min_max() -> tuple[int, int]</code></h5>
<p>Get the minimum and maximum values in the map.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> tuple[int, int]: (min_value, max_value)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">multiply(factor: float, *, pos=None, size=None) -> DiscreteMap</code></h5>
<p>Multiply values by a scalar factor, with saturation to 0-255.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>factor</span>: Multiplier for each cell</div>
<div><span class='arg-name'>pos</span>: Region start (x, y) (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: entire map)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">set(x: int, y: int, value: int) -> None</code></h5>
<p>Set the value at integer coordinates.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>x</span>: X coordinate</div>
<div><span class='arg-name'>y</span>: Y coordinate</div>
<div><span class='arg-name'>value</span>: Value to set (0-255, or IntEnum member)</div>
</div>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> IndexError: Position is out of bounds ValueError: Value out of range 0-255</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">subtract(other: DiscreteMap | int, *, pos=None, source_pos=None, size=None) -> DiscreteMap</code></h5>
<p>Subtract values from another map or a scalar, with saturation to 0-255.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: DiscreteMap to subtract, or int scalar</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> DiscreteMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes() -> bytes</code></h5>
<p>Serialize map data to bytes (row-major, one byte per cell).</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> bytes: Raw cell data, length = width * height</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_heightmap(mapping: dict[int, float] = None) -> HeightMap</code></h5>
<p>Convert to HeightMap, optionally mapping values to floats.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>mapping</span>: Optional {int: float} mapping (default: direct cast)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: new heightmap with converted values</p>
</div>
</div>
<div class="method-section">
<h3 id="Drawable"><span class="class-name">Drawable</span></h3>
<p>Base class for all drawable UI elements</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx, dy) or (delta) -> None</code></h5>
<p>Move the element by a relative offset.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>dx</span>: Horizontal offset in pixels (or use delta)</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels (or use delta)</div>
<div><span class='arg-name'>delta</span>: Offset as tuple, list, or Vector: (dx, dy)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width, height) or (size) -> None</code></h5>
<p>Resize the element to new dimensions.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>width</span>: New width in pixels (or use size)</div>
<div><span class='arg-name'>height</span>: New height in pixels (or use size)</div>
<div><span class='arg-name'>size</span>: Size as tuple, list, or Vector: (width, height)</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="Easing"><span class="class-name">Easing</span></h3>
<p><em>Inherits from: IntEnum</em></p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">as_integer_ratio(...)</code></h5>
<p>Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
&gt;&gt;&gt; (10).as_integer_ratio()
(10, 1)
&gt;&gt;&gt; (-10).as_integer_ratio()
(-10, 1)
&gt;&gt;&gt; (0).as_integer_ratio()
(0, 1)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_count(...)</code></h5>
<p>Number of ones in the binary representation of the absolute value of self.
Also known as the population count.
&gt;&gt;&gt; bin(13)
&#x27;0b1101&#x27;
&gt;&gt;&gt; (13).bit_count()
3</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_length(...)</code></h5>
<p>Number of bits necessary to represent self in binary.
&gt;&gt;&gt; bin(37)
&#x27;0b100101&#x27;
&gt;&gt;&gt; (37).bit_length()
6</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">conjugate(...)</code></h5>
<p>Returns self, the complex conjugate of any int.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Indicates whether two&#x27;s complement is used to represent the integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_integer(...)</code></h5>
<p>Returns True. Exists for duck type compatibility with float.is_integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Determines whether two&#x27;s complement is used to represent the integer.
If signed is False and a negative integer is given, an OverflowError
is raised.</p>
</div>
</div>
<div class="method-section">
<h3 id="Entity"><span class="class-name">Entity</span></h3>
<p>Entity(grid_pos=None, texture=None, sprite_index=0, **kwargs)
A game entity that exists on a grid with sprite rendering.
Args:
grid_pos (tuple, optional): Grid position as (x, y) tuple. Default: (0, 0)
texture (Texture, optional): Texture object for sprite. Default: default texture
sprite_index (int, optional): Index into texture atlas. Default: 0
Keyword Args:
grid (Grid): Grid to attach entity to. Default: None
visible (bool): Visibility state. Default: True
opacity (float): Opacity (0.0-1.0). Default: 1.0
name (str): Element name for finding. Default: None
x (float): X grid position override (tile coords). Default: 0
y (float): Y grid position override (tile coords). Default: 0
sprite_offset (tuple): Pixel offset for oversized sprites. Default: (0, 0)
sprite_grid (list): Per-tile sprite indices for composite entities. Default: None
Attributes:
pos (Vector): Pixel position relative to grid (requires grid attachment)
x, y (float): Pixel position components (requires grid attachment)
grid_pos (Vector): Integer tile coordinates (logical game position)
grid_x, grid_y (int): Integer tile coordinate components
draw_pos (Vector): Fractional tile position for smooth animation
perspective_map (DiscreteMap | None): 3-state per-entity FOV memory
sprite_index (int): Current sprite index
visible (bool): Visibility state
opacity (float): Opacity value
name (str): Element name
sprite_offset (Vector): Pixel offset for oversized sprites
sprite_offset_x (float): X component of sprite offset
sprite_offset_y (float): Y component of sprite offset</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>behavior_type</span> (read-only): Current behavior type (int, read-only). Use set_behavior() to change.</li>
<li><span class='property-name'>cell_pos</span>: Integer logical cell position (Vector). Decoupled from draw_pos. Determines which cell this entity logically occupies for collision, pathfinding, etc.</li>
<li><span class='property-name'>cell_x</span>: Integer X cell coordinate.</li>
<li><span class='property-name'>cell_y</span>: Integer Y cell coordinate.</li>
<li><span class='property-name'>default_behavior</span>: Default behavior type (int, maps to Behavior enum). Entity reverts to this after DONE trigger. Default: 0 (IDLE).</li>
<li><span class='property-name'>draw_pos</span>: Fractional tile position for rendering (Vector). Use for smooth animation between grid cells.</li>
<li><span class='property-name'>grid</span>: Grid this entity belongs to. Get: Returns the Grid or None. Set: Assign a Grid to move entity, or None to remove from grid.</li>
<li><span class='property-name'>grid_pos</span>: Grid position as integer cell coordinates (Vector). Alias for cell_pos.</li>
<li><span class='property-name'>grid_x</span>: Grid X position as integer cell coordinate. Alias for cell_x.</li>
<li><span class='property-name'>grid_y</span>: Grid Y position as integer cell coordinate. Alias for cell_y.</li>
<li><span class='property-name'>labels</span>: Set of string labels for collision/targeting (frozenset). Assign any iterable of strings to replace all labels.</li>
<li><span class='property-name'>move_speed</span>: Animation duration for behavior movement in seconds (float). 0 = instant. Default: 0.15.</li>
<li><span class='property-name'>name</span>: Name for finding elements</li>
<li><span class='property-name'>opacity</span>: Opacity (0.0 = transparent, 1.0 = opaque)</li>
<li><span class='property-name'>perspective_map</span>: Per-entity FOV memory (DiscreteMap, read-write). 3-state values per cell: 0 = unknown (never seen), 1 = discovered (seen before, not currently visible), 2 = visible (in current FOV). Use mcrfpy.Perspective enum for clarity. Lazy-allocated on first access once the entity has a grid; returns None otherwise. The returned DiscreteMap is a live reference -- mutations are visible to subsequent updateVisibility() calls. Assigning a DiscreteMap replaces the entity&#x27;s memory; the new map&#x27;s size must match the grid&#x27;s size or ValueError is raised. Assign None to clear (will be lazy-reallocated on next access).</li>
<li><span class='property-name'>pos</span>: Pixel position relative to grid (Vector). Computed as draw_pos * tile_size. Requires entity to be attached to a grid.</li>
<li><span class='property-name'>shader</span>: 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.</li>
<li><span class='property-name'>sight_radius</span>: FOV radius for TARGET trigger (int). Default: 10.</li>
<li><span class='property-name'>sprite_grid</span>: 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.</li>
<li><span class='property-name'>sprite_index</span>: Sprite index on the texture on the display</li>
<li><span class='property-name'>sprite_offset</span>: Pixel offset for oversized sprites (Vector). Applied pre-zoom during grid rendering.</li>
<li><span class='property-name'>sprite_offset_x</span>: X component of sprite pixel offset.</li>
<li><span class='property-name'>sprite_offset_y</span>: Y component of sprite pixel offset.</li>
<li><span class='property-name'>step</span>: Step callback for grid.step() turn management. Called with (trigger, data) when behavior triggers fire. Set to None to clear.</li>
<li><span class='property-name'>target_label</span>: Label to search for with TARGET trigger (str or None). Default: None.</li>
<li><span class='property-name'>tile_height</span>: Entity height in tiles (int). Must be &gt;= 1. Default 1.</li>
<li><span class='property-name'>tile_size</span>: Entity size in tiles as (width, height) Vector. Default (1, 1).</li>
<li><span class='property-name'>tile_width</span>: Entity width in tiles (int). Must be &gt;= 1. Default 1.</li>
<li><span class='property-name'>turn_order</span>: Turn order for grid.step() (int). 0 = skip, higher values go later. Default: 1.</li>
<li><span class='property-name'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: entity.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
<li><span class='property-name'>visible</span>: Visibility flag</li>
<li><span class='property-name'>x</span>: Pixel X position relative to grid. Requires entity to be attached to a grid.</li>
<li><span class='property-name'>y</span>: Pixel Y position relative to grid. Requires entity to be attached to a grid.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add_label(label: str) -> None</code></h5>
<p>Add a label to this entity. Idempotent (adding same label twice is safe).</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation</code></h5>
<p>Create and start an animation on this entity&#x27;s property.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>property</span>: Name of the property to animate: &#x27;draw_x&#x27;, &#x27;draw_y&#x27; (tile coords), &#x27;sprite_scale&#x27;, &#x27;sprite_index&#x27;</div>
<div><span class='arg-name'>target</span>: Target value - float, int, or list of int (for sprite frame sequences)</div>
<div><span class='arg-name'>duration</span>: Animation duration in seconds</div>
<div><span class='arg-name'>easing</span>: Easing function: Easing enum value, string name, or None for linear</div>
<div><span class='arg-name'>delta</span>: If True, target is relative to current value; if False, target is absolute</div>
<div><span class='arg-name'>loop</span>: If True, animation repeats from start when it reaches the end (default False)</div>
<div><span class='arg-name'>callback</span>: Optional callable invoked when animation completes (not called for looping animations)</div>
<div><span class='arg-name'>conflict_mode</span>: &#x27;replace&#x27; (default), &#x27;queue&#x27;, or &#x27;error&#x27; if property already animating</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Animation object for monitoring progress</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: If property name is not valid for Entity (draw_x, draw_y, sprite_scale, sprite_index) Use &#x27;draw_x&#x27;/&#x27;draw_y&#x27; to animate tile coordinates for smooth movement between grid cells. Use list target with loop=True for repeating sprite frame animations.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">at(x, y) or at(pos) -> GridPoint | None</code></h5>
<p>Return the GridPoint at (x, y) if currently VISIBLE to this entity&#x27;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.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Grid coordinates as tuple, list, or Vector</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">die(...)</code></h5>
<p>Remove this entity from its grid.
Warning: Do not call during iteration over grid.entities.
Modifying the collection during iteration raises RuntimeError.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">find_path(target, diagonal_cost=1.41, collide=None) -> AStarPath | None</code></h5>
<p>Find a path from this entity to the target position.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>target</span>: Target as Vector, Entity, or (x, y) tuple.</div>
<div><span class='arg-name'>diagonal_cost</span>: Cost of diagonal movement (default 1.41).</div>
<div><span class='arg-name'>collide</span>: Label string. Entities with this label block pathfinding.</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> AStarPath object, or None if no path exists.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">has_label(label: str) -> bool</code></h5>
<p>Check if this entity has the given label.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">index(...)</code></h5>
<p>Return the index of this entity in its grid&#x27;s entity collection</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx, dy) or (delta) -> None</code></h5>
<p>Move the element by a relative offset.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>dx</span>: Horizontal offset in pixels (or use delta)</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels (or use delta)</div>
<div><span class='arg-name'>delta</span>: Offset as tuple, list, or Vector: (dx, dy)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">path_to(x, y) or path_to(target) -> list</code></h5>
<p>Find a path to the target position using Dijkstra pathfinding.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>target</span>: Target coordinates as tuple, list, or Vector</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of (x, y) tuples representing the path.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">remove_label(label: str) -> None</code></h5>
<p>Remove a label from this entity. No-op if label not present.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width, height) or (size) -> None</code></h5>
<p>Resize the element to new dimensions.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>width</span>: New width in pixels (or use size)</div>
<div><span class='arg-name'>height</span>: New height in pixels (or use size)</div>
<div><span class='arg-name'>size</span>: Size as tuple, list, or Vector: (width, height)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">set_behavior(type, waypoints=None, turns=0, path=None) -> None</code></h5>
<p>Configure this entity&#x27;s behavior for grid.step() turn management.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">update_visibility() -> None</code></h5>
<p>Update entity&#x27;s visibility state based on current FOV.
Recomputes which cells are visible from the entity&#x27;s position and updates
the entity&#x27;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.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">visible_entities(fov=None, radius=None) -> list[Entity]</code></h5>
<p>Get list of other entities visible from this entity&#x27;s position.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of Entity objects that are within field of view. Computes FOV from this entity&#x27;s position and returns all other entities whose positions fall within the visible area.</p>
</div>
</div>
<div class="method-section">
<h3 id="Entity3D"><span class="class-name">Entity3D</span></h3>
<p>Entity3D(pos=None, **kwargs)
A 3D game entity that exists on a Viewport3D&#x27;s navigation grid.
Args:
pos (tuple, optional): Grid position as (x, z). Default: (0, 0)
Keyword Args:
viewport (Viewport3D): Viewport to attach entity to. Default: None
rotation (float): Y-axis rotation in degrees. Default: 0
scale (float or tuple): Scale factor. Default: 1.0
visible (bool): Visibility state. Default: True
color (Color): Entity color. Default: orange
Attributes:
pos (tuple): Grid position (x, z) - setting triggers movement
grid_pos (tuple): Same as pos (read-only)
world_pos (tuple): Current world coordinates (x, y, z) (read-only)
rotation (float): Y-axis rotation in degrees
scale (float): Uniform scale factor
visible (bool): Visibility state
color (Color): Entity render color
viewport (Viewport3D): Owning viewport (read-only)</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>anim_clip</span>: Current animation clip name. Set to play an animation.</li>
<li><span class='property-name'>anim_frame</span> (read-only): Current animation frame number (read-only, approximate at 30fps).</li>
<li><span class='property-name'>anim_loop</span>: Whether animation loops when it reaches the end.</li>
<li><span class='property-name'>anim_paused</span>: Whether animation playback is paused.</li>
<li><span class='property-name'>anim_speed</span>: Animation playback speed multiplier. 1.0 = normal speed.</li>
<li><span class='property-name'>anim_time</span>: Current time position in animation (seconds).</li>
<li><span class='property-name'>auto_animate</span>: Enable auto-play of walk/idle clips based on movement.</li>
<li><span class='property-name'>color</span>: Entity render color.</li>
<li><span class='property-name'>grid_pos</span>: Grid position (x, z). Same as pos.</li>
<li><span class='property-name'>idle_clip</span>: Animation clip to play when entity is stationary.</li>
<li><span class='property-name'>is_moving</span> (read-only): Whether entity is currently moving (read-only).</li>
<li><span class='property-name'>model</span>: 3D model (Model3D). If None, uses placeholder cube.</li>
<li><span class='property-name'>name</span>: Entity name (str). Used for find() lookup.</li>
<li><span class='property-name'>on_anim_complete</span>: Callback(entity, clip_name) when non-looping animation ends.</li>
<li><span class='property-name'>pos</span>: Grid position (x, z). Setting triggers smooth movement.</li>
<li><span class='property-name'>rotation</span>: Y-axis rotation in degrees.</li>
<li><span class='property-name'>scale</span>: Uniform scale factor. Can also set as (x, y, z) tuple.</li>
<li><span class='property-name'>viewport</span> (read-only): Owning Viewport3D (read-only).</li>
<li><span class='property-name'>visible</span>: Visibility state.</li>
<li><span class='property-name'>walk_clip</span>: Animation clip to play when entity is moving.</li>
<li><span class='property-name'>world_pos</span> (read-only): Current world position (x, y, z) (read-only). Includes animation interpolation.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">animate(property, target, duration, easing=None, delta=False, callback=None, conflict_mode=None)</code></h5>
<p>Animate a property over time.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>property</span>: Property name (x, y, z, rotation, scale, etc.)</div>
<div><span class='arg-name'>target</span>: Target value (float or int)</div>
<div><span class='arg-name'>duration</span>: Animation duration in seconds</div>
<div><span class='arg-name'>easing</span>: Easing function (Easing enum or None for linear)</div>
<div><span class='arg-name'>delta</span>: If True, target is relative to current value</div>
<div><span class='arg-name'>callback</span>: Called with (target, property, value) when complete</div>
<div><span class='arg-name'>conflict_mode</span>: &#x27;replace&#x27;, &#x27;queue&#x27;, or &#x27;error&#x27;</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">at(x, z) -> dict</code></h5>
<p>Get visibility state for a cell from this entity&#x27;s perspective.
Returns dict with &#x27;visible&#x27; and &#x27;discovered&#x27; boolean keys.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">clear_path()</code></h5>
<p>Clear the movement queue and stop at current position.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">follow_path(path)</code></h5>
<p>Queue path positions for smooth movement.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>path</span>: List of (x, z) tuples (as returned by path_to())</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">path_to(x, z) or path_to(pos=(x, z)) -> list</code></h5>
<p>Compute A* path to target position.
Returns list of (x, z) tuples, or empty list if no path exists.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">teleport(x, z) or teleport(pos=(x, z))</code></h5>
<p>Instantly move to target position without animation.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">update_visibility()</code></h5>
<p>Recompute field of view from current position.</p>
</div>
</div>
<div class="method-section">
<h3 id="EntityCollection3D"><span class="class-name">EntityCollection3D</span></h3>
<p>Collection of Entity3D objects belonging to a Viewport3D.
Supports list-like operations: indexing, iteration, append, remove.
Example:
viewport.entities.append(entity)
for entity in viewport.entities:
print(entity.pos)</p>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">append(entity)</code></h5>
<p>Add an Entity3D to the collection.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">clear()</code></h5>
<p>Remove all entities from the collection.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">extend(iterable)</code></h5>
<p>Add all Entity3D objects from iterable to the collection.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">find(name) -> Entity3D or None</code></h5>
<p>Find an Entity3D by name. Returns None if not found.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">pop(index=-1) -> Entity3D</code></h5>
<p>Remove and return Entity3D at index (default: last).</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">remove(entity)</code></h5>
<p>Remove an Entity3D from the collection.</p>
</div>
</div>
<div class="method-section">
<h3 id="EntityCollection3DIter"><span class="class-name">EntityCollection3DIter</span></h3>
<p>Iterator for EntityCollection3D</p>
<h4>Methods:</h4>
</div>
<div class="method-section">
<h3 id="FOV"><span class="class-name">FOV</span></h3>
<p><em>Inherits from: IntEnum</em></p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">as_integer_ratio(...)</code></h5>
<p>Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
&gt;&gt;&gt; (10).as_integer_ratio()
(10, 1)
&gt;&gt;&gt; (-10).as_integer_ratio()
(-10, 1)
&gt;&gt;&gt; (0).as_integer_ratio()
(0, 1)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_count(...)</code></h5>
<p>Number of ones in the binary representation of the absolute value of self.
Also known as the population count.
&gt;&gt;&gt; bin(13)
&#x27;0b1101&#x27;
&gt;&gt;&gt; (13).bit_count()
3</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_length(...)</code></h5>
<p>Number of bits necessary to represent self in binary.
&gt;&gt;&gt; bin(37)
&#x27;0b100101&#x27;
&gt;&gt;&gt; (37).bit_length()
6</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">conjugate(...)</code></h5>
<p>Returns self, the complex conjugate of any int.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Indicates whether two&#x27;s complement is used to represent the integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_integer(...)</code></h5>
<p>Returns True. Exists for duck type compatibility with float.is_integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Determines whether two&#x27;s complement is used to represent the integer.
If signed is False and a negative integer is given, an OverflowError
is raised.</p>
</div>
</div>
<div class="method-section">
<h3 id="Font"><span class="class-name">Font</span></h3>
<p>Font(filename: str)
A font resource for rendering text in Caption elements.
Args:
filename: Path to a TrueType (.ttf) or OpenType (.otf) font file.
Properties:
family (str, read-only): Font family name from metadata.
source (str, read-only): File path used to load this font.
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>family</span> (read-only): Font family name (str, read-only). Retrieved from font metadata.</li>
<li><span class='property-name'>source</span> (read-only): Source filename path (str, read-only). The path used to load this font.</li>
</ul>
<h4>Methods:</h4>
</div>
<div class="method-section">
<h3 id="Frame"><span class="class-name">Frame</span></h3>
<p><em>Inherits from: Drawable</em></p>
<p>Frame(pos=None, size=None, **kwargs)
A rectangular frame UI element that can contain other drawable elements.
Args:
pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0)
size (tuple, optional): Size as (width, height) tuple. Default: (0, 0)
Keyword Args:
fill_color (Color): Background fill color. Default: (0, 0, 0, 128)
outline_color (Color): Border outline color. Default: (255, 255, 255, 255)
outline (float): Border outline thickness. Default: 0
click (callable): Click event handler. Default: None
children (list): Initial list of child drawable elements. Default: None
visible (bool): Visibility state. Default: True
opacity (float): Opacity (0.0-1.0). Default: 1.0
z_index (int): Rendering order. Default: 0
name (str): Element name for finding. Default: None
x (float): X position override. Default: 0
y (float): Y position override. Default: 0
w (float): Width override. Default: 0
h (float): Height override. Default: 0
clip_children (bool): Whether to clip children to frame bounds. Default: False
cache_subtree (bool): Cache rendering to texture for performance. Default: False
align (Alignment): Alignment relative to parent. Default: None (manual positioning)
margin (float): Margin from parent edge when aligned. Default: 0
horiz_margin (float): Horizontal margin override. Default: 0 (use margin)
vert_margin (float): Vertical margin override. Default: 0 (use margin)
Attributes:
x, y (float): Position in pixels
w, h (float): Size in pixels
pos (Vector): Position as a Vector object
fill_color, outline_color (Color): Visual appearance
outline (float): Border thickness
click (callable): Click event handler
children (list): Collection of child drawable elements
visible (bool): Visibility state
opacity (float): Opacity value
z_index (int): Rendering order
name (str): Element name
clip_children (bool): Whether to clip children to frame bounds
cache_subtree (bool): Cache subtree rendering to texture
align (Alignment): Alignment relative to parent (or None)
margin (float): General margin for alignment
horiz_margin (float): Horizontal margin override
vert_margin (float): Vertical margin override</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>align</span>: 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.</li>
<li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>cache_subtree</span>: #144: Cache subtree rendering to texture for performance</li>
<li><span class='property-name'>children</span>: UICollection of objects on top of this one</li>
<li><span class='property-name'>clip_children</span>: Whether to clip children to frame bounds</li>
<li><span class='property-name'>fill_color</span>: Fill color of the rectangle. Returns a copy; modifying components requires reassignment. For animation, use &#x27;fill_color.r&#x27;, &#x27;fill_color.g&#x27;, etc.</li>
<li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>grid_pos</span>: Position in grid tile coordinates (only when parent is Grid)</li>
<li><span class='property-name'>grid_size</span>: Size in grid tile coordinates (only when parent is Grid)</li>
<li><span class='property-name'>h</span>: height of the rectangle</li>
<li><span class='property-name'>horiz_margin</span>: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
<li><span class='property-name'>name</span>: Name for finding elements</li>
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: 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.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>outline</span>: Thickness of the border</li>
<li><span class='property-name'>outline_color</span>: Outline color of the rectangle. Returns a copy; modifying components requires reassignment. For animation, use &#x27;outline_color.r&#x27;, &#x27;outline_color.g&#x27;, etc.</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position as a Vector</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>shader</span>: 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.</li>
<li><span class='property-name'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>w</span>: width of the rectangle</li>
<li><span class='property-name'>x</span>: X coordinate of top-left corner</li>
<li><span class='property-name'>y</span>: Y coordinate of top-left corner</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation</code></h5>
<p>Create and start an animation on this drawable&#x27;s property.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>property</span>: Name of the property to animate (e.g., &#x27;x&#x27;, &#x27;fill_color&#x27;, &#x27;opacity&#x27;)</div>
<div><span class='arg-name'>target</span>: Target value - type depends on property (float, tuple for color/vector, etc.)</div>
<div><span class='arg-name'>duration</span>: Animation duration in seconds</div>
<div><span class='arg-name'>easing</span>: Easing function: Easing enum value, string name, or None for linear</div>
<div><span class='arg-name'>delta</span>: If True, target is relative to current value; if False, target is absolute</div>
<div><span class='arg-name'>loop</span>: If True, animation repeats from start when it reaches the end (default False)</div>
<div><span class='arg-name'>callback</span>: Optional callable invoked when animation completes (not called for looping animations)</div>
<div><span class='arg-name'>conflict_mode</span>: &#x27;replace&#x27; (default), &#x27;queue&#x27;, or &#x27;error&#x27; if property already animating</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Animation object for monitoring progress</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> 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.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx, dy) or (delta) -> None</code></h5>
<p>Move the element by a relative offset.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>dx</span>: Horizontal offset in pixels (or use delta)</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels (or use delta)</div>
<div><span class='arg-name'>delta</span>: Offset as tuple, list, or Vector: (dx, dy)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">realign() -> None</code></h5>
<p>Reapply alignment relative to parent, useful for responsive layouts.
Note:
Call this to recalculate position after parent changes size. For elements with align=None, this has no effect.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width, height) or (size) -> None</code></h5>
<p>Resize the element to new dimensions.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>width</span>: New width in pixels (or use size)</div>
<div><span class='arg-name'>height</span>: New height in pixels (or use size)</div>
<div><span class='arg-name'>size</span>: Size as tuple, list, or Vector: (width, height)</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="Grid"><span class="class-name">Grid</span></h3>
<p><em>Inherits from: Drawable</em></p>
<p>Grid(grid_size=None, pos=None, size=None, texture=None, **kwargs)
A grid-based UI element for tile-based rendering and entity management.
Creates and owns grid data (cells, entities, layers) with an integrated
rendering view (camera, zoom, perspective).
Can also be constructed as a view of existing grid data:
Grid(grid=existing_grid, pos=..., size=...)
Args:
grid_size (tuple): Grid dimensions as (grid_w, grid_h). Default: (2, 2)
pos (tuple): Position as (x, y). Default: (0, 0)
size (tuple): Size as (w, h). Default: auto-calculated
texture (Texture): Tile texture atlas. Default: default texture
Keyword Args:
grid (Grid): Existing Grid to view (creates view of shared data).
fill_color (Color): Background fill color.
on_click (callable): Click event handler.
center_x, center_y (float): Camera center coordinates.
zoom (float): Zoom level. Default: 1.0
visible (bool): Visibility. Default: True
opacity (float): Opacity (0.0-1.0). Default: 1.0
z_index (int): Rendering order. Default: 0
name (str): Element name.
layers (list): List of ColorLayer/TileLayer objects.
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>align</span>: 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.</li>
<li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>camera_rotation</span>: Rotation of grid contents around camera center (degrees).</li>
<li><span class='property-name'>center</span>: Camera center point in pixel coordinates.</li>
<li><span class='property-name'>center_x</span>: center of the view X-coordinate</li>
<li><span class='property-name'>center_y</span>: center of the view Y-coordinate</li>
<li><span class='property-name'>fill_color</span>: Background fill color.</li>
<li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>grid_data</span>: The underlying grid data object (for multi-view scenarios).</li>
<li><span class='property-name'>h</span>: visible widget height</li>
<li><span class='property-name'>horiz_margin</span>: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
<li><span class='property-name'>name</span>: Name for finding elements</li>
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked.</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: 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.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position of the grid as Vector</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>shader</span>: 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.</li>
<li><span class='property-name'>texture</span> (read-only): Texture used for tile rendering (read-only).</li>
<li><span class='property-name'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>w</span>: visible widget width</li>
<li><span class='property-name'>x</span>: top-left corner X-coordinate</li>
<li><span class='property-name'>y</span>: top-left corner Y-coordinate</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first).</li>
<li><span class='property-name'>zoom</span>: Zoom level for rendering.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation</code></h5>
<p>Create and start an animation on this drawable&#x27;s property.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>property</span>: Name of the property to animate (e.g., &#x27;x&#x27;, &#x27;fill_color&#x27;, &#x27;opacity&#x27;)</div>
<div><span class='arg-name'>target</span>: Target value - type depends on property (float, tuple for color/vector, etc.)</div>
<div><span class='arg-name'>duration</span>: Animation duration in seconds</div>
<div><span class='arg-name'>easing</span>: Easing function: Easing enum value, string name, or None for linear</div>
<div><span class='arg-name'>delta</span>: If True, target is relative to current value; if False, target is absolute</div>
<div><span class='arg-name'>loop</span>: If True, animation repeats from start when it reaches the end (default False)</div>
<div><span class='arg-name'>callback</span>: Optional callable invoked when animation completes (not called for looping animations)</div>
<div><span class='arg-name'>conflict_mode</span>: &#x27;replace&#x27; (default), &#x27;queue&#x27;, or &#x27;error&#x27; if property already animating</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Animation object for monitoring progress</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> 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.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx, dy) or (delta) -> None</code></h5>
<p>Move the element by a relative offset.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>dx</span>: Horizontal offset in pixels (or use delta)</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels (or use delta)</div>
<div><span class='arg-name'>delta</span>: Offset as tuple, list, or Vector: (dx, dy)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">realign() -> None</code></h5>
<p>Reapply alignment relative to parent, useful for responsive layouts.
Note:
Call this to recalculate position after parent changes size. For elements with align=None, this has no effect.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width, height) or (size) -> None</code></h5>
<p>Resize the element to new dimensions.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>width</span>: New width in pixels (or use size)</div>
<div><span class='arg-name'>height</span>: New height in pixels (or use size)</div>
<div><span class='arg-name'>size</span>: Size as tuple, list, or Vector: (width, height)</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="GridView"><span class="class-name">GridView</span></h3>
<p><em>Inherits from: Drawable</em></p>
<p>Grid(grid_size=None, pos=None, size=None, texture=None, **kwargs)
A grid-based UI element for tile-based rendering and entity management.
Creates and owns grid data (cells, entities, layers) with an integrated
rendering view (camera, zoom, perspective).
Can also be constructed as a view of existing grid data:
Grid(grid=existing_grid, pos=..., size=...)
Args:
grid_size (tuple): Grid dimensions as (grid_w, grid_h). Default: (2, 2)
pos (tuple): Position as (x, y). Default: (0, 0)
size (tuple): Size as (w, h). Default: auto-calculated
texture (Texture): Tile texture atlas. Default: default texture
Keyword Args:
grid (Grid): Existing Grid to view (creates view of shared data).
fill_color (Color): Background fill color.
on_click (callable): Click event handler.
center_x, center_y (float): Camera center coordinates.
zoom (float): Zoom level. Default: 1.0
visible (bool): Visibility. Default: True
opacity (float): Opacity (0.0-1.0). Default: 1.0
z_index (int): Rendering order. Default: 0
name (str): Element name.
layers (list): List of ColorLayer/TileLayer objects.
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>align</span>: 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.</li>
<li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>camera_rotation</span>: Rotation of grid contents around camera center (degrees).</li>
<li><span class='property-name'>center</span>: Camera center point in pixel coordinates.</li>
<li><span class='property-name'>center_x</span>: center of the view X-coordinate</li>
<li><span class='property-name'>center_y</span>: center of the view Y-coordinate</li>
<li><span class='property-name'>fill_color</span>: Background fill color.</li>
<li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>grid_data</span>: The underlying grid data object (for multi-view scenarios).</li>
<li><span class='property-name'>h</span>: visible widget height</li>
<li><span class='property-name'>horiz_margin</span>: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
<li><span class='property-name'>name</span>: Name for finding elements</li>
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked.</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: 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.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position of the grid as Vector</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>shader</span>: 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.</li>
<li><span class='property-name'>texture</span> (read-only): Texture used for tile rendering (read-only).</li>
<li><span class='property-name'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>w</span>: visible widget width</li>
<li><span class='property-name'>x</span>: top-left corner X-coordinate</li>
<li><span class='property-name'>y</span>: top-left corner Y-coordinate</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first).</li>
<li><span class='property-name'>zoom</span>: Zoom level for rendering.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation</code></h5>
<p>Create and start an animation on this drawable&#x27;s property.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>property</span>: Name of the property to animate (e.g., &#x27;x&#x27;, &#x27;fill_color&#x27;, &#x27;opacity&#x27;)</div>
<div><span class='arg-name'>target</span>: Target value - type depends on property (float, tuple for color/vector, etc.)</div>
<div><span class='arg-name'>duration</span>: Animation duration in seconds</div>
<div><span class='arg-name'>easing</span>: Easing function: Easing enum value, string name, or None for linear</div>
<div><span class='arg-name'>delta</span>: If True, target is relative to current value; if False, target is absolute</div>
<div><span class='arg-name'>loop</span>: If True, animation repeats from start when it reaches the end (default False)</div>
<div><span class='arg-name'>callback</span>: Optional callable invoked when animation completes (not called for looping animations)</div>
<div><span class='arg-name'>conflict_mode</span>: &#x27;replace&#x27; (default), &#x27;queue&#x27;, or &#x27;error&#x27; if property already animating</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Animation object for monitoring progress</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> 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.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx, dy) or (delta) -> None</code></h5>
<p>Move the element by a relative offset.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>dx</span>: Horizontal offset in pixels (or use delta)</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels (or use delta)</div>
<div><span class='arg-name'>delta</span>: Offset as tuple, list, or Vector: (dx, dy)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">realign() -> None</code></h5>
<p>Reapply alignment relative to parent, useful for responsive layouts.
Note:
Call this to recalculate position after parent changes size. For elements with align=None, this has no effect.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width, height) or (size) -> None</code></h5>
<p>Resize the element to new dimensions.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>width</span>: New width in pixels (or use size)</div>
<div><span class='arg-name'>height</span>: New height in pixels (or use size)</div>
<div><span class='arg-name'>size</span>: Size as tuple, list, or Vector: (width, height)</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="HeightMap"><span class="class-name">HeightMap</span></h3>
<p>HeightMap(size: tuple[int, int], fill: float = 0.0)
A 2D grid of float values for procedural generation.
HeightMap is the universal canvas for procedural generation. It stores float values that can be manipulated, combined, and applied to Grid and Layer objects.
Args:
size: (width, height) dimensions of the heightmap. Immutable after creation.
fill: Initial value for all cells. Default 0.0.
Example:
hmap = mcrfpy.HeightMap((100, 100))
hmap.fill(0.5).scale(2.0).clamp(0.0, 1.0)
value = hmap[5, 5] # Subscript shorthand for get()
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>size</span> (read-only): Dimensions (width, height) of the heightmap. Read-only.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add(other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap</code></h5>
<p>Add another heightmap&#x27;s values to this one in the specified region.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: HeightMap to add values from</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add_bsp(bsp: BSP, *, pos=None, select: str = 'leaves', nodes: list = None, shrink: int = 0, value: float = 1.0) -> HeightMap</code></h5>
<p>Add BSP node regions to heightmap. More efficient than creating intermediate HeightMap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>bsp</span>: BSP tree to sample from</div>
<div><span class='arg-name'>pos</span>: Where BSP origin maps to in HeightMap (default: origin-relative like to_heightmap)</div>
<div><span class='arg-name'>select</span>: &#x27;leaves&#x27;, &#x27;all&#x27;, or &#x27;internal&#x27; (default: &#x27;leaves&#x27;)</div>
<div><span class='arg-name'>nodes</span>: Override: specific BSPNodes only (default: None)</div>
<div><span class='arg-name'>shrink</span>: Pixels to shrink from node bounds (default: 0)</div>
<div><span class='arg-name'>value</span>: Value to add inside regions (default: 1.0)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add_constant(value: float, *, pos=None, size=None) -> HeightMap</code></h5>
<p>Add a constant value to cells in region.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>value</span>: The value to add to each cell</div>
<div><span class='arg-name'>pos</span>: Region start (x, y) in destination (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: remaining space)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add_hill(center, radius: float, height: float) -> HeightMap</code></h5>
<p>Add a smooth hill at the specified position.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>center</span>: Center position as (x, y) tuple, list, or Vector</div>
<div><span class='arg-name'>radius</span>: Radius of the hill in cells</div>
<div><span class='arg-name'>height</span>: Height of the hill peak</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add_noise(source: NoiseSource, world_origin: tuple = (0.0, 0.0), world_size: tuple = None, mode: str = 'fbm', octaves: int = 4, scale: float = 1.0) -> HeightMap</code></h5>
<p>Sample noise and add to current values. More efficient than creating intermediate HeightMap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>source</span>: 2D NoiseSource to sample from</div>
<div><span class='arg-name'>world_origin</span>: World coordinates of top-left (default: (0, 0))</div>
<div><span class='arg-name'>world_size</span>: World area to sample (default: HeightMap size)</div>
<div><span class='arg-name'>mode</span>: &#x27;flat&#x27;, &#x27;fbm&#x27;, or &#x27;turbulence&#x27; (default: &#x27;fbm&#x27;)</div>
<div><span class='arg-name'>octaves</span>: Octaves for fbm/turbulence (default: 4)</div>
<div><span class='arg-name'>scale</span>: Multiplier for sampled values (default: 1.0)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add_voronoi(num_points: int, coefficients: tuple = (1.0, -0.5), seed: int = None) -> HeightMap</code></h5>
<p>Add Voronoi-based terrain features.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>num_points</span>: Number of Voronoi seed points</div>
<div><span class='arg-name'>coefficients</span>: Coefficients for distance calculations (default: (1.0, -0.5))</div>
<div><span class='arg-name'>seed</span>: Random seed (None for random)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">clamp(min: float = 0.0, max: float = 1.0, *, pos=None, size=None) -> HeightMap</code></h5>
<p>Clamp values in region to the specified range.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>min</span>: Minimum value (default 0.0)</div>
<div><span class='arg-name'>max</span>: Maximum value (default 1.0)</div>
<div><span class='arg-name'>pos</span>: Region start (x, y) in destination (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: remaining space)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">clear() -> HeightMap</code></h5>
<p>Set all cells to 0.0. Equivalent to fill(0.0).</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">copy_from(other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap</code></h5>
<p>Copy values from another heightmap into the specified region.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: HeightMap to copy from</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">count_in_range(range: tuple[float, float]) -> int</code></h5>
<p>Count cells with values in the specified range (inclusive).</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>range</span>: Value range as (min, max) tuple or list</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> int: Number of cells with values in range</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: min &gt; max</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">dig_bezier(points: tuple, start_radius: float, end_radius: float, start_height: float, end_height: float) -> HeightMap</code></h5>
<p>Construct a canal along a cubic Bezier curve with specified heights.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>points</span>: Four control points as ((x0,y0), (x1,y1), (x2,y2), (x3,y3))</div>
<div><span class='arg-name'>start_radius</span>: Radius at start of path</div>
<div><span class='arg-name'>end_radius</span>: Radius at end of path</div>
<div><span class='arg-name'>start_height</span>: Target height at start of path</div>
<div><span class='arg-name'>end_height</span>: Target height at end of path</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining Only lowers cells; cells below target height are unchanged</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">dig_hill(center, radius: float, target_height: float) -> HeightMap</code></h5>
<p>Construct a pit or crater with the specified center height.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>center</span>: Center position as (x, y) tuple, list, or Vector</div>
<div><span class='arg-name'>radius</span>: Radius of the crater in cells</div>
<div><span class='arg-name'>target_height</span>: Height at the center of the pit</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining Only lowers cells; cells below target_height are unchanged</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill(value: float, *, pos=None, size=None) -> HeightMap</code></h5>
<p>Set cells in region to the specified value.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>value</span>: The value to set</div>
<div><span class='arg-name'>pos</span>: Region start (x, y) in destination (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) to fill (default: remaining space)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get(x, y) or (pos) -> float</code></h5>
<p>Get the height value at integer coordinates.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> float: Height value at that position</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> IndexError: Position is out of bounds</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get_interpolated(x, y) or (pos) -> float</code></h5>
<p>Get interpolated height value at non-integer coordinates.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> float: Bilinearly interpolated height value</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get_normal(x, y, water_level=0.0) or (pos, water_level=0.0) -> tuple[float, float, float]</code></h5>
<p>Get the normal vector at given coordinates for lighting calculations.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>water_level</span>: Water level below which terrain is considered flat (default 0.0)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> tuple[float, float, float]: Normal vector (nx, ny, nz)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get_slope(x, y) or (pos) -> float</code></h5>
<p>Get the slope at integer coordinates, from 0 (flat) to pi/2 (vertical).</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> float: Slope angle in radians (0 to pi/2)</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> IndexError: Position is out of bounds</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">inverse() -> HeightMap</code></h5>
<p>Return NEW HeightMap with (1.0 - value) for each cell.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: New inverted HeightMap (original is unchanged)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">lerp(other: HeightMap, t: float, *, pos=None, source_pos=None, size=None) -> HeightMap</code></h5>
<p>Linear interpolation between this and another heightmap in the specified region.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: HeightMap to interpolate towards</div>
<div><span class='arg-name'>t</span>: Interpolation factor (0.0 = this, 1.0 = other)</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">max(other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap</code></h5>
<p>Set each cell in region to the maximum of this and another heightmap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: HeightMap to compare with</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">mid_point_displacement(roughness: float = 0.5, seed: int = None) -> HeightMap</code></h5>
<p>Generate terrain using midpoint displacement algorithm (diamond-square).
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>roughness</span>: Controls terrain roughness (0.0-1.0, default 0.5)</div>
<div><span class='arg-name'>seed</span>: Random seed (None for random)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining Works best with power-of-2+1 dimensions (e.g., 65x65, 129x129)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">min(other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap</code></h5>
<p>Set each cell in region to the minimum of this and another heightmap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: HeightMap to compare with</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">min_max() -> tuple[float, float]</code></h5>
<p>Get the minimum and maximum height values in the map.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> tuple[float, float]: (min_value, max_value)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">multiply(other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap</code></h5>
<p>Multiply this heightmap by another in the specified region (useful for masking).</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: HeightMap to multiply by</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">multiply_bsp(bsp: BSP, *, pos=None, select: str = 'leaves', nodes: list = None, shrink: int = 0, value: float = 1.0) -> HeightMap</code></h5>
<p>Multiply by BSP regions. Effectively masks the heightmap to node interiors.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>bsp</span>: BSP tree to sample from</div>
<div><span class='arg-name'>pos</span>: Where BSP origin maps to in HeightMap (default: origin-relative like to_heightmap)</div>
<div><span class='arg-name'>select</span>: &#x27;leaves&#x27;, &#x27;all&#x27;, or &#x27;internal&#x27; (default: &#x27;leaves&#x27;)</div>
<div><span class='arg-name'>nodes</span>: Override: specific BSPNodes only (default: None)</div>
<div><span class='arg-name'>shrink</span>: Pixels to shrink from node bounds (default: 0)</div>
<div><span class='arg-name'>value</span>: Value to multiply inside regions (default: 1.0)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">multiply_noise(source: NoiseSource, world_origin: tuple = (0.0, 0.0), world_size: tuple = None, mode: str = 'fbm', octaves: int = 4, scale: float = 1.0) -> HeightMap</code></h5>
<p>Sample noise and multiply with current values. Useful for applying noise-based masks.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>source</span>: 2D NoiseSource to sample from</div>
<div><span class='arg-name'>world_origin</span>: World coordinates of top-left (default: (0, 0))</div>
<div><span class='arg-name'>world_size</span>: World area to sample (default: HeightMap size)</div>
<div><span class='arg-name'>mode</span>: &#x27;flat&#x27;, &#x27;fbm&#x27;, or &#x27;turbulence&#x27; (default: &#x27;fbm&#x27;)</div>
<div><span class='arg-name'>octaves</span>: Octaves for fbm/turbulence (default: 4)</div>
<div><span class='arg-name'>scale</span>: Multiplier for sampled values (default: 1.0)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">normalize(min: float = 0.0, max: float = 1.0, *, pos=None, size=None) -> HeightMap</code></h5>
<p>Linearly rescale values in region. Current min becomes new min, current max becomes new max.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>min</span>: Target minimum value (default 0.0)</div>
<div><span class='arg-name'>max</span>: Target maximum value (default 1.0)</div>
<div><span class='arg-name'>pos</span>: Region start (x, y) in destination (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: remaining space)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">rain_erosion(drops: int, erosion: float = 0.1, sedimentation: float = 0.05, seed: int = None) -> HeightMap</code></h5>
<p>Simulate rain erosion on the terrain.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>drops</span>: Number of rain drops to simulate</div>
<div><span class='arg-name'>erosion</span>: Erosion coefficient (default 0.1)</div>
<div><span class='arg-name'>sedimentation</span>: Sedimentation coefficient (default 0.05)</div>
<div><span class='arg-name'>seed</span>: Random seed (None for random)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">scale(factor: float, *, pos=None, size=None) -> HeightMap</code></h5>
<p>Multiply cells in region by a factor.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>factor</span>: The multiplier for each cell</div>
<div><span class='arg-name'>pos</span>: Region start (x, y) in destination (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: remaining space)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">smooth(iterations: int = 1) -> HeightMap</code></h5>
<p>Smooth the heightmap by averaging neighboring cells.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>iterations</span>: Number of smoothing passes (default 1)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">sparse_kernel(weights: dict[tuple[int, int], float]) -> HeightMap</code></h5>
<p>Apply sparse convolution kernel, returning a NEW HeightMap with results.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>weights</span>: Dict mapping (dx, dy) offsets to weight values</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: new heightmap with convolution result</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">sparse_kernel_from(source: HeightMap, weights: dict[tuple[int, int], float]) -> None</code></h5>
<p>Apply sparse convolution from source heightmap into self (for reusing destination buffers).</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>source</span>: Source HeightMap to convolve from</div>
<div><span class='arg-name'>weights</span>: Dict mapping (dx, dy) offsets to weight values</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">subtract(other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap</code></h5>
<p>Subtract another heightmap&#x27;s values from this one in the specified region.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: HeightMap to subtract values from</div>
<div><span class='arg-name'>pos</span>: Destination start (x, y) in self (default: (0, 0))</div>
<div><span class='arg-name'>source_pos</span>: Source start (x, y) in other (default: (0, 0))</div>
<div><span class='arg-name'>size</span>: Region (width, height) (default: max overlapping area)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: self, for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">threshold(range: tuple[float, float]) -> HeightMap</code></h5>
<p>Return NEW HeightMap with original values where in range, 0.0 elsewhere.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>range</span>: Value range as (min, max) tuple or list, inclusive</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: New HeightMap (original is unchanged)</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: min &gt; max</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">threshold_binary(range: tuple[float, float], value: float = 1.0) -> HeightMap</code></h5>
<p>Return NEW HeightMap with uniform value where in range, 0.0 elsewhere.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>range</span>: Value range as (min, max) tuple or list, inclusive</div>
<div><span class='arg-name'>value</span>: Value to set for cells in range (default 1.0)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: New HeightMap (original is unchanged)</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: min &gt; max</p>
</div>
</div>
<div class="method-section">
<h3 id="Heuristic"><span class="class-name">Heuristic</span></h3>
<p><em>Inherits from: IntEnum</em></p>
<p>Built-in A* heuristic function selector.
Values:
EUCLIDEAN: sqrt((dx)^2 + (dy)^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.
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">as_integer_ratio(...)</code></h5>
<p>Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
&gt;&gt;&gt; (10).as_integer_ratio()
(10, 1)
&gt;&gt;&gt; (-10).as_integer_ratio()
(-10, 1)
&gt;&gt;&gt; (0).as_integer_ratio()
(0, 1)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_count(...)</code></h5>
<p>Number of ones in the binary representation of the absolute value of self.
Also known as the population count.
&gt;&gt;&gt; bin(13)
&#x27;0b1101&#x27;
&gt;&gt;&gt; (13).bit_count()
3</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_length(...)</code></h5>
<p>Number of bits necessary to represent self in binary.
&gt;&gt;&gt; bin(37)
&#x27;0b100101&#x27;
&gt;&gt;&gt; (37).bit_length()
6</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">conjugate(...)</code></h5>
<p>Returns self, the complex conjugate of any int.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Indicates whether two&#x27;s complement is used to represent the integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_integer(...)</code></h5>
<p>Returns True. Exists for duck type compatibility with float.is_integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Determines whether two&#x27;s complement is used to represent the integer.
If signed is False and a negative integer is given, an OverflowError
is raised.</p>
</div>
</div>
<div class="method-section">
<h3 id="InputState"><span class="class-name">InputState</span></h3>
<p><em>Inherits from: IntEnum</em></p>
<p>Enum representing input event states (pressed/released).
Values:
PRESSED: Key or button was pressed
RELEASED: Key or button was released
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">as_integer_ratio(...)</code></h5>
<p>Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
&gt;&gt;&gt; (10).as_integer_ratio()
(10, 1)
&gt;&gt;&gt; (-10).as_integer_ratio()
(-10, 1)
&gt;&gt;&gt; (0).as_integer_ratio()
(0, 1)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_count(...)</code></h5>
<p>Number of ones in the binary representation of the absolute value of self.
Also known as the population count.
&gt;&gt;&gt; bin(13)
&#x27;0b1101&#x27;
&gt;&gt;&gt; (13).bit_count()
3</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_length(...)</code></h5>
<p>Number of bits necessary to represent self in binary.
&gt;&gt;&gt; bin(37)
&#x27;0b100101&#x27;
&gt;&gt;&gt; (37).bit_length()
6</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">conjugate(...)</code></h5>
<p>Returns self, the complex conjugate of any int.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Indicates whether two&#x27;s complement is used to represent the integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_integer(...)</code></h5>
<p>Returns True. Exists for duck type compatibility with float.is_integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Determines whether two&#x27;s complement is used to represent the integer.
If signed is False and a negative integer is given, an OverflowError
is raised.</p>
</div>
</div>
<div class="method-section">
<h3 id="Key"><span class="class-name">Key</span></h3>
<p><em>Inherits from: IntEnum</em></p>
<p>Enum representing keyboard keys.
Values map to SFML&#x27;s sf::Keyboard::Key enum.
Categories:
Letters: A-Z
Numbers: NUM_0 through NUM_9 (top row)
Numpad: NUMPAD_0 through NUMPAD_9
Function: F1 through F15
Modifiers: LEFT_SHIFT, RIGHT_SHIFT, LEFT_CONTROL, etc.
Navigation: LEFT, RIGHT, UP, DOWN, HOME, END, PAGE_UP, PAGE_DOWN
Editing: ENTER, BACKSPACE, DELETE, INSERT, TAB, SPACE
Symbols: COMMA, PERIOD, SLASH, SEMICOLON, etc.
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">as_integer_ratio(...)</code></h5>
<p>Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
&gt;&gt;&gt; (10).as_integer_ratio()
(10, 1)
&gt;&gt;&gt; (-10).as_integer_ratio()
(-10, 1)
&gt;&gt;&gt; (0).as_integer_ratio()
(0, 1)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_count(...)</code></h5>
<p>Number of ones in the binary representation of the absolute value of self.
Also known as the population count.
&gt;&gt;&gt; bin(13)
&#x27;0b1101&#x27;
&gt;&gt;&gt; (13).bit_count()
3</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_length(...)</code></h5>
<p>Number of bits necessary to represent self in binary.
&gt;&gt;&gt; bin(37)
&#x27;0b100101&#x27;
&gt;&gt;&gt; (37).bit_length()
6</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">conjugate(...)</code></h5>
<p>Returns self, the complex conjugate of any int.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Indicates whether two&#x27;s complement is used to represent the integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_integer(...)</code></h5>
<p>Returns True. Exists for duck type compatibility with float.is_integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Determines whether two&#x27;s complement is used to represent the integer.
If signed is False and a negative integer is given, an OverflowError
is raised.</p>
</div>
</div>
<div class="method-section">
<h3 id="Keyboard"><span class="class-name">Keyboard</span></h3>
<p>Keyboard state singleton for checking modifier keys</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>alt</span> (read-only): True if either Alt key is currently pressed (read-only).</li>
<li><span class='property-name'>ctrl</span> (read-only): True if either Control key is currently pressed (read-only).</li>
<li><span class='property-name'>shift</span> (read-only): True if either Shift key is currently pressed (read-only).</li>
<li><span class='property-name'>system</span> (read-only): True if either System key (Win/Cmd) is currently pressed (read-only).</li>
</ul>
<h4>Methods:</h4>
</div>
<div class="method-section">
<h3 id="LdtkProject"><span class="class-name">LdtkProject</span></h3>
<p>LdtkProject(path: str)
Load an LDtk project file (.ldtk).
Parses the project and provides access to tilesets, auto-rule sets,
levels, and enum definitions.
Args:
path: Path to the .ldtk project file.
Properties:
version (str, read-only): LDtk JSON format version.
tileset_names (list[str], read-only): Names of all tilesets.
ruleset_names (list[str], read-only): Names of all rule sets.
level_names (list[str], read-only): Names of all levels.
enums (dict, read-only): Enum definitions from the project.
Example:
proj = mcrfpy.LdtkProject(&#x27;dungeon.ldtk&#x27;)
ts = proj.tileset(&#x27;Dungeon_Tiles&#x27;)
rs = proj.ruleset(&#x27;Walls&#x27;)
level = proj.level(&#x27;Level_0&#x27;)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>enums</span> (read-only): Enum definitions from the project as a list of dicts (read-only).</li>
<li><span class='property-name'>level_names</span> (read-only): List of level identifier names (list[str], read-only).</li>
<li><span class='property-name'>ruleset_names</span> (read-only): List of rule set / layer names (list[str], read-only).</li>
<li><span class='property-name'>tileset_names</span> (read-only): List of tileset identifier names (list[str], read-only).</li>
<li><span class='property-name'>version</span> (read-only): LDtk JSON format version string (str, read-only).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">level(name: str) -> dict</code></h5>
<p>Get level data by name.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>name</span>: Level identifier from the LDtk project</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Dict with name, dimensions, world position, and layer data.</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> KeyError: If no level with the given name exists</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">ruleset(name: str) -> AutoRuleSet</code></h5>
<p>Get an auto-rule set by layer name.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>name</span>: Layer identifier from the LDtk project</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> An AutoRuleSet for resolving IntGrid data to sprite tiles.</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> KeyError: If no ruleset with the given name exists</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">tileset(name: str) -> TileSetFile</code></h5>
<p>Get a tileset by name.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>name</span>: Tileset identifier from the LDtk project</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> A TileSetFile object for texture creation and tile metadata.</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> KeyError: If no tileset with the given name exists</p>
</div>
</div>
<div class="method-section">
<h3 id="Line"><span class="class-name">Line</span></h3>
<p><em>Inherits from: Drawable</em></p>
<p>Line(start=None, end=None, thickness=1.0, color=None, **kwargs)
A line UI element for drawing straight lines between two points.
Args:
start (tuple, optional): Starting point as (x, y). Default: (0, 0)
end (tuple, optional): Ending point as (x, y). Default: (0, 0)
thickness (float, optional): Line thickness in pixels. Default: 1.0
color (Color, optional): Line color. Default: White
Keyword Args:
on_click (callable): Click handler. Default: None
visible (bool): Visibility state. Default: True
opacity (float): Opacity (0.0-1.0). Default: 1.0
z_index (int): Rendering order. Default: 0
name (str): Element name for finding. Default: None
align (Alignment): Alignment relative to parent. Default: None
margin (float): Margin from parent edge when aligned. Default: 0
horiz_margin (float): Horizontal margin override. Default: 0 (use margin)
vert_margin (float): Vertical margin override. Default: 0 (use margin)
Attributes:
start (Vector): Starting point
end (Vector): Ending point
thickness (float): Line thickness
color (Color): Line color
visible (bool): Visibility state
opacity (float): Opacity value
z_index (int): Rendering order
name (str): Element name
align (Alignment): Alignment relative to parent (or None)
margin (float): General margin for alignment
horiz_margin (float): Horizontal margin override
vert_margin (float): Vertical margin override
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>align</span>: 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.</li>
<li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>color</span>: Line color as a Color object.</li>
<li><span class='property-name'>end</span>: Ending point of the line as a Vector.</li>
<li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>grid_pos</span>: Position in grid tile coordinates (only when parent is Grid)</li>
<li><span class='property-name'>grid_size</span>: Size in grid tile coordinates (only when parent is Grid)</li>
<li><span class='property-name'>horiz_margin</span>: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
<li><span class='property-name'>name</span>: Name for finding this element.</li>
<li><span class='property-name'>on_click</span>: Callable executed when line is clicked. Function receives (pos: Vector, button: str, action: str).</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: 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.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position as a Vector (midpoint of line).</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>start</span>: Starting point of the line as a Vector.</li>
<li><span class='property-name'>thickness</span>: Line thickness in pixels.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation</code></h5>
<p>Create and start an animation on this drawable&#x27;s property.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>property</span>: Name of the property to animate (e.g., &#x27;x&#x27;, &#x27;fill_color&#x27;, &#x27;opacity&#x27;)</div>
<div><span class='arg-name'>target</span>: Target value - type depends on property (float, tuple for color/vector, etc.)</div>
<div><span class='arg-name'>duration</span>: Animation duration in seconds</div>
<div><span class='arg-name'>easing</span>: Easing function: Easing enum value, string name, or None for linear</div>
<div><span class='arg-name'>delta</span>: If True, target is relative to current value; if False, target is absolute</div>
<div><span class='arg-name'>loop</span>: If True, animation repeats from start when it reaches the end (default False)</div>
<div><span class='arg-name'>callback</span>: Optional callable invoked when animation completes (not called for looping animations)</div>
<div><span class='arg-name'>conflict_mode</span>: &#x27;replace&#x27; (default), &#x27;queue&#x27;, or &#x27;error&#x27; if property already animating</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Animation object for monitoring progress</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> 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.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx, dy) or (delta) -> None</code></h5>
<p>Move the element by a relative offset.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>dx</span>: Horizontal offset in pixels (or use delta)</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels (or use delta)</div>
<div><span class='arg-name'>delta</span>: Offset as tuple, list, or Vector: (dx, dy)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">realign() -> None</code></h5>
<p>Reapply alignment relative to parent, useful for responsive layouts.
Note:
Call this to recalculate position after parent changes size. For elements with align=None, this has no effect.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width, height) or (size) -> None</code></h5>
<p>Resize the element to new dimensions.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>width</span>: New width in pixels (or use size)</div>
<div><span class='arg-name'>height</span>: New height in pixels (or use size)</div>
<div><span class='arg-name'>size</span>: Size as tuple, list, or Vector: (width, height)</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="Model3D"><span class="class-name">Model3D</span></h3>
<p>Model3D(path=None)
A 3D model resource that can be rendered by Entity3D.
Args:
path (str, optional): Path to .glb file to load. If None, creates empty model.
Class Methods:
cube(size=1.0) -&gt; Model3D: Create a unit cube
plane(width=1.0, depth=1.0, segments=1) -&gt; Model3D: Create a flat plane
sphere(radius=0.5, segments=16, rings=12) -&gt; Model3D: Create a UV sphere
Properties:
name (str, read-only): Model name
vertex_count (int, read-only): Total vertices across all meshes
triangle_count (int, read-only): Total triangles across all meshes
has_skeleton (bool, read-only): Whether model has skeletal animation data
bounds (tuple, read-only): AABB as ((min_x, min_y, min_z), (max_x, max_y, max_z))
mesh_count (int, read-only): Number of submeshes
bone_count (int, read-only): Number of bones in skeleton
animation_clips (list, read-only): List of animation clip names</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>animation_clips</span> (read-only): List of animation clip names (read-only)</li>
<li><span class='property-name'>bone_count</span> (read-only): Number of bones in skeleton (read-only)</li>
<li><span class='property-name'>bounds</span> (read-only): AABB as ((min_x, min_y, min_z), (max_x, max_y, max_z)) (read-only)</li>
<li><span class='property-name'>has_skeleton</span> (read-only): Whether model has skeletal animation data (read-only)</li>
<li><span class='property-name'>mesh_count</span> (read-only): Number of submeshes (read-only)</li>
<li><span class='property-name'>name</span> (read-only): Model name (read-only)</li>
<li><span class='property-name'>triangle_count</span> (read-only): Total triangle count across all meshes (read-only)</li>
<li><span class='property-name'>vertex_count</span> (read-only): Total vertex count across all meshes (read-only)</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">cube(size=1.0) -> Model3D</code></h5>
<p>Create a unit cube centered at origin.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">plane(width=1.0, depth=1.0, segments=1) -> Model3D</code></h5>
<p>Create a flat plane.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">sphere(radius=0.5, segments=16, rings=12) -> Model3D</code></h5>
<p>Create a UV sphere.</p>
</div>
</div>
<div class="method-section">
<h3 id="Mouse"><span class="class-name">Mouse</span></h3>
<p>Mouse state singleton for reading button/position state and controlling cursor visibility</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>grabbed</span>: Whether the mouse cursor is confined to the window (default: False).</li>
<li><span class='property-name'>left</span> (read-only): True if left mouse button is currently pressed (read-only).</li>
<li><span class='property-name'>middle</span> (read-only): True if middle mouse button is currently pressed (read-only).</li>
<li><span class='property-name'>pos</span> (read-only): Current mouse position as Vector (read-only).</li>
<li><span class='property-name'>right</span> (read-only): True if right mouse button is currently pressed (read-only).</li>
<li><span class='property-name'>visible</span>: Whether the mouse cursor is visible (default: True).</li>
<li><span class='property-name'>x</span> (read-only): Current mouse X position in window coordinates (read-only).</li>
<li><span class='property-name'>y</span> (read-only): Current mouse Y position in window coordinates (read-only).</li>
</ul>
<h4>Methods:</h4>
</div>
<div class="method-section">
<h3 id="MouseButton"><span class="class-name">MouseButton</span></h3>
<p><em>Inherits from: IntEnum</em></p>
<p>Enum representing mouse buttons and scroll wheel.
Values:
LEFT: Left mouse button
RIGHT: Right mouse button
MIDDLE: Middle mouse button / scroll wheel click
X1: Extra mouse button 1
X2: Extra mouse button 2
SCROLL_UP: Scroll wheel up
SCROLL_DOWN: Scroll wheel down
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">as_integer_ratio(...)</code></h5>
<p>Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
&gt;&gt;&gt; (10).as_integer_ratio()
(10, 1)
&gt;&gt;&gt; (-10).as_integer_ratio()
(-10, 1)
&gt;&gt;&gt; (0).as_integer_ratio()
(0, 1)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_count(...)</code></h5>
<p>Number of ones in the binary representation of the absolute value of self.
Also known as the population count.
&gt;&gt;&gt; bin(13)
&#x27;0b1101&#x27;
&gt;&gt;&gt; (13).bit_count()
3</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_length(...)</code></h5>
<p>Number of bits necessary to represent self in binary.
&gt;&gt;&gt; bin(37)
&#x27;0b100101&#x27;
&gt;&gt;&gt; (37).bit_length()
6</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">conjugate(...)</code></h5>
<p>Returns self, the complex conjugate of any int.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Indicates whether two&#x27;s complement is used to represent the integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_integer(...)</code></h5>
<p>Returns True. Exists for duck type compatibility with float.is_integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Determines whether two&#x27;s complement is used to represent the integer.
If signed is False and a negative integer is given, an OverflowError
is raised.</p>
</div>
</div>
<div class="method-section">
<h3 id="Music"><span class="class-name">Music</span></h3>
<p>Streaming music object for longer audio tracks</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>duration</span> (read-only): Total duration of the music in seconds (read-only).</li>
<li><span class='property-name'>loop</span>: Whether the music loops when it reaches the end.</li>
<li><span class='property-name'>playing</span> (read-only): True if the music is currently playing (read-only).</li>
<li><span class='property-name'>position</span>: Current playback position in seconds. Can be set to seek.</li>
<li><span class='property-name'>source</span> (read-only): Filename path used to load this music (read-only).</li>
<li><span class='property-name'>volume</span>: Volume level from 0 (silent) to 100 (full volume).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">pause() -> None</code></h5>
<p>Pause the music. Use play() to resume from the paused position.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">play() -> None</code></h5>
<p>Start or resume playing the music.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">stop() -> None</code></h5>
<p>Stop playing and reset to the beginning.</p>
</div>
</div>
<div class="method-section">
<h3 id="NoiseSource"><span class="class-name">NoiseSource</span></h3>
<p>NoiseSource(dimensions: int = 2, algorithm: str = &#x27;simplex&#x27;, hurst: float = 0.5, lacunarity: float = 2.0, seed: int = None)
A configured noise generator for procedural generation.
NoiseSource wraps libtcod&#x27;s noise generator, providing coherent noise values that can be used for terrain generation, textures, and other procedural content. The same coordinates always produce the same value (deterministic).
Args:
dimensions: Number of input dimensions (1-4). Default: 2.
algorithm: Noise algorithm - &#x27;simplex&#x27;, &#x27;perlin&#x27;, or &#x27;wavelet&#x27;. Default: &#x27;simplex&#x27;.
hurst: Fractal Hurst exponent for fbm/turbulence (0.0-1.0). Default: 0.5.
lacunarity: Frequency multiplier between octaves. Default: 2.0.
seed: Random seed for reproducibility. None for random seed.
Properties:
dimensions (int): Read-only. Number of input dimensions.
algorithm (str): Read-only. Noise algorithm name.
hurst (float): Read-only. Hurst exponent.
lacunarity (float): Read-only. Lacunarity value.
seed (int): Read-only. Seed used (even if originally None).
Example:
noise = mcrfpy.NoiseSource(dimensions=2, algorithm=&#x27;simplex&#x27;, 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)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>algorithm</span> (read-only): Noise algorithm name (&#x27;simplex&#x27;, &#x27;perlin&#x27;, or &#x27;wavelet&#x27;). Read-only.</li>
<li><span class='property-name'>dimensions</span> (read-only): Number of input dimensions (1-4). Read-only.</li>
<li><span class='property-name'>hurst</span> (read-only): Hurst exponent for fbm/turbulence. Read-only.</li>
<li><span class='property-name'>lacunarity</span> (read-only): Frequency multiplier between octaves. Read-only.</li>
<li><span class='property-name'>seed</span> (read-only): Random seed used (even if originally None). Read-only.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fbm(pos: tuple[float, ...], octaves: int = 4) -> float</code></h5>
<p>Get fractal brownian motion value at coordinates.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Position tuple with length matching dimensions</div>
<div><span class='arg-name'>octaves</span>: Number of noise octaves to combine (default: 4)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> float: FBM noise value in range [-1.0, 1.0]</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: Position tuple length doesn&#x27;t match dimensions</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get(pos: tuple[float, ...]) -> float</code></h5>
<p>Get flat noise value at coordinates.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Position tuple with length matching dimensions</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> float: Noise value in range [-1.0, 1.0]</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: Position tuple length doesn&#x27;t match dimensions</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">sample(size: tuple[int, int], world_origin: tuple[float, float] = (0.0, 0.0), world_size: tuple[float, float] = None, mode: str = 'fbm', octaves: int = 4) -> HeightMap</code></h5>
<p>Sample noise into a HeightMap for batch processing.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>size</span>: Output dimensions in cells as (width, height)</div>
<div><span class='arg-name'>world_origin</span>: World coordinates of top-left corner (default: (0, 0))</div>
<div><span class='arg-name'>world_size</span>: World area to sample (default: same as size)</div>
<div><span class='arg-name'>mode</span>: Sampling mode: &#x27;flat&#x27;, &#x27;fbm&#x27;, or &#x27;turbulence&#x27; (default: &#x27;fbm&#x27;)</div>
<div><span class='arg-name'>octaves</span>: Octaves for fbm/turbulence modes (default: 4)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> HeightMap: New HeightMap filled with sampled noise values Requires dimensions=2. Values are in range [-1.0, 1.0].</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">turbulence(pos: tuple[float, ...], octaves: int = 4) -> float</code></h5>
<p>Get turbulence (absolute fbm) value at coordinates.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Position tuple with length matching dimensions</div>
<div><span class='arg-name'>octaves</span>: Number of noise octaves to combine (default: 4)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> float: Turbulence noise value in range [-1.0, 1.0]</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: Position tuple length doesn&#x27;t match dimensions</p>
</div>
</div>
<div class="method-section">
<h3 id="Perspective"><span class="class-name">Perspective</span></h3>
<p><em>Inherits from: IntEnum</em></p>
<p>Enum representing an entity&#x27;s knowledge of a cell.
Values:
UNKNOWN: Never seen (perspective_map value 0)
DISCOVERED: Seen before but not currently visible (value 1)
VISIBLE: In current FOV (value 2)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">as_integer_ratio(...)</code></h5>
<p>Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
&gt;&gt;&gt; (10).as_integer_ratio()
(10, 1)
&gt;&gt;&gt; (-10).as_integer_ratio()
(-10, 1)
&gt;&gt;&gt; (0).as_integer_ratio()
(0, 1)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_count(...)</code></h5>
<p>Number of ones in the binary representation of the absolute value of self.
Also known as the population count.
&gt;&gt;&gt; bin(13)
&#x27;0b1101&#x27;
&gt;&gt;&gt; (13).bit_count()
3</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_length(...)</code></h5>
<p>Number of bits necessary to represent self in binary.
&gt;&gt;&gt; bin(37)
&#x27;0b100101&#x27;
&gt;&gt;&gt; (37).bit_length()
6</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">conjugate(...)</code></h5>
<p>Returns self, the complex conjugate of any int.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Indicates whether two&#x27;s complement is used to represent the integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_integer(...)</code></h5>
<p>Returns True. Exists for duck type compatibility with float.is_integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Determines whether two&#x27;s complement is used to represent the integer.
If signed is False and a negative integer is given, an OverflowError
is raised.</p>
</div>
</div>
<div class="method-section">
<h3 id="PropertyBinding"><span class="class-name">PropertyBinding</span></h3>
<p>PropertyBinding(target: UIDrawable, property: str)
A binding that reads a property value from a UI drawable.
Args:
target: The drawable to read the property from
property: Name of the property to read (e.g., &#x27;x&#x27;, &#x27;opacity&#x27;)
Use this to create dynamic shader uniforms that follow a drawable&#x27;s
properties. The binding automatically handles cases where the target
is destroyed.
Example:
other_frame = mcrfpy.Frame(pos=(100, 100))
frame.uniforms[&#x27;offset_x&#x27;] = mcrfpy.PropertyBinding(other_frame, &#x27;x&#x27;)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>is_valid</span> (read-only): True if the binding target still exists and property is valid (bool, read-only).</li>
<li><span class='property-name'>property</span> (read-only): The property name being read (str, read-only).</li>
<li><span class='property-name'>target</span> (read-only): The drawable this binding reads from (read-only).</li>
<li><span class='property-name'>value</span> (read-only): Current value of the binding (float, read-only). Returns None if invalid.</li>
</ul>
<h4>Methods:</h4>
</div>
<div class="method-section">
<h3 id="Scene"><span class="class-name">Scene</span></h3>
<p>Scene(name: str)
Object-oriented scene management with lifecycle callbacks.
This is the recommended approach for scene management, replacing module-level
functions like createScene(), setScene(), and sceneUI(). Key advantage: you can
set on_key handlers on ANY scene, not just the currently active one.
Args:
name: Unique identifier for this scene. Used for scene transitions.
Properties:
name (str, read-only): Scene&#x27;s unique identifier.
active (bool, read-only): Whether this scene is currently displayed.
children (UICollection, read-only): UI elements in this scene. Modify to add/remove elements.
on_key (callable): Keyboard handler. Set on ANY scene, regardless of which is active!
pos (Vector): Position offset for all UI elements.
visible (bool): Whether the scene renders.
opacity (float): Scene transparency (0.0-1.0).
Lifecycle Callbacks (override in subclass):
on_enter(): Called when scene becomes active via activate().
on_exit(): Called when scene is deactivated (another scene activates).
on_key(key: str, action: str): Called for keyboard events (subclass method).
update(dt: float): Called every frame with delta time in seconds.
on_resize(new_size: Vector): Called when window is resized.
Example:
# Basic usage (replacing module functions):
scene = mcrfpy.Scene(&#x27;main_menu&#x27;)
scene.children.append(mcrfpy.Caption(text=&#x27;Welcome&#x27;, pos=(100, 100)))
scene.on_key = lambda key, action: print(f&#x27;Key: {key}&#x27;)
scene.activate() # Switch to this scene
# Subclassing for lifecycle:
class GameScene(mcrfpy.Scene):
def on_enter(self):
print(&#x27;Game started!&#x27;)
def update(self, dt):
self.player.move(dt)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>active</span> (read-only): Whether this scene is currently active (bool, read-only). Only one scene can be active at a time.</li>
<li><span class='property-name'>children</span> (read-only): UI element collection for this scene (UICollection, read-only). Use to add, remove, or iterate over UI elements. Changes are reflected immediately.</li>
<li><span class='property-name'>name</span> (read-only): Scene name (str, read-only). Unique identifier for this scene.</li>
<li><span class='property-name'>on_key</span>: Keyboard event handler (callable or None). Function receives (key: Key, action: InputState) for keyboard events. Set to None to remove the handler.</li>
<li><span class='property-name'>opacity</span>: Scene opacity (0.0-1.0). Applied to all UI elements during rendering.</li>
<li><span class='property-name'>pos</span>: Scene position offset (Vector). Applied to all UI elements during rendering.</li>
<li><span class='property-name'>registered</span> (read-only): Whether this scene is registered with the game engine (bool, read-only). Unregistered scenes still exist but won&#x27;t receive lifecycle callbacks.</li>
<li><span class='property-name'>visible</span>: Scene visibility (bool). If False, scene is not rendered.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">activate(transition: Transition = None, duration: float = None) -> None</code></h5>
<p>Make this the active scene with optional transition effect.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>transition</span>: Transition type (mcrfpy.Transition enum). Defaults to mcrfpy.default_transition</div>
<div><span class='arg-name'>duration</span>: Transition duration in seconds. Defaults to mcrfpy.default_transition_duration</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None Deactivates the current scene and activates this one. Lifecycle callbacks (on_exit, on_enter) are triggered.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">realign() -> None</code></h5>
<p>Recalculate alignment for all children with alignment set.
Note:
Call this after window resize or when game_resolution changes. For responsive layouts, connect this to on_resize callback.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">register() -> None</code></h5>
<p>Register this scene with the game engine.
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.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">unregister() -> None</code></h5>
<p>Unregister this scene from the game engine.
Note:
Removes the scene from the engine&#x27;s registry but keeps the Python object alive. The scene&#x27;s UI elements and state are preserved. Call register() to re-add it. Useful for temporary scenes or scene pooling.</p>
</div>
</div>
<div class="method-section">
<h3 id="Shader"><span class="class-name">Shader</span></h3>
<p>Shader(fragment_source: str, dynamic: bool = False)
A GPU shader program for visual effects.
Args:
fragment_source: GLSL fragment shader source code
dynamic: If True, shader uses time-varying effects and will
invalidate parent caches each frame
Shaders enable GPU-accelerated visual effects like glow, distortion,
color manipulation, and more. Assign to drawable.shader to apply.
Engine-provided uniforms (automatically available):
- float time: Seconds since engine start
- float delta_time: Seconds since last frame
- vec2 resolution: Texture size in pixels
- vec2 mouse: Mouse position in window coordinates
Example:
shader = mcrfpy.Shader(&#x27;&#x27;&#x27;
uniform sampler2D texture;
uniform float time;
void main() {
vec2 uv = gl_TexCoord[0].xy;
vec4 color = texture2D(texture, uv);
color.rgb *= 0.5 + 0.5 * sin(time);
gl_FragColor = color;
}
&#x27;&#x27;&#x27;, dynamic=True)
frame.shader = shader
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>dynamic</span>: Whether this shader uses time-varying effects (bool). Dynamic shaders invalidate parent caches each frame.</li>
<li><span class='property-name'>is_valid</span> (read-only): True if the shader compiled successfully (bool, read-only).</li>
<li><span class='property-name'>source</span> (read-only): The GLSL fragment shader source code (str, read-only).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">set_uniform(name: str, value: float|tuple) -> None</code></h5>
<p>Set a custom uniform value on this shader.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>name</span>: Uniform variable name in the shader</div>
<div><span class='arg-name'>value</span>: Float, vec2 (2-tuple), vec3 (3-tuple), or vec4 (4-tuple)</div>
</div>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: If uniform type cannot be determined Engine uniforms (time, resolution, etc.) are set automatically</p>
</div>
</div>
<div class="method-section">
<h3 id="Sound"><span class="class-name">Sound</span></h3>
<p>Sound(source)
Sound effect object for short audio clips.
Args:
source: Filename string or SoundBuffer object.
Properties:
volume (float): Volume 0-100.
loop (bool): Whether to loop.
playing (bool, read-only): True if playing.
duration (float, read-only): Duration in seconds.
source (str, read-only): Source filename.
pitch (float): Playback pitch (1.0 = normal).
buffer (SoundBuffer, read-only): The SoundBuffer, if created from one.
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>buffer</span> (read-only): The SoundBuffer if created from one, else None (read-only).</li>
<li><span class='property-name'>duration</span> (read-only): Total duration of the sound in seconds (read-only).</li>
<li><span class='property-name'>loop</span>: Whether the sound loops when it reaches the end.</li>
<li><span class='property-name'>pitch</span>: Playback pitch multiplier (1.0 = normal, &gt;1 = higher, &lt;1 = lower).</li>
<li><span class='property-name'>playing</span> (read-only): True if the sound is currently playing (read-only).</li>
<li><span class='property-name'>source</span> (read-only): Filename path used to load this sound (read-only).</li>
<li><span class='property-name'>volume</span>: Volume level from 0 (silent) to 100 (full volume).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">pause() -> None</code></h5>
<p>Pause the sound. Use play() to resume from the paused position.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">play() -> None</code></h5>
<p>Start or resume playing the sound.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">play_varied(pitch_range: float = 0.1, volume_range: float = 3.0) -> None</code></h5>
<p>Play with randomized pitch and volume for natural variation.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pitch_range</span>: Random pitch offset range (default 0.1)</div>
<div><span class='arg-name'>volume_range</span>: Random volume offset range (default 3.0)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">stop() -> None</code></h5>
<p>Stop playing and reset to the beginning.</p>
</div>
</div>
<div class="method-section">
<h3 id="SoundBuffer"><span class="class-name">SoundBuffer</span></h3>
<p>SoundBuffer(filename: str)
SoundBuffer.from_samples(data: bytes, channels: int, sample_rate: int)
SoundBuffer.tone(frequency: float, duration: float, waveform: str = &#x27;sine&#x27;, ...)
SoundBuffer.sfxr(preset: str, seed: int = None)
Audio sample buffer for procedural audio generation and effects.
Holds PCM sample data that can be created from files, raw samples,
tone synthesis, or sfxr presets. Effect methods return new SoundBuffer
instances (copy-modify pattern).
Properties:
duration (float, read-only): Duration in seconds.
sample_count (int, read-only): Total number of samples.
sample_rate (int, read-only): Samples per second (e.g. 44100).
channels (int, read-only): Number of audio channels.
sfxr_params (dict or None, read-only): sfxr parameters if sfxr-generated.
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>channels</span> (read-only): Number of audio channels (read-only).</li>
<li><span class='property-name'>duration</span> (read-only): Total duration in seconds (read-only).</li>
<li><span class='property-name'>sample_count</span> (read-only): Total number of samples (read-only).</li>
<li><span class='property-name'>sample_rate</span> (read-only): Sample rate in Hz (read-only).</li>
<li><span class='property-name'>sfxr_params</span> (read-only): Dict of sfxr parameters if sfxr-generated, else None (read-only).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_crush(bits: int, rate_divisor: int) -> SoundBuffer</code></h5>
<p>Reduce bit depth and sample rate for lo-fi effect.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">concat(buffers: list[SoundBuffer], overlap: float = 0.0) -> SoundBuffer</code></h5>
<p>Concatenate multiple SoundBuffers with optional crossfade overlap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>buffers</span>: List of SoundBuffer objects to concatenate</div>
<div><span class='arg-name'>overlap</span>: Crossfade overlap duration in seconds</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">distortion(drive: float) -> SoundBuffer</code></h5>
<p>Apply tanh soft clipping distortion.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">echo(delay_ms: float, feedback: float, wet: float) -> SoundBuffer</code></h5>
<p>Apply echo effect with delay, feedback, and wet/dry mix.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_samples(data: bytes, channels: int, sample_rate: int) -> SoundBuffer</code></h5>
<p>Create a SoundBuffer from raw int16 PCM sample data.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>data</span>: Raw PCM data as bytes (int16 little-endian)</div>
<div><span class='arg-name'>channels</span>: Number of audio channels (1=mono, 2=stereo)</div>
<div><span class='arg-name'>sample_rate</span>: Sample rate in Hz (e.g. 44100)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">gain(factor: float) -> SoundBuffer</code></h5>
<p>Multiply all samples by a scalar factor. Use for volume/amplitude control before mixing.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>factor</span>: Amplitude multiplier (0.5 = half volume, 2.0 = double). Clamps to int16 range.</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">high_pass(cutoff_hz: float) -> SoundBuffer</code></h5>
<p>Apply single-pole IIR high-pass filter.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">low_pass(cutoff_hz: float) -> SoundBuffer</code></h5>
<p>Apply single-pole IIR low-pass filter.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">mix(buffers: list[SoundBuffer]) -> SoundBuffer</code></h5>
<p>Mix multiple SoundBuffers together (additive, clamped).</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>buffers</span>: List of SoundBuffer objects to mix</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">normalize() -> SoundBuffer</code></h5>
<p>Scale samples to 95%% of int16 max.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">pitch_shift(factor: float) -> SoundBuffer</code></h5>
<p>Resample to shift pitch. factor&gt;1 = higher+shorter.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">reverb(room_size: float, damping: float, wet: float) -> SoundBuffer</code></h5>
<p>Apply simplified Freeverb-style reverb.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">reverse() -> SoundBuffer</code></h5>
<p>Reverse the sample order.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">sfxr(preset: str = None, seed: int = None, **params) -> SoundBuffer</code></h5>
<p>Generate retro sound effects using sfxr synthesis.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>preset</span>: One of: coin, laser, explosion, powerup, hurt, jump, blip</div>
<div><span class='arg-name'>seed</span>: Random seed for deterministic generation</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> SoundBuffer with sfxr_params set for later mutation</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">sfxr_mutate(amount: float = 0.05, seed: int = None) -> SoundBuffer</code></h5>
<p>Jitter sfxr params and re-synthesize. Only works on sfxr-generated buffers.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">slice(start: float, end: float) -> SoundBuffer</code></h5>
<p>Extract a time range in seconds.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">tone(frequency: float, duration: float, waveform: str = 'sine', ...) -> SoundBuffer</code></h5>
<p>Generate a tone with optional ADSR envelope.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>frequency</span>: Frequency in Hz</div>
<div><span class='arg-name'>duration</span>: Duration in seconds</div>
<div><span class='arg-name'>waveform</span>: One of: sine, square, saw, triangle, noise</div>
<div><span class='arg-name'>attack</span>: ADSR attack time in seconds (default 0.01)</div>
<div><span class='arg-name'>decay</span>: ADSR decay time in seconds (default 0.0)</div>
<div><span class='arg-name'>sustain</span>: ADSR sustain level 0.0-1.0 (default 1.0)</div>
<div><span class='arg-name'>release</span>: ADSR release time in seconds (default 0.01)</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="Sprite"><span class="class-name">Sprite</span></h3>
<p><em>Inherits from: Drawable</em></p>
<p>Sprite(pos=None, texture=None, sprite_index=0, **kwargs)
A sprite UI element that displays a texture or portion of a texture atlas.
Args:
pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0)
texture (Texture, optional): Texture object to display. Default: default texture
sprite_index (int, optional): Index into texture atlas. Default: 0
Keyword Args:
scale (float): Uniform scale factor. Default: 1.0
scale_x (float): Horizontal scale factor. Default: 1.0
scale_y (float): Vertical scale factor. Default: 1.0
click (callable): Click event handler. Default: None
visible (bool): Visibility state. Default: True
opacity (float): Opacity (0.0-1.0). Default: 1.0
z_index (int): Rendering order. Default: 0
name (str): Element name for finding. Default: None
x (float): X position override. Default: 0
y (float): Y position override. Default: 0
align (Alignment): Alignment relative to parent. Default: None
margin (float): Margin from parent edge when aligned. Default: 0
horiz_margin (float): Horizontal margin override. Default: 0 (use margin)
vert_margin (float): Vertical margin override. Default: 0 (use margin)
Attributes:
x, y (float): Position in pixels
pos (Vector): Position as a Vector object
texture (Texture): The texture being displayed
sprite_index (int): Current sprite index in texture atlas
scale (float): Uniform scale factor
scale_x, scale_y (float): Individual scale factors
click (callable): Click event handler
visible (bool): Visibility state
opacity (float): Opacity value
z_index (int): Rendering order
name (str): Element name
w, h (float): Read-only computed size based on texture and scale
align (Alignment): Alignment relative to parent (or None)
margin (float): General margin for alignment
horiz_margin (float): Horizontal margin override
vert_margin (float): Vertical margin override</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>align</span>: 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.</li>
<li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>grid_pos</span>: Position in grid tile coordinates (only when parent is Grid)</li>
<li><span class='property-name'>grid_size</span>: Size in grid tile coordinates (only when parent is Grid)</li>
<li><span class='property-name'>horiz_margin</span>: Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>margin</span>: General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).</li>
<li><span class='property-name'>name</span>: Name for finding elements</li>
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: 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.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position as a Vector</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>scale</span>: Uniform size factor</li>
<li><span class='property-name'>scale_x</span>: Horizontal scale factor</li>
<li><span class='property-name'>scale_y</span>: Vertical scale factor</li>
<li><span class='property-name'>shader</span>: 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.</li>
<li><span class='property-name'>sprite_index</span>: Which sprite on the texture is shown</li>
<li><span class='property-name'>texture</span>: Texture object</li>
<li><span class='property-name'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>x</span>: X coordinate of top-left corner</li>
<li><span class='property-name'>y</span>: Y coordinate of top-left corner</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation</code></h5>
<p>Create and start an animation on this drawable&#x27;s property.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>property</span>: Name of the property to animate (e.g., &#x27;x&#x27;, &#x27;fill_color&#x27;, &#x27;opacity&#x27;)</div>
<div><span class='arg-name'>target</span>: Target value - type depends on property (float, tuple for color/vector, etc.)</div>
<div><span class='arg-name'>duration</span>: Animation duration in seconds</div>
<div><span class='arg-name'>easing</span>: Easing function: Easing enum value, string name, or None for linear</div>
<div><span class='arg-name'>delta</span>: If True, target is relative to current value; if False, target is absolute</div>
<div><span class='arg-name'>loop</span>: If True, animation repeats from start when it reaches the end (default False)</div>
<div><span class='arg-name'>callback</span>: Optional callable invoked when animation completes (not called for looping animations)</div>
<div><span class='arg-name'>conflict_mode</span>: &#x27;replace&#x27; (default), &#x27;queue&#x27;, or &#x27;error&#x27; if property already animating</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Animation object for monitoring progress</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> 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.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx, dy) or (delta) -> None</code></h5>
<p>Move the element by a relative offset.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>dx</span>: Horizontal offset in pixels (or use delta)</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels (or use delta)</div>
<div><span class='arg-name'>delta</span>: Offset as tuple, list, or Vector: (dx, dy)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">realign() -> None</code></h5>
<p>Reapply alignment relative to parent, useful for responsive layouts.
Note:
Call this to recalculate position after parent changes size. For elements with align=None, this has no effect.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width, height) or (size) -> None</code></h5>
<p>Resize the element to new dimensions.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>width</span>: New width in pixels (or use size)</div>
<div><span class='arg-name'>height</span>: New height in pixels (or use size)</div>
<div><span class='arg-name'>size</span>: Size as tuple, list, or Vector: (width, height)</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="Texture"><span class="class-name">Texture</span></h3>
<p>Texture(filename: str, sprite_width: int = 0, sprite_height: int = 0, display_size: tuple = None, display_origin: tuple = None)
A texture atlas for sprites and tiles.
Args:
filename: Path to an image file (PNG, BMP, etc.).
sprite_width: Width of each sprite cell in pixels (0 = full image).
sprite_height: Height of each sprite cell in pixels (0 = full image).
display_size: Optional (w, h) actual content size within each cell.
display_origin: Optional (x, y) content offset within each cell.
Properties:
sprite_width, sprite_height (int, read-only): Cell dimensions.
sheet_width, sheet_height (int, read-only): Grid dimensions in cells.
sprite_count (int, read-only): Total number of sprite cells.
source (str, read-only): File path used to load this texture.
display_width, display_height (int, read-only): Content size within cells.
display_offset_x, display_offset_y (int, read-only): Content offset within cells.
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>display_height</span> (read-only): Display height of sprite content within each cell (int, read-only). Defaults to sprite_height.</li>
<li><span class='property-name'>display_offset_x</span> (read-only): X offset of sprite content within each cell (int, read-only). Default 0.</li>
<li><span class='property-name'>display_offset_y</span> (read-only): Y offset of sprite content within each cell (int, read-only). Default 0.</li>
<li><span class='property-name'>display_width</span> (read-only): Display width of sprite content within each cell (int, read-only). Defaults to sprite_width.</li>
<li><span class='property-name'>sheet_height</span> (read-only): Number of sprite rows in the texture sheet (int, read-only). Calculated as texture_height / sprite_height.</li>
<li><span class='property-name'>sheet_width</span> (read-only): Number of sprite columns in the texture sheet (int, read-only). Calculated as texture_width / sprite_width.</li>
<li><span class='property-name'>source</span> (read-only): Source filename path (str, read-only). The path used to load this texture.</li>
<li><span class='property-name'>sprite_count</span> (read-only): Total number of sprites in the texture sheet (int, read-only). Equals sheet_width * sheet_height.</li>
<li><span class='property-name'>sprite_height</span> (read-only): Height of each sprite in pixels (int, read-only). Specified during texture initialization.</li>
<li><span class='property-name'>sprite_width</span> (read-only): Width of each sprite in pixels (int, read-only). Specified during texture initialization.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">composite(layers: list[Texture], sprite_width: int, sprite_height: int, name: str = '<composite>') -> Texture</code></h5>
<p>Alpha-composite multiple texture layers into a single texture.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>layers</span>: List of Texture objects, composited bottom-to-top</div>
<div><span class='arg-name'>sprite_width</span>: Width of each sprite cell in the result</div>
<div><span class='arg-name'>sprite_height</span>: Height of each sprite cell in the result</div>
<div><span class='arg-name'>name</span>: Optional name for the composite texture</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Texture: New texture with all layers composited</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: If layers have different dimensions or list is empty This is a class method. Uses Porter-Duff &#x27;over&#x27; alpha compositing.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(data: bytes, width: int, height: int, sprite_width: int, sprite_height: int, name: str = '<generated>') -> Texture</code></h5>
<p>Create a Texture from raw RGBA pixel data.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>data</span>: Raw RGBA bytes (length must equal width * height * 4)</div>
<div><span class='arg-name'>width</span>: Image width in pixels</div>
<div><span class='arg-name'>height</span>: Image height in pixels</div>
<div><span class='arg-name'>sprite_width</span>: Width of each sprite cell</div>
<div><span class='arg-name'>sprite_height</span>: Height of each sprite cell</div>
<div><span class='arg-name'>name</span>: Optional name for the texture (default: &#x27;&lt;generated&gt;&#x27;)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Texture: New texture containing the pixel data</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: If data length does not match width * height * 4 This is a class method. Useful for procedurally generated textures.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">hsl_shift(hue_shift: float, sat_shift: float = 0.0, lit_shift: float = 0.0) -> Texture</code></h5>
<p>Create a new texture with HSL color adjustments applied.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>hue_shift</span>: Hue rotation in degrees [0.0, 360.0)</div>
<div><span class='arg-name'>sat_shift</span>: Saturation adjustment [-1.0, 1.0] (default 0.0)</div>
<div><span class='arg-name'>lit_shift</span>: Lightness adjustment [-1.0, 1.0] (default 0.0)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Texture: New texture with color-shifted pixels Preserves alpha channel. Skips fully transparent pixels.</p>
</div>
</div>
<div class="method-section">
<h3 id="TileLayer"><span class="class-name">TileLayer</span></h3>
<p>TileLayer(z_index=-1, name=None, texture=None, grid_size=None)
A grid layer that stores sprite indices per cell for tile-based rendering.
TileLayers can be created standalone and attached to a Grid via add_layer()
or passed to the Grid constructor&#x27;s layers parameter. Layers with size (0, 0)
automatically resize to match the Grid when attached.
Args:
z_index (int): Render order relative to entities. Negative values render
below entities (as backgrounds), positive values render above entities
(as overlays). Default: -1 (background)
name (str): Layer name for Grid.layer(name) lookup. Default: None
texture (Texture): Sprite atlas containing tile images. The texture&#x27;s
sprite_size determines individual tile dimensions. Required for
rendering; can be set after creation. Default: None
grid_size (tuple): Dimensions as (width, height). If None or (0, 0), the
layer will auto-resize when attached to a Grid. Default: None
Attributes:
z_index (int): Layer z-order relative to entities (read/write)
name (str): Layer name for lookup (read-only)
visible (bool): Whether layer is rendered (read/write)
texture (Texture): Sprite atlas for tile images (read/write)
grid_size (tuple): Layer dimensions as (width, height) (read-only)
grid (Grid): Parent Grid or None. Setting manages layer association.
Methods:
at(x, y) -&gt; int: Get the tile index at cell position (x, y)
set(x, y, index): Set the tile index at cell position (x, y)
fill(index): Fill the entire layer with a single tile index
fill_rect(x, y, w, h, index): Fill a rectangular region with a tile index
Tile Index Values:
-1: No tile (transparent/empty cell)
0+: Index into the texture&#x27;s sprite atlas (row-major order)
Example:
terrain = mcrfpy.TileLayer(z_index=-2, name=&#x27;terrain&#x27;, texture=tileset)
grid = mcrfpy.Grid(grid_size=(20, 15), layers=[terrain])
terrain.fill(0) # Fill with tile index 0
grid.layer(&#x27;terrain&#x27;).set(5, 5, 42) # Place tile 42 at (5, 5)</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>grid</span>: Parent Grid or None. Setting manages layer association and handles lazy allocation.</li>
<li><span class='property-name'>grid_size</span>: Layer dimensions as (width, height) tuple.</li>
<li><span class='property-name'>name</span> (read-only): Layer name (str, read-only). Used for Grid.layer(name) lookup.</li>
<li><span class='property-name'>texture</span>: Texture atlas for tile sprites.</li>
<li><span class='property-name'>visible</span>: Whether the layer is rendered.</li>
<li><span class='property-name'>z_index</span>: Layer z-order. Negative values render below entities.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">apply_ranges(source, ranges) -> TileLayer</code></h5>
<p>Apply multiple tile assignments in a single pass.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> self for method chaining Later ranges override earlier ones if overlapping. Cells not matching any range are left unchanged.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">apply_threshold(source, range, tile) -> TileLayer</code></h5>
<p>Set tile index for cells where HeightMap value is within range.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> self for method chaining</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">at(pos) -> int</code></h5>
<p>at(x, y) -&gt; int
Get the tile index at cell position. Returns -1 if no tile.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Position as (x, y) tuple, list, or Vector</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill(index)</code></h5>
<p>Fill the entire layer with the specified tile index.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill_rect(pos, size, index)</code></h5>
<p>Fill a rectangular region with a tile index.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">set(pos, index)</code></h5>
<p>Set the tile index at cell position. Use -1 for no tile.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>pos</span>: Position as (x, y) tuple, list, or Vector</div>
<div><span class='arg-name'>index</span>: Tile index (-1 for no tile)</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="TileMapFile"><span class="class-name">TileMapFile</span></h3>
<p>TileMapFile(path: str)
Load a Tiled map file (.tmx or .tmj).
Parses the map and its referenced tilesets, providing access to tile layers,
object layers, and GID resolution.
Args:
path: Path to the .tmx or .tmj map file.
Properties:
width (int, read-only): Map width in tiles.
height (int, read-only): Map height in tiles.
tile_width (int, read-only): Tile width in pixels.
tile_height (int, read-only): Tile height in pixels.
orientation (str, read-only): Map orientation (e.g. &#x27;orthogonal&#x27;).
properties (dict, read-only): Custom map properties.
tileset_count (int, read-only): Number of referenced tilesets.
tile_layer_names (list, read-only): Names of tile layers.
object_layer_names (list, read-only): Names of object layers.
Example:
tm = mcrfpy.TileMapFile(&#x27;map.tmx&#x27;)
data = tm.tile_layer_data(&#x27;Ground&#x27;)
tm.apply_to_tile_layer(my_tile_layer, &#x27;Ground&#x27;)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>height</span> (read-only): Map height in tiles (int, read-only).</li>
<li><span class='property-name'>object_layer_names</span> (read-only): List of object layer names (read-only).</li>
<li><span class='property-name'>orientation</span> (read-only): Map orientation, e.g. &#x27;orthogonal&#x27; (str, read-only).</li>
<li><span class='property-name'>properties</span> (read-only): Custom map properties as a dict (read-only).</li>
<li><span class='property-name'>tile_height</span> (read-only): Tile height in pixels (int, read-only).</li>
<li><span class='property-name'>tile_layer_names</span> (read-only): List of tile layer names (read-only).</li>
<li><span class='property-name'>tile_width</span> (read-only): Tile width in pixels (int, read-only).</li>
<li><span class='property-name'>tileset_count</span> (read-only): Number of referenced tilesets (int, read-only).</li>
<li><span class='property-name'>width</span> (read-only): Map width in tiles (int, read-only).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">apply_to_tile_layer(tile_layer: TileLayer, layer_name: str, tileset_index: int = 0) -> None</code></h5>
<p>Resolve GIDs and write sprite indices into a TileLayer.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>tile_layer</span>: Target TileLayer to write into</div>
<div><span class='arg-name'>layer_name</span>: Name of the tile layer in this map</div>
<div><span class='arg-name'>tileset_index</span>: Which tileset to resolve GIDs against (default 0)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">object_layer(name: str) -> list[dict]</code></h5>
<p>Get objects from an object layer as Python dicts.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>name</span>: Name of the object layer</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of dicts with object properties (id, name, x, y, width, height, etc.).</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> KeyError: If no object layer with that name exists</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resolve_gid(gid: int) -> tuple[int, int]</code></h5>
<p>Resolve a global tile ID to tileset index and local tile ID.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>gid</span>: Global tile ID from tile_layer_data()</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Tuple of (tileset_index, local_tile_id). (-1, -1) for empty/invalid.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">tile_layer_data(name: str) -> list[int]</code></h5>
<p>Get raw global GID data for a tile layer.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>name</span>: Name of the tile layer</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Flat list of global GIDs (0 = empty tile).</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> KeyError: If no tile layer with that name exists</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">tileset(index: int) -> tuple[int, TileSetFile]</code></h5>
<p>Get a referenced tileset by index.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>index</span>: Tileset index (0-based)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Tuple of (firstgid, TileSetFile).</p>
</div>
</div>
<div class="method-section">
<h3 id="TileSetFile"><span class="class-name">TileSetFile</span></h3>
<p>TileSetFile(path: str)
Load a Tiled tileset file (.tsx or .tsj).
Parses the tileset and provides access to tile metadata, properties,
Wang sets, and texture creation.
Args:
path: Path to the .tsx or .tsj tileset file.
Properties:
name (str, read-only): Tileset name.
tile_width (int, read-only): Width of each tile in pixels.
tile_height (int, read-only): Height of each tile in pixels.
tile_count (int, read-only): Total number of tiles.
columns (int, read-only): Number of columns in the tileset image.
image_source (str, read-only): Resolved path to the tileset image.
properties (dict, read-only): Custom properties from the tileset.
wang_sets (list, read-only): List of WangSet objects.
Example:
ts = mcrfpy.TileSetFile(&#x27;tileset.tsx&#x27;)
texture = ts.to_texture()
print(f&#x27;{ts.name}: {ts.tile_count} tiles&#x27;)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>columns</span> (read-only): Number of columns in tileset image (int, read-only).</li>
<li><span class='property-name'>image_source</span> (read-only): Resolved path to the tileset image file (str, read-only).</li>
<li><span class='property-name'>margin</span> (read-only): Margin around tiles in pixels (int, read-only).</li>
<li><span class='property-name'>name</span> (read-only): Tileset name (str, read-only).</li>
<li><span class='property-name'>properties</span> (read-only): Custom tileset properties as a dict (read-only).</li>
<li><span class='property-name'>spacing</span> (read-only): Spacing between tiles in pixels (int, read-only).</li>
<li><span class='property-name'>tile_count</span> (read-only): Total number of tiles (int, read-only).</li>
<li><span class='property-name'>tile_height</span> (read-only): Height of each tile in pixels (int, read-only).</li>
<li><span class='property-name'>tile_width</span> (read-only): Width of each tile in pixels (int, read-only).</li>
<li><span class='property-name'>wang_sets</span> (read-only): List of WangSet objects from this tileset (read-only).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">tile_info(tile_id: int) -> dict | None</code></h5>
<p>Get metadata for a specific tile.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>tile_id</span>: Local tile ID (0-based)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Dict with &#x27;properties&#x27; and &#x27;animation&#x27; keys, or None if no metadata.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_texture() -> Texture</code></h5>
<p>Create a Texture from the tileset image.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> A Texture object for use with TileLayer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">wang_set(name: str) -> WangSet</code></h5>
<p>Look up a WangSet by name.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>name</span>: Name of the Wang set</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> The WangSet object.</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> KeyError: If no WangSet with that name exists</p>
</div>
</div>
<div class="method-section">
<h3 id="Timer"><span class="class-name">Timer</span></h3>
<p>Timer(name, callback, interval, once=False, start=True)
Create a timer that calls a function at regular intervals.
Args:
name (str): Unique identifier for the timer
callback (callable): Function to call - receives (timer, runtime) args
interval (int): Time between calls in milliseconds
once (bool): If True, timer stops after first call. Default: False
start (bool): If True, timer starts immediately. Default: True
Attributes:
interval (int): Time between calls in milliseconds
remaining (int): Time until next call in milliseconds (read-only)
paused (bool): Whether timer is paused (read-only)
stopped (bool): Whether timer is stopped (read-only)
active (bool): Running state (read-write). Set True to start, False to pause
callback (callable): The callback function (preserved when stopped)
once (bool): Whether timer stops after firing once
Methods:
start(): Start the timer, adding to engine tick loop
stop(): Stop the timer (removes from engine, preserves callback)
pause(): Pause the timer, preserving time remaining
resume(): Resume a paused timer
restart(): Reset timer and ensure it&#x27;s running
Example:
def on_timer(timer, runtime):
print(f&#x27;Timer {timer} fired at {runtime}ms&#x27;)
if runtime &gt; 5000:
timer.stop() # Stop but can restart later
timer = mcrfpy.Timer(&#x27;my_timer&#x27;, on_timer, 1000)
timer.pause() # Pause timer
timer.resume() # Resume timer
timer.stop() # Stop completely
timer.start() # Restart from beginning</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>active</span>: Running state (bool, read-write). True if running (not paused, not stopped). Set True to start/resume, False to pause.</li>
<li><span class='property-name'>callback</span>: The callback function (callable). Preserved when stopped, allowing timer restart.</li>
<li><span class='property-name'>interval</span>: Timer interval in milliseconds (int). Must be positive. Can be changed while timer is running.</li>
<li><span class='property-name'>name</span> (read-only): Timer name (str, read-only). Unique identifier for this timer.</li>
<li><span class='property-name'>once</span>: Whether the timer stops after firing once (bool). One-shot timers can be restarted.</li>
<li><span class='property-name'>paused</span> (read-only): Whether the timer is paused (bool, read-only). Paused timers preserve their remaining time.</li>
<li><span class='property-name'>remaining</span> (read-only): Time remaining until next trigger in milliseconds (int, read-only). Full interval when stopped.</li>
<li><span class='property-name'>stopped</span> (read-only): Whether the timer is stopped (bool, read-only). Stopped timers are not in the engine tick loop but preserve their callback.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">pause() -> None</code></h5>
<p>Pause the timer, preserving the time remaining until next trigger.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None The timer can be resumed later with resume(). Time spent paused does not count toward the interval.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">restart() -> None</code></h5>
<p>Restart the timer from the beginning and ensure it&#x27;s running.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None Resets progress and adds timer to engine if stopped. Equivalent to stop() followed by start().</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resume() -> None</code></h5>
<p>Resume a paused timer from where it left off.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None Has no effect if the timer is not paused. Timer will fire after the remaining time elapses.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">start() -> None</code></h5>
<p>Start the timer, adding it to the engine tick loop.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None Resets progress and begins counting toward the next fire. If another timer has this name, it will be stopped.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">stop() -> None</code></h5>
<p>Stop the timer and remove it from the engine tick loop.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None The callback is preserved, so the timer can be restarted with start() or restart().</p>
</div>
</div>
<div class="method-section">
<h3 id="Transition"><span class="class-name">Transition</span></h3>
<p><em>Inherits from: IntEnum</em></p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">as_integer_ratio(...)</code></h5>
<p>Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
&gt;&gt;&gt; (10).as_integer_ratio()
(10, 1)
&gt;&gt;&gt; (-10).as_integer_ratio()
(-10, 1)
&gt;&gt;&gt; (0).as_integer_ratio()
(0, 1)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_count(...)</code></h5>
<p>Number of ones in the binary representation of the absolute value of self.
Also known as the population count.
&gt;&gt;&gt; bin(13)
&#x27;0b1101&#x27;
&gt;&gt;&gt; (13).bit_count()
3</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_length(...)</code></h5>
<p>Number of bits necessary to represent self in binary.
&gt;&gt;&gt; bin(37)
&#x27;0b100101&#x27;
&gt;&gt;&gt; (37).bit_length()
6</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">conjugate(...)</code></h5>
<p>Returns self, the complex conjugate of any int.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Indicates whether two&#x27;s complement is used to represent the integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_integer(...)</code></h5>
<p>Returns True. Exists for duck type compatibility with float.is_integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Determines whether two&#x27;s complement is used to represent the integer.
If signed is False and a negative integer is given, an OverflowError
is raised.</p>
</div>
</div>
<div class="method-section">
<h3 id="Traversal"><span class="class-name">Traversal</span></h3>
<p><em>Inherits from: IntEnum</em></p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">as_integer_ratio(...)</code></h5>
<p>Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
&gt;&gt;&gt; (10).as_integer_ratio()
(10, 1)
&gt;&gt;&gt; (-10).as_integer_ratio()
(-10, 1)
&gt;&gt;&gt; (0).as_integer_ratio()
(0, 1)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_count(...)</code></h5>
<p>Number of ones in the binary representation of the absolute value of self.
Also known as the population count.
&gt;&gt;&gt; bin(13)
&#x27;0b1101&#x27;
&gt;&gt;&gt; (13).bit_count()
3</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_length(...)</code></h5>
<p>Number of bits necessary to represent self in binary.
&gt;&gt;&gt; bin(37)
&#x27;0b100101&#x27;
&gt;&gt;&gt; (37).bit_length()
6</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">conjugate(...)</code></h5>
<p>Returns self, the complex conjugate of any int.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Indicates whether two&#x27;s complement is used to represent the integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_integer(...)</code></h5>
<p>Returns True. Exists for duck type compatibility with float.is_integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Determines whether two&#x27;s complement is used to represent the integer.
If signed is False and a negative integer is given, an OverflowError
is raised.</p>
</div>
</div>
<div class="method-section">
<h3 id="Trigger"><span class="class-name">Trigger</span></h3>
<p><em>Inherits from: IntEnum</em></p>
<p>Enum representing trigger types passed to entity step() callbacks.
Values:
DONE: Behavior completed (path exhausted, sleep finished, etc.)
BLOCKED: Movement blocked by wall or collision
TARGET: Target entity spotted in FOV
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">as_integer_ratio(...)</code></h5>
<p>Return a pair of integers, whose ratio is equal to the original int.
The ratio is in lowest terms and has a positive denominator.
&gt;&gt;&gt; (10).as_integer_ratio()
(10, 1)
&gt;&gt;&gt; (-10).as_integer_ratio()
(-10, 1)
&gt;&gt;&gt; (0).as_integer_ratio()
(0, 1)</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_count(...)</code></h5>
<p>Number of ones in the binary representation of the absolute value of self.
Also known as the population count.
&gt;&gt;&gt; bin(13)
&#x27;0b1101&#x27;
&gt;&gt;&gt; (13).bit_count()
3</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">bit_length(...)</code></h5>
<p>Number of bits necessary to represent self in binary.
&gt;&gt;&gt; bin(37)
&#x27;0b100101&#x27;
&gt;&gt;&gt; (37).bit_length()
6</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">conjugate(...)</code></h5>
<p>Returns self, the complex conjugate of any int.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Indicates whether two&#x27;s complement is used to represent the integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_integer(...)</code></h5>
<p>Returns True. Exists for duck type compatibility with float.is_integer.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes(...)</code></h5>
<p>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 &#x27;big&#x27;,
the most significant byte is at the beginning of the byte array. If
byteorder is &#x27;little&#x27;, 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 &#x27;big&#x27;.
signed
Determines whether two&#x27;s complement is used to represent the integer.
If signed is False and a negative integer is given, an OverflowError
is raised.</p>
</div>
</div>
<div class="method-section">
<h3 id="Vector"><span class="class-name">Vector</span></h3>
<p>Vector(x: float = 0, y: float = 0)
2D vector for positions, sizes, and directions.
Args:
x: X component.
y: Y component.
Supports arithmetic (+, -, *, /), abs(), len() == 2,
indexing ([0] for x, [1] for y), hashing, and equality.
Properties:
x (float): X component.
y (float): Y component.
int (tuple[int, int], read-only): Integer floor of (x, y).
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>int</span> (read-only): Integer tuple (floor of x and y) for use as dict keys. Read-only.</li>
<li><span class='property-name'>x</span>: X coordinate of the vector (float)</li>
<li><span class='property-name'>y</span>: Y coordinate of the vector (float)</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">angle() -> float</code></h5>
<p>Get the angle of this vector in radians.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> float: Angle in radians from positive x-axis</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">copy() -> Vector</code></h5>
<p>Create a copy of this vector.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Vector: New Vector object with same x and y values</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">distance_to(other: Vector) -> float</code></h5>
<p>Calculate the distance to another vector.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: The other vector</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> float: Distance between the two vectors</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">dot(other: Vector) -> float</code></h5>
<p>Calculate the dot product with another vector.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>other</span>: The other vector</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> float: Dot product of the two vectors</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">floor() -> Vector</code></h5>
<p>Return a new vector with floored (integer) coordinates.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Vector: New Vector with floor(x) and floor(y) Useful for grid-based positioning. For a hashable tuple, use the .int property instead.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">magnitude() -> float</code></h5>
<p>Calculate the length/magnitude of this vector.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> float: The magnitude of the vector</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">magnitude_squared() -> float</code></h5>
<p>Calculate the squared magnitude of this vector.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> float: The squared magnitude (faster than magnitude()) Use this for comparisons to avoid expensive square root calculation.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">normalize() -> Vector</code></h5>
<p>Return a unit vector in the same direction.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Vector: New normalized vector with magnitude 1.0 For zero vectors (magnitude 0.0), returns a zero vector rather than raising an exception</p>
</div>
</div>
<div class="method-section">
<h3 id="Viewport3D"><span class="class-name">Viewport3D</span></h3>
<p><em>Inherits from: Drawable</em></p>
<p>Viewport3D(pos=None, size=None, **kwargs)
A 3D rendering viewport that displays a 3D scene as a UI element.
Args:
pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0)
size (tuple, optional): Display size as (width, height). Default: (320, 240)
Keyword Args:
render_resolution (tuple): Internal render resolution (width, height). Default: (320, 240)
fov (float): Camera field of view in degrees. Default: 60
camera_pos (tuple): Camera position (x, y, z). Default: (0, 0, 5)
camera_target (tuple): Camera look-at point (x, y, z). Default: (0, 0, 0)
bg_color (Color): Background clear color. Default: (25, 25, 50)
enable_vertex_snap (bool): PS1-style vertex snapping. Default: True
enable_affine (bool): PS1-style affine texture mapping. Default: True
enable_dither (bool): PS1-style color dithering. Default: True
enable_fog (bool): Distance fog. Default: True
fog_color (Color): Fog color. Default: (128, 128, 153)
fog_near (float): Fog start distance. Default: 10
fog_far (float): Fog end distance. Default: 100
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>bg_color</span>: Background clear color.</li>
<li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>camera_pos</span>: Camera position as (x, y, z) tuple.</li>
<li><span class='property-name'>camera_target</span>: Camera look-at target as (x, y, z) tuple.</li>
<li><span class='property-name'>cell_size</span>: World units per navigation grid cell.</li>
<li><span class='property-name'>enable_affine</span>: Enable PS1-style affine texture mapping (warped textures).</li>
<li><span class='property-name'>enable_dither</span>: Enable PS1-style color dithering.</li>
<li><span class='property-name'>enable_fog</span>: Enable distance fog.</li>
<li><span class='property-name'>enable_vertex_snap</span>: Enable PS1-style vertex snapping (jittery vertices).</li>
<li><span class='property-name'>entities</span> (read-only): Collection of Entity3D objects (read-only). Use append/remove to modify.</li>
<li><span class='property-name'>fog_color</span>: Fog color.</li>
<li><span class='property-name'>fog_far</span>: Fog end distance.</li>
<li><span class='property-name'>fog_near</span>: Fog start distance.</li>
<li><span class='property-name'>fov</span>: Camera field of view in degrees.</li>
<li><span class='property-name'>global_bounds</span>: Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>grid_size</span>: Navigation grid dimensions as (width, depth) tuple.</li>
<li><span class='property-name'>h</span>: Display height in pixels.</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: 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.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position as Vector (x, y).</li>
<li><span class='property-name'>render_resolution</span>: Internal render resolution (width, height). Lower values for PS1 effect.</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>w</span>: Display width in pixels.</li>
<li><span class='property-name'>x</span>: X position in pixels.</li>
<li><span class='property-name'>y</span>: Y position in pixels.</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add_billboard(billboard)</code></h5>
<p>Add a Billboard to the viewport.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>billboard</span>: Billboard object to add</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add_layer(name, z_index=0) -> dict</code></h5>
<p>Add a new mesh layer to the viewport.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>name</span>: Unique identifier for the layer</div>
<div><span class='arg-name'>z_index</span>: Render order (lower = rendered first)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add_mesh(layer_name, model, pos, rotation=0, scale=1.0) -> int</code></h5>
<p>Add a Model3D instance to a layer at the specified position.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>layer_name</span>: Name of layer to add mesh to (created if needed)</div>
<div><span class='arg-name'>model</span>: Model3D object to place</div>
<div><span class='arg-name'>pos</span>: World position as (x, y, z) tuple</div>
<div><span class='arg-name'>rotation</span>: Y-axis rotation in degrees</div>
<div><span class='arg-name'>scale</span>: Uniform scale factor</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Index of the mesh instance</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add_voxel_layer(voxel_grid, z_index=0)</code></h5>
<p>Add a VoxelGrid as a renderable layer.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>voxel_grid</span>: VoxelGrid object to render</div>
<div><span class='arg-name'>z_index</span>: Render order (lower = rendered first)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation</code></h5>
<p>Create and start an animation on this drawable&#x27;s property.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>property</span>: Name of the property to animate (e.g., &#x27;x&#x27;, &#x27;fill_color&#x27;, &#x27;opacity&#x27;)</div>
<div><span class='arg-name'>target</span>: Target value - type depends on property (float, tuple for color/vector, etc.)</div>
<div><span class='arg-name'>duration</span>: Animation duration in seconds</div>
<div><span class='arg-name'>easing</span>: Easing function: Easing enum value, string name, or None for linear</div>
<div><span class='arg-name'>delta</span>: If True, target is relative to current value; if False, target is absolute</div>
<div><span class='arg-name'>loop</span>: If True, animation repeats from start when it reaches the end (default False)</div>
<div><span class='arg-name'>callback</span>: Optional callable invoked when animation completes (not called for looping animations)</div>
<div><span class='arg-name'>conflict_mode</span>: &#x27;replace&#x27; (default), &#x27;queue&#x27;, or &#x27;error&#x27; if property already animating</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Animation object for monitoring progress</p>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> 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.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">apply_heightmap(heightmap, y_scale=1.0)</code></h5>
<p>Set cell heights from HeightMap.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>heightmap</span>: HeightMap object</div>
<div><span class='arg-name'>y_scale</span>: Vertical scale factor</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">apply_terrain_colors(layer_name, r_map, g_map, b_map)</code></h5>
<p>Apply per-vertex colors to terrain from RGB HeightMaps.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>layer_name</span>: Name of terrain layer to colorize</div>
<div><span class='arg-name'>r_map</span>: HeightMap for red channel (0-1 values)</div>
<div><span class='arg-name'>g_map</span>: HeightMap for green channel (0-1 values)</div>
<div><span class='arg-name'>b_map</span>: HeightMap for blue channel (0-1 values)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">apply_threshold(heightmap, min_height, max_height, walkable=True)</code></h5>
<p>Set cell walkability based on height thresholds.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>heightmap</span>: HeightMap object</div>
<div><span class='arg-name'>min_height</span>: Minimum height (0-1)</div>
<div><span class='arg-name'>max_height</span>: Maximum height (0-1)</div>
<div><span class='arg-name'>walkable</span>: Walkability value for cells in range</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">at(x, z) -> VoxelPoint</code></h5>
<p>Get VoxelPoint at grid coordinates.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>x</span>: X coordinate in grid</div>
<div><span class='arg-name'>z</span>: Z coordinate in grid</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> VoxelPoint object for the cell</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">billboard_count() -> int</code></h5>
<p>Get the number of billboards.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Number of billboards in the viewport</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">build_terrain(layer_name, heightmap, y_scale=1.0, cell_size=1.0) -> int</code></h5>
<p>Build terrain mesh from HeightMap on specified layer.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>layer_name</span>: Name of layer to build terrain on (created if doesn&#x27;t exist)</div>
<div><span class='arg-name'>heightmap</span>: HeightMap object with height data</div>
<div><span class='arg-name'>y_scale</span>: Vertical exaggeration factor</div>
<div><span class='arg-name'>cell_size</span>: World-space size of each grid cell</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Number of vertices in the generated mesh</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">clear_billboards()</code></h5>
<p>Remove all billboards from the viewport.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">clear_meshes(layer_name)</code></h5>
<p>Clear all mesh instances from a layer.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>layer_name</span>: Name of layer to clear</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">clear_voxel_nav_region(voxel_grid)</code></h5>
<p>Clear navigation cells in a voxel grid&#x27;s footprint.
Resets walkability, transparency, height, and cost to defaults
for all nav cells corresponding to the voxel grid&#x27;s XZ extent.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>voxel_grid</span>: VoxelGrid whose nav region to clear</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">compute_fov(origin, radius=10) -> list</code></h5>
<p>Compute field of view from a position.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>origin</span>: Origin point as (x, z) tuple</div>
<div><span class='arg-name'>radius</span>: FOV radius</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of visible (x, z) positions</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">find_path(start, end) -> list</code></h5>
<p>Find A* path between two points.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>start</span>: Starting point as (x, z) tuple</div>
<div><span class='arg-name'>end</span>: End point as (x, z) tuple</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of (x, z) tuples forming the path, or empty list if no path</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">follow(entity, distance=10, height=5, smoothing=1.0)</code></h5>
<p>Position camera to follow an entity.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>entity</span>: Entity3D to follow</div>
<div><span class='arg-name'>distance</span>: Distance behind entity</div>
<div><span class='arg-name'>height</span>: Camera height above entity</div>
<div><span class='arg-name'>smoothing</span>: Interpolation factor (0-1). 1 = instant, lower = smoother</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get_billboard(index) -> Billboard</code></h5>
<p>Get a Billboard by index.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>index</span>: Index of the billboard</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Billboard object</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get_layer(name) -> dict or None</code></h5>
<p>Get a layer by name.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">is_in_fov(x, z) -> bool</code></h5>
<p>Check if a cell is in the current FOV (after compute_fov).</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>x</span>: X coordinate</div>
<div><span class='arg-name'>z</span>: Z coordinate</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> True if the cell is visible</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">layer_count() -> int</code></h5>
<p>Get the number of mesh layers.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx, dy) or (delta) -> None</code></h5>
<p>Move the element by a relative offset.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>dx</span>: Horizontal offset in pixels (or use delta)</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels (or use delta)</div>
<div><span class='arg-name'>delta</span>: Offset as tuple, list, or Vector: (dx, dy)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">orbit_camera(angle=0, distance=10, height=5)</code></h5>
<p>Position camera to orbit around origin.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>angle</span>: Orbit angle in radians</div>
<div><span class='arg-name'>distance</span>: Distance from origin</div>
<div><span class='arg-name'>height</span>: Camera height above XZ plane</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">place_blocking(grid_pos, footprint, walkable=False, transparent=False)</code></h5>
<p>Mark grid cells as blocking for pathfinding and FOV.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>grid_pos</span>: Top-left grid position as (x, z) tuple</div>
<div><span class='arg-name'>footprint</span>: Size in cells as (width, depth) tuple</div>
<div><span class='arg-name'>walkable</span>: Whether cells should be walkable (default: False)</div>
<div><span class='arg-name'>transparent</span>: Whether cells should be transparent (default: False)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">project_all_voxels_to_nav(headroom=2)</code></h5>
<p>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.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>headroom</span>: Required air voxels above floor for walkability (default: 2)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">project_voxel_to_nav(voxel_grid, headroom=2)</code></h5>
<p>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.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>voxel_grid</span>: VoxelGrid to project</div>
<div><span class='arg-name'>headroom</span>: Required air voxels above floor for walkability (default: 2)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">realign() -> None</code></h5>
<p>Reapply alignment relative to parent, useful for responsive layouts.
Note:
Call this to recalculate position after parent changes size. For elements with align=None, this has no effect.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">remove_billboard(billboard)</code></h5>
<p>Remove a Billboard from the viewport.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>billboard</span>: Billboard object to remove</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">remove_layer(name) -> bool</code></h5>
<p>Remove a layer by name. Returns True if found and removed.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">remove_voxel_layer(voxel_grid) -> bool</code></h5>
<p>Remove a VoxelGrid layer from the viewport.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>voxel_grid</span>: VoxelGrid object to remove</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> True if the layer was found and removed</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width, height) or (size) -> None</code></h5>
<p>Resize the element to new dimensions.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>width</span>: New width in pixels (or use size)</div>
<div><span class='arg-name'>height</span>: New height in pixels (or use size)</div>
<div><span class='arg-name'>size</span>: Size as tuple, list, or Vector: (width, height)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">screen_to_world(x, y, y_plane=0.0) -> tuple or None</code></h5>
<p>Convert screen coordinates to world position via ray casting.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>x</span>: Screen X coordinate relative to viewport</div>
<div><span class='arg-name'>y</span>: Screen Y coordinate relative to viewport</div>
<div><span class='arg-name'>y_plane</span>: Y value of horizontal plane to intersect (default: 0.0)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> (x, y, z) world position tuple, or None if no intersection with the plane</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">set_grid_size(width, depth)</code></h5>
<p>Initialize navigation grid with specified dimensions.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>width</span>: Grid width (X axis)</div>
<div><span class='arg-name'>depth</span>: Grid depth (Z axis)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">set_slope_cost(max_slope=0.5, cost_multiplier=1.0)</code></h5>
<p>Calculate slope costs and mark steep cells unwalkable.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>max_slope</span>: Maximum height difference before marking unwalkable</div>
<div><span class='arg-name'>cost_multiplier</span>: Cost increase per unit slope</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">voxel_layer_count() -> int</code></h5>
<p>Get the number of voxel layers.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Number of voxel layers in the viewport</p>
</div>
</div>
<div class="method-section">
<h3 id="VoxelGrid"><span class="class-name">VoxelGrid</span></h3>
<p>VoxelGrid(size: tuple[int, int, int], cell_size: float = 1.0)
A dense 3D grid of voxel material IDs with a material palette.
VoxelGrids provide volumetric storage for 3D structures like buildings,
caves, and dungeon walls. Each cell stores a uint8 material ID (0-255),
where 0 is always air.
Args:
size: (width, height, depth) dimensions. Immutable after creation.
cell_size: World units per voxel. Default 1.0.
Properties:
size (tuple, read-only): Grid dimensions as (width, height, depth)
width, height, depth (int, read-only): Individual dimensions
cell_size (float, read-only): World units per voxel
offset (tuple): World-space position (x, y, z)
rotation (float): Y-axis rotation in degrees
material_count (int, read-only): Number of defined materials
Example:
voxels = mcrfpy.VoxelGrid(size=(16, 8, 16), cell_size=1.0)
stone = voxels.add_material(&#x27;stone&#x27;, color=mcrfpy.Color(128, 128, 128))
voxels.set(5, 0, 5, stone)
assert voxels.get(5, 0, 5) == stone
print(f&#x27;Non-air voxels: {voxels.count_non_air()}&#x27;)</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>cell_size</span> (read-only): World units per voxel. Read-only.</li>
<li><span class='property-name'>depth</span> (read-only): Grid depth (Z dimension). Read-only.</li>
<li><span class='property-name'>greedy_meshing</span>: Enable greedy meshing optimization (reduces vertex count for uniform regions).</li>
<li><span class='property-name'>height</span> (read-only): Grid height (Y dimension). Read-only.</li>
<li><span class='property-name'>material_count</span> (read-only): Number of materials in the palette. Read-only.</li>
<li><span class='property-name'>offset</span>: World-space position (x, y, z) of the grid origin.</li>
<li><span class='property-name'>rotation</span>: Y-axis rotation in degrees.</li>
<li><span class='property-name'>size</span> (read-only): Dimensions (width, height, depth) of the grid. Read-only.</li>
<li><span class='property-name'>vertex_count</span> (read-only): Number of vertices after mesh generation. Read-only.</li>
<li><span class='property-name'>visible</span>: Show or hide this voxel grid in rendering.</li>
<li><span class='property-name'>width</span> (read-only): Grid width (X dimension). Read-only.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add_material(name, color=Color(255,255,255), sprite_index=-1, transparent=False, path_cost=1.0) -> int</code></h5>
<p>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.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">clear() -> None</code></h5>
<p>Clear the grid (fill with air, material 0).</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">copy_region(min_coord, max_coord) -> VoxelRegion</code></h5>
<p>Copy a rectangular region to a VoxelRegion prefab.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>min_coord</span>: (x0, y0, z0) - minimum corner (inclusive)</div>
<div><span class='arg-name'>max_coord</span>: (x1, y1, z1) - maximum corner (inclusive)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> VoxelRegion object that can be pasted elsewhere.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">count_material(material) -> int</code></h5>
<p>Count the number of voxels with the specified material ID.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">count_non_air() -> int</code></h5>
<p>Count the number of non-air voxels in the grid.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill(material) -> None</code></h5>
<p>Fill the entire grid with the specified material ID.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill_box(min_coord, max_coord, material) -> None</code></h5>
<p>Fill a rectangular region with the specified material.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>min_coord</span>: (x0, y0, z0) - minimum corner (inclusive)</div>
<div><span class='arg-name'>max_coord</span>: (x1, y1, z1) - maximum corner (inclusive)</div>
<div><span class='arg-name'>material</span>: material ID (0-255)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill_box_hollow(min_coord, max_coord, material, thickness=1) -> None</code></h5>
<p>Create a hollow rectangular room (walls only, hollow inside).</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>min_coord</span>: (x0, y0, z0) - minimum corner (inclusive)</div>
<div><span class='arg-name'>max_coord</span>: (x1, y1, z1) - maximum corner (inclusive)</div>
<div><span class='arg-name'>material</span>: material ID for walls (0-255)</div>
<div><span class='arg-name'>thickness</span>: wall thickness in voxels (default 1)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill_cylinder(base_pos, radius, height, material) -> None</code></h5>
<p>Fill a vertical cylinder (Y-axis aligned).</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>base_pos</span>: (cx, cy, cz) - base center position</div>
<div><span class='arg-name'>radius</span>: cylinder radius in voxels</div>
<div><span class='arg-name'>height</span>: cylinder height in voxels</div>
<div><span class='arg-name'>material</span>: material ID (0-255)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill_noise(min_coord, max_coord, material, threshold=0.5, scale=0.1, seed=0) -> None</code></h5>
<p>Fill region with 3D noise-based pattern (caves, clouds).</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>min_coord</span>: (x0, y0, z0) - minimum corner</div>
<div><span class='arg-name'>max_coord</span>: (x1, y1, z1) - maximum corner</div>
<div><span class='arg-name'>material</span>: material ID for solid areas</div>
<div><span class='arg-name'>threshold</span>: noise threshold (0-1, higher = more solid)</div>
<div><span class='arg-name'>scale</span>: noise scale (smaller = larger features)</div>
<div><span class='arg-name'>seed</span>: random seed (0 for default)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">fill_sphere(center, radius, material) -> None</code></h5>
<p>Fill a spherical region.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>center</span>: (cx, cy, cz) - sphere center coordinates</div>
<div><span class='arg-name'>radius</span>: sphere radius in voxels</div>
<div><span class='arg-name'>material</span>: material ID (0-255, use 0 to carve)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">from_bytes(data) -> bool</code></h5>
<p>Load voxel data from a bytes object.
Note: This replaces the current grid data entirely.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>data</span>: bytes object containing serialized grid data</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> True on success, False on failure.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get(x, y, z) -> int</code></h5>
<p>Get the material ID at integer coordinates.
Returns 0 (air) for out-of-bounds coordinates.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get_material(id) -> dict</code></h5>
<p>Get material properties by ID.
Returns dict with keys: name, color, sprite_index, transparent, path_cost.
ID 0 returns the implicit air material.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">load(path) -> bool</code></h5>
<p>Load voxel data from a binary file.
Note: This replaces the current grid data entirely, including</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>path</span>: File path to load from</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> True on success, False on failure. dimensions and material palette.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">paste_region(region, position, skip_air=True) -> None</code></h5>
<p>Paste a VoxelRegion prefab at the specified position.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>region</span>: VoxelRegion from copy_region()</div>
<div><span class='arg-name'>position</span>: (x, y, z) - paste destination</div>
<div><span class='arg-name'>skip_air</span>: if True, air voxels don&#x27;t overwrite (default True)</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">project_column(x, z, headroom=2) -> dict</code></h5>
<p>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.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>x</span>: X coordinate in voxel grid</div>
<div><span class='arg-name'>z</span>: Z coordinate in voxel grid</div>
<div><span class='arg-name'>headroom</span>: Required air voxels above floor (default 2)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> 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&#x27;s path cost</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">rebuild_mesh() -> None</code></h5>
<p>Force immediate mesh rebuild for rendering.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">save(path) -> bool</code></h5>
<p>Save the voxel grid to a binary file.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>path</span>: File path to save to (.mcvg extension recommended)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> True on success, False on failure. The file format includes grid dimensions, cell size, material palette, and RLE-compressed voxel data.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">set(x, y, z, material) -> None</code></h5>
<p>Set the material ID at integer coordinates.
Out-of-bounds coordinates are silently ignored.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">to_bytes() -> bytes</code></h5>
<p>Serialize the voxel grid to a bytes object.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> bytes object containing the serialized grid data. Useful for network transmission or custom storage.</p>
</div>
</div>
<div class="method-section">
<h3 id="VoxelRegion"><span class="class-name">VoxelRegion</span></h3>
<p>VoxelRegion - Portable voxel data for copy/paste operations.
Created by VoxelGrid.copy_region(), used with paste_region().
Cannot be instantiated directly.
Properties:
size (tuple, read-only): Dimensions as (width, height, depth)
width, height, depth (int, read-only): Individual dimensions</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>depth</span> (read-only): Region depth. Read-only.</li>
<li><span class='property-name'>height</span> (read-only): Region height. Read-only.</li>
<li><span class='property-name'>size</span> (read-only): Dimensions (width, height, depth) of the region. Read-only.</li>
<li><span class='property-name'>width</span> (read-only): Region width. Read-only.</li>
</ul>
<h4>Methods:</h4>
</div>
<div class="method-section">
<h3 id="WangSet"><span class="class-name">WangSet</span></h3>
<p>WangSet - Wang terrain auto-tile set from a Tiled tileset.
WangSets are obtained from TileSetFile.wang_sets or TileSetFile.wang_set().
They map abstract terrain types to concrete sprite indices using Tiled&#x27;s
Wang tile algorithm.
Properties:
name (str, read-only): Wang set name.
type (str, read-only): &#x27;corner&#x27;, &#x27;edge&#x27;, or &#x27;mixed&#x27;.
color_count (int, read-only): Number of terrain colors.
colors (list, read-only): List of color dicts.
Example:
ws = tileset.wang_set(&#x27;overworld&#x27;)
Terrain = ws.terrain_enum()
tiles = ws.resolve(discrete_map)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>color_count</span> (read-only): Number of terrain colors (int, read-only).</li>
<li><span class='property-name'>colors</span> (read-only): List of color dicts with name, index, tile_id, probability (read-only).</li>
<li><span class='property-name'>name</span> (read-only): Wang set name (str, read-only).</li>
<li><span class='property-name'>type</span> (read-only): Wang set type: &#x27;corner&#x27;, &#x27;edge&#x27;, or &#x27;mixed&#x27; (str, read-only).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">apply(discrete_map: DiscreteMap, tile_layer: TileLayer) -> None</code></h5>
<p>Resolve terrain and write tile indices directly into a TileLayer.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>discrete_map</span>: A DiscreteMap with terrain IDs</div>
<div><span class='arg-name'>tile_layer</span>: Target TileLayer to write resolved tiles into</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resolve(discrete_map: DiscreteMap) -> list[int]</code></h5>
<p>Resolve terrain data to tile indices using Wang tile rules.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>discrete_map</span>: A DiscreteMap with terrain IDs matching this WangSet&#x27;s colors</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of tile IDs (one per cell). -1 means no matching Wang tile.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">terrain_enum() -> IntEnum</code></h5>
<p>Generate a Python IntEnum from this WangSet&#x27;s terrain colors.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> IntEnum class with NONE=0 and one member per color (UPPER_SNAKE_CASE).</p>
</div>
</div>
<div class="method-section">
<h3 id="Window"><span class="class-name">Window</span></h3>
<p>Window singleton for accessing and modifying the game window properties</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>framerate_limit</span>: Frame rate limit in FPS (int, 0 for unlimited). Caps maximum frame rate.</li>
<li><span class='property-name'>fullscreen</span>: Window fullscreen state (bool). Setting this recreates the window.</li>
<li><span class='property-name'>game_resolution</span>: Fixed game resolution as (width, height) tuple. Enables resolution-independent rendering with scaling.</li>
<li><span class='property-name'>resolution</span>: Window resolution as (width, height) tuple. Setting this recreates the window.</li>
<li><span class='property-name'>scaling_mode</span>: Viewport scaling mode (str): &#x27;center&#x27; (no scaling), &#x27;stretch&#x27; (fill window), or &#x27;fit&#x27; (maintain aspect ratio).</li>
<li><span class='property-name'>title</span>: Window title string (str). Displayed in the window title bar.</li>
<li><span class='property-name'>visible</span>: Window visibility state (bool). Hidden windows still process events.</li>
<li><span class='property-name'>vsync</span>: Vertical sync enabled state (bool). Prevents screen tearing but may limit framerate.</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">center() -> None</code></h5>
<p>Center the window on the screen.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None Only works in windowed mode. Has no effect when fullscreen or in headless mode.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get() -> Window</code></h5>
<p>Get the Window singleton instance.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Window: The global window object This is a class method. Call as Window.get(). There is only one window instance per application.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">screenshot(filename: str = None) -> bytes | None</code></h5>
<p>Take a screenshot of the current window contents.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>filename</span>: Optional path to save screenshot. If omitted, returns raw RGBA bytes.</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> 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.</p>
</div>
</div>
<h2 id='constants'>Constants</h2>
<ul>
</ul>
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink