John McCardle
e64c5c147f
Doc generator fixes (tools/generate_dynamic_docs.py): - Add types.GetSetDescriptorType detection for C++ extension properties - All 22 classes with properties now have documented Properties sections - Read-only detection via "read-only" docstring convention Scene class documentation (src/PySceneObject.h): - Expanded tp_doc with constructor, properties, lifecycle callbacks - Documents key advantage: on_key works on ANY scene - Includes usage examples for basic and subclass patterns CLAUDE.md additions: - New section "Adding Documentation for New Python Types" - Step-by-step guide for tp_doc, PyMethodDef, PyGetSetDef - Documentation extraction details and troubleshooting 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2130 lines
121 KiB
HTML
2130 lines
121 KiB
HTML
<!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 2025-12-29 14:23:40</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="#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>
|
|
<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="#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>
|
|
<li><a href="#UIEntityCollectionIter">UIEntityCollectionIter</a></li>
|
|
<li><a href="#Vector">Vector</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">createScene(name: str) -> None</code></h3>
|
|
<p>Create a new empty scene.
|
|
|
|
Note:</p>
|
|
<h4>Arguments:</h4>
|
|
<ul>
|
|
<li><span class='arg-name'>name</span>: Unique name for the new scene</li>
|
|
</ul>
|
|
<p><span class='returns'>Returns:</span> None</p>
|
|
<p><span class='raises'>Raises:</span> ValueError: If a scene with this name already exists The scene is created but not made active. Use setScene() to switch to it.</p>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3><code class="function-signature">createSoundBuffer(filename: str) -> int</code></h3>
|
|
<p>Load a sound effect from a file and return its buffer ID.</p>
|
|
<h4>Arguments:</h4>
|
|
<ul>
|
|
<li><span class='arg-name'>filename</span>: Path to the sound file (WAV, OGG, FLAC)</li>
|
|
</ul>
|
|
<p><span class='returns'>Returns:</span> int: Buffer ID for use with playSound()</p>
|
|
<p><span class='raises'>Raises:</span> RuntimeError: If the file cannot be loaded</p>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3><code class="function-signature">currentScene() -> str</code></h3>
|
|
<p>Get the name of the currently active scene.</p>
|
|
<p><span class='returns'>Returns:</span> str: Name of the current scene</p>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3><code class="function-signature">delTimer(name: str) -> None</code></h3>
|
|
<p>Stop and remove a timer.
|
|
|
|
Note:</p>
|
|
<h4>Arguments:</h4>
|
|
<ul>
|
|
<li><span class='arg-name'>name</span>: Timer identifier to remove</li>
|
|
</ul>
|
|
<p><span class='returns'>Returns:</span> None No error is raised if the timer doesn'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., 'benchmark_12345_20250528_143022.json')</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">findAll(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">getMetrics() -> 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">getMusicVolume() -> int</code></h3>
|
|
<p>Get the current music volume level.</p>
|
|
<p><span class='returns'>Returns:</span> int: Current volume (0-100)</p>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3><code class="function-signature">getSoundVolume() -> int</code></h3>
|
|
<p>Get the current sound effects volume level.</p>
|
|
<p><span class='returns'>Returns:</span> int: Current volume (0-100)</p>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3><code class="function-signature">keypressScene(handler: callable) -> None</code></h3>
|
|
<p>Set the keyboard event handler for the current scene.
|
|
|
|
Note:</p>
|
|
<h4>Arguments:</h4>
|
|
<ul>
|
|
<li><span class='arg-name'>handler</span>: Callable that receives (key_name: str, is_pressed: bool)</li>
|
|
</ul>
|
|
<p><span class='returns'>Returns:</span> None</p>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3><code class="function-signature">loadMusic(filename: str) -> None</code></h3>
|
|
<p>Load and immediately play background music from a file.
|
|
|
|
Note:</p>
|
|
<h4>Arguments:</h4>
|
|
<ul>
|
|
<li><span class='arg-name'>filename</span>: Path to the music file (WAV, OGG, FLAC)</li>
|
|
</ul>
|
|
<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 'logs' 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>
|
|
<h4>Arguments:</h4>
|
|
<ul>
|
|
<li><span class='arg-name'>buffer_id</span>: Sound buffer ID returned by createSoundBuffer()</li>
|
|
</ul>
|
|
<p><span class='returns'>Returns:</span> None</p>
|
|
<p><span class='raises'>Raises:</span> RuntimeError: If the buffer ID is invalid</p>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3><code class="function-signature">sceneUI(scene: str = None) -> list</code></h3>
|
|
<p>Get all UI elements for a scene.</p>
|
|
<h4>Arguments:</h4>
|
|
<ul>
|
|
<li><span class='arg-name'>scene</span>: Scene name. If None, uses current scene</li>
|
|
</ul>
|
|
<p><span class='returns'>Returns:</span> list: All UI elements (Frame, Caption, Sprite, Grid) in the scene</p>
|
|
<p><span class='raises'>Raises:</span> KeyError: If the specified scene doesn'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>
|
|
<h4>Arguments:</h4>
|
|
<ul>
|
|
<li><span class='arg-name'>volume</span>: Volume level from 0 (silent) to 100 (full volume)</li>
|
|
</ul>
|
|
<p><span class='returns'>Returns:</span> None</p>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3><code class="function-signature">setScale(multiplier: float) -> None</code></h3>
|
|
<p>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">setScene(scene: str, transition: str = None, duration: float = 0.0) -> None</code></h3>
|
|
<p>Switch to a different scene with optional transition effect.</p>
|
|
<h4>Arguments:</h4>
|
|
<ul>
|
|
<li><span class='arg-name'>scene</span>: Name of the scene to switch to</li>
|
|
<li><span class='arg-name'>transition</span>: Transition type ('fade', 'slide_left', 'slide_right', 'slide_up', 'slide_down')</li>
|
|
<li><span class='arg-name'>duration</span>: Transition duration in seconds (default: 0.0 for instant)</li>
|
|
</ul>
|
|
<p><span class='returns'>Returns:</span> None</p>
|
|
<p><span class='raises'>Raises:</span> KeyError: If the scene doesn't exist ValueError: If the transition type is invalid</p>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3><code class="function-signature">setSoundVolume(volume: int) -> None</code></h3>
|
|
<p>Set the global sound effects volume.</p>
|
|
<h4>Arguments:</h4>
|
|
<ul>
|
|
<li><span class='arg-name'>volume</span>: Volume level from 0 (silent) to 100 (full volume)</li>
|
|
</ul>
|
|
<p><span class='returns'>Returns:</span> None</p>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3><code class="function-signature">setTimer(name: str, handler: callable, interval: int) -> None</code></h3>
|
|
<p>Create or update a recurring timer.
|
|
|
|
Note:</p>
|
|
<h4>Arguments:</h4>
|
|
<ul>
|
|
<li><span class='arg-name'>name</span>: Unique identifier for the timer</li>
|
|
<li><span class='arg-name'>handler</span>: Function called with (runtime: float) parameter</li>
|
|
<li><span class='arg-name'>interval</span>: Time between calls in milliseconds</li>
|
|
</ul>
|
|
<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>
|
|
|
|
<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="Animation"><span class="class-name">Animation</span></h3>
|
|
<p>Animation object for animating UI properties</p>
|
|
<h4>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>duration</span> (read-only): Animation duration in seconds (float, read-only). Total time for the animation to complete.</li>
|
|
<li><span class='property-name'>elapsed</span> (read-only): Elapsed time in seconds (float, read-only). Time since the animation started.</li>
|
|
<li><span class='property-name'>is_complete</span> (read-only): Whether animation is complete (bool, read-only). True when elapsed >= duration or complete() was called.</li>
|
|
<li><span class='property-name'>is_delta</span> (read-only): Whether animation uses delta mode (bool, read-only). In delta mode, the target value is added to the starting value.</li>
|
|
<li><span class='property-name'>property</span> (read-only): Target property name (str, read-only). The property being animated (e.g., 'pos', 'opacity', 'sprite_index').</li>
|
|
</ul>
|
|
<h4>Methods:</h4>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">complete() -> None</code></h5>
|
|
<p>Complete the animation immediately by jumping to the final value.
|
|
|
|
Note:</p>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None Sets elapsed = duration and applies target value immediately. Completion callback will be called if set.</p>
|
|
</div>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">get_current_value() -> Any</code></h5>
|
|
<p>Get the current interpolated value of the animation.
|
|
|
|
Note:</p>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Any: Current value (type depends on property: float, int, Color tuple, Vector tuple, or str) Return type matches the target property type. For sprite_index returns int, for pos returns (x, y), for fill_color returns (r, g, b, a).</p>
|
|
</div>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">hasValidTarget() -> bool</code></h5>
|
|
<p>Check if the animation still has a valid target.
|
|
|
|
Note:</p>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> bool: True if the target still exists, False if it was destroyed Animations automatically clean up when targets are destroyed. Use this to check if manual cleanup is needed.</p>
|
|
</div>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">start(target: UIDrawable, conflict_mode: str = 'replace') -> None</code></h5>
|
|
<p>Start the animation on a target UI element.
|
|
|
|
Note:</p>
|
|
<div style='margin-left: 20px;'>
|
|
<div><span class='arg-name'>target</span>: The UI element to animate (Frame, Caption, Sprite, Grid, or Entity)</div>
|
|
<div><span class='arg-name'>conflict_mode</span>: How to handle conflicts if property is already animating: 'replace' (default) - complete existing animation and start new one; 'queue' - wait for existing animation to complete; 'error' - raise RuntimeError if property is busy</div>
|
|
</div>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None</p>
|
|
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> RuntimeError: When conflict_mode='error' and property is already animating The animation will automatically stop if the target is destroyed.</p>
|
|
</div>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">update(delta_time: float) -> bool</code></h5>
|
|
<p>Update the animation by the given time delta.
|
|
|
|
Note:</p>
|
|
<div style='margin-left: 20px;'>
|
|
<div><span class='arg-name'>delta_time</span>: Time elapsed since last update in seconds</div>
|
|
</div>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> bool: True if animation is still running, False if complete Typically called by AnimationManager automatically. Manual calls only needed for custom animation control.</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
|
|
|
|
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>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</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 rectangle (x, y, width, height) in screen coordinates.</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'>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'>name</span>: Name for finding this element.</li>
|
|
<li><span class='property-name'>on_click</span>: Callable executed when arc is clicked.</li>
|
|
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.</li>
|
|
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.</li>
|
|
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) 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 a Vector (same as center).</li>
|
|
<li><span class='property-name'>radius</span>: Arc radius in pixels</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'>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">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'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>
|
|
<p>Caption(pos=None, font=None, text='', **kwargs)
|
|
|
|
A text display UI element with customizable font and styling.
|
|
|
|
Args:
|
|
pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0)
|
|
font (Font, optional): Font object for text rendering. Default: engine default font
|
|
text (str, optional): The text content to display. Default: ''
|
|
|
|
Keyword Args:
|
|
fill_color (Color): Text fill color. Default: (255, 255, 255, 255)
|
|
outline_color (Color): Text outline color. Default: (0, 0, 0, 255)
|
|
outline (float): Text outline thickness. Default: 0
|
|
font_size (float): Font size in points. Default: 16
|
|
click (callable): Click event handler. Default: None
|
|
visible (bool): Visibility state. Default: True
|
|
opacity (float): Opacity (0.0-1.0). Default: 1.0
|
|
z_index (int): Rendering order. Default: 0
|
|
name (str): Element name for finding. Default: None
|
|
x (float): X position override. Default: 0
|
|
y (float): Y position override. Default: 0
|
|
|
|
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</p>
|
|
<h4>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</li>
|
|
<li><span class='property-name'>fill_color</span>: Fill color of the text</li>
|
|
<li><span class='property-name'>font_size</span>: Font size (integer) in points</li>
|
|
<li><span class='property-name'>global_bounds</span>: Bounding rectangle (x, y, width, height) in screen coordinates.</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'>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'>name</span>: Name for finding elements</li>
|
|
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (x, y) coordinates of click.</li>
|
|
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.</li>
|
|
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.</li>
|
|
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) 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'>outline</span>: Thickness of the border</li>
|
|
<li><span class='property-name'>outline_color</span>: Outline color of the text</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'>text</span>: The text displayed</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">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'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="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
|
|
|
|
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>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</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 rectangle (x, y, width, height) in screen coordinates.</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'>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'>name</span>: Name for finding this element.</li>
|
|
<li><span class='property-name'>on_click</span>: Callable executed when circle is clicked.</li>
|
|
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.</li>
|
|
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.</li>
|
|
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) 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'>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'>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">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'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="Color"><span class="class-name">Color</span></h3>
|
|
<p>SFML Color Object</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., '#FF0000', 'FF0000', '#AABBCCDD' 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('#FF0000')</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 '#RRGGBB' or '#RRGGBBAA' (if alpha < 255) Alpha component is only included if not fully opaque (< 255)</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>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>grid_size</span>: Layer dimensions as (width, height) tuple.</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_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">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">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(x, y, color)</code></h5>
|
|
<p>Set the color at cell position (x, y).</p>
|
|
</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's current position.
|
|
Call this after the entity moves to update the visibility layer.</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 (x, y) coordinates of click.</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">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'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="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. Default: 0
|
|
y (float): Y grid position override. Default: 0
|
|
|
|
Attributes:
|
|
pos (tuple): Grid position as (x, y) tuple
|
|
x, y (float): Grid position coordinates
|
|
draw_pos (tuple): Pixel position for rendering
|
|
gridstate (GridPointState): Visibility state for grid points
|
|
sprite_index (int): Current sprite index
|
|
visible (bool): Visibility state
|
|
opacity (float): Opacity value
|
|
name (str): Element name</p>
|
|
<h4>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>draw_pos</span>: Entity position (graphically)</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'>gridstate</span>: Grid point states for the entity</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'>pos</span>: Entity position (integer grid coordinates)</li>
|
|
<li><span class='property-name'>sprite_index</span>: Sprite index on the texture on the display</li>
|
|
<li><span class='property-name'>sprite_number</span>: Sprite index (DEPRECATED: use sprite_index instead)</li>
|
|
<li><span class='property-name'>visible</span>: Visibility flag</li>
|
|
<li><span class='property-name'>x</span>: Entity x position</li>
|
|
<li><span class='property-name'>y</span>: Entity y position</li>
|
|
</ul>
|
|
<h4>Methods:</h4>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">at(...)</code></h5>
|
|
</div>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">die(...)</code></h5>
|
|
<p>Remove this entity from its grid</p>
|
|
</div>
|
|
|
|
<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'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">index(...)</code></h5>
|
|
<p>Return the index of this entity in its grid's entity collection</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">path_to(x: int, y: int) -> bool</code></h5>
|
|
<p>Find and follow path to target position using A* pathfinding.</p>
|
|
<div style='margin-left: 20px;'>
|
|
<div><span class='arg-name'>x</span>: Target X coordinate</div>
|
|
<div><span class='arg-name'>y</span>: Target Y coordinate</div>
|
|
</div>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> True if a path was found and the entity started moving, False otherwise The entity will automatically move along the path over multiple frames. Call this again to change the target or repath.</p>
|
|
</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 style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">update_visibility() -> None</code></h5>
|
|
<p>Update entity's visibility state based on current FOV.
|
|
Recomputes which cells are visible from the entity's position and updates
|
|
the entity's gridstate to track explored areas. 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'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's position and returns all other entities whose positions fall within the visible area.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3 id="EntityCollection"><span class="class-name">EntityCollection</span></h3>
|
|
<p>Iterable, indexable collection of Entities</p>
|
|
<h4>Methods:</h4>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<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(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(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">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">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>
|
|
|
|
<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.
|
|
>>> (10).as_integer_ratio()
|
|
(10, 1)
|
|
>>> (-10).as_integer_ratio()
|
|
(-10, 1)
|
|
>>> (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.
|
|
>>> bin(13)
|
|
'0b1101'
|
|
>>> (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.
|
|
>>> bin(37)
|
|
'0b100101'
|
|
>>> (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 'big',
|
|
the most significant byte is at the beginning of the byte array. If
|
|
byteorder is 'little', the most significant byte is at the end of the
|
|
byte array. To request the native byte order of the host system, use
|
|
sys.byteorder as the byte order value. Default is to use 'big'.
|
|
signed
|
|
Indicates whether two'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 'big',
|
|
the most significant byte is at the beginning of the byte array. If
|
|
byteorder is 'little', the most significant byte is at the end of the
|
|
byte array. To request the native byte order of the host system, use
|
|
sys.byteorder as the byte order value. Default is to use 'big'.
|
|
signed
|
|
Determines whether two'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>SFML Font Object</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
|
|
|
|
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</p>
|
|
<h4>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</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</li>
|
|
<li><span class='property-name'>global_bounds</span>: Bounding rectangle (x, y, width, height) in screen coordinates.</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'>h</span>: height of the rectangle</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'>name</span>: Name for finding elements</li>
|
|
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (x, y) coordinates of click.</li>
|
|
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.</li>
|
|
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.</li>
|
|
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) 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'>outline</span>: Thickness of the border</li>
|
|
<li><span class='property-name'>outline_color</span>: Outline color of the rectangle</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'>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">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'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="Grid"><span class="class-name">Grid</span></h3>
|
|
<p><em>Inherits from: Drawable</em></p>
|
|
<p>Grid(pos=None, size=None, grid_size=None, texture=None, **kwargs)
|
|
|
|
A grid-based UI element for tile-based rendering and entity management.
|
|
|
|
Args:
|
|
pos (tuple, optional): Position as (x, y) tuple. Default: (0, 0)
|
|
size (tuple, optional): Size as (width, height) tuple. Default: auto-calculated from grid_size
|
|
grid_size (tuple, optional): Grid dimensions as (grid_x, grid_y) tuple. Default: (2, 2)
|
|
texture (Texture, optional): Texture containing tile sprites. Default: default texture
|
|
|
|
Keyword Args:
|
|
fill_color (Color): Background fill color. Default: None
|
|
click (callable): Click event handler. Default: None
|
|
center_x (float): X coordinate of center point. Default: 0
|
|
center_y (float): Y coordinate of center point. Default: 0
|
|
zoom (float): Zoom level for rendering. Default: 1.0
|
|
perspective (int): Entity perspective index (-1 for omniscient). Default: -1
|
|
visible (bool): Visibility state. Default: True
|
|
opacity (float): Opacity (0.0-1.0). Default: 1.0
|
|
z_index (int): Rendering order. Default: 0
|
|
name (str): Element name for finding. Default: None
|
|
x (float): X position override. Default: 0
|
|
y (float): Y position override. Default: 0
|
|
w (float): Width override. Default: auto-calculated
|
|
h (float): Height override. Default: auto-calculated
|
|
grid_x (int): Grid width override. Default: 2
|
|
grid_y (int): Grid height override. Default: 2
|
|
|
|
Attributes:
|
|
x, y (float): Position in pixels
|
|
w, h (float): Size in pixels
|
|
pos (Vector): Position as a Vector object
|
|
size (tuple): Size as (width, height) tuple
|
|
center (tuple): Center point as (x, y) tuple
|
|
center_x, center_y (float): Center point coordinates
|
|
zoom (float): Zoom level for rendering
|
|
grid_size (tuple): Grid dimensions (width, height) in tiles
|
|
grid_x, grid_y (int): Grid dimensions
|
|
texture (Texture): Tile texture atlas
|
|
fill_color (Color): Background color
|
|
entities (EntityCollection): Collection of entities in the grid
|
|
perspective (int): Entity perspective index
|
|
click (callable): Click event handler
|
|
visible (bool): Visibility state
|
|
opacity (float): Opacity value
|
|
z_index (int): Rendering order
|
|
name (str): Element name</p>
|
|
<h4>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</li>
|
|
<li><span class='property-name'>center</span>: Grid coordinate at the center of the Grid's view (pan)</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'>children</span>: UICollection of UIDrawable children (speech bubbles, effects, overlays)</li>
|
|
<li><span class='property-name'>entities</span>: EntityCollection of entities on this grid</li>
|
|
<li><span class='property-name'>fill_color</span>: Background fill color of the grid</li>
|
|
<li><span class='property-name'>fov</span>: FOV algorithm for this grid (mcrfpy.FOV enum). Used by entity.updateVisibility() and layer methods when fov=None.</li>
|
|
<li><span class='property-name'>fov_radius</span>: Default FOV radius for this grid. Used when radius not specified.</li>
|
|
<li><span class='property-name'>global_bounds</span>: Bounding rectangle (x, y, width, height) in screen coordinates.</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>: Grid dimensions (grid_x, grid_y)</li>
|
|
<li><span class='property-name'>grid_x</span>: Grid x dimension</li>
|
|
<li><span class='property-name'>grid_y</span>: Grid y dimension</li>
|
|
<li><span class='property-name'>h</span>: visible widget height</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'>hovered_cell</span>: Currently hovered cell as (x, y) tuple, or None if not hovering.</li>
|
|
<li><span class='property-name'>layers</span>: List of grid layers (ColorLayer, TileLayer) sorted by z_index</li>
|
|
<li><span class='property-name'>name</span>: Name for finding elements</li>
|
|
<li><span class='property-name'>on_cell_click</span>: Callback when a grid cell is clicked. Called with (cell_x, cell_y).</li>
|
|
<li><span class='property-name'>on_cell_enter</span>: Callback when mouse enters a grid cell. Called with (cell_x, cell_y).</li>
|
|
<li><span class='property-name'>on_cell_exit</span>: Callback when mouse exits a grid cell. Called with (cell_x, cell_y).</li>
|
|
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (x, y) coordinates of click.</li>
|
|
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.</li>
|
|
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.</li>
|
|
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) 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'>perspective</span>: Entity whose perspective to use for FOV rendering (None for omniscient view). Setting an entity automatically enables perspective mode.</li>
|
|
<li><span class='property-name'>perspective_enabled</span>: Whether to use perspective-based FOV rendering. When True with no valid entity, all cells appear undiscovered.</li>
|
|
<li><span class='property-name'>pos</span>: Position of the grid as Vector</li>
|
|
<li><span class='property-name'>position</span>: Position of the grid (x, y)</li>
|
|
<li><span class='property-name'>size</span>: Size of the grid (width, height)</li>
|
|
<li><span class='property-name'>texture</span>: Texture of the grid</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). Automatically triggers scene resort when changed.</li>
|
|
<li><span class='property-name'>zoom</span>: zoom factor for displaying the Grid</li>
|
|
</ul>
|
|
<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 ('color' or 'tile')</div>
|
|
<div><span class='arg-name'>z_index</span>: Render order. Negative = below entities, >= 0 = above entities. Default: -1</div>
|
|
<div><span class='arg-name'>texture</span>: Texture for tile layers. Required for 'tile' 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>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">compute_astar_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]</code></h5>
|
|
<p>Compute A* path between two points.</p>
|
|
<div style='margin-left: 20px;'>
|
|
<div><span class='arg-name'>x1</span>: Starting X coordinate</div>
|
|
<div><span class='arg-name'>y1</span>: Starting Y coordinate</div>
|
|
<div><span class='arg-name'>x2</span>: Target X coordinate</div>
|
|
<div><span class='arg-name'>y2</span>: Target Y coordinate</div>
|
|
<div><span class='arg-name'>diagonal_cost</span>: Cost of diagonal movement (default: 1.41)</div>
|
|
</div>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of (x, y) tuples representing the path, empty list if no path exists Alternative A* implementation. Prefer find_path() for consistency.</p>
|
|
</div>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">compute_dijkstra(root_x: int, root_y: int, diagonal_cost: float = 1.41) -> None</code></h5>
|
|
<p>Compute Dijkstra map from root position.</p>
|
|
<div style='margin-left: 20px;'>
|
|
<div><span class='arg-name'>root_x</span>: X coordinate of the root/target</div>
|
|
<div><span class='arg-name'>root_y</span>: Y coordinate of the root/target</div>
|
|
<div><span class='arg-name'>diagonal_cost</span>: Cost of diagonal movement (default: 1.41)</div>
|
|
</div>
|
|
</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) -> 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>
|
|
<div><span class='arg-name'>radius</span>: Maximum view distance (0 = unlimited)</div>
|
|
<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>
|
|
</div>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">entities_in_radius(x: float, y: float, radius: float) -> list[Entity]</code></h5>
|
|
<p>Query entities within radius using spatial hash (O(k) where k = nearby entities).</p>
|
|
<div style='margin-left: 20px;'>
|
|
<div><span class='arg-name'>x</span>: Center X coordinate</div>
|
|
<div><span class='arg-name'>y</span>: Center Y coordinate</div>
|
|
<div><span class='arg-name'>radius</span>: Search radius</div>
|
|
</div>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of Entity objects within the radius.</p>
|
|
</div>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">find_path(x1: int, y1: int, x2: int, y2: int, diagonal_cost: float = 1.41) -> List[Tuple[int, int]]</code></h5>
|
|
<p>Find A* path between two points.</p>
|
|
<div style='margin-left: 20px;'>
|
|
<div><span class='arg-name'>x1</span>: Starting X coordinate</div>
|
|
<div><span class='arg-name'>y1</span>: Starting Y coordinate</div>
|
|
<div><span class='arg-name'>x2</span>: Target X coordinate</div>
|
|
<div><span class='arg-name'>y2</span>: Target Y coordinate</div>
|
|
<div><span class='arg-name'>diagonal_cost</span>: Cost of diagonal movement (default: 1.41)</div>
|
|
</div>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of (x, y) tuples representing the path, empty list if no path exists Uses A* algorithm with walkability from grid cells.</p>
|
|
</div>
|
|
|
|
<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'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">get_dijkstra_distance(x: int, y: int) -> Optional[float]</code></h5>
|
|
<p>Get distance from Dijkstra root to position.</p>
|
|
<div style='margin-left: 20px;'>
|
|
<div><span class='arg-name'>x</span>: X coordinate to query</div>
|
|
<div><span class='arg-name'>y</span>: Y coordinate to query</div>
|
|
</div>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> Distance as float, or None if position is unreachable or invalid Must call compute_dijkstra() first.</p>
|
|
</div>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">get_dijkstra_path(x: int, y: int) -> List[Tuple[int, int]]</code></h5>
|
|
<p>Get path from position to Dijkstra root.</p>
|
|
<div style='margin-left: 20px;'>
|
|
<div><span class='arg-name'>x</span>: Starting X coordinate</div>
|
|
<div><span class='arg-name'>y</span>: Starting Y coordinate</div>
|
|
</div>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> List of (x, y) tuples representing path to root, empty if unreachable Must call compute_dijkstra() first. Path includes start but not root position.</p>
|
|
</div>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">is_in_fov(x: int, y: int) -> bool</code></h5>
|
|
<p>Check if a cell is in the field of view.</p>
|
|
<div style='margin-left: 20px;'>
|
|
<div><span class='arg-name'>x</span>: X coordinate to check</div>
|
|
<div><span class='arg-name'>y</span>: Y coordinate to check</div>
|
|
</div>
|
|
<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.
|
|
|
|
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">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.
|
|
|
|
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="GridPoint"><span class="class-name">GridPoint</span></h3>
|
|
<p>UIGridPoint object</p>
|
|
<h4>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>entities</span> (read-only): List of entities at this grid cell (read-only)</li>
|
|
<li><span class='property-name'>transparent</span>: Is the GridPoint transparent</li>
|
|
<li><span class='property-name'>walkable</span>: Is the GridPoint walkable</li>
|
|
</ul>
|
|
<h4>Methods:</h4>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3 id="GridPointState"><span class="class-name">GridPointState</span></h3>
|
|
<p>UIGridPointState object</p>
|
|
<h4>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>discovered</span>: Has the GridPointState been discovered</li>
|
|
<li><span class='property-name'>point</span>: GridPoint at this position (None if not discovered)</li>
|
|
<li><span class='property-name'>visible</span>: Is the GridPointState visible</li>
|
|
</ul>
|
|
<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:
|
|
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
|
|
|
|
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>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</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 rectangle (x, y, width, height) in screen coordinates.</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'>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'>name</span>: Name for finding this element.</li>
|
|
<li><span class='property-name'>on_click</span>: Callable executed when line is clicked.</li>
|
|
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.</li>
|
|
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.</li>
|
|
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) 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 a Vector (midpoint of line).</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'>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">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'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>Scene(name: str)
|
|
|
|
Object-oriented scene management with lifecycle callbacks.
|
|
|
|
This is the recommended approach for scene management, replacing module-level
|
|
functions like createScene(), setScene(), and sceneUI(). Key advantage: you can
|
|
set on_key handlers on ANY scene, not just the currently active one.
|
|
|
|
Args:
|
|
name: Unique identifier for this scene. Used for scene transitions.
|
|
|
|
Properties:
|
|
name (str, read-only): Scene's unique identifier.
|
|
active (bool, read-only): Whether this scene is currently displayed.
|
|
children (UICollection, read-only): UI elements in this scene. Modify to add/remove elements.
|
|
on_key (callable): Keyboard handler. Set on ANY scene, regardless of which is active!
|
|
pos (Vector): Position offset for all UI elements.
|
|
visible (bool): Whether the scene renders.
|
|
opacity (float): Scene transparency (0.0-1.0).
|
|
|
|
Lifecycle Callbacks (override in subclass):
|
|
on_enter(): Called when scene becomes active via activate().
|
|
on_exit(): Called when scene is deactivated (another scene activates).
|
|
on_keypress(key: str, action: str): Called for keyboard events. Alternative to on_key property.
|
|
update(dt: float): Called every frame with delta time in seconds.
|
|
on_resize(width: int, height: int): Called when window is resized.
|
|
|
|
Example:
|
|
# Basic usage (replacing module functions):
|
|
scene = mcrfpy.Scene('main_menu')
|
|
scene.children.append(mcrfpy.Caption(text='Welcome', pos=(100, 100)))
|
|
scene.on_key = lambda key, action: print(f'Key: {key}')
|
|
scene.activate() # Switch to this scene
|
|
|
|
# Subclassing for lifecycle:
|
|
class GameScene(mcrfpy.Scene):
|
|
def on_enter(self):
|
|
print('Game started!')
|
|
def update(self, dt):
|
|
self.player.move(dt)
|
|
</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: str, action: str) 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'>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() -> None</code></h5>
|
|
<p>Make this the active scene.
|
|
|
|
Note:</p>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None Deactivates the current scene and activates this one. Scene transitions and lifecycle callbacks are triggered.</p>
|
|
</div>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">register_keyboard(callback: callable) -> None</code></h5>
|
|
<p>Register a keyboard event handler function.
|
|
|
|
Note:</p>
|
|
<div style='margin-left: 20px;'>
|
|
<div><span class='arg-name'>callback</span>: Function that receives (key: str, pressed: bool) when keyboard events occur</div>
|
|
</div>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None Alternative to setting on_key property. Handler is called for both key press and release events.</p>
|
|
</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
|
|
|
|
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</p>
|
|
<h4>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</li>
|
|
<li><span class='property-name'>global_bounds</span>: Bounding rectangle (x, y, width, height) in screen coordinates.</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'>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'>name</span>: Name for finding elements</li>
|
|
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (x, y) coordinates of click.</li>
|
|
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.</li>
|
|
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.</li>
|
|
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) 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 a Vector</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'>sprite_index</span>: Which sprite on the texture is shown</li>
|
|
<li><span class='property-name'>sprite_number</span>: Sprite index (DEPRECATED: use sprite_index instead)</li>
|
|
<li><span class='property-name'>texture</span>: Texture object</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">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'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="Texture"><span class="class-name">Texture</span></h3>
|
|
<p>SFML Texture Object</p>
|
|
<h4>Properties:</h4>
|
|
<ul>
|
|
<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>
|
|
|
|
<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>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>grid_size</span>: Layer dimensions as (width, height) tuple.</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">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">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(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)
|
|
|
|
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
|
|
|
|
Attributes:
|
|
interval (int): Time between calls in milliseconds
|
|
remaining (int): Time until next call in milliseconds (read-only)
|
|
paused (bool): Whether timer is paused (read-only)
|
|
active (bool): Whether timer is active and not paused (read-only)
|
|
callback (callable): The callback function
|
|
once (bool): Whether timer stops after firing once
|
|
|
|
Methods:
|
|
pause(): Pause the timer, preserving time remaining
|
|
resume(): Resume a paused timer
|
|
cancel(): Stop and remove the timer
|
|
restart(): Reset timer to start from beginning
|
|
|
|
Example:
|
|
def on_timer(timer, runtime):
|
|
print(f'Timer {timer} fired at {runtime}ms')
|
|
if runtime > 5000:
|
|
timer.cancel()
|
|
|
|
timer = mcrfpy.Timer('my_timer', on_timer, 1000)
|
|
timer.pause() # Pause timer
|
|
timer.resume() # Resume timer
|
|
timer.once = True # Make it one-shot</p>
|
|
<h4>Properties:</h4>
|
|
<ul>
|
|
<li><span class='property-name'>active</span> (read-only): Whether the timer is active and not paused (bool, read-only). False if cancelled or paused.</li>
|
|
<li><span class='property-name'>callback</span>: The callback function to be called when timer fires (callable). Can be changed while timer is running.</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). If False, timer repeats indefinitely.</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). Preserved when timer is paused.</li>
|
|
</ul>
|
|
<h4>Methods:</h4>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<h5><code class="method-name">cancel() -> None</code></h5>
|
|
<p>Cancel the timer and remove it from the timer system.
|
|
|
|
Note:</p>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None The timer will no longer fire and cannot be restarted. The callback will not be called again.</p>
|
|
</div>
|
|
|
|
<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.
|
|
|
|
Note:</p>
|
|
<p style='margin-left: 20px;'><span class='returns'>Returns:</span> None Resets the timer to fire after a full interval from now, regardless of remaining time.</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>
|
|
|
|
<div class="method-section">
|
|
<h3 id="UICollection"><span class="class-name">UICollection</span></h3>
|
|
<p>Iterable, indexable collection of UI objects</p>
|
|
<h4>Methods:</h4>
|
|
|
|
<div style="margin-left: 20px; margin-bottom: 15px;">
|
|
<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(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(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">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">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>
|
|
|
|
<div class="method-section">
|
|
<h3 id="UICollectionIter"><span class="class-name">UICollectionIter</span></h3>
|
|
<p>Iterator for a collection of UI objects</p>
|
|
<h4>Methods:</h4>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3 id="UIEntityCollectionIter"><span class="class-name">UIEntityCollectionIter</span></h3>
|
|
<p>Iterator for a collection of UI objects</p>
|
|
<h4>Methods:</h4>
|
|
</div>
|
|
|
|
<div class="method-section">
|
|
<h3 id="Vector"><span class="class-name">Vector</span></h3>
|
|
<p>SFML Vector Object</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="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): 'center' (no scaling), 'stretch' (fill window), or 'fit' (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>
|