1773 lines
54 KiB
HTML
1773 lines
54 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, "Helvetica Neue", Arial, sans-serif;
|
|
line-height: 1.6;
|
|
color: #333;
|
|
max-width: 1200px;
|
|
margin: 0 auto;
|
|
padding: 20px;
|
|
background: #f8f9fa;
|
|
}
|
|
|
|
.container {
|
|
background: white;
|
|
padding: 30px;
|
|
border-radius: 8px;
|
|
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
|
|
}
|
|
|
|
h1 {
|
|
color: #2c3e50;
|
|
border-bottom: 3px solid #3498db;
|
|
padding-bottom: 15px;
|
|
margin-bottom: 30px;
|
|
}
|
|
|
|
h2 {
|
|
color: #34495e;
|
|
border-bottom: 2px solid #ecf0f1;
|
|
padding-bottom: 10px;
|
|
margin-top: 40px;
|
|
}
|
|
|
|
h3 {
|
|
color: #2c3e50;
|
|
margin-top: 30px;
|
|
}
|
|
|
|
h4 {
|
|
color: #34495e;
|
|
margin-top: 20px;
|
|
font-size: 1.1em;
|
|
}
|
|
|
|
h5 {
|
|
color: #555;
|
|
margin-top: 15px;
|
|
font-size: 1em;
|
|
}
|
|
|
|
code {
|
|
background: #f4f4f4;
|
|
padding: 2px 6px;
|
|
border-radius: 3px;
|
|
font-family: "SF Mono", Monaco, "Cascadia Code", "Roboto Mono", Consolas, monospace;
|
|
font-size: 0.9em;
|
|
}
|
|
|
|
pre {
|
|
background: #f8f8f8;
|
|
border: 1px solid #e1e4e8;
|
|
border-radius: 6px;
|
|
padding: 16px;
|
|
overflow-x: auto;
|
|
margin: 15px 0;
|
|
}
|
|
|
|
pre code {
|
|
background: none;
|
|
padding: 0;
|
|
font-size: 0.875em;
|
|
line-height: 1.45;
|
|
}
|
|
|
|
.class-name {
|
|
color: #8e44ad;
|
|
font-weight: bold;
|
|
}
|
|
|
|
.property {
|
|
color: #27ae60;
|
|
font-weight: 600;
|
|
}
|
|
|
|
.method {
|
|
color: #2980b9;
|
|
font-weight: 600;
|
|
}
|
|
|
|
.inheritance {
|
|
color: #7f8c8d;
|
|
font-size: 0.9em;
|
|
margin-top: -10px;
|
|
}
|
|
|
|
.toc {
|
|
background: #f8f9fa;
|
|
border: 1px solid #e1e4e8;
|
|
border-radius: 6px;
|
|
padding: 20px;
|
|
margin: 20px 0;
|
|
}
|
|
|
|
.toc h2 {
|
|
margin-top: 0;
|
|
border: none;
|
|
padding: 0;
|
|
}
|
|
|
|
.toc ul {
|
|
list-style: none;
|
|
padding-left: 0;
|
|
}
|
|
|
|
.toc li {
|
|
margin: 8px 0;
|
|
}
|
|
|
|
.toc a {
|
|
color: #3498db;
|
|
text-decoration: none;
|
|
font-weight: 500;
|
|
}
|
|
|
|
.toc a:hover {
|
|
text-decoration: underline;
|
|
}
|
|
|
|
.class-section, .function-section {
|
|
margin: 30px 0;
|
|
padding: 20px;
|
|
background: #fafbfc;
|
|
border-radius: 6px;
|
|
border: 1px solid #e1e4e8;
|
|
}
|
|
|
|
.description {
|
|
margin: 15px 0;
|
|
color: #4a5568;
|
|
}
|
|
|
|
.arguments, .properties, .methods {
|
|
margin: 20px 0;
|
|
}
|
|
|
|
dl {
|
|
margin: 10px 0;
|
|
}
|
|
|
|
dt {
|
|
font-weight: 600;
|
|
margin-top: 10px;
|
|
color: #2c3e50;
|
|
}
|
|
|
|
dd {
|
|
margin-left: 20px;
|
|
margin-bottom: 10px;
|
|
color: #555;
|
|
}
|
|
|
|
.example {
|
|
margin: 20px 0;
|
|
padding: 15px;
|
|
background: #f0f7ff;
|
|
border-left: 4px solid #3498db;
|
|
border-radius: 4px;
|
|
}
|
|
|
|
.example h4 {
|
|
margin-top: 0;
|
|
color: #2980b9;
|
|
}
|
|
|
|
hr {
|
|
border: none;
|
|
border-top: 1px solid #e1e4e8;
|
|
margin: 30px 0;
|
|
}
|
|
|
|
.timestamp {
|
|
color: #7f8c8d;
|
|
font-style: italic;
|
|
font-size: 0.9em;
|
|
}
|
|
|
|
.overview {
|
|
background: #e8f4fd;
|
|
border-left: 4px solid #3498db;
|
|
padding: 20px;
|
|
margin: 20px 0;
|
|
border-radius: 4px;
|
|
}
|
|
|
|
.overview pre {
|
|
background: white;
|
|
border: 1px solid #d6e9f5;
|
|
}
|
|
|
|
strong {
|
|
color: #2c3e50;
|
|
}
|
|
|
|
em {
|
|
color: #555;
|
|
}
|
|
|
|
.automation-section {
|
|
background: #f0f9ff;
|
|
border: 1px solid #b8daff;
|
|
border-radius: 6px;
|
|
padding: 20px;
|
|
margin-top: 30px;
|
|
}
|
|
|
|
.automation-section h2 {
|
|
color: #004085;
|
|
border-bottom: 2px solid #b8daff;
|
|
}
|
|
|
|
.function-signature {
|
|
font-family: "SF Mono", Monaco, monospace;
|
|
font-size: 1.1em;
|
|
color: #d73a49;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="container">
|
|
|
|
<h1>McRogueFace API Reference</h1>
|
|
<p class="timestamp">Generated on 2025-07-08 11:45:09</p>
|
|
<div class="overview">
|
|
<h2>Overview</h2>
|
|
<p>McRogueFace Python API</p>
|
|
<p>Core game engine interface for creating roguelike games with Python.</p>
|
|
<p>This module provides:</p>
|
|
<p>- Scene management (createScene, setScene, currentScene)</p>
|
|
<p>- UI components (Frame, Caption, Sprite, Grid)</p>
|
|
<p>- Entity system for game objects</p>
|
|
<p>- Audio playback (sound effects and music)</p>
|
|
<p>- Timer system for scheduled events</p>
|
|
<p>- Input handling</p>
|
|
<p>- Performance metrics</p>
|
|
<h4>Example:</h4>
|
|
<pre><code class="language-python">
|
|
import mcrfpy
|
|
# Create a new scene
|
|
mcrfpy.createScene('game')
|
|
mcrfpy.setScene('game')
|
|
# Add UI elements
|
|
frame = mcrfpy.Frame(10, 10, 200, 100)
|
|
caption = mcrfpy.Caption('Hello World', 50, 50)
|
|
mcrfpy.sceneUI().extend([frame, caption])
|
|
</code></pre>
|
|
</div>
|
|
<div class="toc">
|
|
<h2>Table of Contents</h2>
|
|
<ul>
|
|
<li><a href="#classes">Classes</a>
|
|
<ul>
|
|
<li><a href="#ui-components">UI Components</a></li>
|
|
<li><a href="#collections">Collections</a></li>
|
|
<li><a href="#system-types">System Types</a></li>
|
|
<li><a href="#other-classes">Other Classes</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#functions">Functions</a>
|
|
<ul>
|
|
<li><a href="#scene-management">Scene Management</a></li>
|
|
<li><a href="#audio">Audio</a></li>
|
|
<li><a href="#ui-utilities">UI Utilities</a></li>
|
|
<li><a href="#system">System</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#automation">Automation Module</a></li>
|
|
</ul>
|
|
</div>
|
|
<h2 id="classes">Classes</h2>
|
|
<h3 id="ui-components">UI Components</h3>
|
|
<div class="class-section" id="class-Frame">
|
|
<h3>class <span class="class-name">Frame</span></h3>
|
|
<p class="inheritance"><em>Inherits from: Drawable</em></p>
|
|
<div class="description">
|
|
<p>A rectangular frame UI element that can contain other drawable elements.<br>
|
|
<br>
|
|
Args:<br>
|
|
x (float): X position in pixels. Default: 0<br>
|
|
y (float): Y position in pixels. Default: 0<br>
|
|
w (float): Width in pixels. Default: 0<br>
|
|
h (float): Height in pixels. Default: 0<br>
|
|
fill_color (Color): Background fill color. Default: (0, 0, 0, 128)<br>
|
|
outline_color (Color): Border outline color. Default: (255, 255, 255, 255)<br>
|
|
outline (float): Border outline thickness. Default: 0<br>
|
|
click (callable): Click event handler. Default: None<br>
|
|
children (list): Initial list of child drawable elements. Default: None<br>
|
|
<br>
|
|
Attributes:<br>
|
|
x, y (float): Position in pixels<br>
|
|
w, h (float): Size in pixels<br>
|
|
fill_color, outline_color (Color): Visual appearance<br>
|
|
outline (float): Border thickness<br>
|
|
click (callable): Click event handler<br>
|
|
children (list): Collection of child drawable elements<br>
|
|
visible (bool): Visibility state<br>
|
|
z_index (int): Rendering order<br>
|
|
clip_children (bool): Whether to clip children to frame bounds<br></p>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">get_bounds()</code></h5>
|
|
<p>Get the bounding rectangle of the frame.</p>
|
|
<p><strong>Returns:</strong> tuple: (x, y, width, height) representing the frame bounds</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">move(dx, dy)</code></h5>
|
|
<p>Move the frame and all its children by a relative offset.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>dx</code> (float): Horizontal offset in pixels</li>
|
|
<li><code>dy</code> (float): Vertical offset in pixels</li>
|
|
</ul>
|
|
<p><strong>Note:</strong> Child elements maintain their relative positions within the frame.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">resize(width, height)</code></h5>
|
|
<p>Resize the frame to new dimensions.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>width</code> (float): New width in pixels</li>
|
|
<li><code>height</code> (float): New height in pixels</li>
|
|
</ul>
|
|
<p><strong>Note:</strong> Does not automatically resize children. Set clip_children=True to clip overflow.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-Caption">
|
|
<h3>class <span class="class-name">Caption</span></h3>
|
|
<p class="inheritance"><em>Inherits from: Drawable</em></p>
|
|
<div class="description">
|
|
<p>A text display UI element with customizable font and styling.<br>
|
|
<br>
|
|
Args:<br>
|
|
text (str): The text content to display. Default: ''<br>
|
|
x (float): X position in pixels. Default: 0<br>
|
|
y (float): Y position in pixels. Default: 0<br>
|
|
font (Font): Font object for text rendering. Default: engine default font<br>
|
|
fill_color (Color): Text fill color. Default: (255, 255, 255, 255)<br>
|
|
outline_color (Color): Text outline color. Default: (0, 0, 0, 255)<br>
|
|
outline (float): Text outline thickness. Default: 0<br>
|
|
click (callable): Click event handler. Default: None<br>
|
|
<br>
|
|
Attributes:<br>
|
|
text (str): The displayed text content<br>
|
|
x, y (float): Position in pixels<br>
|
|
font (Font): Font used for rendering<br>
|
|
fill_color, outline_color (Color): Text appearance<br>
|
|
outline (float): Outline thickness<br>
|
|
click (callable): Click event handler<br>
|
|
visible (bool): Visibility state<br>
|
|
z_index (int): Rendering order<br>
|
|
w, h (float): Read-only computed size based on text and font<br></p>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">get_bounds()</code></h5>
|
|
<p>Get the bounding rectangle of the text.</p>
|
|
<p><strong>Returns:</strong> tuple: (x, y, width, height) based on text content and font size</p>
|
|
<p><strong>Note:</strong> Bounds are automatically calculated from the rendered text dimensions.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">move(dx, dy)</code></h5>
|
|
<p>Move the caption by a relative offset.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>dx</code> (float): Horizontal offset in pixels</li>
|
|
<li><code>dy</code> (float): Vertical offset in pixels</li>
|
|
</ul>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">resize(width, height)</code></h5>
|
|
<p>Set text wrapping bounds (limited support).</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>width</code> (float): Maximum width for text wrapping</li>
|
|
<li><code>height</code> (float): Currently unused</li>
|
|
</ul>
|
|
<p><strong>Note:</strong> Full text wrapping is not yet implemented. This prepares for future multiline support.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-Sprite">
|
|
<h3>class <span class="class-name">Sprite</span></h3>
|
|
<p class="inheritance"><em>Inherits from: Drawable</em></p>
|
|
<div class="description">
|
|
<p>A sprite UI element that displays a texture or portion of a texture atlas.<br>
|
|
<br>
|
|
Args:<br>
|
|
x (float): X position in pixels. Default: 0<br>
|
|
y (float): Y position in pixels. Default: 0<br>
|
|
texture (Texture): Texture object to display. Default: None<br>
|
|
sprite_index (int): Index into texture atlas (if applicable). Default: 0<br>
|
|
scale (float): Sprite scaling factor. Default: 1.0<br>
|
|
click (callable): Click event handler. Default: None<br>
|
|
<br>
|
|
Attributes:<br>
|
|
x, y (float): Position in pixels<br>
|
|
texture (Texture): The texture being displayed<br>
|
|
sprite_index (int): Current sprite index in texture atlas<br>
|
|
scale (float): Scale multiplier<br>
|
|
click (callable): Click event handler<br>
|
|
visible (bool): Visibility state<br>
|
|
z_index (int): Rendering order<br>
|
|
w, h (float): Read-only computed size based on texture and scale<br></p>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">get_bounds()</code></h5>
|
|
<p>Get the bounding rectangle of the sprite.</p>
|
|
<p><strong>Returns:</strong> tuple: (x, y, width, height) based on texture size and scale</p>
|
|
<p><strong>Note:</strong> Bounds account for current scale. Returns (x, y, 0, 0) if no texture.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">move(dx, dy)</code></h5>
|
|
<p>Move the sprite by a relative offset.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>dx</code> (float): Horizontal offset in pixels</li>
|
|
<li><code>dy</code> (float): Vertical offset in pixels</li>
|
|
</ul>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">resize(width, height)</code></h5>
|
|
<p>Resize the sprite by adjusting its scale.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>width</code> (float): Target width in pixels</li>
|
|
<li><code>height</code> (float): Target height in pixels</li>
|
|
</ul>
|
|
<p><strong>Note:</strong> Calculates and applies uniform scale to best fit the target dimensions.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-Grid">
|
|
<h3>class <span class="class-name">Grid</span></h3>
|
|
<p class="inheritance"><em>Inherits from: Drawable</em></p>
|
|
<div class="description">
|
|
<p>A grid-based tilemap UI element for rendering tile-based levels and game worlds.<br>
|
|
<br>
|
|
Args:<br>
|
|
x (float): X position in pixels. Default: 0<br>
|
|
y (float): Y position in pixels. Default: 0<br>
|
|
grid_size (tuple): Grid dimensions as (width, height) in tiles. Default: (20, 20)<br>
|
|
texture (Texture): Texture atlas containing tile sprites. Default: None<br>
|
|
tile_width (int): Width of each tile in pixels. Default: 16<br>
|
|
tile_height (int): Height of each tile in pixels. Default: 16<br>
|
|
scale (float): Grid scaling factor. Default: 1.0<br>
|
|
click (callable): Click event handler. Default: None<br>
|
|
<br>
|
|
Attributes:<br>
|
|
x, y (float): Position in pixels<br>
|
|
grid_size (tuple): Grid dimensions (width, height) in tiles<br>
|
|
tile_width, tile_height (int): Tile dimensions in pixels<br>
|
|
texture (Texture): Tile texture atlas<br>
|
|
scale (float): Scale multiplier<br>
|
|
points (list): 2D array of GridPoint objects for tile data<br>
|
|
entities (list): Collection of Entity objects in the grid<br>
|
|
background_color (Color): Grid background color<br>
|
|
click (callable): Click event handler<br>
|
|
visible (bool): Visibility state<br>
|
|
z_index (int): Rendering order<br></p>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">at(x, y) or at((x, y))</code></h5>
|
|
<p>Get the GridPoint at the specified grid coordinates.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>x</code> (int): Grid x coordinate (0-based)</li>
|
|
<li><code>y</code> (int): Grid y coordinate (0-based)</li>
|
|
</ul>
|
|
<p><strong>Returns:</strong> GridPoint: The grid point at (x, y)</p>
|
|
<p><strong>Note:</strong> Raises IndexError if coordinates are out of range. Accepts either two arguments or a tuple.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">get_bounds()</code></h5>
|
|
<p>Get the bounding rectangle of the entire grid.</p>
|
|
<p><strong>Returns:</strong> tuple: (x, y, width, height) of the grid's display area</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">move(dx, dy)</code></h5>
|
|
<p>Move the grid display by a relative offset.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>dx</code> (float): Horizontal offset in pixels</li>
|
|
<li><code>dy</code> (float): Vertical offset in pixels</li>
|
|
</ul>
|
|
<p><strong>Note:</strong> Moves the entire grid viewport. Use center property to pan within the grid.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">resize(width, height)</code></h5>
|
|
<p>Resize the grid's display viewport.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>width</code> (float): New viewport width in pixels</li>
|
|
<li><code>height</code> (float): New viewport height in pixels</li>
|
|
</ul>
|
|
<p><strong>Note:</strong> Changes the visible area, not the grid dimensions. Use zoom to scale content.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-Entity">
|
|
<h3>class <span class="class-name">Entity</span></h3>
|
|
<div class="constructor">
|
|
<pre><code class="language-python">
|
|
Entity(x=0, y=0, sprite_id=0)
|
|
</code></pre>
|
|
</div>
|
|
<div class="description">
|
|
<p>Game entity that can be placed in a Grid.<br></p>
|
|
</div>
|
|
<div class="arguments">
|
|
<h4>Arguments:</h4>
|
|
<dl>
|
|
<dt><code>x</code> (<em>int</em>)</dt>
|
|
<dd>Grid x coordinate. Default: 0</dd>
|
|
<dt><code>y</code> (<em>int</em>)</dt>
|
|
<dd>Grid y coordinate. Default: 0</dd>
|
|
<dt><code>sprite_id</code> (<em>int</em>)</dt>
|
|
<dd>Sprite index for rendering. Default: 0</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">at(x, y)</code></h5>
|
|
<p>Get the GridPointState at the specified grid coordinates relative to this entity.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>x</code> (int): Grid x offset from entity position</li>
|
|
<li><code>y</code> (int): Grid y offset from entity position</li>
|
|
</ul>
|
|
<p><strong>Returns:</strong> GridPointState: State of the grid point at the specified position</p>
|
|
<p><strong>Note:</strong> Requires entity to be associated with a grid. Raises ValueError if not.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">die()</code></h5>
|
|
<p>Remove this entity from its parent grid.</p>
|
|
<p><strong>Returns:</strong> None</p>
|
|
<p><strong>Note:</strong> The entity object remains valid but is no longer rendered or updated.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">get_bounds()</code></h5>
|
|
<p>Get the bounding rectangle of the entity's sprite.</p>
|
|
<p><strong>Returns:</strong> tuple: (x, y, width, height) of the sprite bounds</p>
|
|
<p><strong>Note:</strong> Delegates to the internal sprite's get_bounds method.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">index()</code></h5>
|
|
<p>Get the index of this entity in its grid's entity collection.</p>
|
|
<p><strong>Returns:</strong> int: Zero-based index in the parent grid's entity list</p>
|
|
<p><strong>Note:</strong> Raises RuntimeError if not associated with a grid, ValueError if not found.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">move(dx, dy)</code></h5>
|
|
<p>Move the entity by a relative offset in pixels.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>dx</code> (float): Horizontal offset in pixels</li>
|
|
<li><code>dy</code> (float): Vertical offset in pixels</li>
|
|
</ul>
|
|
<p><strong>Note:</strong> Updates both sprite position and entity grid position.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">resize(width, height)</code></h5>
|
|
<p>Entities do not support direct resizing.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>width</code> (float): Ignored</li>
|
|
<li><code>height</code> (float): Ignored</li>
|
|
</ul>
|
|
<p><strong>Note:</strong> This method exists for interface compatibility but has no effect.</p>
|
|
</div>
|
|
</div>
|
|
<div class="example">
|
|
<h4>Example:</h4>
|
|
<pre><code class="language-python">
|
|
entity = mcrfpy.Entity(5, 10, 42)
|
|
entity.move(1, 0) # Move right one tile
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<h3 id="collections">Collections</h3>
|
|
<div class="class-section" id="class-EntityCollection">
|
|
<h3>class <span class="class-name">EntityCollection</span></h3>
|
|
<div class="description">
|
|
<p>Container for Entity objects in a Grid. Supports iteration and indexing.<br></p>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">append(entity)</code></h5>
|
|
<p>Add an entity to the end of the collection.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>entity</code> (Entity): The entity to add</li>
|
|
</ul>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">remove(entity)</code></h5>
|
|
<p>Remove the first occurrence of an entity from the collection.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>entity</code> (Entity): The entity to remove</li>
|
|
</ul>
|
|
<p><strong>Note:</strong> Raises ValueError if entity is not found.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">extend(iterable)</code></h5>
|
|
<p>Add multiple entities from an iterable.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>iterable</code> (iterable): An iterable of Entity objects</li>
|
|
</ul>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">count(entity)</code></h5>
|
|
<p>Count occurrences of an entity in the collection.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>entity</code> (Entity): The entity to count</li>
|
|
</ul>
|
|
<p><strong>Returns:</strong> int: Number of times the entity appears</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">index(entity)</code></h5>
|
|
<p>Find the index of the first occurrence of an entity.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>entity</code> (Entity): The entity to find</li>
|
|
</ul>
|
|
<p><strong>Returns:</strong> int: Zero-based index of the entity</p>
|
|
<p><strong>Note:</strong> Raises ValueError if entity is not found.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-UICollection">
|
|
<h3>class <span class="class-name">UICollection</span></h3>
|
|
<div class="description">
|
|
<p>Container for UI drawable elements. Supports iteration and indexing.<br></p>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">append(drawable)</code></h5>
|
|
<p>Add a drawable element to the end of the collection.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>drawable</code> (Drawable): Any UI element (Frame, Caption, Sprite, Grid)</li>
|
|
</ul>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">remove(drawable)</code></h5>
|
|
<p>Remove the first occurrence of a drawable from the collection.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>drawable</code> (Drawable): The drawable to remove</li>
|
|
</ul>
|
|
<p><strong>Note:</strong> Raises ValueError if drawable is not found.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">extend(iterable)</code></h5>
|
|
<p>Add multiple drawables from an iterable.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>iterable</code> (iterable): An iterable of Drawable objects</li>
|
|
</ul>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">count(drawable)</code></h5>
|
|
<p>Count occurrences of a drawable in the collection.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>drawable</code> (Drawable): The drawable to count</li>
|
|
</ul>
|
|
<p><strong>Returns:</strong> int: Number of times the drawable appears</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">index(drawable)</code></h5>
|
|
<p>Find the index of the first occurrence of a drawable.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>drawable</code> (Drawable): The drawable to find</li>
|
|
</ul>
|
|
<p><strong>Returns:</strong> int: Zero-based index of the drawable</p>
|
|
<p><strong>Note:</strong> Raises ValueError if drawable is not found.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-UICollectionIter">
|
|
<h3>class <span class="class-name">UICollectionIter</span></h3>
|
|
<div class="description">
|
|
<p>Iterator for UICollection. Automatically created when iterating over a UICollection.<br></p>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-UIEntityCollectionIter">
|
|
<h3>class <span class="class-name">UIEntityCollectionIter</span></h3>
|
|
<div class="description">
|
|
<p>Iterator for EntityCollection. Automatically created when iterating over an EntityCollection.<br></p>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<h3 id="system-types">System Types</h3>
|
|
<div class="class-section" id="class-Color">
|
|
<h3>class <span class="class-name">Color</span></h3>
|
|
<div class="constructor">
|
|
<pre><code class="language-python">
|
|
Color(r=255, g=255, b=255, a=255)
|
|
</code></pre>
|
|
</div>
|
|
<div class="description">
|
|
<p>RGBA color representation.<br></p>
|
|
</div>
|
|
<div class="arguments">
|
|
<h4>Arguments:</h4>
|
|
<dl>
|
|
<dt><code>r</code> (<em>int</em>)</dt>
|
|
<dd>Red component (0-255). Default: 255</dd>
|
|
<dt><code>g</code> (<em>int</em>)</dt>
|
|
<dd>Green component (0-255). Default: 255</dd>
|
|
<dt><code>b</code> (<em>int</em>)</dt>
|
|
<dd>Blue component (0-255). Default: 255</dd>
|
|
<dt><code>a</code> (<em>int</em>)</dt>
|
|
<dd>Alpha component (0-255). Default: 255</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">from_hex(...)</code></h5>
|
|
<p>Create Color from hex string (e.g., '#FF0000' or 'FF0000')</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">lerp(...)</code></h5>
|
|
<p>Linearly interpolate between this color and another</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">to_hex(...)</code></h5>
|
|
<p>Convert Color to hex string</p>
|
|
</div>
|
|
</div>
|
|
<div class="example">
|
|
<h4>Example:</h4>
|
|
<pre><code class="language-python">
|
|
red = mcrfpy.Color(255, 0, 0)
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-Vector">
|
|
<h3>class <span class="class-name">Vector</span></h3>
|
|
<div class="constructor">
|
|
<pre><code class="language-python">
|
|
Vector(x=0.0, y=0.0)
|
|
</code></pre>
|
|
</div>
|
|
<div class="description">
|
|
<p>2D vector for positions and directions.<br></p>
|
|
</div>
|
|
<div class="arguments">
|
|
<h4>Arguments:</h4>
|
|
<dl>
|
|
<dt><code>x</code> (<em>float</em>)</dt>
|
|
<dd>X component. Default: 0.0</dd>
|
|
<dt><code>y</code> (<em>float</em>)</dt>
|
|
<dd>Y component. Default: 0.0</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">angle(...)</code></h5>
|
|
<p>Return the angle in radians from the positive X axis</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">copy(...)</code></h5>
|
|
<p>Return a copy of this vector</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">distance_to(...)</code></h5>
|
|
<p>Return the distance to another vector</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">dot(...)</code></h5>
|
|
<p>Return the dot product with another vector</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">magnitude(...)</code></h5>
|
|
<p>Return the length of the vector</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">magnitude_squared(...)</code></h5>
|
|
<p>Return the squared length of the vector</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">normalize(...)</code></h5>
|
|
<p>Return a unit vector in the same direction</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-Texture">
|
|
<h3>class <span class="class-name">Texture</span></h3>
|
|
<div class="constructor">
|
|
<pre><code class="language-python">
|
|
Texture(filename)
|
|
</code></pre>
|
|
</div>
|
|
<div class="description">
|
|
<p>Load a texture from file.<br></p>
|
|
</div>
|
|
<div class="arguments">
|
|
<h4>Arguments:</h4>
|
|
<dl>
|
|
<dt><code>filename</code> (<em>str</em>)</dt>
|
|
<dd>Path to image file (PNG/JPG/BMP)</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-Font">
|
|
<h3>class <span class="class-name">Font</span></h3>
|
|
<div class="constructor">
|
|
<pre><code class="language-python">
|
|
Font(filename)
|
|
</code></pre>
|
|
</div>
|
|
<div class="description">
|
|
<p>Load a font from file.<br></p>
|
|
</div>
|
|
<div class="arguments">
|
|
<h4>Arguments:</h4>
|
|
<dl>
|
|
<dt><code>filename</code> (<em>str</em>)</dt>
|
|
<dd>Path to font file (TTF/OTF)</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<h3 id="other-classes">Other Classes</h3>
|
|
<div class="class-section" id="class-Animation">
|
|
<h3>class <span class="class-name">Animation</span></h3>
|
|
<div class="constructor">
|
|
<pre><code class="language-python">
|
|
Animation(property_name, start_value, end_value, duration, transition="linear", loop=False)
|
|
</code></pre>
|
|
</div>
|
|
<div class="description">
|
|
<p>Animate UI element properties over time.<br></p>
|
|
</div>
|
|
<div class="arguments">
|
|
<h4>Arguments:</h4>
|
|
<dl>
|
|
<dt><code>property_name</code> (<em>str</em>)</dt>
|
|
<dd>Property to animate (e.g., "x", "y", "scale")</dd>
|
|
<dt><code>start_value</code> (<em>float</em>)</dt>
|
|
<dd>Starting value</dd>
|
|
<dt><code>end_value</code> (<em>float</em>)</dt>
|
|
<dd>Ending value</dd>
|
|
<dt><code>duration</code> (<em>float</em>)</dt>
|
|
<dd>Duration in seconds</dd>
|
|
<dt><code>transition</code> (<em>str</em>)</dt>
|
|
<dd>Easing function. Default: "linear"</dd>
|
|
<dt><code>loop</code> (<em>bool</em>)</dt>
|
|
<dd>Whether to loop. Default: False</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="properties">
|
|
<h4>Attributes:</h4>
|
|
<dl>
|
|
<dt><code class="property">current_value</code></dt>
|
|
<dd>Property of Animation</dd>
|
|
<dt><code class="property">elapsed_time</code></dt>
|
|
<dd>Property of Animation</dd>
|
|
<dt><code class="property">is_running</code></dt>
|
|
<dd>Property of Animation</dd>
|
|
<dt><code class="property">is_finished</code></dt>
|
|
<dd>Property of Animation</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">get_current_value()</code></h5>
|
|
<p>Get the current interpolated value.</p>
|
|
<p><strong>Returns:</strong> float: Current animation value</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">start(target)</code></h5>
|
|
<p>Start the animation on a target UI element.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>target</code> (UIDrawable): The element to animate</li>
|
|
</ul>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">update(...)</code></h5>
|
|
<p>Update the animation by deltaTime (returns True if still running)</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-Drawable">
|
|
<h3>class <span class="class-name">Drawable</span></h3>
|
|
<div class="description">
|
|
<p>Base class for all drawable UI elements<br></p>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">get_bounds()</code></h5>
|
|
<p>Get the bounding rectangle of this drawable element.</p>
|
|
<p><strong>Returns:</strong> tuple: (x, y, width, height) representing the element's bounds</p>
|
|
<p><strong>Note:</strong> The bounds are in screen coordinates and account for current position and size.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">move(dx, dy)</code></h5>
|
|
<p>Move the element by a relative offset.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>dx</code> (float): Horizontal offset in pixels</li>
|
|
<li><code>dy</code> (float): Vertical offset in pixels</li>
|
|
</ul>
|
|
<p><strong>Note:</strong> This modifies the x and y position properties by the given amounts.</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">resize(width, height)</code></h5>
|
|
<p>Resize the element to new dimensions.</p>
|
|
<p><strong>Arguments:</strong></p>
|
|
<ul>
|
|
<li><code>width</code> (float): New width in pixels</li>
|
|
<li><code>height</code> (float): New height in pixels</li>
|
|
</ul>
|
|
<p><strong>Note:</strong> Behavior varies by element type. Some elements may ignore or constrain dimensions.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-GridPoint">
|
|
<h3>class <span class="class-name">GridPoint</span></h3>
|
|
<div class="description">
|
|
<p>Represents a single tile in a Grid.<br></p>
|
|
</div>
|
|
<div class="properties">
|
|
<h4>Attributes:</h4>
|
|
<dl>
|
|
<dt><code class="property">x</code></dt>
|
|
<dd>Property of GridPoint</dd>
|
|
<dt><code class="property">y</code></dt>
|
|
<dd>Property of GridPoint</dd>
|
|
<dt><code class="property">texture_index</code></dt>
|
|
<dd>Property of GridPoint</dd>
|
|
<dt><code class="property">solid</code></dt>
|
|
<dd>Property of GridPoint</dd>
|
|
<dt><code class="property">transparent</code></dt>
|
|
<dd>Property of GridPoint</dd>
|
|
<dt><code class="property">color</code></dt>
|
|
<dd>Property of GridPoint</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-GridPointState">
|
|
<h3>class <span class="class-name">GridPointState</span></h3>
|
|
<div class="description">
|
|
<p>State information for a GridPoint.<br></p>
|
|
</div>
|
|
<div class="properties">
|
|
<h4>Attributes:</h4>
|
|
<dl>
|
|
<dt><code class="property">visible</code></dt>
|
|
<dd>Property of GridPointState</dd>
|
|
<dt><code class="property">discovered</code></dt>
|
|
<dd>Property of GridPointState</dd>
|
|
<dt><code class="property">custom_flags</code></dt>
|
|
<dd>Property of GridPointState</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-Scene">
|
|
<h3>class <span class="class-name">Scene</span></h3>
|
|
<div class="description">
|
|
<p>Base class for object-oriented scenes<br></p>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">activate(...)</code></h5>
|
|
<p>Make this the active scene</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">get_ui(...)</code></h5>
|
|
<p>Get the UI element collection for this scene</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">register_keyboard(...)</code></h5>
|
|
<p>Register a keyboard handler function (alternative to overriding on_keypress)</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-Timer">
|
|
<h3>class <span class="class-name">Timer</span></h3>
|
|
<div class="constructor">
|
|
<pre><code class="language-python">
|
|
Timer(name, callback, interval_ms)
|
|
</code></pre>
|
|
</div>
|
|
<div class="description">
|
|
<p>Create a recurring timer.<br></p>
|
|
</div>
|
|
<div class="arguments">
|
|
<h4>Arguments:</h4>
|
|
<dl>
|
|
<dt><code>name</code> (<em>str</em>)</dt>
|
|
<dd>Unique timer identifier</dd>
|
|
<dt><code>callback</code> (<em>callable</em>)</dt>
|
|
<dd>Function to call</dd>
|
|
<dt><code>interval_ms</code> (<em>int</em>)</dt>
|
|
<dd>Interval in milliseconds</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">cancel(...)</code></h5>
|
|
<p>Cancel the timer and remove it from the system</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">pause(...)</code></h5>
|
|
<p>Pause the timer</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">restart(...)</code></h5>
|
|
<p>Restart the timer from the current time</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">resume(...)</code></h5>
|
|
<p>Resume a paused timer</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="class-section" id="class-Window">
|
|
<h3>class <span class="class-name">Window</span></h3>
|
|
<div class="description">
|
|
<p>Window singleton for accessing and modifying the game window properties<br></p>
|
|
</div>
|
|
<div class="methods">
|
|
<h4>Methods:</h4>
|
|
<div class="method">
|
|
<h5><code class="method">center(...)</code></h5>
|
|
<p>Center the window on the screen</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">get(...)</code></h5>
|
|
<p>Get the Window singleton instance</p>
|
|
</div>
|
|
<div class="method">
|
|
<h5><code class="method">screenshot(...)</code></h5>
|
|
<p>Take a screenshot. Pass filename to save to file, or get raw bytes if no filename.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<h2 id="functions">Functions</h2>
|
|
<h3 id="scene-management">Scene Management</h3>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">createScene(name: str) -> None</code></h4>
|
|
<p class="description">Create a new empty scene.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>name</code> : <em>str</em></dt>
|
|
<dd>Unique name for the new scene</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>None</p>
|
|
</div>
|
|
<div class="exceptions">
|
|
<h5>Raises:</h5>
|
|
<dl>
|
|
<dt><code>ValueError</code></dt>
|
|
<dd>If a scene with this name already exists</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="note">
|
|
<p><strong>Note:</strong> The scene is created but not made active. Use setScene() to switch to it.</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
mcrfpy.createScene("game")
|
|
mcrfpy.createScene("menu")
|
|
mcrfpy.setScene("game")
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">setScene(scene: str, transition: str = None, duration: float = 0.0) -> None</code></h4>
|
|
<p class="description">Switch to a different scene with optional transition effect.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>scene</code> : <em>str</em></dt>
|
|
<dd>Name of the scene to switch to</dd>
|
|
<dt><code>transition</code> : <em>str</em></dt>
|
|
<dd>Transition type ("fade", "slide_left", "slide_right", "slide_up", "slide_down"). Default: None</dd>
|
|
<dt><code>duration</code> : <em>float</em></dt>
|
|
<dd>Transition duration in seconds. Default: 0.0 for instant</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>None</p>
|
|
</div>
|
|
<div class="exceptions">
|
|
<h5>Raises:</h5>
|
|
<dl>
|
|
<dt><code>KeyError</code></dt>
|
|
<dd>If the scene doesn't exist</dd>
|
|
<dt><code>ValueError</code></dt>
|
|
<dd>If the transition type is invalid</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
mcrfpy.setScene("menu")
|
|
mcrfpy.setScene("game", "fade", 0.5)
|
|
mcrfpy.setScene("credits", "slide_left", 1.0)
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">currentScene() -> str</code></h4>
|
|
<p class="description">Get the name of the currently active scene.</p>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>str: Name of the current scene</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
scene = mcrfpy.currentScene()
|
|
print(f"Currently in scene: {scene}")
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">sceneUI(scene: str = None) -> list</code></h4>
|
|
<p class="description">Get all UI elements for a scene.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>scene</code> : <em>str</em></dt>
|
|
<dd>Scene name. If None, uses current scene. Default: None</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>list: All UI elements (Frame, Caption, Sprite, Grid) in the scene</p>
|
|
</div>
|
|
<div class="exceptions">
|
|
<h5>Raises:</h5>
|
|
<dl>
|
|
<dt><code>KeyError</code></dt>
|
|
<dd>If the specified scene doesn't exist</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
# Get UI for current scene
|
|
ui_elements = mcrfpy.sceneUI()
|
|
|
|
# Get UI for specific scene
|
|
menu_ui = mcrfpy.sceneUI("menu")
|
|
for element in menu_ui:
|
|
print(f"{element.name}: {type(element).__name__}")
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">keypressScene(handler: callable) -> None</code></h4>
|
|
<p class="description">Set the keyboard event handler for the current scene.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>handler</code> : <em>callable</em></dt>
|
|
<dd>Function that receives (key_name: str, is_pressed: bool)</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>None</p>
|
|
</div>
|
|
<div class="note">
|
|
<p><strong>Note:</strong> The handler is called for every key press and release event. Key names are single characters (e.g., "A", "1") or special keys (e.g., "Space", "Enter", "Escape").</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
def on_key(key, pressed):
|
|
if pressed:
|
|
if key == "Space":
|
|
player.jump()
|
|
elif key == "Escape":
|
|
mcrfpy.setScene("pause_menu")
|
|
else:
|
|
# Handle key release
|
|
if key in ["A", "D"]:
|
|
player.stop_moving()
|
|
|
|
mcrfpy.keypressScene(on_key)
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<h3 id="audio">Audio</h3>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">createSoundBuffer(filename: str) -> int</code></h4>
|
|
<p class="description">Load a sound effect from a file and return its buffer ID.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>filename</code> : <em>str</em></dt>
|
|
<dd>Path to the sound file (WAV, OGG, FLAC)</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>int: Buffer ID for use with playSound()</p>
|
|
</div>
|
|
<div class="exceptions">
|
|
<h5>Raises:</h5>
|
|
<dl>
|
|
<dt><code>RuntimeError</code></dt>
|
|
<dd>If the file cannot be loaded</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="note">
|
|
<p><strong>Note:</strong> Sound buffers are stored in memory for fast playback. Load sound effects once and reuse the buffer ID.</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
# Load sound effects
|
|
jump_sound = mcrfpy.createSoundBuffer("assets/sounds/jump.wav")
|
|
coin_sound = mcrfpy.createSoundBuffer("assets/sounds/coin.ogg")
|
|
|
|
# Play later
|
|
mcrfpy.playSound(jump_sound)
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">loadMusic(filename: str, loop: bool = True) -> None</code></h4>
|
|
<p class="description">Load and immediately play background music from a file.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>filename</code> : <em>str</em></dt>
|
|
<dd>Path to the music file (WAV, OGG, FLAC)</dd>
|
|
<dt><code>loop</code> : <em>bool</em></dt>
|
|
<dd>Whether to loop the music. Default: True</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>None</p>
|
|
</div>
|
|
<div class="note">
|
|
<p><strong>Note:</strong> Only one music track can play at a time. Loading new music stops the current track.</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
# Play looping background music
|
|
mcrfpy.loadMusic("assets/music/theme.ogg")
|
|
|
|
# Play music once without looping
|
|
mcrfpy.loadMusic("assets/music/victory.ogg", loop=False)
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">playSound(buffer_id: int) -> None</code></h4>
|
|
<p class="description">Play a sound effect using a previously loaded buffer.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>buffer_id</code> : <em>int</em></dt>
|
|
<dd>Sound buffer ID returned by createSoundBuffer()</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>None</p>
|
|
</div>
|
|
<div class="exceptions">
|
|
<h5>Raises:</h5>
|
|
<dl>
|
|
<dt><code>RuntimeError</code></dt>
|
|
<dd>If the buffer ID is invalid</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="note">
|
|
<p><strong>Note:</strong> Multiple sounds can play simultaneously. Each call creates a new sound instance.</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
# Load once
|
|
explosion_sound = mcrfpy.createSoundBuffer("explosion.wav")
|
|
|
|
# Play multiple times
|
|
for enemy in destroyed_enemies:
|
|
mcrfpy.playSound(explosion_sound)
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">getMusicVolume() -> int</code></h4>
|
|
<p class="description">Get the current music volume level.</p>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>int: Current volume (0-100)</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
volume = mcrfpy.getMusicVolume()
|
|
print(f"Music volume: {volume}%")
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">getSoundVolume() -> int</code></h4>
|
|
<p class="description">Get the current sound effects volume level.</p>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>int: Current volume (0-100)</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
volume = mcrfpy.getSoundVolume()
|
|
print(f"Sound effects volume: {volume}%")
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">setMusicVolume(volume: int) -> None</code></h4>
|
|
<p class="description">Set the global music volume.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>volume</code> : <em>int</em></dt>
|
|
<dd>Volume level from 0 (silent) to 100 (full volume)</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>None</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
# Mute music
|
|
mcrfpy.setMusicVolume(0)
|
|
|
|
# Half volume
|
|
mcrfpy.setMusicVolume(50)
|
|
|
|
# Full volume
|
|
mcrfpy.setMusicVolume(100)
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">setSoundVolume(volume: int) -> None</code></h4>
|
|
<p class="description">Set the global sound effects volume.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>volume</code> : <em>int</em></dt>
|
|
<dd>Volume level from 0 (silent) to 100 (full volume)</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>None</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
# Audio settings from options menu
|
|
mcrfpy.setSoundVolume(sound_slider.value)
|
|
mcrfpy.setMusicVolume(music_slider.value)
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<h3 id="ui-utilities">UI Utilities</h3>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">find(name: str, scene: str = None) -> UIDrawable | None</code></h4>
|
|
<p class="description">Find the first UI element with the specified name.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>name</code> : <em>str</em></dt>
|
|
<dd>Exact name to search for</dd>
|
|
<dt><code>scene</code> : <em>str</em></dt>
|
|
<dd>Scene to search in. Default: current scene</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>Frame, Caption, Sprite, Grid, or Entity if found; None otherwise</p>
|
|
</div>
|
|
<div class="note">
|
|
<p><strong>Note:</strong> Searches scene UI elements and entities within grids. Returns the first match found.</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
# Find in current scene
|
|
player = mcrfpy.find("player")
|
|
if player:
|
|
player.x = 100
|
|
|
|
# Find in specific scene
|
|
menu_button = mcrfpy.find("start_button", "main_menu")
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">findAll(pattern: str, scene: str = None) -> list</code></h4>
|
|
<p class="description">Find all UI elements matching a name pattern.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>pattern</code> : <em>str</em></dt>
|
|
<dd>Name pattern with optional wildcards (* matches any characters)</dd>
|
|
<dt><code>scene</code> : <em>str</em></dt>
|
|
<dd>Scene to search in. Default: current scene</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>list: All matching UI elements and entities</p>
|
|
</div>
|
|
<div class="note">
|
|
<p><strong>Note:</strong> Supports wildcard patterns for flexible searching.</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
# Find all enemies
|
|
enemies = mcrfpy.findAll("enemy*")
|
|
for enemy in enemies:
|
|
enemy.sprite_id = 0 # Reset sprite
|
|
|
|
# Find all buttons
|
|
buttons = mcrfpy.findAll("*_button")
|
|
for btn in buttons:
|
|
btn.visible = True
|
|
|
|
# Find exact matches
|
|
health_bars = mcrfpy.findAll("health_bar") # No wildcards = exact match
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<h3 id="system">System</h3>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">exit() -> None</code></h4>
|
|
<p class="description">Cleanly shut down the game engine and exit the application.</p>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>None</p>
|
|
</div>
|
|
<div class="note">
|
|
<p><strong>Note:</strong> This immediately closes the window and terminates the program. Ensure any necessary cleanup is done before calling.</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
def quit_game():
|
|
# Save game state
|
|
save_progress()
|
|
|
|
# Exit
|
|
mcrfpy.exit()
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">getMetrics() -> dict</code></h4>
|
|
<p class="description">Get current performance metrics.</p>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>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="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
metrics = mcrfpy.getMetrics()
|
|
print(f"FPS: {metrics['fps']}")
|
|
print(f"Frame time: {metrics['frame_time']*1000:.1f}ms")
|
|
print(f"Draw calls: {metrics['draw_calls']}")
|
|
print(f"Runtime: {metrics['runtime']:.1f}s")
|
|
|
|
# Performance monitoring
|
|
if metrics['fps'] < 30:
|
|
print("Performance warning: FPS below 30")
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">setTimer(name: str, handler: callable, interval: int) -> None</code></h4>
|
|
<p class="description">Create or update a recurring timer.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>name</code> : <em>str</em></dt>
|
|
<dd>Unique identifier for the timer</dd>
|
|
<dt><code>handler</code> : <em>callable</em></dt>
|
|
<dd>Function called with (runtime: float) parameter</dd>
|
|
<dt><code>interval</code> : <em>int</em></dt>
|
|
<dd>Time between calls in milliseconds</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>None</p>
|
|
</div>
|
|
<div class="note">
|
|
<p><strong>Note:</strong> 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="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
# Simple repeating timer
|
|
def spawn_enemy(runtime):
|
|
enemy = mcrfpy.Entity()
|
|
enemy.x = random.randint(0, 800)
|
|
grid.entities.append(enemy)
|
|
|
|
mcrfpy.setTimer("enemy_spawner", spawn_enemy, 2000) # Every 2 seconds
|
|
|
|
# Timer with runtime check
|
|
def update_timer(runtime):
|
|
time_left = 60 - runtime
|
|
timer_text.text = f"Time: {int(time_left)}"
|
|
if time_left <= 0:
|
|
mcrfpy.delTimer("game_timer")
|
|
game_over()
|
|
|
|
mcrfpy.setTimer("game_timer", update_timer, 100) # Update every 100ms
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">delTimer(name: str) -> None</code></h4>
|
|
<p class="description">Stop and remove a timer.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>name</code> : <em>str</em></dt>
|
|
<dd>Timer identifier to remove</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>None</p>
|
|
</div>
|
|
<div class="note">
|
|
<p><strong>Note:</strong> No error is raised if the timer doesn't exist.</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
# Stop spawning enemies
|
|
mcrfpy.delTimer("enemy_spawner")
|
|
|
|
# Clean up all game timers
|
|
for timer_name in ["enemy_spawner", "powerup_timer", "score_updater"]:
|
|
mcrfpy.delTimer(timer_name)
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">setScale(multiplier: float) -> None</code></h4>
|
|
<p class="description">Scale the game window size.</p>
|
|
<div class="arguments">
|
|
<h5>Arguments:</h5>
|
|
<dl>
|
|
<dt><code>multiplier</code> : <em>float</em></dt>
|
|
<dd>Scale factor (e.g., 2.0 for double size)</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="returns">
|
|
<h5>Returns:</h5>
|
|
<p>None</p>
|
|
</div>
|
|
<div class="exceptions">
|
|
<h5>Raises:</h5>
|
|
<dl>
|
|
<dt><code>ValueError</code></dt>
|
|
<dd>If multiplier is not between 0.2 and 4.0</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="note">
|
|
<p><strong>Note:</strong> The internal resolution remains 1024x768, but the window is scaled. This is deprecated - use Window.resolution instead.</p>
|
|
</div>
|
|
<div class="example">
|
|
<h5>Example:</h5>
|
|
<pre><code class="language-python">
|
|
# Double the window size
|
|
mcrfpy.setScale(2.0)
|
|
|
|
# Half size window
|
|
mcrfpy.setScale(0.5)
|
|
|
|
# Better approach (not deprecated):
|
|
mcrfpy.Window.resolution = (1920, 1080)
|
|
</code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
<div class="automation-section">
|
|
<h2 id="automation">Automation Module</h2>
|
|
<p>The <code>mcrfpy.automation</code> module provides testing and automation capabilities for simulating user input and capturing screenshots.</p>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.click</code></h4>
|
|
<p>Click at position</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.doubleClick</code></h4>
|
|
<p>Double click at position</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.dragRel</code></h4>
|
|
<p>Drag mouse relative to current position</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.dragTo</code></h4>
|
|
<p>Drag mouse to position</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.hotkey</code></h4>
|
|
<p>Press a hotkey combination (e.g., hotkey('ctrl', 'c'))</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.keyDown</code></h4>
|
|
<p>Press and hold a key</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.keyUp</code></h4>
|
|
<p>Release a key</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.middleClick</code></h4>
|
|
<p>Middle click at position</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.mouseDown</code></h4>
|
|
<p>Press mouse button</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.mouseUp</code></h4>
|
|
<p>Release mouse button</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.moveRel</code></h4>
|
|
<p>Move mouse relative to current position</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.moveTo</code></h4>
|
|
<p>Move mouse to absolute position</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.onScreen</code></h4>
|
|
<p>Check if coordinates are within screen bounds</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.position</code></h4>
|
|
<p>Get current mouse position as (x, y) tuple</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.rightClick</code></h4>
|
|
<p>Right click at position</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.screenshot</code></h4>
|
|
<p>Save a screenshot to the specified file</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.scroll</code></h4>
|
|
<p>Scroll wheel at position</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.size</code></h4>
|
|
<p>Get screen size as (width, height) tuple</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.tripleClick</code></h4>
|
|
<p>Triple click at position</p>
|
|
</div>
|
|
<div class="function-section">
|
|
<h4><code class="function-signature">automation.typewrite</code></h4>
|
|
<p>Type text with optional interval between keystrokes</p>
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
</body>
|
|
</html> |