john
/
McRogueFace
1
0
Fork 0
Code Issues 29 Pull Requests Projects 1 Releases Wiki Activity

docs: Update grid demo and regenerate API docs 

- grid_demo.py: Updated for new layer-based rendering
- Screenshots: Refreshed demo screenshots
- API docs: Regenerated with latest method signatures

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
John McCardle 2025-12-02 09:21:43 -05:00
parent 4713b62535
commit d761b53d48
6 changed files with 957 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

434
docs/api_reference_dynamic.html
View File

@ -108,7 +108,7 @@
<body>
<div class="container">
<h1>McRogueFace API Reference</h1>
<p><em>Generated on 2025-10-30 21:14:43</em></p>
<p><em>Generated on 2025-11-29 10:12:05</em></p>
<p><em>This documentation was dynamically generated from the compiled module.</em></p>
<div class="toc">
@ -118,8 +118,11 @@
<li><a href="#classes">Classes</a>
<ul>
<li><a href="#Animation">Animation</a></li>
<li><a href="#Arc">Arc</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="#Drawable">Drawable</a></li>
<li><a href="#Entity">Entity</a></li>
<li><a href="#EntityCollection">EntityCollection</a></li>
@ -128,9 +131,11 @@
<li><a href="#Grid">Grid</a></li>
<li><a href="#GridPoint">GridPoint</a></li>
<li><a href="#GridPointState">GridPointState</a></li>
<li><a href="#Line">Line</a></li>
<li><a href="#Scene">Scene</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="#Timer">Timer</a></li>
<li><a href="#UICollection">UICollection</a></li>
<li><a href="#UICollectionIter">UICollectionIter</a></li>
@ -187,6 +192,15 @@ Note:</p>
<p><span class='returns'>Returns:</span> None No error is raised if the timer doesn&#x27;t exist.</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.
@ -263,6 +277,19 @@ Note:</p>
<p><span class='returns'>Returns:</span> None Only one music track can play at a time. Loading new music stops the current track.</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">playSound(buffer_id: int) -> None</code></h3>
<p>Play a sound effect using a previously loaded buffer.</p>
@ -285,6 +312,18 @@ Note:</p>
<p><span class='raises'>Raises:</span> KeyError: If the specified scene doesn&#x27;t exist</p>
</div>
<div class="method-section">
<h3><code class="function-signature">setDevConsole(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">setMusicVolume(volume: int) -> None</code></h3>
<p>Set the global music volume.</p>
@ -344,6 +383,15 @@ Note:</p>
<p><span class='returns'>Returns:</span> None If a timer with this name exists, it will be replaced. The handler receives the total runtime in seconds as its argument.</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>
<h2 id='classes'>Classes</h2>
<div class="method-section">
@ -398,6 +446,73 @@ Note:</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:
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
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
</p>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get_bounds() -> tuple</code></h5>
<p>Get the bounding rectangle of this drawable element.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> tuple: (x, y, width, height) representing the element&#x27;s bounds The bounds are in screen coordinates and account for current position and size.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx: float, dy: float) -> 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</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width: float, height: float) -> 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</div>
<div><span class='arg-name'>height</span>: New height in pixels</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="Caption"><span class="class-name">Caption</span></h3>
<p><em>Inherits from: Drawable</em></p>
@ -462,6 +577,71 @@ Note:</p>
<h5><code class="method-name">resize(width: float, height: float) -> 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</div>
<div><span class='arg-name'>height</span>: New height in pixels</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:
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
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
</p>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get_bounds() -> tuple</code></h5>
<p>Get the bounding rectangle of this drawable element.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> tuple: (x, y, width, height) representing the element&#x27;s bounds The bounds are in screen coordinates and account for current position and size.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx: float, dy: float) -> 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</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width: float, height: float) -> 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</div>
@ -508,6 +688,43 @@ Note:</p>
</div>
</div>
<div class="method-section">
<h3 id="ColorLayer"><span class="class-name">ColorLayer</span></h3>
<p>ColorLayer(z_index=-1, grid_size=None)
A grid layer that stores RGBA colors per cell.
Args:
z_index (int): Render order. Negative = below entities. Default: -1
grid_size (tuple): Dimensions as (width, height). Default: parent grid size
Attributes:
z_index (int): Layer z-order relative to entities
visible (bool): Whether layer is rendered
grid_size (tuple): Layer dimensions (read-only)
Methods:
at(x, y): Get color at cell position
set(x, y, color): Set color at cell position
fill(color): Fill entire layer with color</p>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">at(x, y) -> Color</code></h5>
<p>Get the color at cell position (x, y).</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">set(x, y, color)</code></h5>
<p>Set the color at cell position (x, y).</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>
@ -643,23 +860,44 @@ when the entity moves if it has a grid with perspective set.</p>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">append(...)</code></h5>
<h5><code class="method-name">append(entity)</code></h5>
<p>Add an entity to the end of the collection.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">count(...)</code></h5>
<h5><code class="method-name">count(entity) -> int</code></h5>
<p>Count occurrences of entity in the collection.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">extend(...)</code></h5>
<h5><code class="method-name">extend(iterable)</code></h5>
<p>Add all entities from an iterable to the collection.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">index(...)</code></h5>
<h5><code class="method-name">find(name) -> entity or list</code></h5>
<p>Find entities by name.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Single entity if exact match, list if wildcard, None if not found.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">remove(...)</code></h5>
<h5><code class="method-name">index(entity) -> int</code></h5>
<p>Return index of first occurrence of entity. Raises ValueError if not found.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">insert(index, entity)</code></h5>
<p>Insert entity at index. Like list.insert(), indices past the end append.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">pop([index]) -> entity</code></h5>
<p>Remove and return entity at index (default: last entity).</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">remove(entity)</code></h5>
<p>Remove first occurrence of entity. Raises ValueError if not found.</p>
</div>
</div>
@ -695,6 +933,7 @@ Keyword Args:
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
Attributes:
x, y (float): Position in pixels
@ -708,7 +947,8 @@ Attributes:
opacity (float): Opacity value
z_index (int): Rendering order
name (str): Element name
clip_children (bool): Whether to clip children to frame bounds</p>
clip_children (bool): Whether to clip children to frame bounds
cache_subtree (bool): Cache subtree rendering to texture</p>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
@ -794,6 +1034,17 @@ Attributes:
name (str): Element name</p>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">add_layer(type: str, z_index: int = -1, texture: Texture = None) -> ColorLayer | TileLayer</code></h5>
<p>Add a new layer to the grid.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>type</span>: Layer type (&#x27;color&#x27; or &#x27;tile&#x27;)</div>
<div><span class='arg-name'>z_index</span>: Render order. Negative = below entities, &gt;= 0 = above entities. Default: -1</div>
<div><span class='arg-name'>texture</span>: Texture for tile layers. Required for &#x27;tile&#x27; type.</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> The created ColorLayer or TileLayer object.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">at(...)</code></h5>
</div>
@ -822,8 +1073,8 @@ Attributes:
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">compute_fov(x: int, y: int, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> List[Tuple[int, int, bool, bool]]</code></h5>
<p>Compute field of view from a position and return visible cells.</p>
<h5><code class="method-name">compute_fov(x: int, y: int, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None</code></h5>
<p>Compute field of view from a position.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>x</span>: X coordinate of the viewer</div>
<div><span class='arg-name'>y</span>: Y coordinate of the viewer</div>
@ -831,7 +1082,6 @@ Attributes:
<div><span class='arg-name'>light_walls</span>: Whether walls are lit when visible</div>
<div><span class='arg-name'>algorithm</span>: FOV algorithm to use (FOV_BASIC, FOV_DIAMOND, FOV_SHADOW, FOV_PERMISSIVE_0-8)</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of tuples (x, y, visible, discovered) for all visible cells: - x, y: Grid coordinates - visible: True (all returned cells are visible) - discovered: True (FOV implies discovery) Also updates the internal FOV state for use with is_in_fov().</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
@ -885,6 +1135,15 @@ Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> True if the cell is visible, False otherwise Must call compute_fov() first to calculate visibility.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">layer(z_index: int) -> ColorLayer | TileLayer | None</code></h5>
<p>Get a layer by its z_index.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>z_index</span>: The z_index of the layer to find.</div>
</div>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> The layer with the specified z_index, or None if not found.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx: float, dy: float) -> None</code></h5>
<p>Move the element by a relative offset.
@ -896,6 +1155,14 @@ Note:</p>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">remove_layer(layer: ColorLayer | TileLayer) -> None</code></h5>
<p>Remove a layer from the grid.</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>layer</span>: The layer to remove.</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width: float, height: float) -> None</code></h5>
<p>Resize the element to new dimensions.
@ -920,6 +1187,69 @@ Note:</p>
<h4>Methods:</h4>
</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:
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
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
</p>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">get_bounds() -> tuple</code></h5>
<p>Get the bounding rectangle of this drawable element.
Note:</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> tuple: (x, y, width, height) representing the element&#x27;s bounds The bounds are in screen coordinates and account for current position and size.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">move(dx: float, dy: float) -> 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</div>
<div><span class='arg-name'>dy</span>: Vertical offset in pixels</div>
</div>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">resize(width: float, height: float) -> 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</div>
<div><span class='arg-name'>height</span>: New height in pixels</div>
</div>
</div>
</div>
<div class="method-section">
<h3 id="Scene"><span class="class-name">Scene</span></h3>
<p>Base class for object-oriented scenes</p>
@ -1029,6 +1359,45 @@ Note:</p>
<h4>Methods:</h4>
</div>
<div class="method-section">
<h3 id="TileLayer"><span class="class-name">TileLayer</span></h3>
<p>TileLayer(z_index=-1, texture=None, grid_size=None)
A grid layer that stores sprite indices per cell.
Args:
z_index (int): Render order. Negative = below entities. Default: -1
texture (Texture): Sprite atlas for tile rendering. Default: None
grid_size (tuple): Dimensions as (width, height). Default: parent grid size
Attributes:
z_index (int): Layer z-order relative to entities
visible (bool): Whether layer is rendered
texture (Texture): Tile sprite atlas
grid_size (tuple): Layer dimensions (read-only)
Methods:
at(x, y): Get tile index at cell position
set(x, y, index): Set tile index at cell position
fill(index): Fill entire layer with tile index</p>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">at(x, y) -> int</code></h5>
<p>Get the tile index at cell position (x, y). Returns -1 if no tile.</p>
</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">set(x, y, index)</code></h5>
<p>Set the tile index at cell position (x, y). Use -1 for no tile.</p>
</div>
</div>
<div class="method-section">
<h3 id="Timer"><span class="class-name">Timer</span></h3>
<p>Timer(name, callback, interval, once=False)
@ -1106,23 +1475,50 @@ Note:</p>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">append(...)</code></h5>
<h5><code class="method-name">append(element)</code></h5>
<p>Add an element to the end of the collection.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">count(...)</code></h5>
<h5><code class="method-name">count(element) -> int</code></h5>
<p>Count occurrences of element in the collection.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">extend(...)</code></h5>
<h5><code class="method-name">extend(iterable)</code></h5>
<p>Add all elements from an iterable to the collection.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">index(...)</code></h5>
<h5><code class="method-name">find(name, recursive=False) -> element or list</code></h5>
<p>Find elements by name.</p>
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Single element if exact match, list if wildcard, None if not found.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">remove(...)</code></h5>
<h5><code class="method-name">index(element) -> int</code></h5>
<p>Return index of first occurrence of element. Raises ValueError if not found.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">insert(index, element)</code></h5>
<p>Insert element at index. Like list.insert(), indices past the end append.
Note: If using z_index for sorting, insertion order may not persist after
the next render. Use name-based .find() for stable element access.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">pop([index]) -> element</code></h5>
<p>Remove and return element at index (default: last element).
Note: If using z_index for sorting, indices may shift after render.
Use name-based .find() for stable element access.</p>
</div>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">remove(element)</code></h5>
<p>Remove first occurrence of element. Raises ValueError if not found.</p>
</div>
</div>
@ -1173,6 +1569,14 @@ Note:</p>
<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>

408
docs/mcrfpy.3
View File

@ -14,11 +14,11 @@
. ftr VB CB
. ftr VBI CBI
.\}
.TH "MCRFPY" "3" "2025-10-30" "McRogueFace dev" ""
.TH "MCRFPY" "3" "2025-11-29" "McRogueFace dev" ""
.hy
.SH McRogueFace API Reference
.PP
\f[I]Generated on 2025-10-30 20:49:34\f[R]
\f[I]Generated on 2025-11-29 10:12:05\f[R]
.PP
\f[I]This documentation was dynamically generated from the compiled
module.\f[R]
@ -31,10 +31,16 @@ Classes
.IP \[bu] 2
Animation
.IP \[bu] 2
Arc
.IP \[bu] 2
Caption
.IP \[bu] 2
Circle
.IP \[bu] 2
Color
.IP \[bu] 2
ColorLayer
.IP \[bu] 2
Drawable
.IP \[bu] 2
Entity
@ -51,12 +57,16 @@ GridPoint
.IP \[bu] 2
GridPointState
.IP \[bu] 2
Line
.IP \[bu] 2
Scene
.IP \[bu] 2
Sprite
.IP \[bu] 2
Texture
.IP \[bu] 2
TileLayer
.IP \[bu] 2
Timer
.IP \[bu] 2
UICollection
@ -110,6 +120,17 @@ Note:
.PP
\f[B]Returns:\f[R] None No error is raised if the timer doesn\[cq]t
exist.
.SS \f[V]end_benchmark() -> str\f[R]
.PP
Stop benchmark capture and write data to JSON file.
.PP
Note:
.PP
\f[B]Returns:\f[R] str: The filename of the written benchmark data
.PP
\f[B]Raises:\f[R] RuntimeError: If no benchmark is currently running
Returns the auto-generated filename (e.g.,
`benchmark_12345_20250528_143022.json')
.SS \f[V]exit() -> None\f[R]
.PP
Cleanly shut down the game engine and exit the application.
@ -180,6 +201,19 @@ OGG, FLAC)
.PP
\f[B]Returns:\f[R] None Only one music track can play at a time.
Loading new music stops the current track.
.SS \f[V]log_benchmark(message: str) -> None\f[R]
.PP
Add a log message to the current benchmark frame.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]message\f[R]: Text to associate with the
current frame
.PP
\f[B]Returns:\f[R] None
.PP
\f[B]Raises:\f[R] RuntimeError: If no benchmark is currently running
Messages appear in the `logs' array of each frame in the output JSON.
.SS \f[V]playSound(buffer_id: int) -> None\f[R]
.PP
Play a sound effect using a previously loaded buffer.
@ -201,6 +235,18 @@ If None, uses current scene
in the scene
.PP
\f[B]Raises:\f[R] KeyError: If the specified scene doesn\[cq]t exist
.SS \f[V]setDevConsole(enabled: bool) -> None\f[R]
.PP
Enable or disable the developer console overlay.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]enabled\f[R]: True to enable the console
(default), False to disable
.PP
\f[B]Returns:\f[R] None When disabled, the grave/tilde key will not open
the console.
Use this to ship games without debug features.
.SS \f[V]setMusicVolume(volume: int) -> None\f[R]
.PP
Set the global music volume.
@ -255,6 +301,17 @@ Note:
\f[B]Returns:\f[R] None If a timer with this name exists, it will be
replaced.
The handler receives the total runtime in seconds as its argument.
.SS \f[V]start_benchmark() -> None\f[R]
.PP
Start capturing benchmark data to a file.
.PP
Note:
.PP
\f[B]Returns:\f[R] None
.PP
\f[B]Raises:\f[R] RuntimeError: If a benchmark is already running
Benchmark filename is auto-generated from PID and timestamp.
Use end_benchmark() to stop and get filename.
.SS Classes
.SS Animation
.PP
@ -316,6 +373,62 @@ update in seconds
\f[B]Returns:\f[R] bool: True if animation is still running, False if
complete Typically called by AnimationManager automatically.
Manual calls only needed for custom animation control.
.SS Arc
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Arc(center=None, radius=0, start_angle=0, end_angle=90, color=None,
thickness=1, **kwargs)
.PP
An arc UI element for drawing curved line segments.
.PP
Args: center (tuple, optional): Center position as (x, y).
Default: (0, 0) radius (float, optional): Arc radius in pixels.
Default: 0 start_angle (float, optional): Starting angle in degrees.
Default: 0 end_angle (float, optional): Ending angle in degrees.
Default: 90 color (Color, optional): Arc color.
Default: White thickness (float, optional): Line thickness.
Default: 1.0
.PP
Keyword Args: 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
.PP
Attributes: center (Vector): Center position radius (float): Arc radius
start_angle (float): Starting angle in degrees end_angle (float): Ending
angle in degrees color (Color): Arc color thickness (float): Line
thickness visible (bool): Visibility state opacity (float): Opacity
value z_index (int): Rendering order name (str): Element name
.PP
\f[B]Methods:\f[R]
.SS \f[V]get_bounds() -> tuple\f[R]
.PP
Get the bounding rectangle of this drawable element.
.PP
Note:
.PP
\f[B]Returns:\f[R] tuple: (x, y, width, height) representing the
element\[cq]s bounds The bounds are in screen coordinates and account
for current position and size.
.SS \f[V]move(dx: float, dy: float) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels -
\f[V]dy\f[R]: Vertical offset in pixels
.SS \f[V]resize(width: float, height: float) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels -
\f[V]height\f[R]: New height in pixels
.SS Caption
.PP
\f[I]Inherits from: Drawable\f[R]
@ -378,6 +491,61 @@ Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels -
\f[V]height\f[R]: New height in pixels
.SS Circle
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Circle(radius=0, center=None, fill_color=None, outline_color=None,
outline=0, **kwargs)
.PP
A circle UI element for drawing filled or outlined circles.
.PP
Args: radius (float, optional): Circle radius in pixels.
Default: 0 center (tuple, optional): Center position as (x, y).
Default: (0, 0) fill_color (Color, optional): Fill color.
Default: White outline_color (Color, optional): Outline color.
Default: Transparent outline (float, optional): Outline thickness.
Default: 0 (no outline)
.PP
Keyword Args: 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
.PP
Attributes: radius (float): Circle radius center (Vector): Center
position fill_color (Color): Fill color outline_color (Color): Outline
color outline (float): Outline thickness visible (bool): Visibility
state opacity (float): Opacity value z_index (int): Rendering order name
(str): Element name
.PP
\f[B]Methods:\f[R]
.SS \f[V]get_bounds() -> tuple\f[R]
.PP
Get the bounding rectangle of this drawable element.
.PP
Note:
.PP
\f[B]Returns:\f[R] tuple: (x, y, width, height) representing the
element\[cq]s bounds The bounds are in screen coordinates and account
for current position and size.
.SS \f[V]move(dx: float, dy: float) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels -
\f[V]dy\f[R]: Vertical offset in pixels
.SS \f[V]resize(width: float, height: float) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels -
\f[V]height\f[R]: New height in pixels
.SS Color
.PP
SFML Color Object
@ -419,6 +587,34 @@ Note:
\f[B]Returns:\f[R] str: Hex string in format `#RRGGBB' or `#RRGGBBAA'
(if alpha < 255) Alpha component is only included if not fully opaque (<
255)
.SS ColorLayer
.PP
ColorLayer(z_index=-1, grid_size=None)
.PP
A grid layer that stores RGBA colors per cell.
.PP
Args: z_index (int): Render order.
Negative = below entities.
Default: -1 grid_size (tuple): Dimensions as (width, height).
Default: parent grid size
.PP
Attributes: z_index (int): Layer z-order relative to entities visible
(bool): Whether layer is rendered grid_size (tuple): Layer dimensions
(read-only)
.PP
Methods: at(x, y): Get color at cell position set(x, y, color): Set
color at cell position fill(color): Fill entire layer with color
.PP
\f[B]Methods:\f[R]
.SS \f[V]at(x, y) -> Color\f[R]
.PP
Get the color at cell position (x, y).
.SS \f[V]fill(color)\f[R]
.PP
Fill the entire layer with the specified color.
.SS \f[V]set(x, y, color)\f[R]
.PP
Set the color at cell position (x, y).
.SS Drawable
.PP
Base class for all drawable UI elements
@ -531,11 +727,36 @@ perspective set.
Iterable, indexable collection of Entities
.PP
\f[B]Methods:\f[R]
.SS \f[V]append(...)\f[R]
.SS \f[V]count(...)\f[R]
.SS \f[V]extend(...)\f[R]
.SS \f[V]index(...)\f[R]
.SS \f[V]remove(...)\f[R]
.SS \f[V]append(entity)\f[R]
.PP
Add an entity to the end of the collection.
.SS \f[V]count(entity) -> int\f[R]
.PP
Count occurrences of entity in the collection.
.SS \f[V]extend(iterable)\f[R]
.PP
Add all entities from an iterable to the collection.
.SS \f[V]find(name) -> entity or list\f[R]
.PP
Find entities by name.
.PP
\f[B]Returns:\f[R] Single entity if exact match, list if wildcard, None
if not found.
.SS \f[V]index(entity) -> int\f[R]
.PP
Return index of first occurrence of entity.
Raises ValueError if not found.
.SS \f[V]insert(index, entity)\f[R]
.PP
Insert entity at index.
Like list.insert(), indices past the end append.
.SS \f[V]pop([index]) -> entity\f[R]
.PP
Remove and return entity at index (default: last entity).
.SS \f[V]remove(entity)\f[R]
.PP
Remove first occurrence of entity.
Raises ValueError if not found.
.SS Font
.PP
SFML Font Object
@ -568,6 +789,8 @@ 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
.PP
Attributes: x, y (float): Position in pixels w, h (float): Size in
@ -577,7 +800,7 @@ 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
frame bounds cache_subtree (bool): Cache subtree rendering to texture
.PP
\f[B]Methods:\f[R]
.SS \f[V]get_bounds() -> tuple\f[R]
@ -653,6 +876,17 @@ visible (bool): Visibility state opacity (float): Opacity value z_index
(int): Rendering order name (str): Element name
.PP
\f[B]Methods:\f[R]
.SS \f[V]add_layer(type: str, z_index: int = -1, texture: Texture = None) -> ColorLayer | TileLayer\f[R]
.PP
Add a new layer to the grid.
.PP
\f[B]Arguments:\f[R] - \f[V]type\f[R]: Layer type (`color' or `tile') -
\f[V]z_index\f[R]: Render order.
Negative = below entities, >= 0 = above entities.
Default: -1 - \f[V]texture\f[R]: Texture for tile layers.
Required for `tile' type.
.PP
\f[B]Returns:\f[R] The created ColorLayer or TileLayer object.
.SS \f[V]at(...)\f[R]
.SS \f[V]compute_astar_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]\f[R]
.PP
@ -673,20 +907,15 @@ Compute Dijkstra map from root position.
\f[B]Arguments:\f[R] - \f[V]root_x\f[R]: X coordinate of the root/target
- \f[V]root_y\f[R]: Y coordinate of the root/target -
\f[V]diagonal_cost\f[R]: Cost of diagonal movement (default: 1.41)
.SS \f[V]compute_fov(x: int, y: int, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> List[Tuple[int, int, bool, bool]]\f[R]
.SS \f[V]compute_fov(x: int, y: int, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None\f[R]
.PP
Compute field of view from a position and return visible cells.
Compute field of view from a position.
.PP
\f[B]Arguments:\f[R] - \f[V]x\f[R]: X coordinate of the viewer -
\f[V]y\f[R]: Y coordinate of the viewer - \f[V]radius\f[R]: Maximum view
distance (0 = unlimited) - \f[V]light_walls\f[R]: Whether walls are lit
when visible - \f[V]algorithm\f[R]: FOV algorithm to use (FOV_BASIC,
FOV_DIAMOND, FOV_SHADOW, FOV_PERMISSIVE_0-8)
.PP
\f[B]Returns:\f[R] List of tuples (x, y, visible, discovered) for all
visible cells: - x, y: Grid coordinates - visible: True (all returned
cells are visible) - discovered: True (FOV implies discovery) Also
updates the internal FOV state for use with is_in_fov().
.SS \f[V]find_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]\f[R]
.PP
Find A* path between two points.
@ -736,6 +965,15 @@ Y coordinate to check
.PP
\f[B]Returns:\f[R] True if the cell is visible, False otherwise Must
call compute_fov() first to calculate visibility.
.SS \f[V]layer(z_index: int) -> ColorLayer | TileLayer | None\f[R]
.PP
Get a layer by its z_index.
.PP
\f[B]Arguments:\f[R] - \f[V]z_index\f[R]: The z_index of the layer to
find.
.PP
\f[B]Returns:\f[R] The layer with the specified z_index, or None if not
found.
.SS \f[V]move(dx: float, dy: float) -> None\f[R]
.PP
Move the element by a relative offset.
@ -744,6 +982,11 @@ Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels -
\f[V]dy\f[R]: Vertical offset in pixels
.SS \f[V]remove_layer(layer: ColorLayer | TileLayer) -> None\f[R]
.PP
Remove a layer from the grid.
.PP
\f[B]Arguments:\f[R] - \f[V]layer\f[R]: The layer to remove.
.SS \f[V]resize(width: float, height: float) -> None\f[R]
.PP
Resize the element to new dimensions.
@ -762,6 +1005,58 @@ UIGridPoint object
UIGridPointState object
.PP
\f[B]Methods:\f[R]
.SS Line
.PP
\f[I]Inherits from: Drawable\f[R]
.PP
Line(start=None, end=None, thickness=1.0, color=None, **kwargs)
.PP
A line UI element for drawing straight lines between two points.
.PP
Args: start (tuple, optional): Starting point as (x, y).
Default: (0, 0) end (tuple, optional): Ending point as (x, y).
Default: (0, 0) thickness (float, optional): Line thickness in pixels.
Default: 1.0 color (Color, optional): Line color.
Default: White
.PP
Keyword Args: 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
.PP
Attributes: start (Vector): Starting point end (Vector): Ending point
thickness (float): Line thickness color (Color): Line color visible
(bool): Visibility state opacity (float): Opacity value z_index (int):
Rendering order name (str): Element name
.PP
\f[B]Methods:\f[R]
.SS \f[V]get_bounds() -> tuple\f[R]
.PP
Get the bounding rectangle of this drawable element.
.PP
Note:
.PP
\f[B]Returns:\f[R] tuple: (x, y, width, height) representing the
element\[cq]s bounds The bounds are in screen coordinates and account
for current position and size.
.SS \f[V]move(dx: float, dy: float) -> None\f[R]
.PP
Move the element by a relative offset.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]dx\f[R]: Horizontal offset in pixels -
\f[V]dy\f[R]: Vertical offset in pixels
.SS \f[V]resize(width: float, height: float) -> None\f[R]
.PP
Resize the element to new dimensions.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]width\f[R]: New width in pixels -
\f[V]height\f[R]: New height in pixels
.SS Scene
.PP
Base class for object-oriented scenes
@ -864,6 +1159,38 @@ Note:
SFML Texture Object
.PP
\f[B]Methods:\f[R]
.SS TileLayer
.PP
TileLayer(z_index=-1, texture=None, grid_size=None)
.PP
A grid layer that stores sprite indices per cell.
.PP
Args: z_index (int): Render order.
Negative = below entities.
Default: -1 texture (Texture): Sprite atlas for tile rendering.
Default: None grid_size (tuple): Dimensions as (width, height).
Default: parent grid size
.PP
Attributes: z_index (int): Layer z-order relative to entities visible
(bool): Whether layer is rendered texture (Texture): Tile sprite atlas
grid_size (tuple): Layer dimensions (read-only)
.PP
Methods: at(x, y): Get tile index at cell position set(x, y, index): Set
tile index at cell position fill(index): Fill entire layer with tile
index
.PP
\f[B]Methods:\f[R]
.SS \f[V]at(x, y) -> int\f[R]
.PP
Get the tile index at cell position (x, y).
Returns -1 if no tile.
.SS \f[V]fill(index)\f[R]
.PP
Fill the entire layer with the specified tile index.
.SS \f[V]set(x, y, index)\f[R]
.PP
Set the tile index at cell position (x, y).
Use -1 for no tile.
.SS Timer
.PP
Timer(name, callback, interval, once=False)
@ -937,11 +1264,43 @@ Timer will fire after the remaining time elapses.
Iterable, indexable collection of UI objects
.PP
\f[B]Methods:\f[R]
.SS \f[V]append(...)\f[R]
.SS \f[V]count(...)\f[R]
.SS \f[V]extend(...)\f[R]
.SS \f[V]index(...)\f[R]
.SS \f[V]remove(...)\f[R]
.SS \f[V]append(element)\f[R]
.PP
Add an element to the end of the collection.
.SS \f[V]count(element) -> int\f[R]
.PP
Count occurrences of element in the collection.
.SS \f[V]extend(iterable)\f[R]
.PP
Add all elements from an iterable to the collection.
.SS \f[V]find(name, recursive=False) -> element or list\f[R]
.PP
Find elements by name.
.PP
\f[B]Returns:\f[R] Single element if exact match, list if wildcard, None
if not found.
.SS \f[V]index(element) -> int\f[R]
.PP
Return index of first occurrence of element.
Raises ValueError if not found.
.SS \f[V]insert(index, element)\f[R]
.PP
Insert element at index.
Like list.insert(), indices past the end append.
.PP
Note: If using z_index for sorting, insertion order may not persist
after the next render.
Use name-based .find() for stable element access.
.SS \f[V]pop([index]) -> element\f[R]
.PP
Remove and return element at index (default: last element).
.PP
Note: If using z_index for sorting, indices may shift after render.
Use name-based .find() for stable element access.
.SS \f[V]remove(element)\f[R]
.PP
Remove first occurrence of element.
Raises ValueError if not found.
.SS UICollectionIter
.PP
Iterator for a collection of UI objects
@ -981,6 +1340,15 @@ Calculate the dot product with another vector.
\f[B]Arguments:\f[R] - \f[V]other\f[R]: The other vector
.PP
\f[B]Returns:\f[R] float: Dot product of the two vectors
.SS \f[V]floor() -> Vector\f[R]
.PP
Return a new vector with floored (integer) coordinates.
.PP
Note:
.PP
\f[B]Returns:\f[R] Vector: New Vector with floor(x) and floor(y) Useful
for grid-based positioning.
For a hashable tuple, use the .int property instead.
.SS \f[V]magnitude() -> float\f[R]
.PP
Calculate the length/magnitude of this vector.

166
stubs/mcrfpy.pyi
View File

@ -96,98 +96,159 @@ class Drawable:
...
class Frame(Drawable):
"""Frame(x=0, y=0, w=0, h=0, fill_color=None, outline_color=None, outline=0, click=None, children=None)
"""Frame(x=0, y=0, w=0, h=0, fill_color=None, outline_color=None, outline=0, on_click=None, children=None)
A rectangular frame UI element that can contain other drawable elements.
"""
@overload
def __init__(self) -> None: ...
@overload
def __init__(self, x: float = 0, y: float = 0, w: float = 0, h: float = 0,
fill_color: Optional[Color] = None, outline_color: Optional[Color] = None,
outline: float = 0, click: Optional[Callable] = None,
outline: float = 0, on_click: Optional[Callable] = None,
children: Optional[List[UIElement]] = None) -> None: ...
w: float
h: float
fill_color: Color
outline_color: Color
outline: float
click: Optional[Callable[[float, float, int], None]]
on_click: Optional[Callable[[float, float, int], None]]
on_enter: Optional[Callable[[], None]]
on_exit: Optional[Callable[[], None]]
on_move: Optional[Callable[[float, float], None]]
children: 'UICollection'
clip_children: bool
class Caption(Drawable):
"""Caption(text='', x=0, y=0, font=None, fill_color=None, outline_color=None, outline=0, click=None)
"""Caption(text='', x=0, y=0, font=None, fill_color=None, outline_color=None, outline=0, on_click=None)
A text display UI element with customizable font and styling.
"""
@overload
def __init__(self) -> None: ...
@overload
def __init__(self, text: str = '', x: float = 0, y: float = 0,
font: Optional[Font] = None, fill_color: Optional[Color] = None,
outline_color: Optional[Color] = None, outline: float = 0,
click: Optional[Callable] = None) -> None: ...
on_click: Optional[Callable] = None) -> None: ...
text: str
font: Font
fill_color: Color
outline_color: Color
outline: float
click: Optional[Callable[[float, float, int], None]]
on_click: Optional[Callable[[float, float, int], None]]
on_enter: Optional[Callable[[], None]]
on_exit: Optional[Callable[[], None]]
on_move: Optional[Callable[[float, float], None]]
w: float # Read-only, computed from text
h: float # Read-only, computed from text
class Sprite(Drawable):
"""Sprite(x=0, y=0, texture=None, sprite_index=0, scale=1.0, click=None)
"""Sprite(x=0, y=0, texture=None, sprite_index=0, scale=1.0, on_click=None)
A sprite UI element that displays a texture or portion of a texture atlas.
"""
@overload
def __init__(self) -> None: ...
@overload
def __init__(self, x: float = 0, y: float = 0, texture: Optional[Texture] = None,
sprite_index: int = 0, scale: float = 1.0,
click: Optional[Callable] = None) -> None: ...
on_click: Optional[Callable] = None) -> None: ...
texture: Texture
sprite_index: int
scale: float
click: Optional[Callable[[float, float, int], None]]
on_click: Optional[Callable[[float, float, int], None]]
on_enter: Optional[Callable[[], None]]
on_exit: Optional[Callable[[], None]]
on_move: Optional[Callable[[float, float], None]]
w: float # Read-only, computed from texture
h: float # Read-only, computed from texture
class Grid(Drawable):
"""Grid(x=0, y=0, grid_size=(20, 20), texture=None, tile_width=16, tile_height=16, scale=1.0, click=None)
"""Grid(pos=None, size=None, grid_size=(20, 20), texture=None, on_click=None, layers=None)
A grid-based tilemap UI element for rendering tile-based levels and game worlds.
Supports multiple rendering layers (ColorLayer, TileLayer) and entity management.
"""
@overload
def __init__(self) -> None: ...
@overload
def __init__(self, x: float = 0, y: float = 0, grid_size: Tuple[int, int] = (20, 20),
texture: Optional[Texture] = None, tile_width: int = 16, tile_height: int = 16,
scale: float = 1.0, click: Optional[Callable] = None) -> None: ...
def __init__(self, pos: Optional[Tuple[float, float]] = None,
size: Optional[Tuple[float, float]] = None,
grid_size: Tuple[int, int] = (20, 20),
texture: Optional[Texture] = None,
on_click: Optional[Callable] = None,
layers: Optional[Dict[str, str]] = None) -> None: ...
grid_size: Tuple[int, int]
tile_width: int
tile_height: int
grid_x: int # Read-only grid width
grid_y: int # Read-only grid height
texture: Texture
scale: float
points: List[List['GridPoint']]
zoom: float
center: Tuple[float, float]
center_x: float
center_y: float
fill_color: Color
entities: 'EntityCollection'
background_color: Color
click: Optional[Callable[[int, int, int], None]]
children: 'UICollection'
layers: List[Union['ColorLayer', 'TileLayer']]
hovered_cell: Optional[Tuple[int, int]]
# Mouse event handlers
on_click: Optional[Callable[[float, float, int], None]]
on_enter: Optional[Callable[[], None]]
on_exit: Optional[Callable[[], None]]
on_move: Optional[Callable[[float, float], None]]
# Grid cell event handlers
on_cell_click: Optional[Callable[[int, int], None]]
on_cell_enter: Optional[Callable[[int, int], None]]
on_cell_exit: Optional[Callable[[int, int], None]]
def at(self, x: int, y: int) -> 'GridPoint':
"""Get grid point at tile coordinates."""
...
def add_layer(self, type: str, z_index: int = -1,
texture: Optional[Texture] = None) -> Union['ColorLayer', 'TileLayer']:
"""Add a rendering layer. type='color' or 'tile'. z_index<0 = below entities."""
...
def remove_layer(self, layer: Union['ColorLayer', 'TileLayer']) -> None:
"""Remove a layer from the grid."""
...
def compute_fov(self, x: int, y: int, radius: int) -> None:
"""Compute field of view from a position."""
...
def is_in_fov(self, x: int, y: int) -> bool:
"""Check if a cell is visible in the current FOV."""
...
def compute_dijkstra(self, sources: List[Tuple[int, int]], max_cost: float = -1) -> None:
"""Compute Dijkstra distance map from source points."""
...
def get_dijkstra_distance(self, x: int, y: int) -> float:
"""Get distance to nearest source for a cell."""
...
def get_dijkstra_path(self, x: int, y: int) -> List[Tuple[int, int]]:
"""Get path from cell to nearest source."""
...
def find_path(self, x1: int, y1: int, x2: int, y2: int) -> List[Tuple[int, int]]:
"""Find A* path between two cells."""
...
class GridPoint:
"""Grid point representing a single tile."""
@ -197,10 +258,49 @@ class GridPoint:
class GridPointState:
"""State information for a grid point."""
texture_index: int
color: Color
class ColorLayer:
"""Grid layer that renders solid colors per cell."""
z_index: int
visible: bool
grid_size: Tuple[int, int]
def fill(self, color: Color) -> None:
"""Fill all cells with a color."""
...
def set(self, x: int, y: int, color: Color) -> None:
"""Set color at a specific cell."""
...
def at(self, x: int, y: int) -> Color:
"""Get color at a specific cell."""
...
class TileLayer:
"""Grid layer that renders texture tiles per cell."""
z_index: int
visible: bool
texture: Texture
grid_size: Tuple[int, int]
def fill(self, sprite_index: int) -> None:
"""Fill all cells with a sprite index."""
...
def set(self, x: int, y: int, sprite_index: int) -> None:
"""Set tile sprite at a specific cell."""
...
def at(self, x: int, y: int) -> int:
"""Get tile sprite index at a specific cell."""
...
class Entity(Drawable):
"""Entity(grid_x=0, grid_y=0, texture=None, sprite_index=0, name='')

30
tests/demo/screens/grid_demo.py
View File

@ -8,29 +8,33 @@ class GridDemo(DemoScreen):
def setup(self):
self.add_title("Grid System")
self.add_description("Tile-based rendering with camera, zoom, and children support")
self.add_description("Multi-layer rendering with camera, zoom, and children support")
# Create a grid
grid = mcrfpy.Grid(grid_size=(15, 10), pos=(50, 120), size=(400, 280))
# Create a grid with no default layers
grid = mcrfpy.Grid(grid_size=(15, 10), pos=(50, 120), size=(400, 280), layers={})
grid.fill_color = mcrfpy.Color(20, 20, 40)
# Add a color layer for the checkerboard pattern (z_index=-1 = below entities)
color_layer = grid.add_layer("color", z_index=-1)
# Center camera on middle of grid (in pixel coordinates: cells * cell_size / 2)
# For 15x10 grid with 16x16 cells: center = (15*16/2, 10*16/2) = (120, 80)
grid.center = (120, 80)
self.ui.append(grid)
# Set some tile colors to create a pattern
# Set tile colors via the color layer to create a pattern
for x in range(15):
for y in range(10):
point = grid.at(x, y)
# Checkerboard pattern
if (x + y) % 2 == 0:
point.color = mcrfpy.Color(40, 40, 60)
color_layer.set(x, y, mcrfpy.Color(40, 40, 60))
else:
point.color = mcrfpy.Color(30, 30, 50)
color_layer.set(x, y, mcrfpy.Color(30, 30, 50))
# Border
if x == 0 or x == 14 or y == 0 or y == 9:
point.color = mcrfpy.Color(80, 60, 40)
color_layer.set(x, y, mcrfpy.Color(80, 60, 40))
point.walkable = False
# Add some children to the grid
@ -53,13 +57,12 @@ class GridDemo(DemoScreen):
props = [
"grid_size: (15, 10)",
"zoom: 1.0",
"layers: [ColorLayer]",
"center: (120, 80)",
"fill_color: dark blue",
"",
"Features:",
"- Multi-layer rendering",
"- Camera pan/zoom",
"- Tile colors",
"- Children collection",
"- FOV/pathfinding",
]
@ -69,8 +72,9 @@ class GridDemo(DemoScreen):
info.children.append(cap)
# Code example
code = """# Grid with children
grid = mcrfpy.Grid(grid_size=(20, 15), pos=(50, 50), size=(320, 240))
grid.at(5, 5).color = mcrfpy.Color(255, 0, 0) # Red tile
code = """# Grid with layers
grid = mcrfpy.Grid(grid_size=(20, 15), pos=(50, 50), size=(320, 240), layers={})
layer = grid.add_layer("color", z_index=-1) # Below entities
layer.set(5, 5, mcrfpy.Color(255, 0, 0)) # Red tile
grid.children.append(mcrfpy.Caption("Label", pos=(80, 48)))"""
self.add_code_example(code, y=420)

BIN
tests/demo/screenshots/demo_03_grid_system.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 71 KiB

After

Width:  |  Height:  |  Size: 76 KiB

BIN
tests/demo/screenshots/demo_04_animation_system.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 60 KiB

After

Width:  |  Height:  |  Size: 60 KiB