john/McRogueFace
1
0
Fork 0
Code Issues 32 Pull requests Projects Releases Wiki Activity

Update documentation for API changes #229, #230, #184

Browse source 
CLAUDE.md updates:
- Fix Python version 3.12 -> 3.14
- Update keypressScene -> scene.on_key pattern
- Add API examples for new callback signatures
- Document animation callbacks (target, prop, value)
- Document hover callbacks (position-only)
- Document enum types (Key, MouseButton, InputState)

stubs/mcrfpy.pyi updates:
- Add Key, MouseButton, InputState, Easing enum classes
- Fix Drawable hover callback signatures per #230
- Fix Grid cell callback signatures per #230
- Fix Scene.on_key signature to use enums per #184
- Update Animation class with correct callback signature per #229
- Add deprecation notes to keypressScene, setTimer, delTimer

Regenerated docs:
- API_REFERENCE_DYNAMIC.md
- api_reference_dynamic.html
- mcrfpy.3 man page

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
John McCardle 2026-01-28 19:20:04 -05:00
commit 5a1948699e
5 changed files with 700 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

38
CLAUDE.md
View file

@ -309,12 +309,12 @@ McRogueFace is a C++ game engine with Python scripting support, designed for cre
### Key Python API (`mcrfpy` module)
The C++ engine exposes these primary functions to Python:
- Scene Management: `Scene("name")` object
- Scene Management: `Scene("name")` object with `scene.on_key` for keyboard events
- Entity Creation: `Entity()` with position and sprite properties
- Grid Management: `Grid()` for tilemap rendering
- Input Handling: `keypressScene()` for keyboard events
- Grid Management: `Grid()` for tilemap rendering with cell callbacks
- Input Handling: `scene.on_key = handler` receives `(Key, InputState)` enums
- Audio: `createSoundBuffer()`, `playSound()`, `setVolume()`
- Timers: `Timer("name")` object for event scheduling
- Timers: `Timer("name", callback, interval)` object for event scheduling
## Development Workflow
@ -322,7 +322,7 @@ The C++ engine exposes these primary functions to Python:
After building, the executable expects:
- `assets/` directory with sprites, fonts, and audio
- `scripts/` directory with Python game files
- Python 3.12 shared libraries in `./lib/`
- Python 3.14 shared libraries in `./lib/`
### Modifying Game Logic
- Game scripts are in `src/scripts/`
@ -591,6 +591,11 @@ demo_scene = mcrfpy.Scene("demo")
# preferred: create animations directly against the targeted object; use Enum of easing functions
frame.animate("x", 500.0, 2.0, mcrfpy.Easing.EASE_IN_OUT)
# Animation callbacks (#229) receive (target, property, final_value):
def on_anim_complete(target, prop, value):
print(f"{type(target).__name__}.{prop} reached {value}")
frame.animate("x", 500.0, 2.0, mcrfpy.Easing.EASE_IN_OUT, callback=on_anim_complete)
# Caption: use keyword arguments to avoid positional conflicts
cap = mcrfpy.Caption(text="Hello", pos=(100, 100))
@ -601,10 +606,27 @@ grid.center = (120, 80) # pixels: (cells * cell_size / 2)
# set grid.center to focus on that position. To position the camera in tile coordinates, use grid.center_camera():
grid.center_camera((14.5, 8.5)) # offset of 0.5 tiles to point at the middle of the tile
# Keyboard handler: key names are "Num1", "Num2", "Escape", "Q", etc.
def on_key(key, state):
if key == "Num1" and state == "start":
# Keyboard handler (#184): receives Key and InputState enums
def on_key(key, action):
if key == mcrfpy.Key.Num1 and action == mcrfpy.InputState.PRESSED:
demo_scene.activate()
scene.on_key = on_key
# Mouse callbacks (#230):
# on_click receives (pos: Vector, button: MouseButton, action: InputState)
def on_click(pos, button, action):
if button == mcrfpy.MouseButton.LEFT and action == mcrfpy.InputState.PRESSED:
print(f"Clicked at {pos.x}, {pos.y}")
frame.on_click = on_click
# Hover callbacks (#230) receive only position:
def on_enter(pos):
print(f"Entered at {pos.x}, {pos.y}")
frame.on_enter = on_enter # Also: on_exit, on_move
# Grid cell callbacks (#230):
# on_cell_click receives (cell_pos: Vector, button: MouseButton, action: InputState)
# on_cell_enter/on_cell_exit receive only (cell_pos: Vector)
```
## Development Best Practices

145
docs/API_REFERENCE_DYNAMIC.md
View file

@ -1,6 +1,6 @@
# McRogueFace API Reference
*Generated on 2026-01-23 20:45:13*
*Generated on 2026-01-28 19:16:58*
*This documentation was dynamically generated from the compiled module.*
@ -13,6 +13,7 @@
- [Animation](#animation)
- [Arc](#arc)
- [BSP](#bsp)
- [CallableBinding](#callablebinding)
- [Caption](#caption)
- [Circle](#circle)
- [Color](#color)
@ -34,7 +35,9 @@
- [MouseButton](#mousebutton)
- [Music](#music)
- [NoiseSource](#noisesource)
- [PropertyBinding](#propertybinding)
- [Scene](#scene)
- [Shader](#shader)
- [Sound](#sound)
- [Sprite](#sprite)
- [Texture](#texture)
@ -508,9 +511,12 @@ Attributes:
- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- `parent`: 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.
- `pos`: Position as a Vector (same as center).
- `radius`: Arc radius in pixels
- `rotate_with_camera`: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
- `rotation`: Rotation angle in degrees (clockwise around origin). Animatable property.
- `start_angle`: Starting angle in degrees
- `thickness`: Line thickness
- `vert_margin`: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
@ -682,6 +688,32 @@ Note:
**Returns:** Iterator yielding BSPNode objects Orders: PRE_ORDER, IN_ORDER, POST_ORDER, LEVEL_ORDER, INVERTED_LEVEL_ORDER
### CallableBinding
CallableBinding(callable: Callable[[], float])
A binding that calls a Python function to get its value.
Args:
callable: A function that takes no arguments and returns a float
The callable is invoked every frame when the shader is rendered.
Keep the callable lightweight to avoid performance issues.
Example:
player_health = 100
frame.uniforms['health_pct'] = mcrfpy.CallableBinding(
lambda: player_health / 100.0
)
**Properties:**
- `callable` *(read-only)*: The Python callable (read-only).
- `is_valid` *(read-only)*: True if the callable is still valid (bool, read-only).
- `value` *(read-only)*: Current value from calling the callable (float, read-only). Returns None on error.
**Methods:**
### Caption
*Inherits from: Drawable*
@ -750,12 +782,17 @@ Attributes:
- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- `outline`: Thickness of the border
- `outline_color`: Outline color of the text. Returns a copy; modifying components requires reassignment. For animation, use 'outline_color.r', 'outline_color.g', etc.
- `parent`: 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.
- `pos`: (x, y) vector
- `rotate_with_camera`: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
- `rotation`: Rotation angle in degrees (clockwise around origin). Animatable property.
- `shader`: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
- `size` *(read-only)*: Text dimensions as Vector (read-only)
- `text`: The text displayed
- `uniforms` *(read-only)*: Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
- `vert_margin`: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `w` *(read-only)*: Text width in pixels (read-only)
@ -873,11 +910,14 @@ Attributes:
- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- `outline`: Outline thickness (0 for no outline)
- `outline_color`: Outline color of the circle
- `parent`: 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.
- `pos`: Position as a Vector (same as center).
- `radius`: Circle radius in pixels
- `rotate_with_camera`: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
- `rotation`: Rotation angle in degrees (clockwise around origin). Animatable property.
- `vert_margin`: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `z_index`: Z-order for rendering (lower values rendered first).
@ -1351,8 +1391,10 @@ Attributes:
- `name`: Name for finding elements
- `opacity`: Opacity (0.0 = transparent, 1.0 = opaque)
- `pos`: Pixel position relative to grid (Vector). Computed as draw_pos * tile_size. Requires entity to be attached to a grid.
- `shader`: Shader for GPU visual effects (Shader or None). When set, the entity is rendered through the shader program. Set to None to disable shader effects.
- `sprite_index`: Sprite index on the texture on the display
- `sprite_number`: Sprite index (DEPRECATED: use sprite_index instead)
- `uniforms` *(read-only)*: Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: entity.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
- `visible`: Visibility flag
- `x`: Pixel X position relative to grid. Requires entity to be attached to a grid.
- `y`: Pixel Y position relative to grid. Requires entity to be attached to a grid.
@ -1605,10 +1647,15 @@ Attributes:
- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- `outline`: Thickness of the border
- `outline_color`: Outline color of the rectangle. Returns a copy; modifying components requires reassignment. For animation, use 'outline_color.r', 'outline_color.g', etc.
- `parent`: 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.
- `pos`: Position as a Vector
- `rotate_with_camera`: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
- `rotation`: Rotation angle in degrees (clockwise around origin). Animatable property.
- `shader`: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
- `uniforms` *(read-only)*: Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
- `vert_margin`: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `w`: width of the rectangle
@ -1729,6 +1776,7 @@ Attributes:
**Properties:**
- `align`: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
- `bounds`: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
- `camera_rotation`: Rotation of grid contents around camera center (degrees). The grid widget stays axis-aligned; only the view into the world rotates.
- `center`: Grid coordinate at the center of the Grid's view (pan)
- `center_x`: center of the view X-coordinate
- `center_y`: center of the view Y-coordinate
@ -1758,13 +1806,18 @@ Attributes:
- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- `parent`: 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.
- `perspective`: Entity whose perspective to use for FOV rendering (None for omniscient view). Setting an entity automatically enables perspective mode.
- `perspective_enabled`: Whether to use perspective-based FOV rendering. When True with no valid entity, all cells appear undiscovered.
- `pos`: Position of the grid as Vector
- `position`: Position of the grid (x, y)
- `rotate_with_camera`: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
- `rotation`: Rotation angle in degrees (clockwise around origin). Animatable property.
- `shader`: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
- `size`: Size of the grid as Vector (width, height)
- `texture`: Texture of the grid
- `uniforms` *(read-only)*: Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
- `vert_margin`: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `w`: visible widget width
@ -2615,8 +2668,11 @@ Attributes:
- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- `parent`: 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.
- `pos`: Position as a Vector (midpoint of line).
- `rotate_with_camera`: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
- `rotation`: Rotation angle in degrees (clockwise around origin). Animatable property.
- `start`: Starting point of the line as a Vector.
- `thickness`: Line thickness in pixels.
- `vert_margin`: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
@ -2900,6 +2956,33 @@ Get turbulence (absolute fbm) value at coordinates.
**Raises:** ValueError: Position tuple length doesn't match dimensions
### PropertyBinding
PropertyBinding(target: UIDrawable, property: str)
A binding that reads a property value from a UI drawable.
Args:
target: The drawable to read the property from
property: Name of the property to read (e.g., 'x', 'opacity')
Use this to create dynamic shader uniforms that follow a drawable's
properties. The binding automatically handles cases where the target
is destroyed.
Example:
other_frame = mcrfpy.Frame(pos=(100, 100))
frame.uniforms['offset_x'] = mcrfpy.PropertyBinding(other_frame, 'x')
**Properties:**
- `is_valid` *(read-only)*: True if the binding target still exists and property is valid (bool, read-only).
- `property` *(read-only)*: The property name being read (str, read-only).
- `target` *(read-only)*: The drawable this binding reads from (read-only).
- `value` *(read-only)*: Current value of the binding (float, read-only). Returns None if invalid.
**Methods:**
### Scene
Scene(name: str)
@ -2948,7 +3031,7 @@ Example:
- `active` *(read-only)*: Whether this scene is currently active (bool, read-only). Only one scene can be active at a time.
- `children` *(read-only)*: UI element collection for this scene (UICollection, read-only). Use to add, remove, or iterate over UI elements. Changes are reflected immediately.
- `name` *(read-only)*: Scene name (str, read-only). Unique identifier for this scene.
- `on_key`: Keyboard event handler (callable or None). Function receives (key: str, action: str) for keyboard events. Set to None to remove the handler.
- `on_key`: Keyboard event handler (callable or None). Function receives (key: Key, action: InputState) for keyboard events. Set to None to remove the handler.
- `opacity`: Scene opacity (0.0-1.0). Applied to all UI elements during rendering.
- `pos`: Scene position offset (Vector). Applied to all UI elements during rendering.
- `visible`: Scene visibility (bool). If False, scene is not rendered.
@ -2974,6 +3057,59 @@ Recalculate alignment for all children with alignment set.
Note:
Call this after window resize or when game_resolution changes. For responsive layouts, connect this to on_resize callback.
### Shader
Shader(fragment_source: str, dynamic: bool = False)
A GPU shader program for visual effects.
Args:
fragment_source: GLSL fragment shader source code
dynamic: If True, shader uses time-varying effects and will
invalidate parent caches each frame
Shaders enable GPU-accelerated visual effects like glow, distortion,
color manipulation, and more. Assign to drawable.shader to apply.
Engine-provided uniforms (automatically available):
- float time: Seconds since engine start
- float delta_time: Seconds since last frame
- vec2 resolution: Texture size in pixels
- vec2 mouse: Mouse position in window coordinates
Example:
shader = mcrfpy.Shader('''
uniform sampler2D texture;
uniform float time;
void main() {
vec2 uv = gl_TexCoord[0].xy;
vec4 color = texture2D(texture, uv);
color.rgb *= 0.5 + 0.5 * sin(time);
gl_FragColor = color;
}
''', dynamic=True)
frame.shader = shader
**Properties:**
- `dynamic`: Whether this shader uses time-varying effects (bool). Dynamic shaders invalidate parent caches each frame.
- `is_valid` *(read-only)*: True if the shader compiled successfully (bool, read-only).
- `source` *(read-only)*: The GLSL fragment shader source code (str, read-only).
**Methods:**
#### `set_uniform(name: str, value: float|tuple) -> None`
Set a custom uniform value on this shader.
Note:
**Arguments:**
- `name`: Uniform variable name in the shader
- `value`: Float, vec2 (2-tuple), vec3 (3-tuple), or vec4 (4-tuple)
**Raises:** ValueError: If uniform type cannot be determined Engine uniforms (time, resolution, etc.) are set automatically
### Sound
Sound effect object for short audio clips
@ -3062,14 +3198,19 @@ Attributes:
- `on_exit`: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `origin`: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- `parent`: 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.
- `pos`: Position as a Vector
- `rotate_with_camera`: Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.
- `rotation`: Rotation angle in degrees (clockwise around origin). Animatable property.
- `scale`: Uniform size factor
- `scale_x`: Horizontal scale factor
- `scale_y`: Vertical scale factor
- `shader`: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
- `sprite_index`: Which sprite on the texture is shown
- `sprite_number`: Sprite index (DEPRECATED: use sprite_index instead)
- `texture`: Texture object
- `uniforms` *(read-only)*: Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
- `vert_margin`: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `x`: X coordinate of top-left corner

148
docs/api_reference_dynamic.html
View file

@ -108,7 +108,7 @@
<body>
<div class="container">
<h1>McRogueFace API Reference</h1>
<p><em>Generated on 2026-01-23 20:45:13</em></p>
<p><em>Generated on 2026-01-28 19:16:58</em></p>
<p><em>This documentation was dynamically generated from the compiled module.</em></p>
<div class="toc">
@ -122,6 +122,7 @@
<li><a href="#Animation">Animation</a></li>
<li><a href="#Arc">Arc</a></li>
<li><a href="#BSP">BSP</a></li>
<li><a href="#CallableBinding">CallableBinding</a></li>
<li><a href="#Caption">Caption</a></li>
<li><a href="#Circle">Circle</a></li>
<li><a href="#Color">Color</a></li>
@ -143,7 +144,9 @@
<li><a href="#MouseButton">MouseButton</a></li>
<li><a href="#Music">Music</a></li>
<li><a href="#NoiseSource">NoiseSource</a></li>
<li><a href="#PropertyBinding">PropertyBinding</a></li>
<li><a href="#Scene">Scene</a></li>
<li><a href="#Shader">Shader</a></li>
<li><a href="#Sound">Sound</a></li>
<li><a href="#Sprite">Sprite</a></li>
<li><a href="#Texture">Texture</a></li>
@ -630,9 +633,12 @@ Attributes:
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
<li><span class='property-name'>pos</span>: Position as a Vector (same as center).</li>
<li><span class='property-name'>radius</span>: Arc radius in pixels</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>start_angle</span>: Starting angle in degrees</li>
<li><span class='property-name'>thickness</span>: Line thickness</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
@ -807,6 +813,33 @@ Note:</p>
</div>
</div>
<div class="method-section">
<h3 id="CallableBinding"><span class="class-name">CallableBinding</span></h3>
<p>CallableBinding(callable: Callable[[], float])
A binding that calls a Python function to get its value.
Args:
callable: A function that takes no arguments and returns a float
The callable is invoked every frame when the shader is rendered.
Keep the callable lightweight to avoid performance issues.
Example:
player_health = 100
frame.uniforms[&#x27;health_pct&#x27;] = mcrfpy.CallableBinding(
lambda: player_health / 100.0
)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>callable</span> (read-only): The Python callable (read-only).</li>
<li><span class='property-name'>is_valid</span> (read-only): True if the callable is still valid (bool, read-only).</li>
<li><span class='property-name'>value</span> (read-only): Current value from calling the callable (float, read-only). Returns None on error.</li>
</ul>
<h4>Methods:</h4>
</div>
<div class="method-section">
<h3 id="Caption"><span class="class-name">Caption</span></h3>
<p><em>Inherits from: Drawable</em></p>
@ -874,12 +907,17 @@ Attributes:
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>outline</span>: Thickness of the border</li>
<li><span class='property-name'>outline_color</span>: Outline color of the text. Returns a copy; modifying components requires reassignment. For animation, use &#x27;outline_color.r&#x27;, &#x27;outline_color.g&#x27;, etc.</li>
<li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
<li><span class='property-name'>pos</span>: (x, y) vector</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>shader</span>: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.</li>
<li><span class='property-name'>size</span> (read-only): Text dimensions as Vector (read-only)</li>
<li><span class='property-name'>text</span>: The text displayed</li>
<li><span class='property-name'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>w</span> (read-only): Text width in pixels (read-only)</li>
@ -999,11 +1037,14 @@ Attributes:
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>outline</span>: Outline thickness (0 for no outline)</li>
<li><span class='property-name'>outline_color</span>: Outline color of the circle</li>
<li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
<li><span class='property-name'>pos</span>: Position as a Vector (same as center).</li>
<li><span class='property-name'>radius</span>: Circle radius in pixels</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first).</li>
@ -1501,8 +1542,10 @@ Attributes:
<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>: Pixel position relative to grid (Vector). Computed as draw_pos * tile_size. Requires entity to be attached to a grid.</li>
<li><span class='property-name'>shader</span>: Shader for GPU visual effects (Shader or None). When set, the entity is rendered through the shader program. Set to None to disable shader effects.</li>
<li><span class='property-name'>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'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: entity.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
<li><span class='property-name'>visible</span>: Visibility flag</li>
<li><span class='property-name'>x</span>: Pixel X position relative to grid. Requires entity to be attached to a grid.</li>
<li><span class='property-name'>y</span>: Pixel Y position relative to grid. Requires entity to be attached to a grid.</li>
@ -1768,10 +1811,15 @@ Attributes:
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>outline</span>: Thickness of the border</li>
<li><span class='property-name'>outline_color</span>: Outline color of the rectangle. Returns a copy; modifying components requires reassignment. For animation, use &#x27;outline_color.r&#x27;, &#x27;outline_color.g&#x27;, etc.</li>
<li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
<li><span class='property-name'>pos</span>: Position as a Vector</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>shader</span>: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.</li>
<li><span class='property-name'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>w</span>: width of the rectangle</li>
@ -1894,6 +1942,7 @@ Attributes:
<ul>
<li><span class='property-name'>align</span>: Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.</li>
<li><span class='property-name'>bounds</span>: Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).</li>
<li><span class='property-name'>camera_rotation</span>: Rotation of grid contents around camera center (degrees). The grid widget stays axis-aligned; only the view into the world rotates.</li>
<li><span class='property-name'>center</span>: Grid coordinate at the center of the Grid&#x27;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>
@ -1923,13 +1972,18 @@ Attributes:
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
<li><span class='property-name'>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'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>shader</span>: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.</li>
<li><span class='property-name'>size</span>: Size of the grid as Vector (width, height)</li>
<li><span class='property-name'>texture</span>: Texture of the grid</li>
<li><span class='property-name'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>w</span>: visible widget width</li>
@ -2798,8 +2852,11 @@ Attributes:
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
<li><span class='property-name'>pos</span>: Position as a Vector (midpoint of line).</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>start</span>: Starting point of the line as a Vector.</li>
<li><span class='property-name'>thickness</span>: Line thickness in pixels.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
@ -3096,6 +3153,34 @@ Note:</p>
</div>
</div>
<div class="method-section">
<h3 id="PropertyBinding"><span class="class-name">PropertyBinding</span></h3>
<p>PropertyBinding(target: UIDrawable, property: str)
A binding that reads a property value from a UI drawable.
Args:
target: The drawable to read the property from
property: Name of the property to read (e.g., &#x27;x&#x27;, &#x27;opacity&#x27;)
Use this to create dynamic shader uniforms that follow a drawable&#x27;s
properties. The binding automatically handles cases where the target
is destroyed.
Example:
other_frame = mcrfpy.Frame(pos=(100, 100))
frame.uniforms[&#x27;offset_x&#x27;] = mcrfpy.PropertyBinding(other_frame, &#x27;x&#x27;)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>is_valid</span> (read-only): True if the binding target still exists and property is valid (bool, read-only).</li>
<li><span class='property-name'>property</span> (read-only): The property name being read (str, read-only).</li>
<li><span class='property-name'>target</span> (read-only): The drawable this binding reads from (read-only).</li>
<li><span class='property-name'>value</span> (read-only): Current value of the binding (float, read-only). Returns None if invalid.</li>
</ul>
<h4>Methods:</h4>
</div>
<div class="method-section">
<h3 id="Scene"><span class="class-name">Scene</span></h3>
<p>Scene(name: str)
@ -3144,7 +3229,7 @@ Example:
<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'>on_key</span>: Keyboard event handler (callable or None). Function receives (key: Key, action: InputState) for keyboard events. Set to None to remove the handler.</li>
<li><span class='property-name'>opacity</span>: Scene opacity (0.0-1.0). Applied to all UI elements during rendering.</li>
<li><span class='property-name'>pos</span>: Scene position offset (Vector). Applied to all UI elements during rendering.</li>
<li><span class='property-name'>visible</span>: Scene visibility (bool). If False, scene is not rendered.</li>
@ -3172,6 +3257,60 @@ Note:
</div>
</div>
<div class="method-section">
<h3 id="Shader"><span class="class-name">Shader</span></h3>
<p>Shader(fragment_source: str, dynamic: bool = False)
A GPU shader program for visual effects.
Args:
fragment_source: GLSL fragment shader source code
dynamic: If True, shader uses time-varying effects and will
invalidate parent caches each frame
Shaders enable GPU-accelerated visual effects like glow, distortion,
color manipulation, and more. Assign to drawable.shader to apply.
Engine-provided uniforms (automatically available):
- float time: Seconds since engine start
- float delta_time: Seconds since last frame
- vec2 resolution: Texture size in pixels
- vec2 mouse: Mouse position in window coordinates
Example:
shader = mcrfpy.Shader(&#x27;&#x27;&#x27;
uniform sampler2D texture;
uniform float time;
void main() {
vec2 uv = gl_TexCoord[0].xy;
vec4 color = texture2D(texture, uv);
color.rgb *= 0.5 + 0.5 * sin(time);
gl_FragColor = color;
}
&#x27;&#x27;&#x27;, dynamic=True)
frame.shader = shader
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>dynamic</span>: Whether this shader uses time-varying effects (bool). Dynamic shaders invalidate parent caches each frame.</li>
<li><span class='property-name'>is_valid</span> (read-only): True if the shader compiled successfully (bool, read-only).</li>
<li><span class='property-name'>source</span> (read-only): The GLSL fragment shader source code (str, read-only).</li>
</ul>
<h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;">
<h5><code class="method-name">set_uniform(name: str, value: float|tuple) -> None</code></h5>
<p>Set a custom uniform value on this shader.
Note:</p>
<div style='margin-left: 20px;'>
<div><span class='arg-name'>name</span>: Uniform variable name in the shader</div>
<div><span class='arg-name'>value</span>: Float, vec2 (2-tuple), vec3 (3-tuple), or vec4 (4-tuple)</div>
</div>
<p style='margin-left: 20px;'><span class='raises'>Raises:</span> ValueError: If uniform type cannot be determined Engine uniforms (time, resolution, etc.) are set automatically</p>
</div>
</div>
<div class="method-section">
<h3 id="Sound"><span class="class-name">Sound</span></h3>
<p>Sound effect object for short audio clips</p>
@ -3263,14 +3402,19 @@ Attributes:
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>origin</span>: Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.</li>
<li><span class='property-name'>parent</span>: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.</li>
<li><span class='property-name'>pos</span>: Position as a Vector</li>
<li><span class='property-name'>rotate_with_camera</span>: Whether to rotate visually with parent Grid&#x27;s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of UIGrid; ignored for other parents.</li>
<li><span class='property-name'>rotation</span>: Rotation angle in degrees (clockwise around origin). Animatable property.</li>
<li><span class='property-name'>scale</span>: Uniform size factor</li>
<li><span class='property-name'>scale_x</span>: Horizontal scale factor</li>
<li><span class='property-name'>scale_y</span>: Vertical scale factor</li>
<li><span class='property-name'>shader</span>: Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.</li>
<li><span class='property-name'>sprite_index</span>: Which sprite on the texture is shown</li>
<li><span class='property-name'>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'>uniforms</span> (read-only): Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms[&#x27;name&#x27;] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.</li>
<li><span class='property-name'>vert_margin</span>: Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>x</span>: X coordinate of top-left corner</li>

279
docs/mcrfpy.3
View file

@ -14,11 +14,11 @@
. ftr VB CB
. ftr VBI CBI
.\}
.TH "MCRFPY" "3" "2026-01-23" "McRogueFace 0.2.1-prerelease-7drl2026-15-g3fea641" ""
.TH "MCRFPY" "3" "2026-01-28" "McRogueFace 0.2.2-prerelease-7drl2026-12-g55f6ea9" ""
.hy
.SH McRogueFace API Reference
.PP
\f[I]Generated on 2026-01-23 20:45:13\f[R]
\f[I]Generated on 2026-01-28 19:16:58\f[R]
.PP
\f[I]This documentation was dynamically generated from the compiled
module.\f[R]
@ -39,6 +39,8 @@ Arc
.IP \[bu] 2
BSP
.IP \[bu] 2
CallableBinding
.IP \[bu] 2
Caption
.IP \[bu] 2
Circle
@ -81,8 +83,12 @@ Music
.IP \[bu] 2
NoiseSource
.IP \[bu] 2
PropertyBinding
.IP \[bu] 2
Scene
.IP \[bu] 2
Shader
.IP \[bu] 2
Sound
.IP \[bu] 2
Sprite
@ -599,14 +605,25 @@ Performance note: Called frequently during movement - keep handlers
fast.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]parent\f[R]: Parent drawable.
Get: Returns the parent Frame/Grid if nested, or None if at scene level.
Set: Assign a Frame/Grid to reparent, or None to remove from parent.
- \f[V]pos\f[R]: Position as a Vector (same as center).
- \f[V]radius\f[R]: Arc radius in pixels - \f[V]start_angle\f[R]:
Starting angle in degrees - \f[V]thickness\f[R]: Line thickness -
\f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use general
margin).
- \f[V]radius\f[R]: Arc radius in pixels - \f[V]rotate_with_camera\f[R]:
Whether to rotate visually with parent Grid\[cq]s camera_rotation
(bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]start_angle\f[R]: Starting angle in degrees -
\f[V]thickness\f[R]: Line thickness - \f[V]vert_margin\f[R]: Vertical
margin override (float, 0 = use general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
@ -789,6 +806,29 @@ Default: LEVEL_ORDER.
.PP
\f[B]Returns:\f[R] Iterator yielding BSPNode objects Orders: PRE_ORDER,
IN_ORDER, POST_ORDER, LEVEL_ORDER, INVERTED_LEVEL_ORDER
.SS CallableBinding
.PP
CallableBinding(callable: Callable[[], float])
.PP
A binding that calls a Python function to get its value.
.PP
Args: callable: A function that takes no arguments and returns a float
.PP
The callable is invoked every frame when the shader is rendered.
Keep the callable lightweight to avoid performance issues.
.PP
Example: player_health = 100 frame.uniforms[`health_pct'] =
mcrfpy.CallableBinding( lambda: player_health / 100.0 )
.PP
\f[B]Properties:\f[R] - \f[V]callable\f[R] \f[I](read-only)\f[R]: The
Python callable (read-only).
- \f[V]is_valid\f[R] \f[I](read-only)\f[R]: True if the callable is
still valid (bool, read-only).
- \f[V]value\f[R] \f[I](read-only)\f[R]: Current value from calling the
callable (float, read-only).
Returns None on error.
.PP
\f[B]Methods:\f[R]
.SS Caption
.PP
\f[I]Inherits from: Drawable\f[R]
@ -878,6 +918,9 @@ Performance note: Called frequently during movement - keep handlers
fast.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]outline\f[R]: Thickness of the border - \f[V]outline_color\f[R]:
Outline color of the text.
Returns a copy; modifying components requires reassignment.
@ -885,10 +928,25 @@ For animation, use `outline_color.r', `outline_color.g', etc.
- \f[V]parent\f[R]: Parent drawable.
Get: Returns the parent Frame/Grid if nested, or None if at scene level.
Set: Assign a Frame/Grid to reparent, or None to remove from parent.
- \f[V]pos\f[R]: (x, y) vector - \f[V]size\f[R] \f[I](read-only)\f[R]:
Text dimensions as Vector (read-only) - \f[V]text\f[R]: The text
displayed - \f[V]vert_margin\f[R]: Vertical margin override (float, 0 =
use general margin).
- \f[V]pos\f[R]: (x, y) vector - \f[V]rotate_with_camera\f[R]: Whether
to rotate visually with parent Grid\[cq]s camera_rotation (bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]shader\f[R]: Shader for GPU visual effects (Shader or None).
When set, the drawable is rendered through the shader program.
Set to None to disable shader effects.
- \f[V]size\f[R] \f[I](read-only)\f[R]: Text dimensions as Vector
(read-only) - \f[V]text\f[R]: The text displayed - \f[V]uniforms\f[R]
\f[I](read-only)\f[R]: Collection of shader uniforms (read-only access
to collection).
Set uniforms via dict-like syntax: drawable.uniforms[`name'] = value.
Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
@ -1023,14 +1081,26 @@ Performance note: Called frequently during movement - keep handlers
fast.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]outline\f[R]: Outline thickness (0 for no outline) -
\f[V]outline_color\f[R]: Outline color of the circle - \f[V]parent\f[R]:
Parent drawable.
Get: Returns the parent Frame/Grid if nested, or None if at scene level.
Set: Assign a Frame/Grid to reparent, or None to remove from parent.
- \f[V]pos\f[R]: Position as a Vector (same as center).
- \f[V]radius\f[R]: Circle radius in pixels - \f[V]vert_margin\f[R]:
Vertical margin override (float, 0 = use general margin).
- \f[V]radius\f[R]: Circle radius in pixels -
\f[V]rotate_with_camera\f[R]: Whether to rotate visually with parent
Grid\[cq]s camera_rotation (bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
@ -1485,10 +1555,17 @@ The logical cell this entity occupies.
relative to grid (Vector).
Computed as draw_pos * tile_size.
Requires entity to be attached to a grid.
- \f[V]shader\f[R]: Shader for GPU visual effects (Shader or None).
When set, the entity is rendered through the shader program.
Set to None to disable shader effects.
- \f[V]sprite_index\f[R]: Sprite index on the texture on the display -
\f[V]sprite_number\f[R]: Sprite index (DEPRECATED: use sprite_index
instead) - \f[V]visible\f[R]: Visibility flag - \f[V]x\f[R]: Pixel X
position relative to grid.
instead) - \f[V]uniforms\f[R] \f[I](read-only)\f[R]: Collection of
shader uniforms (read-only access to collection).
Set uniforms via dict-like syntax: entity.uniforms[`name'] = value.
Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
- \f[V]visible\f[R]: Visibility flag - \f[V]x\f[R]: Pixel X position
relative to grid.
Requires entity to be attached to a grid.
- \f[V]y\f[R]: Pixel Y position relative to grid.
Requires entity to be attached to a grid.
@ -1750,6 +1827,9 @@ Performance note: Called frequently during movement - keep handlers
fast.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]outline\f[R]: Thickness of the border - \f[V]outline_color\f[R]:
Outline color of the rectangle.
Returns a copy; modifying components requires reassignment.
@ -1757,8 +1837,24 @@ For animation, use `outline_color.r', `outline_color.g', etc.
- \f[V]parent\f[R]: Parent drawable.
Get: Returns the parent Frame/Grid if nested, or None if at scene level.
Set: Assign a Frame/Grid to reparent, or None to remove from parent.
- \f[V]pos\f[R]: Position as a Vector - \f[V]vert_margin\f[R]: Vertical
margin override (float, 0 = use general margin).
- \f[V]pos\f[R]: Position as a Vector - \f[V]rotate_with_camera\f[R]:
Whether to rotate visually with parent Grid\[cq]s camera_rotation
(bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]shader\f[R]: Shader for GPU visual effects (Shader or None).
When set, the drawable is rendered through the shader program.
Set to None to disable shader effects.
- \f[V]uniforms\f[R] \f[I](read-only)\f[R]: Collection of shader
uniforms (read-only access to collection).
Set uniforms via dict-like syntax: drawable.uniforms[`name'] = value.
Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
@ -1875,6 +1971,10 @@ or resized.
Set to None to disable alignment and use manual positioning.
- \f[V]bounds\f[R]: Bounding box as (pos, size) tuple of Vectors.
Returns (Vector(x, y), Vector(width, height)).
- \f[V]camera_rotation\f[R]: Rotation of grid contents around camera
center (degrees).
The grid widget stays axis-aligned; only the view into the world
rotates.
- \f[V]center\f[R]: Grid coordinate at the center of the Grid\[cq]s view
(pan) - \f[V]center_x\f[R]: center of the view X-coordinate -
\f[V]center_y\f[R]: center of the view Y-coordinate -
@ -1933,6 +2033,9 @@ Performance note: Called frequently during movement - keep handlers
fast.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]parent\f[R]: Parent drawable.
Get: Returns the parent Frame/Grid if nested, or None if at scene level.
Set: Assign a Frame/Grid to reparent, or None to remove from parent.
@ -1943,10 +2046,25 @@ Setting an entity automatically enables perspective mode.
rendering.
When True with no valid entity, all cells appear undiscovered.
- \f[V]pos\f[R]: Position of the grid as Vector - \f[V]position\f[R]:
Position of the grid (x, y) - \f[V]size\f[R]: Size of the grid as Vector
(width, height) - \f[V]texture\f[R]: Texture of the grid -
\f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use general
margin).
Position of the grid (x, y) - \f[V]rotate_with_camera\f[R]: Whether to
rotate visually with parent Grid\[cq]s camera_rotation (bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]shader\f[R]: Shader for GPU visual effects (Shader or None).
When set, the drawable is rendered through the shader program.
Set to None to disable shader effects.
- \f[V]size\f[R]: Size of the grid as Vector (width, height) -
\f[V]texture\f[R]: Texture of the grid - \f[V]uniforms\f[R]
\f[I](read-only)\f[R]: Collection of shader uniforms (read-only access
to collection).
Set uniforms via dict-like syntax: drawable.uniforms[`name'] = value.
Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).
@ -2743,10 +2861,21 @@ Performance note: Called frequently during movement - keep handlers
fast.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]parent\f[R]: Parent drawable.
Get: Returns the parent Frame/Grid if nested, or None if at scene level.
Set: Assign a Frame/Grid to reparent, or None to remove from parent.
- \f[V]pos\f[R]: Position as a Vector (midpoint of line).
- \f[V]rotate_with_camera\f[R]: Whether to rotate visually with parent
Grid\[cq]s camera_rotation (bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]start\f[R]: Starting point of the line as a Vector.
- \f[V]thickness\f[R]: Line thickness in pixels.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
@ -3041,6 +3170,34 @@ combine (default: 4)
.PP
\f[B]Raises:\f[R] ValueError: Position tuple length doesn\[cq]t match
dimensions
.SS PropertyBinding
.PP
PropertyBinding(target: UIDrawable, property: str)
.PP
A binding that reads a property value from a UI drawable.
.PP
Args: target: The drawable to read the property from property: Name of
the property to read (e.g., `x', `opacity')
.PP
Use this to create dynamic shader uniforms that follow a drawable\[cq]s
properties.
The binding automatically handles cases where the target is destroyed.
.PP
Example: other_frame = mcrfpy.Frame(pos=(100, 100))
frame.uniforms[`offset_x'] = mcrfpy.PropertyBinding(other_frame, `x')
.PP
\f[B]Properties:\f[R] - \f[V]is_valid\f[R] \f[I](read-only)\f[R]: True
if the binding target still exists and property is valid (bool,
read-only).
- \f[V]property\f[R] \f[I](read-only)\f[R]: The property name being read
(str, read-only).
- \f[V]target\f[R] \f[I](read-only)\f[R]: The drawable this binding
reads from (read-only).
- \f[V]value\f[R] \f[I](read-only)\f[R]: Current value of the binding
(float, read-only).
Returns None if invalid.
.PP
\f[B]Methods:\f[R]
.SS Scene
.PP
Scene(name: str)
@ -3100,7 +3257,7 @@ Changes are reflected immediately.
- \f[V]name\f[R] \f[I](read-only)\f[R]: Scene name (str, read-only).
Unique identifier for this scene.
- \f[V]on_key\f[R]: Keyboard event handler (callable or None).
Function receives (key: str, action: str) for keyboard events.
Function receives (key: Key, action: InputState) for keyboard events.
Set to None to remove the handler.
- \f[V]opacity\f[R]: Scene opacity (0.0-1.0).
Applied to all UI elements during rendering.
@ -3131,6 +3288,53 @@ Recalculate alignment for all children with alignment set.
.PP
Note: Call this after window resize or when game_resolution changes.
For responsive layouts, connect this to on_resize callback.
.SS Shader
.PP
Shader(fragment_source: str, dynamic: bool = False)
.PP
A GPU shader program for visual effects.
.PP
Args: fragment_source: GLSL fragment shader source code dynamic: If
True, shader uses time-varying effects and will invalidate parent caches
each frame
.PP
Shaders enable GPU-accelerated visual effects like glow, distortion,
color manipulation, and more.
Assign to drawable.shader to apply.
.PP
Engine-provided uniforms (automatically available): - float time:
Seconds since engine start - float delta_time: Seconds since last frame
- vec2 resolution: Texture size in pixels - vec2 mouse: Mouse position
in window coordinates
.PP
Example: shader = mcrfpy.Shader(\[cq]\[cq]\[cq] uniform sampler2D
texture; uniform float time; void main() { vec2 uv = gl_TexCoord[0].xy;
vec4 color = texture2D(texture, uv); color.rgb \f[I]= 0.5 + 0.5 \f[R]
sin(time); gl_FragColor = color; } \[cq]\[cq]\[cq], dynamic=True)
frame.shader = shader
.PP
\f[B]Properties:\f[R] - \f[V]dynamic\f[R]: Whether this shader uses
time-varying effects (bool).
Dynamic shaders invalidate parent caches each frame.
- \f[V]is_valid\f[R] \f[I](read-only)\f[R]: True if the shader compiled
successfully (bool, read-only).
- \f[V]source\f[R] \f[I](read-only)\f[R]: The GLSL fragment shader
source code (str, read-only).
.PP
\f[B]Methods:\f[R]
.SS \f[V]set_uniform(name: str, value: float|tuple) -> None\f[R]
.PP
Set a custom uniform value on this shader.
.PP
Note:
.PP
\f[B]Arguments:\f[R] - \f[V]name\f[R]: Uniform variable name in the
shader - \f[V]value\f[R]: Float, vec2 (2-tuple), vec3 (3-tuple), or vec4
(4-tuple)
.PP
\f[B]Raises:\f[R] ValueError: If uniform type cannot be determined
Engine uniforms (time, resolution, etc.)
are set automatically
.SS Sound
.PP
Sound effect object for short audio clips
@ -3238,16 +3442,35 @@ Performance note: Called frequently during movement - keep handlers
fast.
- \f[V]opacity\f[R]: Opacity level (0.0 = transparent, 1.0 = opaque).
Automatically clamped to valid range [0.0, 1.0].
- \f[V]origin\f[R]: Transform origin as Vector (pivot point for
rotation).
Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
- \f[V]parent\f[R]: Parent drawable.
Get: Returns the parent Frame/Grid if nested, or None if at scene level.
Set: Assign a Frame/Grid to reparent, or None to remove from parent.
- \f[V]pos\f[R]: Position as a Vector - \f[V]scale\f[R]: Uniform size
factor - \f[V]scale_x\f[R]: Horizontal scale factor - \f[V]scale_y\f[R]:
Vertical scale factor - \f[V]sprite_index\f[R]: Which sprite on the
texture is shown - \f[V]sprite_number\f[R]: Sprite index (DEPRECATED:
use sprite_index instead) - \f[V]texture\f[R]: Texture object -
\f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use general
margin).
- \f[V]pos\f[R]: Position as a Vector - \f[V]rotate_with_camera\f[R]:
Whether to rotate visually with parent Grid\[cq]s camera_rotation
(bool).
False (default): stay screen-aligned.
True: tilt with camera.
Only affects children of UIGrid; ignored for other parents.
- \f[V]rotation\f[R]: Rotation angle in degrees (clockwise around
origin).
Animatable property.
- \f[V]scale\f[R]: Uniform size factor - \f[V]scale_x\f[R]: Horizontal
scale factor - \f[V]scale_y\f[R]: Vertical scale factor -
\f[V]shader\f[R]: Shader for GPU visual effects (Shader or None).
When set, the drawable is rendered through the shader program.
Set to None to disable shader effects.
- \f[V]sprite_index\f[R]: Which sprite on the texture is shown -
\f[V]sprite_number\f[R]: Sprite index (DEPRECATED: use sprite_index
instead) - \f[V]texture\f[R]: Texture object - \f[V]uniforms\f[R]
\f[I](read-only)\f[R]: Collection of shader uniforms (read-only access
to collection).
Set uniforms via dict-like syntax: drawable.uniforms[`name'] = value.
Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
- \f[V]vert_margin\f[R]: Vertical margin override (float, 0 = use
general margin).
Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT,
CENTER).
- \f[V]visible\f[R]: Whether the object is visible (bool).

159
stubs/mcrfpy.pyi
View file

@ -9,6 +9,88 @@ from typing import Any, List, Dict, Tuple, Optional, Callable, Union, overload
UIElement = Union['Frame', 'Caption', 'Sprite', 'Grid', 'Line', 'Circle', 'Arc']
Transition = Union[str, None]
# Enums
class Key:
"""Keyboard key codes enum.
All standard keyboard keys are available as class attributes:
A-Z, Num0-Num9, F1-F15, Arrow keys, modifiers, etc.
"""
A: 'Key'
B: 'Key'
C: 'Key'
# ... (all letters A-Z)
Num0: 'Key'
Num1: 'Key'
Num2: 'Key'
# ... (Num0-Num9)
ESCAPE: 'Key'
ENTER: 'Key'
SPACE: 'Key'
TAB: 'Key'
BACKSPACE: 'Key'
DELETE: 'Key'
UP: 'Key'
DOWN: 'Key'
LEFT: 'Key'
RIGHT: 'Key'
LSHIFT: 'Key'
RSHIFT: 'Key'
LCTRL: 'Key'
RCTRL: 'Key'
LALT: 'Key'
RALT: 'Key'
# ... (additional keys)
class MouseButton:
"""Mouse button enum for click callbacks."""
LEFT: 'MouseButton'
RIGHT: 'MouseButton'
MIDDLE: 'MouseButton'
class InputState:
"""Input action state enum for callbacks."""
PRESSED: 'InputState'
RELEASED: 'InputState'
class Easing:
"""Animation easing function enum.
Available easing functions for smooth animations.
"""
LINEAR: 'Easing'
EASE_IN: 'Easing'
EASE_OUT: 'Easing'
EASE_IN_OUT: 'Easing'
EASE_IN_QUAD: 'Easing'
EASE_OUT_QUAD: 'Easing'
EASE_IN_OUT_QUAD: 'Easing'
EASE_IN_CUBIC: 'Easing'
EASE_OUT_CUBIC: 'Easing'
EASE_IN_OUT_CUBIC: 'Easing'
EASE_IN_QUART: 'Easing'
EASE_OUT_QUART: 'Easing'
EASE_IN_OUT_QUART: 'Easing'
EASE_IN_SINE: 'Easing'
EASE_OUT_SINE: 'Easing'
EASE_IN_OUT_SINE: 'Easing'
EASE_IN_EXPO: 'Easing'
EASE_OUT_EXPO: 'Easing'
EASE_IN_OUT_EXPO: 'Easing'
EASE_IN_CIRC: 'Easing'
EASE_OUT_CIRC: 'Easing'
EASE_IN_OUT_CIRC: 'Easing'
EASE_IN_ELASTIC: 'Easing'
EASE_OUT_ELASTIC: 'Easing'
EASE_IN_OUT_ELASTIC: 'Easing'
EASE_IN_BACK: 'Easing'
EASE_OUT_BACK: 'Easing'
EASE_IN_OUT_BACK: 'Easing'
EASE_IN_BOUNCE: 'Easing'
EASE_OUT_BOUNCE: 'Easing'
EASE_IN_OUT_BOUNCE: 'Easing'
# Classes
class Color:
@ -83,11 +165,13 @@ class Drawable:
name: str
pos: Vector
# Mouse event callbacks (#140, #141)
on_click: Optional[Callable[[float, float, int, str], None]]
on_enter: Optional[Callable[[float, float, int, str], None]]
on_exit: Optional[Callable[[float, float, int, str], None]]
on_move: Optional[Callable[[float, float, int, str], None]]
# Mouse event callbacks (#140, #141, #230)
# on_click receives (pos: Vector, button: MouseButton, action: InputState)
on_click: Optional[Callable[['Vector', 'MouseButton', 'InputState'], None]]
# Hover callbacks receive only position per #230
on_enter: Optional[Callable[['Vector'], None]]
on_exit: Optional[Callable[['Vector'], None]]
on_move: Optional[Callable[['Vector'], None]]
# Read-only hover state (#140)
hovered: bool
@ -222,10 +306,12 @@ class Grid(Drawable):
fov: 'FOV' # FOV algorithm enum
fov_radius: int # Default FOV radius
# Cell-level mouse events
# Cell-level mouse events (#230)
# on_cell_click receives (cell_pos: Vector, button: MouseButton, action: InputState)
on_cell_click: Optional[Callable[['Vector', 'MouseButton', 'InputState'], None]]
# Cell hover callbacks receive only position per #230
on_cell_enter: Optional[Callable[['Vector'], None]]
on_cell_exit: Optional[Callable[['Vector'], None]]
on_cell_click: Optional[Callable[['Vector'], None]]
hovered_cell: Optional[Tuple[int, int]] # Read-only
def at(self, x: int, y: int) -> 'GridPoint':
@ -655,7 +741,8 @@ class Scene:
name: str
children: UICollection # #151: UI elements collection (read-only alias for get_ui())
on_key: Optional[Callable[[str, str], None]] # Keyboard handler (key, action)
# Keyboard handler receives (key: Key, action: InputState) per #184
on_key: Optional[Callable[['Key', 'InputState'], None]]
def __init__(self, name: str) -> None: ...
@ -733,27 +820,31 @@ class Window:
...
class Animation:
"""Animation object for animating UI properties."""
target: Any
"""Animation object for animating UI properties.
Note: The preferred way to create animations is via the .animate() method
on drawable objects:
frame.animate("x", 500.0, 2.0, mcrfpy.Easing.EASE_IN_OUT)
Animation callbacks (#229) receive (target, property, final_value):
def on_complete(target, prop, value):
print(f"{type(target).__name__}.{prop} = {value}")
"""
property: str
duration: float
easing: str
loop: bool
on_complete: Optional[Callable]
def __init__(self, target: Any, property: str, start_value: Any, end_value: Any,
duration: float, easing: str = 'linear', loop: bool = False,
on_complete: Optional[Callable] = None) -> None: ...
def start(self) -> None:
"""Start the animation."""
easing: 'Easing'
# Callback receives (target: Any, property: str, final_value: Any) per #229
callback: Optional[Callable[[Any, str, Any], None]]
def __init__(self, property: str, end_value: Any, duration: float,
easing: Union[str, 'Easing'] = 'linear',
callback: Optional[Callable[[Any, str, Any], None]] = None) -> None: ...
def start(self, target: Any) -> None:
"""Start the animation on a target object."""
...
def update(self, dt: float) -> bool:
"""Update animation, returns True if still running."""
...
def get_current_value(self) -> Any:
"""Get the current interpolated value."""
...
@ -805,15 +896,25 @@ def createScene(name: str) -> None:
...
def keypressScene(handler: Callable[[str, bool], None]) -> None:
"""Set the keyboard event handler for the current scene."""
"""Set the keyboard event handler for the current scene.
DEPRECATED: Use scene.on_key = handler instead.
The new handler receives (key: Key, action: InputState) enums.
"""
...
def setTimer(name: str, handler: Callable[[float], None], interval: int) -> None:
"""Create or update a recurring timer."""
"""Create or update a recurring timer.
DEPRECATED: Use Timer(name, callback, interval) object instead.
"""
...
def delTimer(name: str) -> None:
"""Stop and remove a timer."""
"""Stop and remove a timer.
DEPRECATED: Use timer.cancel() method instead.
"""
...
def exit() -> None: