From 5a1948699ea4148f10f300a8db93fd2ea133b1d1 Mon Sep 17 00:00:00 2001 From: John McCardle Date: Wed, 28 Jan 2026 19:20:04 -0500 Subject: [PATCH] Update documentation for API changes #229, #230, #184 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 --- CLAUDE.md | 38 ++++- docs/API_REFERENCE_DYNAMIC.md | 145 ++++++++++++++++- docs/api_reference_dynamic.html | 148 ++++++++++++++++- docs/mcrfpy.3 | 279 ++++++++++++++++++++++++++++---- stubs/mcrfpy.pyi | 159 ++++++++++++++---- 5 files changed, 700 insertions(+), 69 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ed8e2cf..fae43e6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 diff --git a/docs/API_REFERENCE_DYNAMIC.md b/docs/API_REFERENCE_DYNAMIC.md index 6163c7e..051269b 100644 --- a/docs/API_REFERENCE_DYNAMIC.md +++ b/docs/API_REFERENCE_DYNAMIC.md @@ -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 diff --git a/docs/api_reference_dynamic.html b/docs/api_reference_dynamic.html index d31c10d..ed456f1 100644 --- a/docs/api_reference_dynamic.html +++ b/docs/api_reference_dynamic.html @@ -108,7 +108,7 @@

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.

@@ -122,6 +122,7 @@
  • Animation
  • Arc
  • BSP
    • +
  • CallableBinding
  • Caption
  • Circle
  • Color
    • @@ -143,7 +144,9 @@
  • MouseButton
  • Music
  • NoiseSource
    • +
  • PropertyBinding
  • Scene
    • +
  • Shader
  • Sound
  • Sprite
  • Texture
    • @@ -630,9 +633,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).
    • @@ -807,6 +813,33 @@ Note:

    +
    +

    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

    @@ -874,12 +907,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)
    • @@ -999,11 +1037,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).
    • @@ -1501,8 +1542,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.
    • @@ -1768,10 +1811,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
    • @@ -1894,6 +1942,7 @@ Attributes:
    • 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
      • @@ -1923,13 +1972,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
      • @@ -2798,8 +2852,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).
      • @@ -3096,6 +3153,34 @@ Note:

    +
    +

    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) @@ -3144,7 +3229,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.
    • @@ -3172,6 +3257,60 @@ Note:
    +
    +

    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:

    +
    +
    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

    @@ -3263,14 +3402,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
    • diff --git a/docs/mcrfpy.3 b/docs/mcrfpy.3 index d4601bc..03dd45b 100644 --- a/docs/mcrfpy.3 +++ b/docs/mcrfpy.3 @@ -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). diff --git a/stubs/mcrfpy.pyi b/stubs/mcrfpy.pyi index b9d4b4e..04153b6 100644 --- a/stubs/mcrfpy.pyi +++ b/stubs/mcrfpy.pyi @@ -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: